laser_wire/codes.rs
1// Managed command codes LaserData Cloud reserves. Upstream Apache Iggy uses low
2// codes (1..=605), so LaserData reserves everything from one million up and the
3// two never collide. Within that, each feature owns a 100-wide block:
4//
5// 1_000_000..=1_000_099 internal commands (capability probe, backend hello, client metadata, batch)
6// 1_000_100..=1_000_199 authorization & system management (whoami, roles, bindings) [first management band]
7// 1_000_200..=1_000_299 query family (query, projection/schema browse)
8// 1_000_300..=1_000_399 key-value store
9// 1_000_400..=1_000_499 forks (experimental)
10// 1_000_500..=1_000_599 agentic memory (reserved facade: remember/recall/improve/forget)
11// 1_000_600..=1_000_699 knowledge graph (traverse, neighbors, upsert)
12// 1_000_700..=1_000_799 agent and workflow control (submit/cancel/status/list)
13//
14// A query is a non-replicated read, so it is served off the log via these
15// managed commands instead of a topic round-trip. Raw Apache Iggy rejects them
16// with `InvalidCommand`. The values are a pinned wire contract, enforced by
17// the constants test.
18
19/// Base of LaserData's reserved managed-command range.
20pub const AGDX_COMMAND_BASE: u32 = 1_000_000;
21// Capability probe (internal block): LaserData Cloud answers it,
22// raw Apache Iggy rejects it.
23/// Managed command code: capability probe.
24pub const AGDX_HELLO_CODE: u32 = AGDX_COMMAND_BASE;
25/// Internal command code: the managed backend announces its served capabilities
26/// (an `OpVersions`) to the streaming server over their private socket on connect. The
27/// streaming server caches it and answers the client `AGDX_HELLO` with it, so the binary
28/// feature bits and the HTTP capability flags cannot drift from what the backend
29/// actually serves (the backend is the single source of its own truth). Not a
30/// client-facing code, a client never sends it.
31pub const AGDX_BACKEND_HELLO_CODE: u32 = AGDX_COMMAND_BASE + 1;
32/// Fork-native command code: set this connection's advertised metadata (the
33/// transport-level discovery primitive). Handled by the streaming server itself,
34/// not forwarded to the plane, because it touches per-connection session state the
35/// plane never sees. Connection-scoped and cleared on disconnect.
36pub const AGDX_SET_CLIENT_METADATA_CODE: u32 = AGDX_COMMAND_BASE + 2;
37/// Fork-native command code: list every connection with its advertised metadata.
38/// The discovery read, answered by the streaming server from its connection table.
39/// A LaserData-owned reply ([`crate::clients::ClientMetadataList`]), never the
40/// upstream Apache Iggy `get_clients` shape, so an Apache Iggy SDK against LaserData
41/// Cloud and the metadata read stay byte-independent.
42pub const AGDX_GET_CLIENTS_METADATA_CODE: u32 = AGDX_COMMAND_BASE + 3;
43/// Managed command code: the mixed-operation batch. The request body is a CBOR
44/// [`BatchRequest`](crate::batch::BatchRequest) carrying up to
45/// [`MAX_BATCH_OPS`](crate::limits::MAX_BATCH_OPS) managed requests, each with
46/// its own code and payload. The reply a [`BatchReply`](crate::batch::BatchReply)
47/// with each op's own reply bytes in order. One round trip amortized over
48/// several ops, per-op results, explicitly NOT atomic. A nested batch is
49/// rejected. An old backend answers the unknown code with `CommandError`,
50/// decoded client-side as the typed unsupported, so no capability bit is
51/// needed.
52pub const AGDX_BATCH_CODE: u32 = AGDX_COMMAND_BASE + 20;
53
54// Authorization and system-management band (1_000_100..=1_000_199). Handled by
55// the streaming server itself, not forwarded to the plane, the same class as
56// `AGDX_SET_CLIENT_METADATA`. Reads +0..+3, writes +4..+6.
57/// Base of the authorization and system-management band (first management band).
58pub const AGDX_AUTHZ_BASE: u32 = AGDX_COMMAND_BASE + 100;
59/// Managed command code: read the caller's own effective capabilities (self-read).
60pub const AGDX_AUTHZ_WHOAMI_CODE: u32 = AGDX_AUTHZ_BASE;
61/// Managed command code: list defined roles (optionally filtered).
62pub const AGDX_AUTHZ_LIST_ROLES_CODE: u32 = AGDX_AUTHZ_BASE + 1;
63/// Managed command code: read one role by name.
64pub const AGDX_AUTHZ_GET_ROLE_CODE: u32 = AGDX_AUTHZ_BASE + 2;
65/// Managed command code: read one user's bound role names.
66pub const AGDX_AUTHZ_GET_BINDINGS_CODE: u32 = AGDX_AUTHZ_BASE + 3;
67/// Managed command code: define or replace a role (upsert).
68pub const AGDX_AUTHZ_DEFINE_ROLE_CODE: u32 = AGDX_AUTHZ_BASE + 4;
69/// Managed command code: delete a role by name.
70pub const AGDX_AUTHZ_DELETE_ROLE_CODE: u32 = AGDX_AUTHZ_BASE + 5;
71/// Managed command code: bind roles to a user (replace the user's role set).
72pub const AGDX_AUTHZ_BIND_ROLES_CODE: u32 = AGDX_AUTHZ_BASE + 6;
73/// Managed command code: read the authorization change history (audit).
74pub const AGDX_AUTHZ_HISTORY_CODE: u32 = AGDX_AUTHZ_BASE + 7;
75
76// Query family block (1_000_200..=1_000_299). Direct query ops reserve the
77// +0x decade, projection browse the +1x decade, schema browse the +2x decade.
78/// Base of the query managed-command block.
79pub const AGDX_QUERY_BASE: u32 = AGDX_COMMAND_BASE + 200;
80// Execute a `Query`: request body is a CBOR `QueryEnvelope`, reply a CBOR
81// `QueryReply`, off the log over the managed command channel.
82/// Managed command code: execute a query.
83pub const AGDX_QUERY_CODE: u32 = AGDX_QUERY_BASE;
84// Browse the projection registry (read-only). Get one projection by id (request
85// `GetProjection`) or list them all (request `ListProjections`), reply a CBOR
86// `BrowseReply`.
87/// Managed command code: browse one projection.
88pub const AGDX_GET_PROJECTION_CODE: u32 = AGDX_QUERY_BASE + 10;
89/// Managed command code: list projections.
90pub const AGDX_LIST_PROJECTIONS_CODE: u32 = AGDX_QUERY_BASE + 11;
91/// Managed command code: browse one registered schema by id.
92pub const AGDX_GET_SCHEMA_CODE: u32 = AGDX_QUERY_BASE + 20;
93/// Managed command code: list registered schemas.
94pub const AGDX_LIST_SCHEMAS_CODE: u32 = AGDX_QUERY_BASE + 21;
95/// Managed command code: advisory next free schema id.
96pub const AGDX_REGISTER_SCHEMA_CODE: u32 = AGDX_QUERY_BASE + 22;
97/// Managed command code: decode one payload under a registered schema id.
98pub const AGDX_DECODE_RECORD_CODE: u32 = AGDX_QUERY_BASE + 23;
99
100// Key-value command block (1_000_300..=1_000_399). Each op is its own managed
101// command, forwarded to LaserData Cloud over the same local channel the query path
102// uses, with the authenticated identity stamped in.
103/// Base of the KV managed-command block.
104pub const AGDX_KV_BASE: u32 = AGDX_COMMAND_BASE + 300;
105/// Managed command code: KV get.
106pub const AGDX_KV_GET_CODE: u32 = AGDX_KV_BASE;
107/// Managed command code: KV set.
108pub const AGDX_KV_SET_CODE: u32 = AGDX_KV_BASE + 1;
109/// Managed command code: KV scan.
110pub const AGDX_KV_SCAN_CODE: u32 = AGDX_KV_BASE + 2;
111/// Managed command code: KV delete one.
112pub const AGDX_KV_DELETE_CODE: u32 = AGDX_KV_BASE + 3;
113/// Managed command code: KV bulk delete by filter.
114pub const AGDX_KV_DELETE_MANY_CODE: u32 = AGDX_KV_BASE + 4;
115/// Managed command code: list the caller's namespaces.
116pub const AGDX_KV_NAMESPACES_CODE: u32 = AGDX_KV_BASE + 5;
117/// Managed command code: compare-and-swap a key (optimistic concurrency).
118/// Additive over [`KV_OP_VERSION`] 1: a backend or server that does not serve it
119/// rejects the code, which the client surfaces as an unsupported error. Whether
120/// it is served is advertised by the `kv_cas` capability flag.
121pub const AGDX_KV_CAS_CODE: u32 = AGDX_KV_BASE + 6;
122/// Managed command code: test presence and read metadata without the value
123/// (the formal `EXISTS` object primitive).
124pub const AGDX_KV_EXISTS_CODE: u32 = AGDX_KV_BASE + 7;
125/// Managed command code: set, refresh, or clear a key's expiry in place without
126/// rewriting its value (the formal `EXPIRE` primitive).
127pub const AGDX_KV_EXPIRE_CODE: u32 = AGDX_KV_BASE + 8;
128/// Managed command code: apply a merge patch to a structured value (the formal
129/// `PATCH` primitive).
130pub const AGDX_KV_PATCH_CODE: u32 = AGDX_KV_BASE + 9;
131/// Managed command code: acquire an advisory lease on a key (the formal `LEASE`
132/// primitive). A backend that cannot serve it returns a clean unsupported error.
133pub const AGDX_KV_LEASE_CODE: u32 = AGDX_KV_BASE + 10;
134/// Managed command code: release an advisory lease early (the formal `RELEASE`
135/// primitive).
136pub const AGDX_KV_RELEASE_CODE: u32 = AGDX_KV_BASE + 11;
137/// Managed command code: fenced compare-and-swap. Applies the CAS only while the
138/// task's fence sequence still equals the presented token (the at-most-one
139/// effective-writer gate). Additive over [`KV_OP_VERSION`] 1: a backend or server
140/// that does not serve it rejects the code, which the client surfaces as an
141/// unsupported error. Whether it is served is advertised by the `kv_cas_fenced`
142/// capability flag.
143pub const AGDX_KV_CAS_FENCED_CODE: u32 = AGDX_KV_BASE + 12;
144/// Managed command code: copy the value at one key to another key (possibly in
145/// another namespace) in a single backend transaction. Reuses the kv outcomes:
146/// `Committed` on success, `NotFound` when the source is absent.
147pub const AGDX_KV_COPY_CODE: u32 = AGDX_KV_BASE + 13;
148/// Managed command code: move the value at one key to another key. Copy plus
149/// delete of the source, one backend transaction, the same outcomes.
150pub const AGDX_KV_MOVE_CODE: u32 = AGDX_KV_BASE + 14;
151
152// Fork block (1_000_400..): agentic copy-on-write branches of the materialized
153// read model. Each op is its own managed command, forwarded over the same bridge.
154// Experimental: the fork surface is not a native Iggy topic fork and may be
155// superseded by a native shared-log implementation.
156/// Base of the fork managed-command block.
157pub const AGDX_FORK_BASE: u32 = AGDX_COMMAND_BASE + 400;
158/// Managed command code: open a fork.
159pub const AGDX_FORK_CREATE_CODE: u32 = AGDX_FORK_BASE;
160/// Managed command code: squash a fork.
161pub const AGDX_FORK_DELETE_CODE: u32 = AGDX_FORK_BASE + 1;
162/// Managed command code: promote a fork onto the trunk.
163pub const AGDX_FORK_PROMOTE_CODE: u32 = AGDX_FORK_BASE + 2;
164/// Managed command code: list forks.
165pub const AGDX_FORK_LIST_CODE: u32 = AGDX_FORK_BASE + 3;
166/// Managed command code: write a speculative fork row.
167pub const AGDX_FORK_PUT_CODE: u32 = AGDX_FORK_BASE + 4;
168
169// Knowledge graph block (1_000_600..=1_000_699). Traversal reads and the
170// projector's node/edge upsert. Whether they are served is advertised by the
171// `managed_graph` capability flag. Agentic memory is not a wire band of its own:
172// the four-verb memory API is an SDK facade that composes `publish`, the query
173// block, and this graph block, so there is one managed read/write model, not a
174// parallel one.
175/// Base of the graph managed-command block.
176pub const AGDX_GRAPH_BASE: u32 = AGDX_COMMAND_BASE + 600;
177/// Managed command code: run a graph traversal.
178pub const AGDX_GRAPH_QUERY_CODE: u32 = AGDX_GRAPH_BASE;
179/// Managed command code: write nodes and edges (the projector path).
180pub const AGDX_GRAPH_UPSERT_CODE: u32 = AGDX_GRAPH_BASE + 1;
181/// Managed command code: one-hop neighbor read.
182pub const AGDX_GRAPH_NEIGHBORS_CODE: u32 = AGDX_GRAPH_BASE + 2;
183
184// Agent and workflow control band (1_000_700..=1_000_799). Plane-served control
185// operations over the agent and workflow surfaces, forwarded over the same
186// bridge. Distinct from the agent ENVELOPE (the on-the-log message form, carried
187// by `agdx.av`, not a command code): this band is the request-reply control
188// surface a coordinator drives. Whether it is served is advertised by the
189// `agent_workflow` feature bit.
190/// Base of the agent and workflow control band.
191pub const AGDX_AGENT_BASE: u32 = AGDX_COMMAND_BASE + 700;
192/// Managed command code: submit a task to an agent or workflow.
193pub const AGDX_AGENT_SUBMIT_CODE: u32 = AGDX_AGENT_BASE;
194/// Managed command code: cancel a submitted task.
195pub const AGDX_AGENT_CANCEL_CODE: u32 = AGDX_AGENT_BASE + 1;
196/// Managed command code: read a task's status.
197pub const AGDX_AGENT_STATUS_CODE: u32 = AGDX_AGENT_BASE + 2;
198/// Managed command code: list tasks.
199pub const AGDX_AGENT_LIST_CODE: u32 = AGDX_AGENT_BASE + 3;
200
201// Per-surface op-schema versions, stamped on every request envelope (or, for
202// the agent surface, carried as the `agdx.av` header). A peer rejects a payload
203// it cannot decode rather than mis-reading a skewed schema.
204/// Wire version of the authorization command envelopes.
205pub const AUTHZ_OP_VERSION: u32 = 1;
206/// Wire version of the query envelope.
207pub const QUERY_OP_VERSION: u32 = 1;
208/// Wire version of the control envelope.
209pub const CONTROL_OP_VERSION: u32 = 1;
210/// Wire version of the KV op envelopes.
211pub const KV_OP_VERSION: u32 = 1;
212/// Wire version of the fork op envelopes.
213pub const FORK_OP_VERSION: u32 = 1;
214/// Wire version of the graph op envelopes.
215pub const GRAPH_OP_VERSION: u32 = 1;
216/// Wire version of the agent and workflow control-band envelopes. Distinct from
217/// [`AGENT_OP_VERSION`] (the on-the-log envelope), this versions the request and
218/// reply types of the control band.
219pub const AGENT_WORKFLOW_OP_VERSION: u32 = 1;
220
221/// Wire version of the mixed-operation batch request and reply
222/// ([`crate::batch`]). The items inside version themselves: each rides its own
223/// op's request frame with that op's own `v`.
224pub const BATCH_OP_VERSION: u32 = 1;
225
226/// Versions the change-feed record (`ChangeRecord.v`). Checked by consumers of
227/// the changes topic. The feed is advertised by the `WATCH` feature bit.
228pub const CHANGE_OP_VERSION: u32 = 1;
229/// Wire version of the client-metadata discovery request and reply
230/// ([`crate::clients`]).
231pub const CLIENT_METADATA_OP_VERSION: u32 = 1;
232/// Wire version of the agent presence body ([`crate::agent::AgentPresence`]) an
233/// agent advertises in its connection metadata. Carried in the body's own `v`
234/// field, not out-of-band, because presence rides the opaque connection-metadata
235/// bytes with no envelope header to select a decoder.
236pub const PRESENCE_OP_VERSION: u32 = 1;
237/// Wire version of the agent envelope (the Agent Data Exchange Protocol). Carried
238/// out-of-band as the typed `agdx.av` header, never inside the body: a durable
239/// log record must select its decoder before any body byte is read.
240pub const AGENT_OP_VERSION: u32 = 1;
241
242/// Whether a managed command can change plane-owned state and therefore must
243/// carry a stable operation identity across transport retries.
244pub const fn is_idempotent_managed_request(code: u32) -> bool {
245 matches!(
246 code,
247 AGDX_BATCH_CODE
248 | AGDX_KV_SET_CODE
249 | AGDX_KV_DELETE_CODE
250 | AGDX_KV_DELETE_MANY_CODE
251 | AGDX_KV_CAS_CODE
252 | AGDX_KV_EXPIRE_CODE
253 | AGDX_KV_PATCH_CODE
254 | AGDX_KV_LEASE_CODE
255 | AGDX_KV_RELEASE_CODE
256 | AGDX_KV_CAS_FENCED_CODE
257 | AGDX_KV_COPY_CODE
258 | AGDX_KV_MOVE_CODE
259 | AGDX_FORK_CREATE_CODE
260 | AGDX_FORK_DELETE_CODE
261 | AGDX_FORK_PROMOTE_CODE
262 | AGDX_FORK_PUT_CODE
263 | AGDX_GRAPH_UPSERT_CODE
264 | AGDX_AGENT_SUBMIT_CODE
265 | AGDX_AGENT_CANCEL_CODE
266 )
267}