Skip to main content

Module latch

Module latch 

Source
Expand description

Latched completion / retained terminal state (EV7, epic #600).

First-class fan-out completion: a resource’s terminal value (task exit, model-load result, fd close/EOF, …) is retained host-side in a TerminalStore (the authoritative value, plaintext-at-owner — NOT the content-blind relay, NOT [crate::stream_info::StreamOpt::Retention]), and served to late watchers immediately while early watchers block on the EventService edge.

read_then_subscribe is the one helper that subsumes load --wait and the P9 /task/<id>/exit pattern under one shape: serve the retained value if present, else subscribe to the live edge and block until a terminal event arrives.

§Await contract

read_then_subscribe is a real awaitable Future — it .awaits crate::events::EventSubscriber::recv, which registers a waker with the runtime. It is NOT correct-only-under-poll-spin. A consumer that drives VFS futures via a noop-waker spin loop (e.g. the TUI chat_app.rs poll_local driver, being replaced with a real async driver in the workers/P9-task lane, epic #608) would busy-spin on a blocking read here — consumers MUST drive this with a real async runtime.

§Lane split (epic #600 vs epic #608)

This module is the generic EventService-side primitive. The concrete per-resource Mount-served files (/task/<id>/{exit,status,fd}) and the per-type terminal payloads (Exited(code)|Killed(sig)|Failed(reason), Loaded(handle)|LoadFailed, fd close/EOF) are owned by the workers/P9-task lane (epic #608): they instantiate TerminalState-style payloads, own a TerminalStore, and call read_then_subscribe. This crate provides only the generic envelope + store + helper + the await/liveness contracts.

Structs§

AllowAllTerminalAuthz
Permissive TerminalAuthz for a Public (plaintext) operational plane.
DenyAllTerminalAuthz
Fail-closed default TerminalAuthz until EV4 (#604). Denies all late reads — a watcher must subscribe before the edge to receive the terminal value live. Correct ZSP default; not a security gap (no plaintext is released to a late watcher the MAC hasn’t authorized).
Terminal
A latched terminal value — monotonic write-once. The owner of a resource latches exactly one of these when the resource terminates.
TerminalStore
Monotonic-write-once retained-terminal-state store — the authoritative, host-side, plaintext-at-owner value for each resource.

Traits§

ResourceKey
A resource identifier for a latched terminal value (e.g. a task id, a model load-attempt id). Cheap to clone/hash/compare.
TerminalAuthz
Authorization hook for a late read of a retained terminal value. The late-watcher file read must enforce the same MAC as the subscribe; until EV4 (#604) wires real MAC this is fail-closed — DenyAllTerminalAuthz denies every late read, so a late watcher cannot observe a retained value yet. An EARLY watcher (one that subscribes before the edge) is unaffected: it receives the live edge through the normal subscribe path (whose authz is separate).
TerminalState
Marker for a per-type terminal payload. Implementations live in the consumer (epic #608): task-exit, model-load, fd-close, … They carry their own value type; this trait only pins the “I am a terminal payload” contract so the store/helper stay generic.

Functions§

read_then_subscribe
Latched-completion read: serve the retained terminal for key if already latched (and authz permits the late read), else subscribe to the live EventService edge via subscriber and block until an event that classify identifies as terminal, then latch + return it.