# Synthesis Interface Contract

The synthesis module is the final stage. It reads resolved WorldState and produces a natural language answer plus a derivation trace. The answer must be derivable from resolved constraints — not generated from surface token patterns.

---

## Design principle

Synthesis is translation, not reasoning. All reasoning was done by specialists and the resolver. Synthesis converts the stabilized structured state into human-readable output.

If the answer cannot be derived from resolved constraints, synthesis should say so rather than confabulate.

---

## Input

```
SynthesisInput {
  world_state:     WorldState     -- must have stage = "resolved"
  original_query:  string         -- the user's original input text
  synthesis_mode:  string         -- "direct" | "explain" | "trace"
}
```

**Synthesis modes:**

- `direct`: produce the answer as a natural sentence. Minimal explanation.
- `explain`: produce the answer with a short explanation of how it was derived.
- `trace`: produce the answer plus a full derivation trace listing every constraint and resolver operation used.

---

## Output

```
SynthesisOutput {
  answer:              string
  confidence:          float [0, 1]
  derivation_trace:    string[]     -- ordered list of constraint_ids / operations used
  open_questions:      string[]?    -- aspects the system could not resolve
  synthesis_mode:      string       -- echoes input mode
}
```

---

## Derivation trace

The `derivation_trace` must list, in order:
1. The objects and facts the answer is based on
2. The constraints that were applied
3. The resolver operations that stabilized the relevant values

The trace must be sufficient for a reader to reconstruct the answer without the system.

---

## Invariants

1. **Grounded answer.** Every factual claim in the answer must correspond to a resolved constraint or a confirmed object in WorldState. Synthesis does not add new facts.

2. **Uncertainty acknowledgment.** If a relevant constraint has `status: contradicted` or is in `open_contradictions`, the answer must acknowledge the uncertainty rather than silently pick a side.

3. **Trace completeness.** `derivation_trace` must list all constraints used. If a claim appears in the answer, the constraint supporting it must appear in the trace.

4. **Stage check.** Synthesis must reject WorldState where `stage ≠ "resolved"` with an error, not a guess.

---

## Answer generation patterns

### Simple factual answer

When WorldState contains a single resolved quantity or state that directly answers the query:

```
Template: "{Subject} {verb} {value} {unit}."
Example: "Alice has 3 apples."

Derivation:
  1. E1 (Alice) — active entity
  2. Q_alice_final — quantity, value=3, unit="apples"
  3. C1: owns(Alice, apples, count=5) at t0 — resolved
  4. C2: transfers(Alice, Bob, apples, count=2) at t1 — resolved
  5. C3: quantity_difference(Q_alice_final, Q1, Q2) — resolved, computed 5-2=3
  6. Resolver Op: merge_coreference (she → Alice)
  7. Resolver Op: resolve_arithmetic (Q_alice_final.value = 3)
```

### Uncertain answer

When `open_contradictions` is non-empty or relevant objects are low-confidence:

```
Template: "{Subject} likely {verb} {value}, though {uncertainty description}."
```

### No answer available

When the query asks for something not covered by any resolved constraint:

```
Template: "The available information does not determine {query_topic}."
```

---

## Synthesis does not do

- Infer new facts beyond resolved constraints
- Choose between contradicted constraints without flagging the contradiction
- Generate fluent text that goes beyond what WorldState supports
- Add caveats, hedges, or stylistic embellishments not grounded in confidence values

---

## Contract test requirements

- Given resolved WorldState with Q_alice_final.value=3 and owns constraint resolved: answer must contain "3" and "Alice"
- Given WorldState with `open_contradictions` non-empty: answer must not state a definitive value for the contradicted quantity
- `derivation_trace` must be non-empty for any non-trivial answer
- `stage` check: must raise error given WorldState where stage = "post_specialist"
- All emitted `derivation_trace` entries must reference valid IDs in WorldState