# =============================================================================
# layout.yaml — the env-image layout declaration grammar (spec 18 §2.2, C3)
#
# The in-image contract between a runtime exe and its env image (the
# pair): /lib/tebako/layout.yaml inside the env `.tfs`. The DRIVER
# verifies it post-mount, before any interpreter handoff — a mismatch is
# never a ruby LoadError.
#
# SSOT: this file owns the grammar. crates/tebako-driver (the reader,
# src/layout.rs) mirrors it — keep the two in sync in the same PR. The
# runtime factory (the writer) FLOWS it from the same owned values
# (mount_root from tamatebako/ruby's patch literals) and asserts parity
# in its CI (separate release chain — spec 00 §10).
# =============================================================================
schema: layout
schema_version: 1 # MAJOR — breaking changes only
schema_minor: 5 # MINOR — additive changes only (1: mount_root_override; 2: preload_shim; 3: runtime_dll; 4: interpreter + visibility; 5: entry_delivery)
status: normative
owner: tebako-runtime-ruby (writer) + crates/tebako-driver (reader); grammar owned here
edge: C3 (runtime exe ↔ env image)
# The schema evolution law (spec 18 §3) — every schema in this registry
# obeys it; per-schema specializations are noted under `notes:`.
evolution:
major_minor: >-
schema_version is a single integer MAJOR; schema_minor an additive
counter. MAJOR breaks, MINOR adds.
unknown_fields: >-
Readers ignore unknown fields within their MAJOR — but never invent
semantics for them. A field you do not understand changes nothing you do.
unknown_major: >-
A named refusal naming the artifact, its schema + version, the consumer
and its max spoken version, and "upgrade". Exit code per spec 18 §7.
missing_schema_version: >-
Era 1 — a named refusal ("pre-era document; regenerate with a current
tool"), never a silent default.
type_changes: >-
MAJOR only — no silent coercion (string→list, int→string, kebab→snake).
Renames ride the deprecation window.
deprecation_window: >-
To rename/retype a field inside one MAJOR: writers emit BOTH old and
new for two consecutive MINOR versions (noted under `deprecated:` with
the window dates); readers prefer new and warn on old; after two MINORs
the old field is dropped in the next MINOR.
critical_flag: >-
Any container that skips unknown entries supports `critical: true` on
an entry: a reader that does not understand a critical entry refuses
with a named error instead of skipping it (spec 18 §3.7).
lists_stay_lists: >-
Ordered/multiplicity data is a list of entries carrying their identity
fields — never keyed maps.
declaration:
where: /lib/tebako/layout.yaml inside the env image (read through the TFS layer, never the host fs)
format: YAML (authored-manifest rule, invariant 6)
grammar:
schema_version:
type: int
required: true
notes: this schema's MAJOR; missing = era 1 (pre-era document, S17's kin)
era:
type: int
required: true
notes: >-
The contract era of the image. >= 2 once declared; < 2 is the
pre-era refusal. Newer than the driver speaks → upgrade refusal.
image_layout:
type: int
required: true
notes: >-
The image's internal layout generation (where stdlib, gems and the
manifest tree live). The driver speaks <= its own compiled
generation (1); newer → upgrade refusal.
mount_root:
type: string
required: true
notes: >-
The mount root the image was built for — must equal the exe's
compiled-in value (the one tebako_main forwards to the driver;
ruby: /__tfs__ on POSIX, A:/t on windows — a per-platform baked
default, short on windows by owner decision for MAX_PATH
headroom). Mismatch → exit 78, both values printed (S19). The
value FLOWS from tamatebako/ruby's patch literals (the single
owner); nothing re-authors it.
mount_root_override:
type: bool
required: false
since: schema_minor 1
notes: >-
The image's grant that its interpreter follows TEBAKO_MOUNT_ROOT
at run time (ruby: rbconfig emits ENV["TEBAKO_MOUNT_ROOT"] || the
baked root). Absent ⇒ false ⇒ the driver refuses a root override
by name (exit 78) rather than booting an interpreter whose load
paths would point at an unmounted root. The driver validates the
override's form before any mount (malformed → exit 65 naming the
variable).
preload_shim:
type: string
required: false
since: schema_minor 2
notes: >-
The preload shim's in-image path, RELATIVE to the mount root
(e.g. lib/tebako/libtfs_preload.so). The image declares, the
driver flows it: materialized to the exec cache for the
child-injection env (LD_PRELOAD / DYLD_INSERT_LIBRARIES) and
exported as TEBAKO_PRELOAD_SHIM for the interpreter's spawn hook
(spec 22 §3 Rules E2/E3). SSOT: the factory stages the file and
emits this key in the same deploy pass — declared-but-absent is a
named boot error (exit 78: the declaration lies). Absent ⇒ no
preload env (an older image — spawned children get no VFS, the
honest degradation it always was).
runtime_dll:
type: string
required: false
since: schema_minor 3
notes: >-
The runtime's own PE module basename (e.g. x64-ucrt-ruby340.dll)
— MSYS builds only; POSIX builds omit the key. Bare-name grammar
(no '/', '\', ':' — the spec 03 §2.5 byte rule); a violation is
a named exit 78 (the declaration lies). The image declares, the
driver flows it: exported verbatim as TEBAKO_RUNTIME_DLL into the
handoff env at boot, on every platform (spec 17 §2 — POSIX legs
never read it). The reader is the tfs PE closure walk (spec 22
§2.1): a bare import name matching it case-insensitively is never
materialized out of a payload image — the OS's basename-reuse
rule binds the already-loaded copy, and the exe-dir layout copy
stays the only one on disk. SSOT: the factory knows the name at
build time (the built tree's bin/<name> is THE file the build
produced) and flows it; nothing downstream recomputes it. Absent
⇒ no export (an older image — the exclusion is simply off).
interpreter:
type: string
required: false
since: schema_minor 4
notes: >-
The interpreter's in-image path (POSIX-absolute on every platform,
e.g. /bin/java) — the spec-29 wrapper-exe pattern: a runtime whose
exe artifact is the tebako-owned wrapper (repacked upstream bytes
the driver cannot be linked into) declares the real interpreter
here; the wrapper resolves it against the env image's mount,
drive-qualified onto the runtime root per spec 17 §1. Absent ⇒ the
linked pattern (the driver is compiled into the interpreter exe;
era-2 ruby images) — the key is wrapper-consumed, so the linked
driver parses but never gates on it. The WRAPPER fails closed:
absent under the wrapper pattern, a malformed value (not
POSIX-absolute, '..' components), or a path that does not resolve
inside the env mount is a named boot error — exit 65 naming the
key / the path and the mount (spec 29 §2/§4). SSOT: the runtime's
factory authors the path once (the image's own manifest owns it —
the wrapper crate carries no per-runtime knowledge, spec 29 §7).
entry_delivery:
type: string
required: false
since: schema_minor 5
enum: [read, exec]
notes: >-
How the child reaches its ENTRY under a mechanism that can serve
virtual paths (spec 29 §3). 'read' keeps the entry's VFS spelling:
the interpreter opens it through the shim, so every relative
include the program performs resolves INSIDE the image. 'exec'
materializes a host twin instead, which is what a runtime whose
file-runner SPAWN-EXECS its entry needs, because the spawned
shebang would otherwise resolve through the kernel's PATH
(tebako#831). The distinction is the RUNTIME's property and never
the file's: every entry in an image is 0644 data, so nothing about
the file can decide it — which is why the image declares it and
the wrapper honours it. Absent ⇒ 'read', because a twin is the
exception a runtime must ask for. Honoured under 'preload' only;
an 'exec-cache' image materializes regardless, having no
interposition able to read a virtual path. A value outside the
enum is a named exit 78.
visibility:
type: string
required: false
since: schema_minor 4
notes: >-
The kernel-visibility mechanism the wrapper honors for the
interpreter and its children (spec 29 §3 — spec 07 §8's locked
tiers applied to the runtime's own interpreter, interposition-
first, never FUSE): 'preload' (tier 1 — the POSIX default for
dynamic interpreters; requires the preload_shim grant, schema_minor
2), 'seccomp-notify' (tier 2a — linux statics), 'exec-cache' (tier
2b — the windows default, universal fallback; the interpreter home
tree materializes into the spec 22 §6 exec cache). Absent ⇒ the
locked default order (tier 1 on POSIX, tier 2b on windows and for
statics without tier 2a), journaled at boot. Wrapper-consumed like
`interpreter`; an unknown value, or a declared mechanism unusable
on the host, is the wrapper's named boot error — exit 65 naming
the mechanism and the fact (spec 29 §3/§4); the factory validates
the declaration against the runtime's platform list at press.
interpreter_api_version:
type: string
required: true
notes: >-
The interpreter API version line the image carries (ruby: the
"3.4"-style line). Declared for the factory and future consumers;
the era-2 driver parses but does not gate on it.
refusals:
- case: entry_delivery declared outside read|exec
behavior: "named refusal \u2014 exit 78 naming the image and the value (spec 29 §3.1)"
- case: /lib/tebako/layout.yaml absent (S17)
behavior: era-1 refusal naming the image — exit 78
- case: schema_version / era / image_layout newer than the driver speaks (S18)
behavior: upgrade refusal naming both versions — exit 78
- case: era < 2 or the declaration malformed
behavior: named refusal — exit 78
- case: mount_root != the exe's compiled-in root (S19)
behavior: exit 78 with both values printed — a mismatched pair, never a ruby LoadError
- case: TEBAKO_MOUNT_ROOT set but mount_root_override absent/false
behavior: exit 78 naming the override and the image — the image's rbconfig cannot follow, never a broken boot
- case: preload_shim declared but the file absent from the image
behavior: exit 78 — the declaration lies; rebuild the runtime with the current factory
- case: runtime_dll declared with a path separator or drive qualifier
behavior: exit 78 — a basename owns no path; the declaration lies
- case: interpreter absent under the wrapper pattern, malformed, or not resolving inside the env mount (spec 29 §2)
behavior: exit 65 naming the key / the path and the mount — the wrapper's boot error, never a silent linked-pattern guess
- case: visibility unknown, or declared but unusable on the host (spec 29 §3)
behavior: exit 65 naming the mechanism and the fact — fail closed, never a silent fallback
deprecated: [] # no field is in a deprecation window
REFERENCE · 15
The env-image layout declaration grammar.
A runtime's environment image declares its layout in a small YAML document, and the runtime driver verifies the declaration after mounting the image and before any interpreter handoff, so that a layout mismatch is a named error rather than a load failure. This page is the grammar of that declaration.
What it defines.
The in-image contract between a runtime exe and its env image (the pair): /lib/tebako/layout.yaml inside the env .tfs. The DRIVER verifies it post-mount, before any interpreter handoff — a mismatch is never a ruby LoadError.
Identity.
| Field | Value |
|---|---|
schema |
layout |
schema_version |
1 |
schema_minor |
5 |
status |
normative |
owner |
tebako-runtime-ruby (writer) + crates/tebako-driver (reader); grammar owned here |
Sections.
| Section | What it declares |
|---|---|
|
This schema’s MAJOR; missing = era 1 (pre-era document, S17’s kin). |
|
The contract era of the image. >= 2 once declared; < 2 is the pre-era refusal. Newer than the driver speaks → upgrade refusal. |
|
The image’s internal layout generation (where stdlib, gems and the manifest tree live). The driver speaks ⇐ its own compiled generation (1); newer → upgrade refusal. |
|
The mount root the image was built for — must equal the exe’s compiled-in value (the one tebako_main forwards to the driver; ruby: /__tfs__ on POSIX, A:/t on windows — a per-platform baked default, short on windows by owner decision for MAX_PATH headroom). |
|
The image’s grant that its interpreter follows TEBAKO_MOUNT_ROOT at run time (ruby: rbconfig emits ENV["TEBAKO_MOUNT_ROOT"] || the baked root). |
|
The preload shim’s in-image path, RELATIVE to the mount root (e.g. lib/tebako/libtfs_preload.so). |
|
The runtime’s own PE module basename (e.g. x64-ucrt-ruby340.dll) — MSYS builds only; POSIX builds omit the key. Bare-name grammar; a violation is a named exit 78 (the declaration lies). |
|
The interpreter’s in-image path (POSIX-absolute on every platform, e.g. /bin/java) — the spec-29 wrapper-exe pattern: a runtime whose exe artifact is the tebako-owned wrapper (repacked upstream bytes the driver cannot be linked into) declares the real interpreter here; the wrapper resolves it against the env image’s mount, drive-qualified onto the runtime root per spec-17 §1. |
|
How the child reaches its ENTRY under a mechanism that can serve virtual paths. 'read' keeps the entry’s VFS spelling: the interpreter opens it through the shim, so every relative include the program performs resolves INSIDE the image. |
|
The kernel-visibility mechanism the wrapper honors for the interpreter and its children: 'preload' (tier 1 — the POSIX default for dynamic interpreters; requires the preload_shim grant, schema_minor 2), 'seccomp-notify' (tier 2a — linux statics), 'exec-cache'. |
|
The interpreter API version line the image carries (ruby: the "3.4"-style line). Declared for the factory and future consumers; the era-2 driver parses but does not gate on it. |
The full grammar.
The source of truth is
docs/spec/schemas/layout.yaml
in the product repository; this page is regenerated from it by
tools/sync-schemas.rb.
See also: Runtime as image · Spec index