Skip to content

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

schema_version

This schema’s MAJOR; missing = era 1 (pre-era document, S17’s kin).

era

The contract era of the image. >= 2 once declared; < 2 is the pre-era refusal. Newer than the driver speaks → upgrade refusal.

image_layout

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

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).

mount_root_override

The image’s grant that its interpreter follows TEBAKO_MOUNT_ROOT at run time (ruby: rbconfig emits ENV["TEBAKO_MOUNT_ROOT"] || the baked root).

preload_shim

The preload shim’s in-image path, RELATIVE to the mount root (e.g. lib/tebako/libtfs_preload.so).

runtime_dll

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).

interpreter

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.

entry_delivery

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.

visibility

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'.

interpreter_api_version

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.

# =============================================================================
# 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

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.