tenequm/pond/pond-add-adapter

Adding a pond adapter

An adapter is a bidirectional codec between one agent's native session format and pond's canonical schema (docs/spec.md section 6). The bar it must meet: lossless capture (every source field recoverable), no synthesized values, additive re-sync, and a restore face that is either lossless-native or an honest refusal. The registry cost is fixed and small: one file under packages/pond/src/adapter/ plus its wiring in src/adapter/mod.rs - a module declaration, a re-export, and the registry() entry (spec 6.7).

The work splits into two phases. Phase A produces the spec doc and the fixture; Phase B implements from them. Ship both in ONE self-contained PR: spec doc + fixture + adapter + tests + doc rows. Opening a draft PR after Phase A, so the decision table gets reviewed before implementation, is recommended but not required.

Ground rules that override any instinct to improvise:

• docs/spec.md section 6 is the contract. The named rules cited below (adapter-integrity-*, adapter-bounded-values, model-no-synthesis, ...) are binding, and each states WHY it exists - read the rule before deviating.
• cargo fmt --check, cargo clippy --all-targets -- -D warnings, cargo test green is the whole bar for an adapter PR. No benchmarks: adapters are import-isolated from the store and query layer (a guard test in src/adapter/mod.rs enforces it and lists its exemptions with reasons), so an adapter cannot reach the store's write path, commit discipline, or query plans; what it can still get wrong - parse cost, emitted volume, freshness reads - is what the conformance harness and review look at.
• Third-party session-search parsers (franken_agent_detection, deja-vu, ctx, ...) may be read as corroborating references, never as the authority. Their bar is a search projection; pond's is a lossless round-trip codec.
• Fixtures come from sandboxed self-capture only. Never vendor another repo's fixture, and never copy files from a real (non-sandboxed) agent home.

Phase A - spec the adapter

Output: docs/adapters/<source_agent>.md (named by the brand string, e.g. grok-build.md; the directory is created with the first spec doc) plus the committed fixture.

Preflight, before anything else: the agent binary installed at the version the spec doc will cite, a provider key in the environment (or the credential file step 2 describes), and tmux when the TUI is the only writer. Discovering one of these missing on the day implementation starts is the most expensive kind of blocker.

A key is not always enough. An agent may gate every run on account sign-in rather than on a key, and a per-model API key will not satisfy that gate: grok-build refuses headless runs with "Not signed in" until an OAuth device-code login completes, which needs a human at a browser. Prove the capture can actually run before scripting the session list - one throwaway headless turn in the sandbox, with the credentials you intend to use.

1. Read the writer, not the reader

Clone the upstream agent locally and locate the code that WRITES the session files - serializers, transcript stores, migration code - not code that reads them back. The writer is the authority on what can appear in a file; readers routinely tolerate less than writers emit. Note the agent version or commit you read: it becomes the Last verified line of the spec doc.

Verify every claimed shape empirically against a real capture (step 2). A field the source never actually emits does not get a mapping.

Trace each field's history on the writer file: git log --follow -S'<field>' -- <writer file> (--follow because renames stop -S; a shallow clone needs git fetch --unshallow first). Record it in the spec doc as a field-history section - the commit and date each row kind and field first appeared. That list decides which legacy shapes the current agent can no longer produce, which is exactly what the supplementary synthetic rows in step 2 must cover.

Some upstreams have no history to trace: a filtered monorepo export squashed to one "Synced from monorepo" commit (xai-org/grok-build), a vendored drop. --unshallow cannot recover what was never pushed. Say so in the doc and derive the legacy shapes from the back-compat code instead - #[serde(default)] fields, alias attributes, format-version constants, and the migration paths that still read old shapes. What the current writer can no longer produce is still what its reader tolerates, and that is the list you need.

2. Capture the fixture (sandbox self-capture)

The conformance fixture is captured by running the target agent yourself under a sandboxed home, so the capture is born clean - sanitization collapses into verification. Generator-script synthetics are allowed only as supplementary edge-case rows, never as the round-trip ground truth.

Procedure:

• Create a throwaway home and run the agent entirely inside it: HOME=$(mktemp -d) plus XDG_CONFIG_HOME/XDG_DATA_HOME/XDG_STATE_HOME under it (USERPROFILE on Windows). Prefer a neutral base path (/tmp/<name>-fixture, not $TMPDIR, which embeds the username on macOS) because agents record their cwd and home into rows. A fresh home hides the sign-in state in your real one; if the agent takes its provider key from the environment (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, ...), use that and nothing touches disk. Otherwise copy only the agent's credential file into the sandbox (the opencode capture note in packages/pond/tests/fixtures/README.md shows the shape) and delete it before you copy anything out; auth material never enters the fixture. On Windows a sandboxed USERPROFILE is not full isolation: an agent that resolves known folders through the shell API reads the real profile regardless (grok-build's Claude-compat skill discovery wrote the real username into two sidecar files that way), so sweep for your actual username, not only for the generic patterns.
• Confirm which code path WRITES the session file before scripting (step 1): a headless / -p one-shot mode may skip the writer entirely, or write a reduced shape (letta-code's bidirectional stream drops tool rows; only its TUI writes them). When the TUI is the only complete writer, drive it under tmux: tmux new-session -d -s cap -x 180 -y 45 "<agent> ...", then per prompt tmux send-keys -t cap -l "<text>", sleep 1, tmux send-keys -t cap C-m - sending Enter in the same call as the text inserts a literal U+21B5 into the prompt instead of submitting - and read tmux capture-pane -p -t cap to wait for the turn. Rehearse once in a scratch home, then capture in a fresh one, so the committed fixture holds no retries.
• Script one or more sessions that exercise every shape the decision table needs: multi-turn text, a tool call with its result, a failed tool call, an unfinished/interrupted call, reasoning output if the agent supports it, a subagent/fork/spawn if the format records lineage, and an empty or aborted session. Encoding variants (CRLF, UTF-16) come from a capture on the platform that produces them, never from converting a copy - a converted file keeps the original's session id and collides with it.
• Copy the session files out preserving the agent's native directory layout, under packages/pond/tests/fixtures/adapter/<name>/. The fixture policy in packages/pond/tests/fixtures/README.md governs layout, which fields must stay verbatim, and the anonymization rules - verify against it, run its "Verification" sweep (trufflehog, gitleaks, parse validation) before committing, and add the new platform's section to it (layout, quirks, provenance: producer version/commit, capture date). Include a per-file row census in that section (jq -r .kind transcript.jsonl | sort | uniq -c, or the format's equivalent); every count a test asserts is derived from the census, never from memory - the letta counts drifted twice between capture and test. Reconcile the census against itself too: the per-bucket counts must sum to the total it claims. A grok-build census reading "15 sessions (11 macOS, 1 hash-form, 2 Windows)" - which sums to 14 - survived writing, review, and the fixture README until polish caught it.

3. Fill the decision table

Every row below is a required section of the spec doc. Every answer cites evidence: an upstream file permalink or an observed line in the capture. "Unknown" is an acceptable interim answer in a draft; it is not an acceptable answer at implementation time.