Oko
Oko/Docs

Command reference

oko tasks derive

Derives the operator's messages and tasks from one named session (Transcript Lake before a local live copy), an explicitly named transcript, or every session with a user event in Transcript Lake, bound to canonical identity allocations. Every derive reads the signed-in member's shared database; --write also stores messages and tasks.

Invocation#

Command
oko tasks derive (--session ID | --transcript PATH | --all) [--write]

Inputs and options#

  • --session names a live or archived session and prefers its nonempty Lake source, so a shorter local copy cannot hide archived turns; --transcript names an explicit original file and may be paired with --session; --all enumerates Lake sessions and cannot be combined with either. --write explicitly persists the derived ledgers.

Output and state effect#

  • Prints the derived ledger as JSON, including transcript/runtime for an explicitly selected file or source for a named session; with --write, upserts its messages and tasks. For an archived session whose historical numbering differs, a stored occurrence retains its identity under the canonical Lake ordinal; new Lake turns receive their own identities. Oko Desktop → Rulings → Operator messages and their records offers the same read-only derivation and explicit store action through the native API, displays source, unread/unattached ordinals and stored counts, and rereads the message links afterwards.
  • With --all, the CLI and Oko Desktop enumerate Lake sessions and read Lake itself even when a local live transcript is older than the archive. They return the Lake session count, succeeded session count, derived message count, unread and unattached counts, `byRuntime` message/unread/unattached totals from successfully derived sessions, write mode and every `{session, refusal}`. A failed session does not hide subsequent sessions or contribute to the runtime totals; the CLI prints this report and exits nonzero if any session refused. The corresponding Audit all Lake message links in Rulings checks actual task/defect linkage, rather than treating derivation or classification counts as proof of complete coverage.
  • The shared writer compares the complete text fingerprint as well as message identity. A corrected body is persisted even when the native UUID and first line did not change; unchanged bodies are not downloaded or rewritten for this comparison. To promote a corrected live original while Lake still holds an older copy, run `oko tasks derive --session <session-id> --transcript <path-to-original-transcript> --write`, then read the complete message before classifying it again. Refresh does not itself authorize a different classification.
  • The canonical schema must provide the generated `oko_operator_messages.content_digest` column before this writer is deployed. This is a schema and application release dependency, not permission to reset the catalogue or replace message identities.
  • Timestamp-backed messages without native turn IDs use full source precision. A retained whole-second time is matched to the original live or Lake occurrence when its source second and complete body identify a unique unmatched turn; a previously reconciled timestamp is bound by its exact source time and body first, even when another identical message shares its second. A body that the stored rows and the original both hold equally often in one source second pairs in order: the lowest stored number takes the earliest unmatched original occurrence, so the two sides fall in lockstep. The writer then retains that precise source time under the old allocated identity. Existing task IDs, instruction parts, evidence, verdicts and qualification receipts keep their allocated owner. A changed or masked archived body, a body the stored rows hold a different number of times in one source second than the original does, or a missing original occurrence refuses instead of transferring an identity. Different full bodies in the same second are independently matched. Native UUID identities remain unchanged.
  • With --write, Oko first reconciles the retained original source and stores durable allocations separately from the message projection. The original source may be selected with `oko tasks derive --session <session-id> --transcript <path-to-original-transcript> --write`. For an archived session, read-only derive refuses a retained timestamp origin that is not yet reconciled; `--write` can select the original Lake occurrence and reconcile it before reading classifications. This metadata preparation does not upload unchanged message bodies. Deleting a projection does not erase its identity allocation.
  • Deploy the canonical identity-origin, allocation, legacy-owner, part-binding and reconciliation migrations with the matching application release. The registry also binds classifications and instruction parts recorded before the message body was stored. Historical part numbers are reconstructed from their existing task hashes, not from row order or a column default.
  • The ignored real archive qualification `readings-stored-only` includes `precise_archive::precise_occurrences_keep_distinct_allocations` and takes OKO_TEST_PRECISE_ARCHIVE_SESSION and OKO_TEST_SOURCE_REVISION. Its genuine stored Lake fixture has two identical bodies in one second with distinct precise instants. Run `cargo test --manifest-path rust/Cargo.toml --test readings-stored-only precise_archive::precise_occurrences_keep_distinct_allocations -- --ignored --nocapture` on the committed candidate. The CLI read-only derive and linkage audit must retain both allocations without rewriting the stored ledger; commands, exits, source revision and digests remain in the ignored build directory. A fixture without that pair is refused, not a pass.

Refusals and safe exits#

  • `oko tasks derive requires --session <id> or --transcript <path>`; without a live file, a session absent from both the stored ledger and Transcript Lake refuses with every source it looked for; a divergent live copy or ambiguous archived source second and body refuses instead of silently replacing a reading; the shared database refusals of `oko database check`, including read-only derive.
  • With --all, an unknown flag or a concurrent --session/--transcript is refused rather than silently ignored. Per-session failures appear in the final report and make the CLI nonzero; the native UI retains them beside the counts. The Lake inventory refuses a missing session/runtime identity or one session assigned to different runtimes rather than misattributing its totals. The user-event inventory is read again at the end: if Lake gained or lost a turn while the pass ran, the report refuses the changed source rather than claiming a complete snapshot. A read-only pass cannot reconcile legacy timestamp identities; --write requires the original live or archived source and may still refuse ambiguity.
  • A missing content_digest column retains the database's operation and cause. A malformed stored fingerprint row refuses as `reading stored message fingerprints of session <id>: <cause>` before message writes; it is not treated as a missing message.
  • A repeated task identity refuses before database writes. The cause names the session, every colliding identity and each source message number, complete timestamp and parent when present. An absent source timestamp is stated explicitly. Distinct fractional timestamps are not rounded in this diagnostic; they are evidence of separate source occurrences, not permission to discard a message or move an existing task's evidence to the first occurrence.
  • Read-only derive refuses an unreconciled timestamp projection or a retained reading, addition or task without an allocated original source. The error names the session, message number and retained reference when present. Replay the original source with --write; a rounded stored timestamp is not a substitute.
  • Reconciliation refuses missing source occurrences, original occurrences of one body in a rounded second that the stored rows hold a different number of times, conflicting root/part/reading ownership, or identical full timestamp and text without a native turn ID. Outside equal counts paired in order it never chooses the first or last occurrence. The reconciliation transaction leaves allocations unchanged on refusal; an older partial capture cannot erase a retained occurrence.

CLI reference#