Sprint 1: project skeleton, type system, and all architecture specs
- 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>
This commit is contained in:
222
docs/architecture.md
Normal file
222
docs/architecture.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# UCWM Architecture — Unified Constraint World Model
|
||||
|
||||
## Core thesis
|
||||
|
||||
Current LLMs mostly do:
|
||||
|
||||
tokens → latent vectors → tokens
|
||||
|
||||
UCWM does:
|
||||
|
||||
tokens → objects → facets → constraints → resolved state → answer
|
||||
|
||||
Language is messy at the surface. Much of reasoning is not inherently messy once input has been decomposed into typed structures. UCWM uses neural perception where input is messy, and structured/deterministic/specialist systems once state has been converted into contract-based representations.
|
||||
|
||||
**Central invariant:** tokens are not meaning. Tokens are *evidence pointers* toward entities, events, concepts, propositions, relations, quantities, and procedures. The architecture moves away from raw tokens as soon as practical.
|
||||
|
||||
---
|
||||
|
||||
## Pipeline overview
|
||||
|
||||
```
|
||||
User input
|
||||
│
|
||||
▼
|
||||
Relation Gate Array ← small recognizers, high-recall, many parallel
|
||||
│
|
||||
▼
|
||||
Perception / Object Proposal ← broad model, emits CanonicalObject proposals
|
||||
│
|
||||
▼
|
||||
Composite Routing Decision ← relay decides which specialists run, on what, with what budget
|
||||
│
|
||||
▼
|
||||
Specialists (parallel/seq) ← each attaches typed Facets + Constraints to objects
|
||||
│
|
||||
▼
|
||||
UCWM Resolver ← merges, detects contradictions, stabilizes world state
|
||||
│
|
||||
▼
|
||||
Synthesis ← produces answer from resolved state, not from token patterns
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component responsibilities
|
||||
|
||||
### 1. Relation Gate Array
|
||||
|
||||
A set of small, independent recognizers that detect which relation families are probably relevant to the input. Gates are the cheapest possible front-end filter.
|
||||
|
||||
**Key property:** high-recall over high-precision. Activating an unnecessary specialist costs budget. Missing a needed one corrupts the answer.
|
||||
|
||||
Gate outputs are `GateSignal` objects (see `schemas/routing.json`). They do not solve anything. They only inform the router.
|
||||
|
||||
Standard gates (not exhaustive):
|
||||
|
||||
| Gate ID | Detects |
|
||||
|---|---|
|
||||
| `is_math` | Numeric reasoning needed |
|
||||
| `is_code` | Code generation or analysis |
|
||||
| `has_temporal_relation` | Before/after/during/recurring |
|
||||
| `has_spatial_relation` | Location, containment, proximity |
|
||||
| `has_causal_relation` | Cause/effect/enabling/blocking |
|
||||
| `has_entity_reference` | Named or implied entities |
|
||||
| `has_coreference` | Pronoun or alias chains |
|
||||
| `has_quantity` | Counts, amounts, measures |
|
||||
| `has_logical_negation` | Not, unless, except |
|
||||
| `has_comparison` | More/less/same/different |
|
||||
| `has_planning` | Steps, goals, prerequisites |
|
||||
| `has_constraint` | Requirements, restrictions |
|
||||
| `has_state_change` | Possession, status transitions |
|
||||
| `has_ownership_transfer` | Give, sell, take, lose |
|
||||
| `has_social_intent` | Belief, desire, obligation, deception |
|
||||
| `requires_external_knowledge` | World facts not in input |
|
||||
| `requires_synthesis_only` | No structure needed, direct answer |
|
||||
|
||||
Gates may be implemented as: regex rules, feature classifiers, small neural nets, or hybrids. The interface contract is identical regardless of implementation.
|
||||
|
||||
---
|
||||
|
||||
### 2. Router / Relay (RSA)
|
||||
|
||||
The relay (Relay Specialist Architecture) consumes gate outputs and initial extraction signals, then emits a `RoutingDecision` (see `schemas/routing.json`).
|
||||
|
||||
A `RoutingDecision` activates multiple specialists for the same target simultaneously. The relay is a *dispatcher*, not a solver. RSA is the routing mechanism; UCWM is the constraint-based reasoning substrate.
|
||||
|
||||
Relay responsibilities:
|
||||
- Which specialists should run
|
||||
- Which objects or spans they should inspect
|
||||
- Budget per specialist
|
||||
- Execution mode (parallel, sequential, iterative, conflict-checking)
|
||||
- Priority order for constraint merging
|
||||
|
||||
---
|
||||
|
||||
### 3. Canonical Object Layer
|
||||
|
||||
A `CanonicalObject` (see `schemas/objects.json`) is the primary reusable referent inside UCWM.
|
||||
|
||||
Objects are stable anchors. They are not overloaded with every possible field. Typed descriptions attach to objects via Facets.
|
||||
|
||||
Object kinds: `entity`, `event`, `concept`, `proposition`, `relation_instance`, `procedure_step`, `code_object`, `quantity`, `claim`, `state`
|
||||
|
||||
---
|
||||
|
||||
### 4. Facet Bundles
|
||||
|
||||
A single object can carry multiple typed descriptions simultaneously. This is a `FacetBundle`.
|
||||
|
||||
Facets are optional and additive. Not every object exists in time or space. A physical entity may have temporal and spatial facets. An abstract concept may not. A proposition may have logical facets but no spatial facet.
|
||||
|
||||
Facet kinds: `temporal`, `spatial`, `causal`, `logical`, `syntactic`, `semantic`, `social`, `ownership`, `code_structure`, `quantity`, `planning`
|
||||
|
||||
See `schemas/facets.json` for schemas of each type.
|
||||
|
||||
---
|
||||
|
||||
### 5. Schema Plurality
|
||||
|
||||
The same underlying thing may be describable by multiple schemas simultaneously. An event could simultaneously be:
|
||||
- A predicate-argument structure
|
||||
- A temporal interval
|
||||
- A causal node
|
||||
- A state transition
|
||||
- A social action
|
||||
|
||||
UCWM does not force one schema too early. Multiple specialists attach schema-shaped facets to the same canonical object. The resolver reconciles them.
|
||||
|
||||
---
|
||||
|
||||
### 6. Constraint System
|
||||
|
||||
Constraints are the core reasoning currency (see `schemas/constraints.json`).
|
||||
|
||||
A constraint is an explicit relation, restriction, incompatibility, requirement, or preference involving objects and/or facets.
|
||||
|
||||
Strength levels: `hard`, `soft`, `probabilistic`, `defeasible`
|
||||
|
||||
Status lifecycle: `unresolved` → `resolved` | `contradicted` | `suspended`
|
||||
|
||||
Examples:
|
||||
```
|
||||
before(E1, E2)
|
||||
causes(E1, E3)
|
||||
same_entity(O4, O9)
|
||||
quantity(Q1) = quantity(Q2) - 3
|
||||
truth(P1) = false
|
||||
inside(O1, O2)
|
||||
owner(O3) = Entity_Alice
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. UCWM Resolver
|
||||
|
||||
The resolver maintains `WorldState` and stabilizes it by:
|
||||
- Combining constraints from multiple specialists
|
||||
- Detecting contradictions
|
||||
- Reinforcing agreements
|
||||
- Maintaining multiple hypotheses when ambiguous
|
||||
- Resolving object merges and splits
|
||||
- Reducing uncertainty to a stabilized state for synthesis
|
||||
|
||||
See `resolver/contract.md` and `resolver/operations.md`.
|
||||
|
||||
---
|
||||
|
||||
### 8. Specialists
|
||||
|
||||
Specialists are contract-bound modules that attach `Facet` and `Constraint` objects to `CanonicalObject` refs. They may be neural, statistical, symbolic, deterministic, graph-based, or hybrid.
|
||||
|
||||
**Key rule:** specialists emit bounded structured outputs, not unconstrained free text.
|
||||
|
||||
See `specialists/contract.md` for the interface and individual specialist files for domain logic.
|
||||
|
||||
---
|
||||
|
||||
## Contractual layers and testability
|
||||
|
||||
Every layer has a typed boundary that can be independently tested:
|
||||
|
||||
| Layer | Input | Output |
|
||||
|---|---|---|
|
||||
| Gate | text span | `GateSignal[]` |
|
||||
| Object proposal | text + gate signals | `CanonicalObject[]` |
|
||||
| Routing | objects + gate signals | `RoutingDecision` |
|
||||
| Specialist | object refs + routing context | `Facet[]` + `Constraint[]` |
|
||||
| Resolver | `WorldState` | resolved `WorldState` |
|
||||
| Synthesis | resolved state + query | answer + derivation trace |
|
||||
|
||||
This enables unit tests, regression tests, swappable implementations, local debugging, and failure localization — advantages not available with monolithic LLMs.
|
||||
|
||||
---
|
||||
|
||||
## Compute strategy
|
||||
|
||||
Target profile:
|
||||
- One ~1B perception/routing/object-proposal model
|
||||
- Many 10M–50M specialist models
|
||||
- Deterministic solvers where state is already structured
|
||||
- Structured state instead of long token chains
|
||||
- Bounded outputs rather than free-form generation
|
||||
|
||||
Goal: comparable usefulness to large dense models via decomposition, sparse activation, explicit structure, and constraint resolution — not by scaling a single model.
|
||||
|
||||
---
|
||||
|
||||
## First vertical slice target
|
||||
|
||||
Prove the pipeline on a narrow domain before expanding.
|
||||
|
||||
Candidate domains:
|
||||
- Math word problems
|
||||
- Temporal + entity tracking
|
||||
- State-change / ownership reasoning
|
||||
- Code generation with AST constraints
|
||||
|
||||
Success criteria for first prototype:
|
||||
1. Structured intermediate state is produced and inspectable
|
||||
2. Answer is derivable from resolved constraints, not from surface patterns
|
||||
3. Each layer has at least one passing contract test
|
||||
4. A failure in one layer is localizable without inspecting other layers
|
||||
165
docs/decision_matrices.md
Normal file
165
docs/decision_matrices.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# UCWM Decision Matrices
|
||||
|
||||
Use this format for every major architecture fork. A decision that is too complex to settle in a sentence deserves a matrix.
|
||||
|
||||
---
|
||||
|
||||
## Matrix format
|
||||
|
||||
**Rows** = options under consideration
|
||||
**Columns** = evaluation factors
|
||||
**Each row also includes** a structured summary block
|
||||
|
||||
### Standard columns
|
||||
|
||||
| Column | What it measures |
|
||||
|---|---|
|
||||
| `compute_efficiency` | Ops and memory per inference pass |
|
||||
| `memory_efficiency` | State size and cache pressure |
|
||||
| `latency_cost` | Wall-clock time sensitivity |
|
||||
| `implementation_complexity` | Engineering effort to build correctly |
|
||||
| `training_complexity` | Data, infra, and iteration cost |
|
||||
| `scaling_behavior` | How quality changes with more data/compute |
|
||||
| `mechanistic_interpretability` | Can you understand what the model is doing internally? |
|
||||
| `state_inspectability` | Can intermediate state be read and debugged? |
|
||||
| `constraint_explicitness` | Are constraints visible as typed objects? |
|
||||
| `failure_localizability` | Can a failure be traced to a specific module? |
|
||||
| `update_localizability` | Can a fix be applied without retraining everything? |
|
||||
| `swappability` | Can this component be replaced without cascading changes? |
|
||||
| `extensibility` | How hard is it to add new capability? |
|
||||
| `backward_compatibility` | Does a change break existing contracts? |
|
||||
| `migration_cost` | Cost to shift if this option turns out wrong |
|
||||
| `reasoning_power` | Quality of structured reasoning output |
|
||||
| `generalization_potential` | Expected performance outside training distribution |
|
||||
| `precision` | False positive rate on structured outputs |
|
||||
| `robustness` | Graceful degradation under noisy/adversarial input |
|
||||
| `cognitive_load` | Mental overhead for a solo builder to hold this in mind |
|
||||
| `solo_builder_feasibility` | Can one person build and maintain this? |
|
||||
| `prototype_speed` | Time from decision to working test |
|
||||
| `dependency_risk` | Risk from external libraries, APIs, models |
|
||||
|
||||
Rating scale: `low` / `med` / `high` or numeric where useful. Unknown cells should say `?` not be left blank.
|
||||
|
||||
### Per-row summary block
|
||||
|
||||
```
|
||||
key_benefit: One sentence on the strongest argument for this option
|
||||
key_risk: One sentence on the most likely failure mode
|
||||
unknowns: What you don't know yet that would change this rating
|
||||
what_it_unlocks: What becomes possible if this works
|
||||
what_it_blocks: What becomes harder or impossible if you choose this
|
||||
reversibility: easy / partial / hard — cost of switching away later
|
||||
recommended_now: yes / no / conditional
|
||||
```
|
||||
|
||||
**Note:** Unknown is not the same as bad. Prototype choice is not always final architecture choice.
|
||||
|
||||
---
|
||||
|
||||
## Matrix 001 — Object Proposal Strategy
|
||||
|
||||
**Decision:** How should the system produce initial CanonicalObject proposals from raw input?
|
||||
|
||||
| Option | compute_efficiency | memory_efficiency | implementation_complexity | training_complexity | state_inspectability | failure_localizability | prototype_speed | solo_builder_feasibility |
|
||||
|---|---|---|---|---|---|---|---|---|
|
||||
| A. Rule-based NER + heuristics | high | high | low | none | high | high | high | high |
|
||||
| B. Small fine-tuned span extractor (~100M) | med | med | med | med | med | high | med | med |
|
||||
| C. Prompted general LLM | low | low | low | none | low | low | high | high |
|
||||
| D. Full encoder-decoder proposal model | low | low | high | high | med | med | low | low |
|
||||
|
||||
```
|
||||
Option A — Rule-based NER + heuristics
|
||||
key_benefit: Zero training cost, fully inspectable, fast to iterate contracts against
|
||||
key_risk: Low recall on implicit or unusual entities; won't generalize to new domains
|
||||
unknowns: How many object kinds can be reliably detected with rules alone?
|
||||
what_it_unlocks: Fast contract stabilization; deterministic test fixtures
|
||||
what_it_blocks: Realistic handling of ambiguous or implicit entities
|
||||
reversibility: easy — rules are swappable
|
||||
recommended_now: yes — for first vertical slice
|
||||
|
||||
Option B — Small fine-tuned span extractor
|
||||
key_benefit: Better recall than rules, bounded output, can be contract-tested
|
||||
key_risk: Requires labeled data; adds training loop before contracts are stable
|
||||
unknowns: Minimum labeled data needed for acceptable recall on target domains?
|
||||
what_it_unlocks: Realistic prototype; near-production object proposal
|
||||
what_it_blocks: Nothing significant
|
||||
reversibility: partial — retraining needed to change object kinds
|
||||
recommended_now: conditional — after contracts stabilize
|
||||
|
||||
Option C — Prompted general LLM
|
||||
key_benefit: Zero training, fast to prototype
|
||||
key_risk: Output is not contract-typed; failure modes are opaque and inconsistent
|
||||
unknowns: ?
|
||||
what_it_unlocks: Fast exploration
|
||||
what_it_blocks: All downstream contract-testing; structured state guarantees
|
||||
reversibility: easy
|
||||
recommended_now: no — undermines UCWM's core value proposition
|
||||
|
||||
Option D — Full encoder-decoder proposal model
|
||||
key_benefit: Highest potential recall and precision
|
||||
key_risk: Massive training complexity before any contract is validated
|
||||
unknowns: ?
|
||||
what_it_unlocks: Full generality
|
||||
what_it_blocks: Fast iteration; solo buildability
|
||||
reversibility: hard
|
||||
recommended_now: no
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Matrix 002 — Constraint Representation Format
|
||||
|
||||
**Decision:** What format should constraints use internally?
|
||||
|
||||
| Option | state_inspectability | constraint_explicitness | swappability | implementation_complexity | reasoning_power | prototype_speed |
|
||||
|---|---|---|---|---|---|---|
|
||||
| A. Typed record structs (per schema) | high | high | high | med | med | med |
|
||||
| B. Predicate logic strings | high | med | med | low | high | med |
|
||||
| C. Graph edges in a knowledge graph | med | med | low | high | high | low |
|
||||
| D. Embedding vectors | low | low | low | low | low | high |
|
||||
|
||||
```
|
||||
Option A — Typed record structs
|
||||
key_benefit: Directly contract-testable; every field is named and typed
|
||||
key_risk: Requires upfront schema design for each constraint type
|
||||
unknowns: How many constraint types are needed before the schema stabilizes?
|
||||
what_it_unlocks: Unit testing of individual constraints; specialist contract validation
|
||||
what_it_blocks: Nothing significant for structured reasoning
|
||||
reversibility: partial — schema changes require migration
|
||||
recommended_now: yes
|
||||
|
||||
Option B — Predicate logic strings
|
||||
key_benefit: Human-readable; can feed formal solvers
|
||||
key_risk: String parsing adds fragility; harder to type-check
|
||||
unknowns: How to handle probabilistic and defeasible constraints in logic strings?
|
||||
what_it_unlocks: Integration with SMT solvers, Prolog-style inference
|
||||
what_it_blocks: Clean contract testing without a parser layer
|
||||
reversibility: partial
|
||||
recommended_now: conditional — after typed structs prove insufficient
|
||||
|
||||
Option C — Knowledge graph edges
|
||||
key_benefit: Natural representation for relation-heavy domains
|
||||
key_risk: Graph traversal adds latency; harder to express soft constraints
|
||||
unknowns: Which graph library and query interface?
|
||||
what_it_unlocks: Graph-native reasoning; visualization
|
||||
what_it_blocks: Simple sequential constraint resolution
|
||||
reversibility: hard
|
||||
recommended_now: no
|
||||
|
||||
Option D — Embedding vectors
|
||||
key_benefit: Fast similarity; compatible with neural downstream
|
||||
key_risk: Zero inspectability; no contract-testing possible
|
||||
unknowns: ?
|
||||
what_it_unlocks: Neural constraint matching
|
||||
what_it_blocks: Everything UCWM stands for
|
||||
reversibility: easy
|
||||
recommended_now: no
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to add a new matrix
|
||||
|
||||
Copy the template above. Give it the next sequential ID and a clear decision statement. Fill in relevant columns only — not every column applies to every decision. Mark unknowns as `?` rather than guessing. Add the per-row summary block for every option.
|
||||
|
||||
Archive old matrices as decisions are made, but do not delete them. Past reasoning is provenance.
|
||||
279
docs/implementation_constraints.md
Normal file
279
docs/implementation_constraints.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# Implementation Constraints (v1.1)
|
||||
|
||||
These constraints apply to every module in the system without exception. They are architectural rules, not guidelines. A module that violates any of them is not a valid UCWM module, regardless of whether it produces correct answers.
|
||||
|
||||
---
|
||||
|
||||
## 1. No hidden state between modules
|
||||
|
||||
Every module must:
|
||||
- Accept only typed inputs defined by its contract
|
||||
- Produce only typed outputs defined by its contract
|
||||
- Not rely on hidden global context
|
||||
- Not rely on implicit latent carryover from prior calls
|
||||
|
||||
If a module needs information, it must be passed explicitly through the WorldState or arguments. A module that reads from a global variable or internal cache that is not visible in WorldState is invalid.
|
||||
|
||||
---
|
||||
|
||||
## 2. WorldState is the source of truth
|
||||
|
||||
All state lives in WorldState. Modules must not:
|
||||
- Store their own internally evolving state across calls
|
||||
- Cache interpretations across calls unless that cache is explicitly registered as a field in WorldState
|
||||
- Mutate shared objects directly — all changes must be returned as typed outputs and applied by the receiving layer
|
||||
|
||||
All changes take the form:
|
||||
```
|
||||
Operation {
|
||||
type: "propose" | "merge" | "refine" | "link" | "suppress"
|
||||
target_refs: string[]
|
||||
payload: typed payload per operation type
|
||||
confidence_delta: float?
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Every operation must be logged
|
||||
|
||||
All module outputs must include provenance. The provenance record must be sufficient to reconstruct:
|
||||
|
||||
```
|
||||
final_answer → constraints → facets → objects → source text
|
||||
```
|
||||
|
||||
Every Constraint, Facet, and Object created or modified must have a corresponding ProvenanceRecord with:
|
||||
```
|
||||
ProvenanceRecord {
|
||||
source_module: string
|
||||
input_refs: string[]
|
||||
output_refs: string[]
|
||||
reasoning_tag: string -- short label for what operation was performed
|
||||
}
|
||||
```
|
||||
|
||||
See `schemas/provenance.json` for the normative schema.
|
||||
|
||||
---
|
||||
|
||||
## 4. Bounded output enforcement
|
||||
|
||||
Every module must declare and enforce explicit output caps in its manifest. No module may produce unbounded output.
|
||||
|
||||
Default caps (may be overridden per module manifest):
|
||||
```
|
||||
max_objects_proposed: 8
|
||||
max_constraints_emitted: 16
|
||||
max_facets_emitted: 8
|
||||
max_merges: 4
|
||||
max_splits: 2
|
||||
```
|
||||
|
||||
If a module reaches a cap, it must stop and return what it has, not raise an error and discard all output. Partial output is valid. Unbounded output is not.
|
||||
|
||||
Gates have separate caps: a gate emits exactly 1 GateSignal. No cap needed — it is structurally enforced.
|
||||
|
||||
---
|
||||
|
||||
## 5. No free-form text past the perception layer
|
||||
|
||||
After the perception / extraction stage:
|
||||
- No module may output free-form natural language as a primary output
|
||||
- All outputs must be structured, typed, and schema-compliant
|
||||
- Diagnostic `notes` fields in logs may contain free text, but these are not part of the reasoning chain
|
||||
|
||||
Only the final synthesis layer may produce language as output.
|
||||
|
||||
This rule applies to constraint `expression` fields too — they are informational annotations, not authoritative outputs.
|
||||
|
||||
---
|
||||
|
||||
## 6. First-class error states
|
||||
|
||||
Every module must be able to return explicit error states. Forcing a resolution when insufficient information exists is a contract violation.
|
||||
|
||||
Valid first-class output states for any object, facet, or constraint:
|
||||
|
||||
| State | Meaning |
|
||||
|---|---|
|
||||
| `unknown` | The module could not determine a value |
|
||||
| `ambiguous` | Multiple valid interpretations exist |
|
||||
| `conflicting` | Two or more inputs contradict each other |
|
||||
| `insufficient_data` | Not enough evidence to propose anything |
|
||||
|
||||
These states must be returned as typed fields, not inferred from missing values or nulls.
|
||||
|
||||
Example — SpecialistError type:
|
||||
```
|
||||
SpecialistError {
|
||||
error_kind: "unknown" | "ambiguous" | "conflicting" | "insufficient_data"
|
||||
affected_refs: string[]
|
||||
description: string
|
||||
}
|
||||
```
|
||||
|
||||
The resolver preserves and propagates error states rather than collapsing them.
|
||||
|
||||
---
|
||||
|
||||
## 7. Constraint-first thinking
|
||||
|
||||
Specialists should prefer emitting constraints over conclusions.
|
||||
|
||||
Wrong:
|
||||
```
|
||||
Q_result.value = 3
|
||||
```
|
||||
|
||||
Right:
|
||||
```
|
||||
quantity_difference(Q_result, Q1, Q2) -- status: unresolved
|
||||
```
|
||||
|
||||
Resolution happens in the UCWM resolver, not inside specialists. A specialist that resolves arithmetic or logical conclusions itself before emitting constraints is bypassing the resolver contract.
|
||||
|
||||
The exception: arithmetic that is provably deterministic with all operands present may be resolved inline by the quantity specialist, with the resolution logged in provenance.
|
||||
|
||||
---
|
||||
|
||||
## 8. Test-driven module design
|
||||
|
||||
For every module, the following test classes must exist before the module is considered complete:
|
||||
|
||||
| Test class | Validates |
|
||||
|---|---|
|
||||
| Input → output correctness | Expected outputs for known inputs |
|
||||
| Schema compliance | All outputs validate against declared schemas |
|
||||
| Bounded output | Output never exceeds declared caps |
|
||||
| Deterministic behavior | Same input → same output (where determinism is expected) |
|
||||
| Failure modes | Module returns valid error states on ambiguous/missing data |
|
||||
| Domain adherence | Module does not emit facet/constraint kinds outside its manifest |
|
||||
|
||||
See `tests/contracts/` for templates.
|
||||
|
||||
---
|
||||
|
||||
## 9. Minimal vertical slice priority
|
||||
|
||||
Do not build everything before validating anything.
|
||||
|
||||
The first working pipeline must support:
|
||||
```
|
||||
Input sentence
|
||||
→ gate signals
|
||||
→ object extraction (1–3 objects)
|
||||
→ 1–2 specialists
|
||||
→ constraints
|
||||
→ resolution
|
||||
→ correct answer
|
||||
```
|
||||
|
||||
Suggested first domain: math word problems or simple transfer/state-change problems.
|
||||
|
||||
Expand coverage only after the vertical slice produces correct, inspectable, testable output.
|
||||
|
||||
---
|
||||
|
||||
## 10. Language binding stubs
|
||||
|
||||
Two interface stubs must exist from the start, even if naive:
|
||||
|
||||
```
|
||||
to_ucwm(text_input: string) → WorldState
|
||||
from_ucwm(world_state: WorldState) → string
|
||||
```
|
||||
|
||||
See `synthesis/language_bindings.md` for the full interface specification.
|
||||
|
||||
These stubs enforce that translation and generation remain separable from reasoning. The reasoning core must never depend on how language enters or exits the system.
|
||||
|
||||
---
|
||||
|
||||
## 11. Composite routing must be multi-label
|
||||
|
||||
The router must activate multiple specialists simultaneously. Single-label routing is not valid for real-world inputs.
|
||||
|
||||
A valid RoutingDecision activates:
|
||||
```
|
||||
temporal: true
|
||||
causal: true
|
||||
quantity: true
|
||||
```
|
||||
|
||||
Not:
|
||||
```
|
||||
category: "quantity" ← wrong; exactly one specialist selected
|
||||
```
|
||||
|
||||
See `schemas/routing.json#/$defs/RoutingDecision` — the `assignments[]` array is the mechanism.
|
||||
|
||||
---
|
||||
|
||||
## 12. Facets must be independent
|
||||
|
||||
A facet describes only its own dimension. It must not modify or depend on another facet's fields.
|
||||
|
||||
A TemporalFacet must not modify ownership state. A QuantityFacet must not set truth status. Cross-facet interaction happens only through constraints, never through direct facet-to-facet references.
|
||||
|
||||
---
|
||||
|
||||
## 13. Resolver must be replaceable
|
||||
|
||||
The resolver is defined by an interface, not an implementation:
|
||||
|
||||
```
|
||||
resolve(world_state: WorldState) → WorldState
|
||||
```
|
||||
|
||||
The rest of the pipeline must not depend on resolver internals. Any implementation that satisfies `tests/contracts/resolver_contract_tests.md` is a valid resolver. This makes it possible to swap:
|
||||
|
||||
- Simple rule-based resolver
|
||||
- Graph-based constraint solver
|
||||
- Probabilistic constraint solver
|
||||
- SAT-style system
|
||||
|
||||
---
|
||||
|
||||
## 14. Keep implementations simple first
|
||||
|
||||
Prefer clarity over performance. Prefer correctness over cleverness. This system will become complex naturally — do not add complexity early.
|
||||
|
||||
Guidelines:
|
||||
- Use simple, flat data structures where possible
|
||||
- Avoid premature abstraction
|
||||
- An obvious implementation that is slow is better than a clever one that is wrong
|
||||
- Performance optimization begins after contract tests pass
|
||||
|
||||
Language choice is not prescribed. Whatever language is chosen, it must support schema validation of WorldState at every module boundary.
|
||||
|
||||
---
|
||||
|
||||
## 15. Debug mode
|
||||
|
||||
Every implementation must support a debug mode that emits a step-by-step trace:
|
||||
|
||||
```
|
||||
[Step 1] Gate outputs: {gate_id: activated, confidence}
|
||||
[Step 2] Objects proposed: {object_id, kind, label, confidence}
|
||||
[Step 3] Routing decision: {specialist_id, target_refs, budget}
|
||||
[Step 4] Specialist outputs: {specialist_id, new_facets[], new_constraints[]}
|
||||
[Step 5] Constraints: {constraint_id, type, args, strength, status}
|
||||
[Step 6] Resolution log: {operation, affected_refs, result}
|
||||
[Step 7] Final answer: {answer, confidence, derivation_trace}
|
||||
```
|
||||
|
||||
Debug mode must write to a structured log (JSON or equivalent), not only to stdout. The log must be sufficient to replay and inspect any inference.
|
||||
|
||||
---
|
||||
|
||||
## Priority order
|
||||
|
||||
When any two implementation choices conflict, resolve by this priority:
|
||||
|
||||
1. Contracts (schema compliance, interface adherence)
|
||||
2. Testability (can this behavior be verified independently?)
|
||||
3. Inspectability (can intermediate state be read and debugged?)
|
||||
4. Correctness (does it produce right answers?)
|
||||
5. Performance (how fast?)
|
||||
6. Scale (how big?)
|
||||
140
docs/roadmap.md
Normal file
140
docs/roadmap.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# UCWM Roadmap
|
||||
|
||||
## Goal
|
||||
|
||||
A working, inspectable, contract-tested language reasoning system that converts natural language into structured world state, resolves constraints, and produces answers from that structure — not from token pattern matching.
|
||||
|
||||
## Guiding principle
|
||||
|
||||
Build the thinnest possible vertical slice first. Prove the pipeline shape. Replace rule-based components with trained models only after contracts are stable and the slice works end-to-end.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Vertical Slice
|
||||
|
||||
**Goal:** One input in, one correct answer out, with a full inspectable trace at every stage.
|
||||
**Target input:** `"Alice had 5 apples. She gave Bob 2 apples. How many apples does Alice have now?"`
|
||||
**Target output:** `"Alice has 3 apples."` with derivation trace.
|
||||
|
||||
| Sprint | Name | Goal |
|
||||
|---|---|---|
|
||||
| 1 | Skeleton | C++ project compiles. All core types defined. WorldState round-trips to/from JSON. |
|
||||
| 2 | Gates + Proposal | 5 keyword gates fire correctly. Object proposal extracts entities, quantities, events from apple problem. |
|
||||
| 3 | Specialists | Entity specialist resolves Alice/She. Quantity specialist emits arithmetic constraint and resolves it. |
|
||||
| 4 | Resolver + Synthesis + Pipeline | Full pipeline runs. Apple problem produces correct answer with debug trace. All contract tests pass. |
|
||||
|
||||
**Phase 1 exit criteria:**
|
||||
- Apple problem works end-to-end
|
||||
- Each layer has passing contract tests
|
||||
- Debug trace shows full derivation
|
||||
- A failure in one layer is diagnosable without inspecting others
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Domain Expansion
|
||||
|
||||
**Goal:** Expand to more input types. Stress-test contracts. Add the specialists the apple problem skipped.
|
||||
|
||||
| Sprint | Name | Goal |
|
||||
|---|---|---|
|
||||
| 5 | Ownership Specialist | Track possession, transfers, state at time T. Multi-step ownership chains. |
|
||||
| 6 | Temporal Specialist | Before/after/during. Temporal chain example (temporal_001.json) works end-to-end. |
|
||||
| 7 | Causal Specialist | Cause/effect/enabling/blocking. First causal example works. |
|
||||
| 8 | Logic Specialist | Negation, implication, contradiction detection. |
|
||||
| 9 | Multi-step Problems | 3+ step word problems. Resolver handles chains of arithmetic and ownership constraints. |
|
||||
| 10 | Robustness Sprint | Edge cases: empty input, ambiguous entities, contradicting constraints. Error states propagate correctly. |
|
||||
|
||||
**Phase 2 exit criteria:**
|
||||
- All 5 core specialist domains covered (entity, quantity, temporal, causal, logic)
|
||||
- At least 10 distinct example fixtures with passing end-to-end tests
|
||||
- `open_contradictions` and error states tested explicitly
|
||||
- Decision matrix completed for gate implementation (regex vs. transformer)
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Neural Gates
|
||||
|
||||
**Goal:** Replace keyword gates with a trained multi-label transformer classifier. Gate contract unchanged.
|
||||
|
||||
| Sprint | Name | Goal |
|
||||
|---|---|---|
|
||||
| 11 | Training Data | Generate labeled gate training examples (synthetic + manual). At least 500 examples per gate. |
|
||||
| 12 | Gate Model | Fine-tune small encoder (DistilBERT-scale) with 17 sigmoid heads on labeled data. |
|
||||
| 13 | ONNX Integration | Export gate model to ONNX. Load and run via ONNX Runtime in C++. Pass gate contract tests. |
|
||||
| 14 | Calibration | Confidence scores calibrated against held-out set. Recall >= 0.90 on each gate. |
|
||||
|
||||
**Phase 3 exit criteria:**
|
||||
- Gate model passes all contract tests from `tests/contracts/gate_contract_tests.md`
|
||||
- Recall >= 0.90 per gate
|
||||
- Latency per gate array pass <= 20ms on CPU
|
||||
- Keyword gates retained as fallback (togglable)
|
||||
- All downstream behavior unchanged (contract held)
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Neural Specialists
|
||||
|
||||
**Goal:** Replace rule-based specialists with trained neural modules, one at a time.
|
||||
|
||||
| Sprint | Name | Goal |
|
||||
|---|---|---|
|
||||
| 15 | Entity Specialist (Neural) | Small NER + coreference model. Passes entity contract tests. Replaces rule-based version. |
|
||||
| 16 | Quantity Specialist (Neural) | Numeric extraction + arithmetic constraint emission. Handles implicit quantities. |
|
||||
| 17 | Temporal Specialist (Neural) | Temporal ordering under ambiguity. Handles implicit sequence without explicit connectives. |
|
||||
| 18 | Resolver Upgrade | Add probabilistic constraint handling. Soft constraint weighting. Multiple hypotheses. |
|
||||
| 19 | Synthesis Upgrade | Move from template-based to generative synthesis. Answer quality evaluation. |
|
||||
|
||||
**Phase 4 exit criteria:**
|
||||
- Each specialist passes its contract tests with the neural implementation
|
||||
- Performance equal to or better than rule-based on held-out examples
|
||||
- Rule-based versions retained as reference implementations for debugging
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Perception Model
|
||||
|
||||
**Goal:** Build or integrate the broad ~1B parameter perception model that handles object proposal for novel domains.
|
||||
|
||||
| Sprint | Name | Goal |
|
||||
|---|---|---|
|
||||
| 20 | Architecture Decision | Decision matrix: train from scratch vs. fine-tune existing. Encoder-only vs. encoder-decoder. |
|
||||
| 21 | Perception Prototype | Small prototype perception model producing CanonicalObject proposals on unseen inputs. |
|
||||
| 22 | Shared Encoder | Evaluate sharing the perception encoder with the gate classifier heads. |
|
||||
| 23 | Integration | Wire perception model into pipeline. Replace rule-based object proposal. |
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — Scale and Specialized Domains
|
||||
|
||||
**Goal:** Expand to code, planning, social reasoning, and multi-turn conversation.
|
||||
|
||||
| Sprint | Name | Goal |
|
||||
|---|---|---|
|
||||
| 24 | Code Specialist | AST-constrained generation. Code object proposals. Dependency graph constraints. |
|
||||
| 25 | Planning Specialist | Step/goal/prerequisite tracking. Multi-step planning problems. |
|
||||
| 26 | Social Specialist | Belief, intention, obligation, deception. Theory of mind examples. |
|
||||
| 27 | Multi-turn | WorldState carries over across turns. Coreference across sentences. |
|
||||
| 28 | Performance | Parallel specialist execution. Profiling. Latency targets. |
|
||||
|
||||
---
|
||||
|
||||
## Key decision points
|
||||
|
||||
These are forks in the road that should be decided with a decision matrix (see `docs/decision_matrices.md`) rather than ad hoc:
|
||||
|
||||
| Decision | When |
|
||||
|---|---|
|
||||
| Gate implementation: keyword vs. neural | End of Phase 2 |
|
||||
| Specialist implementation: rule vs. neural (per specialist) | After each rule-based specialist is validated |
|
||||
| Perception model: train from scratch vs. fine-tune | Start of Phase 5 |
|
||||
| Resolver: deterministic vs. probabilistic vs. SAT | End of Phase 3 |
|
||||
| Shared encoder: gate + perception vs. separate models | Start of Phase 5 |
|
||||
| Synthesis: template vs. generative | End of Phase 4 |
|
||||
|
||||
---
|
||||
|
||||
## What this is not
|
||||
|
||||
- Not a chatbot. Multi-turn comes late (Sprint 27) because single-turn must be solid first.
|
||||
- Not a 30B dense model. The goal is comparable usefulness via decomposition and structure.
|
||||
- Not a research paper. The goal is a working system. Publish after it works.
|
||||
204
docs/sprint_001.md
Normal file
204
docs/sprint_001.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# Sprint 1 — Skeleton
|
||||
|
||||
## Goal
|
||||
|
||||
The C++ project compiles cleanly. All core UCWM types are defined as C++ structs. A `WorldState` can be constructed in code and serialized to JSON. No logic runs yet — this sprint is purely about getting the type system right before anything else is built on top of it.
|
||||
|
||||
**If the types are wrong here, everything built on them will be wrong. Take the time to get them right.**
|
||||
|
||||
---
|
||||
|
||||
## Deliverables
|
||||
|
||||
| File | Description |
|
||||
|---|---|
|
||||
| `CMakeLists.txt` | Build system. CPM dependencies. Targets for main and tests. |
|
||||
| `src/types.hpp` | All core UCWM structs: CanonicalObject, all Facet types, Constraint, GateSignal, RoutingDecision, WorldState, Provenance, SpecialistError. |
|
||||
| `src/main.cpp` | Smoke test: constructs a minimal WorldState for the apple problem by hand, serializes to JSON, prints debug output. |
|
||||
| `tests/test_types.cpp` | Unit tests: construct each type, verify field access, verify JSON round-trip. |
|
||||
|
||||
---
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `cmake -B build && cmake --build build` succeeds with zero errors and zero warnings
|
||||
- [ ] `./build/ucwm` runs and prints a JSON-serialized WorldState to stdout
|
||||
- [ ] `./build/tests` runs and all type tests pass
|
||||
- [ ] Every field from `schemas/objects.json`, `schemas/facets.json`, `schemas/constraints.json`, `schemas/routing.json`, `schemas/provenance.json`, and `schemas/world_state.json` has a corresponding C++ field
|
||||
- [ ] No raw owning pointers — use `std::optional`, `std::variant`, `std::vector`, `std::unordered_map`
|
||||
- [ ] All string IDs typed as `std::string` (upgrade to a newtype wrapper in a later sprint if needed)
|
||||
|
||||
---
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Any gate logic
|
||||
- Any specialist logic
|
||||
- Any resolver logic
|
||||
- Any synthesis logic
|
||||
- JSON Schema validation (structs mirror the schemas, but no runtime validation yet)
|
||||
- Neural models of any kind
|
||||
- Performance optimization
|
||||
|
||||
---
|
||||
|
||||
## Dependencies (pulled via CPM)
|
||||
|
||||
```cmake
|
||||
CPMAddPackage("gh:nlohmann/json@3.11.3")
|
||||
CPMAddPackage("gh:gabime/spdlog@1.13.0")
|
||||
CPMAddPackage("gh:catchorg/Catch2@3.5.4")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type design notes
|
||||
|
||||
### Use `std::variant` for sum types
|
||||
|
||||
Object kind, facet kind, constraint status, object status — these are closed enumerations in the schema. Use `enum class` for simple enums, `std::variant` when the type carries different data per variant.
|
||||
|
||||
```cpp
|
||||
enum class ObjectKind {
|
||||
Entity, Event, Concept, Proposition,
|
||||
RelationInstance, ProcedureStep, CodeObject,
|
||||
Quantity, Claim, State
|
||||
};
|
||||
|
||||
enum class ObjectStatus { Proposed, Active, Merged, Split, Invalidated };
|
||||
enum class ConstraintStrength { Hard, Soft, Probabilistic, Defeasible };
|
||||
enum class ConstraintStatus { Unresolved, Resolved, Contradicted, Suspended };
|
||||
enum class Polarity { Positive, Negative };
|
||||
```
|
||||
|
||||
### Use `std::optional` for nullable fields
|
||||
|
||||
Schema fields that are not in `required` should be `std::optional<T>` in C++. Never use raw nulls or sentinel values.
|
||||
|
||||
```cpp
|
||||
std::optional<SurfaceSpan> surface_span;
|
||||
std::optional<std::string> canonical_label;
|
||||
std::optional<std::string> merged_into;
|
||||
std::optional<float> probability; // only when strength=Probabilistic
|
||||
```
|
||||
|
||||
### Facets as a variant
|
||||
|
||||
All facet types share a base set of fields, then add domain-specific fields. Represent as a `std::variant` or a struct with a `std::variant` payload.
|
||||
|
||||
```cpp
|
||||
struct TemporalFacetData {
|
||||
std::optional<std::string> time_point;
|
||||
std::optional<std::string> interval_start;
|
||||
std::optional<std::string> interval_end;
|
||||
bool is_recurring = false;
|
||||
std::optional<std::string> recurrence_pattern;
|
||||
std::vector<std::string> temporal_order_refs;
|
||||
};
|
||||
|
||||
// ... one struct per facet kind ...
|
||||
|
||||
using FacetData = std::variant<
|
||||
TemporalFacetData,
|
||||
SpatialFacetData,
|
||||
CausalFacetData,
|
||||
LogicalFacetData,
|
||||
OwnershipFacetData,
|
||||
QuantityFacetData,
|
||||
SyntacticFacetData,
|
||||
SocialFacetData,
|
||||
PlanningFacetData
|
||||
>;
|
||||
|
||||
struct Facet {
|
||||
std::string facet_id;
|
||||
std::string object_ref;
|
||||
float confidence;
|
||||
std::string source_module;
|
||||
std::vector<std::string> provenance_refs;
|
||||
FacetData data; // kind is implicit in the variant index
|
||||
};
|
||||
```
|
||||
|
||||
### WorldState as maps
|
||||
|
||||
```cpp
|
||||
struct WorldState {
|
||||
std::string state_id;
|
||||
WorldStateStage stage;
|
||||
std::optional<std::string> input_text;
|
||||
std::unordered_map<std::string, CanonicalObject> objects;
|
||||
std::unordered_map<std::string, Facet> facets;
|
||||
std::unordered_map<std::string, Constraint> constraints;
|
||||
std::unordered_map<std::string, Provenance> provenance;
|
||||
std::optional<RoutingDecision> routing_decision;
|
||||
std::vector<GateSignal> gate_signals;
|
||||
std::vector<ResolutionEntry> resolution_log;
|
||||
std::vector<ContradictionRecord> open_contradictions;
|
||||
std::optional<std::string> synthesis_answer;
|
||||
std::optional<float> synthesis_confidence;
|
||||
std::vector<std::string> derivation_trace;
|
||||
};
|
||||
```
|
||||
|
||||
### JSON serialization
|
||||
|
||||
Use `nlohmann/json`'s `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE` macro or manual `to_json`/`from_json` overloads. Every type needs both directions for the debug trace and for loading fixtures.
|
||||
|
||||
```cpp
|
||||
// Example pattern for each type:
|
||||
void to_json(nlohmann::json& j, const CanonicalObject& o);
|
||||
void from_json(const nlohmann::json& j, CanonicalObject& o);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File layout after Sprint 1
|
||||
|
||||
```
|
||||
ucwm/
|
||||
CMakeLists.txt
|
||||
cmake/
|
||||
CPM.cmake
|
||||
src/
|
||||
types.hpp ← all structs and enums
|
||||
main.cpp ← smoke test
|
||||
tests/
|
||||
test_types.cpp ← type construction + JSON round-trip tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Smoke test behavior (`main.cpp`)
|
||||
|
||||
`main.cpp` should:
|
||||
1. Construct the post-proposal WorldState from `examples/word_problem_001.json` by hand (hardcoded, not parsed — parsing the fixture comes in Sprint 2)
|
||||
2. Serialize it to JSON using nlohmann/json
|
||||
3. Print the JSON to stdout
|
||||
4. Print a simple debug header showing object count, constraint count
|
||||
|
||||
Expected output:
|
||||
```
|
||||
=== UCWM Smoke Test ===
|
||||
WorldState stage: post_proposal
|
||||
Objects: 7
|
||||
Facets: 0
|
||||
Constraints: 0
|
||||
|
||||
[full JSON follows]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Definition of done
|
||||
|
||||
Sprint 1 is done when:
|
||||
1. All acceptance criteria checkboxes are checked
|
||||
2. A second person (or the same person on a fresh read) can understand every field in `types.hpp` without referring back to the schemas
|
||||
3. The JSON output of `main.cpp` matches the structure of `examples/word_problem_001.json` for the post-proposal stage
|
||||
|
||||
---
|
||||
|
||||
## Next sprint preview
|
||||
|
||||
Sprint 2 builds the keyword gates and rule-based object proposal on top of these types. None of that can start until `types.hpp` is locked.
|
||||
90
docs/vocabulary.md
Normal file
90
docs/vocabulary.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# UCWM Vocabulary
|
||||
|
||||
## Core terms
|
||||
|
||||
**UCWM — Unified Constraint World Model**
|
||||
The whole structured reasoning substrate. Converts messy natural language into a typed world state of objects, facets, and constraints, then resolves that state to produce answers.
|
||||
|
||||
**RSA — Relay Specialist Architecture**
|
||||
The routing and dispatch mechanism inside UCWM. RSA decides which specialists run, on which objects, with what budget. RSA is not the model core; UCWM is.
|
||||
|
||||
**CanonicalObject**
|
||||
The primary reusable referent. A stable anchor that facets attach to. Objects are not overloaded — they carry identity, kind, status, confidence, and refs to facets, constraints, and provenance.
|
||||
|
||||
**FacetBundle**
|
||||
The collection of typed descriptions attached to a single canonical object. A single object may have temporal, causal, spatial, logical, and other facets simultaneously.
|
||||
|
||||
**Facet**
|
||||
A partial, typed view of a canonical object. Examples: TemporalFacet, SpatialFacet, CausalFacet, QuantityFacet. Facets are optional — not every object exists in every relation type.
|
||||
|
||||
**Schema Plurality**
|
||||
The principle that the same underlying thing may be validly described by multiple schema systems simultaneously. UCWM does not force a single schema early. Specialists attach schema-shaped facets; the resolver reconciles.
|
||||
|
||||
**Constraint**
|
||||
An explicit relation, restriction, incompatibility, requirement, or preference involving objects and/or facets. Constraints are the core reasoning currency. Examples: `before(E1, E2)`, `owns(Alice, apples, count=5)`, `quantity(Q1) = quantity(Q2) - 3`.
|
||||
|
||||
**Constraint Profile**
|
||||
The active set of constraints touching a given object and its facets.
|
||||
|
||||
**Composite Routing**
|
||||
A relay decision that activates multiple specialists on the same target simultaneously.
|
||||
|
||||
**Relation Gate Array**
|
||||
The front-end set of small recognizers that detect which relation families are probably relevant to the input. High-recall by design — prefer false activation over missed activation.
|
||||
|
||||
**GateSignal**
|
||||
The output of a single gate. Contains: gate_id, activated flag, confidence score, and evidence spans.
|
||||
|
||||
**RoutingDecision**
|
||||
The output of the relay. Contains: active specialists, target object refs, execution mode, budget, and priority order.
|
||||
|
||||
**WorldState**
|
||||
The active UCWM state at a given processing stage. Contains all current objects, facets, constraints, and their statuses.
|
||||
|
||||
**Contractual Layer**
|
||||
A module boundary with typed input/output schemas and testable behavior. Every UCWM layer is a contractual layer.
|
||||
|
||||
**Specialist**
|
||||
A contract-bound module that takes canonical objects and routing context, and emits typed facets and constraints. May be neural, symbolic, statistical, or hybrid. Emits bounded structured output — never unconstrained free text.
|
||||
|
||||
**Resolver**
|
||||
The UCWM component that combines constraints from specialists, detects contradictions, reinforces agreements, and stabilizes WorldState into a resolved form ready for synthesis.
|
||||
|
||||
**Synthesis**
|
||||
The final stage. Produces a natural language answer and derivation trace from resolved WorldState. The answer must be derivable from constraints, not from surface token patterns.
|
||||
|
||||
**Provenance**
|
||||
A record of where a fact, object, facet, or constraint came from: which input span, which module, which inference step, at what confidence.
|
||||
|
||||
## Constraint strength levels
|
||||
|
||||
| Strength | Meaning |
|
||||
|---|---|
|
||||
| `hard` | Must hold; contradiction is an error |
|
||||
| `soft` | Preferred; can be overridden by hard constraints |
|
||||
| `probabilistic` | Holds with a stated probability |
|
||||
| `defeasible` | Default assumption; can be retracted by new evidence |
|
||||
|
||||
## Constraint status lifecycle
|
||||
|
||||
```
|
||||
unresolved → resolved
|
||||
→ contradicted
|
||||
→ suspended
|
||||
```
|
||||
|
||||
## Object kinds
|
||||
|
||||
`entity`, `event`, `concept`, `proposition`, `relation_instance`, `procedure_step`, `code_object`, `quantity`, `claim`, `state`
|
||||
|
||||
## Object status lifecycle
|
||||
|
||||
```
|
||||
proposed → active → merged
|
||||
→ split
|
||||
→ invalidated
|
||||
```
|
||||
|
||||
## Facet kinds
|
||||
|
||||
`temporal`, `spatial`, `causal`, `logical`, `syntactic`, `semantic`, `social`, `ownership`, `code_structure`, `quantity`, `planning`
|
||||
Reference in New Issue
Block a user