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 an advisory lease on a key (the formal `LEASE`
146/// primitive). A backend that cannot serve it returns a clean unsupported error.
147pub const AGDX_KV_LEASE_CODE: u32 = AGDX_KV_BASE + 10;
148/// Managed command code: release an advisory lease early (the formal `RELEASE`
149/// primitive).
150pub const AGDX_KV_RELEASE_CODE: u32 = AGDX_KV_BASE + 11;
151/// Managed command code: fenced compare-and-swap. Applies the CAS only while the
152/// task's fence sequence still equals the presented token (the at-most-one
153/// effective-writer gate). Additive over [`KV_OP_VERSION`] 1: a backend or server
154/// that does not serve it rejects the code, which the client surfaces as an
155/// unsupported error. Whether it is served is advertised by the `kv_cas_fenced`
156/// capability flag.
157pub const AGDX_KV_CAS_FENCED_CODE: u32 = AGDX_KV_BASE + 12;
158/// Managed command code: copy the value at one key to another key (possibly in
159/// another namespace) in a single backend transaction. Reuses the kv outcomes:
160/// `Committed` on success, `NotFound` when the source is absent.
161pub const AGDX_KV_COPY_CODE: u32 = AGDX_KV_BASE + 13;
162/// Managed command code: move the value at one key to another key. Copy plus
163/// delete of the source, one backend transaction, the same outcomes.
164pub const AGDX_KV_MOVE_CODE: u32 = AGDX_KV_BASE + 14;
165
166// Fork block (1_000_400..): agentic copy-on-write branches of the materialized
167// read model. Each op is its own managed command, forwarded over the same bridge.
168// Experimental: the fork surface is not a native Iggy topic fork and may be
169// superseded by a native shared-log implementation.
170/// Base of the fork managed-command block.
171pub const AGDX_FORK_BASE: u32 = AGDX_COMMAND_BASE + 400;
172/// Managed command code: open a fork.
173pub const AGDX_FORK_CREATE_CODE: u32 = AGDX_FORK_BASE;
174/// Managed command code: squash a fork.
175pub const AGDX_FORK_DELETE_CODE: u32 = AGDX_FORK_BASE + 1;
176/// Managed command code: promote a fork onto the trunk.
177pub const AGDX_FORK_PROMOTE_CODE: u32 = AGDX_FORK_BASE + 2;
178/// Managed command code: list forks.
179pub const AGDX_FORK_LIST_CODE: u32 = AGDX_FORK_BASE + 3;
180/// Managed command code: write a speculative fork row.
181pub const AGDX_FORK_PUT_CODE: u32 = AGDX_FORK_BASE + 4;
182
183// Knowledge graph block (1_000_600..=1_000_699). Traversal reads and the
184// projector's node/edge upsert. Whether they are served is advertised by the
185// `managed_graph` capability flag. Agentic memory is not a wire band of its own:
186// the four-verb memory API is an SDK facade that composes `publish`, the query
187// block, and this graph block, so there is one managed read/write model, not a
188// parallel one.
189/// Base of the graph managed-command block.
190pub const AGDX_GRAPH_BASE: u32 = AGDX_COMMAND_BASE + 600;
191/// Managed command code: run a graph traversal.
192pub const AGDX_GRAPH_QUERY_CODE: u32 = AGDX_GRAPH_BASE;
193/// Managed command code: write nodes and edges (the projector path).
194pub const AGDX_GRAPH_UPSERT_CODE: u32 = AGDX_GRAPH_BASE + 1;
195/// Managed command code: one-hop neighbor read.
196pub const AGDX_GRAPH_NEIGHBORS_CODE: u32 = AGDX_GRAPH_BASE + 2;
197
198// Agent and workflow control band (1_000_700..=1_000_799). Plane-served control
199// operations over the agent and workflow surfaces, forwarded over the same
200// bridge. Distinct from the agent ENVELOPE (the on-the-log message form, carried
201// by `agdx.av`, not a command code): this band is the request-reply control
202// surface a coordinator drives. Whether it is served is advertised by the
203// `agent_workflow` feature bit.
204/// Base of the agent and workflow control band.
205pub const AGDX_AGENT_BASE: u32 = AGDX_COMMAND_BASE + 700;
206/// Managed command code: submit a task to an agent or workflow.
207pub const AGDX_AGENT_SUBMIT_CODE: u32 = AGDX_AGENT_BASE;
208/// Managed command code: cancel a submitted task.
209pub const AGDX_AGENT_CANCEL_CODE: u32 = AGDX_AGENT_BASE + 1;
210/// Managed command code: read a task's status.
211pub const AGDX_AGENT_STATUS_CODE: u32 = AGDX_AGENT_BASE + 2;
212/// Managed command code: list tasks.
213pub const AGDX_AGENT_LIST_CODE: u32 = AGDX_AGENT_BASE + 3;
214
215// Per-surface op-schema versions, stamped on every request envelope (or, for
216// the agent surface, carried as the `agdx.av` header). A peer rejects a payload
217// it cannot decode rather than mis-reading a skewed schema.
218/// Wire version of the authorization command envelopes.
219pub const AUTHZ_OP_VERSION: u32 = 1;
220/// Wire version of the query envelope.
221pub const QUERY_OP_VERSION: u32 = 1;
222/// Wire version of the control envelope.
223pub const CONTROL_OP_VERSION: u32 = 1;
224/// Wire version of the KV op envelopes.
225pub const KV_OP_VERSION: u32 = 1;
226/// Wire version of the fork op envelopes.
227pub const FORK_OP_VERSION: u32 = 1;
228/// Wire version of the graph op envelopes.
229pub const GRAPH_OP_VERSION: u32 = 1;
230/// Wire version of the agent and workflow control-band envelopes. Distinct from
231/// [`AGENT_OP_VERSION`] (the on-the-log envelope), this versions the request and
232/// reply types of the control band.
233pub const AGENT_WORKFLOW_OP_VERSION: u32 = 1;
234
235/// Wire version of the mixed-operation batch request and reply
236/// ([`crate::batch`]). The items inside version themselves: each rides its own
237/// op's request frame with that op's own `v`.
238pub const BATCH_OP_VERSION: u32 = 1;
239
240/// Versions the change-feed record (`ChangeRecord.v`). Checked by consumers of
241/// the changes topic. The feed is advertised by the `WATCH` feature bit.
242pub const CHANGE_OP_VERSION: u32 = 1;
243/// Wire version of the client-metadata discovery request and reply
244/// ([`crate::clients`]).
245pub const CLIENT_METADATA_OP_VERSION: u32 = 1;
246/// Wire version of public checkpoint mutation requests and status replies.
247pub const CHECKPOINT_OP_VERSION: u32 = 1;
248/// Wire version of the agent presence body ([`crate::agent::AgentPresence`]) an
249/// agent advertises in its connection metadata. Carried in the body's own `v`
250/// field, not out-of-band, because presence rides the opaque connection-metadata
251/// bytes with no envelope header to select a decoder.
252pub const PRESENCE_OP_VERSION: u32 = 1;
253/// Wire version of the agent envelope (the Agent Data Exchange Protocol). Carried
254/// out-of-band as the typed `agdx.av` header, never inside the body: a durable
255/// log record must select its decoder before any body byte is read.
256pub const AGENT_OP_VERSION: u32 = 1;
257
258/// Whether a managed command can change plane-owned state and therefore must
259/// carry a stable operation identity across transport retries.
260pub const fn is_idempotent_managed_request(code: u32) -> bool {
261 matches!(
262 code,
263 AGDX_BATCH_CODE
264 | AGDX_KV_SET_CODE
265 | AGDX_KV_DELETE_CODE
266 | AGDX_KV_DELETE_MANY_CODE
267 | AGDX_KV_CAS_CODE
268 | AGDX_KV_EXPIRE_CODE
269 | AGDX_KV_PATCH_CODE
270 | AGDX_KV_LEASE_CODE
271 | AGDX_KV_RELEASE_CODE
272 | AGDX_KV_CAS_FENCED_CODE
273 | AGDX_KV_COPY_CODE
274 | AGDX_KV_MOVE_CODE
275 | AGDX_FORK_CREATE_CODE
276 | AGDX_FORK_DELETE_CODE
277 | AGDX_FORK_PROMOTE_CODE
278 | AGDX_FORK_PUT_CODE
279 | AGDX_GRAPH_UPSERT_CODE
280 | AGDX_AGENT_SUBMIT_CODE
281 | AGDX_AGENT_CANCEL_CODE
282 | AGDX_CHECKPOINT_CODE
283 )
284}