Skip to content

fix(ingest): accept AI transcript archive replays - #252

Merged
jmagar merged 10 commits into
mainfrom
codex/ai-transcript-archive-replay
Sep 28, 2026
Merged

jmagar merged 10 commits into
mainfrom
codex/ai-transcript-archive-replay

Conversation

@jmagar

@jmagar jmagar commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Treat the path-derived transcript locator as mutable when verifying receipt-backed AI transcript replays.
  • Preserve the durable evidence-v2 receipt format instead of introducing a new on-disk fingerprint format.
  • Verify locator moves against the canonical stored locator before accepting a duplicate, while continuing to reject changes to immutable transcript evidence.
  • Read the short-lived evidence-v3 receipts produced by the pre-review patched deployment and lazily rebind them to canonical v2 only after the evidence matches.
  • Cover current v2 receipts, transient v3 receipts, migration-53 null fingerprints, old full-envelope fingerprints, repeated archive moves, and changed-payload rejection.

Root cause

An AI client can move a transcript from its active sessions directory to its archive directory without changing the file inode or transcript record. The forwarder intentionally retains the same source record ID across that move, but the receiver's v2 fingerprint included the path-derived locator. The receiver therefore returned 409 idempotency_conflict, rolling back the batch and preventing the forwarder checkpoint from advancing.

Review hardening

The review surfaced and fixed these issues:

  • Rollback/read compatibility: persisting the proposed v3 fingerprint would make receipts unreadable by the previous Cortex release. New durable receipts remain v2. Existing transient v3 receipts are accepted only after full evidence validation and are then rebound to canonical v2.
  • Replay-query overhead: the first compatibility implementation added an extra receipt-to-log locator query for v2 mismatches. The stored locator is now fetched by the existing receipt lookup instead.
  • Compatibility coverage: tests now prove changed immutable evidence cannot claim v2/v3 receipts, legacy null receipts accept locator moves only when the remaining evidence matches, old/transient formats rebind safely, and repeated locator changes remain duplicates.
  • Invariant clarity: comments now distinguish durable fingerprint-format compatibility from locator-move behavior so rollback guarantees are not overstated.

Verification

  • Archive-replay regression reproduced the original 409 and passes with the fix.
  • Focused replay/idempotency coverage exercises v2, transient v3, old full-envelope, and null-fingerprint receipts.
  • The branch has been refreshed onto current main.
  • Formatting, version sync, dependency policy, repository contract, public identity, Clippy, tests, benchmark, container/deployment contracts, and CodeQL are required before this draft is ready.

The local patched deployment previously caught up across the affected transcript backlog and continued advancing receipts afterward. This PR remains draft and has not been merged or released through the normal release path.

@jmagar
jmagar marked this pull request as ready for review September 28, 2026 05:51
@jmagar
jmagar enabled auto-merge (squash) September 28, 2026 05:52
@jmagar
jmagar merged commit a1a8443 into main Sep 28, 2026
18 checks passed
@jmagar
jmagar deleted the codex/ai-transcript-archive-replay branch September 28, 2026 05:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant