transcript-lake [--data-dir <path>] adopt \
--source <runtime> \
--root <discovered-root> [--json]Inputs#
--source and --root are required exactly once. The canonicalized root must equal a root returned for that runtime by sources. Symlink aliases, arbitrary archives, individual transcript files, hook telemetry, and unrecognized runtime names are refused.
Supported inputs are the established native stores of every runtime in the installed adapter registry. Choose the runtime and root from sources --json; the ingestion reference describes line journals, whole documents and read-only databases. This command does not define a generic interchange format.
Atomic validation#
Before mutation, every discovered candidate must resolve inside the selected root and be an adapter-owned file or whole-session directory. Whole-store readers validate their documents or databases by loading them. Every complete nonempty JSONL line must be a JSON object; adapters that define a closed record-type contract reject unsupported kinds, while extensible adapters may preserve or ignore unknown kinds. The root must yield accepted events. Malformed complete records reject adoption. An unterminated final line is not consumed and is counted as pending so a live writer can finish it later.
After preflight, the normal writer lease, masking, canonical partition, cursor, and Oko projection code ingests the source. The selection is written only after the destination accepts either new canonical events or verified unchanged files. Invalid input does not mark onboarding complete.
Duplicates and retained state#
The stable source id is derived from runtime plus canonical root. Existing Lake partitions and earlier source declarations are preserved. Unchanged sources are idempotent. Modified sources verify their consumed prefix before resuming; replaced or truncated files and legacy cursors replay through masking without duplicating retained canonical occurrences. Missing Oko rows are restored. An interrupted recovery keeps its old cursor and repeats that comparison on the next invocation. The selected id and all adopted declarations remain in LAKE_DATA/sources.json. Once selected, stream follows only that exact source instead of every discovered root; adoption is not an all-runtime repair command.
Result#
Human output names the source, status, runtime, root, imported/unchanged files, and imported events. --json additionally returns candidateFiles, candidateEvents, pendingIncompleteLines, selected, and dataDir. Every count is the one ingestion reported: an ingestion summary missing filesImported, filesUnchanged or eventsImported is refused naming the count, and the selection is not changed. Transcript text and credentials are never printed.
Failures#
Missing flags, duplicate flags, unknown runtime, absent or non-discovered root, empty source, unreadable file, path escape, malformed JSON, unsupported record type, writer-lease conflict, masking/write failure, or a selection-registry failure exits non-zero. The error names the path or contract that failed.
The same operation is available during first use as transcript-lake onboarding --source <runtime> --root <path>. --skip-source keeps an empty usable Lake and records no source fact.