Expand description
Client-facing subc channel-0 control wire shapes.
This crate is the client ↔ subc control-plane boundary. It depends only on
[subc-protocol] for shared primitives such as RouteTarget and
BindIdentity; clients can use it without depending on the
daemon implementation.
Modules§
Structs§
- Activity
Actor - Verified identity stamped by the daemon, not supplied by a recording module.
- Activity
Cursor - A live-feed position. Query continuation positions are sequence numbers only.
- Activity
Entry - One durably appended event.
previs reserved for a future hash chain and is deliberately absent from this format. Identity is (daemon_incarnation, seq), and entries are ordered by seq rather than by their wall-clock timestamps. - Activity
Query Request - Filter a newest-first scan.
cursoris exclusive: only lower seqs follow it. - Activity
Query Response - A page plus the current incarnation’s head at scan capture, even on an empty page. Subscribe from head to move from the scan to live entries without a gap.
- Activity
Record Request - Report an event. Shape checking lives here; kind, size, ownership and rate validation remain the daemon’s responsibility. There is no actor field.
- Activity
Record Response - Sent only after the assigned sequence has been durably appended.
- Activity
Route - A route binding owned by the recording module, checked at this epoch.
- Activity
Scope - A live scope owned by the recording module, checked at this epoch.
- Activity
Subject - A short typed pointer, never a secret value.
- Activity
Subscribe Request - Replay after since and remain open for live entries. A refused or lagged feed ends with an Error frame carrying one of the activity refusal-code constants.
- Activity
Subscribe Response - One successful append delivered on the subscription’s correlation id. There is no separate acknowledgement; each response is one streamed entry.
- Agent
Command Resources - Commands attributed to agents rather than to the module that launches them.
Construct with
AgentCommandResources::newand its builders, not a struct literal. - AppOpen
Reply - A successful
app.openreply. - AppOpen
Request - Ask the daemon to start the operator app named
app. - Busy
Gauge Reading - A declared busy gauge’s last reading from the daemon’s health cache.
- Capability
Requirement Status - Catalog
Entry - A registered module’s catalog projection.
- Catalog
Watch Request - Channel-0 subscription request, framed like
activity.subscribe. It stays outside the exhaustive control enums; defining it does not advertise the op. - Catalog
Watch Response - One channel-0 subscription response on the request’s correlation id, with
RESPONSE and MORE set, like
activity.subscribe. There is no separate ACK: the first push carries the current generation, then advances may coalesce. - Child
Resource Reading - One reading of a module process’s memory and CPU time.
Use
ChildResourceReading::newand its builders so future fields stay additive. - Claim
- An opaque bearer claim. Debug output is always redacted, including when a containing request or reply is formatted. Never log the serialized body or exposed value, or put the claim in argv or an environment variable.
- Claim
Mint Reply - One single-use 128-bit base64url claim, redeemable for 30 seconds on the daemon’s monotonic clock. The wall-clock expiry is informational only; readers must not use it to decide that a claim is still valid.
- Claim
Mint Request - Mint only over the spawn’s live primary registration channel. Claim-bound connections cannot mint. Refusals never permit falling back to direct.
- Claim
Present Reply - Acceptance of a single-use claim. Refusals use an ERROR frame, never this ACK.
- Claim
Present Request - The first frame after a new connection’s handshake. Acceptance consumes the claim and binds the connection atomically while rechecking the live spawn. Any refused presentation closes the connection, including a retryable refusal; it never continues as direct.
- Claim
Rate Limited Detail - Backoff carried in
crate::ErrorBody::detailforclaim_rate_limited. - Connection
Describe Reply - The daemon’s current view of the caller’s connection.
- Connection
Describe Request - Ask the daemon what it knows about this connection.
- Consumer
Identity - Daemon-spawned consumer identity presented on route.open.
- CpuLast
Hour - CPU used between the retained wall-clock samples, not a percentage.
Construct with
CpuLastHour::newand its builders, not a struct literal. - Daemon
Build Provenance - Build metadata embedded in the daemon binary.
- Daemon
Observed Process - Runtime process facts observed for the daemon itself.
- Daemon
Resources - The daemon’s own process, excluding CPU of its reaped module children.
Construct with
DaemonResources::newand its builders, not a struct literal. - Live
Spawn - One process present in an atomic supervisor spawn snapshot.
- NotReady
Reason - Why a registered module is not accepting new route binds.
- Ordered
Json Object - Ordered JSON members retained for an unknown tagged value.
- Pending
Reload Verdict - Independent comparisons of configured path, launch spec and running image at list time. An absent verdict means the daemon predates this field, not agreement.
- Process
Group - A live program group, ordered by descending memory in a tree reading.
CPU is funded attributed credit of its currently live identities; the row
additionally retains retired work. Groups never exceed their row’s CPU.
Construct with
ProcessGroup::newand its builders, not a struct literal. - Rescan
Expect - What must still match for the daemon to accept an apply of this preview, so the apply does what the preview described.
- Rescan
Module Action - One module’s entry in a candidate preview.
- Route
Open Reply Ext - Optional reply keys kept beside, rather than inside, the exhaustive
RouteOpenvariant so existing emitters and readers need no source changes. - Route
Open Request Ext - Optional request keys kept outside the exhaustive
RouteOpenvariant so existing construction sites and destructures remain source-compatible. SDKs send these keys only after observingROUTE_CLOSE_REASONS_CAPABILITY. - Route
Open Target - Daemon-attested target facts. Spawn-only keys are ignored for all other kinds, which are always unmarked. Incomplete targets decode as absent in the reply.
- Scope
Ref - An owner-qualified scope reference, without selecting an epoch.
- Scope
Served ByReply - Volatile bind history in one daemon incarnation; unknown never means served.
- Scope
Served ByRequest - Ask about an epoch owned by the registered module sending the request.
- Scope
Watch Push - A terminal event delivered at most once per selector within one watch.
- Scope
Watch Request - Open an immutable set of at most 256 scope epochs on channel zero.
- Scope
Watch Response - Initial nonterminal RESPONSE, followed by lifecycle STREAM_DATA pushes.
- Scope
Watch Selector - One epoch whose lifetime the caller wants to observe.
- Scope
Watch State - One entry in the initial snapshot, in request order.
- Script
Module Status - Content identity is separate from the runner executable’s identity.
- Spawn
Cursor - A daemon-incarnation-scoped position in the supervised spawn event stream.
- Spawn
Event - One retained or live spawn event.
- Spawn
Snapshot - Atomic live-process census and the cursor at which it was observed.
- Staged
Generation - Names one state of the daemon’s staged configuration. The counter alone is not enough: it starts again at zero when the daemon restarts, and a restarted daemon may hold different staged specs under the same number.
- Stderr
Tail - A module’s retained stderr, oldest entry first.
- Subtree
Reading - A report-only memory reading of a module’s process container.
- Supervisor
Daemon Provenance - Daemon provenance paired with its runtime process observation.
- Supervisor
Entry - A supervised module’s current state and process observations.
- Supervisor
Health Entry - Supervisor
Module Provenance - Source-tagged provenance for one supervised module.
- Supervisor
Module Provenance Ext - Optional entry keys kept outside the exhaustive provenance struct so older construction sites and destructures remain source-compatible.
- Supervisor
Observed Process - Process facts observed by the daemon for a supervised module.
- Supervisor
Pending Field - A configured value that rescan has read but has not applied.
- Supervisor
Pending Module - Supervisor
Rescan Result - Supervisor
Route - One live consumer route in a
SupervisorRouteModule. - Supervisor
Route Module - Live routes served by one module.
- Terminal
Entry - One terminal child exit and the supervisor action it selected.
- Terminal
History - Bounded terminal history for one module, oldest retained record first.
- TreeOwn
- The module root’s attributed share, funded from the module row like groups. Root plus emitted child-group CPU and memory shares never exceed their respective module-row totals.
- Tree
Reading - Cumulative CPU and current memory of a module and its descendants.
Construct with
TreeReading::newand its builders, not a struct literal.
Enums§
- Activity
On - Exactly one citation from which the daemon resolves the actor.
- AppOpen
Status - What an
app.opencall did. - Catalog
Origin - Evidence-backed program origin. Unknown strings establish no recognized origin.
- Child
Memory Kind - What
ChildResourceReading::memory_bytesmeasures. - Child
Resource Unavailable Reason - Why a module process’s resources could not be read.
- Child
Resource Usage - A module process’s memory and CPU time as read at list time, or why none could be read.
- Claim
Purpose - The authority requested for one additional connection. Only a prefix claim carries a module id. The daemon checks its grammar and that the minting module owns the longest matching reserved prefix, excluding exact reserved or gated ids and prefixes without an owner.
- Client
Control Push - Daemon-originated channel-0 control push body.
- Client
Control Request - Client-originated channel-0 control RPC body.
- Client
Control Response - subc’s channel-0 response body for client control RPCs.
- Launch
Spec Agreement - Comparison of the configured launch inputs with the inputs recorded at spawn. No digest or configured env values are sent to clients.
- Launch
Spec Unavailable Reason - Module
Declared Provenance - A module’s declared build metadata, if its HELLO manifest carried it.
- Module
Protocol - Which wire protocol a supervised module speaks to subc, as DECLARED in daemon config. Never inferred from observed behaviour.
- Ordered
Json Value - JSON values whose object members retain wire order at every depth.
- Pending
Module Apply - When a module-entry edit can take effect without changing rescan semantics.
- Poll
Kind - Registration
Method - How a running supervised spawn registered. Unknown future methods confer neither channel registration nor nonce registration.
- Reload
Path Agreement - Whether the running process was spawned from the currently configured program.
- Reload
Path Unavailable Reason - Why configured and spawned paths cannot be compared.
- Rescan
Module Action Kind - What applying a candidate would do to one module.
- Resource
Bound - Exact counters omit this member; uncontained or ambiguous CPU is a floor.
- Route
Close Reason - Why subc is closing a module’s client routes.
- Route
Open Target Kind - A target kind unknown to this reader never establishes a supervised spawn.
- Running
Image Agreement - Whether the executable currently running agrees with the spawned image.
- Running
Image Evidence - Platform-specific evidence used to compare a running image with its spawn path.
- Running
Image Unavailable Reason - Reasons why an executable identity could not be observed.
- Scope
Served ByAnswer - Only
Servedestablishes that the target acknowledged a scoped bind. - Scope
Watch Event - Terminal lifecycle transition for the watched epoch.
- Scope
Watch Status - Current state of a requested epoch; unknown never establishes liveness.
- Spawn
Event Kind - Fact observed by the supervisor when a child process starts or exits.
- Stderr
Capture State - Whether stderr is being captured for a module, and if not, why not.
- Stderr
Tail Entry - Subtree
Source - The measurement behind a module’s memory including child processes.
- Supervisor
Health Status - Supervisor
Route Consumer - The identity tier the daemon can honestly report for a route consumer.
- Terminal
Disposition - The supervisor disposition selected after observing a terminal exit.
- Terminal
Exit Kind - Exit classification carried by supervisor history and census records.
- Tree
Source - The measurement behind cumulative tree resources.
Constants§
- ACTIVITY_
ACTOR_ UNKNOWN - ACTIVITY_
CURSOR_ INCARNATION_ MISMATCH - ACTIVITY_
CURSOR_ TOO_ OLD - ACTIVITY_
KIND_ FORBIDDEN - ACTIVITY_
LEDGER_ CAPABILITY - Advertised in HELLO_ACK and server.describe before activity operations are used.
- ACTIVITY_
MALFORMED - ACTIVITY_
RATE_ LIMITED - ACTIVITY_
READ_ FORBIDDEN - ACTIVITY_
SUBSCRIBER_ LAGGED - ACTIVITY_
TOO_ LARGE - ACTIVITY_
UNAVAILABLE - APP_
NOT_ INSTALLED - Refusal code for a known app that is not installed where the daemon looks.
- APP_
OPEN_ DISABLED - Refusal code when the platform supports
app.openbut this daemon build has it switched off. - APP_
OPEN_ ERROR_ CODES - Every
app.openrefusal code, in the order the daemon checks them. - APP_
OPEN_ NOT_ USED - Refusal code on a platform that never launches apps through the daemon.
- APP_
UNKNOWN - Refusal code for an app id the daemon does not know.
- APP_
VERIFICATION_ FAILED - Refusal code for an installed binary that failed the daemon’s checks. No process was started.
- CONFIG_
CHANGED_ SINCE_ PREVIEW - Refusal code for an apply whose
expectno longer matches the daemon: the file it reads hashes differently, or the staged generation has moved since the preview (another rescan with module changes ran, even one that failed partway, or the daemon restarted). Nothing was applied. - REGISTRATION_
CHANNEL_ UNSUPPORTED - Admission refused because a gated module lacks channel support. This reason spends no restart budget; restarting cannot repair a missing declaration.
- RESCAN_
CANDIDATE_ MAX_ BYTES - The largest candidate text, in bytes, a preview accepts. A daemon config file is a few kilobytes; the cap bounds what one request can make the daemon parse.
- RESCAN_
CANDIDATE_ PREVIEW_ CAPABILITY - Advertised in
server.describeby a daemon that servessupervisor.rescan_checked. A client sends that op only when this is listed: an older daemon refuses the unknown op, so a client that skipped the check would fail closed rather than preview the file on disk. - RESCAN_
CANDIDATE_ TOO_ LARGE - Refusal code for a preview whose candidate is longer than
RESCAN_CANDIDATE_MAX_BYTES. - ROUTE_
CLOSE_ REASONS_ CAPABILITY - Capability required before sending
accepts_close_reasonsonroute.open. - SCOPE_
SERVED_ BY_ OP