Harness

Integrate a new harness

You are adding a harness to txcript, the transcript converter in this repo. The work is one flat file src/harness/<name>.rs plus wiring and tests, but the quality bar is set by two fidelity contracts (below) and by the fact that the output must actually resume in the native app — a session that loads but shows an empty conversation is a failed integration.

Inputs

$ARGUMENTS: <name> <docs> <sample-session-id>

• name — the harness (e.g. gemini, amp). Derive the snake_case id from it.
• docs — URL or file path describing the native transcript format.
• sample-session-id — a real session of that harness on this machine. This is your ground truth. If any input is missing, ask before starting.

The two fidelity contracts (non-negotiable, from src/lib.rs)

1. Native ↔ disk is record-lossless. The Body holds a faithful typed representation; Store/TextCodec round-trip it without loss. This is value-level, not byte-level: serde_json is built without preserve_order, so key order canonicalizes — tests assert record equality, never string equality of the file.
2. Through Common is semantically lossless. to_common may canonicalize representation (so the thread works in another harness) but must never discard what a same-harness round trip needs. The testable form is the fixpoint: to_common(from_common(c)) == c for any c in the harness-representable subset of Common.

Corollary: from_common must be pure and deterministic — synthetic ids are UUIDv5 over a fixed namespace and stable keys like "{session_id}:{i}:{j}", never Uuid::new_v4() (sole exception: generating a session id when meta.id is empty), never clock reads.

Phase 0 — Recon: the bytes are the spec

Before writing any Rust:

1. Read the docs at <docs>.
2. Find the sample session on disk. Probe the harness's storage root (~/.<name>/…, XDG data dirs, an SQLite DB, app-support dirs) until you locate the file/rows for <sample-session-id>.
3. Dump the raw session into the scratchpad. Catalog every record/blob kind you observe: which carry conversation (user/assistant/tool records), which are bookkeeping (headers, token counts, snapshots, titles, model changes), which are opaque (binary, protobuf).
4. Check how the native app resumes a session (CLI flag, id format, sidecar files it validates). The consumer defines correctness, not the schema.
5. Interrogate the consumer by bisection. Find the harness's cheapest read-only replay of a session (<name> export, sessions list, a --print resume) and use it as a load oracle: copy the sample under a fresh id, then delete files/records until it stops loading. What survives deletion is bookkeeping; what breaks the load is the regeneration contract for from_common — learned before writing any code, at zero model cost.
6. Mint the bytes the sample lacks. One session won't cover every record kind you must emit (file edits, images, errored calls, aborts). Don't guess from docs — run the harness itself headlessly in a scratch dir with prompts engineered to exercise each gap, and probe its input flags (a --prompt-json-style flag reveals content-block encodings). The same trick answers optionality questions: to learn whether the native parser treats a field as optional, load a session without it.
7. For multi-file/dual-log formats, write down the exclusive carrier of each semantic field: timestamps, images, or stop reasons may exist only in the display log while reasoning tokens exist only in the model log. to_common is then a join across carriers and from_common a fan-out — knowing the carrier map is most of the codec design.

Where docs and bytes disagree, model the bytes. Keep the dump — it becomes your test fixture material and the final verification anchor. Copy the sample session out of the live root NOW: save() derives its path from Meta, so converting a session back into its source harness reuses the original id and silently overwrites your ground truth.

Phase 1 — Choose the Body shape

Pick the closest existing codec as your reference and re-read it before implementing (don't work from memory of it):

Details and per-harness idioms: read references/patterns.md in this skill directory now.

Phase 2 — Native record rules

• Type only what the codec must interpret; keep messy payload unions as raw Value inside a typed envelope.
• Every typed record struct: #[serde(flatten)] extra: Map<String, Value> for unknown keys, and #[serde(default, skip_serializing_if = "Option::is_none")] on every optional field — absent must not round-trip as null.
• The type tag lives outside the struct (stripped on parse, re-inserted on render), or it duplicates into extra.
• Any classification/parse failure demotes to a raw-Value variant (Record::Other(v)) — never an error, never a dropped line. One corrupt line must not sink the session (jsonl::parse already skips unparseable lines for the line-based path).
• Do NOT put deny_unknown_fields on harness record types. It exists only on the canonical tool-arg structs in common.rs, where it forces the lossless Tool::Raw fallback.

Phase 3 — Codec

to_common

• Claude Code is the canonical convention. Write a normalize_tool(name, input) that maps native tool names and argument keys onto it (bash→Bash, path→file_path, …), then call Tool::from_canonical. Its deny_unknown_fields→Raw fallback is the safety net — never bypass it, never pre-drop keys. mcp__* passes through. Write denormalize_tool at the same time; they must be a real inverse pair, including shape changes (e.g. pi's multi-hunk edit → Edit/MultiEdit by hunk count).
• Tool results ride on Role::User messages (Anthropic convention). Errored calls → is_error: true; in-flight calls → ToolUse with no result.
• Skip bookkeeping records and harness-injected scaffolding (environment preambles, <user_query>-style wrappers — strip on read, re-wrap on write). Skip empty/whitespace-only blocks and messages that end up empty. Unknown block types drop from Common — they still live in the native body.
• Turn-level attribution (model, usage, stop reason) often lives in bookkeeping records far from the message: do a stateful pass with per-turn maps and backfill onto the right assistant message (typically the last text message of the turn).
• Dual-log formats (protocol log + display log): pick the canonical record per kind, mark fallback mirrors, dedup by call id in a post-pass so file order doesn't matter.
• Pairing without ids: key on serialized semantic content, tolerate both arrival orders, use a deterministic synthetic id as last resort.
• Timestamps: parse per-record with fallback to meta.timestamp; never error.

from_common

• Regenerate every field the native app validates on resume — even as explicit null (codex refuses sessions missing model_provider/ base_instructions keys). Regenerate both logs of a dual-log format, and any internal structures the app needs (Cursor's protobuf turn graph, sidecar meta.json). The failure mode here is silent: the app starts a fresh or empty session. Only end-to-end resume testing catches it.
• Write only field shapes you have observed the native app write. This is the loud failure mode, dual to the silent one: native parsers are strict, and one field of an unobserved type fails the WHOLE session load ("invalid type: sequence, expected a string"). Structural pass-through is the lossless instinct for reading and exactly wrong for writing — where Common is richer than the observed slot (structured ToolOutput::Json into a string field, an image block into a text-only log), flatten to the observed shape (block arrays → joined text, other JSON → compact string, image → its display-log carrier plus a placeholder) and document the loss.
• Carry a tool_use_id → native tool name map while emitting tool calls so redundant result fields can be reconstructed; give orphans a fallback.
• Fabricate required-but-derivable fields plausibly (provider from a model-id prefix, zero cost objects, totalTokens) and comment that they are best-effort historical reconstruction.
• Option-vs-zero trap: never serialize a default that parses back as Some(default) (e.g. omit an all-zero cache object entirely).
• Some Common detail may have no native slot (thinking signatures, replace_all, StopReason::Other). Accept the loss, document it in the module doc, and keep the fixpoint fixture inside the representable subset.