ucwm/specialists/temporal.md

# Temporal Specialist

**specialist_id:** `temporal`  
**trigger_gates:** `has_temporal_relation`, `has_state_change`

---

## Responsibility

The temporal specialist adds before/after/during/recurring constraints to events and states. It identifies time points, intervals, and orderings, then attaches TemporalFacets to relevant objects and emits temporal ordering constraints.

---

## Manifest

```
declared_facet_kinds:
  - temporal

declared_constraint_types:
  - before
  - after
  - during
  - overlaps
  - starts_at
  - ends_at
  - recurring

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

---

## Output: TemporalFacet

Attach to any object of kind `event`, `state`, or `procedure_step`.

```
TemporalFacet fields used:
  - time_point:            absolute or relative (if known)
  - interval_start:        if event has a duration
  - interval_end:          if event has a duration
  - temporal_order_refs:   constraint_ids expressing ordering
  - is_recurring:          true/false
  - recurrence_pattern:    if recurring
```

---

## Output: Constraints

### `before(A, B)`

Event or state A occurs before event or state B.

Emit when:
- Explicit connective: `before`, `prior to`, `earlier`, `first ... then`
- Narrative sequence: events described in causal or sequential order
- Completed event followed by a subsequent event

Strength: `hard` for explicit connectives, `soft` for narrative inference.

### `after(A, B)`

Event A occurs after event B. Equivalent to `before(B, A)` but retains the original linguistic direction.

### `during(A, B)`

Event A occurs within the span of event B.

### `overlaps(A, B)`

Events A and B share some time without one being fully within the other.

### `starts_at(E, time_expression)`

Argument_refs: [event_id, time_object_id]. Emit when a specific start time is mentioned.

### `ends_at(E, time_expression)`

Argument_refs: [event_id, time_object_id]. Emit when a specific end time is mentioned.

### `recurring(E, pattern)`

Emit when an event is described as habitual or recurring. Argument_refs: [event_id, pattern_string_as_object].

---

## Ordering baseline algorithm

```
events = [objects in target_refs where kind = event | state | procedure_step]

for each pair (A, B) in events × events where A ≠ B:
  check for explicit temporal connective between A and B
  if found:
    emit corresponding constraint with strength = hard
  else:
    check narrative order (A mentioned before B in text):
    if A is a precondition or cause of B:
      emit before(A, B) with strength = soft
```

---

## Contract test requirements

- Given `Alice had 5 apples. She gave Bob 2 apples.`, must emit `before(EV_initial_possession, EV_transfer)` or equivalent
- Given explicit `before X, Y happened`, must emit `before(Y, X)` with `strength: hard`
- Must not emit entity, quantity, or ownership constraints
- All temporal facets must reference at least one constraint
- All emitted constraints must have `source_module: temporal`