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>
223 lines
7.9 KiB
Markdown
223 lines
7.9 KiB
Markdown
# 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
|