Trace and observability.

The bus lives in the Rust tfs crate, the shipping VFS implementation on every platform. Every interception point that the driver and TFS already implement emits one structured event per decision. The bus is armed by TEBAKO_TRACE=<host-path> or by the driver’s --tebako-trace argument (the argument wins, and it travels the env-scrubbed handoff). The channel opens at driver boot, before any mount; writes are append-only, process-internal, and never policy-gated. When disarmed, an emission point is one Option::is_none() branch, and the bus compiles into the runtime/driver side only, so the bootstrap’s size gate is untouched. Spawned children inherit the armed channel (fd inheritance on POSIX; re-open-for-append on windows), and every event carries pid/tid so front-ends can regroup.

The stream is JSONL, one JSON object per line, streamable, diffable, and robust to a crashed tail, under the versioned schema trace-event.yaml (envelope v1: additive only, never bumped; ts/pid/tid/op/path/verdict/detail/dur_us/errno). CI property-tests the whole op matrix against the schema. TEBAKO_DEBUG_TFS remains as the human-readable degraded view over the same emission points.

The command runs a composition under policy: record with the bus armed, then synthesizes a suggested manifest, a commented YAML fragment that is never applied. Host reads become ro grants, and host writes become rw grants (strongest-observed-op wins). A VFS-resident file read through a raw host fd (a native library’s own fopen, where the exec-cache answer consumed it) becomes a materialize: candidate, caught automatically instead of discovered by a failing import; an in-image dlopen whose deps all resolve in-image earns a NOTE "closure-covered — nothing to declare"; and a spawned host-absolute executable becomes an entrypoint/runtime-dep note. Floor, store, and exec-cache paths are excluded, because the automatic surface is never declared. Each entry carries its evidence line, and the author reviews, flips ro↔rw, deletes noise, and fills why.

The command replays a capture into the hop chain (mount → manifest read → resolve → materialize → OS bind) and prints the first hop whose verdict is red, with a signature table seeded from the incident corpus. The table lives in data and is extended as incidents teach new signatures; it is never hard-coded into the bus.

This command is the escapes report. The question of what tebako does not intercept is answerable only by subtracting the inside stream from an outside capture, and only up to the outside capture’s own layer.

Escapes split in two at the libc boundary: libc-routed escapes (the app called open/CreateFileW directly, visible to retrace on both platforms today) and sub-libc escapes (raw syscall / NtCreateFile, and loader-internal probes like macOS’s dyld rpath class, which only a kernel-layer producer sees). A report must name the producing layer of its outside input: a libc-boundary capture certifies libc-routed escapes only, and a raw-syscall fixture paired with one reports UNCERTIFIABLE, not covered. The outside format is the retrace trace document, and tebako never authors a competing one; procmon/ETW join through an offline converter (tebako trace import procmon, pure Rust, in-process).

The correlator is tebako-owned, safe Rust, and self-contained, because the invariants leave no other home (no shell-outs in shipped artifacts, and no C/C++ linkage outside dwarfs-t). The format is retrace’s single source, and the algorithm has two implementations that must agree; the shared golden fixtures produce byte-identical escapes reports from both correlators in CI. Intentionally-unserved surfaces (documented passthroughs like the platform floor) are declared in the composition, so the report separates KNOWN-UNSERVED from ESCAPE. A NAME-NOT-FOUND probe on an unserved under-prefix path is an escape, because existence is information.

See also: Jails and host proxying · Native interposition · The contract model.