laser_wire/
headers.rs

1// Header conventions. Format framing rides `agdx.*`, and index values ride the
2// `agdx.idx.` namespace as small scalars. The reserved keys are deliberately SHORT
3// and their values TYPED (u8 content-type code, u32 schema id, bool inline
4// flag): these headers ride every message, so at millions of messages the
5// key+value bytes are real bandwidth. The byte layout also matches the
6// planned native Iggy reserved-block carve (`schema_id: u32, content_type:
7// u8`), so the eventual migration is a dispatch-key swap.
8
9/// Header key: the wire codec tag (`u8` code, see
10/// [`ContentType::code`](crate::content::ContentType::code)).
11pub const CONTENT_TYPE: &str = "agdx.ct";
12/// Header key carrying the `u32` writer-schema id (typed header value) for a
13/// schema-first codec (Avro, Protobuf). The LaserData Cloud resolves it against
14/// its schema registry to decode the body. A bridge that lives in LaserData Cloud
15/// until Iggy gains native schema dispatch.
16pub const SCHEMA_ID: &str = "agdx.sid";
17/// Header key carrying the 32-byte logical schema fingerprint for an Arrow IPC stream.
18pub const LOGICAL_SCHEMA_FINGERPRINT: &str = "agdx.sfp";
19/// Prefix marking an indexed-field header (`agdx.idx.<name>`).
20pub const IDX_PREFIX: &str = "agdx.idx.";
21/// Header key: per-record inline-payload override (`bool` typed value).
22/// Stamped so the projector keeps a copy of the opaque payload bytes inline
23/// with the materialized row. Absent means the index row carries only indexed
24/// scalars and metadata while Iggy keeps the original body in the log.
25pub const INLINE_PAYLOAD: &str = "agdx.inline";
26/// Header key: which projection a record routes to. Opaque string by design
27/// (a name + version like `"reading.v1"`), deliberately distinct from `agdx.sid`,
28/// which selects a codec's writer schema rather than a materialization rule.
29pub const PROJECTION_REF: &str = "agdx.ref";
30/// Header key for the generic request/reply correlation id. Short on purpose
31/// (it rides every request/reply pair) and independent of any agentic header
32/// so the generic substrate works without provenance.
33pub const CORRELATION_ID: &str = "agdx.corr";
34
35// Well-known projected field names (the `agdx.idx.*` value after the prefix).
36/// Reserved indexed-field name for the event type.
37pub const FIELD_MESSAGE_TYPE: &str = "message_type";
38/// Reserved indexed-field name for the timestamp (epoch micros).
39pub const FIELD_TS: &str = "ts";
40/// Default field/pointer for the embedding vector.
41pub const VECTOR_FIELD: &str = "embedding";
42/// Result-row header key carrying a tumbling window's lower edge (epoch
43/// micros) when an aggregate query sets a window. Byte-identical to the
44/// LaserData Cloud's `window_start` column.
45pub const WINDOW_START: &str = "window_start";
46
47// On-wire header caps (Iggy-level, not provenance-specific).
48/// Soft cap on total header bytes per record.
49pub const HEADER_SOFT_CAP: usize = 1024;
50/// Per-header wire overhead counted toward the soft cap (key length, value
51/// kind, value length), so the cap reflects on-wire size.
52pub const HEADER_FRAMING_BYTES: usize = 9;
53/// Maximum bytes in a single header value (Iggy serializes the length as u8).
54pub const HEADER_VALUE_MAX: usize = 255;
55
56// The provenance dictionary. OTel `gen_ai.*` keys stay spec-exact (verified
57// against the gen-ai semconv registry) so traces correlate across tooling.
58// Custom keys are deliberately short because they ride every agentic message.
59/// Header key: conversation id (OTel `gen_ai.conversation.id`).
60pub const CONVERSATION_ID: &str = "gen_ai.conversation.id";
61/// The projected-column name a deployment materializes the
62/// [`CONVERSATION_ID`] header under, so every projection row is filterable by
63/// the conversation that produced it without a producer stamping an index
64/// header. The stable short field name the query surface's conversation lens
65/// and the graph/KV conversation columns all agree on.
66pub const CONVERSATION_FIELD: &str = "conversation_id";
67/// Header key: the producing agent's id.
68pub const AGENT_ID: &str = "gen_ai.agent.id";
69/// Header key: LLM input/prompt tokens.
70pub const USAGE_INPUT_TOKENS: &str = "gen_ai.usage.input_tokens";
71/// Header key: LLM output/completion tokens.
72pub const USAGE_OUTPUT_TOKENS: &str = "gen_ai.usage.output_tokens";
73/// Header key: the message this one is a reply to.
74pub const CAUSAL_PARENT: &str = "agdx.cause";
75/// Header key: the conversation this was spawned from.
76pub const PARENT_CONVERSATION_ID: &str = "agdx.parent_conv";
77/// Header key: the root of the conversation tree.
78pub const ROOT_CONVERSATION_ID: &str = "agdx.root_conv";
79/// Header key: the agent this message is addressed to.
80pub const TARGET_AGENT_ID: &str = "agdx.to";
81/// Header key: reserved alias for an on-behalf-of subject. Signed delegation
82/// uses the envelope metadata key `on_behalf_of`.
83pub const DELEGATED_BY: &str = "agdx.on_behalf_of";
84/// Header key: dedup / reply-correlation key.
85pub const IDEMPOTENCY_KEY: &str = "agdx.idem";
86/// Header key: drop-dead time (epoch micros).
87pub const DEADLINE: &str = "agdx.deadline";
88/// Header key: LLM call cost in USD.
89pub const COST_USD: &str = "agdx.cost";
90/// Header key: the strictly-monotonic per-task fence the producer held (`u64`).
91/// A consumer rejects a log-resident effect whose fence is below the highest it
92/// has accepted for the task, so a stale-holder replay cannot re-fire.
93pub const FENCE: &str = "agdx.fence";
94/// Header key: the agent envelope's wire version (`u32` typed value).
95/// Rides outside the CBOR body so projections, a viewer, and rolling-upgrade
96/// consumers pick the decoder (and filter per version) without decoding the body.
97pub const AGENT_VERSION: &str = "agdx.av";
98
99// Memory scope. Carried as headers so the fold keys the read view on the scope,
100// not the topic, and one shared topic still resolves every context.
101/// Header key: the logical memory namespace the read view materializes under.
102pub const MEMORY_NAMESPACE: &str = "agdx.mem.ns";
103/// Header key: the user scope layer. Unscoped recall widens across it.
104pub const MEMORY_USER: &str = "agdx.mem.user";
105/// Header key: the app scope layer. Unscoped recall widens across it.
106pub const MEMORY_APP: &str = "agdx.mem.app";
laser_wire/headers.rs

laser_wire/
headers.rs
