Skip to main content

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//   1_000_800..=1_000_899  delivery: consumer filters (filtered reads and their catalog)
14//
15// A query is a non-replicated read, so it is served off the log via these
16// managed commands instead of a topic round-trip. Raw Apache Iggy rejects them
17// with `InvalidCommand`. The values are a pinned wire contract, enforced by
18// the constants test.
19
20/// Base of LaserData's reserved managed-command range.
21pub const AGDX_COMMAND_BASE: u32 = 1_000_000;
22// Capability probe (internal block): LaserData Cloud answers it,
23// raw Apache Iggy rejects it.
24/// Managed command code: capability probe.
25pub const AGDX_HELLO_CODE: u32 = AGDX_COMMAND_BASE;
26/// Internal command code: the managed backend announces its served capabilities
27/// (an `OpVersions`) to the streaming server over their private socket on connect. The
28/// streaming server caches it and answers the client `AGDX_HELLO` with it, so the binary
29/// feature bits and the HTTP capability flags cannot drift from what the backend
30/// actually serves (the backend is the single source of its own truth). Not a
31/// client-facing code, a client never sends it.
32pub const AGDX_BACKEND_HELLO_CODE: u32 = AGDX_COMMAND_BASE + 1;
33/// Fork-native command code: set this connection's advertised metadata (the
34/// transport-level discovery primitive). Handled by the streaming server itself,
35/// not forwarded to the managed backend, because it touches per-connection session state the
36/// backend never sees. Connection-scoped and cleared on disconnect.
37pub const AGDX_SET_CLIENT_METADATA_CODE: u32 = AGDX_COMMAND_BASE + 2;
38/// Fork-native command code: list every connection with its advertised metadata.
39/// The discovery read, answered by the streaming server from its connection table.
40/// A LaserData-owned reply ([`crate::clients::ClientMetadataList`]), never the
41/// upstream Apache Iggy `get_clients` shape, so an Apache Iggy SDK against LaserData
42/// Cloud and the metadata read stay byte-independent.
43pub const AGDX_GET_CLIENTS_METADATA_CODE: u32 = AGDX_COMMAND_BASE + 3;
44/// Managed command code: the mixed-operation batch. The request body is a CBOR
45/// [`BatchRequest`](crate::batch::BatchRequest) carrying up to
46/// [`MAX_BATCH_OPS`](crate::limits::MAX_BATCH_OPS) managed requests, each with
47/// its own code and payload. The reply a [`BatchReply`](crate::batch::BatchReply)
48/// with each op's own reply bytes in order. One round trip amortized over
49/// several ops, per-op results, explicitly NOT atomic. A nested batch is
50/// rejected. An old backend answers the unknown code with `CommandError`,
51/// decoded client-side as the typed unsupported, so no capability bit is
52/// needed.
53pub const AGDX_BATCH_CODE: u32 = AGDX_COMMAND_BASE + 20;
54// Codes 1_000_021 to 1_000_025 belonged to the retired lakehouse destinations
55// and are never reused.
56
57// Authorization and system-management band (1_000_100..=1_000_199). Handled by
58// the streaming server itself. Reads +0..+3, writes +4..+6, history +7.
59/// Base of the authorization and system-management band (first management band).
60pub const AGDX_AUTHZ_BASE: u32 = AGDX_COMMAND_BASE + 100;
61/// Managed command code: read the caller's own effective capabilities (self-read).
62pub const AGDX_AUTHZ_WHOAMI_CODE: u32 = AGDX_AUTHZ_BASE;
63/// Managed command code: list defined roles (optionally filtered).
64pub const AGDX_AUTHZ_LIST_ROLES_CODE: u32 = AGDX_AUTHZ_BASE + 1;
65/// Managed command code: read one role by name.
66pub const AGDX_AUTHZ_GET_ROLE_CODE: u32 = AGDX_AUTHZ_BASE + 2;
67/// Managed command code: read one user's bound role names.
68pub const AGDX_AUTHZ_GET_BINDINGS_CODE: u32 = AGDX_AUTHZ_BASE + 3;
69/// Managed command code: define or replace a role (upsert).
70pub const AGDX_AUTHZ_DEFINE_ROLE_CODE: u32 = AGDX_AUTHZ_BASE + 4;
71/// Managed command code: delete a role by name.
72pub const AGDX_AUTHZ_DELETE_ROLE_CODE: u32 = AGDX_AUTHZ_BASE + 5;
73/// Managed command code: bind roles to a user (replace the user's role set).
74pub const AGDX_AUTHZ_BIND_ROLES_CODE: u32 = AGDX_AUTHZ_BASE + 6;
75/// Managed command code: read the authorization change history (audit).
76pub const AGDX_AUTHZ_HISTORY_CODE: u32 = AGDX_AUTHZ_BASE + 7;
77/// Managed command code: publish one [`crate::control::ControlCommand`] through
78/// the managed backend. The reply is a [`crate::result::CommandError`] whose
79/// `Ok` code means the backend accepted the control-log append. Applying the
80/// command remains asynchronous.
81pub const AGDX_CONTROL_PUBLISH_CODE: u32 = AGDX_AUTHZ_BASE + 8;
82
83// Query family block (1_000_200..=1_000_299). Direct query ops reserve the
84// +0x decade, projection browse the +1x decade, schema browse the +2x decade.
85/// Base of the query managed-command block.
86pub const AGDX_QUERY_BASE: u32 = AGDX_COMMAND_BASE + 200;
87// Execute a `Query`: request body is a CBOR `QueryEnvelope`, reply a CBOR
88// `QueryReply`, off the log over the managed command channel.
89/// Managed command code: execute a query.
90pub const AGDX_QUERY_CODE: u32 = AGDX_QUERY_BASE;
91// Codes 1_000_201 to 1_000_203 belonged to the retired query execution paging,
92// cancellation and status operations and are never reused.
93// Browse the projection registry (read-only). Get one projection by id (request
94// `GetProjection`) or list them all (request `ListProjections`), reply a CBOR
95// `BrowseReply`.
96/// Managed command code: browse one projection.
97pub const AGDX_GET_PROJECTION_CODE: u32 = AGDX_QUERY_BASE + 10;
98/// Managed command code: list projections.
99pub const AGDX_LIST_PROJECTIONS_CODE: u32 = AGDX_QUERY_BASE + 11;
100/// Managed command code: browse one registered schema by id.
101pub const AGDX_GET_SCHEMA_CODE: u32 = AGDX_QUERY_BASE + 20;
102/// Managed command code: list registered schemas.
103pub const AGDX_LIST_SCHEMAS_CODE: u32 = AGDX_QUERY_BASE + 21;
104/// Managed command code: register a writer schema and answer its allocated id.
105pub const AGDX_REGISTER_SCHEMA_CODE: u32 = AGDX_QUERY_BASE + 22;
106/// Managed command code: decode one payload under a registered schema id.
107pub const AGDX_DECODE_RECORD_CODE: u32 = AGDX_QUERY_BASE + 23;
108
109// Key-value command block (1_000_300..=1_000_399). Each op is its own managed
110// command, forwarded to LaserData Cloud over the same local channel the query path
111// uses, with the authenticated identity stamped in.
112/// Base of the KV managed-command block.
113pub const AGDX_KV_BASE: u32 = AGDX_COMMAND_BASE + 300;
114/// Managed command code: KV get.
115pub const AGDX_KV_GET_CODE: u32 = AGDX_KV_BASE;
116/// Managed command code: KV set.
117pub const AGDX_KV_SET_CODE: u32 = AGDX_KV_BASE + 1;
118/// Managed command code: KV scan.
119pub const AGDX_KV_SCAN_CODE: u32 = AGDX_KV_BASE + 2;
120/// Managed command code: KV delete one.
121pub const AGDX_KV_DELETE_CODE: u32 = AGDX_KV_BASE + 3;
122/// Managed command code: KV bulk delete by filter.
123pub const AGDX_KV_DELETE_MANY_CODE: u32 = AGDX_KV_BASE + 4;
124/// Managed command code: list the caller's namespaces.
125pub const AGDX_KV_NAMESPACES_CODE: u32 = AGDX_KV_BASE + 5;
126/// Managed command code: compare-and-swap a key (optimistic concurrency).
127/// Additive over [`KV_OP_VERSION`] 1: a backend or server that does not serve it
128/// rejects the code, which the client surfaces as an unsupported error. Whether
129/// it is served is advertised by the `kv_cas` capability flag.
130pub const AGDX_KV_CAS_CODE: u32 = AGDX_KV_BASE + 6;
131/// Managed command code: test presence and read metadata without the value
132/// (the formal `EXISTS` object primitive).
133pub const AGDX_KV_EXISTS_CODE: u32 = AGDX_KV_BASE + 7;
134/// Managed command code: set, refresh, or clear a key's expiry in place without
135/// rewriting its value (the formal `EXPIRE` primitive).
136pub const AGDX_KV_EXPIRE_CODE: u32 = AGDX_KV_BASE + 8;
137/// Managed command code: apply a merge patch to a structured value (the formal
138/// `PATCH` primitive).
139pub const AGDX_KV_PATCH_CODE: u32 = AGDX_KV_BASE + 9;
140/// Managed command code: acquire a revocable lease on a key (the formal `LEASE`
141/// primitive). Carries the stable holder identity and an optional delegated
142/// subject at [`KV_LEASE_OP_VERSION`]. Served only by a deployment advertising
143/// the `KV_FENCED_LEASES` feature bit. A backend that cannot serve it returns a
144/// clean unsupported error.
145pub const AGDX_KV_LEASE_CODE: u32 = AGDX_KV_BASE + 10;
146/// Managed command code: release a held lease early (the formal `RELEASE`
147/// primitive). Requires the same holder and the current fence token, validated
148/// against the fence sequence, never the resetting lease-row version.
149pub const AGDX_KV_RELEASE_CODE: u32 = AGDX_KV_BASE + 11;
150/// Managed command code: fenced compare-and-swap. Applies the CAS in one
151/// backend transaction that also requires a live lease at the request's
152/// coordination namespace and key plus a fence sequence equal to the presented
153/// token (the at-most-one effective-writer gate). Rides
154/// [`KV_LEASE_OP_VERSION`] and is served only under the `KV_FENCED_LEASES` feature
155/// bit, which subsumes the older fence-only `kv_cas_fenced` flag.
156pub const AGDX_KV_CAS_FENCED_CODE: u32 = AGDX_KV_BASE + 12;
157/// Managed command code: copy the value at one key to another key (possibly in
158/// another namespace) in a single backend transaction. Reuses the kv outcomes:
159/// `Committed` on success, `NotFound` when the source is absent.
160pub const AGDX_KV_COPY_CODE: u32 = AGDX_KV_BASE + 13;
161/// Managed command code: move the value at one key to another key. Copy plus
162/// delete of the source, one backend transaction, the same outcomes.
163pub const AGDX_KV_MOVE_CODE: u32 = AGDX_KV_BASE + 14;
164/// Managed command code: extend a held lease without changing its token (the
165/// formal `RENEW` primitive). Requires the same holder and subject, a live
166/// lease, and the current fence token, and never bumps the fence. Rides
167/// [`KV_LEASE_OP_VERSION`] under the `KV_FENCED_LEASES` feature bit.
168pub const AGDX_KV_LEASE_RENEW_CODE: u32 = AGDX_KV_BASE + 15;
169
170// Fork block (1_000_400..): agentic copy-on-write branches of the materialized
171// read model. Each op is its own managed command, forwarded over the same bridge.
172// Experimental: the fork surface is not a native Iggy topic fork and may be
173// superseded by a native shared-log implementation.
174/// Base of the fork managed-command block.
175pub const AGDX_FORK_BASE: u32 = AGDX_COMMAND_BASE + 400;
176/// Managed command code: open a fork.
177pub const AGDX_FORK_CREATE_CODE: u32 = AGDX_FORK_BASE;
178/// Managed command code: squash a fork.
179pub const AGDX_FORK_DELETE_CODE: u32 = AGDX_FORK_BASE + 1;
180/// Managed command code: promote a fork onto the trunk.
181pub const AGDX_FORK_PROMOTE_CODE: u32 = AGDX_FORK_BASE + 2;
182/// Managed command code: list forks.
183pub const AGDX_FORK_LIST_CODE: u32 = AGDX_FORK_BASE + 3;
184/// Managed command code: write a speculative fork row.
185pub const AGDX_FORK_PUT_CODE: u32 = AGDX_FORK_BASE + 4;
186
187// Knowledge graph block (1_000_600..=1_000_699). Traversal reads and the
188// projector's node/edge upsert. Whether they are served is advertised by the
189// `managed_graph` capability flag. Agentic memory is not a wire band of its own:
190// the four-verb memory API is an SDK facade that composes `publish`, the query
191// block, and this graph block, so there is one managed read/write model, not a
192// parallel one.
193/// Base of the graph managed-command block.
194pub const AGDX_GRAPH_BASE: u32 = AGDX_COMMAND_BASE + 600;
195/// Managed command code: run a graph traversal.
196pub const AGDX_GRAPH_QUERY_CODE: u32 = AGDX_GRAPH_BASE;
197/// Managed command code: write nodes and edges (the projector path).
198pub const AGDX_GRAPH_UPSERT_CODE: u32 = AGDX_GRAPH_BASE + 1;
199/// Managed command code: one-hop neighbor read.
200pub const AGDX_GRAPH_NEIGHBORS_CODE: u32 = AGDX_GRAPH_BASE + 2;
201
202// Agent band (1_000_700..=1_000_799). Codes 1_000_700 to 1_000_703 belonged to
203// the retired run registry and are never reused. The session reads start at
204// 1_000_710.
205/// Base of the agent band.
206pub const AGDX_AGENT_BASE: u32 = AGDX_COMMAND_BASE + 700;
207/// Managed command code: read one session summary.
208pub const AGDX_SESSION_GET_CODE: u32 = AGDX_AGENT_BASE + 10;
209/// Managed command code: list sessions in one stream.
210pub const AGDX_SESSION_LIST_CODE: u32 = AGDX_AGENT_BASE + 11;
211/// Managed command code: read a session timeline page.
212pub const AGDX_SESSION_EVENTS_CODE: u32 = AGDX_AGENT_BASE + 12;
213/// Managed command code: read folded session state.
214pub const AGDX_SESSION_STATE_CODE: u32 = AGDX_AGENT_BASE + 13;
215/// Managed command code: read links to derived facts.
216pub const AGDX_SESSION_LINKS_CODE: u32 = AGDX_AGENT_BASE + 14;
217/// Managed command code: read session source positions.
218pub const AGDX_SESSION_SOURCES_CODE: u32 = AGDX_AGENT_BASE + 15;
219/// Managed command code: read committed session changes.
220pub const AGDX_SESSION_CHANGES_CODE: u32 = AGDX_AGENT_BASE + 16;
221
222// Delivery band (1_000_800..=1_000_899). Consumer filters: a reader asks the
223// streaming server for only the records that match a declarative filter.
224// Reads, acknowledgments, previews, sample tests, and validation are served by
225// the streaming server itself (the +0x decade). The catalog of saved filters and
226// their consumer-group bindings lives in LaserData Cloud and is forwarded (the
227// +1x decade). Whether it is served is advertised by the `CONSUMER_FILTERS`
228// feature bit.
229/// Base of the delivery band.
230pub const AGDX_DELIVERY_BASE: u32 = AGDX_COMMAND_BASE + 800;
231/// Server-native command code: read one bounded page of matching records.
232pub const AGDX_FILTERED_POLL_CODE: u32 = AGDX_DELIVERY_BASE;
233/// Server-native command code: acknowledge a page under its current group policy.
234pub const AGDX_FILTERED_ACK_CODE: u32 = AGDX_DELIVERY_BASE + 1;
235/// Server-native command code: hold until one of a reader's partitions has a
236/// record at or after its offset, or the wait ends. Served when the filter
237/// announcement names a non-zero `max_wait_ms`.
238pub const AGDX_FILTERED_WAIT_CODE: u32 = AGDX_DELIVERY_BASE + 5;
239/// Server-native command code: end filtered waits this connection holds,
240/// named by their `wait_id`.
241pub const AGDX_FILTERED_WAIT_CANCEL_CODE: u32 = AGDX_DELIVERY_BASE + 6;
242/// Server-native command code: preview a filter over stored records without
243/// joining a consumer group or storing an offset.
244pub const AGDX_FILTER_PREVIEW_CODE: u32 = AGDX_DELIVERY_BASE + 2;
245/// Server-native command code: evaluate a filter against one supplied sample.
246pub const AGDX_FILTER_TEST_CODE: u32 = AGDX_DELIVERY_BASE + 3;
247/// Server-native command code: validate and compile a filter, returning its digest.
248pub const AGDX_FILTER_VALIDATE_CODE: u32 = AGDX_DELIVERY_BASE + 4;
249/// Managed command code: one catalog mutation (register, revise, describe,
250/// set_revision_enabled, archive, drop, bind, unbind), with its authoritative outcome.
251pub const AGDX_FILTER_MUTATE_CODE: u32 = AGDX_DELIVERY_BASE + 10;
252/// Managed command code: read one saved filter.
253pub const AGDX_GET_FILTER_CODE: u32 = AGDX_DELIVERY_BASE + 11;
254/// Managed command code: list saved filters.
255pub const AGDX_LIST_FILTERS_CODE: u32 = AGDX_DELIVERY_BASE + 12;
256/// Managed command code: list one filter's immutable revisions.
257pub const AGDX_LIST_FILTER_REVISIONS_CODE: u32 = AGDX_DELIVERY_BASE + 13;
258/// Managed command code: read the filter binding of one consumer group.
259pub const AGDX_GET_FILTER_BINDING_CODE: u32 = AGDX_DELIVERY_BASE + 14;
260/// Managed command code: list consumer-group filter bindings.
261pub const AGDX_LIST_FILTER_BINDINGS_CODE: u32 = AGDX_DELIVERY_BASE + 15;
262/// Managed command code: read the outcome of a catalog mutation by its operation id.
263pub const AGDX_FILTER_OPERATION_CODE: u32 = AGDX_DELIVERY_BASE + 16;
264/// Internal command code: the streaming server resolves the execution policy of a
265/// filtered read (a saved revision or a group binding). Never sent by a client.
266pub const AGDX_RESOLVE_FILTER_POLICY_CODE: u32 = AGDX_DELIVERY_BASE + 17;
267/// Internal command code: the streaming server waits for the next change of the
268/// filter catalog its managed backend replayed. A zero wait confirms cached policies
269/// before use. Never sent by a client.
270pub const AGDX_WATCH_FILTER_CATALOG_CODE: u32 = AGDX_DELIVERY_BASE + 18;
271
272// Per-surface op-schema versions, stamped on every request envelope (or, for
273// the agent surface, carried as the `agdx.av` header). A peer rejects a payload
274// it cannot decode rather than mis-reading a skewed schema.
275/// Wire version of the authorization command envelopes.
276pub const AUTHZ_OP_VERSION: u32 = 1;
277/// Wire version of the query envelope.
278pub const QUERY_OP_VERSION: u32 = 1;
279/// Wire version of the control envelope.
280pub const CONTROL_OP_VERSION: u32 = 1;
281/// Wire version of the KV op envelopes.
282pub const KV_OP_VERSION: u32 = 1;
283/// Wire version of the fenced-lease op family: `KvLease`, `KvLeaseRenew`,
284/// `KvRelease`, and `KvCasFenced`. The holder-identity shape was finalized
285/// before publication, so it remains at version 1 with the rest of the KV
286/// surface. Its required fields have no serde defaults and
287/// [`crate::validate::Validate`] rejects any other `v` fail-closed.
288pub const KV_LEASE_OP_VERSION: u32 = 1;
289/// Wire version of the fork op envelopes.
290pub const FORK_OP_VERSION: u32 = 1;
291/// Wire version of the graph op envelopes.
292pub const GRAPH_OP_VERSION: u32 = 1;
293/// Wire version of the consumer-filter envelopes (reads, acknowledgments,
294/// previews, tests, catalog requests, and their replies).
295pub const FILTER_OP_VERSION: u32 = 1;
296
297/// Wire version of the mixed-operation batch request and reply
298/// ([`crate::batch`]). The items inside version themselves: each rides its own
299/// op's request frame with that op's own `v`.
300pub const BATCH_OP_VERSION: u32 = 1;
301
302/// Versions the change-feed record (`ChangeRecord.v`). Checked by consumers of
303/// the changes topic. The feed is advertised by the `WATCH` feature bit.
304pub const CHANGE_OP_VERSION: u32 = 1;
305/// Wire version of the client-metadata discovery request and reply
306/// ([`crate::clients`]).
307pub const CLIENT_METADATA_OP_VERSION: u32 = 1;
308/// Wire version of the agent presence body ([`crate::agent::AgentPresence`]) an
309/// agent advertises in its connection metadata. Carried in the body's own `v`
310/// field, not out-of-band, because presence rides the opaque connection-metadata
311/// bytes with no envelope header to select a decoder.
312pub const PRESENCE_OP_VERSION: u32 = 1;
313/// Wire version of the agent envelope (the Agent Data Exchange Protocol). Carried
314/// out-of-band as the typed `agdx.av` header, never inside the body: a durable
315/// log record must select its decoder before any body byte is read.
316pub const AGENT_OP_VERSION: u32 = 1;
317
318/// Whether a managed read may carry a [`crate::mutation::ManagedReadEnvelope`]
319/// barrier: the reads of the key-value, fork and graph surfaces, whose state
320/// the mutation logs fold, and the session reads, whose state the session
321/// fold builds from the session source topics.
322pub const fn is_barrier_read(code: u32) -> bool {
323    matches!(
324        code,
325        AGDX_KV_GET_CODE
326            | AGDX_KV_SCAN_CODE
327            | AGDX_KV_NAMESPACES_CODE
328            | AGDX_KV_EXISTS_CODE
329            | AGDX_FORK_LIST_CODE
330            | AGDX_GRAPH_QUERY_CODE
331            | AGDX_GRAPH_NEIGHBORS_CODE
332            | AGDX_SESSION_GET_CODE
333            | AGDX_SESSION_LIST_CODE
334            | AGDX_SESSION_EVENTS_CODE
335            | AGDX_SESSION_STATE_CODE
336            | AGDX_SESSION_LINKS_CODE
337            | AGDX_SESSION_SOURCES_CODE
338            | AGDX_SESSION_CHANGES_CODE
339    )
340}
341
342/// Whether a backend-served managed command changes state and therefore must
343/// carry a stable operation identity across transport retries. Iggy's custom
344/// authorization mutations use their established request `mutation_id`
345/// instead of this managed envelope.
346pub const fn is_idempotent_managed_request(code: u32) -> bool {
347    matches!(
348        code,
349        AGDX_BATCH_CODE
350            | AGDX_KV_SET_CODE
351            | AGDX_KV_DELETE_CODE
352            | AGDX_KV_DELETE_MANY_CODE
353            | AGDX_KV_CAS_CODE
354            | AGDX_KV_EXPIRE_CODE
355            | AGDX_KV_PATCH_CODE
356            | AGDX_KV_LEASE_CODE
357            | AGDX_KV_LEASE_RENEW_CODE
358            | AGDX_KV_RELEASE_CODE
359            | AGDX_KV_CAS_FENCED_CODE
360            | AGDX_KV_COPY_CODE
361            | AGDX_KV_MOVE_CODE
362            | AGDX_FORK_CREATE_CODE
363            | AGDX_FORK_DELETE_CODE
364            | AGDX_FORK_PROMOTE_CODE
365            | AGDX_FORK_PUT_CODE
366            | AGDX_GRAPH_UPSERT_CODE
367            | AGDX_CONTROL_PUBLISH_CODE
368            | AGDX_REGISTER_SCHEMA_CODE
369    )
370}