{"row":{"id":"ADR-033","title":"L0 foundational types: Cost, UUIDv7, TrustLevel, TokenUsage evolution","file":"adr-033-l0-foundational-types.md","status":"accepted","date":"2026-04-16","cites":11,"supersedes":[],"superseded_by":[],"layers":["L0","L0.5"],"tags":["l0","types","foundational","cost"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-033: L0 foundational types: Cost, UUIDv7, TrustLevel, TokenUsage evolution","id":"adr-033-l0-foundational-types-cost-uuidv7-trustlevel-tokenusage-evolution"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"L0 today contains exactly two crates: "},{"k":"code","text":"nika-error"},{"k":"text","text":" (error codes,\nNIKA-XXX ranges) and "},{"k":"code","text":"nika-catalog"},{"k":"text","text":" (provider/model catalog data).\nNeither holds the foundational "},{"k":"em","text":"value"},{"k":"text","text":" types — Cost, IDs, TrustLevel —\nthat L1 effect crates and L2 verb crates will need."}]},{"k":"p","inline":[{"k":"text","text":"The kernel currently leaks several types that should live one layer\nbelow it."}]},{"k":"p","inline":[{"k":"strong","text":"TokenUsage"},{"k":"text","text":" ("},{"k":"code","text":"crates/nika-kernel-ai/src/provider.rs:247-256"},{"k":"text","text":") has 4 fields:"}]},{"k":"code","lang":"rust","text":"#[non_exhaustive]\npub struct TokenUsage {\n    pub input_tokens: u64,\n    pub output_tokens: u64,\n    pub cache_read_tokens: Option<u64>,\n    pub cache_write_tokens: Option<u64>,\n}"},{"k":"p","inline":[{"k":"text","text":"This is missing several axes that real providers already bill for:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"reasoning_tokens"},{"k":"text","text":" — Anthropic extended thinking, OpenAI o3."}],[{"k":"code","text":"thinking_tokens"},{"k":"text","text":" — separate from reasoning; visible thinking trace."}],[{"k":"code","text":"cache_creation_tokens"},{"k":"text","text":" — Anthropic prompt caching write side."}],[{"k":"code","text":"image_tokens_in"},{"k":"text","text":" / "},{"k":"code","text":"image_tokens_out"},{"k":"text","text":" — vision input + image output."}],[{"k":"code","text":"audio_tokens_in"},{"k":"text","text":" / "},{"k":"code","text":"audio_tokens_out"},{"k":"text","text":" — Gemini Live, GPT-4o audio."}],[{"k":"code","text":"video_tokens"},{"k":"text","text":" — Gemini 1.5 Pro video."}],[{"k":"code","text":"tool_use_tokens"},{"k":"text","text":" — some providers bill tool definitions separately."}]]},{"k":"p","inline":[{"k":"strong","text":"MemoryId"},{"k":"text","text":" ("},{"k":"code","text":"crates/nika-kernel-ai/src/memory.rs:21-22"},{"k":"text","text":") is "},{"k":"code","text":"MemoryId(u128)"},{"k":"text","text":"\nwith "},{"k":"code","text":"Display"},{"k":"text","text":" as "},{"k":"code","text":"mem-{hex32}"},{"k":"text","text":". The "},{"k":"code","text":"u128"},{"k":"text","text":" is opaque random; not\ntime-sortable. Memory queries that want chronological ordering need\na separate timestamp."}]},{"k":"p","inline":[{"k":"strong","text":"TaskId"},{"k":"text","text":" ("},{"k":"code","text":"crates/nika-kernel-core/src/types.rs"},{"k":"text","text":") is "},{"k":"code","text":"TaskId(String)"},{"k":"text","text":" —\na bare string wrapper, no validation, no time ordering, no parse\nguarantee."}]},{"k":"p","inline":[{"k":"strong","text":"Cost"},{"k":"text","text":" is currently "},{"k":"code","text":"cost_usd: Option<f64>"},{"k":"text","text":" on "},{"k":"code","text":"InferResponse"},{"k":"text","text":"\n("},{"k":"code","text":"crates/nika-kernel-ai/src/provider.rs:307"},{"k":"text","text":"). Floating-point accumulation\nacross thousands of API calls drifts; we cannot ship billing on f64."}]},{"k":"p","inline":[{"k":"strong","text":"TrustLevel"},{"k":"text","text":" is referenced by Shield error codes\n(NIKA-380..389: "},{"k":"code","text":"nika-error/src/codes.rs"},{"k":"text","text":") but currently passed as\nhardcoded strings in workflow engine code. No enum exists in any\nadmitted crate."}]},{"k":"p","inline":[{"k":"text","text":"L1 effect crates and L2 verb crates need a shared vocabulary for these\nvalues. Putting them in "},{"k":"code","text":"nika-kernel"},{"k":"text","text":" (L0.5) creates an upward\ndependency from L0 catalog → L0.5 kernel just to share an "},{"k":"code","text":"IdGenerator"},{"k":"text","text":"\ntarget type. Putting them in L0 "},{"k":"code","text":"nika-error"},{"k":"text","text":" is the only stratum that\nall higher layers already depend on."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"Add 23 foundational value types to `nika-error` (L0). All higher\nlayers re-export or import directly. `nika-error` keeps its dependency\nbudget: std + serde + thiserror + miette only."}]},{"k":"p","inline":[{"k":"text","text":"The 23 types group into 9 modules:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Module · Types · Why"}],[{"k":"text","text":"`cost` · `Cost(i128)` · nano-USD; arithmetic; Display `\u0024X.XXXXXX`; no float drift"}],[{"k":"text","text":"`id` · 9 newtyped UUIDv7 IDs: `RunId`, `EventId`, `TraceId`, `SpanId`, `CorrelationId`, `WorkflowId`, `TenantId`, `ProviderId`, `ModelId` · type-safe ID separation; chronological ordering"}],[{"k":"text","text":"`trust` · `TrustLevel(u8)` lattice + `meet` / `join` / `is_at_least` · Shield gating becomes a compile-time invariant"}],[{"k":"text","text":"`retry` · `RetryConfig`, `ErrorCategory` · shared vocabulary for ADR-019's stratified retry"}],[{"k":"text","text":"`budget` · `BudgetDirective` enum · per-task budget enforcement (cost, tokens, time)"}],[{"k":"text","text":"`schema` · `EventSchemaVersion`, `TraceFormatVersion` · wire-compat versioning for events + traces"}],[{"k":"text","text":"`hash` · `Blake3Hash`, `ContentDigest`, `BlobRef` · content-addressed storage primitive"}],[{"k":"text","text":"`baggage` · W3C Baggage (max 64 entries, 8 KB cap) · OTel propagation across spans"}],[{"k":"text","text":"`resource` · OTel `Resource { service_name, attrs }` · OTel resource attributes, span enrichment"}]]},{"k":"p","inline":[{"k":"strong","text":"Migration of existing kernel types"},{"k":"text","text":" (lands in S1-C):"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"MemoryId(u128)"},{"k":"text","text":" → "},{"k":"code","text":"MemoryId(Uuid)"},{"k":"text","text":" UUIDv7-backed. "},{"k":"code","text":"Display"},{"k":"text","text":" becomes\n"},{"k":"code","text":"mem-{uuid}"},{"k":"text","text":". Existing serde format moves to UUIDv7 string. "},{"k":"strong","text":"Pre-S1-C\ncallers will need to be re-codegened"},{"k":"text","text":" (mock IDs in tests included)."}],[{"k":"code","text":"TaskId(String)"},{"k":"text","text":" → "},{"k":"code","text":"TaskId(Uuid)"},{"k":"text","text":" UUIDv7-backed. Validation on parse."}],[{"k":"code","text":"InferResponse.cost_usd: Option<f64>"},{"k":"text","text":" → "},{"k":"code","text":"cost: Option<Cost>"},{"k":"text","text":"."}],[{"k":"code","text":"TokenUsage"},{"k":"text","text":" 4-field → 18-field expansion (reasoning, thinking,\ncache_creation, image*, audio*, video, tool_use, ...). All new fields\n"},{"k":"code","text":"Option<u64>"},{"k":"text","text":" so producers opt in. "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" makes the\nexpansion non-breaking."}]]},{"k":"p","inline":[{"k":"strong","text":"Cost arithmetic"},{"k":"text","text":" (concrete shape):"}]},{"k":"code","lang":"rust","text":"#[non_exhaustive]\npub struct Cost(i128); // nano-USD: 1 USD = 1_000_000_000\n\nimpl Cost {\n    pub const ZERO: Cost;\n    pub fn from_usd(usd: f64) -> Cost; // saturating\n    pub fn from_nano_usd(n: i128) -> Cost;\n    pub fn as_nano_usd(&self) -> i128;\n    pub fn as_usd(&self) -> f64; // lossy display\n}\n\nimpl Add for Cost { ... }\nimpl Sub for Cost { ... }\nimpl Mul<u64> for Cost { ... }\nimpl Display for Cost { /* \"\u0024X.XXXXXX\" */ }"},{"k":"p","inline":[{"k":"text","text":"i128 gives a range of ±1.7e29 nano-USD = ±170 quintillion USD. Enough\nfor any conceivable aggregation horizon."}]},{"k":"p","inline":[{"k":"strong","text":"TrustLevel lattice"},{"k":"text","text":" (concrete shape):"}]},{"k":"code","lang":"rust","text":"#[non_exhaustive]\npub struct TrustLevel(u8); // Untrusted=0, LocalTrusted=128, Trusted=255\n\nimpl TrustLevel {\n    pub const UNTRUSTED: Self;\n    pub const LOCAL_TRUSTED: Self;\n    pub const TRUSTED: Self;\n    pub fn meet(self, other: Self) -> Self; // min\n    pub fn join(self, other: Self) -> Self; // max\n    pub fn is_at_least(self, threshold: Self) -> bool;\n}\n\nimpl Display for TrustLevel { ... }\nimpl FromStr for TrustLevel { ... }\nimpl Serialize / Deserialize for TrustLevel { ... }"},{"k":"p","inline":[{"k":"text","text":"Lattice ops let Shield gate \"this tool requires "},{"k":"code","text":"Trusted"},{"k":"text","text":" data\" with a\ncompile-time-checkable contract."}]},{"k":"p","inline":[{"k":"strong","text":"UUIDv7"},{"k":"text","text":" is chosen over UUIDv4 because:"}]},{"k":"list","ordered":true,"items":[[{"k":"text","text":"Time-sortable: natural chronological ordering for memory queries,\nevent logs, task lookup."}],[{"k":"text","text":"Random suffix preserves uniqueness at high creation rates."}],[{"k":"text","text":"Wire-compatible with "},{"k":"code","text":"uuid::Uuid"},{"k":"text","text":" ecosystem."}]]},{"k":"p","inline":[{"k":"code","text":"nika-error"},{"k":"text","text":" adds "},{"k":"code","text":"uuid = { version = \"1\", features = [\"v7\", \"serde\"] }"},{"k":"text","text":"\nto its dep list (S1-C lands the dep)."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Single L0 vocabulary across all higher layers — no more \"what's a\nTrustLevel\" ambiguity."}],[{"k":"text","text":"Cost arithmetic moves from f64 (drift) to i128 (exact) — billing\nbecomes auditable."}],[{"k":"text","text":"UUIDv7 IDs give natural chronological ordering for memory queries\nand event logs without a parallel timestamp field."}],[{"k":"text","text":"TokenUsage expansion (4 → 18 fields) covers every billable axis\ncurrent providers expose. New axes land additively under\n"},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":"."}],[{"k":"text","text":"TrustLevel becomes a typed value with lattice ops; Shield can express\n\"tool X requires "},{"k":"code","text":"at_least(LocalTrusted)"},{"k":"text","text":"\" as code, not docs."}],[{"k":"code","text":"RetryConfig"},{"k":"text","text":" + "},{"k":"code","text":"ErrorCategory"},{"k":"text","text":" give ADR-019's three retry layers a\nshared vocabulary."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"23 new types is a bigger admit than typical for L0. Mitigated by\ntopological ordering in S1-C (hash → schema → id → baggage → trust →\nretry → budget → cost → resource)."}],[{"k":"text","text":"Migrating "},{"k":"code","text":"MemoryId"},{"k":"text","text":" and "},{"k":"code","text":"TaskId"},{"k":"text","text":" to UUIDv7 changes their wire\nformat (existing snapshots in tests must be refreshed). Pre-emption:\nno production data exists yet (Diamond is orphan-branch, no users)."}],[{"k":"code","text":"nika-error"},{"k":"text","text":" gains a "},{"k":"code","text":"uuid"},{"k":"text","text":" dependency. Acceptable — "},{"k":"code","text":"uuid"},{"k":"text","text":" is\nstd-only with "},{"k":"code","text":"serde"},{"k":"text","text":" + "},{"k":"code","text":"v7"},{"k":"text","text":" features; no transitive runtime."}],[{"k":"text","text":"TokenUsage 18-field struct is wider; serialization size grows.\nMitigated: all new fields are "},{"k":"code","text":"Option<u64>"},{"k":"text","text":" and producers omit them\nby default."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-error"},{"k":"text","text":" already crosses 184 tests (largest crate by test\ncount); adding ~70-90 more keeps it under reasonable test budget."}],[{"k":"text","text":"Some types (RetryConfig, BudgetDirective) live in "},{"k":"code","text":"nika-error"},{"k":"text","text":"\neven though \"error\" is not literally what they describe. This is\nconsistent with "},{"k":"code","text":"nika-error"},{"k":"text","text":" being the de-facto \"L0 foundation\"\ncrate. We may rename it to "},{"k":"code","text":"nika-foundation"},{"k":"text","text":" at v0.82+ if friction\nappears."}]]},{"k":"h","depth":2,"text":"Evidence / Affected code","id":"evidence--affected-code"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"crates/nika-kernel-ai/src/provider.rs:247-256"},{"k":"text","text":" — current 4-field\nTokenUsage."}],[{"k":"code","text":"crates/nika-kernel-ai/src/provider.rs:307"},{"k":"text","text":" — current\n"},{"k":"code","text":"cost_usd: Option<f64>"},{"k":"text","text":"."}],[{"k":"code","text":"crates/nika-kernel-ai/src/memory.rs:21-22"},{"k":"text","text":" — current "},{"k":"code","text":"MemoryId(u128)"},{"k":"text","text":"."}],[{"k":"code","text":"crates/nika-kernel-core/src/types.rs"},{"k":"text","text":" — current "},{"k":"code","text":"TaskId(String)"},{"k":"text","text":"."}],[{"k":"code","text":"crates/nika-error/src/codes.rs"},{"k":"text","text":" — Shield NIKA-380..389 (TrustLevel\nconsumers)."}],[{"k":"code","text":"docs/architecture/forward-compat-invariants.md"},{"k":"text","text":" — Pattern 2\n("},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":"), INV-019 (per-crate "},{"k":"code","text":"new()"},{"k":"text","text":" ctor), INV-025\n(verb error enums "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":")."}],[{"k":"text","text":"ADR-019 — names "},{"k":"code","text":"RetryConfig"},{"k":"text","text":" + "},{"k":"code","text":"ErrorCategory"},{"k":"text","text":" as the shared\nretry vocabulary that lands here."}],[{"k":"text","text":"ADR-034 — L0.5 traits expansion that depends on these L0 types\n(IdGenerator returns "},{"k":"code","text":"Uuid"},{"k":"text","text":", BillingSink takes "},{"k":"code","text":"Cost"},{"k":"text","text":")."}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A -- Keep `cost_usd` as `f64`","id":"alt-a----keep-cost_usd-as-f64"},{"k":"p","inline":[{"k":"text","text":"\"Floats are simpler.\"\nRejected: f64 accumulation across thousands of provider calls drifts\nin the 7th decimal. Auditable billing is not negotiable. i128\nnano-USD is exact and trivially comparable."}]},{"k":"h","depth":3,"text":"Alt B -- UUIDv4 (random only)","id":"alt-b----uuidv4-random-only"},{"k":"p","inline":[{"k":"text","text":"\"Standard, well-supported.\"\nRejected: not time-sortable. Memory queries that want\n\"recent first\" need a separate timestamp; UUIDv7 collapses both into\none column. UUIDv7 is also already an RFC (9562, 2024-05)."}]},{"k":"h","depth":3,"text":"Alt C -- Types stay in `nika-kernel`","id":"alt-c----types-stay-in-nika-kernel"},{"k":"p","inline":[{"k":"text","text":"\"Don't add a new home.\"\nRejected: L1 crates (nika-http, nika-fs) need "},{"k":"code","text":"Cost"},{"k":"text","text":" and "},{"k":"code","text":"TrustLevel"},{"k":"text","text":"\nbut must not depend on L0.5 kernel (per ADR-006 layering and\n"},{"k":"code","text":"scripts/ci/check-layering.sh"},{"k":"text","text":"). L0 "},{"k":"code","text":"nika-error"},{"k":"text","text":" is the only\ncommon ancestor."}]},{"k":"h","depth":3,"text":"Alt D -- Separate `nika-types` or `nika-foundation` crate","id":"alt-d----separate-nika-types-or-nika-foundation-crate"},{"k":"p","inline":[{"k":"text","text":"\"Logically distinct from errors.\"\nRejected: would proliferate L0 crates without functional gain.\n"},{"k":"code","text":"nika-error"},{"k":"text","text":" already has zero deps beyond std + serde + thiserror;\nadding types keeps the dep graph flat. The name is suboptimal but\nnot load-bearing — we may rename later."}]},{"k":"h","depth":3,"text":"Alt E -- Decimal floats (e.g., `decimal_rs::Decimal`)","id":"alt-e----decimal-floats-eg-decimal_rsdecimal"},{"k":"p","inline":[{"k":"text","text":"\"Exact arithmetic without going to integer.\"\nRejected: brings a non-trivial third-party dep into L0 (the strictest\nlayer). i128 gives the same exactness with zero deps."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-005 — error hierarchy. ADR-033 lives in the same crate\n("},{"k":"code","text":"nika-error"},{"k":"text","text":") but adds value types alongside the existing error\ncodes."}],[{"k":"text","text":"ADR-007 — forward-compat invariants. Pattern 2\n("},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":") is applied to every new struct/enum."}],[{"k":"text","text":"ADR-019 — retry + timeout ownership. ADR-019 named\n"},{"k":"code","text":"RetryConfig"},{"k":"text","text":" + "},{"k":"code","text":"ErrorCategory"},{"k":"text","text":" as the shared vocabulary; ADR-033\nis where they actually live."}],[{"k":"text","text":"ADR-034 — L0.5 kernel traits expansion. ADR-034's traits\n(IdGenerator, BillingSink, ...) consume ADR-033's types."}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"Follow-ups (S1-C and beyond):"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Migrate "},{"k":"code","text":"MemoryId(u128)"},{"k":"text","text":" → "},{"k":"code","text":"MemoryId(Uuid)"},{"k":"text","text":" UUIDv7-backed (S1-C)."}],[{"k":"text","text":"Migrate "},{"k":"code","text":"TaskId(String)"},{"k":"text","text":" → "},{"k":"code","text":"TaskId(Uuid)"},{"k":"text","text":" UUIDv7-backed (S1-C)."}],[{"k":"text","text":"Replace "},{"k":"code","text":"InferResponse.cost_usd: Option<f64>"},{"k":"text","text":" with\n"},{"k":"code","text":"cost: Option<Cost>"},{"k":"text","text":" (S1-C)."}],[{"k":"text","text":"Wire "},{"k":"code","text":"TrustLevel"},{"k":"text","text":" into Shield gating when verb-* crates ship."}],[{"k":"text","text":"Consider renaming "},{"k":"code","text":"nika-error"},{"k":"text","text":" → "},{"k":"code","text":"nika-foundation"},{"k":"text","text":" at v0.82+ if\nthe \"errors crate that holds value types\" framing causes friction."}]]}]

ADR-033

L0 foundational types: Cost, UUIDv7, TrustLevel, TokenUsage evolution

accepted · 2026-04-16 · L0 L0.5 · cites 11

ADR-033: L0 foundational types: Cost, UUIDv7, TrustLevel, TokenUsage evolution #

Context #

L0 today contains exactly two crates: nika-error (error codes, NIKA-XXX ranges) and nika-catalog (provider/model catalog data). Neither holds the foundational value types — Cost, IDs, TrustLevel — that L1 effect crates and L2 verb crates will need.

The kernel currently leaks several types that should live one layer below it.

TokenUsage (crates/nika-kernel-ai/src/provider.rs:247-256) has 4 fields:

rust

1#[non_exhaustive]2pub struct TokenUsage {3    pub input_tokens: u64,4    pub output_tokens: u64,5    pub cache_read_tokens: Option<u64>,6    pub cache_write_tokens: Option<u64>,7}

This is missing several axes that real providers already bill for:

reasoning_tokens — Anthropic extended thinking, OpenAI o3.
thinking_tokens — separate from reasoning; visible thinking trace.
cache_creation_tokens — Anthropic prompt caching write side.
image_tokens_in / image_tokens_out — vision input + image output.
audio_tokens_in / audio_tokens_out — Gemini Live, GPT-4o audio.
video_tokens — Gemini 1.5 Pro video.
tool_use_tokens — some providers bill tool definitions separately.

MemoryId (crates/nika-kernel-ai/src/memory.rs:21-22) is MemoryId(u128) with Display as mem-{hex32}. The u128 is opaque random; not time-sortable. Memory queries that want chronological ordering need a separate timestamp.

TaskId (crates/nika-kernel-core/src/types.rs) is TaskId(String) — a bare string wrapper, no validation, no time ordering, no parse guarantee.

Cost is currently cost_usd: Option<f64> on InferResponse (crates/nika-kernel-ai/src/provider.rs:307). Floating-point accumulation across thousands of API calls drifts; we cannot ship billing on f64.

TrustLevel is referenced by Shield error codes (NIKA-380..389: nika-error/src/codes.rs) but currently passed as hardcoded strings in workflow engine code. No enum exists in any admitted crate.

L1 effect crates and L2 verb crates need a shared vocabulary for these values. Putting them in nika-kernel (L0.5) creates an upward dependency from L0 catalog → L0.5 kernel just to share an IdGenerator target type. Putting them in L0 nika-error is the only stratum that all higher layers already depend on.

Decision #

Add 23 foundational value types to `nika-error` (L0). All higher layers re-export or import directly. `nika-error` keeps its dependency budget: std + serde + thiserror + miette only.

The 23 types group into 9 modules:

Module · Types · Why
`cost` · `Cost(i128)` · nano-USD; arithmetic; Display `$X.XXXXXX`; no float drift
`id` · 9 newtyped UUIDv7 IDs: `RunId`, `EventId`, `TraceId`, `SpanId`, `CorrelationId`, `WorkflowId`, `TenantId`, `ProviderId`, `ModelId` · type-safe ID separation; chronological ordering
`trust` · `TrustLevel(u8)` lattice + `meet` / `join` / `is_at_least` · Shield gating becomes a compile-time invariant
`retry` · `RetryConfig`, `ErrorCategory` · shared vocabulary for ADR-019's stratified retry
`budget` · `BudgetDirective` enum · per-task budget enforcement (cost, tokens, time)
`schema` · `EventSchemaVersion`, `TraceFormatVersion` · wire-compat versioning for events + traces
`hash` · `Blake3Hash`, `ContentDigest`, `BlobRef` · content-addressed storage primitive
`baggage` · W3C Baggage (max 64 entries, 8 KB cap) · OTel propagation across spans
`resource` · OTel `Resource { service_name, attrs }` · OTel resource attributes, span enrichment

Migration of existing kernel types (lands in S1-C):

MemoryId(u128) → MemoryId(Uuid) UUIDv7-backed. Display becomes mem-{uuid}. Existing serde format moves to UUIDv7 string. Pre-S1-C callers will need to be re-codegened (mock IDs in tests included).
TaskId(String) → TaskId(Uuid) UUIDv7-backed. Validation on parse.
InferResponse.cost_usd: Option<f64> → cost: Option<Cost>.
TokenUsage 4-field → 18-field expansion (reasoning, thinking, cache_creation, image*, audio*, video, tool_use, ...). All new fields Option<u64> so producers opt in. #[non_exhaustive] makes the expansion non-breaking.

Cost arithmetic (concrete shape):

rust

1#[non_exhaustive]2pub struct Cost(i128); // nano-USD: 1 USD = 1_000_000_00034impl Cost {5    pub const ZERO: Cost;6    pub fn from_usd(usd: f64) -> Cost; // saturating7    pub fn from_nano_usd(n: i128) -> Cost;8    pub fn as_nano_usd(&self) -> i128;9    pub fn as_usd(&self) -> f64; // lossy display10}1112impl Add for Cost { ... }13impl Sub for Cost { ... }14impl Mul<u64> for Cost { ... }15impl Display for Cost { /* "$X.XXXXXX" */ }

i128 gives a range of ±1.7e29 nano-USD = ±170 quintillion USD. Enough for any conceivable aggregation horizon.

TrustLevel lattice (concrete shape):

rust

1#[non_exhaustive]2pub struct TrustLevel(u8); // Untrusted=0, LocalTrusted=128, Trusted=25534impl TrustLevel {5    pub const UNTRUSTED: Self;6    pub const LOCAL_TRUSTED: Self;7    pub const TRUSTED: Self;8    pub fn meet(self, other: Self) -> Self; // min9    pub fn join(self, other: Self) -> Self; // max10    pub fn is_at_least(self, threshold: Self) -> bool;11}1213impl Display for TrustLevel { ... }14impl FromStr for TrustLevel { ... }15impl Serialize / Deserialize for TrustLevel { ... }

Lattice ops let Shield gate "this tool requires Trusted data" with a compile-time-checkable contract.

UUIDv7 is chosen over UUIDv4 because:

Time-sortable: natural chronological ordering for memory queries, event logs, task lookup.
Random suffix preserves uniqueness at high creation rates.
Wire-compatible with uuid::Uuid ecosystem.

nika-error adds uuid = { version = "1", features = ["v7", "serde"] } to its dep list (S1-C lands the dep).

Consequences #

Positive #

Single L0 vocabulary across all higher layers — no more "what's a TrustLevel" ambiguity.
Cost arithmetic moves from f64 (drift) to i128 (exact) — billing becomes auditable.
UUIDv7 IDs give natural chronological ordering for memory queries and event logs without a parallel timestamp field.
TokenUsage expansion (4 → 18 fields) covers every billable axis current providers expose. New axes land additively under #[non_exhaustive].
TrustLevel becomes a typed value with lattice ops; Shield can express "tool X requires at_least(LocalTrusted)" as code, not docs.
RetryConfig + ErrorCategory give ADR-019's three retry layers a shared vocabulary.

Negative #

23 new types is a bigger admit than typical for L0. Mitigated by topological ordering in S1-C (hash → schema → id → baggage → trust → retry → budget → cost → resource).
Migrating MemoryId and TaskId to UUIDv7 changes their wire format (existing snapshots in tests must be refreshed). Pre-emption: no production data exists yet (Diamond is orphan-branch, no users).
nika-error gains a uuid dependency. Acceptable — uuid is std-only with serde + v7 features; no transitive runtime.
TokenUsage 18-field struct is wider; serialization size grows. Mitigated: all new fields are Option<u64> and producers omit them by default.

Neutral #

nika-error already crosses 184 tests (largest crate by test count); adding ~70-90 more keeps it under reasonable test budget.
Some types (RetryConfig, BudgetDirective) live in nika-error even though "error" is not literally what they describe. This is consistent with nika-error being the de-facto "L0 foundation" crate. We may rename it to nika-foundation at v0.82+ if friction appears.

Evidence / Affected code #

crates/nika-kernel-ai/src/provider.rs:247-256 — current 4-field TokenUsage.
crates/nika-kernel-ai/src/provider.rs:307 — current cost_usd: Option<f64>.
crates/nika-kernel-ai/src/memory.rs:21-22 — current MemoryId(u128).
crates/nika-kernel-core/src/types.rs — current TaskId(String).
crates/nika-error/src/codes.rs — Shield NIKA-380..389 (TrustLevel consumers).
docs/architecture/forward-compat-invariants.md — Pattern 2 (#[non_exhaustive]), INV-019 (per-crate new() ctor), INV-025 (verb error enums #[non_exhaustive]).
ADR-019 — names RetryConfig + ErrorCategory as the shared retry vocabulary that lands here.
ADR-034 — L0.5 traits expansion that depends on these L0 types (IdGenerator returns Uuid, BillingSink takes Cost).

Alternatives considered #

Alt A -- Keep `cost_usd` as `f64` #

"Floats are simpler." Rejected: f64 accumulation across thousands of provider calls drifts in the 7th decimal. Auditable billing is not negotiable. i128 nano-USD is exact and trivially comparable.

Alt B -- UUIDv4 (random only) #

"Standard, well-supported." Rejected: not time-sortable. Memory queries that want "recent first" need a separate timestamp; UUIDv7 collapses both into one column. UUIDv7 is also already an RFC (9562, 2024-05).

Alt C -- Types stay in `nika-kernel` #

"Don't add a new home." Rejected: L1 crates (nika-http, nika-fs) need Cost and TrustLevel but must not depend on L0.5 kernel (per ADR-006 layering and scripts/ci/check-layering.sh). L0 nika-error is the only common ancestor.

Alt D -- Separate `nika-types` or `nika-foundation` crate #

"Logically distinct from errors." Rejected: would proliferate L0 crates without functional gain. nika-error already has zero deps beyond std + serde + thiserror; adding types keeps the dep graph flat. The name is suboptimal but not load-bearing — we may rename later.

Alt E -- Decimal floats (e.g., `decimal_rs::Decimal`) #

"Exact arithmetic without going to integer." Rejected: brings a non-trivial third-party dep into L0 (the strictest layer). i128 gives the same exactness with zero deps.

ADR-005 — error hierarchy. ADR-033 lives in the same crate (nika-error) but adds value types alongside the existing error codes.
ADR-007 — forward-compat invariants. Pattern 2 (#[non_exhaustive]) is applied to every new struct/enum.
ADR-019 — retry + timeout ownership. ADR-019 named RetryConfig + ErrorCategory as the shared vocabulary; ADR-033 is where they actually live.
ADR-034 — L0.5 kernel traits expansion. ADR-034's traits (IdGenerator, BillingSink, ...) consume ADR-033's types.

Notes #

Follow-ups (S1-C and beyond):

Migrate MemoryId(u128) → MemoryId(Uuid) UUIDv7-backed (S1-C).
Migrate TaskId(String) → TaskId(Uuid) UUIDv7-backed (S1-C).
Replace InferResponse.cost_usd: Option<f64> with cost: Option<Cost> (S1-C).
Wire TrustLevel into Shield gating when verb-* crates ship.
Consider renaming nika-error → nika-foundation at v0.82+ if the "errors crate that holds value types" framing causes friction.

read at v0.107.0 · the decision record ships with the engine

Every decision, with its status This one in the repo

L0 foundational types: Cost, UUIDv7, TrustLevel, TokenUsage evolution

ADR-033: L0 foundational types: Cost, UUIDv7, TrustLevel, TokenUsage evolution #

Context #

Decision #

Consequences #

Positive #

Negative #

Neutral #

Evidence / Affected code #

Alternatives considered #

Alt A -- Keep `cost_usd` as `f64` #

Alt B -- UUIDv4 (random only) #

Alt C -- Types stay in `nika-kernel` #

Alt D -- Separate `nika-types` or `nika-foundation` crate #

Alt E -- Decimal floats (e.g., `decimal_rs::Decimal`) #

Related #

Notes #