ucwm/specialists/entity.md

# Entity Specialist

**specialist_id:** `entity`  
**trigger_gates:** `has_entity_reference`, `has_coreference`

---

## Responsibility

The entity specialist finds named and implied entities, proposes CanonicalObjects for them, resolves aliases, and detects coreference chains. It upgrades `proposed` objects to `active` when evidence is sufficient, and emits `same_entity` or `not_same_entity` constraints when coreference is resolved.

---

## Manifest

```
declared_facet_kinds:
  - syntactic
  - semantic

declared_constraint_types:
  - same_entity
  - not_same_entity
  - has_role

budget_caps:
  max_objects_proposed:    10
  max_facets_emitted:       8
  max_constraints_emitted: 12
  max_merges:               4
  max_splits:               0
```

---

## Input focus

Given `target_refs`, the entity specialist inspects:
- Surface text spans that evidence each target object
- Pronouns and alias spans in the same context window
- Prior objects already in WorldState with overlapping spans or labels

---

## Output: CanonicalObject proposals

The entity specialist may propose new objects of kind `entity`. New entity proposals use `status: proposed`. Proposals are confirmed (`active`) only if confidence exceeds 0.75.

Required fields on all proposed entities:
- `surface_span`
- `canonical_label`
- `aliases` (may be empty)
- `confidence`
- `source_module: entity`

---

## Output: SyntacticFacet

For each confirmed entity, emit a `SyntacticFacet` describing its grammatical role in the input.

```
SyntacticFacet fields used by entity specialist:
  - grammatical_role: "subject" | "object" | "indirect_object" | "adjunct" | "other"
  - head_token: string
```

---

## Output: Constraints

### `same_entity`

Emit when two object proposals likely refer to the same real-world entity. Common cases:
- Pronoun resolution: `she` → `Alice`
- Alias resolution: `the company` → `Acme Corp`
- Repeated reference: `Alice ... Alice` (same span, different positions)

```
Constraint example:
{
  "constraint_type": "same_entity",
  "argument_refs": ["E1", "E3"],
  "polarity": "positive",
  "strength": "hard",
  "expression": "same_entity(E1, E3)"
}
```

### `not_same_entity`

Emit when two object proposals are clearly different entities that might otherwise be confused.

```
Constraint example:
{
  "constraint_type": "not_same_entity",
  "argument_refs": ["E1", "E2"],
  "polarity": "positive",
  "strength": "hard",
  "expression": "not_same_entity(Alice, Bob)"
}
```

### `has_role`

Emit when an entity is playing a specific functional role in the input context (giver, receiver, buyer, seller, etc.).

```
Constraint example:
{
  "constraint_type": "has_role",
  "argument_refs": ["E1", "EV_transfer"],
  "polarity": "positive",
  "strength": "soft",
  "expression": "has_role(Alice, giver, EV_transfer)"
}
```

---

## Coreference resolution algorithm (rule-based baseline)

```
for each pronoun P in input:
  candidates = all active entity objects in WorldState
  rank candidates by:
    1. recency (closest preceding entity)
    2. gender agreement (he/she/they match)
    3. number agreement (they/them = plural)
    4. animacy (personal pronouns prefer animate entities)
  if top candidate confidence > 0.7:
    emit same_entity(pronoun_object, top_candidate)
  else:
    propose new entity with surface_span = P, status = proposed
```

---

## Contract test requirements

- Given `Alice gave Bob 2 apples`, must emit at least two distinct entity objects (Alice, Bob)
- Must emit `not_same_entity(Alice, Bob)`
- Given `She gave him 2 apples` with prior context establishing Alice and Bob, must resolve `she → Alice` and `him → Bob`
- Must not emit quantity or temporal constraints
- All emitted objects must have `source_module: entity`