# Specialist Contract Tests

Template for testing any specialist implementation against its contract.

---

## Entity Specialist

### ES_001 — Two named entities detected
```
Input: "Alice gave Bob 2 apples."
Expected:
  - new_objects contains at least two entities
  - E_alice.canonical_label = "Alice"
  - E_bob.canonical_label = "Bob"
  - Constraint not_same_entity(E_alice, E_bob) emitted
  - All objects have source_module = "entity"
```

### ES_002 — Coreference resolved
```
Input: "Alice arrived. She sat down."
WorldState contains E_alice from prior proposal.
Expected:
  - same_entity(E_alice, E_she) constraint emitted
  - Confidence >= 0.80
```

### ES_003 — Domain adherence
```
Input: "Alice gave Bob 5 apples."
Expected:
  - No quantity facets emitted
  - No temporal constraints emitted
  - Only syntactic/semantic facets and entity constraints
```

### ES_004 — Budget respected
```
BudgetSpec: max_constraints = 3
Input: very long text with many entities
Expected:
  - len(new_constraints) <= 3
```

### ES_005 — Valid refs
```
Expected for any input:
  - All argument_refs in constraints resolve to IDs in new_objects or input WorldState.objects
  - No dangling refs
```

---

## Quantity Specialist

### QS_001 — Exact arithmetic resolved inline
```
Input context: Q1.value=5, Q2.value=2
Constraint: quantity_difference(Q_result, Q1, Q2) with status=unresolved
Expected:
  - Q_result QuantityFacet.value = 3
  - Q_result QuantityFacet.is_exact = true
  - Constraint status = resolved
```

### QS_002 — Units propagated
```
Input: Q1.unit="apples", Q2.unit="apples"
Expected:
  - Q_result.unit = "apples"
```

### QS_003 — Domain adherence
```
Input: any text
Expected:
  - No temporal facets emitted
  - No entity constraints emitted
  - Only quantity facets and quantity constraints
```

### QS_004 — Unresolvable emits unresolved constraint
```
Input context: Q1.value=5, Q2.value=null (not yet known)
Expected:
  - quantity_difference(Q_result, Q1, Q2) emitted with status=unresolved
  - Q_result.value = null
  - No error, no crash
```

---

## Temporal Specialist

### TS_001 — Explicit ordering
```
Input: "Alice arrived before the meeting started."
Expected:
  - before(EV_arrival, EV_meeting) emitted with strength=hard
  - Both objects referenced exist in WorldState or new_objects
```

### TS_002 — Implicit sequence
```
Input: "The light turned green. The car moved."
Expected:
  - before(EV_light_green, EV_car_move) emitted with strength=soft
```

### TS_003 — Time point attachment
```
Input: "The meeting started at 9am."
Expected:
  - TemporalFacet on EV_meeting with time_point set
  - starts_at(EV_meeting, T_9am) constraint emitted
```

### TS_004 — Domain adherence
```
Expected: no quantity constraints, no entity constraints emitted
```

---

## Cross-specialist invariants (apply to all specialists)

| invariant | check |
|---|---|
| Bounded output | len(new_constraints) <= BudgetSpec.max_constraints |
| Valid refs | all argument_refs resolve |
| Source module | all records have correct source_module |
| Provenance | len(provenance) >= len(new_facets) + len(new_constraints) |
| No WorldState mutation | input WorldState identical before and after call |
| Schema compliance | all outputs validate against schemas/facets.json and schemas/constraints.json |