# =============================================================================
# trace-event.yaml — the trace bus event envelope (spec 25 §3, phase T1)
#
# One structured event per interception decision, one JSONL line per event,
# appended to the channel named by TEBAKO_TRACE / --tebako-trace. This file
# owns the wire grammar: the envelope fields, the op vocabulary, and the
# per-op verdict/detail keys.
#
# SSOT: this file owns the grammar; crates/tfs/src/trace.rs (the emitter),
# crates/tebako-driver/src/driver.rs (the resolve emitter), and
# crates/tebako-cli/src/trace/ (the `tebako trace run|cover|explain`
# consumers) mirror it — keep the four in sync in the same PR. The
# property test in crates/tfs/src/trace.rs drives the op matrix against a
# mounted fixture and validates every emitted event against this grammar.
# =============================================================================
schema: trace-event
schema_version: 1 # MAJOR — the envelope's `v` field; additive-only, NEVER bumps
schema_minor: 0 # MINOR — additive counter (unused while v1 grows by ops/keys)
status: normative
owner: crates/tfs (tfs::trace, the bus) in tamatebako/tebako
edge: T1 (driver/context → trace channel), T1' (channel → tebako trace run generator), T2 (preload posix_spawn surface → spawn; driver resolve_image → resolve)
# The schema evolution law (spec 18 §3), specialized for an append-only
# event stream: events are never re-read by their emitter, so evolution
# serves DOWNSTREAM readers (trace explain/cover, external tooling).
evolution:
major_minor: >-
The envelope's `v` is 1 forever. Extensions ride NEW ops and NEW detail
keys — never retyped fields, never renamed keys, never a version bump
(spec 25 §3: a consumer that understands v1 today understands every
future v1 event; one it doesn't recognize costs it exactly that event's
detail).
unknown_fields: >-
Readers ignore unknown detail keys and unknown ops within v1. A writer
never invents semantics a reader must know to parse the envelope.
unknown_major: >-
Not reachable: `v` never bumps. A consumer meeting v != 1 is reading a
non-tebako file and names that, never guesses.
type_changes: >-
Forbidden within v1. New shapes arrive as new keys.
lists_stay_lists: >-
Ordered/multiplicity data (the closure walk's deps) is a list of
entries carrying their identity fields — never keyed maps.
channel:
named_by: TEBAKO_TRACE (env) or --tebako-trace <path> (driver argument wins)
opened: >-
At driver boot, BEFORE any mount (a path op is only safe that early —
the journal fd discipline, crates/tfs/src/journal.rs). Append-only,
never policy-gated.
children: >-
Re-derived at each child's own driver boot on both platforms —
TEBAKO_TRACE inherits across spawn/exec and the child re-opens for
append. (Spec 25 §2's POSIX fd-inheritance spelling is not the
mechanism: the bus forbids unsafe, and env re-derivation is uniform.)
failure: >-
Observability never gates: an unopenable channel is one loud stderr
note and a disarmed bus; the run proceeds. A dropped write drops the
event, never the run.
disarmed_cost: >-
One relaxed atomic load per interception point (tfs::trace::Start::now
returns None; no event is built).
grammar:
envelope:
type: map
required: true
serialization: one JSON object per line (JSONL), keys in the listed order
fields:
v: {type: int, required: true, notes: "== 1; the envelope version"}
ts: {type: string, required: true, notes: "RFC 3339 UTC, microsecond precision: 2026-08-19T13:49:20.344123Z"}
pid: {type: int, required: true, notes: "the emitting OS process id (re-read per event — a forked child reports its own)"}
tid:
type: int
required: true
notes: >-
The bus's PER-PROCESS thread ordinal (1 for the first thread to
emit, then sequential) — deliberately not an OS thread id: the
bus is pure safe Rust and stable Rust exposes no OS tid. Grouping
by (pid, tid) regroups events by thread identically.
op: {type: string, required: true, notes: "one of the op vocabulary below"}
path:
type: string
required: true
notes: >-
The decision's subject: the normalized VFS path (open/stat/
dlopen/exec/materialize), the mount point (mount), the bare
library name (dlopen's alias surface), the host path (jail).
Empty for the whole-table mount clear.
verdict: {type: string, required: true, notes: "<word> or <word>:<payload>, per op below"}
detail: {type: map, required: true, notes: "per-op keys below; empty when none"}
dur_us: {type: int, required: true, notes: "the decision's wall time, microseconds"}
errno:
type: int
required: false
notes: >-
Present when the verdict carries an errno (error:<errno>,
denied:<rule>, deny:<rule>). The typed duplicate of the verdict
suffix, for filtering.
ops:
mount:
emitter: crates/tfs/src/context.rs (mount table decisions)
verdicts: [ok, "error:<errno>"]
detail_keys:
action: "init | insert | union | remove | clear"
handle: "int — the mount handle, on a successful init/insert/union/remove"
image: "string — the host image path, when file-backed"
count: "int — mounts cleared, on action: clear only"
open:
emitter: crates/tfs/src/context.rs (open; the fopen routing via dlmap2file_for_open)
verdicts: ["image:<mount>", "host", "denied:<rule>", "error:<errno>"]
detail_keys:
need: "read | write — on passthrough/denial decisions"
dlmap_redirect: "the memfs original, when the dlmap-prefix redirect served"
materialized: >-
The host path of the materialized copy a raw host fd answered
from (dlmap-prefix redirect; the preload's fopen routing) — the
spec 25 §4 materialize-candidate signal.
effective: "the memfs path, when the presented spelling was a dlmap-prefix path"
reason: "no-mounts — the degenerate passthrough with an empty mount table; dlmap-tree — a dlmap-marker path the image did not answer: the runtime's own materialization tree, passed through ungated (spec 08 §3, tebako#502)"
closure: "the closure-walk record (see dlopen), on the fopen surface"
notes: >-
denied:<rule> carries the policy source label, or `write-gate`
for the spec 24 §5 held-tree EROFS.
stat:
emitter: crates/tfs/src/context.rs (stat/fstat)
verdicts: ["image:<mount>", "host", "denied:<rule>", "error:<errno>"]
detail_keys:
dlmap_redirect: "as open's"
reason: "as open's"
dlopen:
emitter: crates/tfs/src/context.rs (dlmap2file, dlalias2file)
verdicts: ["materialized:<host-path>", "host", "error:<errno>"]
detail_keys:
closure:
format: "macho | elf | pe, or null when the header parse was unsupported (no dep walk ran)"
deps:
- name: "the dependency name as the image declares it"
resolved: "the in-image path it resolved to, or null for a host/system name"
verdict: "materialized | host-system | error:<errno>"
effective: "as open's"
alias: "bool — the windows bare-name surface (dlalias2file)"
notes: >-
The closure key is present on the dlopen surface (dlmap2file);
the alias surface carries `alias` instead. A cache-hit answer
reports an empty walk (format: null, deps: []) — the walk did not
re-run; the paired materialize event carries cache-hit.
exec:
emitter: crates/tfs/src/context.rs (exec_materialize — the execve-surface routing; the preload's execve and the C ABI's tebako_fs_exec_materialize)
verdicts: ["routed:<host-path>", "host", "error:<errno>"]
detail_keys:
route: "home-tree | dlmap-closure"
notes: >-
verdict `host` on the ENOENT fallthrough is the spec 25 §4
entrypoint/runtime-dep note signal (a spawned host-absolute
executable). The interpreter's own spawn hook (spec 22 rule E1)
rides the C ABI's exec surface — splitting it onto the spawn
vocabulary is factory-side follow-up, not a bus change.
spawn:
emitter: crates/tfs/src/context.rs (exec_materialize_for_spawn — the preload's posix_spawn/posix_spawnp routing; phase T2)
verdicts: ["routed:<host-path>", "host", "error:<errno>"]
detail_keys:
route: "home-tree | dlmap-closure"
notes: >-
The exec row's grammar on the child-creating surface (spec 25 §2):
same routing decision, same details — the op token is the
process-tree signal (a spawn means later events may carry a NEW
pid: the child's re-derived channel). A bare-name posix_spawnp
(no '/' in the file argument) is a host PATH search that never
consults the VFS — no routing decision exists, so no event; the
correlator treats it as a KNOWN-UNSERVED passthrough (§6.3).
Emitted at the routing decision, BEFORE the real spawn runs: the
child pid is not the event's to carry (the child's own events
report their own pid).
resolve:
emitter: crates/tebako-driver/src/driver.rs (resolve_image — the --tebako-image <path>:<slot>:<mount> triple → mount-region decision; phase T2)
verdicts: [whole, "slot:<n>", "error:<errno>"]
detail_keys:
slot: "the slot reference as spelled (`0`…`n` or `-`) — on whole and error verdicts (a slot:<n> verdict carries n itself)"
mount: "the triple's mount point (the physical, drive-qualified point on windows)"
offset: "int — the slot region's byte offset in the image file, on slot:<n>"
size: "int — the slot region's byte size, on slot:<n>"
slots: "int — the package's slot count, on slot:<n>"
reason: "open | no-trailer | corrupt-trailer | whole-on-package | slot-out-of-range | runtime-slot | self-not-packaged — the failure class, on error:<errno>"
notes: >-
One event per --tebako-image triple, BEFORE the mount it feeds:
path is the host file actually probed (a `<self>` triple names
the running executable), the verdict is the resolution class, and
the slot:<n> details are the payload/slot identity the §6
correlator matches the outside capture's byte-range reads
against. The env image (TEBAKO_RUNTIME_IMAGE) emits NO resolve
event — it is bare by construction (no slot decision); its mount
event covers it. Failures carry the closest errno-level fact
(the open's raw errno; EINVAL for the grammar refusals; ERANGE
for slot-out-of-range) with the named class in `reason`; the
boot's named-error path (exit codes 65/69) is unchanged.
PLANNED: the L3 runtime/payload cache resolution (tebako-resolve
— loader-side, outside the runtime process) adds verdicts
`cache` / `fetched` / `error` when its channel story lands.
materialize:
emitter: crates/tfs/src/context.rs (extract_for_exec — dlopen/exec extractions and tebako install's store-side pass)
verdicts: ["ok:<host-path>", "cache-hit", "error:<errno>"]
detail_keys:
dest: "dlcache | store"
bytes: "int — bytes written, on ok"
host: "the cached host path, on cache-hit"
notes: >-
The ENOENT host-passthrough answers emit nothing here (no
materialization was decided); the caller's dlopen/exec event
carries the `host` verdict.
jail:
emitter: crates/tfs/src/context.rs (host_check — spec 23 §8's journal, formalized)
verdicts: ["allow:<rule>", "deny:<rule>", "record"]
detail_keys:
access: "read | write"
notes: >-
<rule> is the policy's source label (manifest / user /
manifest+user / TEBAKO_JAIL / …). `record` is the record-policy
allow (the observation trail `tebako trace run` turns into a
needs: draft); plain allows emit only when the policy can deny
(never under the open default — the op events carry those
passthroughs). A policy-gated decision yields BOTH its op event
and the jail event: two layers of one decision, by design.
notes: >-
Phase T1 emits mount/open/stat/dlopen/exec/materialize/jail from the
tfs context; phase T2 adds spawn (the same context routing, the
preload's posix_spawn surface) and resolve (the driver's image-triple
resolution). The driver's class-R boot materialization
(crates/tebako-driver/src/materialize.rs — declared-manifest
resources, merkle-verified) is deliberately NOT instrumented: it
is boot work outside the interception surface, and its failures already
abort the boot loudly. The TEBAKO_DEBUG_TFS eprintln gates remain as
the human-readable degraded view over the same emission points.
REFERENCE · 22
The trace bus event envelope.
With tracing enabled, the runtime emits one structured event per interception decision, one JSON line per event, on the channel the operator names. This page is the grammar of the event envelope and its operation vocabulary.
What it defines.
One structured event per interception decision, one JSONL line per event, appended to the channel named by TEBAKO_TRACE / --tebako-trace. This file owns the wire grammar: the envelope fields, the op vocabulary, and the per-op verdict/detail keys.
Identity.
| Field | Value |
|---|---|
schema |
trace-event |
schema_version |
1 |
schema_minor |
0 |
status |
normative |
owner |
crates/tfs (tfs::trace, the bus) in tamatebako/tebako |
Sections.
| Section | What it declares |
|---|---|
|
How the trace channel is named, opened, and inherited by spawned children. |
|
Map, required — fields v, ts, pid, tid, op, path, verdict, detail, and 2 more. |
|
Map — keys mount, open, stat, dlopen, exec, spawn, resolve, materialize, and 1 more. |
The full grammar.
The source of truth is
docs/spec/schemas/trace-event.yaml
in the product repository; this page is regenerated from it by
tools/sync-schemas.rb.
See also: Trace a packaged app · Observability