feat(extract): temporal validity role + source-date resolution anchor

[laynepenney]

Temporal validity role + source-date resolution anchor

Spec: config/design/extract-temporal-role-2026-07-14.md. Base: sprint-39.

Replaces recall's B2-LLM-re-judges-temporal duct tape (recall#875/876, now pulled to an honest null placeholder) with a real extract IL fix — direction and resolution both belong at extraction, where the source sentence and source date are directly available, not in a second recall-side LLM pass re-deriving them from already-extracted text.

The gap, in two parts

Direction (role): extract's temporal ref emitted a directionless {raw, resolved}. "2026-04-30" — is that an expiry (→ valid_until) or an effective date (→ valid_from)? The direction lives in the sentence ("expires" vs "effective/since") and extraction dropped it. Root cause (verified against the real pipeline, not reasoned from code): resolved_end/type sit behind a temporal_classes capability recall never requests, and even type: point doesn't encode start-vs-end.

Resolution (source-date anchor): "April 30" only resolves to the right year against the fact's source date. B1 sends extract_batch only candidate text — no anchor. Sentinel's real-path finding: a 2025-sourced "API key expires April 30" resolved to 2026-04-30 under the old decomposed path — wrong year, silently.

What landed

• role enum (effective | expiry | range | superseded | point) on the temporal-ref schema. role + resolved_end moved to BASE tier (no longer temporal_classes-gated) — the actual fix for the unreachability bug. type/context stay gated (non-load-bearing extras once role carries direction).
• BatchUnit.date (optional) — the unit's source date, threaded into Stage-1 as the resolution anchor.
• validate.py: role accepted + enum-validated; role == "range" requires resolved_end (mirrors the existing type == "range" rule).
• _coerce_shape/_coerce_item: zero changes. Verified empirically (before writing any code) that the batch whitelist is schema-driven — preserving role+resolved_end through the batch path is a consequence of the schema fix, not separate coercion logic. This was Apollo's original root-cause diagnosis (the batch coercion strip); turns out the fix for it lives entirely upstream in the schema.
• finalize.py::_detect_capabilities: the temporal_classes heuristic previously kept resolved_end is not None as a trigger — now that resolved_end is base-tier, that would mislabel capability usage. Keys on type presence only now. Found by tracing consequences, not in the spec's literal list.
• A latent prompt bug, found while building this: an absent date param rendered the literal string "Resolve relative dates using: None." — actively misleading, not just unhelpful. Now wrapped in {{#if date}}.
• schemas/temporal-ref/v1.json (the published JSON-schema document, a separate source from the runtime Python) synced to match.
• Version: 0.5.0 → 0.6.0 (additive schema = minor). CHANGELOG updated.

npm / TypeScript parity

Additive-role parity carried; full port deferred. packages/ts is a fully independent reimplementation (own hand-written schema.ts, no extract_batch/batch.ts equivalent at all) — the specific coercion-strip bug this PR fixes doesn't even reproduce there, since there's no batch coercion layer to strip anything. Per Sentinel's REQUEST CHANGES, the additive-role schema/validate/finalize/prompt parity was subsequently carried in this PR (see the "Update" section below); the full batch.ts port and the npm version-sync remain a follow-up (config/design/extract-ts-py-parity-plan-2026-07-15.md). npm stays at its own 0.5.0 for now; Opus is tracking the full-parity effort.

Fruit discipline (this bug's own lesson, applied throughout)

The original temporal fix passed both author-tests and reviewer-fruit because both used a hand-built envelope that misrepresented the real extract contract — only Sentinel's pinned-real-output caught it. Every test here uses the real extract_batch/build_extraction_prompt/validate_extraction call paths, never a hand-built shortcut. The capstone test (test_extract_batch_replicates_sentinels_wrong_year_scenario_end_to_end) replicates her exact bug scenario end-to-end: a 2025-03-01-sourced unit, "API key expires April 30", asserting the persisted envelope carries role="expiry" and resolved="2025-04-30" — the anchored year, not 2026.

Tests

36 new tests across test_validate.py (role enum + range-requires-resolved_end + base-tier-without-temporal_classes), test_extract_batch.py (date threading, per-unit isolation, coercion-preserves-role, the capstone), test_finalize.py (capability-detection heuristic), test_prompt.py (role instructions present, the "None"-bug regression guard). 382 total extract tests green, no regression.

Sequencing

Recall-side consumption (deterministic role → valid_from/valid_until map, replacing the current null placeholder in recall#876) is a follow-up PR, sequenced after this lands — per the design note's own sequencing, and because recall's _EXTRACT_CAPABILITIES needs to re-request temporal_refs and consume the new shape, which depends on this being merged first.

Premium boundary

OSS — extract's IL schema/validation/prompt system is a public primitive (synapt-dev/extract is public). No identity, org, or entitlement logic touched.

Reviewers: Opus, Sentinel

---

Update: ts/py parity slice added (fd8dff3) — Sentinel REQUEST CHANGES resolved

Sentinel's review caught that the Python-only cut left the shared prompt/schema surface in a half-state (shared prompt asks for role; TS surfaces reject it) — which the repo's own schema-drift-check + ts/py-parity contract won't merge. Per Opus (Layne's ts/py-parity directive), carried the additive-role parity here (option A), not asset isolation. The FULL TS parity (a TS batch.ts port) remains the post-validation follow-up per config/design/extract-ts-py-parity-plan-2026-07-15.md.

Canonical + Python public type:

• Repo-root schemas/temporal-ref/v1.json synced to the package copy → diff -r clean, schema-drift-check green (the Python-only cut updated only the package copy).
• schema.py SynaptTemporalRef TypedDict gains role (the runtime emits it; the public type no longer rejects its own output). Guard test asserts the TypedDict declares role AND its Literal members exactly equal the validator's VALID_TEMPORAL_ROLES.
• batch.py docstrings updated for BatchUnit.date + base-tier role/resolved_end (Sentinel's non-blocking doc note).

TypeScript (mirrors the Python decisions exactly): schema.ts (role?), builder.ts (role + resolved_end base-tier), validate.ts (enum + role === "range" → resolved_end), finalize.ts (drops the resolved_end inference), prompt-data.ts (embedded fragment byte-matches the shared file — the fragment-parity test enforces it; TS supports {{#if date}} identically). Version: @synapt-dev/extract (npm) stays at 0.5.0 — the additive-role parity lands without an npm bump; the npm version-sync belongs to the deferred full-parity effort (config/design/extract-ts-py-parity-plan-2026-07-15.md), not this slice. Only synapt-extract (PyPI) bumps to 0.6.0 here (it ships the runtime + extract_batch this traces to). (Reverted at acaccbd after Sentinel caught a package.json-ahead-of-lockfile half-state — package.json had gone to 0.6.0 while the tracked lockfile stayed 0.5.0; both are now consistently 0.5.0.)

Cross-language parity proven empirically, not asserted:

• buildExtractionSchema temporal_refs item → TS and Python produce byte-identical JSON.
• validate + finalize on 5 shared role fixtures → line-for-line identical verdicts, error paths, and temporal_classes detection.
• Embedded prompt fragment == the shared file (byte-exact, existing parity test).

All CI green: schema-drift-check, test-python (3.10–3.13), check-typescript, test-typescript, build-python (schema count unchanged at 13), no-network-guard, reproducibility. 383 Python tests (+ TypedDict guard) + 265 TS tests (+10 mirroring the Python role tests).