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