Release and versioning policy

Product and public contract#

The distribution coordinate is the transcript-lake crate in this repository. Cargo.toml is the single canonical source of the product version; the build compiles it into the binary, so the installed transcript-lake --version command cannot disagree with the artifact it came from. No independent version literal is maintained.

Transcript Lake follows Semantic Versioning. Its public contract includes:

• the transcript-lake executable and advertised commands and flags;
• human output explicitly documented for operators and structured JSON output documented for automation;
• LAKE_DATA and OKO_CLI configuration semantics;
• canonical event, cursor, partition, Oko-export, and provenance formats;
• adapter trait and supported runtime identifiers;
• documented masking, idempotency, retention, compatibility, and failure behavior.

While the major version is zero, an incompatible contract change advances the minor version and resets the patch version. Additive and corrective changes advance the patch version and are published in this release history. Advancing to major version one is a deliberate declaration of stability.

Channels#

Stado owns source capture, builds, signed publication, and any declared automatic reconciliation. A healthy installer or service process is not proof that the archive consumed a source successfully. Verify its persisted events and downstream projection.

Artifact identity#

A release publishes:

• An exact committed .wisent-release.json and Cargo.toml version.
• A deterministic source archive tied to its full Git revision.
• The manifest's darwin-arm64 build, containing bin/transcript-lake from the declared Cargo target output.
• Immutable archive, qualification receipt, signature, and signed manifest under stado://releases/transcript-lake/<version>/darwin-arm64/.
• The retained real CLI command results and final canonical/Oko evidence.
• Release notes and documentation on this website.

One immutable version attests one source revision. Publication reads each written object back through Stado and compares its bytes before the signed manifest is committed. A correction receives a new version; a Git tag or version banner alone is not delivery evidence.

Release procedure#

The release owner is the Transcript Lake maintainer for wisent-ai/transcript-lake.

1. Review the public CLI, state formats, source adapters, masking, docs, and compatibility impact.
2. Choose the version using the shared version policy, update Cargo.toml and Cargo.lock, and commit the source on main.
3. Run the real product journeys required by the release manifest. The source recovery gate executes source_rewrite, oko_export_role, and show_out against isolated local filesystem state and retains each command's result.
4. Submit the exact commit with stado release submit --source <checkout> --commit <full-revision> --version <version> --channel candidate.
5. Inspect stado release status transcript-lake --json. Resume a recorded interrupted run with stado release resume <run-id> --json, rather than assigning new source to an existing version.
6. Retain the source revision, canonical archive digest, qualification results, publication read-back, and required delivery receipts before claiming a release.

The repository's manifest is the build contract; there is no scripts/build-release.sh or scripts/surface.sh release path. Publication uses the product's independent Skarbiec publisher binding. Runtime transcript access, control-plane access, verification, and signing identities are separate. See Stado release and compatibility for exact refusals and receipt semantics.

Compatibility and state evolution#

Canonical NDJSON and cursor layouts are durable product contracts. A release must not silently reinterpret existing data.

Every persisted-state change documents:

• source and destination schema or format;
• required free space and backup;
• whether migration is lazy, eager, resumable, or forward-only;
• behavior after interruption;
• compatibility with the prior executable;
• rollback point and restoration procedure.

Version 0.2.1 lazily adds verified source-prefix checkpoints to existing three-field byte cursors. Canonical NDJSON and Oko row formats are unchanged. Derived projections remain rebuildable from authoritative masked partitions. Vendor transcripts are externally owned and never modified or used as a Lake rollback artifact.

Upgrade#

1. Record the installed version, source receipt, transcript-lake status --json, and current supervisor declaration.
2. Preserve a recoverable copy of authoritative Lake state under the product's retention policy.
3. Obtain the exact signed Stado coordinate and verify its archive digest through the release interface.
4. Deliver through the owning installer and declared supervisor; do not replace an automatic repair condition with a manual restart.
5. Keep one writer per LAKE_DATA. Apply only the documented migration for the selected version.
6. Inspect actual canonical events and Oko rows after catch-up, including affected older instructions, before reporting successful recovery.

Skipping intermediate versions is supported only when every intervening release note says its migration may be skipped.

Rollback and recovery#

1. Stop the stream and every other process that can mutate the same LAKE_DATA root.
2. Restore the prior immutable archive by version and verified digest.
3. If the newer release changed durable state, restore the matching pre-upgrade backup. Never let two versions mutate one state root concurrently.
4. Confirm the restored version and inspect status.
5. Resume the supervised stream only after state compatibility is established.

If only derived Parquet or Oko-projection state is damaged, keep NDJSON and cursors, remove only the affected derived directory, and rebuild it with the matching supported release. If authoritative partitions or cursors are damaged, preserve them for diagnosis and restore the backup rather than attempting ad hoc repair.

Release notes and limitations#

This page is the canonical release-note source. Each published release records added, changed, fixed, removed, and security behavior; configuration and migrations; compatibility; operator actions; and known limitations.

0.2.3: the qualification journeys record the revision the release worker names

Qualification source identity: The show_out and source_rewrite journeys record the commit supplied by the release worker in WISENT_SOURCE_COMMIT, with no working changes on top of it. This supports qualification from a source snapshot without a .git directory. In a checkout, the journeys read the revision and working changes from Git. A release publisher must be declared through stado release catalog declare-publisher transcript-lake before qualification can publish an artifact.

0.2.2: an omp or droid tool call row carries what was run

Fixed: every tool_call row the omp adapter wrote carried an empty text: it kept the tool's name and call id and dropped the call's arguments; the droid adapter did the same with a tool_use block's input. The claude, codex and kimi adapters had always written the arguments as the row's text. Both adapters now serialise them the same way, so a reader of the Oko projection sees what the agent ran and not only that it ran something. On 2026-09-18 Oko's one-off repair detector, which reads that text, saw nothing for any omp session on the operator's machine.

Migration and cost: none is performed. Canonical NDJSON and Oko row formats are unchanged in shape; rows written before 0.2.2 keep their empty text. History is recovered by rebuild --to <empty-path> --source omp (and --source droid) into a fresh root, which replays the vendor stores through the masker and never mutates the current Lake; the stream and every adopt after the upgrade write the arguments for new appends.

Compatibility and rollback: CLI flags and canonical event schemas are unchanged. The prior executable reads rows written by 0.2.2 and simply carries more text per tool call. Rolling back stops writing the arguments again; nothing written is reinterpreted.

Qualification: the oko_export_role journey adopts a seeded omp transcript through the real binary and reads the exported tool_call row's text back as the call's JSON arguments; the source_rewrite and show_out journeys passed unchanged. The source and manifest are committed at 9a22e41.

0.2.1: verified source recovery

Changed: byte cursors include source with consumed-prefix SHA-256, device, inode, and change timestamps. A changed source verifies that prefix once before resuming. A rewritten or shorter source and a legacy cursor replay through masking against retained canonical occurrence counts. Removed vendor history remains archived. Missing Oko rows are restored.

Migration and cost: legacy records replay lazily during the next catch-up or relevant source notification, including files with no new append. No second source copy or full Lake is created. Memory holds counts for only the affected source's canonical partitions plus bounded read/event buffers. Disk growth consists of genuinely missing masked occurrences, projections, and checkpoint metadata. Preserve a backup before upgrade; the required space depends on previously missing history.

Interruption and refusal: recovery keeps its old cursor until all complete source lines succeed. A later failed write cannot turn a partial replay into an ordinary append; retrying counts already retained occurrences again. Corrupt cursor state remains a refusal. Corrupt canonical evidence names its partition path, line, and cause without changing the evidence or recovery cursor. Write failures name the actual canonical partition and operating-system cause.

Compatibility and rollback: CLI flags and canonical event schemas are unchanged; replay counters and the source checkpoint are additive. The prior executable ignores the new checkpoint field but does not safely handle mutable journals. Rolling it back does not provide this recovery guarantee. Use the owning supervisor's release procedure with one writer; restore a matching backup if required rather than editing cursor records or deleting history.

Qualification: real CLI journeys cover growing replacement, equal-size replacement with preserved mtime, legacy EOF cursor recovery, corrupt canonical refusal, and recovery interrupted after earlier batches reached disk. They inspect both canonical and Oko instructions and repeat successful ingestion to detect duplication. Tests retain source revision, working changes, binary digest, arguments, exit codes, and final-state evidence beneath the checkout's ignored build directory.

The source and release manifest are committed at fcc50beadb0f17c3e6238a86fa13dd4b1b031ede. All 11 recovery, projection, and query CLI journeys passed at that revision. The installed source recovery executable also passed all five recovery journeys. Candidate publication was refused with release_api.publishers declares no publisher for transcript-lake/; no candidate or stable package is claimed.

Production observation, 2026-09-15: the shared installer established the declared Stado stream service, which subsequently reported running. A real transcript-lake query comparison of an affected OMP source and its Oko projection found 200 user turns on each side. Their timestamp occurrence multisets matched: zero missing or unexpected occurrences and no invalid timestamps. This confirms that session's previously missing turns reached the projection; it does not attest every content field or the completeness of the entire archive. No vendor transcript or cursor was edited to obtain this result.