ucwm/docs/architecture.md

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