ucwm/synthesis/contract.md

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