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/// Fork-native command code: submit one public checkpoint mutation to Iggy metadata.
54pub const AGDX_CHECKPOINT_CODE: u32 = AGDX_COMMAND_BASE + 21;
55/// Fork-native command code: read one destination and its checkpoint status.
56pub const AGDX_DESTINATION_GET_CODE: u32 = AGDX_COMMAND_BASE + 22;
57/// Fork-native command code: list destinations and their checkpoint status.
58pub const AGDX_DESTINATION_LIST_CODE: u32 = AGDX_COMMAND_BASE + 23;
59/// Fork-native command code: list explicit query-route declarations.
60pub const AGDX_QUERY_ROUTE_LIST_CODE: u32 = AGDX_COMMAND_BASE + 24;
61
62// Authorization and system-management band (1_000_100..=1_000_199). Handled by
63// the streaming server itself, not forwarded to the plane, the same class as
64// `AGDX_SET_CLIENT_METADATA`. Reads +0..+3, writes +4..+6.
65/// Base of the authorization and system-management band (first management band).
66pub const AGDX_AUTHZ_BASE: u32 = AGDX_COMMAND_BASE + 100;
67/// Managed command code: read the caller's own effective capabilities (self-read).
68pub const AGDX_AUTHZ_WHOAMI_CODE: u32 = AGDX_AUTHZ_BASE;
69/// Managed command code: list defined roles (optionally filtered).
70pub const AGDX_AUTHZ_LIST_ROLES_CODE: u32 = AGDX_AUTHZ_BASE + 1;
71/// Managed command code: read one role by name.
72pub const AGDX_AUTHZ_GET_ROLE_CODE: u32 = AGDX_AUTHZ_BASE + 2;
73/// Managed command code: read one user's bound role names.
74pub const AGDX_AUTHZ_GET_BINDINGS_CODE: u32 = AGDX_AUTHZ_BASE + 3;
75/// Managed command code: define or replace a role (upsert).
76pub const AGDX_AUTHZ_DEFINE_ROLE_CODE: u32 = AGDX_AUTHZ_BASE + 4;
77/// Managed command code: delete a role by name.
78pub const AGDX_AUTHZ_DELETE_ROLE_CODE: u32 = AGDX_AUTHZ_BASE + 5;
79/// Managed command code: bind roles to a user (replace the user's role set).
80pub const AGDX_AUTHZ_BIND_ROLES_CODE: u32 = AGDX_AUTHZ_BASE + 6;
81/// Managed command code: read the authorization change history (audit).
82pub const AGDX_AUTHZ_HISTORY_CODE: u32 = AGDX_AUTHZ_BASE + 7;
83
84// Query family block (1_000_200..=1_000_299). Direct query ops reserve the
85// +0x decade, projection browse the +1x decade, schema browse the +2x decade.
86/// Base of the query managed-command block.
87pub const AGDX_QUERY_BASE: u32 = AGDX_COMMAND_BASE + 200;
88// Execute a `Query`: request body is a CBOR `QueryEnvelope`, reply a CBOR
89// `QueryReply`, off the log over the managed command channel.
90/// Managed command code: execute a query.
91pub const AGDX_QUERY_CODE: u32 = AGDX_QUERY_BASE;
92/// Managed command code: retrieve the next page of an executing query.
93pub const AGDX_QUERY_PAGE_CODE: u32 = AGDX_QUERY_BASE + 1;
94/// Managed command code: cancel an executing query.
95pub const AGDX_QUERY_CANCEL_CODE: u32 = AGDX_QUERY_BASE + 2;
96/// Managed command code: read query execution status.
97pub const AGDX_QUERY_STATUS_CODE: u32 = AGDX_QUERY_BASE + 3;
98// Browse the projection registry (read-only). Get one projection by id (request
99// `GetProjection`) or list them all (request `ListProjections`), reply a CBOR
100// `BrowseReply`.
101/// Managed command code: browse one projection.
102pub const AGDX_GET_PROJECTION_CODE: u32 = AGDX_QUERY_BASE + 10;
103/// Managed command code: list projections.
104pub const AGDX_LIST_PROJECTIONS_CODE: u32 = AGDX_QUERY_BASE + 11;
105/// Managed command code: browse one registered schema by id.
106pub const AGDX_GET_SCHEMA_CODE: u32 = AGDX_QUERY_BASE + 20;
107/// Managed command code: list registered schemas.
108pub const AGDX_LIST_SCHEMAS_CODE: u32 = AGDX_QUERY_BASE + 21;
109/// Managed command code: advisory next free schema id.
110pub const AGDX_REGISTER_SCHEMA_CODE: u32 = AGDX_QUERY_BASE + 22;
111/// Managed command code: decode one payload under a registered schema id.
112pub const AGDX_DECODE_RECORD_CODE: u32 = AGDX_QUERY_BASE + 23;
113
114// Key-value command block (1_000_300..=1_000_399). Each op is its own managed
115// command, forwarded to LaserData Cloud over the same local channel the query path
116// uses, with the authenticated identity stamped in.
117/// Base of the KV managed-command block.
118pub const AGDX_KV_BASE: u32 = AGDX_COMMAND_BASE + 300;
119/// Managed command code: KV get.
120pub const AGDX_KV_GET_CODE: u32 = AGDX_KV_BASE;
121/// Managed command code: KV set.
122pub const AGDX_KV_SET_CODE: u32 = AGDX_KV_BASE + 1;
123/// Managed command code: KV scan.
124pub const AGDX_KV_SCAN_CODE: u32 = AGDX_KV_BASE + 2;
125/// Managed command code: KV delete one.
126pub const AGDX_KV_DELETE_CODE: u32 = AGDX_KV_BASE + 3;
127/// Managed command code: KV bulk delete by filter.
128pub const AGDX_KV_DELETE_MANY_CODE: u32 = AGDX_KV_BASE + 4;
129/// Managed command code: list the caller's namespaces.
130pub const AGDX_KV_NAMESPACES_CODE: u32 = AGDX_KV_BASE + 5;
131/// Managed command code: compare-and-swap a key (optimistic concurrency).
132/// Additive over [`KV_OP_VERSION`] 1: a backend or server that does not serve it
133/// rejects the code, which the client surfaces as an unsupported error. Whether
134/// it is served is advertised by the `kv_cas` capability flag.
135pub const AGDX_KV_CAS_CODE: u32 = AGDX_KV_BASE + 6;
136/// Managed command code: test presence and read metadata without the value
137/// (the formal `EXISTS` object primitive).
138pub const AGDX_KV_EXISTS_CODE: u32 = AGDX_KV_BASE + 7;
139/// Managed command code: set, refresh, or clear a key's expiry in place without
140/// rewriting its value (the formal `EXPIRE` primitive).
141pub const AGDX_KV_EXPIRE_CODE: u32 = AGDX_KV_BASE + 8;
142/// Managed command code: apply a merge patch to a structured value (the formal
143/// `PATCH` primitive).
144pub const AGDX_KV_PATCH_CODE: u32 = AGDX_KV_BASE + 9;
145/// Managed command code: acquire a revocable lease on a key (the formal `LEASE`
146/// primitive). Carries the stable holder identity and an optional delegated
147/// subject at [`KV_LEASE_OP_VERSION`]. Served only by a deployment advertising
148/// the `KV_FENCED_LEASES` feature bit; a backend that cannot serve it returns a
149/// clean unsupported error.
150pub const AGDX_KV_LEASE_CODE: u32 = AGDX_KV_BASE + 10;
151/// Managed command code: release a held lease early (the formal `RELEASE`
152/// primitive). Requires the same holder and the current fence token, validated
153/// against the fence sequence, never the resetting lease-row version.
154pub const AGDX_KV_RELEASE_CODE: u32 = AGDX_KV_BASE + 11;
155/// Managed command code: fenced compare-and-swap. Applies the CAS in one
156/// backend transaction that also requires a live lease at the request's
157/// coordination namespace and key plus a fence sequence equal to the presented
158/// token (the at-most-one effective-writer gate). Rides
159/// [`KV_LEASE_OP_VERSION`]; served only under the `KV_FENCED_LEASES` feature
160/// bit, which subsumes the older fence-only `kv_cas_fenced` flag.
161pub const AGDX_KV_CAS_FENCED_CODE: u32 = AGDX_KV_BASE + 12;
162/// Managed command code: copy the value at one key to another key (possibly in
163/// another namespace) in a single backend transaction. Reuses the kv outcomes:
164/// `Committed` on success, `NotFound` when the source is absent.
165pub const AGDX_KV_COPY_CODE: u32 = AGDX_KV_BASE + 13;
166/// Managed command code: move the value at one key to another key. Copy plus
167/// delete of the source, one backend transaction, the same outcomes.
168pub const AGDX_KV_MOVE_CODE: u32 = AGDX_KV_BASE + 14;
169/// Managed command code: extend a held lease without changing its token (the
170/// formal `RENEW` primitive). Requires the same holder and subject, a live
171/// lease, and the current fence token; never bumps the fence. Rides
172/// [`KV_LEASE_OP_VERSION`] under the `KV_FENCED_LEASES` feature bit.
173pub const AGDX_KV_LEASE_RENEW_CODE: u32 = AGDX_KV_BASE + 15;
174
175// Fork block (1_000_400..): agentic copy-on-write branches of the materialized
176// read model. Each op is its own managed command, forwarded over the same bridge.
177// Experimental: the fork surface is not a native Iggy topic fork and may be
178// superseded by a native shared-log implementation.
179/// Base of the fork managed-command block.
180pub const AGDX_FORK_BASE: u32 = AGDX_COMMAND_BASE + 400;
181/// Managed command code: open a fork.
182pub const AGDX_FORK_CREATE_CODE: u32 = AGDX_FORK_BASE;
183/// Managed command code: squash a fork.
184pub const AGDX_FORK_DELETE_CODE: u32 = AGDX_FORK_BASE + 1;
185/// Managed command code: promote a fork onto the trunk.
186pub const AGDX_FORK_PROMOTE_CODE: u32 = AGDX_FORK_BASE + 2;
187/// Managed command code: list forks.
188pub const AGDX_FORK_LIST_CODE: u32 = AGDX_FORK_BASE + 3;
189/// Managed command code: write a speculative fork row.
190pub const AGDX_FORK_PUT_CODE: u32 = AGDX_FORK_BASE + 4;
191
192// Knowledge graph block (1_000_600..=1_000_699). Traversal reads and the
193// projector's node/edge upsert. Whether they are served is advertised by the
194// `managed_graph` capability flag. Agentic memory is not a wire band of its own:
195// the four-verb memory API is an SDK facade that composes `publish`, the query
196// block, and this graph block, so there is one managed read/write model, not a
197// parallel one.
198/// Base of the graph managed-command block.
199pub const AGDX_GRAPH_BASE: u32 = AGDX_COMMAND_BASE + 600;
200/// Managed command code: run a graph traversal.
201pub const AGDX_GRAPH_QUERY_CODE: u32 = AGDX_GRAPH_BASE;
202/// Managed command code: write nodes and edges (the projector path).
203pub const AGDX_GRAPH_UPSERT_CODE: u32 = AGDX_GRAPH_BASE + 1;
204/// Managed command code: one-hop neighbor read.
205pub const AGDX_GRAPH_NEIGHBORS_CODE: u32 = AGDX_GRAPH_BASE + 2;
206
207// Agent and workflow control band (1_000_700..=1_000_799). Plane-served control
208// operations over the agent and workflow surfaces, forwarded over the same
209// bridge. Distinct from the agent ENVELOPE (the on-the-log message form, carried
210// by `agdx.av`, not a command code): this band is the request-reply control
211// surface a coordinator drives. Whether it is served is advertised by the
212// `agent_workflow` feature bit.
213/// Base of the agent and workflow control band.
214pub const AGDX_AGENT_BASE: u32 = AGDX_COMMAND_BASE + 700;
215/// Managed command code: submit a task to an agent or workflow.
216pub const AGDX_AGENT_SUBMIT_CODE: u32 = AGDX_AGENT_BASE;
217/// Managed command code: cancel a submitted task.
218pub const AGDX_AGENT_CANCEL_CODE: u32 = AGDX_AGENT_BASE + 1;
219/// Managed command code: read a task's status.
220pub const AGDX_AGENT_STATUS_CODE: u32 = AGDX_AGENT_BASE + 2;
221/// Managed command code: list tasks.
222pub const AGDX_AGENT_LIST_CODE: u32 = AGDX_AGENT_BASE + 3;
223
224// Per-surface op-schema versions, stamped on every request envelope (or, for
225// the agent surface, carried as the `agdx.av` header). A peer rejects a payload
226// it cannot decode rather than mis-reading a skewed schema.
227/// Wire version of the authorization command envelopes.
228pub const AUTHZ_OP_VERSION: u32 = 1;
229/// Wire version of the query envelope.
230pub const QUERY_OP_VERSION: u32 = 1;
231/// Wire version of the control envelope.
232pub const CONTROL_OP_VERSION: u32 = 1;
233/// Wire version of the KV op envelopes.
234pub const KV_OP_VERSION: u32 = 1;
235/// Wire version of the fenced-lease op family: `KvLease`, `KvLeaseRenew`,
236/// `KvRelease`, and `KvCasFenced`. Bumped past [`KV_OP_VERSION`] by the
237/// holder-identity reshape so a v1 payload and a v2 payload can never be
238/// mistaken for each other: the reshaped fields are required with no serde
239/// defaults (an old payload fails decode) and [`crate::validate::Validate`]
240/// rejects any other `v` (a typed error, fail-closed). The rest of the KV
241/// surface stays at [`KV_OP_VERSION`].
242pub const KV_LEASE_OP_VERSION: u32 = 2;
243/// Wire version of the fork op envelopes.
244pub const FORK_OP_VERSION: u32 = 1;
245/// Wire version of the graph op envelopes.
246pub const GRAPH_OP_VERSION: u32 = 1;
247/// Wire version of the agent and workflow control-band envelopes. Distinct from
248/// [`AGENT_OP_VERSION`] (the on-the-log envelope), this versions the request and
249/// reply types of the control band.
250pub const AGENT_WORKFLOW_OP_VERSION: u32 = 1;
251
252/// Wire version of the mixed-operation batch request and reply
253/// ([`crate::batch`]). The items inside version themselves: each rides its own
254/// op's request frame with that op's own `v`.
255pub const BATCH_OP_VERSION: u32 = 1;
256
257/// Versions the change-feed record (`ChangeRecord.v`). Checked by consumers of
258/// the changes topic. The feed is advertised by the `WATCH` feature bit.
259pub const CHANGE_OP_VERSION: u32 = 1;
260/// Wire version of the client-metadata discovery request and reply
261/// ([`crate::clients`]).
262pub const CLIENT_METADATA_OP_VERSION: u32 = 1;
263/// Wire version of public checkpoint mutation requests and status replies.
264pub const CHECKPOINT_OP_VERSION: u32 = 1;
265/// Wire version of the agent presence body ([`crate::agent::AgentPresence`]) an
266/// agent advertises in its connection metadata. Carried in the body's own `v`
267/// field, not out-of-band, because presence rides the opaque connection-metadata
268/// bytes with no envelope header to select a decoder.
269pub const PRESENCE_OP_VERSION: u32 = 1;
270/// Wire version of the agent envelope (the Agent Data Exchange Protocol). Carried
271/// out-of-band as the typed `agdx.av` header, never inside the body: a durable
272/// log record must select its decoder before any body byte is read.
273pub const AGENT_OP_VERSION: u32 = 1;
274
275/// Whether a managed command can change plane-owned state and therefore must
276/// carry a stable operation identity across transport retries.
277pub const fn is_idempotent_managed_request(code: u32) -> bool {
278 matches!(
279 code,
280 AGDX_BATCH_CODE
281 | AGDX_KV_SET_CODE
282 | AGDX_KV_DELETE_CODE
283 | AGDX_KV_DELETE_MANY_CODE
284 | AGDX_KV_CAS_CODE
285 | AGDX_KV_EXPIRE_CODE
286 | AGDX_KV_PATCH_CODE
287 | AGDX_KV_LEASE_CODE
288 | AGDX_KV_LEASE_RENEW_CODE
289 | AGDX_KV_RELEASE_CODE
290 | AGDX_KV_CAS_FENCED_CODE
291 | AGDX_KV_COPY_CODE
292 | AGDX_KV_MOVE_CODE
293 | AGDX_FORK_CREATE_CODE
294 | AGDX_FORK_DELETE_CODE
295 | AGDX_FORK_PROMOTE_CODE
296 | AGDX_FORK_PUT_CODE
297 | AGDX_GRAPH_UPSERT_CODE
298 | AGDX_AGENT_SUBMIT_CODE
299 | AGDX_AGENT_CANCEL_CODE
300 | AGDX_CHECKPOINT_CODE
301 )
302}