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