Invocation#
transcript-lake [--data-dir <path>] status [--json]Purpose#
Inspect Lake partitions, cursor health, live-stream state, and Oko freshness.
Inputs and options#
- No positional input is required or accepted.
--jsonemits the complete status object.
Output and state effect#
Read-only. Reports dataDir, partition files and bytes by runtime, cursor state, stream summary, and Oko freshness. Invalid cursor or stream state, and a failed stream, make the command non-zero. A stream is failed when it kept failed (its catch-up could not run, for example with no masking declaration) or when it started again while still carrying that failure as lastFailure, which it keeps until a catch-up completes; the line under the stream line then reads stream FAILED: <error>, so a stream its supervisor restarts after every failure reads as failing, not as catching up; an empty Lake is reported as zero state rather than created. A partition entry that cannot be read is not counted and is named under its runtime as not counted, cannot be read: <entry>, so a short count is never silent. The cursor line carries the tracked-file count only when a cursor store was read. A stream count the stream state does not carry is printed as not reported, not as zero: stream: <state>, updated <time>, files <n or not reported>, failures <n or not reported>.
A stream that still records catching-up carries the process doing the catch-up as process {host, pid, started}. When that process no longer runs on this host (its pid gone, or given to a later process with another start time), the catch-up never finished and no cursor advances, so the stream is failed with the catch-up started at <time> by stream process <pid> on <host> never finished: that process no longer runs, so no cursor advances, never shown as catching up. A catching-up record naming no process, or one whose process cannot be checked, is failed with that cause.
Exact refusals#
- Any positional argument is refused as
status accepts flags only. - An unrecognized
--watis refused asunknown status flag: --wat. - Repeating
--jsonis refused asstatus received duplicate --json.
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.