ucwm/resolver/contract.md

Resolver Interface Contract

The resolver is the UCWM core. It receives WorldState after specialists have attached their facets and constraints, and it produces a stabilized WorldState ready for synthesis.

---

Design principles

1. Never adds meaning. The resolver does not infer new facts beyond what constraint propagation and arithmetic require. It resolves existing constraints; it does not guess.

2. Contradiction-explicit. When constraints contradict, the resolver records the contradiction in open_contradictions rather than silently discarding either side.

3. Multiple hypotheses. When ambiguity is unresolvable, the resolver maintains multiple hypotheses in WorldState rather than forcing a single resolution.

4. Monotonic confidence. Constraint reinforcement raises confidence. Contradiction lowers confidence. Confidence never increases without supporting evidence.

5. Traceable. Every operation the resolver performs is recorded in resolution_log with the affected refs and the reason.

---

Input

ResolverInput {
  world_state:     WorldState      -- post-specialist state, stage = "post_specialist"
  resolution_mode: string          -- "single_pass" | "iterative" | "conflict_checking"
  max_iterations:  integer?        -- for iterative mode (default: 5)
}

---

Output

ResolverOutput {
  resolved_state:      WorldState       -- stage = "resolved"
  resolution_log:      ResolutionEntry[]
  open_contradictions: ContradictionRecord[]
  confidence_summary:  ConfidenceSummary
}

ResolutionEntry {
  operation:        string        -- see Operations below
  affected_refs:    string[]
  result:           string        -- "resolved" | "contradicted" | "suspended" | "merged" | "split"
  confidence_after: float?
  note:             string?
}

ContradictionRecord {
  constraint_refs:  string[]      -- constraints that contradict each other
  description:      string
  resolution_attempt: string?     -- what the resolver tried before giving up
}

---

Operations

The resolver applies operations in this order:

1. Validate all refs

Before any operation, verify all argument_refs and object_refs resolve to objects in WorldState. Emit warnings for any dangling refs. Do not proceed with a constraint that has dangling refs.

2. Apply hard constraints

Apply all constraints with strength: hard. If two hard constraints contradict, record the contradiction immediately and mark both as contradicted. Do not attempt to resolve hard-vs-hard contradictions silently.

3. Resolve arithmetic

Apply quantity_difference, quantity_sum, quantity_product, quantity_quotient, quantity_equals where all operands are known exact values. Update the result quantity object's QuantityFacet value field.

4. Propagate truth values

Apply truth_value constraints. Propagate via implies chains. If implies(P1, P2) and P1 is true, mark P2 as true. If P1 is false, no propagation (modus tollens requires explicit encoding).

5. Resolve coreference

Apply same_entity constraints. For each pair (A, B) with same_entity(A, B):

• Merge B into A (or A into B, by priority: higher confidence object survives)
• Set the lower-confidence object to status: merged, merged_into: <surviving_id>
• Transfer all facet_refs and constraint_refs to the surviving object

6. Detect contradictions from soft/defeasible constraints

Apply soft and defeasible constraints. When a soft constraint contradicts a hard constraint, suspend the soft constraint. When two soft constraints contradict, mark both with lower confidence and record in open_contradictions.

7. Confidence propagation

For each constraint that was resolved:

• Increase confidence on objects/facets that the constraint reinforces
• Decrease confidence on objects/facets that the constraint contradicts

Confidence deltas must be bounded: a single constraint may not move confidence by more than 0.15 in either direction.

8. Produce resolved WorldState

Update all constraint statuses. Objects with status: proposed that have at least one resolved constraint referencing them may be upgraded to status: active. Mark WorldState stage as resolved.

---

Resolution modes

single_pass: Apply all operations once. Fast, suitable for simple inputs.

iterative: Apply operations repeatedly until no new resolutions occur or max_iterations is reached. Use for inputs with chains of implications.

conflict_checking: Extra pass after resolution: verify that no two hard constraints in resolved status contradict each other. Emit detailed contradiction records if found. Use when input may contain adversarial or self-contradictory statements.

---

Invariants

1. No new objects. The resolver does not propose new objects. It may merge or split existing ones, but may not create new objects from thin air.

2. Idempotent application. Applying a resolved constraint again does not change WorldState.

3. Contradiction is never silent. Every detected contradiction must appear in open_contradictions or in resolution_log with result: contradicted.

4. Log completeness. Every state change must have a corresponding entry in resolution_log.

---

Contract test requirements

• Given worldstate with quantity_difference(Q3, Q1, Q2), Q1.value=5, Q2.value=2: resolver must set Q3.value=3 and mark C3 resolved
• Given same_entity(E1, E3), E1.confidence=0.97, E3.confidence=0.72: E3 must be merged into E1
• Given before(EV1, EV2) and before(EV2, EV1) (cycle): must emit a ContradictionRecord, not silently resolve
• resolution_log must be non-empty after any state change
• All constraints must have updated status after resolver runs