laser_wire/limits.rs
1// Wire caps, enforced client-side so an oversized op fails fast instead of
2// round-tripping, and server-side so a hostile client cannot inflate state.
3
4/// Hard ceiling on rows in a single query reply. A query `limit` must be in
5/// `1..=MAX_PAGE_SIZE`. Callers page through larger result sets with `offset`.
6pub const MAX_PAGE_SIZE: usize = 1000;
7/// Page size a streaming reader pulls when the caller has not set an explicit
8/// limit. Large enough to amortize round-trips, small enough that an
9/// unbounded scan does not spike memory.
10pub const DEFAULT_STREAM_PAGE_SIZE: usize = 100;
11/// Hard cap on the number of `agdx.idx.*` headers a single record may carry.
12/// Total header byte size is already capped, but a buggy producer could stamp
13/// dozens of tiny indexed scalars under the byte budget and slow the
14/// projector. 32 covers every legitimate analytics row with head-room.
15pub const MAX_INDEX_ENTRIES_PER_RECORD: usize = 32;
16/// Cap on the payload bytes the projector **inlines into a materialized row**
17/// (when `inline_payload` is set). This bounds only the copy kept alongside the
18/// indexed row in the read-model backend, never the original message: the Iggy
19/// log always retains the full bytes and a fetch can replay them. Held at
20/// [`MAX_VALUE_BYTES`] (8 MiB) so a single inlined body and a single KV value
21/// share one "max opaque value" ceiling. A body above it still indexes and
22/// still lives in the log. It is just not duplicated into the row, so a typed
23/// fetch decodes from the log (or a claim-check [`ContentType::Ref`] body). The
24/// cap exists because multi-MB BLOBs per row bloat the embedded query DB and
25/// slow scans.
26///
27/// [`ContentType::Ref`]: crate::content::ContentType::Ref
28pub const MAX_PROJECTOR_PAYLOAD_BYTES: usize = MAX_VALUE_BYTES;
29
30// KV caps. Keys are arbitrary bytes (text, binary, anything), at
31// most 512 bytes. Values are arbitrary opaque bytes, capped at 8 MiB:
32// generous for session, flag, counter, cached-JSON, and chunked working state,
33// yet well under the frame ceiling so a set request and a get reply each ride
34// one socket frame with envelope head-room.
35/// Maximum KV key length, in bytes.
36pub const MAX_KEY_BYTES: usize = 512;
37/// Maximum KV value size, in bytes.
38pub const MAX_VALUE_BYTES: usize = 8 * 1024 * 1024;
39/// Hard ceiling on a KV scan page (LaserData Cloud clamps to it).
40pub const MAX_SCAN_LIMIT: usize = 1000;
41/// KV scan page size when the caller sets none.
42pub const DEFAULT_SCAN_LIMIT: usize = 100;
43/// The namespace a KV call without an explicit one binds to. A namespace is a
44/// logical bucket: keys are unique within it, scans are scoped to it, and one
45/// user's namespaces stay isolated from another's.
46pub const DEFAULT_NAMESPACE: &str = "default";
47/// Maximum KV (and memory) namespace length, in bytes. A namespace is a
48/// caller-chosen bucket name that flows into grant matching and scan scoping,
49/// so it is bounded and control-character-free, while its charset stays open
50/// (namespaces legitimately carry `/`-style hierarchy).
51pub const MAX_NAMESPACE_BYTES: usize = 128;
52/// Maximum UTF-8 byte length of a session label.
53pub const MAX_SESSION_LABEL_BYTES: usize = 256;
54/// Maximum UTF-8 bytes of a session list's text filter.
55pub const MAX_SESSION_TEXT_QUERY_BYTES: usize = 1024;
56/// Most session ids one heartbeat record lists. A process with more leases in
57/// one stream splits them over several records.
58pub const MAX_HEARTBEAT_SESSIONS: usize = 2048;
59pub const MAX_STATE_PATCH_OPS: usize = 256;
60pub const MAX_STATE_DOCUMENT_BYTES: usize = 8 * 1024 * 1024;
61pub const MAX_MANIFEST_FRAGMENTS: usize = 1024;
62/// Maximum lease holder identity length, in bytes. A holder id is a stable
63/// node or worker identifier that flows into lease matching and audit events,
64/// so it is required to be non-empty and length-bounded. Its charset is open.
65pub const MAX_HOLDER_ID_BYTES: usize = 128;
66/// Shortest lease (and renewal) lifetime a request may ask for, in
67/// microseconds. Unlike a scan limit, a lease TTL is not clamped up by the
68/// store: a grant is only ever shorter than the request, so a floor is the only
69/// place the contract can keep a lease long enough to survive one round trip
70/// plus the holder's own renewal cadence. Below it, a holder would trip its
71/// deadline before it could renew, which is a caller bug worth rejecting
72/// locally rather than a lease worth granting.
73pub const MIN_LEASE_TTL_MICROS: u64 = 1_000_000;
74/// Longest lease (and renewal) lifetime a request may ask for, in
75/// microseconds. A lease is a bounded-TTL lock whose whole purpose is that a
76/// dead holder's ownership expires. An unbounded request would let one crashed
77/// holder park a key for hours. The store may still grant less (`granted_ttl_micros`), so this bounds the
78/// *request*, and a holder needing longer renews.
79pub const MAX_LEASE_TTL_MICROS: u64 = 5 * 60 * 1_000_000;
80
81// Fork caps. A fork id is a caller-chosen name (e.g. `"experiment-2026-q2"`),
82// so its length is a validatable input cap like a KV key: the client rejects an
83// over-long id before the round-trip. Per-deployment resource ceilings (how
84// many forks may exist) are NOT here: those are a managed-side policy a client
85// cannot validate against, surfaced only as a `ForkError`.
86/// Maximum fork id length, in bytes.
87pub const MAX_FORK_ID_BYTES: usize = 128;
88
89// Authorization caps. A role name is an admin-chosen identifier that flows
90// into grant matching, audit events, and console rendering, so it shares the
91// fork-id shape: a strict safelist plus a byte cap every tier validates the
92// same way. 64 matches the common RBAC-identifier norm.
93/// Maximum role name length, in bytes.
94pub const MAX_ROLE_NAME_BYTES: usize = 64;
95/// Maximum authorization mutation id length, in bytes.
96pub const MAX_AUTHZ_MUTATION_ID_BYTES: usize = 64;
97
98/// Ceiling on one `[len: u32 LE][bytes]` frame on the managed-command sockets,
99/// enforced by both the server and LaserData Cloud. A reply above it is replaced by
100/// a structured too-large error rather than truncated. The `u32` length prefix
101/// addresses far more (4 GiB), so this is a deliberate per-frame memory bound on
102/// the whole-frame buffer, not a transport limit. Every consumer of the managed
103/// sockets (the server-side dispatch, the streaming server sidecar, the reply-byte budget)
104/// MUST source this one constant rather than redefining its own frame cap, so
105/// the layers cannot disagree and a reply admitted by one is not rejected by the
106/// next. Changing it moves all of them in lockstep.
107pub const MAX_FRAME_BYTES: usize = 64 * 1024 * 1024;
108/// Hard ceiling on a single query reply's serialized bytes. A reply rides the
109/// managed-command socket as one `[len: u32 LE][bytes]` frame, buffered whole,
110/// so it is bounded by [`MAX_FRAME_BYTES`] by construction (the two are held
111/// equal on purpose so anything a backend admits to a reply, the socket can
112/// frame). Larger result sets are not returned as one oversized reply: they
113/// page via [`MAX_PAGE_SIZE`] rows plus `offset`. Raising this means raising
114/// `MAX_FRAME_BYTES` in lockstep across the server, LaserData Cloud, and the
115/// socket buffer, since it is the same frame.
116pub const MAX_QUERY_REPLY_BYTES: usize = MAX_FRAME_BYTES;
117/// Maximum UTF-8 bytes in an operational index name or query engine label.
118pub const MAX_QUERY_NAME_BYTES: usize = 255;
119/// Maximum UTF-8 bytes in a projection id.
120pub const MAX_PROJECTION_ID_BYTES: usize = 255;
121/// Maximum UTF-8 bytes in a projection's human-readable name.
122pub const MAX_PROJECTION_NAME_BYTES: usize = 255;
123/// Maximum UTF-8 bytes in an index field's name, JSON pointer, or vector field pointer.
124pub const MAX_INDEX_FIELD_BYTES: usize = 255;
125/// Maximum UTF-8 bytes in a writer schema's name.
126pub const MAX_SCHEMA_NAME_BYTES: usize = 255;
127/// Maximum UTF-8 bytes in one read-only raw SQL statement.
128pub const MAX_RAW_SQL_BYTES: usize = 64 * 1024;
129/// Maximum number of positional raw SQL parameters.
130pub const MAX_QUERY_PARAMETERS: usize = 1024;
131/// Largest query page `offset`. Deeper rows are reached by narrowing the
132/// filter, for example by a time range.
133pub const MAX_QUERY_OFFSET: u64 = 1_000_000;
134/// Maximum predicate nodes in one structured filter tree.
135pub const MAX_QUERY_PREDICATES: usize = 4096;
136/// Maximum selected, grouped, sorted, or exact-match fields in one query.
137pub const MAX_QUERY_FIELDS: usize = 4096;
138/// Maximum vector dimensions accepted by the generic query contract.
139pub const MAX_VECTOR_DIMENSIONS: usize = 65_536;
140
141/// The most managed requests one mixed-operation batch
142/// ([`AGDX_BATCH_CODE`](crate::codes::AGDX_BATCH_CODE)) may carry. Bounds the
143/// server work one frame can demand. The assembled reply is additionally
144/// bounded by [`MAX_FRAME_BYTES`] like any other.
145pub const MAX_BATCH_OPS: usize = 64;
146
147// Agent Data Exchange Protocol (AGDX) envelope caps, sized to sit inside the existing cap
148// family. The metadata caps are the load-bearing ones: that field is
149// bridge-injected, so a hostile or buggy edge gets a publish-time rejection
150// instead of inflating every record on a topic.
151/// Cap on the envelope's vocabulary strings (`operation`, `tool`,
152/// `finish_reason`), each.
153pub const MAX_AGENT_STRING_BYTES: usize = 256;
154/// Cap on a producer-supplied idempotency key.
155pub const MAX_IDEMPOTENCY_KEY_BYTES: usize = 64;
156/// Max entries in an envelope's `metadata` map.
157pub const MAX_METADATA_ENTRIES: usize = 32;
158/// Max bytes in one `metadata` key.
159pub const MAX_METADATA_KEY_BYTES: usize = 256;
160/// Max bytes in one `metadata` value (scalar/text size).
161pub const MAX_METADATA_VALUE_BYTES: usize = 1024;
162/// Max total bytes across the whole `metadata` map.
163pub const MAX_METADATA_TOTAL_BYTES: usize = 8192;
164/// Cap on a [`BodyRef`](crate::agent::BodyRef) `reference` string (a URI,
165/// object key, or KV key naming where the externalized body lives).
166pub const MAX_BODY_REFERENCE_BYTES: usize = 1024;
167/// Max capability entries on an [`AgentCard`](crate::agent::AgentCard).
168pub const MAX_CARD_CAPABILITIES: usize = 64;
169/// How long a quarantine or unquarantine fact stays valid after its signer
170/// stamps `deadline_micros`, the five minutes of clock skew Kerberos tolerates.
171pub const REGISTRY_FACT_TTL_MICROS: u64 = 5 * 60 * 1_000_000;
172/// The longest validity a registry reader accepts on a fact, and how long it
173/// remembers an applied fact's record id, so a fact cannot outlive its replay
174/// guard.
175pub const MAX_REGISTRY_FACT_TTL_MICROS: u64 = 24 * 60 * 60 * 1_000_000;
176/// Ceiling on a connection's advertised metadata (`AGDX_SET_CLIENT_METADATA`).
177/// The metadata is an opaque byte payload any client may set, not agent-only: an
178/// agent advertises its card under the AGDX schema, a regular app sets whatever
179/// blob its own tooling and the console interpret. The ceiling bounds the
180/// per-connection state the streaming server holds and, because the discovery
181/// read (`AGDX_GET_CLIENTS_METADATA`) returns a page of N connections at once, it
182/// also bounds a page at `N * this`. 64 KiB is generous for any card or app blob
183/// while keeping a page well under the frame cap even at the max page size.
184pub const MAX_CLIENT_METADATA: usize = 64 * 1024;
185
186// Memory and graph caps, sized inside the existing cap family. A memory body
187// shares the opaque-value ceiling. A recall page shares the query page cap.
188/// Max bytes in one memory item's body (shares the opaque-value ceiling).
189pub const MAX_MEMORY_BODY_BYTES: usize = MAX_VALUE_BYTES;
190/// Max items a single recall returns (shares the query page cap).
191pub const MAX_RECALL_LIMIT: usize = MAX_PAGE_SIZE;
192
193/// Byte cap on a lexical search's query text (`TextQuery.query`).
194pub const MAX_TEXT_QUERY_BYTES: usize = 1024;
195/// Recall page size when the caller sets none.
196pub const DEFAULT_RECALL_LIMIT: usize = DEFAULT_STREAM_PAGE_SIZE;
197/// Max tags on one memory item.
198pub const MAX_MEMORY_TAGS: usize = 16;
199/// Max bytes in one memory tag.
200pub const MAX_MEMORY_TAG_BYTES: usize = 64;
201/// Max bytes in a memory item id, its kind word, or a forget or feedback target.
202pub const MAX_MEMORY_ID_BYTES: usize = 255;
203/// Maximum graph name length, in bytes. Bounded and control-character-free
204/// like a namespace: the name keys the projection registry and every
205/// traversal request.
206pub const MAX_GRAPH_NAME_BYTES: usize = 128;
207/// Hard ceiling on the hop depth a single graph traversal may request.
208pub const MAX_GRAPH_TRAVERSE_DEPTH: u32 = 8;
209/// Hard ceiling on nodes plus edges in one graph reply.
210pub const MAX_GRAPH_RESULT_ELEMENTS: usize = 10_000;
211/// Max labels on one graph node.
212pub const MAX_GRAPH_NODE_LABELS: usize = 16;
213/// Max bytes in one graph node label or edge type.
214pub const MAX_GRAPH_LABEL_BYTES: usize = 128;
215/// Max encoded bytes of a node or edge `source` provenance reference. A source
216/// names a stream, topic, key, or id, all of which are bounded inputs already,
217/// so this is a defensive ceiling against a hostile or buggy upsert inflating
218/// per-element state. Sized at two key-lengths, since the largest variant (a
219/// key-value source) names both a namespace and a key, far under the opaque
220/// value ceiling, as a source ref is a short pointer, not a payload.
221pub const MAX_SOURCE_REF_BYTES: usize = 2 * MAX_KEY_BYTES;
222
223// Consumer-filter caps. A filter is evaluated per record on a streaming server
224// shard, so its size and shape are bounded before it compiles.
225/// Maximum encoded writer schema used by a consumer-filter decoder.
226pub const MAX_FILTER_SCHEMA_BYTES: usize = 1024 * 1024;
227/// Maximum nesting in an Avro writer-schema document.
228pub const MAX_FILTER_SCHEMA_DEPTH: usize = 64;
229/// Max encoded bytes of one consumer filter.
230pub const MAX_FILTER_BYTES: usize = 8192;
231/// Max expression nodes in one filter, literals inside lists included.
232pub const MAX_FILTER_NODES: usize = 128;
233/// Max nesting depth of a filter expression.
234pub const MAX_FILTER_DEPTH: usize = 8;
235/// Max JSON nesting depth a payload decoder accepts. Every server bound and
236/// SDK guard uses this one value. It stays below the `serde_json` recursion
237/// limit, so an over-deep payload is reported as `too_deep`, not `malformed`.
238pub const MAX_FILTER_PARSE_DEPTH: usize = 127;
239/// Max segments in one field path.
240pub const MAX_FILTER_PATH_SEGMENTS: usize = 16;
241/// Max bytes in one field path or header key.
242pub const MAX_FILTER_PATH_BYTES: usize = 256;
243/// Max items in one `in` list.
244pub const MAX_FILTER_LIST_ITEMS: usize = 64;
245/// Max bytes in one string literal.
246pub const MAX_FILTER_STRING_BYTES: usize = 1024;
247/// Max bytes in a saved filter's name.
248pub const MAX_FILTER_NAME_BYTES: usize = 128;
249/// Max bytes in a saved filter's description.
250pub const MAX_FILTER_DESCRIPTION_BYTES: usize = 1024;
251/// Max bytes in a stream, topic, consumer, or group name a filtered read names.
252pub const MAX_FILTER_SOURCE_NAME_BYTES: usize = 255;
253/// Max records one filtered page returns.
254pub const MAX_FILTERED_PAGE_RECORDS: u32 = 1000;
255/// Max reply bytes one filtered page may carry.
256pub const MAX_FILTERED_PAGE_BYTES: u32 = 8 * 1024 * 1024;
257/// Max source records one filtered page may ask to examine. The server
258/// lowers it to its own budget.
259pub const MAX_FILTERED_PAGE_EXAMINED: u32 = 100_000;
260/// Max milliseconds a filtered wait is held by the server.
261pub const MAX_FILTERED_WAIT_MS: u32 = 20_000;
262/// Max partitions one filtered wait names.
263pub const MAX_FILTERED_WAIT_PARTITIONS: usize = 1024;
264/// Max waits one filtered wait cancel names.
265pub const MAX_FILTERED_WAIT_CANCEL_IDS: usize = 64;
266/// Max records one preview may examine.
267pub const MAX_FILTER_PREVIEW_EXAMINED: u32 = 10_000;
268/// Max records one preview returns.
269pub const MAX_FILTER_PREVIEW_RECORDS: u32 = 100;
270/// Max payload bytes a preview record carries as text.
271pub const MAX_FILTER_PREVIEW_PAYLOAD_BYTES: usize = 4096;
272/// Max payload bytes a supplied test sample may carry.
273pub const MAX_FILTER_SAMPLE_BYTES: usize = 1024 * 1024;
274/// Max headers a supplied test sample may carry.
275pub const MAX_FILTER_SAMPLE_HEADERS: usize = 64;
276/// Max page size of a catalog list.
277pub const MAX_FILTER_CATALOG_PAGE: u32 = 200;