Transcript Lake

Documentation / Concepts

Concept: canonical event

A canonical event is the smallest durable unit in Transcript Lake: one masked, provider-neutral observation serialized as one NDJSON line.

A canonical event is the smallest durable unit in Transcript Lake: one masked, provider-neutral observation serialized as one NDJSON line.

Its frozen field order is ts, runtime, machine, session_id, project, event_type, text, tool_name, model, tokens_in, tokens_out, extra. Nullable fields preserve absence rather than inventing values. text is the masked text the runtime recorded, or null when it recorded none, such as a metadata record or a tool call without arguments; partitions written by earlier releases hold an empty string there instead. extra is an object.

The seven event types are:

  • user and assistant: conversation turns;
  • thinking: reasoning material exposed by the runtime;
  • tool_call and tool_result: tool boundary records;
  • meta: session/runtime metadata that is useful without becoming conversation text;
  • hook_decision: a Tama policy-hook decision.

The runtime-native session_id is the conversation identity. The same spelling from two runtimes is disambiguated by runtime. extra.source_stem_hash is a one-way bridge to file-oriented indexes without retaining the source filename stem.

Jeden execution receipts are meta, not extra user messages or duplicate conversational tool calls. The adapter retains their payload in text and the recorded eventId, parentId and sequence in extra. When present, extra.recordType, operationKind, operation, requestEvent and status keep the structured execution coordinates. Model inputs and returned conclusions, tool arguments, actual outputs and failures pass through the same masking boundary as every other event. Missing metadata payload stays absent, not an invented empty answer.

A result names its actual request. Native Jeden tool results use requestEvent; older ledgers keep their recorded parent link. Canonical tool boundaries use extra.tool_call_id. A projection row UUID cannot supply a missing call identity. An execution request with no recorded terminal outcome remains unfinished evidence.

transcript-lake sources --json
transcript-lake adopt --source jeden --root <exact-discovered-root> --json
transcript-lake events --runtime jeden --type meta --json

The maintained native tracking adoption journey is stado product cargo test --manifest-path Cargo.toml --test harness-ingestion jeden::native_execution_survives_adoption -- --ignored --nocapture. Set LAKE_TEST_TRACKING_CAPTURE to the genuine tracking-capture.json generated by Jeden's real tests/tracking/journey.mjs execution, retain its native journals, and supply the normal TRANSCRIPT_LAKE_SECRET_FORMATS declaration and the harness evidence/source inputs. The journey invokes the real adoption and inspection CLI, checks completed and refused reads, execution-payload conservation, model decisions, repeated-adoption stability and an undiscovered-root refusal. Source journals remain read-only; commands, exit statuses and actual persisted partitions stay in its isolated build evidence directory. A handwritten transcript is not a substitute for the native execution.

Events are immutable after append. They are sensitive even when masked: time, machine, project, tools, model, ordinary text, and short nonmatching secrets can remain.

See masking, partition, and the full schema.