bill
b758d7ea60
- src/types.hpp: complete UCWM type system in C++20 — 19 enums, 11 facet data types, all core structs (CanonicalObject, Constraint, Facet, GateSignal, WorldState, etc.) with full JSON round-trip serialization - src/main.cpp: smoke test — constructs apple-problem WorldState by hand, serializes to JSON - tests/test_types.cpp: 19 tests, 123 assertions, all passing - CMakeLists.txt: CMake + CPM build with nlohmann/json, spdlog, Catch2 - schemas/: JSON Schema contracts for all UCWM data types - gates/, specialists/, resolver/, synthesis/: language-agnostic interface contracts and domain specs for all pipeline layers - docs/: architecture, vocabulary, decision matrices, roadmap (6 phases, 28 sprints), sprint_001, implementation_constraints Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
124 lines
4.2 KiB
Markdown
124 lines
4.2 KiB
Markdown
# 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
|