CADR-WEB-303 ABI 1.1 deterministic tracing and snapshot reimplementation specification

Mutable-state inventory and derived omissions

The last omission is intentional: snapshotting captures the machine continuation, not an in-flight observation subscription. Restoring yields no active CDRGTRC1 engine. Starting a new trace after restore binds a new initial CDRSTATE2 state.

Start, identity, and transport

cadr_machine_trace_start accepts ABI1.1 cadr_trace_config: first boundary, selector and event masks, full-ring capacity, transport, and SHA-256 identities for the selected profile, artifact set, and input schedule. The core computes the initial CDRSTATE2; all identities and selections become immutable until finish/destroy. Starting while a request is outstanding, a completion is queued, a trace is already active, or state/cache validation fails is rejected.

The 256-byte little-endian header starts CDRGTRC1, has format version 1 and a CRC-32C over bytes 0--251. It carries first_boundary, final record count (all ones while unfinished), masks, profile/artifact/initial-state/input digests, and the semantic seed. It has no host pathname, wall-clock timestamp, pointer, or browser identifier.

FULL retains bounded complete raw records. Its capacity MUST be at least one boundary plus one reservation for every selected slot-event class: 1 + popcount(event-mask & known-slot-event-mask), hence one through six for the current five-class mask. Start rejects a smaller full ring before emitting its INITIAL record or changing machine state. INITIAL itself occupies one retained record, so a caller using the exact minimum drains it before the first compound-slot preflight and then retries unchanged. HASH_ONLY retains no ring and therefore cannot stall because the host has not drained output; its capacity does not create this minimum-admission rule. Both execute the same semantic chain, use the same header identity, record the same count, and MUST return the same semantic digest for the same input sequence. Draining a full ring consumes only complete records and cannot change that digest.

Selectors, events, and records

All record integers and TLV headers are little-endian; record envelopes contain total length, kind, flags, ordinal, boundary, microinstruction count, payload length, and CRC-32C. Records are eight-byte aligned. Each nonterminal record carries state, previous-chain, and semantic-chain SHA-256 TLVs; event records also carry event code, bytes, and their digest. The terminal carries final count, reason, and final state.

Selectors are a projection, not state elision: every emitted boundary is chained to the full CDRSTATE2. On an inhibited slot, decoded-word, A-source, M-source, and destination selections are suppressed because their latches are not valid. The valid mask makes that absence explicit; an implementation MUST NOT report stale values.

The event mask has five one-bit classes: clock, interrupt, device, fault, and halt. Clock carries before/after guest tick and a decision; interrupt carries before/after u16 status, derived level and pending; fault carries before/after/code/valid; halt carries CADR_STATUS_HALTED; device records request issue, completion, or an ordered list of at most 64 in-slot transactions. Device traces bind payload SHA-256 and length, rather than retaining host-owned input buffers.

ABI1.3 adds device code 6 without changing codes 1--5. It records a payload-bearing request issue as operation, status, generation, request ID, descriptor length and SHA-256, expected completion length, and request-payload length and SHA-256. A BLOCK_WRITE request MUST be copied and validated before publication, then recorded with code 6 in the same preflighted transaction. Consequently enabling tracing cannot turn an otherwise valid block write into a disk fault, and its issue witness cannot omit or alias the write payload. Code 1 remains the byte-stable payload-free issue record.

Compound slot ordering and backpressure

For every outer clock slot the producer MUST establish this order:

1. Trace start first rejects a FULL capacity below the complete worst-case slot reservation. Preflight then reserves one boundary plus one slot for every selected event class, leaving room for exactly one terminal record. A NOT_READY preflight makes no guest-visible mutation; a full-mode caller may drain and retry.
2. Before the boundary, device modules may stage valid normalized transactions. More than 64, staging after the boundary, or invalid transaction domains is a guest fault; it is not silently truncated.
3. Execute the normal core transition. Record exactly one boundary, marked executed or inhibited (and optionally halt/checkpoint), after the transition.
4. Close the slot in this fixed order: clock, interrupt, device list, fault, halt. A selected class with no event releases its reservation without a record. Each slot event is single-use. Device code 5 is that in-slot aggregate; codes 1--4 instead record host request/completion lifecycle after close. Once any code 1--4 has been recorded for a boundary, no later slot event may attach to it, although later lifecycle records retain their source order until the next boundary.
5. Clear reservations/staged transactions and only then open another slot or finish.

slot_abort is permitted only before a boundary and with no staged transaction; it releases reservations without guest mutation. Finish fails while a compound slot is open, a reservation exists, or the full raw ring cannot hold the terminal. A halt slot has no simultaneous selected clock, interrupt, device, or fault event; a COMPLETE_HALT terminal requires a halt boundary, and COMPLETE_LIMIT requires that the final boundary not be halt.

Termination and failures

Reasons are COMPLETE_LIMIT, COMPLETE_HALT, ABORT, and FAILURE. Terminal finalization neither advances guest state nor advances the semantic chain; it binds the current chain/state and makes the final count visible in the header. Its cycle MUST exactly equal the immediately preceding nonterminal record's cycle. Starting, preflighting, record construction, and finish reject invalid masks, invalid transport capacity, malformed latches, bad ordering, record-limit exhaustion, and post-finish reuse with a typed status. Once terminal is emitted, later slot preflight returns NOT_READY before any reservation or guest-state mutation; FULL drains terminal as its last retained record, while HASH_ONLY preserves the same count and semantic digest. This rejection precedes event-mask selection, so later host request and otherwise valid completion ingress cannot mutate a sealed trace even when DEVICE is unselected. A post-preflight emission failure is surfaced as guest fault, not retried as a different event ordering.

Wire representation and versioning

CDRSNAP1 is an internal state-transfer representation, not a host ABI record. It starts with the eight ASCII bytes CDRSNAP1, format major 1/minor 0, a 264-byte header, a directory of 64-byte entries, payload chunks, and a 32-byte whole-body SHA-256 trailer. The header binds CADR-WEB-303 profile and artifact-set SHA-256, CDRSTATE1, CDRSTATE2, lifecycle, artifact mask, storage binding/generation, and slot/instruction counters. Numeric fields are little-endian.

The required chunks, in type order, are CORE (1), CPU (2), MEMORY (3), BUS (4), DEVICES (5), CANONICAL (6), EVENTS (7), and TRACE (8). Every directory entry includes type, required flag, nonoverlapping payload offset/length, and a per-chunk SHA-256. Unknown optional chunks MAY be skipped; unknown required chunks, duplicate known chunks, missing known chunks, unrecognized header flags, unsupported format version, nonzero reserved fields, bad offsets/lengths, bad hashes, or trailing bytes are rejected. A future incompatible encoding MUST raise the major version; minor extension uses directory entries and required flags, never reinterpretation of v1 bytes.

cadr_machine_snapshot_size gives the exact required size. snapshot_save writes exactly that many bytes or returns zero out_written and no partial success. It first ensures CDRSTATE2 cache validity/rebuild and computes both digests; request records must be ABI1.1 with zero flags/reserved fields.

Fresh atomic restore

cadr_machine_snapshot_restore parses into a zeroed, newly allocated machine state. It validates the representation and internal state, records a semantic fingerprint, rebuilds only the CDRSTATE1 and CDRSTATE2 derived cache families, re-fingerprints, verifies both snapshot digests/profile/artifact binding, and confirms cache parity. Only then does it allocate/publish a new opaque machine. The destination is therefore either a usable fresh instance or no instance; failed input cannot partially mutate a pre-existing machine.

Queued completions are continuation state. A restore with an outstanding request preserves descriptor identity and exact expected length. A queued zero-byte completion restores with a null byte pointer; a nonzero queued completion receives a fresh copy. The next run applies it at the same core boundary. A snapshot does not invent a host completion, replay host ownership, or preserve an active trace ring.