Transcript Lake

Documentation / CLI

transcript-lake reconcile

Supersede canonical rows that the current adapter projects differently from their retained original.

Invocation#

sh
transcript-lake [--data-dir <path>] reconcile --source <runtime> [--apply] [--reindex]

Purpose#

Canonical partitions are append-only, so rows written before an adapter correction keep the old projection: a provider notice recorded as an operator turn stays one, and Oko imports it as one. reconcile replays every retained original of one runtime through the current adapter and masker into a staging root under the Lake, compares each source partition with what the replay wrote, and with --apply puts the replayed partition in place of each one that differs. The original, not the recorded text, decides every row.

Inputs and options#

  • Required --source <runtime>: one transcript runtime of the adapter registry. Its originals are read from the roots transcript-lake sources lists for it on this machine.
  • --apply: replace every changed partition. Without it nothing in the Lake changes and the report is a preview.
  • --reindex (only with --apply): after the Oko projection is rebuilt, run oko-cli transcripts reindex (or the program OKO_CLI names) so Oko imports the corrected rows; its output goes to stderr.
  • Global --data-dir selects the Lake to reconcile.

Output and state effect#

Prints one JSON document: runtime, the staging replay summary, applied, and partitions with unchanged (a count) and three lists, each entry naming the partition file, its sessions and rowsRecorded:

  • changed: the replay projects the source differently. rowsSuperseded recorded rows no longer follow from the original; rowsReplayed rows do that were never recorded. A corrected sender shows as one of each.
  • unprovable: no retained original on this machine reproduces the partition (the source file is gone or lives under a root this machine does not list). Its rows stay exactly as recorded and are never reclassified from their text.
  • refused: the partition holds rows recorded on another machine (machines), which this machine's original cannot stand for. It is never rewritten.

The whole run holds the Lake's writer lease, so the stream cannot append between the comparison and the replacement. --apply renames each replayed date file over its predecessor (a date the replay no longer writes is removed), gives every source of the runtime the replay's cursor so the stream resumes after what the partition holds, removes the runtime's Parquet mirror (parquetMirrorRemoved; compact writes it again) and rebuilds the Oko projection from every partition (projection). An interrupted apply is completed by running it again: each file is replaced whole, so no row is written twice. The staging root is removed in every case.

Exit 1 when a partition is unprovable or refused or the replay could not read an original; exit 0 when every partition was proved against its original.

Exact refusals#

  • Missing runtime: reconcile requires --source <runtime>.
  • Hook telemetry: reconcile replays transcript originals; hooks segments are immutable and content-addressed, so no projection of them can be superseded.
  • --reindex alone: reconcile --reindex needs --apply: only an applied correction changes what Oko imports.
  • An unsupported --source is refused with the runtimes of the adapter registry, as rebuild refuses it; a positional argument as reconcile accepts flags only.
  • A writer already holding the Lake: the lease refusal names it, and nothing is read or written.
  • --apply when the replay was partial or a partition is refused: nothing is replaced, and the report carries applyRefused with the reason; the files the replay could not read are named on stderr.
  • A canonical partition line that is not an event: canonical partition <path> holds a line that is not an event (<cause>): <line>; nothing is replaced.
  • Without oko-cli: oko-cli is not on PATH and OKO_CLI names none; the corrected projection is written, and `transcript-lake projection refresh --target oko` hands it to Oko.

All long flags are exact and single-use. Global --data-dir may appear anywhere in the invocation, must appear once, and selects an absolute root.

Back to the complete CLI command tree.