Sprint 1: project skeleton, type system, and all architecture specs
- 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>
This commit is contained in:
136
specialists/contract.md
Normal file
136
specialists/contract.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user