feat(adapters): migrate canonical snapshot and event identity formats

[jbeda]

Scope

Review stack: #2404 engine → #2405 providers → #2406 adapters → #2407 host. Full approved delivery plan.

Third draft in the #2117 canonical-identity review stack. Base: impl/2117-identity-providers; the diff contains only adapters/** (21 files). The review stack is linear for source review; the actual module dependency is engine → adapters, not providers → adapters.

• Decode old snapshot/event records and write explicit schema-2 envelopes with canonical occurrence identity and session-owned replay.
• Preserve snapshot atomicity, continuation state, pruning behavior and original legacy evidence provenance across JSONL, Redis and decoding gRPC drivers.
• Cover format refusal before backend mutation, decoding-driver skew, opaque-driver preservation, event identity and pruning with offline fixtures/conformance.

No new persistence service, sidecar replay store, general reconciliation, durability policy or host/client implementation.

API compatibility

Consumes the already-approved breaking pre-v1 engine minor, with adapter compatibility classified in adapters/CHANGELOG.md. Real engine release/pin reconciliation is required before standalone/publication qualification; no invented future versions.

Stored data/driver contract: write sessnap-json/2 and eventlog-json/2; upgraded readers accept /1 and /2. Decoding drivers must understand the new identity schema; opaque drivers preserve payload+format bytes. Format rejection precedes backend mutation. Preserve valid old continuations/evidence; ambiguous pending identity remains inspectable but cannot grant execution/learning authority.

Upgrade: drain old readers/writers and upgrade both independently configured snapshot and event decoding drivers before new harness/client writers. Upgraded readers may return new-format data. No mixed writers or downgrade after new-format writes; do not delete durable records/cursors as a workaround. Existing opaque driver service marker/proto routes do not need a new major merely for envelope-format values.

No Harness protobuf/HTTP/advertised-major change in this diff. The final host/client PR exposes approved Harness API major 2; driver envelope compatibility and Go source compatibility are separate assessments.

Verification

Fresh complete assembled qualification passed on 2026-10-18, Go 1.27.2, Linux/amd64, with no uncommitted source changes:

• task --concurrency 3 test:workspace:race — all 12 modules (including grpcdriver/JSONL/Redis tests) plus offline microvm_dev proof.
• task lint — all module checks, 0 issues.
• task docs, task site:build, offline go run ./cmd/mecademo (tool/result, ask/approval/result), and task test:module-metadata; generated/tracked files unchanged.

Workspace selection uses the assembled checkout's absolute go.work and existing unchanged dependency metadata. The tested tree 3763ffe56e1ba21bab363d3ad416c5e4a50077d7 equals public host-stack head da27200c3, with the same adapter/engine source as this PR. Original implementation/rebase reviews apply to unchanged production code. The engine-only source also passed standalone build/test, engine race and API freshness.

Workspace success is evidence for the assembled code, not public dependency closure. No live Redis/service, provider calls, release or deployment was used for qualification.

Publication and expected red CI

Existing engine pins are intentionally unchanged until an authorized engine release. New adapter source cannot pass its workspace-disabled declared-dependency checks against old engine APIs/codecs; root consumer compilation also remains broken before final host propagation. This is the documented dependency-publication gap, not a required-check waiver. Investigate unrelated failures normally.

Before merging/publishing: human-reviewed/main-reachable engine release (separate release authorization) → update adapters to the real engine tag and tidy the affected module → standalone build/test/race and external-consumer/publication qualification → independently publish adapters → final host/integration real pins. No PR-head pseudo-version, permanent replacement, skipped tests or changed CI rules.

Draft for source review, not merge/release-ready. Intermediate merging with red required checks still needs an explicit maintainer decision. No releases, deployments or merges performed.

[jbeda]

Approved engine-first delivery plan

Archived: 2026-10-18. Applies to review stack #2404 → #2405 → #2406 → #2407; exact branch/head/baseline identities below. Local plan paths are provenance only, not remote links. This is the full selected split/qualification plan; verification tasks below describe intended checks, not implicit pass claims. Actual results and remaining gates are recorded separately in the PR bodies.

Engine-first identity delivery

Slug: 2117-engine-identity
Plan path: .scratch/2117-engine-split/plan.md
Original implementation specification: .scratch/2117-tool-call-identity-plan.md (already implemented and reviewed; not reimplementation scope).

Immutable delivery baseline and branches

Base branch: main; recorded start commit f9a3297. Remote main observed at c4a043f (#2402, TUI/docs only); no automatic rebase. Host requires current-main merge qualification before merge.

Review branch	Base branch	Source head
impl/2117-engine-identity	main	5d830f8
impl/2117-identity-providers	impl/2117-engine-identity	c669ec8
impl/2117-identity-adapters	impl/2117-identity-providers	20f60fd
impl/2117-identity-host	impl/2117-identity-adapters	da27200

These bases organize review, not new module dependencies: providers and adapters both depend directly on engine. The host source tree exactly equals the retained assembled qualification candidate (tree 3763ffe56e1ba21bab363d3ad416c5e4a50077d7). The root checkout remains on the engine review branch; assembled/preparation worktrees stay under .scratch/2117-engine-split/.

Approved outcome and authority

Joe approved on 2026-10-18: prepare, commit, push and open four draft PRs: engine; changed providers; persistence adapters; host/contracts/required client integration. Humans alone merge. No tags/releases, deployment, invented dependency pins, CI bypasses or new TUI presentation work. Preserve the assembled candidate in a local worktree under .scratch and keep the engine review branch at the main checkout root.

Source boundary and contracts

• Engine PR: engine/** and the necessary .golangci.yml depguard allowance, including engine-owned tests, migration fixtures, generated API snapshots, changelog and compatibility documentation.
• Provider PR: existing changes under provider/openai, provider/anthropic and provider/openaichat, plus narrow offline real-engine/provider HTTP composition regressions. These modules release independently.
• Persistence PR: adapters/**, including its changelog and driver format/skew coverage.
• Host PR: remaining existing coordinated source, generated wire/SDK/Studio contracts, required client propagation and owning documentation. No new presentation work and no changes to mecatl-3.
• Engine-minted canonical ToolCallID is distinct from provider pairing/item IDs; whole-batch validation before effects; copied history preserves occurrence IDs. Session owns opaque replay and bindings. Ambiguous legacy state is preserved but inspection-only before authority consumption/execution/learning.
• Preserve existing provider fidelity, not a fuller replay redesign. Preserve allow/deny/ask, isolation, scrubbing and argument ownership behavior.

API compatibility

This is the already-approved breaking pre-v1 Go API minor, not additive-only and not /v2 import migration. Engine APIs change invocation identity, provider-neutral DTOs and private replay ownership. The engine PR does not itself change protobuf fields/server major, but carries engine-originated observable semantics that the final host PR exposes as approved Harness API major 2. Public opaque archive reasoning fields are removed/reserved in that final coordinated host/client change; readable reasoning/text/media/phase remain. Snapshot/event writers advance to sessnap-json/2 and eventlog-json/2; upgraded readers accept /1 and /2. Drain old readers/writers, upgrade both decoding drivers, then harness/clients; no mixed writers or downgrade after new writes. Exact module release versions remain unselected and publication requires separate authority.

Tasks and evidence

1. Preserve assembled checkpoint; extract engine-only source in the root checkout and document exact base/HEAD identities.
2. Verify existing engine standalone API/layering/migration tests. Capture engine-only root/provider compilation failures rather than guessing expected failures. Do not suppress unrelated defects.
3. Reuse provider HTTP/SSE fixtures in one narrow real engine + real adapter + trivial tool test per changed provider. Assert canonical call/result ownership and next-request provider pairing/replay including completed provider-key reuse. No server, UI, deployment or paid/live calls. Keep engine dependencies inward.
4. Run focused normal/race composition checks and assembled workspace/race, lint, docs and offline demo at the owning candidate; preserve original historical reviews and perform incremental review of new tests and split boundaries, not another full historical panel.
5. Prepare stacked draft branches in dependency order, with exact source boundaries and matching assembled engine tree. Preserve a fully assembled stack tip. No fabricated PR-head module versions or permanent replacements.
6. Publish four draft PRs with API compatibility statements, exact evidence, expected intermediate CI failures, dependency/release checklist and plan archive comments. Read back published bodies/comments and record their URLs/heads.

Merge/release readiness

Reviewable source is not merge/release-ready. Before the engine merge, dependent source must be reviewable, assembled behavior qualified and release/pin order explicit. Real engine publication precedes provider/adapter pins and independent releases, then final host/integration pins and standalone/publication qualification. Existing required checks are not waived: Joe accepted review drafts with accounted-for consumer failures; any intermediate merge still needs a separate explicit maintainer decision. Release latency cannot be eliminated. Browser/image qualification remains unclaimed unless actually completed; final host draft must disclose inherited limitations.

Verification ownership

The directing agent owns split, integration, PR publication and evidence. A focused writable worker adds provider composition tests only in the retained assembled worktree and runs narrow checks. New tests get independent incremental panel review. Full Go gates use 1800-second outer limits; other full gates 600 seconds. Heavy suites run serially. No HANDOFF update.