54e6bfc0d0
Implements the 4-phase documentation reorganization master plan. - Consolidation: Merged brief/, handoff/, planning/, and decisions/ into briefs/, handoffs/, plans/, and adr/ respectively (101 ADRs relocated) - Root Cleanup: Relocated HANDOFF-gpt55-*.md and key top-level docs (runtime_contracts.md, etc.) to canonical folders. Added superseded alerts. - Indices & Navigation: Created docs/README.md navigation document, docs/sessions/README.md index, docs/adr/README.md index - Note: Also includes prior commit adding ADR-0200+ corpus hygiene governance (ADR-0225, dependency map, backfilled cross-references)
83 lines
3.3 KiB
Markdown
83 lines
3.3 KiB
Markdown
# ADR-0153 — TurnEvent trace_hash back-stamp (W-020a)
|
|
|
|
Status: accepted
|
|
Date: 2026-05-25
|
|
|
|
## Context
|
|
|
|
`teaching/discovery.py` documents that `DiscoveryCandidate.source_turn_trace`
|
|
"is the upstream `TurnEvent.trace_hash`" (module docstring, line 41).
|
|
The extractor reads it via:
|
|
|
|
```python
|
|
def _trace_hash(turn_event: Any) -> str:
|
|
value = getattr(turn_event, "trace_hash", "") or ""
|
|
return str(value)
|
|
```
|
|
|
|
But `TurnEvent` (`core/physics/identity.py`) has no `trace_hash` field.
|
|
Every `DiscoveryCandidate` written to disk had `source_turn_trace=""`.
|
|
Same defect at `chat/runtime.py:874` for `OOVCandidate`.
|
|
|
|
The real `trace_hash` is computed by `core/cognition/trace.py:compute_trace_hash`
|
|
inside `CognitiveTurnPipeline.process` **after** `runtime.chat()` returns —
|
|
which is after `_emit_discovery_candidates` has already buffered and
|
|
`_checkpointed_response` has already persisted the candidates.
|
|
|
|
Symptom observed: a 103-turn session wrote a `discovery_candidates.jsonl`
|
|
whose one candidate had `"source_turn_trace": ""` — provenance lost.
|
|
|
|
## Decision
|
|
|
|
1. Add `trace_hash: str = ""` to `TurnEvent`.
|
|
2. Add `ChatRuntime.finalize_turn_trace_hash(trace_hash)`. Back-stamps:
|
|
- `turn_log[-1]` (via `dataclasses.replace`)
|
|
- the unstamped tail of `_pending_candidates`
|
|
- re-persists `discovery_candidates.jsonl`
|
|
3. `CognitiveTurnPipeline.process` calls `finalize_turn_trace_hash` after
|
|
`compute_trace_hash`, before constructing `CognitiveTurnResult`.
|
|
|
|
The back-walk halts at the first already-stamped candidate, so prior
|
|
turns' candidates are never overwritten.
|
|
|
|
## Invariants
|
|
|
|
- Empty `trace_hash` is a no-op (refusal/stub call sites do not lose
|
|
byte-identity).
|
|
- Re-stamping is idempotent for the most recent turn and forbidden for
|
|
earlier turns.
|
|
- No change to `compute_trace_hash` inputs — trace_hash bytes for any
|
|
given turn remain identical to pre-ADR-0153.
|
|
- No change to `TurnEvent` telemetry sink emission order (sinks receive
|
|
the pre-stamp event; the persisted record gets the stamped one). A
|
|
follow-up may add a "turn finalized" sink event with the trace_hash.
|
|
|
|
## Out of scope
|
|
|
|
- OOV candidates (`OOVCandidate.source_turn_trace`) — same root cause,
|
|
but the sink is line-streamed at emit time, not buffered. Fix
|
|
requires either buffering OOV or computing trace_hash earlier.
|
|
Tracked separately; no production OOV sink was configured during
|
|
the observed regression.
|
|
- Telemetry sink trace_hash exposure — see invariants above.
|
|
|
|
## Validation
|
|
|
|
`tests/test_adr_0153_trace_hash_backstamp.py`:
|
|
- `TurnEvent.trace_hash` field exists with default `""`
|
|
- main-path `pipe.run` stamps `turn_log[-1].trace_hash == result.trace_hash`
|
|
- main-path `pipe.run` stamps `_pending_candidates[*].source_turn_trace`
|
|
- on-disk `discovery_candidates.jsonl` reflects the stamped values
|
|
- empty trace_hash is a no-op
|
|
- idempotent: prior stamps are not overwritten
|
|
|
|
CLI lanes: `core test --suite cognition` (120 + 1 skipped),
|
|
`core test --suite smoke` (67), `core test --suite runtime` (17),
|
|
`core test --suite teaching` (20) all green.
|
|
|
|
## Provenance gap closure
|
|
|
|
After this ADR, every `DiscoveryCandidate` persisted via the
|
|
load-time auto-proposal pipeline (ADR-0151) carries the canonical
|
|
trace_hash of the turn that produced it, restoring the audit-trail
|
|
invariant the discovery module's docstring already promised.
|