# 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.