laser-wire 0.8.1

// Managed command codes LaserData Cloud reserves. Upstream Apache Iggy uses low
// codes (1..=605), so LaserData reserves everything from one million up and the
// two never collide. Within that, each feature owns a 100-wide block:
//
//   1_000_000..=1_000_099  internal commands (capability probe, backend hello, client metadata, batch)
//   1_000_100..=1_000_199  authorization & system management (whoami, roles, bindings) [first management band]
//   1_000_200..=1_000_299  query family (query, projection/schema browse)
//   1_000_300..=1_000_399  key-value store
//   1_000_400..=1_000_499  forks (experimental)
//   1_000_500..=1_000_599  agentic memory (reserved facade: remember/recall/improve/forget)
//   1_000_600..=1_000_699  knowledge graph (traverse, neighbors, upsert)
//   1_000_700..=1_000_799  agent and workflow control (submit/cancel/status/list)
//   1_000_800..=1_000_899  delivery: consumer filters (filtered reads and their catalog)
//
// A query is a non-replicated read, so it is served off the log via these
// managed commands instead of a topic round-trip. Raw Apache Iggy rejects them
// with `InvalidCommand`. The values are a pinned wire contract, enforced by
// the constants test.

/// Base of LaserData's reserved managed-command range.
pub const AGDX_COMMAND_BASE: u32 = 1_000_000;
// Capability probe (internal block): LaserData Cloud answers it,
// raw Apache Iggy rejects it.
/// Managed command code: capability probe.
pub const AGDX_HELLO_CODE: u32 = AGDX_COMMAND_BASE;
/// Internal command code: the managed backend announces its served capabilities
/// (an `OpVersions`) to the streaming server over their private socket on connect. The
/// streaming server caches it and answers the client `AGDX_HELLO` with it, so the binary
/// feature bits and the HTTP capability flags cannot drift from what the backend
/// actually serves (the backend is the single source of its own truth). Not a
/// client-facing code, a client never sends it.
pub const AGDX_BACKEND_HELLO_CODE: u32 = AGDX_COMMAND_BASE + 1;
/// Fork-native command code: set this connection's advertised metadata (the
/// transport-level discovery primitive). Handled by the streaming server itself,
/// not forwarded to the plane, because it touches per-connection session state the
/// plane never sees. Connection-scoped and cleared on disconnect.
pub const AGDX_SET_CLIENT_METADATA_CODE: u32 = AGDX_COMMAND_BASE + 2;
/// Fork-native command code: list every connection with its advertised metadata.
/// The discovery read, answered by the streaming server from its connection table.
/// A LaserData-owned reply ([`crate::clients::ClientMetadataList`]), never the
/// upstream Apache Iggy `get_clients` shape, so an Apache Iggy SDK against LaserData
/// Cloud and the metadata read stay byte-independent.
pub const AGDX_GET_CLIENTS_METADATA_CODE: u32 = AGDX_COMMAND_BASE + 3;
/// Managed command code: the mixed-operation batch. The request body is a CBOR
/// [`BatchRequest`](crate::batch::BatchRequest) carrying up to
/// [`MAX_BATCH_OPS`](crate::limits::MAX_BATCH_OPS) managed requests, each with
/// its own code and payload. The reply a [`BatchReply`](crate::batch::BatchReply)
/// with each op's own reply bytes in order. One round trip amortized over
/// several ops, per-op results, explicitly NOT atomic. A nested batch is
/// rejected. An old backend answers the unknown code with `CommandError`,
/// decoded client-side as the typed unsupported, so no capability bit is
/// needed.
pub const AGDX_BATCH_CODE: u32 = AGDX_COMMAND_BASE + 20;
/// Managed command code: submit one public checkpoint mutation to Plane.
pub const AGDX_CHECKPOINT_CODE: u32 = AGDX_COMMAND_BASE + 21;
/// Fork-native command code: read one destination and its checkpoint status.
pub const AGDX_DESTINATION_GET_CODE: u32 = AGDX_COMMAND_BASE + 22;
/// Fork-native command code: list destinations and their checkpoint status.
pub const AGDX_DESTINATION_LIST_CODE: u32 = AGDX_COMMAND_BASE + 23;
/// Fork-native command code: list explicit query-route declarations.
pub const AGDX_QUERY_ROUTE_LIST_CODE: u32 = AGDX_COMMAND_BASE + 24;
/// Internal carriage for the closed destination HTTP operation set.
pub const AGDX_DESTINATION_HTTP_CODE: u32 = AGDX_COMMAND_BASE + 25;

// Authorization and system-management band (1_000_100..=1_000_199). Handled by
// the streaming server itself. Reads +0..+3, writes +4..+6, history +7.
/// Base of the authorization and system-management band (first management band).
pub const AGDX_AUTHZ_BASE: u32 = AGDX_COMMAND_BASE + 100;
/// Managed command code: read the caller's own effective capabilities (self-read).
pub const AGDX_AUTHZ_WHOAMI_CODE: u32 = AGDX_AUTHZ_BASE;
/// Managed command code: list defined roles (optionally filtered).
pub const AGDX_AUTHZ_LIST_ROLES_CODE: u32 = AGDX_AUTHZ_BASE + 1;
/// Managed command code: read one role by name.
pub const AGDX_AUTHZ_GET_ROLE_CODE: u32 = AGDX_AUTHZ_BASE + 2;
/// Managed command code: read one user's bound role names.
pub const AGDX_AUTHZ_GET_BINDINGS_CODE: u32 = AGDX_AUTHZ_BASE + 3;
/// Managed command code: define or replace a role (upsert).
pub const AGDX_AUTHZ_DEFINE_ROLE_CODE: u32 = AGDX_AUTHZ_BASE + 4;
/// Managed command code: delete a role by name.
pub const AGDX_AUTHZ_DELETE_ROLE_CODE: u32 = AGDX_AUTHZ_BASE + 5;
/// Managed command code: bind roles to a user (replace the user's role set).
pub const AGDX_AUTHZ_BIND_ROLES_CODE: u32 = AGDX_AUTHZ_BASE + 6;
/// Managed command code: read the authorization change history (audit).
pub const AGDX_AUTHZ_HISTORY_CODE: u32 = AGDX_AUTHZ_BASE + 7;
/// Managed command code: publish one [`crate::control::ControlCommand`] through
/// Plane. The reply is a [`crate::result::CommandError`] whose `Ok` code means
/// Plane accepted the control-log append. Applying the command remains
/// asynchronous.
pub const AGDX_CONTROL_PUBLISH_CODE: u32 = AGDX_AUTHZ_BASE + 8;

// Query family block (1_000_200..=1_000_299). Direct query ops reserve the
// +0x decade, projection browse the +1x decade, schema browse the +2x decade.
/// Base of the query managed-command block.
pub const AGDX_QUERY_BASE: u32 = AGDX_COMMAND_BASE + 200;
// Execute a `Query`: request body is a CBOR `QueryEnvelope`, reply a CBOR
// `QueryReply`, off the log over the managed command channel.
/// Managed command code: execute a query.
pub const AGDX_QUERY_CODE: u32 = AGDX_QUERY_BASE;
/// Managed command code: retrieve the next page of an executing query.
pub const AGDX_QUERY_PAGE_CODE: u32 = AGDX_QUERY_BASE + 1;
/// Managed command code: cancel an executing query.
pub const AGDX_QUERY_CANCEL_CODE: u32 = AGDX_QUERY_BASE + 2;
/// Managed command code: read query execution status.
pub const AGDX_QUERY_STATUS_CODE: u32 = AGDX_QUERY_BASE + 3;
// Browse the projection registry (read-only). Get one projection by id (request
// `GetProjection`) or list them all (request `ListProjections`), reply a CBOR
// `BrowseReply`.
/// Managed command code: browse one projection.
pub const AGDX_GET_PROJECTION_CODE: u32 = AGDX_QUERY_BASE + 10;
/// Managed command code: list projections.
pub const AGDX_LIST_PROJECTIONS_CODE: u32 = AGDX_QUERY_BASE + 11;
/// Managed command code: browse one registered schema by id.
pub const AGDX_GET_SCHEMA_CODE: u32 = AGDX_QUERY_BASE + 20;
/// Managed command code: list registered schemas.
pub const AGDX_LIST_SCHEMAS_CODE: u32 = AGDX_QUERY_BASE + 21;
/// Managed command code: advisory next free schema id.
pub const AGDX_REGISTER_SCHEMA_CODE: u32 = AGDX_QUERY_BASE + 22;
/// Managed command code: decode one payload under a registered schema id.
pub const AGDX_DECODE_RECORD_CODE: u32 = AGDX_QUERY_BASE + 23;

// Key-value command block (1_000_300..=1_000_399). Each op is its own managed
// command, forwarded to LaserData Cloud over the same local channel the query path
// uses, with the authenticated identity stamped in.
/// Base of the KV managed-command block.
pub const AGDX_KV_BASE: u32 = AGDX_COMMAND_BASE + 300;
/// Managed command code: KV get.
pub const AGDX_KV_GET_CODE: u32 = AGDX_KV_BASE;
/// Managed command code: KV set.
pub const AGDX_KV_SET_CODE: u32 = AGDX_KV_BASE + 1;
/// Managed command code: KV scan.
pub const AGDX_KV_SCAN_CODE: u32 = AGDX_KV_BASE + 2;
/// Managed command code: KV delete one.
pub const AGDX_KV_DELETE_CODE: u32 = AGDX_KV_BASE + 3;
/// Managed command code: KV bulk delete by filter.
pub const AGDX_KV_DELETE_MANY_CODE: u32 = AGDX_KV_BASE + 4;
/// Managed command code: list the caller's namespaces.
pub const AGDX_KV_NAMESPACES_CODE: u32 = AGDX_KV_BASE + 5;
/// Managed command code: compare-and-swap a key (optimistic concurrency).
/// Additive over [`KV_OP_VERSION`] 1: a backend or server that does not serve it
/// rejects the code, which the client surfaces as an unsupported error. Whether
/// it is served is advertised by the `kv_cas` capability flag.
pub const AGDX_KV_CAS_CODE: u32 = AGDX_KV_BASE + 6;
/// Managed command code: test presence and read metadata without the value
/// (the formal `EXISTS` object primitive).
pub const AGDX_KV_EXISTS_CODE: u32 = AGDX_KV_BASE + 7;
/// Managed command code: set, refresh, or clear a key's expiry in place without
/// rewriting its value (the formal `EXPIRE` primitive).
pub const AGDX_KV_EXPIRE_CODE: u32 = AGDX_KV_BASE + 8;
/// Managed command code: apply a merge patch to a structured value (the formal
/// `PATCH` primitive).
pub const AGDX_KV_PATCH_CODE: u32 = AGDX_KV_BASE + 9;
/// Managed command code: acquire a revocable lease on a key (the formal `LEASE`
/// primitive). Carries the stable holder identity and an optional delegated
/// subject at [`KV_LEASE_OP_VERSION`]. Served only by a deployment advertising
/// the `KV_FENCED_LEASES` feature bit; a backend that cannot serve it returns a
/// clean unsupported error.
pub const AGDX_KV_LEASE_CODE: u32 = AGDX_KV_BASE + 10;
/// Managed command code: release a held lease early (the formal `RELEASE`
/// primitive). Requires the same holder and the current fence token, validated
/// against the fence sequence, never the resetting lease-row version.
pub const AGDX_KV_RELEASE_CODE: u32 = AGDX_KV_BASE + 11;
/// Managed command code: fenced compare-and-swap. Applies the CAS in one
/// backend transaction that also requires a live lease at the request's
/// coordination namespace and key plus a fence sequence equal to the presented
/// token (the at-most-one effective-writer gate). Rides
/// [`KV_LEASE_OP_VERSION`]; served only under the `KV_FENCED_LEASES` feature
/// bit, which subsumes the older fence-only `kv_cas_fenced` flag.
pub const AGDX_KV_CAS_FENCED_CODE: u32 = AGDX_KV_BASE + 12;
/// Managed command code: copy the value at one key to another key (possibly in
/// another namespace) in a single backend transaction. Reuses the kv outcomes:
/// `Committed` on success, `NotFound` when the source is absent.
pub const AGDX_KV_COPY_CODE: u32 = AGDX_KV_BASE + 13;
/// Managed command code: move the value at one key to another key. Copy plus
/// delete of the source, one backend transaction, the same outcomes.
pub const AGDX_KV_MOVE_CODE: u32 = AGDX_KV_BASE + 14;
/// Managed command code: extend a held lease without changing its token (the
/// formal `RENEW` primitive). Requires the same holder and subject, a live
/// lease, and the current fence token; never bumps the fence. Rides
/// [`KV_LEASE_OP_VERSION`] under the `KV_FENCED_LEASES` feature bit.
pub const AGDX_KV_LEASE_RENEW_CODE: u32 = AGDX_KV_BASE + 15;

// Fork block (1_000_400..): agentic copy-on-write branches of the materialized
// read model. Each op is its own managed command, forwarded over the same bridge.
// Experimental: the fork surface is not a native Iggy topic fork and may be
// superseded by a native shared-log implementation.
/// Base of the fork managed-command block.
pub const AGDX_FORK_BASE: u32 = AGDX_COMMAND_BASE + 400;
/// Managed command code: open a fork.
pub const AGDX_FORK_CREATE_CODE: u32 = AGDX_FORK_BASE;
/// Managed command code: squash a fork.
pub const AGDX_FORK_DELETE_CODE: u32 = AGDX_FORK_BASE + 1;
/// Managed command code: promote a fork onto the trunk.
pub const AGDX_FORK_PROMOTE_CODE: u32 = AGDX_FORK_BASE + 2;
/// Managed command code: list forks.
pub const AGDX_FORK_LIST_CODE: u32 = AGDX_FORK_BASE + 3;
/// Managed command code: write a speculative fork row.
pub const AGDX_FORK_PUT_CODE: u32 = AGDX_FORK_BASE + 4;

// Knowledge graph block (1_000_600..=1_000_699). Traversal reads and the
// projector's node/edge upsert. Whether they are served is advertised by the
// `managed_graph` capability flag. Agentic memory is not a wire band of its own:
// the four-verb memory API is an SDK facade that composes `publish`, the query
// block, and this graph block, so there is one managed read/write model, not a
// parallel one.
/// Base of the graph managed-command block.
pub const AGDX_GRAPH_BASE: u32 = AGDX_COMMAND_BASE + 600;
/// Managed command code: run a graph traversal.
pub const AGDX_GRAPH_QUERY_CODE: u32 = AGDX_GRAPH_BASE;
/// Managed command code: write nodes and edges (the projector path).
pub const AGDX_GRAPH_UPSERT_CODE: u32 = AGDX_GRAPH_BASE + 1;
/// Managed command code: one-hop neighbor read.
pub const AGDX_GRAPH_NEIGHBORS_CODE: u32 = AGDX_GRAPH_BASE + 2;

// Agent band (1_000_700..=1_000_799). Codes 1_000_700 to 1_000_703 belonged to
// the retired run registry and are never reused. The session reads start at
// 1_000_710.
/// Base of the agent band.
pub const AGDX_AGENT_BASE: u32 = AGDX_COMMAND_BASE + 700;
/// Managed command code: read one session summary.
pub const AGDX_SESSION_GET_CODE: u32 = AGDX_AGENT_BASE + 10;
/// Managed command code: list sessions in one stream.
pub const AGDX_SESSION_LIST_CODE: u32 = AGDX_AGENT_BASE + 11;
/// Managed command code: read a session timeline page.
pub const AGDX_SESSION_EVENTS_CODE: u32 = AGDX_AGENT_BASE + 12;
/// Managed command code: read folded session state.
pub const AGDX_SESSION_STATE_CODE: u32 = AGDX_AGENT_BASE + 13;
/// Managed command code: read links to derived facts.
pub const AGDX_SESSION_LINKS_CODE: u32 = AGDX_AGENT_BASE + 14;
/// Managed command code: read session source positions.
pub const AGDX_SESSION_SOURCES_CODE: u32 = AGDX_AGENT_BASE + 15;
/// Managed command code: read committed session changes.
pub const AGDX_SESSION_CHANGES_CODE: u32 = AGDX_AGENT_BASE + 16;

// Delivery band (1_000_800..=1_000_899). Consumer filters: a reader asks the
// streaming server for only the records that match a declarative filter.
// Reads, acknowledgments, previews, sample tests, and validation are served by
// the streaming server itself (the +0x decade). The catalog of saved filters and
// their consumer-group bindings lives in LaserData Cloud and is forwarded (the
// +1x decade). Whether it is served is advertised by the `CONSUMER_FILTERS`
// feature bit.
/// Base of the delivery band.
pub const AGDX_DELIVERY_BASE: u32 = AGDX_COMMAND_BASE + 800;
/// Server-native command code: read one bounded page of matching records.
pub const AGDX_FILTERED_POLL_CODE: u32 = AGDX_DELIVERY_BASE;
/// Server-native command code: acknowledge a filtered page, fenced to the source
/// generation the page was read from.
pub const AGDX_FILTERED_ACK_CODE: u32 = AGDX_DELIVERY_BASE + 1;
/// Server-native command code: preview a filter over stored records without
/// joining a consumer group or storing an offset.
pub const AGDX_FILTER_PREVIEW_CODE: u32 = AGDX_DELIVERY_BASE + 2;
/// Server-native command code: evaluate a filter against one supplied sample.
pub const AGDX_FILTER_TEST_CODE: u32 = AGDX_DELIVERY_BASE + 3;
/// Server-native command code: validate and compile a filter, returning its digest.
pub const AGDX_FILTER_VALIDATE_CODE: u32 = AGDX_DELIVERY_BASE + 4;
/// Managed command code: one catalog mutation (register, revise, describe,
/// set_revision_enabled, archive, drop, bind, unbind), with its authoritative outcome.
pub const AGDX_FILTER_MUTATE_CODE: u32 = AGDX_DELIVERY_BASE + 10;
/// Managed command code: read one saved filter.
pub const AGDX_GET_FILTER_CODE: u32 = AGDX_DELIVERY_BASE + 11;
/// Managed command code: list saved filters.
pub const AGDX_LIST_FILTERS_CODE: u32 = AGDX_DELIVERY_BASE + 12;
/// Managed command code: list one filter's immutable revisions.
pub const AGDX_LIST_FILTER_REVISIONS_CODE: u32 = AGDX_DELIVERY_BASE + 13;
/// Managed command code: read the filter binding of one consumer group.
pub const AGDX_GET_FILTER_BINDING_CODE: u32 = AGDX_DELIVERY_BASE + 14;
/// Managed command code: list consumer-group filter bindings.
pub const AGDX_LIST_FILTER_BINDINGS_CODE: u32 = AGDX_DELIVERY_BASE + 15;
/// Managed command code: read the outcome of a catalog mutation by its operation id.
pub const AGDX_FILTER_OPERATION_CODE: u32 = AGDX_DELIVERY_BASE + 16;
/// Internal command code: the streaming server resolves the execution policy of a
/// filtered read (a saved revision or a group binding). Never sent by a client.
pub const AGDX_RESOLVE_FILTER_POLICY_CODE: u32 = AGDX_DELIVERY_BASE + 17;
/// Internal command code: the streaming server waits for the next change of the
/// filter catalog its plane replayed. A zero wait confirms cached policies
/// before use. Never sent by a client.
pub const AGDX_WATCH_FILTER_CATALOG_CODE: u32 = AGDX_DELIVERY_BASE + 18;

// Per-surface op-schema versions, stamped on every request envelope (or, for
// the agent surface, carried as the `agdx.av` header). A peer rejects a payload
// it cannot decode rather than mis-reading a skewed schema.
/// Wire version of the authorization command envelopes.
pub const AUTHZ_OP_VERSION: u32 = 1;
/// Wire version of the query envelope.
pub const QUERY_OP_VERSION: u32 = 1;
/// Wire version of the control envelope.
pub const CONTROL_OP_VERSION: u32 = 1;
/// Wire version of the KV op envelopes.
pub const KV_OP_VERSION: u32 = 1;
/// Wire version of the fenced-lease op family: `KvLease`, `KvLeaseRenew`,
/// `KvRelease`, and `KvCasFenced`. The holder-identity shape was finalized
/// before publication, so it remains at version 1 with the rest of the KV
/// surface. Its required fields have no serde defaults and
/// [`crate::validate::Validate`] rejects any other `v` fail-closed.
pub const KV_LEASE_OP_VERSION: u32 = 1;
/// Wire version of the fork op envelopes.
pub const FORK_OP_VERSION: u32 = 1;
/// Wire version of the graph op envelopes.
pub const GRAPH_OP_VERSION: u32 = 1;
/// Wire version of the consumer-filter envelopes (reads, acknowledgments,
/// previews, tests, catalog requests, and their replies).
pub const FILTER_OP_VERSION: u32 = 1;

/// Wire version of the mixed-operation batch request and reply
/// ([`crate::batch`]). The items inside version themselves: each rides its own
/// op's request frame with that op's own `v`.
pub const BATCH_OP_VERSION: u32 = 1;

/// Versions the change-feed record (`ChangeRecord.v`). Checked by consumers of
/// the changes topic. The feed is advertised by the `WATCH` feature bit.
pub const CHANGE_OP_VERSION: u32 = 1;
/// Wire version of the client-metadata discovery request and reply
/// ([`crate::clients`]).
pub const CLIENT_METADATA_OP_VERSION: u32 = 1;
/// Wire version of public checkpoint mutation requests and status replies.
pub const CHECKPOINT_OP_VERSION: u32 = 1;
/// Iggy-to-Plane destination HTTP carriage version.
pub const DESTINATION_HTTP_OP_VERSION: u32 = 1;
/// Wire version of the agent presence body ([`crate::agent::AgentPresence`]) an
/// agent advertises in its connection metadata. Carried in the body's own `v`
/// field, not out-of-band, because presence rides the opaque connection-metadata
/// bytes with no envelope header to select a decoder.
pub const PRESENCE_OP_VERSION: u32 = 1;
/// Wire version of the agent envelope (the Agent Data Exchange Protocol). Carried
/// out-of-band as the typed `agdx.av` header, never inside the body: a durable
/// log record must select its decoder before any body byte is read.
pub const AGENT_OP_VERSION: u32 = 1;

/// Whether a managed read may carry a [`crate::mutation::ManagedReadEnvelope`]
/// barrier: the reads of the key-value, fork and graph surfaces, whose state
/// the mutation logs fold, and the session reads, whose state the session
/// fold builds from the session source topics.
pub const fn is_barrier_read(code: u32) -> bool {
    matches!(
        code,
        AGDX_KV_GET_CODE
            | AGDX_KV_SCAN_CODE
            | AGDX_KV_NAMESPACES_CODE
            | AGDX_KV_EXISTS_CODE
            | AGDX_FORK_LIST_CODE
            | AGDX_GRAPH_QUERY_CODE
            | AGDX_GRAPH_NEIGHBORS_CODE
            | AGDX_SESSION_GET_CODE
            | AGDX_SESSION_LIST_CODE
            | AGDX_SESSION_EVENTS_CODE
            | AGDX_SESSION_STATE_CODE
            | AGDX_SESSION_LINKS_CODE
            | AGDX_SESSION_SOURCES_CODE
            | AGDX_SESSION_CHANGES_CODE
    )
}

/// Whether a Plane-served managed command changes state and therefore must
/// carry a stable operation identity across transport retries. Iggy's custom
/// authorization mutations use their established request `mutation_id`
/// instead of this Plane envelope.
pub const fn is_idempotent_managed_request(code: u32) -> bool {
    matches!(
        code,
        AGDX_BATCH_CODE
            | AGDX_KV_SET_CODE
            | AGDX_KV_DELETE_CODE
            | AGDX_KV_DELETE_MANY_CODE
            | AGDX_KV_CAS_CODE
            | AGDX_KV_EXPIRE_CODE
            | AGDX_KV_PATCH_CODE
            | AGDX_KV_LEASE_CODE
            | AGDX_KV_LEASE_RENEW_CODE
            | AGDX_KV_RELEASE_CODE
            | AGDX_KV_CAS_FENCED_CODE
            | AGDX_KV_COPY_CODE
            | AGDX_KV_MOVE_CODE
            | AGDX_FORK_CREATE_CODE
            | AGDX_FORK_DELETE_CODE
            | AGDX_FORK_PROMOTE_CODE
            | AGDX_FORK_PUT_CODE
            | AGDX_GRAPH_UPSERT_CODE
            | AGDX_CHECKPOINT_CODE
            | AGDX_CONTROL_PUBLISH_CODE
    )
}