Transcript Lake

Documentation / CLI

transcript-lake projection

Reconstruct the per-session projection one consumer imports from authoritative Lake partitions, or hand the current projection to that consumer's own CLI; the consumer is an adapter behind the operation.

Invocation#

sh
transcript-lake [--data-dir <path>] projection <rebuild|refresh> --target <oko> [--reindex]

Purpose#

projection rebuild --target <consumer> reconstructs every per-session projection that consumer imports from the authoritative Lake partitions; the live stream owns incremental updates, and this is the recovery path. projection refresh --target <consumer> hands the projection as it stands to the consumer through its own CLI. The consumer is a replaceable adapter behind the one operation: oko is the target that exists today, and a --target without an adapter is refused with the targets that exist.

Inputs and options#

  • The verb, rebuild or refresh, is the first word; no other positional input is accepted.
  • --target <consumer> is required on both verbs. For oko the projection is the per-session JSONL under LAKE_DATA/exports/oko, and refresh runs oko-cli transcripts reindex (OKO_CLI names the executable; otherwise it is searched on PATH).
  • --reindex, on rebuild only, asks the consumer to reindex after reconstruction; without it the consumer is not invoked.
  • rebuild requires the single state-writer lease.

Output and state effect#

rebuild mutates the consumer's derived export and staging data, preserving canonical partitions and cursors. It always writes a JSON summary with output root, session/record counts, written/unchanged/pruned counts, mode, malformed count, and duration. With --reindex, it returns non-zero unless the consumer both ran and exited zero. refresh writes nothing of its own: it runs the consumer's reindex command and returns that command's exit status.

Exact refusals#

  • A missing verb is refused as projection requires rebuild or refresh; another word as projection takes rebuild or refresh, not <word>.
  • A missing target is refused as projection rebuild requires --target <oko> (and the same for refresh); a target without an adapter as no projection target is named <target>; the targets are oko.
  • Malformed authoritative rows: full Oko export refused malformed Lake rows; authoritative partitions were not modified.
  • Writer contention is refused as state writer lock is held by <host> pid <pid>.
  • A positional argument after the verb is refused as projection rebuild accepts flags only; unknown or duplicate flags use the exact parser forms unknown projection rebuild flag: --wat and projection rebuild received duplicate --reindex.
  • refresh without a consumer CLI prints oko-cli is not on PATH; install Oko or set OKO_CLI, then run: oko-cli transcripts reindex and exits 1.

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

Back to the complete CLI command tree.