oko defects operations root

Invocation#

oko defects operations root DEFECT --root ROOT [--json]

Inputs and options#

• DEFECT and ROOT are defect ids or their short forms; ROOT is stored by full id. A symptom may itself be the root of another: a refusal follows the chain to the deepest root still open.

Output and state effect#

• Writes the root under the register lock and updates the open snapshot; a previous root and a statement that it blocks nothing are kept in the notes. oko work ranks the symptom as waiting on its root, so the root is worked first.
• When the root closes (fixed by a published release, or withdrawn), the symptom's functionality is let through to verify that closure: Tama lets the call through, the oko CLI runs the command, the native API runs the operation, and check lists the symptom under verify with the closure it verifies as receipt (<root>@<lifecycle event>, the root's newest fix or withdrawal). A run that fails after that closure proves the root's repair did not repair the symptom, and the symptom refuses the functionality again as the known fault it is. The failure is kept on the symptom as failedVerification {root, receipt, at, cause} in one state for every interface: Oko keeps it for a run of the CLI or the native API (a refusal of the invocation itself ran nothing and counts for nothing), and Tama reports a shell call it let through to the same state (`oko defects operations verification`: begun before the call, succeeded or failed with the result's first line), so every session and every argument spelling meets the same failure through the open snapshot. The refusal names the symptom, the root, the closure and the failure: `its root <root> closed (<receipt>), and the functionality failed after that at <time>: <cause>; the root's repair did not repair it`. check answers such a symptom among defects with failedVerification set, and Oko Desktop's check says the same. It runs again once the symptom itself is repaired or withdrawn, or once the root closes again (a new receipt, a new repair to verify). A run that succeeds keeps nothing, and the next call is let through as before.
• The closed root is the one that ends the symptom's chain, walked through open intermediate symptoms, on the CLI, the native API, the check and Tama alike. One call verifies one closure at a time: before a call Oko runs (the CLI or the native API) is let through to verify, the symptom keeps it as pendingVerification {root, receipt, since, pid}; a second call reaching that closure meanwhile is refused with `its root <root> closed (<receipt>), and process <pid> verifies that closure now, since <time>: one call verifies it at a time`, and the run's outcome takes the pending verification off (a failure is kept as failedVerification). A pending verification whose process ended without an outcome leaves the closure unverified: `the call that verified it (process <pid>, since <time>) ended without an outcome, so the closure is unverified: repair or withdraw this defect itself, or close the root again`. A closed root that holds no lifecycle event that fixed or withdrew it names no repair to verify and grants none: `its root <root> is closed but holds no lifecycle event that fixed or withdrew it, so no repair is named for a call to verify: record the root's closure again (oko defects repaired <root> or oko defects withdraw <root>), or repair or withdraw this defect itself`. check answers each of these among defects with verificationHeld set to that sentence, and Oko Desktop's check shows it.
• A verification that ran outside Oko is reported to the same state with `oko defects operations verification <id> --receipt <root>@<event> --pid PID [--session S] (--begin | --succeeded | --failed CAUSE | --released)` (native operation `verification` with reported {pid, session?, state: begin | succeeded | released} or {pid, session?, state: failed, cause}). The call is the process PID and, for a harness that runs the calls of more than one session, the session S whose call it is; pendingVerification keeps both. begin reserves the closure for that call under the register's lock, on the register as that lock holds it, so of two calls beginning one closure at once only one is kept and the other is refused naming it; begin is also refused when that closure's verification already failed, or when another call holds it (running, or ended without an outcome). Only the call that began it settles it: succeeded takes the pending verification off, failed keeps failedVerification with the failure's own words (a failure already kept for that closure stands), and released takes it off for a call that was refused before it ran, which verified nothing. A settlement from any other call is refused (`holds no verification of <receipt> by process <pid>`) and changes nothing. Every report is refused when <id> is no open symptom whose chain ends at a closed root, when that root holds no closure event, and when the receipt is not the root's current closure. Tama begins the verification, naming its harness and the calling session, before admitting the shell call: a begin Oko refuses refuses the call itself, and reservations already made for that call are released; Tama's admission refuses every call that is not the holding session's from the holding harness.
• A reservation the harness holds is the reservation of every program that harness's call runs: an oko command a shell call starts (Tama reserved that closure for the harness before admitting the call) reads it as its own call's, not as another process verifying, and runs; a failure of that oko command is kept as failedVerification in its own words, and the harness's settlement keeps that first failure rather than replacing it with the shell's first line. Whether the holder is this process's harness is read from the kernel's parent of each process up the chain.
• A verification Oko runs itself also keeps an invocation identifier in pendingVerification. Two native requests can share the resident service PID but never that identifier: each operation gets its own reservation, and a concurrent request in the same process is refused while the first verifies. Settlement must match the PID, session and invocation, so one request cannot clear another's reservation. Running, abandoned and mismatched-settlement diagnostics include the invocation. Older external reports omit it and keep their process/session identity; only an external harness reservation from a different ancestor process can be inherited by its child command.
• The operations qualification (`cargo test --test defects-operations` in oko's rust directory, against the candidate oko and Tama) proves each transition on an isolated register through the real CLI and Tama's real admission: while one admitted call that verifies a closure still runs, another ordinary caller of the same functionality is refused naming that process and runs no consumer; a run that fails after a root's withdrawal keeps failedVerification and the same caller, every other caller and a call of the same bound functionality with different matching arguments are refused with the root, the symptom and the cause shown, each with no filesystem effect of the consumer; a run that succeeds settles the closure; for a bound symptom whose root is an open intermediate with no binding of its own, whose root in turn is closed, the failure is kept against that deepest closed root's receipt and refuses the same three callers; and withdrawing the symptom itself lets its functionality through. Each case keeps the call's exit status, output, process and admission beside the source revision in the journey's report.
• A chain of roots that comes back to a defect already on it (written before this refusal existed, or by hand) establishes no cause: Tama refuses the call for the defect itself with `; its chain of roots loops (<a> -> <b> -> <a>), so no defect on it is an established cause and none is sent to: take back the wrong link with oko defects operations unroot <id> --reason <what shows it>`, the defect's own owner rules apply, check answers the row with root null and rootLoop {loop, unroot} — loop in whole ids, the same document Tama's admission carries — Oko Desktop's check says the same, and oko work ranks it as waiting on nothing.
• Every check of the chain is made on the register as the write's lock holds it, so two sessions naming each other's defect as root at the same moment write one link and the other is refused as leading back.

Refusals and safe exits#

• defect <id> cannot be its own root cause; name the open defect whose repair it waits on
• root cause <id> is closed; a closed defect causes nothing: verify <defect> again and bind what still fails, or name the open cause
• root cause <root> leads back to <defect> (<chain>): a symptom cannot cause its own cause
• root cause <root> sits on a chain of roots that loops (<chain>), so no defect on it is an established cause: take back the wrong link with `oko defects operations unroot <id> --reason <what shows it>` first
• defect <id> is closed; only an open defect is a symptom
• An unknown defect or root, or an unreadable register, is refused with its cause and nothing is written.

CLI reference#

• View the complete oko command tree