ucwm/specialists/contract.md

Specialist Interface Contract

A specialist is a contract-bound module that inspects canonical objects within a specific relation domain and emits typed facets and constraints. Specialists are the workhorses of UCWM — they build the structured world state that the resolver stabilizes.

---

Design principles

1. Bounded output. A specialist emits a finite list of Facets and Constraints. It does not emit free text, tokens, or embeddings as primary output.

2. Contract-typed. Every output conforms to the schemas in schemas/facets.json and schemas/constraints.json.

3. Domain-limited. A specialist operates only in its declared domain. The temporal specialist does not emit ownership constraints.

4. Implementation-neutral. A specialist may be neural, statistical, symbolic, rule-based, graph-based, or hybrid. The contract is identical regardless.

5. Replaceable. Any specialist can be replaced with a different implementation as long as the new implementation satisfies this contract. No other component should be affected.

---

Input

SpecialistInput {
  specialist_id:    string               -- which specialist is being invoked
  target_refs:      string[]             -- object_ids to inspect
  world_state:      WorldState           -- current state (read-only for this specialist)
  routing_context:  SpecialistAssignment -- from the RoutingDecision
  budget:           BudgetSpec           -- resource limits
}

The specialist receives a read-only view of WorldState. It MUST NOT modify WorldState directly. It only returns outputs; the resolver applies them.

---

Output

SpecialistOutput {
  specialist_id:    string
  new_facets:       Facet[]
  new_constraints:  Constraint[]
  updated_objects:  ObjectUpdate[]       -- confidence or alias updates to existing objects
  provenance:       Provenance[]
  budget_used:      BudgetUsed
}

ObjectUpdate {
  object_id:        string
  confidence_delta: float?               -- adjustment to existing confidence
  new_aliases:      string[]?
  new_status:       string?              -- only "proposed" → "active" transitions
}

BudgetUsed {
  objects_inspected:   integer
  constraints_emitted: integer
  iterations_used:     integer
}

---

Invariants

Every specialist implementation MUST satisfy all of the following:

1. Domain adherence. A specialist only emits facets and constraints of kinds it declares in its manifest. A temporal specialist emits temporal facets and temporal constraints (before, after, during). It does not emit ownership facets.

2. Valid refs. Every argument_ref in a constraint and every object_ref in a facet must reference an ID that exists in the input WorldState or in new_objects returned in the same output. No dangling references.

3. Bounded by budget. The specialist respects its BudgetSpec. If max_constraints is 10, it returns at most 10 constraints.

4. Confidence required. Every Facet and Constraint emitted must have a confidence value.

5. Source module declared. Every Facet, Constraint, and Provenance record must have source_module set to the specialist's ID.

6. Provenance required. For every Constraint and Facet emitted, there must be a corresponding Provenance record in provenance[].

7. No WorldState mutation. The specialist only returns outputs. It does not write to WorldState.

8. Idempotent. Calling a specialist twice with identical input produces outputs that are logically equivalent (same constraint set, possibly different IDs if IDs are randomly generated — use deterministic IDs where possible).

---

Specialist manifest format

Each specialist declares its capabilities in a manifest:

SpecialistManifest {
  specialist_id:        string
  display_name:         string
  description:          string
  declared_facet_kinds: string[]       -- facet kinds this specialist may emit
  declared_constraint_types: string[]  -- constraint types this specialist may emit
  trigger_gates:        string[]       -- gate_ids that commonly activate this specialist
  implementation:       string         -- reference to implementation
  version:              string
}

---

Specialist output validation

Before the resolver applies specialist outputs, a contract validator MUST check:

• All emitted facets have facet_kind in declared_facet_kinds
• All emitted constraints have constraint_type in declared_constraint_types
• All argument_refs and object_refs resolve to existing or co-emitted objects
• All confidence values are in [0, 1]
• Budget limits were not exceeded
• source_module is correct on all records

A specialist that emits invalid output is rejected. The resolver logs the rejection and continues without that specialist's output.

---

Registered specialists

specialist_id	Declared facet kinds	Key constraint types
entity	syntactic, semantic	same_entity, not_same_entity
temporal	temporal	before, after, during
spatial	spatial	inside, outside, adjacent
causal	causal	causes, enables, blocks
quantity	quantity	quantity_equals, quantity_sum, quantity_difference
logic	logical	truth_value, implies, negates, contradicts
ownership	ownership	owns, transfers
social	social	has_role, believes, obligated
planning	planning	prerequisite, goal
code	code_structure	domain-specific

See individual specialist files for full manifests and domain logic.