Skip to main content

subc_protocol/
lib.rs

1//! subc wire contract.
2//!
3//! This crate is the single source of truth for the subc <-> module wire,
4//! shared by subc-core and AFT. It defines the **envelope** (the fixed
5//! 21-byte routing header subc splices on), the canonical subc-generated body
6//! schemas such as [`ErrorBody`], and the capability manifest. JSON-RPC request
7//! and response bodies remain module-owned opaque payloads to subc.
8//!
9//! Config-gate bodies expose `subc-config` types in the public API: a breaking
10//! `subc-config` release is a breaking `subc-protocol` release.
11//!
12//! ## The envelope (locked — see docs/subc-core-architecture.md §4.8)
13//!
14//! ```text
15//!  offset  size  field     type    purpose
16//!    0      4    len       u32     # of BODY bytes after this 21-byte header
17//!    4      1    ver       u8      envelope version
18//!    5      1    type      u8      frame kind (see FrameType)
19//!    6      1    flags     u8     bit0 BINARY · bits1-2 PRIORITY · bit3 LAST · bits4-5 ADMISSION · bit6 DAEMON_ORIGIN · bit7 SUBSCRIPTION
20//!    7      2    channel   u16     route = (component, session); 0 = subc itself
21//!    9      4    epoch     u32     per-slot binding epoch; 0 on channel 0
22//!   13      8    corr      u64     correlation id; CANCEL carries the target call's corr
23//!   21 -> body
24//! ```
25//!
26//! Little-endian (same-machine, native, no byte-swap on the hot path).
27//!
28//! **Frozen prefix (the versioning invariant):** `len` (u32 @ 0) and `ver`
29//! (u8 @ 4) keep fixed meaning + position in *every* future version. A reader
30//! of any version can therefore always read the first 5 bytes, learn `ver`,
31//! look up that version's header length, read the rest, and splice `len` body
32//! bytes. `decode_header` enforces this discipline.
33
34#![forbid(unsafe_code)]
35
36use std::{error::Error, fmt};
37
38use serde::{Deserialize, Serialize};
39
40pub use machine_id::{MachineId, MachineIdError};
41
42pub mod call_mode;
43pub mod claim;
44pub mod config;
45pub mod consent;
46pub mod frame;
47pub mod framed_body;
48pub mod machine_id;
49pub mod manifest;
50pub mod module_id;
51pub mod peer;
52pub mod policy_root;
53pub mod provider_declarations;
54pub mod scope;
55pub mod session;
56pub mod tool_call;
57
58#[cfg(test)]
59mod reader_skew;
60
61/// Canonical error codes emitted by subc.
62///
63/// Error frames remain extensible strings; daemon-owned refusals need identical
64/// spelling and operation-specific retry policies across the daemon and SDKs.
65pub mod error_codes {
66    pub const CATALOG_UPDATE_FROZEN_CAPABILITY: &str = "catalog_update_frozen_capability";
67    use crate::Flags;
68
69    /// No approved configuration is available. Keep the last view, never fall
70    /// back to files or exit merely because this refusal was received.
71    pub const CONFIG_GATED: &str = "config_gated";
72    /// A saved plan's read set changed. The refusal carries no fresh digest.
73    pub const PLAN_STALE: &str = "plan_stale";
74    pub const LAYER_FORBIDDEN: &str = "layer_forbidden";
75    pub const BOUND_VIOLATED: &str = "bound_violated";
76    pub const VALUE_INVALID: &str = "value_invalid";
77    pub const CREDENTIAL_SHARED: &str = "credential_shared";
78    pub const LAYER_SYMLINK: &str = "layer_symlink";
79    pub const LAYER_NOT_REGULAR: &str = "layer_not_regular";
80    pub const LAYER_HARDLINKED: &str = "layer_hardlinked";
81    pub const LAYER_TOO_LARGE: &str = "layer_too_large";
82    pub const LAYER_ROOT_INVALID: &str = "layer_root_invalid";
83    pub const LAYER_ROOT_AMBIGUOUS: &str = "layer_root_ambiguous";
84    pub const EDIT_SPANS_FILES: &str = "edit_spans_files";
85    pub const PROJECT_APPLY_KIND_UNSUPPORTED: &str = "project_apply_kind_unsupported";
86    pub const CREDENTIAL_LAYER_UNSUPPORTED: &str = "credential_layer_unsupported";
87    pub const UNKNOWN_WORKSPACE: &str = "unknown_workspace";
88    pub const WORKSPACE_MISMATCH: &str = "workspace_mismatch";
89    pub const UNKNOWN_PROJECT: &str = "unknown_project";
90    /// Declare exactly once per connection, before config.get or config.applied.
91    pub const DECLARATION_ORDER: &str = "declaration_order";
92    pub const PROGRAM_REFUSED: &str = "program_refused";
93    pub const STORE_TAMPERED: &str = "store_tampered";
94    /// The store write is durable, but the protected revision-and-digest record
95    /// that detects replay has not caught up. Keep the current view and report
96    /// config.applied again after that protected record can be updated.
97    pub const ANCHOR_PENDING: &str = "anchor_pending";
98    pub const GENERATION_PRUNED: &str = "generation_pruned";
99    pub const APPROVAL_SURFACE_UNAVAILABLE: &str = "approval_surface_unavailable";
100    /// The operator declined, or the desktop app, phone card or OS prompt did
101    /// not answer in time.
102    pub const APPROVAL_DECLINED: &str = "approval_declined";
103    /// The connection is not the module's delivery target. This refusal never
104    /// sets the module to gated and never changes its delivery state.
105    pub const NOT_DELIVERY_TARGET: &str = "not_delivery_target";
106
107    /// Minting is allowed only on the spawn's live primary registration channel,
108    /// never on a claim-bound connection. TERMINAL.
109    pub const CLAIM_MINT_NOT_ALLOWED: &str = "claim_mint_not_allowed";
110    /// The spawn has 64 unredeemed claims after reclaiming expired claims.
111    /// RETRYABLE once claims are consumed or expire.
112    pub const CLAIM_UNREDEEMED_LIMIT: &str = "claim_unredeemed_limit";
113    /// The spawn has exhausted its claim-minting rate limit. RETRYABLE; `ErrorBody.detail`
114    /// carries `retry_after_ms`, the backoff in milliseconds.
115    pub const CLAIM_RATE_LIMITED: &str = "claim_rate_limited";
116    /// The spawn has 256 live claim-bound connections. RETRYABLE after closing
117    /// a connection; the refused presentation's connection is always closed.
118    pub const CLAIM_CONNECTION_LIMIT: &str = "claim_connection_limit";
119    /// An unknown, reused, expired or revoked claim. TERMINAL and deliberately
120    /// indistinguishable: the refusal never reveals which condition applied.
121    pub const CLAIM_INVALID: &str = "claim_invalid";
122    /// Presentation was not the connection's first frame after handshake.
123    /// TERMINAL; the refused connection is closed, never left direct.
124    pub const CLAIM_PRESENT_NOT_FIRST: &str = "claim_present_not_first";
125    /// A prefix claim's module id was refused, or the minting module does not
126    /// own its longest matching reserved prefix. TERMINAL.
127    pub const CLAIM_PREFIX_REFUSED: &str = "claim_prefix_refused";
128
129    /// Retry classification for `claim.mint` and `claim.present` refusals.
130    /// Unknown codes are terminal. Every refused presentation closes its
131    /// connection, including retryable refusals; retry on a new connection,
132    /// never by continuing as a direct caller.
133    pub fn is_retryable_claim(code: &str) -> bool {
134        matches!(
135            code,
136            CLAIM_UNREDEEMED_LIMIT | CLAIM_RATE_LIMITED | CLAIM_CONNECTION_LIMIT
137        )
138    }
139
140    /// Whether an agent declaration may be retried with a fresh correlation
141    /// and, for a closed declaration queue, a current supervised connection.
142    pub fn is_retryable_agent_commands(code: &str) -> bool {
143        matches!(
144            code,
145            AGENT_ROOTS_FULL | DECLARATION_CLOSED | DUPLICATE_CORRELATION | "busy"
146        )
147    }
148
149    /// RETRYABLE after live command capacity is available; accepted batch peers remain committed.
150    pub const AGENT_ROOTS_FULL: &str = "agent_roots_full";
151    /// RETRYABLE on a current supervised connection, not on the closed declaration queue.
152    pub const DECLARATION_CLOSED: &str = "declaration_closed";
153    /// RETRYABLE with a fresh correlation; the original declaration remains in flight.
154    pub const DUPLICATE_CORRELATION: &str = "duplicate_correlation";
155
156    pub const UNKNOWN_CHANNEL: &str = "unknown_channel";
157    pub const STALE_ROUTE_EPOCH: &str = "stale_route_epoch";
158    /// A caller or target authority epoch changed before the bind committed.
159    /// Retry the open to capture current authority. This refusal never
160    /// closes the shared module connection and does not prove non-delivery.
161    pub const STALE_AUTHORITY_EPOCH: &str = "stale_authority_epoch";
162    /// HELLO carried malformed or oversized provider declarations.
163    pub const INVALID_PROVIDER_DECLARATIONS: &str = "invalid_provider_declarations";
164    /// A catalog update tried to change declarations fixed for the spawn.
165    pub const CATALOG_UPDATE_FROZEN_DECLARATIONS: &str = "catalog_update_frozen_declarations";
166    /// An opted-in established route has no free request or watch credit.
167    /// The daemon did not forward this request; retry on the same route, never
168    /// by treating the route as dead or reopening it.
169    pub const ROUTE_BUSY: &str = "route_busy";
170    /// A module reply exceeds the client connection's whole egress byte budget.
171    /// TERMINAL for this request: the module already received it, and retrying
172    /// unchanged would produce the same oversized reply. The route stays open.
173    pub const FRAME_TOO_LARGE: &str = "frame_too_large";
174    pub const UNKNOWN_MODULE: &str = "unknown_module";
175    pub const MODULE_REMOVED: &str = "module_removed";
176    /// The target module's endpoint is draining for a reload, restart or disable.
177    ///
178    /// On the data plane (an `ERROR` frame answering a `REQUEST` on a bound route)
179    /// this code is a PRE-SEND GUARANTEE: the daemon returns it only when the
180    /// request could not take a route credit because the endpoint is draining,
181    /// and it returns it BEFORE forwarding, so the module never received the
182    /// request. A caller may therefore re-dispatch the same request once the
183    /// route is reopened without risking a duplicated side effect, exactly as it
184    /// may after `unknown_channel`. The daemon keeps this guarantee:
185    /// `supervisor_reload_rejects_new_work_during_drain` asserts the module's
186    /// event journal never records the rejected request. A request the module
187    /// already received is answered by the module (or its route closes with
188    /// `route.closed`), never by this code.
189    pub const MODULE_RELOADING: &str = "module_reloading";
190    pub const MODULE_WARMING: &str = "module_warming";
191    pub const TARGET_UNAVAILABLE: &str = "target_unavailable";
192    /// A flow-scoped route targets a module that does not provide
193    /// either `flow-scopes/v1` or `call-modes/v1`. TERMINAL: decoding `flow_id`
194    /// alone does not promise flow behaviour, and removing it would silently
195    /// change the identity.
196    pub const TARGET_FLOW_UNSUPPORTED: &str = "target_flow_unsupported";
197    /// The target cannot safely receive a federated flow or run claim.
198    pub const TARGET_FEDERATED_UNSUPPORTED: &str = "target_federated_unsupported";
199    /// A describe reader has not declared the federated provider contract.
200    pub const SCOPE_FEDERATED_UNSUPPORTED: &str = "scope_federated_unsupported";
201    /// Federated facts cannot change within a scope epoch.
202    pub const SCOPE_FEDERATED_CHANGED: &str = "scope_federated_changed";
203    /// An agent-run-scoped route targets a module providing neither
204    /// `agent-run-scopes/v1` nor `call-modes/v1`, or a delegating run targets a
205    /// module without `call-modes/v1`. TERMINAL: removing `run_id` or delegation
206    /// would silently change the identity or authority under which the route acts.
207    pub const TARGET_AGENT_RUN_UNSUPPORTED: &str = "target_agent_run_unsupported";
208    pub const MODULE_TIMEOUT: &str = "module_timeout";
209    /// The target module is declared as speaking no subc wire protocol
210    /// (`protocol: "none"` in daemon config), so it has no control lane and can
211    /// never accept a route. The daemon supervises its process and nothing else.
212    ///
213    /// TERMINAL, and deliberately neither of its two neighbours. It is not
214    /// `unknown_module`, which means "no module of this id is registered or
215    /// supervised here" and is likewise terminal; retrying here would storm the
216    /// daemon forever, because the answer is a property of the module's
217    /// declaration rather than of its current state. It is not `module_removed` either: the module is configured,
218    /// running, and supervised. Only an edit to its configuration can change
219    /// this answer, and a caller cannot wait that out.
220    pub const MODULE_NO_PROTOCOL: &str = "module_no_protocol";
221    /// A request field is malformed. The error's `detail.field` names the field
222    /// (for a `route.open`, `role_versions`). TERMINAL: the same request will be
223    /// refused the same way every time, so only a corrected request can succeed.
224    pub const INVALID_REQUEST: &str = "invalid_request";
225
226    /// A `route.open` named a scope whose owner is configured but has not
227    /// synced since this daemon incarnation started. RETRYABLE: after a daemon
228    /// restart a carrier's open can arrive before the owner re-syncs, and the
229    /// carrier waits within its own deadline. See `docs/designs/daemon-scopes.md`.
230    pub const SCOPE_NOT_SYNCED: &str = "scope_not_synced";
231    /// A scoped `route.open` was admitted, but the scope record changed before
232    /// the module's bind committed. Nothing was sent on the route, so the caller
233    /// may re-open against the current record: RETRYABLE.
234    pub const SCOPE_CHANGED: &str = "scope_changed";
235    /// A target module refused the bind because it can't yet resolve where
236    /// the session's state lives, for example while it repairs its session
237    /// index after a first start or a rollback. The target answers this from
238    /// its own bind, so the daemon relays it unchanged. Nothing was sent on
239    /// the route, so the caller may re-open within its deadline: RETRYABLE.
240    pub const SESSION_ADDRESS_UNAVAILABLE: &str = "session_address_unavailable";
241    /// A target module refused the bind because the state this route would
242    /// work on, such as the project folder it resolved for the route, is
243    /// temporarily in use: a read or write still running on it, or its setup
244    /// not finished. Unlike `session_address_unavailable`, the module knows
245    /// where that state is; something running blocks it. The module answers
246    /// this from its own bind and the daemon relays it unchanged. Nothing was
247    /// sent on the route, so the caller may re-open within its own deadline:
248    /// RETRYABLE.
249    ///
250    /// Optional `detail` fields, which a caller must not rely on:
251    /// `reason`, a short cause such as `reader`, and `retry_after_ms`, the
252    /// module's estimate of when to try again, which a caller never waits
253    /// past its own deadline. A module sends this code only once its callers
254    /// run SDKs that classify it as retryable (subc-protocol 0.34.3 or
255    /// `@cortexkit/subc-client` 0.23.1 and later); nothing enforces that, and
256    /// an older caller ends the open as if refused for good.
257    pub const BIND_BUSY: &str = "bind_busy";
258    /// A scoped `route.open` named no `scope_epoch`. Every opener names one,
259    /// the owner included, so an old call can never be carried into a newer
260    /// session that reused the ref. TERMINAL.
261    pub const SCOPE_EPOCH_REQUIRED: &str = "scope_epoch_required";
262    /// A scoped `route.open` named a ref the owner's synced set does not hold,
263    /// or an owner that is not a configured module. TERMINAL.
264    pub const SCOPE_NOT_LIVE: &str = "scope_not_live";
265    /// A scoped `route.open` named a `scope_epoch` that is not the live one, or
266    /// the scope ended between admission and commit. TERMINAL.
267    pub const SCOPE_ENDED: &str = "scope_ended";
268    /// The opener of a scoped `route.open` is neither the scope's owner nor a
269    /// listed carrier, or it is a targeted carrier and the target module is not
270    /// in its list. TERMINAL.
271    pub const SCOPE_NOT_CARRIER: &str = "scope_not_carrier";
272    /// A scope with a bind-proof hash requires every opener, including its
273    /// owner, to present the proof. TERMINAL.
274    pub const SCOPE_BIND_PROOF_REQUIRED: &str = "scope_bind_proof_required";
275    /// The proof is malformed or does not match the scope's hash. TERMINAL.
276    pub const SCOPE_BIND_PROOF_MISMATCH: &str = "scope_bind_proof_mismatch";
277    /// An idle-only epoch/proof replacement found routes, admitted binds or
278    /// connected presence under the live epoch. Per-record refusal. TERMINAL.
279    pub const SCOPE_EPOCH_IN_USE: &str = "scope_epoch_in_use";
280    /// Raised by a carrier, never by the daemon: the daemon does not advertise
281    /// `scopes/v1`, so the carrier fails the call instead of opening an
282    /// unscoped route.
283    pub const SCOPE_UNSUPPORTED: &str = "scope_unsupported";
284
285    /// `scope.sync` or `scope.apply` came from a connection that is not the
286    /// owner's sync authority: another connection of the same launch holds it,
287    /// or this connection's launch is no longer the owner's current one (a
288    /// blue/green swap candidate before cutover, or an incumbent after it).
289    pub const SCOPE_SYNC_NOT_AUTHORITY: &str = "scope_sync_not_authority";
290    /// `scope.apply` came from a connection that has not taken sync authority
291    /// through an accepted full `scope.sync`. The whole call changes nothing.
292    pub const SCOPE_SYNC_REQUIRED: &str = "scope_sync_required";
293    /// `scope.sync` or `scope.apply` carried a generation no larger than the last
294    /// one the authority accepted. The whole call is refused and nothing changes.
295    pub const SCOPE_SYNC_STALE: &str = "scope_sync_stale";
296    /// `scope.sync` or `scope.apply` exceeds the owner's live-scope limit.
297    /// The whole call is refused and nothing changes.
298    pub const SCOPE_LIVE_LIMIT_EXCEEDED: &str = "scope_live_limit_exceeded";
299    /// One record in a `scope.sync` or `scope.apply` carried more attribute bytes
300    /// than a scope may hold. The whole call is refused and nothing changes.
301    pub const SCOPE_ATTRIBUTES_TOO_LARGE: &str = "scope_attributes_too_large";
302
303    // Per-record refusals: each is reported against one record in the
304    // `scope.sync` or `scope.apply` reply. A refusal itself does not change the
305    // ref or undo expiry processing; other records in the call still apply.
306
307    /// The record lowers the `scope_epoch` the daemon holds for its ref.
308    pub const SCOPE_EPOCH_REGRESSED: &str = "scope_epoch_regressed";
309    /// The record names an `(owner, ref, scope_epoch)` that already ended in
310    /// this daemon incarnation; an ended session cannot come back.
311    pub const SCOPE_EPOCH_ENDED: &str = "scope_epoch_ended";
312    /// The record's deadline has passed, or this ref at this epoch was ended by
313    /// expiry and its tombstone is still held. The same session epoch cannot
314    /// return.
315    pub const SCOPE_EXPIRED: &str = "scope_expired";
316    /// The record adds, removes or changes the deadline of a live scope at the
317    /// same epoch. A different deadline requires a new session epoch.
318    pub const SCOPE_EXPIRY_IMMUTABLE: &str = "scope_expiry_immutable";
319    /// The record's deadline is more than `scope::MAX_SCOPE_EXPIRY_AHEAD_MS`
320    /// ahead of the daemon's current Unix wall clock.
321    pub const SCOPE_EXPIRY_TOO_FAR: &str = "scope_expiry_too_far";
322    /// The record changes `kind` at the same `scope_epoch`.
323    pub const SCOPE_KIND_CHANGED: &str = "scope_kind_changed";
324    pub const INVALID_WORKDIR: &str = "invalid_workdir";
325    pub const SCOPE_WORKDIR_CHANGED: &str = "scope_workdir_changed";
326    /// Installed flow identity cannot be added, changed or removed within an epoch.
327    pub const SCOPE_FLOW_IDENTITY_CHANGED: &str = "scope_flow_identity_changed";
328    pub const SCOPE_PROJECT_CHANGED: &str = "scope_project_changed";
329    /// The record sets authority-controlled attributes and its owner is not
330    /// listed in `scope_authority_owners`, or combines `on_behalf_of_agent` with
331    /// `agent_id`, `delegates`, `flow_id` or `run_id`, or supplies an incomplete
332    /// installed flow identity or one without `flow_id`.
333    pub const SCOPE_ATTRIBUTE_NOT_PERMITTED: &str = "scope_attribute_not_permitted";
334    /// The record's parent link is not permitted: the parent's owner has synced
335    /// and the parent is not live at the named epoch, the syncing owner is
336    /// neither the parent's owner nor in its `child_owners`, or the link would
337    /// close a cycle.
338    pub const SCOPE_PARENT_NOT_PERMITTED: &str = "scope_parent_not_permitted";
339    /// A targeted carrier entry lists no target modules, or more than
340    /// `scope::MAX_CARRIER_TARGETS`.
341    pub const SCOPE_CARRIER_TARGETS_INVALID: &str = "scope_carrier_targets_invalid";
342    /// The record sets `delegates` without an `agent_id` to delegate.
343    pub const SCOPE_DELEGATES_WITHOUT_AGENT: &str = "scope_delegates_without_agent";
344    /// The record sets `run_id` without either `agent_id` (an agent run) or
345    /// `on_behalf_of_agent` (a worker run).
346    pub const SCOPE_RUN_ID_WITHOUT_AGENT: &str = "scope_run_id_without_agent";
347    /// The record sets both `run_id` and `flow_id`; a run scope is not a flow scope.
348    pub const SCOPE_RUN_ID_WITH_FLOW_ID: &str = "scope_run_id_with_flow_id";
349    /// Legacy refusal for a record setting `run_id` with `delegates`.
350    /// No longer emitted by validation: run records may delegate, and route
351    /// admission instead requires a target providing `call-modes/v1`.
352    pub const SCOPE_RUN_ID_DELEGATES: &str = "scope_run_id_delegates";
353
354    /// An `operator.confirm` was declined or withdrawn. `detail.reason` is
355    /// `person`, `backoff`, `route_closed`, `module_closed` or `caller_cancelled`.
356    pub const OPERATOR_DECLINED: &str = "operator_declined";
357    /// An `operator.confirm` could not prompt or complete. `detail.reason` is
358    /// `no_presence`, `timeout`, `module_limit`, `queue_full`, `queue_wait`,
359    /// `provider_stuck`, `unsupported_platform` or `provider_error`.
360    pub const OPERATOR_PRESENCE_UNAVAILABLE: &str = "operator_presence_unavailable";
361    /// The summary of an `operator.confirm` breaks the daemon's summary rules.
362    pub const OPERATOR_SUMMARY_INVALID: &str = "operator_summary_invalid";
363    /// An `operator.confirm` is not from a nonce-proven module connection for
364    /// an open route with a verified opener on that connection.
365    pub const OPERATOR_REQUEST_NOT_PERMITTED: &str = "operator_request_not_permitted";
366
367    /// Whether a `route.open` refusal carrying `code` may be retried in place
368    /// within the caller's deadline, or is terminal for the target as named.
369    ///
370    /// This lives beside the codes because every consumer with its own
371    /// connection layer needs the same answer: a copied list breaks loudly on
372    /// a renamed code and silently on an added one. The SDKs call this; the
373    /// golden `decision_tables.json` (`route_open_retryable`) is the record
374    /// the daemon and every SDK are tested against, and the test in
375    /// `golden_json.rs` holds this function to it.
376    ///
377    /// Unknown codes are terminal: a refusal this crate has never heard of
378    /// must not be retried on the strength of a match-all arm.
379    ///
380    /// `unknown_module` is terminal: it now means only "no module of this id
381    /// is registered or supervised here" — a typo, or a peer not deployed on
382    /// this host. The daemon reports a configured-but-late target with its own
383    /// retryable codes (`module_warming`, `target_unavailable`), so a caller
384    /// that races an unsupervised module's HELLO owns its own retry; retrying
385    /// in place only papers over that race for one narrow window.
386    pub fn is_retryable_route_open(code: &str) -> bool {
387        if matches!(
388            code,
389            TARGET_FLOW_UNSUPPORTED
390                | FEDERATED_STAMP_REQUIRED
391                | TARGET_FEDERATED_UNSUPPORTED
392                | TARGET_AGENT_RUN_UNSUPPORTED
393                | SCOPE_BIND_PROOF_REQUIRED
394                | SCOPE_BIND_PROOF_MISMATCH
395                | SCOPE_EPOCH_IN_USE
396        ) {
397            return false;
398        }
399        matches!(
400            code,
401            MODULE_RELOADING
402                | MODULE_WARMING
403                | TARGET_UNAVAILABLE
404                | MODULE_TIMEOUT
405                | SCOPE_NOT_SYNCED
406                | SCOPE_CHANGED
407                | SESSION_ADDRESS_UNAVAILABLE
408                | BIND_BUSY
409                | STALE_AUTHORITY_EPOCH
410        )
411    }
412
413    /// The scope requires a federated stamp, but the target cannot read one.
414    pub const FEDERATED_STAMP_REQUIRED: &str = "federated_stamp_required";
415    /// Only the configured federated owner with route-authorize/v1 may ask.
416    pub const ROUTE_AUTHORIZE_NOT_PERMITTED: &str = "route_authorize_not_permitted";
417
418    /// Whether the caller should evict this established route, reopen it, and
419    /// resend the request once. Consumers mapping route death to their own
420    /// custody, provider, or suspect verdict keep their own named code lists;
421    /// sharing this predicate for those meanings can change a verdict on a
422    /// protocol bump (prefrontal#59).
423    ///
424    /// Takes envelope flags so the daemon-origin check can be enabled here in
425    /// one place. Phase 2 requires first that every daemon a consumer can meet
426    /// sets DAEMON_ORIGIN on these error frames, both landed and deployed;
427    /// only then may this predicate require the bit. Requiring it sooner makes
428    /// a new SDK against an older daemon stop evicting on a genuine
429    /// `stale_route_epoch` — the failure this predicate is meant to prevent.
430    ///
431    /// The daemon emits these codes in `RouterError::to_error_frame` at
432    /// `crates/subc-daemon/src/router.rs` (UnknownChannel and StaleRouteEpoch).
433    pub fn is_established_route_dead(_flags: Flags, code: &str) -> bool {
434        matches!(code, UNKNOWN_CHANNEL | STALE_ROUTE_EPOCH)
435    }
436
437    /// Whether an error proves a retryable credit refusal on the same route.
438    /// A negotiated request window and daemon origin are both required: module
439    /// errors, and errors on routes without the opt-in, prove no non-delivery.
440    pub fn is_route_busy_retryable(flags: Flags, code: &str, route_opted_in: bool) -> bool {
441        route_opted_in && flags.is_daemon_origin() && code == ROUTE_BUSY
442    }
443
444    #[cfg(test)]
445    mod agent_command_tests {
446        #[test]
447        fn agent_declaration_refusals_have_explicit_retry_classes() {
448            for (code, retry) in [
449                ("agent_roots_full", true),
450                ("busy", true),
451                ("duplicate_correlation", true),
452                ("declaration_closed", true),
453                ("not_supervised", false),
454                ("invalid_request", false),
455                ("future_code", false),
456            ] {
457                assert_eq!(super::is_retryable_agent_commands(code), retry, "{code}");
458            }
459        }
460    }
461}
462
463pub use frame::{Frame, FrameBuildError};
464
465/// Why subc is closing a module's client routes.
466#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
467#[serde(rename_all = "snake_case")]
468#[non_exhaustive]
469pub enum RouteCloseReason {
470    Reload,
471    Restart,
472    /// Authority changed; reopening immediately obtains the current attestation.
473    AuthorityChanged,
474    Disable,
475    Crash,
476    /// A live route became forbidden because newly attested capability metadata
477    /// matched its supervised opening module's deny edge.
478    CapabilityDenied,
479    /// The route's scope ended: it expired, its owner ended it, or replaced it
480    /// with a higher `scope_epoch` (a new session under the same ref).
481    ScopeEnded,
482    /// The route's opener is no longer a listed carrier of its scope, or the
483    /// route's target was removed from that carrier's target list.
484    ScopeCarrierRemoved,
485    /// The scope's `delegates` went from true to false, or its `agent_id`,
486    /// `on_behalf_of_agent`, `flow_id` or `run_id` changed.
487    ScopeDelegationChanged,
488    /// The scope's parent ended, so its stamp no longer names a live parent.
489    ScopeParentEnded,
490}
491
492impl RouteCloseReason {
493    /// Whether an opener may immediately reopen after this close.
494    pub fn may_reopen(self) -> bool {
495        matches!(self, Self::Reload | Self::Restart | Self::AuthorityChanged)
496    }
497}
498
499/// `server.describe` capability permitting `accepts_close_reasons` on route opens.
500/// Readers define the name before any daemon advertises support for it.
501pub const ROUTE_CLOSE_REASONS_CAPABILITY: &str = "route-close-reasons/v1";
502
503/// Per-route bind identity shared by client-facing and module-facing control.
504///
505/// Every field here is client-supplied and unattested. Use these claims for
506/// attribution, never authorization; gate on the daemon-stamped [`Principal`]
507/// instead.
508///
509/// Protocol 0.34 identities carry no project fields. For project-free openers,
510/// project attribution comes from the admitted session [`scope::ScopeStamp`]'s
511/// `workdir` and optional `project_id`; without these fields there is no project
512/// attribution. During migration, daemon 0.39 also accepts legacy opener project
513/// fields and prefers the legacy root over the scope workdir for internal root
514/// attribution and compatibility bind fields. Decoding remains lenient so
515/// readers can ignore project fields sent by older daemons during migration.
516/// See [`scope::BIND_NO_PROJECT_CAPABILITY`] for target opt-in to project-free
517/// bind identities.
518#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
519#[non_exhaustive]
520pub struct BindIdentity {
521    pub harness: String,
522    pub session: String,
523    /// The opener's claim about the kind of build it is, sent on `route.open`.
524    /// [`BUILD_CLASS_PRODUCTION`] marks a production build whose integrity the
525    /// opener has verified.
526    ///
527    /// Like every other field here it is unattested. The daemon recognizes
528    /// `callosum` as the caller module ID eligible for this claim. It honours
529    /// the claim only when the opener's principal is
530    /// `Reserved { module_id: "callosum" }`, and only the exact value
531    /// [`BUILD_CLASS_PRODUCTION`]; any other value counts as absent. From any
532    /// other opener it is ignored. The identity on `route.bind` never carries
533    /// it. Targets declaring [`peer::PEER_BUILD_CAPABILITY`] receive the
534    /// honoured production claim separately as [`peer::RouteBindPeer::peer_build`].
535    ///
536    /// An absent build-class claim is omitted from the wire. A reader that
537    /// predates this field drops it, which grants nothing.
538    /// Set it on the public field after [`BindIdentity::new`].
539    #[serde(default, skip_serializing_if = "Option::is_none")]
540    pub build_class: Option<String>,
541}
542
543/// The only [`BindIdentity::build_class`] value the daemon honours.
544pub const BUILD_CLASS_PRODUCTION: &str = "production";
545
546impl BindIdentity {
547    /// Constructs a project-free attribution identity.
548    ///
549    /// Use this instead of a struct literal so future additive identity fields do
550    /// not force construction-site migrations across the fleet.
551    pub fn new(harness: impl Into<String>, session: impl Into<String>) -> Self {
552        Self {
553            harness: harness.into(),
554            session: session.into(),
555            build_class: None,
556        }
557    }
558}
559
560/// Caller fact stamped by subc on each route.bind relayed to a module.
561#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
562#[serde(tag = "kind", rename_all = "snake_case")]
563pub enum Principal {
564    /// A daemon-spawned module proved possession of its launch nonce.
565    Reserved { module_id: String },
566    /// No consumer identity was presented; the caller is a direct key-holder.
567    Direct,
568    /// Reserved vocabulary for a future degraded/no-key-auth mode.
569    Unverified,
570}
571
572/// Explicit target for a route open/bind operation.
573///
574/// RouteTarget.kind ↔ ProviderRole mapping:
575///
576/// | RouteTarget.kind | required ProviderRole | disambiguator |
577/// |---|---|---|
578/// | `tool_provider` | `ToolProvider` | v1: ≤1 per module |
579/// | `management_surface` | `ManagementSurface` | v1: ≤1 per module |
580/// | `internal_service` | `InternalService` | `service_id` (multiple allowed) |
581///
582/// `ProviderRole::PipelineStage` is intentionally unroutable; pipeline modules
583/// are wired by an orchestrator rather than opened directly by clients.
584#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
585#[serde(tag = "kind", rename_all = "snake_case")]
586pub enum RouteTarget {
587    ToolProvider {
588        module_id: String,
589    },
590    ManagementSurface {
591        module_id: String,
592    },
593    InternalService {
594        module_id: String,
595        service_id: String,
596    },
597}
598
599/// Envelope protocol version this build speaks.
600pub const PROTOCOL_VERSION: u8 = 2;
601
602/// The version of THIS crate (`subc-protocol`) as compiled into the linking
603/// binary — the fleet's shared wire-vocabulary version, and the value
604/// `ManifestProvenance.wire_crate_version` declares. Not the version of a
605/// module's own envelope or payload crates: those are different numbering
606/// spaces, and declaring one here produces a confident wrong answer at any
607/// version gate (insula shipped exactly that before the referent was written
608/// down). `env!` makes it a property of the compiled binary, not of whatever
609/// source tree sits beside it at run time.
610pub const SUBC_PROTOCOL_CRATE_VERSION: &str = env!("CARGO_PKG_VERSION");
611
612/// Oldest envelope protocol version this build accepts.
613pub const MIN_SUPPORTED_VERSION: u8 = 2;
614
615/// Env var subc sets on each supervised child telling it the module_id it is
616/// supervised under, so it can register under that id.
617pub const SUBC_MODULE_ID_ENV: &str = "SUBC_MODULE_ID";
618
619/// Env var subc sets, on each spawn of a `reserved` module only, to a fresh
620/// one-time launch nonce. The child echoes it in `ModuleHelloBody::launch_nonce`;
621/// subc accepts a reserved module_id's HELLO only when the nonce matches the one it
622/// last injected for that id. Non-reserved modules never receive it.
623pub const SUBC_LAUNCH_NONCE_ENV: &str = "SUBC_LAUNCH_NONCE";
624
625/// Fixed header length for `PROTOCOL_VERSION` 2.
626pub const HEADER_LEN: usize = 21;
627
628/// Bytes of the frozen prefix (`len` u32 + `ver` u8) that are stable across
629/// every envelope version. A reader needs only these to learn the version and
630/// thus the full header length.
631pub const FROZEN_PREFIX_LEN: usize = 5;
632
633/// Maximum frame body accepted before allocation.
634///
635/// This 64 MiB starting cap prevents a malformed header from forcing an
636/// unbounded allocation. Future protocol versions can negotiate or encode a
637/// different cap while preserving the frozen prefix.
638pub const MAX_FRAME_BODY_LEN: u32 = 64 * 1024 * 1024;
639
640/// Largest frame, `HEADER_LEN` included, that the daemon delivers from a module
641/// to a client: a reply, stream frame, error, reverse request or push. A module
642/// sizes what it sends to a client against this, not against
643/// `MAX_FRAME_BODY_LEN`.
644///
645/// A larger module frame is never forwarded to the client. A reply, stream
646/// frame or error that is too large ends its request with a `frame_too_large`
647/// error; a reverse request that is too large is answered with an error to the
648/// module; an unsolicited push that is too large closes the client connection.
649///
650/// Requests from a client to a module are not held to this limit; they are
651/// bounded only by `MAX_FRAME_BODY_LEN`.
652pub const MAX_DELIVERED_FRAME_LEN: usize = 4 * 1024 * 1024;
653
654/// Canonical JSON body for all subc-generated `ERROR` frames.
655///
656/// `detail` is an optional machine-parsable surface for refusals whose remedy
657/// needs more than a code (e.g. a producer-published backoff number, an
658/// observed-vs-configured size pair). Absent detail serializes to nothing, so
659/// bodies without it are byte-identical to the pre-detail wire and older
660/// readers simply never see the field. Producers document each code's detail
661/// fields where the code is defined; `detail` must never carry secrets.
662#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
663pub struct ErrorBody {
664    pub code: String,
665    pub message: String,
666    #[serde(default, skip_serializing_if = "Option::is_none")]
667    pub detail: Option<serde_json::Value>,
668}
669
670/// Credit snapshot attached to a daemon's never-forwarded `route_busy` error.
671/// `request_in_flight` counts all admitted requests, including watches.
672#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
673pub struct RouteBusyDetail {
674    pub reason: String,
675    pub request_in_flight: usize,
676    pub watch_in_flight: usize,
677    pub request_window: usize,
678    #[serde(default, skip_serializing_if = "Option::is_none")]
679    pub watch_window: Option<usize>,
680}
681
682impl ErrorBody {
683    /// A detail-less error body; the common case.
684    pub fn new(code: impl Into<String>, message: impl Into<String>) -> Self {
685        Self {
686            code: code.into(),
687            message: message.into(),
688            detail: None,
689        }
690    }
691
692    /// Attach a machine-parsable detail object to this error.
693    pub fn with_detail(mut self, detail: serde_json::Value) -> Self {
694        self.detail = Some(detail);
695        self
696    }
697}
698
699/// Module-to-subc `HELLO` body used during module registration.
700#[derive(Clone, Serialize, Deserialize, PartialEq)]
701pub struct ModuleHelloBody {
702    pub manifest: manifest::ModuleManifest,
703    pub protocol_ver: u8,
704    #[serde(default)]
705    pub control_ops: Option<Vec<String>>,
706    /// One-time launch nonce, echoed back from the `SUBC_LAUNCH_NONCE` environment
707    /// variable the daemon injected when it spawned this process. Only a daemon-spawned
708    /// process for a `reserved` module receives a nonce; subc accepts a reserved
709    /// `module_id`'s HELLO only when this matches the nonce it last injected for that
710    /// id, so a different process cannot register as a reserved module while the real
711    /// one is down/restarting. Absent (`serde(default)`) for non-reserved modules and
712    /// self-connecting providers, which are never nonce-checked.
713    #[serde(default, skip_serializing_if = "Option::is_none")]
714    pub launch_nonce: Option<String>,
715}
716
717// Hand-written so the launch nonce is never printed. The nonce is the credential
718// that attributes a connection to a supervised module, and a derived Debug would
719// write it into any log line or panic message that formats this value. Same
720// reasoning as ConnectionInfo's Debug in subc-transport.
721impl fmt::Debug for ModuleHelloBody {
722    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
723        f.debug_struct("ModuleHelloBody")
724            .field("manifest", &self.manifest)
725            .field("protocol_ver", &self.protocol_ver)
726            .field("control_ops", &self.control_ops)
727            .field(
728                "launch_nonce",
729                &self
730                    .launch_nonce
731                    .as_ref()
732                    .map(|nonce| format!("<{} bytes redacted>", nonce.len())),
733            )
734            .finish()
735    }
736}
737
738/// subc-to-module `HELLO_ACK` body used during module registration.
739#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
740pub struct ModuleHelloAckBody {
741    pub negotiated_ver: u8,
742    pub subc_ops: Vec<String>,
743    pub subc_capabilities: Vec<String>,
744    /// The module's resolved storage descriptor, when the daemon's central config
745    /// configures managed storage. Carried opaquely here (subc-protocol stays a
746    /// thin wire crate with no storage/database dependency); a module that uses
747    /// managed storage deserializes it into `cortexkit_store_types::StorageDescriptor`
748    /// and hands it to `cortexkit-store`. Absent when no storage is configured, and
749    /// `serde(default)` so an older module simply ignores it.
750    #[serde(default, skip_serializing_if = "Option::is_none")]
751    pub storage: Option<serde_json::Value>,
752    /// The daemon's machine id (see [`MachineId`]): a name for this machine,
753    /// never an authority. Nothing may admit a peer, grant trust or skip a check
754    /// because two messages carry the same value.
755    ///
756    /// Carried as a plain string so one malformed value cannot fail the whole
757    /// registration reply; a module validates it with [`MachineId::parse`].
758    /// Absent from a daemon that predates the machine id, which a module must
759    /// read as exactly that, never as "no machine" and never as a reason to mint
760    /// its own.
761    #[serde(default, skip_serializing_if = "Option::is_none")]
762    pub machine_id: Option<String>,
763}
764
765/// Frame kind (`type` byte at offset 5).
766///
767/// `CANCEL`, `PING`, `PONG`, and `GOODBYE` are pure-header frames (`len == 0`);
768/// only `HELLO`/`HELLO_ACK` and the RPC payloads carry bodies.
769#[derive(Debug, Clone, Copy, PartialEq, Eq)]
770#[repr(u8)]
771pub enum FrameType {
772    Request = 0,
773    Response = 1,
774    Push = 2,
775    StreamData = 3,
776    StreamEnd = 4,
777    Error = 5,
778    Cancel = 6,
779    Ping = 7,
780    Pong = 8,
781    Hello = 9,
782    HelloAck = 10,
783    Goodbye = 11,
784}
785
786impl FrameType {
787    /// Map the raw `type` byte to a `FrameType`, or `None` if unknown.
788    pub fn from_u8(b: u8) -> Option<Self> {
789        Some(match b {
790            0 => Self::Request,
791            1 => Self::Response,
792            2 => Self::Push,
793            3 => Self::StreamData,
794            4 => Self::StreamEnd,
795            5 => Self::Error,
796            6 => Self::Cancel,
797            7 => Self::Ping,
798            8 => Self::Pong,
799            9 => Self::Hello,
800            10 => Self::HelloAck,
801            11 => Self::Goodbye,
802            _ => return None,
803        })
804    }
805
806    pub fn is_pure_header(self) -> bool {
807        matches!(self, Self::Cancel | Self::Ping | Self::Pong | Self::Goodbye)
808    }
809}
810
811/// Scheduling priority carried in `flags` bits 1-2. subc schedules on this
812/// without parsing the body.
813#[derive(Debug, Clone, Copy, PartialEq, Eq)]
814#[repr(u8)]
815pub enum Priority {
816    Passive = 0,
817    Interactive = 1,
818    Background = 2,
819}
820
821impl Priority {
822    fn from_bits(bits: u8) -> Option<Self> {
823        Some(match bits {
824            0 => Self::Passive,
825            1 => Self::Interactive,
826            2 => Self::Background,
827            _ => return None,
828        })
829    }
830}
831
832/// Admission behavior carried in `flags` bits 4-5.
833#[derive(Debug, Clone, Copy, PartialEq, Eq)]
834#[repr(u8)]
835pub enum AdmissionClass {
836    Normal = 0,
837    Expedite = 1,
838    Sheddable = 2,
839}
840
841impl AdmissionClass {
842    fn from_bits(bits: u8) -> Option<Self> {
843        Some(match bits {
844            0 => Self::Normal,
845            1 => Self::Expedite,
846            2 => Self::Sheddable,
847            _ => return None,
848        })
849    }
850}
851
852const FLAG_BINARY: u8 = 0b0000_0001; // bit 0
853const FLAG_PRIORITY_MASK: u8 = 0b0000_0110; // bits 1-2
854const FLAG_PRIORITY_SHIFT: u8 = 1;
855const FLAG_LAST: u8 = 0b0000_1000; // bit 3
856const FLAG_ADMISSION_MASK: u8 = 0b0011_0000; // bits 4-5
857const FLAG_ADMISSION_SHIFT: u8 = 4;
858pub const FLAG_DAEMON_ORIGIN: u8 = 0b0100_0000;
859/// A request credit the client explicitly declares as a held-open subscription.
860pub const FLAG_SUBSCRIPTION: u8 = 0b1000_0000;
861
862/// The `flags` byte (offset 6): binary, priority, last, admission, daemon origin, subscription.
863#[derive(Debug, Clone, Copy, PartialEq, Eq)]
864pub struct Flags(pub u8);
865
866impl Flags {
867    /// Build flags with the default [`AdmissionClass::Normal`] class.
868    pub fn new(binary: bool, priority: Priority, last: bool) -> Self {
869        let mut b = 0u8;
870        if binary {
871            b |= FLAG_BINARY;
872        }
873        b |= (priority as u8) << FLAG_PRIORITY_SHIFT;
874        if last {
875            b |= FLAG_LAST;
876        }
877        Flags(b)
878    }
879
880    /// Return these flags with a typed admission class.
881    pub fn with_admission_class(mut self, admission_class: AdmissionClass) -> Self {
882        self.0 =
883            (self.0 & !FLAG_ADMISSION_MASK) | ((admission_class as u8) << FLAG_ADMISSION_SHIFT);
884        self
885    }
886
887    /// Body is raw bytes (bulk lane) rather than JSON-RPC.
888    pub fn is_binary(self) -> bool {
889        self.0 & FLAG_BINARY != 0
890    }
891
892    /// Final frame of a streamed message.
893    pub fn is_last(self) -> bool {
894        self.0 & FLAG_LAST != 0
895    }
896
897    /// Decode the priority bits, or `None` if they hold a reserved value.
898    pub fn priority(self) -> Option<Priority> {
899        Priority::from_bits((self.0 & FLAG_PRIORITY_MASK) >> FLAG_PRIORITY_SHIFT)
900    }
901
902    /// Decode the admission-class bits, or `None` if they hold `0b11`.
903    pub fn admission_class(self) -> Option<AdmissionClass> {
904        AdmissionClass::from_bits((self.0 & FLAG_ADMISSION_MASK) >> FLAG_ADMISSION_SHIFT)
905    }
906
907    /// True when a request was explicitly opened as a held-open subscription.
908    pub fn is_subscription(self) -> bool {
909        self.0 & FLAG_SUBSCRIPTION != 0
910    }
911
912    /// True when the frame was authored by the daemon.
913    pub fn is_daemon_origin(self) -> bool {
914        self.0 & FLAG_DAEMON_ORIGIN != 0
915    }
916
917    /// Return these flags with daemon origin asserted.
918    pub fn with_daemon_origin(mut self) -> Self {
919        self.0 |= FLAG_DAEMON_ORIGIN;
920        self
921    }
922
923    /// Return these flags with daemon origin cleared.
924    pub fn without_daemon_origin(self) -> Self {
925        Self(self.0 & !FLAG_DAEMON_ORIGIN)
926    }
927}
928
929/// A decoded envelope header. The body is the `len` bytes that follow it.
930#[derive(Debug, Clone, Copy, PartialEq, Eq)]
931pub struct EnvelopeHeader {
932    /// Number of body bytes after the header.
933    pub len: u32,
934    /// Envelope version.
935    pub ver: u8,
936    /// Frame kind.
937    pub ty: FrameType,
938    /// Flag bits.
939    pub flags: Flags,
940    /// Sender-local route slot; 0 is the control channel.
941    pub channel: u16,
942    /// Sender-local binding epoch; 0 is reserved for the control channel.
943    pub epoch: u32,
944    /// Correlation id.
945    pub corr: u64,
946}
947
948impl EnvelopeHeader {
949    /// Serialize the header to its fixed 21-byte little-endian form.
950    pub fn encode(&self) -> [u8; HEADER_LEN] {
951        let mut buf = [0u8; HEADER_LEN];
952        buf[0..4].copy_from_slice(&self.len.to_le_bytes());
953        buf[4] = self.ver;
954        buf[5] = self.ty as u8;
955        buf[6] = self.flags.0;
956        buf[7..9].copy_from_slice(&self.channel.to_le_bytes());
957        buf[9..13].copy_from_slice(&self.epoch.to_le_bytes());
958        buf[13..21].copy_from_slice(&self.corr.to_le_bytes());
959        buf
960    }
961}
962
963/// Why a header could not be decoded.
964#[derive(Debug, Clone, Copy, PartialEq, Eq)]
965pub enum DecodeError {
966    /// Fewer than `FROZEN_PREFIX_LEN` bytes — cannot even read `len`/`ver`.
967    TooShortForPrefix { have: usize },
968    /// `ver` is not a version this build understands.
969    UnsupportedVersion { ver: u8 },
970    /// Version known but fewer than its header length is present.
971    TooShortForHeader { have: usize, need: usize },
972    /// `type` byte is not a known `FrameType`.
973    UnknownFrameType { byte: u8 },
974    /// A reserved flag bit is set (retained for older decoder error compatibility).
975    ReservedFlagBits { flags: u8 },
976    /// Priority bits 1-2 hold the reserved value `0b11`.
977    ReservedPriorityBits { flags: u8 },
978    /// Admission bits 4-5 hold the reserved value `0b11`.
979    ReservedAdmissionClass { flags: u8 },
980    /// SHEDDABLE is set on a frame type that must be delivered.
981    SheddableIllegalFrameType { ty: FrameType, flags: u8 },
982    /// Channel 0 carried an epoch other than its reserved epoch 0.
983    NonzeroEpochOnControlChannel { epoch: u32 },
984    /// A pure-header frame declared body bytes.
985    PureHeaderFrameWithBody { ty: FrameType, len: u32 },
986}
987
988impl fmt::Display for DecodeError {
989    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
990        match self {
991            Self::TooShortForPrefix { have } => {
992                write!(f, "header shorter than frozen prefix: have {have} bytes")
993            }
994            Self::UnsupportedVersion { ver } => write!(f, "unsupported envelope version {ver}"),
995            Self::TooShortForHeader { have, need } => {
996                write!(
997                    f,
998                    "header too short for version: have {have} bytes, need {need}"
999                )
1000            }
1001            Self::UnknownFrameType { byte } => write!(f, "unknown frame type byte {byte}"),
1002            Self::ReservedFlagBits { flags } => {
1003                write!(f, "reserved flag bits set in flags 0b{flags:08b}")
1004            }
1005            Self::ReservedPriorityBits { flags } => {
1006                write!(f, "reserved priority bits set in flags 0b{flags:08b}")
1007            }
1008            Self::ReservedAdmissionClass { flags } => {
1009                write!(f, "reserved admission class set in flags 0b{flags:08b}")
1010            }
1011            Self::SheddableIllegalFrameType { ty, flags } => write!(
1012                f,
1013                "SHEDDABLE admission class is illegal on {ty:?} in flags 0b{flags:08b}"
1014            ),
1015            Self::NonzeroEpochOnControlChannel { epoch } => {
1016                write!(f, "control channel carried nonzero epoch {epoch}")
1017            }
1018            Self::PureHeaderFrameWithBody { ty, len } => {
1019                write!(
1020                    f,
1021                    "pure-header frame {ty:?} declared non-zero body length {len}"
1022                )
1023            }
1024        }
1025    }
1026}
1027
1028impl Error for DecodeError {}
1029
1030/// How many header bytes a given envelope version occupies. Driven by the
1031/// frozen prefix: read `ver`, then learn the full header length here.
1032fn header_len_for_version(ver: u8) -> Option<usize> {
1033    match ver {
1034        PROTOCOL_VERSION => Some(HEADER_LEN),
1035        _ => None,
1036    }
1037}
1038
1039/// Decode an envelope header from the front of `bytes`, following the
1040/// frozen-prefix discipline:
1041/// 1. need at least the 5-byte prefix to read `len` + `ver`;
1042/// 2. dispatch the full header length on `ver`;
1043/// 3. need the full header present; then parse the rest.
1044///
1045/// Never panics on malformed input — returns a typed [`DecodeError`].
1046pub fn decode_header(bytes: &[u8]) -> Result<EnvelopeHeader, DecodeError> {
1047    if bytes.len() < FROZEN_PREFIX_LEN {
1048        return Err(DecodeError::TooShortForPrefix { have: bytes.len() });
1049    }
1050    let ver = bytes[4];
1051    let need = header_len_for_version(ver).ok_or(DecodeError::UnsupportedVersion { ver })?;
1052    if bytes.len() < need {
1053        return Err(DecodeError::TooShortForHeader {
1054            have: bytes.len(),
1055            need,
1056        });
1057    }
1058
1059    let len = u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]);
1060    let ty =
1061        FrameType::from_u8(bytes[5]).ok_or(DecodeError::UnknownFrameType { byte: bytes[5] })?;
1062    let flags = Flags(bytes[6]);
1063    if flags.priority().is_none() {
1064        return Err(DecodeError::ReservedPriorityBits { flags: bytes[6] });
1065    }
1066    let admission_class = flags
1067        .admission_class()
1068        .ok_or(DecodeError::ReservedAdmissionClass { flags: bytes[6] })?;
1069    if admission_class == AdmissionClass::Sheddable
1070        && !matches!(ty, FrameType::Push | FrameType::StreamData)
1071    {
1072        return Err(DecodeError::SheddableIllegalFrameType {
1073            ty,
1074            flags: bytes[6],
1075        });
1076    }
1077    if ty.is_pure_header() && len != 0 {
1078        return Err(DecodeError::PureHeaderFrameWithBody { ty, len });
1079    }
1080    let channel = u16::from_le_bytes([bytes[7], bytes[8]]);
1081    let epoch = u32::from_le_bytes([bytes[9], bytes[10], bytes[11], bytes[12]]);
1082    if channel == 0 && epoch != 0 {
1083        return Err(DecodeError::NonzeroEpochOnControlChannel { epoch });
1084    }
1085    let corr = u64::from_le_bytes([
1086        bytes[13], bytes[14], bytes[15], bytes[16], bytes[17], bytes[18], bytes[19], bytes[20],
1087    ]);
1088
1089    Ok(EnvelopeHeader {
1090        len,
1091        ver,
1092        ty,
1093        flags,
1094        channel,
1095        epoch,
1096        corr,
1097    })
1098}
1099
1100#[cfg(test)]
1101mod tests {
1102    use super::*;
1103
1104    fn hdr(len: u32, ty: FrameType, flags: Flags, channel: u16, corr: u64) -> EnvelopeHeader {
1105        hdr_with_epoch(len, ty, flags, channel, u32::from(channel != 0), corr)
1106    }
1107
1108    fn hdr_with_epoch(
1109        len: u32,
1110        ty: FrameType,
1111        flags: Flags,
1112        channel: u16,
1113        epoch: u32,
1114        corr: u64,
1115    ) -> EnvelopeHeader {
1116        EnvelopeHeader {
1117            len,
1118            ver: PROTOCOL_VERSION,
1119            ty,
1120            flags,
1121            channel,
1122            epoch,
1123            corr,
1124        }
1125    }
1126
1127    /// Modules size their replies against this limit and the TypeScript and
1128    /// Swift clients mirror it, so changing it must be a deliberate edit here
1129    /// as well as in the constant.
1130    #[test]
1131    fn max_delivered_frame_len_is_four_mebibytes_including_the_header() {
1132        assert_eq!(MAX_DELIVERED_FRAME_LEN, 4_194_304);
1133    }
1134
1135    #[test]
1136    fn bind_identity_round_trips_json() {
1137        let identity = BindIdentity::new("opencode", "session-1");
1138
1139        let encoded = serde_json::to_vec(&identity).unwrap();
1140        let decoded: BindIdentity = serde_json::from_slice(&encoded).unwrap();
1141
1142        assert_eq!(decoded, identity);
1143    }
1144
1145    #[test]
1146    fn legacy_bind_identity_project_fields_are_ignored() {
1147        let decoded: BindIdentity = serde_json::from_value(serde_json::json!({
1148            "project_root": "/tmp/project",
1149            "project_id": "pj-a1b2c3d4",
1150            "harness": "opencode",
1151            "session": "session-1"
1152        }))
1153        .unwrap();
1154
1155        assert_eq!(decoded, BindIdentity::new("opencode", "session-1"));
1156    }
1157
1158    #[test]
1159    fn bind_identity_omits_both_project_fields() {
1160        let encoded = serde_json::to_value(BindIdentity::new("opencode", "session-1")).unwrap();
1161
1162        assert!(encoded.get("project_id").is_none());
1163        assert!(encoded.get("project_root").is_none());
1164    }
1165
1166    #[test]
1167    fn wire_crate_version_is_a_numeric_three_component_version() {
1168        let components = SUBC_PROTOCOL_CRATE_VERSION.split('.').collect::<Vec<_>>();
1169
1170        assert!(!SUBC_PROTOCOL_CRATE_VERSION.is_empty());
1171        assert_eq!(components.len(), 3);
1172        assert!(components
1173            .iter()
1174            .all(|component| !component.is_empty() && component.parse::<u64>().is_ok()));
1175    }
1176
1177    #[test]
1178    fn route_target_variants_round_trip_json() {
1179        let targets = [
1180            RouteTarget::ToolProvider {
1181                module_id: "aft".to_string(),
1182            },
1183            RouteTarget::ManagementSurface {
1184                module_id: "memory".to_string(),
1185            },
1186            RouteTarget::InternalService {
1187                module_id: "bus".to_string(),
1188                service_id: "dm".to_string(),
1189            },
1190        ];
1191
1192        for target in targets {
1193            let encoded = serde_json::to_vec(&target).unwrap();
1194            let decoded: RouteTarget = serde_json::from_slice(&encoded).unwrap();
1195            assert_eq!(decoded, target);
1196        }
1197    }
1198
1199    #[test]
1200    fn error_body_round_trips_json() {
1201        let body = ErrorBody {
1202            code: "config_divergence".to_string(),
1203            message: "active config differs".to_string(),
1204            detail: None,
1205        };
1206
1207        let encoded = serde_json::to_vec(&body).unwrap();
1208        let decoded: ErrorBody = serde_json::from_slice(&encoded).unwrap();
1209
1210        assert_eq!(decoded, body);
1211    }
1212
1213    #[test]
1214    fn round_trip_request() {
1215        let h = hdr(
1216            1234,
1217            FrameType::Request,
1218            Flags::new(false, Priority::Interactive, false),
1219            42,
1220            0xDEAD_BEEF_0000_0001,
1221        );
1222        let decoded = decode_header(&h.encode()).unwrap();
1223        assert_eq!(h, decoded);
1224    }
1225
1226    #[test]
1227    fn round_trip_all_frame_types() {
1228        for b in 0u8..=11 {
1229            let ty = FrameType::from_u8(b).unwrap();
1230            let h = hdr(0, ty, Flags::new(false, Priority::Passive, false), 0, 0);
1231            assert_eq!(decode_header(&h.encode()).unwrap().ty, ty);
1232        }
1233    }
1234
1235    #[test]
1236    fn pure_header_frame_has_zero_len() {
1237        // CANCEL carries only header (len = 0) + the target corr.
1238        let h = hdr(
1239            0,
1240            FrameType::Cancel,
1241            Flags::new(false, Priority::Passive, false),
1242            7,
1243            99,
1244        );
1245        let d = decode_header(&h.encode()).unwrap();
1246        assert_eq!(d.len, 0);
1247        assert_eq!(d.corr, 99);
1248    }
1249
1250    #[test]
1251    fn flags_round_trip() {
1252        let f = Flags::new(true, Priority::Background, true)
1253            .with_admission_class(AdmissionClass::Expedite);
1254        assert!(f.is_binary());
1255        assert!(f.is_last());
1256        assert_eq!(f.priority(), Some(Priority::Background));
1257        assert_eq!(f.admission_class(), Some(AdmissionClass::Expedite));
1258        let h = hdr(8, FrameType::StreamData, f, 1, 1);
1259        assert_eq!(decode_header(&h.encode()).unwrap().flags, f);
1260    }
1261
1262    #[test]
1263    fn daemon_origin_flags_decode_and_round_trip() {
1264        let old = hdr(0, FrameType::Error, Flags(0), 7, 1);
1265        let old_decoded = decode_header(&old.encode()).unwrap();
1266        assert!(!old_decoded.flags.is_daemon_origin());
1267
1268        let daemon = hdr(0, FrameType::Error, Flags(0).with_daemon_origin(), 7, 1);
1269        let daemon_decoded = decode_header(&daemon.encode()).unwrap();
1270        assert!(daemon_decoded.flags.is_daemon_origin());
1271        assert_eq!(daemon_decoded.flags.without_daemon_origin(), Flags(0));
1272        assert!(Flags(0).with_daemon_origin().is_daemon_origin());
1273    }
1274
1275    #[test]
1276    fn little_endian_and_frozen_prefix_layout() {
1277        let h = hdr_with_epoch(
1278            0x0403_0201,
1279            FrameType::Request,
1280            Flags(0),
1281            0x0605,
1282            0x0a09_0807,
1283            0x1211_100f_0e0d_0c0b,
1284        );
1285        let buf = h.encode();
1286        assert_eq!(&buf[0..4], &[1, 2, 3, 4]);
1287        assert_eq!(buf[4], PROTOCOL_VERSION);
1288        assert_eq!(&buf[7..9], &[5, 6]);
1289        assert_eq!(&buf[9..13], &[7, 8, 9, 10]);
1290        assert_eq!(&buf[13..21], &[11, 12, 13, 14, 15, 16, 17, 18]);
1291        assert_eq!(buf.len(), HEADER_LEN);
1292    }
1293
1294    #[test]
1295    fn reject_too_short_for_prefix() {
1296        assert_eq!(
1297            decode_header(&[0, 0, 0, 0]),
1298            Err(DecodeError::TooShortForPrefix { have: 4 })
1299        );
1300    }
1301
1302    #[test]
1303    fn reject_too_short_for_header() {
1304        // Valid 5-byte prefix but the v2 header is truncated.
1305        let mut b = [0u8; 10];
1306        b[4] = PROTOCOL_VERSION;
1307        assert_eq!(
1308            decode_header(&b),
1309            Err(DecodeError::TooShortForHeader {
1310                have: 10,
1311                need: HEADER_LEN
1312            })
1313        );
1314    }
1315
1316    #[test]
1317    fn reject_unsupported_version() {
1318        let mut b = [0u8; HEADER_LEN];
1319        b[4] = 1;
1320        assert_eq!(
1321            decode_header(&b),
1322            Err(DecodeError::UnsupportedVersion { ver: 1 })
1323        );
1324    }
1325
1326    #[test]
1327    fn reject_unknown_frame_type() {
1328        let mut b = [0u8; HEADER_LEN];
1329        b[4] = PROTOCOL_VERSION;
1330        b[5] = 99;
1331        assert_eq!(
1332            decode_header(&b),
1333            Err(DecodeError::UnknownFrameType { byte: 99 })
1334        );
1335    }
1336
1337    #[test]
1338    fn subscription_flag_decodes_and_tags_the_request() {
1339        let mut b = [0u8; HEADER_LEN];
1340        b[4] = PROTOCOL_VERSION;
1341        b[5] = FrameType::Request as u8;
1342        b[6] = FLAG_SUBSCRIPTION;
1343        let decoded = decode_header(&b).unwrap();
1344        assert!(decoded.flags.is_subscription());
1345    }
1346
1347    #[test]
1348    fn reject_reserved_priority_bits() {
1349        let mut b = [0u8; HEADER_LEN];
1350        b[4] = PROTOCOL_VERSION;
1351        b[5] = FrameType::Request as u8;
1352        b[6] = 0b0000_0110; // priority bits 1-2 are reserved value 0b11
1353        assert_eq!(
1354            decode_header(&b),
1355            Err(DecodeError::ReservedPriorityBits { flags: 0b0000_0110 })
1356        );
1357    }
1358
1359    #[test]
1360    fn reject_pure_header_frame_with_body_len() {
1361        let h = hdr(
1362            1,
1363            FrameType::Ping,
1364            Flags::new(false, Priority::Passive, false),
1365            0,
1366            1,
1367        );
1368        assert_eq!(
1369            decode_header(&h.encode()),
1370            Err(DecodeError::PureHeaderFrameWithBody {
1371                ty: FrameType::Ping,
1372                len: 1
1373            })
1374        );
1375    }
1376
1377    #[test]
1378    fn epoch_boundaries_round_trip() {
1379        for (channel, epoch) in [(0, 0), (1, 1), (u16::MAX, u32::MAX)] {
1380            let h = hdr_with_epoch(
1381                0,
1382                FrameType::Request,
1383                Flags::new(false, Priority::Passive, false),
1384                channel,
1385                epoch,
1386                9,
1387            );
1388            assert_eq!(decode_header(&h.encode()).unwrap(), h);
1389        }
1390    }
1391
1392    #[test]
1393    fn admission_classes_accept_three_values_and_reject_reserved_value() {
1394        for (ty, admission_class) in [
1395            (FrameType::Request, AdmissionClass::Normal),
1396            (FrameType::Request, AdmissionClass::Expedite),
1397            (FrameType::Push, AdmissionClass::Sheddable),
1398            (FrameType::StreamData, AdmissionClass::Sheddable),
1399        ] {
1400            let flags = Flags::new(false, Priority::Interactive, false)
1401                .with_admission_class(admission_class);
1402            let h = hdr(0, ty, flags, 1, 2);
1403            assert_eq!(decode_header(&h.encode()).unwrap().flags, flags);
1404        }
1405
1406        let mut h = hdr(
1407            0,
1408            FrameType::Push,
1409            Flags::new(false, Priority::Passive, false),
1410            1,
1411            2,
1412        )
1413        .encode();
1414        h[6] |= 0b0011_0000;
1415        assert_eq!(
1416            decode_header(&h),
1417            Err(DecodeError::ReservedAdmissionClass { flags: h[6] })
1418        );
1419    }
1420
1421    #[test]
1422    fn sheddable_rejected_on_every_illegal_frame_type() {
1423        let flags = Flags::new(false, Priority::Passive, false)
1424            .with_admission_class(AdmissionClass::Sheddable);
1425        for ty in [
1426            FrameType::Request,
1427            FrameType::Response,
1428            FrameType::StreamEnd,
1429            FrameType::Error,
1430            FrameType::Cancel,
1431            FrameType::Ping,
1432            FrameType::Pong,
1433            FrameType::Hello,
1434            FrameType::HelloAck,
1435            FrameType::Goodbye,
1436        ] {
1437            let h = hdr(0, ty, flags, 1, 2);
1438            assert_eq!(
1439                decode_header(&h.encode()),
1440                Err(DecodeError::SheddableIllegalFrameType { ty, flags: flags.0 })
1441            );
1442        }
1443    }
1444
1445    #[test]
1446    fn nonzero_epoch_on_control_channel_is_rejected() {
1447        let h = hdr_with_epoch(
1448            0,
1449            FrameType::Request,
1450            Flags::new(false, Priority::Passive, false),
1451            0,
1452            u32::MAX,
1453            2,
1454        );
1455        assert_eq!(
1456            decode_header(&h.encode()),
1457            Err(DecodeError::NonzeroEpochOnControlChannel { epoch: u32::MAX })
1458        );
1459    }
1460}
1461
1462#[cfg(test)]
1463mod launch_nonce_redaction_tests {
1464    use super::*;
1465
1466    #[test]
1467    fn hello_body_debug_never_prints_the_nonce() {
1468        let body = ModuleHelloBody {
1469            manifest: manifest::ModuleManifest::builder("broca", "0.1.0").build(),
1470            protocol_ver: 2,
1471            control_ops: None,
1472            launch_nonce: Some("nonce-f00dfeed1234abcd".to_string()),
1473        };
1474        let printed = format!("{body:?}");
1475        assert!(printed.contains("broca"), "{printed}");
1476        assert!(
1477            !printed.contains("nonce-f00dfeed1234abcd"),
1478            "launch nonce printed: {printed}"
1479        );
1480    }
1481}