Oko
Oko/Docs

Command reference

oko rulings unlinked

Reads every genuine operator message of one session or every session with a user event in Transcript Lake, with the task that carries it, a related defect, or an explicit attachment to existing work. A ruling is visible context, not a substitute for a task or defect. An unread message, or one read before the session's first task, is carried by none unless attached explicitly; the text form refuses while any such message has no work link.

Invocation#

Command
oko rulings unlinked (--session ID | --all) [--json]

Inputs and options#

  • --session uses Transcript Lake when it holds genuine operator turns, even if a shorter live file exists; otherwise it reads a live or stored source. Stored occurrences are reconciled by exact source time and complete body, or by an unambiguous legacy source second and body. --all enumerates Lake sessions and reads Lake itself for each; a stored snapshot cannot replace a Lake source that disappeared after enumeration. Every session-level refusal remains visible. --session and --all are mutually exclusive. Readings, explicit work links and task relations come from the shared database.

Output and state effect#

  • Prints one line per operator message: `#<n> <task identity> <explicit work | defect ends | carried by a task | ruling <id> only; no task or defect | unlinked> <first line of the message>`; the text form exits 0 only when every message has a current task or defect and otherwise refuses with the uncovered messages. With --json every row carries `ordinal`, `task`, `said`, `kind` (what the message was read as, `unread` until someone reads it), `carried`, `ruling` when recorded, `defects`, and `work` when explicitly attached. The JSON form returns uncovered rows as data; check `carried`, nonempty `defects` or nonempty `work`, not `ruling`. A recorded link to a task or defect that no longer exists refuses the audit instead of counting stale coverage.
  • The `task` field is the message's allocated identity, not necessarily the older task carrying a detail or correction; `carried` is true only after that derived task is present in the shared register.
  • JSON `said` is the complete masked operator message, not just its first line, so a historical correction or question can be read before attaching it. The text CLI abbreviates each row and refusal to the first line. The Desktop session and whole-Lake views display the complete words from that same report.
  • A model-assessed reflection defect is another genuine `defects` end only when its original Lake timestamp and complete masked body uniquely identify this operator turn. `oko reflection scan --session ID` restores the source timestamp on older reflection entries without rejudging or changing their defect. Pending reflections do not count as work. A repeated same-time/body occurrence or a reflected defect absent from the current register refuses instead of silently claiming coverage.
  • Oko Desktop → Rulings → Operator messages and their records shows each session message's reading, task or defect, explicit work links and any ruling; it offers Read as with Oko's declared kinds, Attach and Remove work link, read-only Derive ledger and explicit Store derived ledger. It also offers Audit Transcript Lake / Store Transcript Lake ledgers and Audit all Lake message links, with per-runtime counts, per-session failures and uncovered message numbers. A successful write followed by a failed link read names that partial result. Editing the session clears stale links, derivation and errors; actions are locked while an operation is in flight.
  • With --all, text lists each uncovered session/message and prints exact audited session and message counts and, for each Lake runtime, audited/linked/unlinked totals. JSON returns `{source, sessions, auditedMessages, byRuntime: {runtime: {auditedMessages, linked, unlinked}}, unlinked: [{session, link}], failed: [{session, refusal}]}`. Runtime totals count successful sessions only; a failed session remains named in `failed` and its runtime has no audited messages from that session. Either format refuses if any message is unlinked or any session could not be read, after printing the report for inspection. Lake's user-event inventory is checked again after the pass; a changed source appears as a failure rather than a false complete result.
  • The isolated real linkage journey under `tests/rulings/` requires a signed-in host, the shared database and `OKO_TEST_SOURCE_REVISION` matching a clean committed candidate. Run `cargo test --manifest-path rust/Cargo.toml --test rulings-unlinked an_operator_message_linked_to_nothing_is_named_until_it_is_linked -- --ignored --nocapture`. It creates its own session, records task and defect links through the CLI, verifies persisted read-backs and meaningful refusals, then removes the explicit links. Source revision, binary and test digests, commands, actual exit statuses and output stay under the checkout's ignored build directory.

Refusals and safe exits#

  • `oko rulings unlinked requires --session <text>` without --all; an unknown flag names --session and --all; `--all` with --session refuses as mutually exclusive. If no source has a named session, `session <id> has no operator messages anywhere it was looked for` names the stored ledger, live roots and Transcript Lake; an unreadable stored message or Lake answer names its source and cause; a divergent live transcript names the first mismatched ordinal and both sources.
  • Multiple source occurrences with the same second and complete body, a missing time, a changed or masked archived body, or a stored turn absent from Lake refuse rather than guessing which reading belongs to which turn; an unreconciled timestamp identity names the original source and the derive --write command; `read ledger for session <key>: …` names the table that could not be read. A derived task without a current oko_tasks row is not coverage: the refusal names that task and `oko tasks derive --session <id> --write`. A relation read failure says whether the source or destination selection failed for the named session and retains the database cause; long sessions are split only on the database's URI-too-long refusal. A stale explicit work link or relation names the missing current task or registered defect, and a message identity absent from the original source refuses rather than counting false coverage.
  • A defect relation from a message identity that is no longer a persisted root task refuses with the message identity and defect end; a relation row alone is not current task coverage. A short defect end shared by several registered defects is not treated as coverage for either: its relation is refused rather than picking one.
  • Without --json, unlinked messages are named with their reading and any ruling-only context, plus commands to read as a task, add it as a task, attach to existing work or relate its task to a defect. With --all, an absent or conflicting Lake session/runtime identity refuses before scanning; each failed session and cause appears in the output; an uncovered message or failed session refuses in either format.

CLI reference#