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