137 lines
5.5 KiB
Markdown
137 lines
5.5 KiB
Markdown
|
# 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.
|