# =============================================================================
# payload-manifest.yaml — the L1 in-image payload manifest grammar
# (spec 18 §2.2; spec 03 §1–§5 formalized)
#
# The self-description every payload carries at /__tpkg__/manifest.yaml:
# IDENTITY + PROVIDES + DEPENDS on a common provenance/trust layer. This
# file formalizes the CURRENT shape (crates/tpkg/src/manifest.rs, the
# implementation of record) as schema_version 1 — plus the spec-18
# contract field identity.era. It is a declaration of what exists, not a
# redesign.
#
# SSOT: this file owns the grammar; crates/tpkg/src/manifest.rs (the
# serde model + validators) mirrors it — keep the two in sync in the same
# PR. The versioned JSON Schema the code comments reference
# (schema/tpkg-manifest-v1.schema.json) is generated FROM this file when
# the JSON-Schema pipeline lands (spec 18 §3.9).
# =============================================================================
schema: payload-manifest
schema_version: 1 # MAJOR — breaking changes only
schema_minor: 17 # MINOR — additive changes only (1: materialize, 2: library_aliases, 3: checks, 4: requires kind runtime, 5: requires kind executable + expose, 6: on_runtime, 7: language_version on runtime provides + the runtime_requirement any_of list form and its implementation key, 8: interp_env, 9: per-edge triplets conditioning on requires edges — data/runtime/executable gain the toolkit edge's triplets key; kind: language refuses it, 10: augments + provides.extension_points + provides.gems — the reverse extension-slice edge and its dedup inventory, spec 03 §2.8, 11: windows_boot on runtime provides — the windows materialize boot tier, spec 17 §7, 12: the constraint grammar admits the variant-suffixed component shape versions already carry — each component is leading decimals plus an optional -label ([0-9A-Za-z-]+) — so an exact pin can name a base/runtime LINE (spec 05 §5; pre-minor-12 readers reject a suffixed clause by name, exit 65), 13: aarch64-windows-ucrt joins the platforms axis, 14: the toolkit/data/runtime/executable requires edges gain the optional registry: alias pin — spec 37 §3's pin-surface rule; kind: language never carries it, 15: min_runtime_tebako — the payload's min-runtime tooling floor (spec 03 §2.9, tebako#666; resolution discards stale cached runtimes, the driver refuses by name), 16: env_pass — the packager's env pass-through list for the driver's credential scrub (spec 03 §2.10, tebako#737; the driver blanks every non-contract TEBAKO_* variable at boot unless declared here), 17: identity.era — the spec-18 contract field, absent = era 1 (pre-era)))
status: normative
owner: crates/tpkg (the model) in tamatebako/tebako
edge: C7 (driver → payload images), C10 (executable payload → runtime), C11 (feature payload → consumers)
# 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.
(Here: tolerated at every section level; only identity.annotations is
guaranteed lossless on round-trip.)
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. (Here: identity.schema_version.)
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). Applies to
provides/requires entries.
lists_stay_lists: >-
Ordered/multiplicity data is a list of entries carrying their identity
fields — never keyed maps. (Here: entrypoints, requires, executables,
libraries, encryption parts.)
declaration:
where: /__tpkg__/manifest.yaml inside every payload image
format: YAML (authored-manifest rule, invariant 6)
grammar:
identity:
type: map
required: true
fields:
schema_version: {type: int, required: true, notes: this schema's MAJOR}
era:
type: int
required: false
notes: >-
The spec-18 contract field: the payload's declared era (>= 2
once declared). Absent = era 1 (pre-era payload) — consumers
that require the contract refuse by name (spec 18 §2.2).
kind: {type: enum, values: [app, data, toolkit, runtime, language], required: true}
name: {type: string, required: true}
version: {type: string, required: true, notes: free-form (semver AND datever exist)}
producer:
type: map
required: true
fields:
tool: {type: string, required: true}
tool_version: {type: string, required: true}
created: {type: string, required: true, notes: RFC 3339 rendering; the model does not interpret time}
source:
type: map
required: false
fields:
src_sha256: {type: string, required: false, notes: 64 lowercase hex}
commit: {type: string, required: false}
builder: {type: string, required: false}
notes: at least one digest/id required when the block is present
sbom:
type: map
required: false
fields:
ref: {type: string, required: true}
digest:
type: map
required: true
fields:
tree_hash:
type: string
required: true
notes: "\"<algorithm>:<64 lowercase hex>\" — the manifest-excluded merkle root (tfs-merkle-1), the CAS identity"
blob_sha256:
type: string
required: true
notes: 64 lowercase hex — advisory provenance only in an embedded manifest (spec 03 §7 fixed-point rule)
signing:
type: map
required: true
fields:
state: {type: enum, values: [unsigned, signed], required: true}
keyid: {type: string, required: "iff state signed", notes: 16 lowercase hex — low 64 bits of the OpenPGP fingerprint}
mechanism: {type: enum, values: [openpgp], required: "iff state signed"}
encryption:
type: map
required: true
fields:
state: {type: enum, values: [none, encrypted], required: true}
parts:
type: list
required: "iff state encrypted (non-empty)"
entry:
paths: {type: list of absolute in-image paths, required: true}
algorithm: {type: string, required: true}
envelope_refs: {type: list of string, required: true, notes: references to externally-held grant envelopes — NEVER keys}
annotations:
type: map
required: false
notes: >-
free-form k/v; preserved on round-trip. One reserved-reading key:
`home: "/"` declares the image root a runtime/tool home — every
materialization surface extracts the mount WHOLE (spec 22 §6).
The key is kind-agnostic: an unpatched-interpreter PAYLOAD whose
entries derive sibling paths from `__dir__` declares it too, the
value the mount-relative home dir;
`java_home` is the already-shipped back-compat alias for it.
provides:
type: kind-specialized map (bound to identity.kind at parse time)
required: true
variants:
app:
entrypoints:
type: list
required: true
notes: N>=1 — one per invocable command (suites)
entry:
name: {type: string, required: true, notes: the command name the shim registers}
path: {type: string, required: true, notes: absolute in-image path}
args_default: {type: list of string, required: false}
runtime_requirement:
type: "map | list of maps (one-or-many — since schema_minor 7)"
required: false
notes: >-
omit entirely for native / zero-runtime entrypoints (spec 03
§2.2 locked). The LIST form is spec 28 §8's `any_of` — OR in
declaration order — for pure-language payloads whose
admissible set differs per implementation; every entry names
the SAME engine, and the list is never empty (both named
manifest errors). An `abi:` in force REQUIRES
`implementation:` on that entry and FORBIDS the list form —
an ABI is per-implementation by construction (spec 28 §8).
The FORBIDS is a consumer named manifest error; the
REQUIRES is an AUTHORING rule enforced at press/publish
(tebako#556, spec 18 §3: pre-axis published manifests that
declare abi without implementation stay dispatchable
through the compat window). A reader predating schema_minor
7 fails the LIST spelling's parse — the correct refusal
(never a guessed entry).
fields:
engine: {type: string, required: true}
constraint: {type: string, required: true, notes: "range for pure-language (\">= 3.3, < 5.0\"); abi-line for native-extension (\"~> 3.3.0\")"}
implementation: {type: string, required: false, notes: "since schema_minor 7 (spec 28 §8) — narrows to one implementation, matched against the runtime's OWN version line; an entry WITHOUT it matches at the language level (the runtime's language_version, falling back to version on pre-field shards)"}
abi: {type: string, required: false, notes: "the runtime's platform string the native extensions were built against (ruby: Gem::Platform.local.to_s)"}
platforms: {type: "\"universal\" | list of vcpkg triplets", required: true, notes: "spec 03 §3 axis; aarch64-windows-ucrt since schema_minor 13"}
capabilities:
type: map
required: true
notes: "exactly {exec: true, read: true}; may carry host (spec 08 §4 jail request)"
extension_points:
type: list
required: false
notes: "since schema_minor 10 (spec 03 §2.8) — WHERE extension slices may land; absent = the payload accepts none"
entry:
name: {type: string, required: true, notes: "symbolic; slices reference it as augments[].extension_point"}
mount: {type: absolute path, required: true, notes: "slices mount BELOW it at <mount>/<slice.name>"}
layout: {type: "enum: gem-home | files", required: true, notes: "gem-home = a mini GEM_HOME per slice (the ecosystem's multi-home search list, never a union mount); files = opaque content the app enumerates itself"}
gems:
type: list
required: false
notes: "since schema_minor 10 (spec 03 §2.8) — the staged gem inventory, GENERATED by the builder's specifications/*.gemspec scan (never hand-authored); REQUIRED when provides.extension_points declares a gem-home point; exported verbatim as the release's closure.json asset (the slice press's dedup subtraction source); the dispatcher reads it for the slice-overlap journal (spec 07 §2 step 3a)"
entry:
name: {type: string, required: true}
version: {type: string, required: true}
runtime:
provides:
type: "map | list of maps (one-or-many)"
required: true
entry:
engine: {type: string, required: true}
version: {type: string, required: true}
abi_line: {type: string, required: true, notes: "the abi line this build satisfies (e.g. \"4.0\")"}
platform: {type: vcpkg triplet, required: true}
implementation: {type: string, required: false, notes: "the engine implementation this build is (spec 28 §8 — mri / jruby / truffleruby); the spawn edge's implementation filter"}
language_version: {type: string, required: false, notes: "since schema_minor 7 (spec 28 §8) — the language level the runtime implements (jruby 9.4 → \"3.1\"; for mri it equals version); absent on manifests that predate the field — the compat window: eligible, never a match failure of its own"}
built_from:
type: map
required: true
fields:
src_sha256: {type: string, required: true, notes: 64 lowercase hex}
patch_set: {type: string, required: true}
env: {type: map, required: false, notes: environment defaults the dispatcher composes}
entrypoints:
type: list
required: false
notes: "the spawn surface (spec 30 §2) — commands this runtime boots for a consumer's runtime-edge expose list; app-entrypoint grammar minus runtime_requirement (a runtime runs on itself)"
entry:
name: {type: string, required: true, notes: the command name a consumer's expose list names}
path: {type: string, required: true, notes: absolute in-image path}
args_default: {type: list of string, required: false}
on_runtime:
type: map
required: false
since: schema_minor 6
notes: >-
spec 33 (runtime-on-runtime): REQUIRED iff this runtime declares
an owner edge — a requires entry {kind: runtime, …} WITHOUT
expose: — and FORBIDDEN otherwise (both directions are named
manifest errors: the composition declares its rewrite or it is
not a composition). mount declares where THIS runtime's env
image mounts on the owner's boot; argv_template composes between
the owner's interpreter token and the entry (spec 33 §3).
fields:
mount: {type: string, required: true, notes: "POSIX-absolute, spec 17 §1's uniform namespace; never /; colliding with an occupied point is the boot's EEXIST"}
argv_template: {type: list of string, required: true, notes: "the single placeholder is {mount} — expanded to this boot's effective mount point (drive-qualified on windows); an unknown placeholder or a post-expansion escape of the mount is a named boot error (65)"}
owner_contract: {type: string, required: false, notes: "constraint on the owner's contract_version (fail-closed, exit 75 class); default \">= 2\""}
windows_boot: {type: string, required: false, notes: "since schema_minor 11 (spec 17 §7) — the windows boot tier; the single locked value is `materialize`: the runtime's interpreter cannot consume the driver's mounts on windows, so the driver extracts the mounted+verified images into the exec cache and rewires the runtime root to the extracted host tree. Absent = the interpreter reads the mounts directly (ruby); POSIX boots never read the key"}
capabilities:
type: map
required: true
notes: "exactly {exec: true, read: true, runtime: true}"
data:
mount_semantics:
type: map
required: true
fields:
suggested: {type: string, required: true, notes: absolute path — SUGGESTED only (the MOUNT RULE gives the decision to the consumer)}
consumers: {type: list of string, required: false, notes: informational reverse edges}
capabilities:
type: map
required: true
notes: "exactly {exec: false, read: true}"
toolkit:
executables:
type: list
required: false
entry:
name: {type: string, required: true}
path: {type: string, required: true, notes: absolute in-image path}
version: {type: string, required: false}
notes: native, zero-runtime programs — never a runtime_requirement
libraries:
type: list
required: false
entry:
name: {type: string, required: true}
path: {type: string, required: true}
platforms: {type: "\"universal\" | list of vcpkg triplets", required: true}
capabilities:
type: map
required: true
notes: "must carry read: true; may carry host (spec 08 §4)"
provides_abi:
type: list
required: false
notes: >-
The spec-18 C11 contract field (feature/toolkit payloads): a C
ABI name + version at an in-image path. Consumers bind only on
match, both versions printed on mismatch (named refusal; exit
code unallocated, spec 18 §7 — 79 is spec 26's CHECK).
entry:
name: {type: string, required: true}
version: {type: string, required: true}
path: {type: string, required: true, notes: absolute in-image path}
language:
notes: no locked v1 shape — preserved losslessly (Provides::Other)
requires:
type: list
required: false
notes: the MOUNT RULE — mount is declared HERE, in the consumer's manifest
entry:
kind: {type: enum, values: [language, toolkit, data, runtime, executable], required: true}
"language": {engine: "string, required", constraint: "string, required", notes: "FORBIDS triplets (schema_minor 9) — a skipped language edge would boot a payload with no runtime; platform reach of the runtime is the payload-level platforms: axis's statement. A language edge carrying triplets is a named manifest error at parse, steering to platforms:"}
"toolkit": {name: "string, required", constraint: "string, required", triplets: "list of vcpkg triplets, optional", mount: "absolute path, optional", registry: "registry alias ([a-z][a-z0-9-]*), optional (since schema_minor 14, spec 37 §3 — scopes resolution to the one book entry the alias names; an unknown alias is the named UnknownRegistryAlias at resolution)"}
"data": {name: "string, required", constraint: "string, required", triplets: "list of vcpkg triplets, optional (since schema_minor 9)", mount: "absolute path, optional", registry: "registry alias, optional (since schema_minor 14, spec 37 §3 — as on the toolkit edge)"}
"runtime": {engine: "string, required", implementation: "string, optional", constraint: "string, required", expose: "list of bare command names (no path separator, no drive qualifier; never repeated), optional", triplets: "list of vcpkg triplets, optional (since schema_minor 9 — a non-covering host skips the edge: no resolve, no spawn surface, no exposed names; skip is loud and journaled, never an error)", registry: "registry alias, optional (since schema_minor 14, spec 37 §3/§8 — scopes the runtime discovery to the one book entry; runtime_requirement itself gains NO alias field)", notes: "spec 30 §1 (since schema_minor 4) — the spawned-runtime edge: the depended runtime resolves through the RUNTIME index into the store's runtimes/ area and is NEVER co-mounted (NO mount key exists on this edge); its exposed entries are spawned through spec 30 §2's dispatch. The expose x own-entrypoint collision refusal (spec 30 §3) is semantic (the tpkg validator) — not schema-expressible. When the DECLARING payload is kind: runtime and expose is ABSENT, the edge is an OWNER edge (spec 33, since schema_minor 6): the depended runtime owns the boot's process and the declarer's provides carries on_runtime — semantic, not schema-expressible"}
"executable": {name: "string, required", payload: "string, optional", constraint: "string, required", mount: "absolute path, optional", expose: "list of bare command names (no path separator, no drive qualifier; never repeated), optional", critical: "boolean, optional", triplets: "list of vcpkg triplets, optional (since schema_minor 9 — skip semantics as on the runtime edge; applies regardless of critical: true, which governs reader-ERA refusal, never platform reach)", registry: "registry alias, optional (since schema_minor 14, spec 37 §3 — scopes the provider's registry resolution to the one book entry)", notes: "spec 03 §8 + spec 32 §1 (since schema_minor 5) — the capability edge: exact-name resolution against provides.executables ∪ provides.entrypoints[].name (DependencyNotFound / AmbiguousProvider; payload: pins the provider by name). mount and expose are ORTHOGONAL axes: mount opens the VFS surface (co-mount, consumer-declared), expose opens the spawn surface (spec 32 §2 — each exposed name dispatches the provider's own spec-17 dispatch as a child; exposed names never take the exec-tier path). Semantic (the tpkg validator), not schema-expressible: an edge with neither mount nor expose is a named manifest error; name ∈ expose is required; every exposed name must resolve to a runtime-carrying entrypoint of the provider (press/install cross-check, the tebako#494 class); the expose x own-entrypoint collision refusal is spec 30 §3's, extended. Producers mark a functionally required edge critical: true (the evolution law's critical flag)"}
augments:
type: list
required: false
notes: "since schema_minor 10 (spec 03 §2.8) — the REVERSE edge: this slice extends the named base payload, attaching below the base's declared extension point. Slices are in-process CONTENT only (capabilities.exec false); a slice is never the dispatched root payload; nested augmentation is the named NestedAugment error. The constraint binds against the base's RESOLVED version; gem-closure slices MUST pin exactly (the binding rule — the dedup subtraction is sound only against the exact inventory it subtracted). Dispatch semantics: spec 07 §2 step 3a."
entry:
payload: {type: string, required: true, notes: "the base payload's name"}
constraint: {type: string, required: true, notes: "vs the base's RESOLVED version; exact pin (= x.y.z) for gem-closure slices — naming the base LINE's exact version when the base ships suffixed runtime lines (= 1.16.9-ruby4.0; schema_minor 12 grammar, spec 05 §5)"}
extension_point: {type: string, required: true, notes: "names the base's declared extension_points[].name"}
built_against:
type: map
required: false
notes: "press-tooling provenance — the exact base release whose closure inventory was subtracted"
fields:
version: {type: string, required: true}
closure_sha256: {type: string, required: true, notes: 64 lowercase hex}
materialize:
type: list of absolute in-image paths
required: false
since: schema_minor 1
notes: >-
spec 22 §4 class R — regular files a C library must read through
its own IO (the OpenSSL CA cert is the canonical entry). Any kind
may declare. The driver extracts each declared path P to
<TEBAKO_EXEC_CACHE>/resources/<image-key>/<P> after the mounts and
the jail, before the interpreter handoff; the copy is whole-file,
read-only, and digest-verified (a <P>.tfs-digest record, the
tfs-merkle-1 file digest). Entries are absolute and carry no '..'
components (validated at parse). Old readers ignore the key
(unknown-field rule).
library_aliases:
type: list of entries
required: false
since: schema_minor 2
entry:
name: {type: string, required: true}
path: {type: absolute in-image path, required: true}
notes: >-
spec 22 §2.1 (windows Class L, phase W) — the ONLY bare library
names that resolve to the image's own files; a bare name matching
no entry is a HOST reference and passes through untouched
(host-by-default, no heuristics). `name` is the exact spelling a
loader call presents: no path separator, no drive qualifier
(validated at parse); matching is verbatim and case-insensitive,
never extension-completed. `path` is absolute, carries no '..'
components, and must name a regular file in the image. Any kind
may declare; no platform filter (native images are triplet-bound,
so an alias is platform surface by construction). Old readers
ignore the key (unknown-field rule).
checks:
type: map of check name → check
required: false
since: schema_minor 3
key: "[A-Za-z0-9][A-Za-z0-9._-]* — names surface in report lines and scratch dir names; unique by the map's construction"
entry:
entry: {type: "absolute in-image path | the reserved spelling \"self\"", required: false, notes: "PRESENT ⇒ an exec check; ABSENT ⇒ a structural check (MECE — one key decides the shape, never a kind flag). \"self\" is kind-runtime only (spec 26 §1.1: the runtime exe itself, env image mounted)"}
argv: {type: list of string, required: false, notes: "exec-only. `{scratch}` (the per-run host scratch dir) at most once per entry; every other spelling is literal passthrough — the engine substitutes, the model carries"}
fixtures: {type: absolute in-image path, required: false, notes: "exec-only. The dir whose CONTENTS land at the HOST scratch root — never VFS-spelled (spec 26 §1)"}
fixtures_inline: {type: map of fixture name → content, required: false, notes: "COMPOSITION-ONLY (spec 26 §2.1) — a composition document's checks: block speaks this family (a composition has no image); REFUSED in a slice manifest with a named validation error (the fixture families are MECE). Names are non-empty scratch-relative paths (never absolute, no '..' components)"}
fixtures_host: {type: path relative to the composition file, required: false, notes: "COMPOSITION-ONLY (spec 26 §2.1) — the org repo's checked-in fixture tree, copied to scratch; refused in a slice manifest. Never absolute (either platform family's spellings), no '..' components — validated platform-neutrally"}
expect:
type: map
required: false
notes: "absent = the default {exit: 0}; byte-golden assertions do not exist by construction"
fields:
exit: {type: int, required: false, notes: "default 0"}
files: {type: list of scratch-relative paths, required: false, notes: "existence + non-empty after the run; never absolute, no '..' components"}
stdout: {type: string, required: false, notes: "one regex the run's stdout must match; carried uncompiled, the engine compiles it"}
image_files: {type: list of absolute in-image paths, required: false, notes: "existence + non-empty; the structural check's assertion channel — a structural check requires a non-empty image_files"}
needs:
type: list
required: false
notes: additive host needs for the check run ONLY (rare) — a minimal mirror of the spec 23 §2 D1 entry grammar
entry:
path: {type: string, required: true, notes: absolute host path or a spec 23 §2 symbolic atom}
access: {type: enum, values: [ro, rw], required: true}
when: {type: "list of enum [windows, macos, linux]", required: false}
why: {type: string, required: false}
requires:
type: map
required: false
notes: "composition prerequisites; unmet ⇒ SKIP (loud, the capability named), never FAIL (spec 26 §2)"
fields:
provides: {type: list of string, required: true, notes: non-empty}
when: {type: "list of enum [windows, macos, linux]", required: false, notes: "the OS-family axis, NOT the spec 03 §3 triplet axis; absent = every platform"}
timeout: {type: int, required: false, notes: positive seconds; expiry is a FAIL}
notes: >-
spec 26 §1 — the payload's own acceptance contracts, declared
in-image: "given my declared needs, I do my one real thing". Any
kind may declare checks (exec checks on executable/runtime slices —
the latter with entry: self — structural checks on data slices).
A malformed block is a named error at press/`tfs validate` (exit
65), never discovered at run time (spec 26 §7). Old readers ignore
the key (unknown-field rule).
interp_env:
type: map of ENV key → string value
required: false
since: schema_minor 8
key: "[A-Z_][A-Z0-9_]* — the shell-safe env-name grammar; a key outside it is a named manifest error at press/`tfs validate` (exit 65)"
notes: >-
tebako#559 (IMPLEMENTED 2026-10-07) — INTERPRETER-OPTION defaults owned by the
slice author (RUBY_YJIT_ENABLE, PYTHON_JIT, JAVA_TOOL_OPTIONS, …):
values the dispatcher exports into the runtime process at dispatch
so the interpreter reads them at its own boot. MECE against
provides' `env:` (the runtime kind's composed process-env
defaults): interp_env is the per-SLICE packaging-time channel
subject to the spec 07 §9 five-layer chain (user env > user config
> package manifest > payload manifest > interpreter built-in);
it is NEVER path-class (path composition stays spec 07 §9's rule
on `env:`) and never carries the TEBAKO_* control namespace (those
vars are dispatcher/driver-owned — a TEBAKO_* key here is a named
manifest error). Values are literal strings: no expansion, no
command execution, no reference grammar — additive and declarative
by construction. A malformed block (non-string value, empty key)
is a named manifest error at press/`tfs validate` (exit 65),
never discovered at run time. Old readers ignore the key
(unknown-field rule): a pre-minor-8 dispatcher simply ships the
interpreter's built-in default — the declaration is a default,
never a requirement.
min_runtime_tebako:
type: string
required: false
since: schema_minor 15
grammar: 1..=4 dot-separated components of the schema_minor-12 component shape (leading decimals, optional -label suffix)
notes: >-
spec 03 §2.9 (tebako#666) — the minimum tebako tooling version of
the runtime this payload runs on. Resolution (spec 05 §5)
discards cached runtimes below the floor and fetches instead; the
driver (spec 17 §8) refuses a manifest whose floor exceeds the
runtime's own tooling version with the named stale-runtime
wording ("the runtime is too old for this payload's manifest"),
including on the parse-failure path via the tolerant top-level
scan. Old readers ignore the key (unknown-field rule). A value
outside the grammar is a named manifest error at parse (exit 65).
env_pass:
type: list-of-strings
optional: true
description: |
The packager's env pass-through list (spec 03 §2.10, additive —
schema_minor 16, tebako#737): TEBAKO_* variable names the
packaged run KEEPS despite the driver's packager-credential
scrub (every non-contract TEBAKO_* variable is blanked at boot —
a packaged app must not exfiltrate the packager's credentials,
TEBAKO_GITHUB_TOKEN above all). Names are TEBAKO_-prefixed
uppercase alphanumerics/underscore; anything else is a named
manifest error at parse. Absent = the scrub takes everything
non-contract.
refusals:
- case: identity.schema_version missing
behavior: era-1 named refusal (never a silent default)
- case: kind ↔ provides shape mismatch
behavior: structural error at parse (never a validation surprise later)
- case: entrypoint's runtime_requirement unsatisfiable at dispatch (S26/C10)
behavior: named error naming the entrypoint and the requirement — never a segfault
- case: provides_abi mismatch at bind (C11)
behavior: named refusal, both versions printed (exit code unallocated — spec 18 §7; 79 is spec 26's CHECK)
- case: a materialize entry absent from the image, or not a regular file (schema_minor 1)
behavior: the manifest lies — boot fails with a named error (exit 65), never a skipped entry
- case: a materialized copy failing digest verification at boot (schema_minor 1)
behavior: the exec cache is tampered or corrupt — boot fails with a named error (exit 70), never a silently served corruption
- case: a library_aliases name carrying a path separator or drive qualifier (schema_minor 2)
behavior: named validation error at parse — the bare-name grammar is exact, never guessed (exit 65)
- case: a library_aliases path absent from the image, or not a regular file (schema_minor 2)
behavior: the manifest lies — boot fails with a named error (exit 65), never a skipped entry
- case: a duplicate alias name within one image, or one alias name declared by two co-mounted images (schema_minor 2)
behavior: authoring ambiguity — a named error (parse-time, resp. boot-time exit 65), never a silent winner
- case: "entry: self on a kind other than runtime (schema_minor 3)"
behavior: named validation error at parse (exit 65) — the reserved spelling names the runtime exe, spec 26 §1.1
- case: a structural check (no entry) declaring argv/fixtures, or asserting no image_files (schema_minor 3)
behavior: named validation error at parse (exit 65) — exec-only keys on a structural check are a grammar violation
- case: a slice manifest declaring fixtures_inline/fixtures_host, or a composition check declaring fixtures (schema_minor 3)
behavior: named validation error at parse (exit 65) — the fixture families are MECE per context (spec 26 §2.1); a composition check is validated by the engine at document load, a slice check at press/`tfs validate`
- case: "a duplicate check name within one checks: block (schema_minor 3)"
behavior: named structural error at parse — an authoring ambiguity, never a silent winner (the map's own deserializer refuses)
- case: a malformed checks block otherwise (bad name grammar, relative entry, absolute expect.files, '..' components, non-positive timeout, a when value outside windows/macos/linux) (schema_minor 3)
behavior: named validation error at press/`tfs validate` (exit 65), never discovered at run time (spec 26 §7)
- case: "a kind: executable edge declaring neither mount: nor expose: (schema_minor 5)"
behavior: named validation error at parse (exit 65) — a contentless edge opens no surface (spec 32 §1)
- case: "expose: declared on a kind other than runtime/executable, or an expose-carrying kind: executable edge whose name is absent from the expose list (schema_minor 5)"
behavior: named validation error at parse (exit 65) — expose lives on spawned edges only, and the depended capability must be surfaced (spec 32 §1)
- case: "an expose name on a kind: executable edge that does not resolve to a runtime-carrying entrypoint of the resolved provider payload (schema_minor 5)"
behavior: named validation error at press/install (the tebako#494 cross-check class; a runtime-less match is authoring confusion, never an exec-tier fallback); at spawn, the outruns rule's named spawn error (spec 32 §7)
- case: "on_runtime present without an owner edge, an owner edge (kind: runtime declared BY a kind: runtime payload, expose absent) without on_runtime, or two owner edges on one payload (schema_minor 6)"
behavior: named manifest error at press/`tfs validate` (exit 65) — the composition declares its rewrite or it is not a composition (spec 33 §2/§4)
- case: "on_runtime.mount spelled /, carrying '..' components, or argv_template holding an unknown placeholder or a path escaping the mount after expansion (schema_minor 6)"
behavior: named validation error at parse, resp. a named boot error (exit 65) — the template is data, never guessed (spec 33 §2)
- case: "a kind: language edge carrying triplets: (schema_minor 9)"
behavior: "named validation error at parse (exit 65) — a skipped language edge would boot a payload with no runtime; platform reach is the payload-level platforms: axis's statement (spec 03 §2.3)"
- case: "a requires edge's triplets: list empty or carrying a duplicate (all kinds; schema_minor 9)"
behavior: named validation error at parse (exit 65) — the toolkit edge's existing list grammar, generalized (spec 03 §2.3)
- case: "dispatching a command whose expose edge was platform-skipped on this host (schema_minor 9)"
behavior: named error, exit 69 — \"not available on this platform\", never a silent fallback to another provider (spec 03 §2.3)
- case: "a requires edge's registry: value outside the [a-z][a-z0-9-]* alias grammar (schema_minor 14)"
behavior: named validation error at parse (exit 65) — the alias grammar is the config book's own (spec 37 §2/§3); whether the alias EXISTS is resolution-time's UnknownRegistryAlias, never the manifest's call
- case: "a min_runtime_tebako value outside the version grammar (schema_minor 15)"
behavior: named validation error at parse (exit 65) — the floor is data, never guessed (spec 03 §2.9)
- case: "a runtime whose tebako version is below the payload's declared min_runtime_tebako (schema_minor 15)"
behavior: resolution skips the stale cached runtime and fetches (TEBAKO_OFFLINE stays fail-closed); at boot the driver refuses with the named stale-runtime wording — \"the runtime is too old for this payload's manifest (needs X, have Y)\" — never \"corrupt manifest / self-description lies\" (spec 05 §5, spec 17 §8, tebako#666)
deprecated: [] # no field is in a deprecation window
REFERENCE · 17
The L1 in-image payload manifest grammar.
Every payload image carries a manifest that declares the payload's identity, what it provides, and what it requires from the runtime and from other payloads. The manifest is the authority that every other tier mirrors. This page is the grammar of that manifest.
What it defines.
The self-description every payload carries at /__tpkg__/manifest.yaml: IDENTITY + PROVIDES + DEPENDS on a common provenance/trust layer. This file formalizes the CURRENT shape (crates/tpkg/src/manifest.rs, the implementation of record) as schema_version 1 — plus the spec-18 contract field identity.era. It is a declaration of what exists, not a redesign.
Identity.
| Field | Value |
|---|---|
schema |
payload-manifest |
schema_version |
1 |
schema_minor |
17 |
status |
normative |
owner |
crates/tpkg (the model) in tamatebako/tebako |
Sections.
| Section | What it declares |
|---|---|
|
Map, required — fields schema_version, era, kind, name, version, producer, created, source, and 5 more. |
|
Kind-specialized map (bound to identity.kind at parse time), required. |
|
The MOUNT RULE — mount is declared HERE, in the consumer’s manifest. |
|
The REVERSE edge: this slice extends the named base payload, attaching below the base’s declared extension point. Slices are in-process CONTENT only (capabilities.exec false); a slice is never the dispatched root payload; nested augmentation is the named NestedAugment error. |
|
Spec-22 §4 class R — regular files a C library must read through its own IO (the OpenSSL CA cert is the canonical entry). Any kind may declare. |
|
The ONLY bare library names that resolve to the image’s own files; a bare name matching no entry is a HOST reference and passes through untouched (host-by-default, no heuristics). |
|
The payload’s own acceptance contracts, declared in-image: "given my declared needs, I do my one real thing". Any kind may declare checks (exec checks on executable/runtime slices — the latter with entry: self — structural checks on data slices). |
|
INTERPRETER-OPTION defaults owned by the slice author (RUBY_YJIT_ENABLE, PYTHON_JIT, JAVA_TOOL_OPTIONS, …): values the dispatcher exports into the runtime process at dispatch so the interpreter reads them at its own boot. |
|
The minimum tebako tooling version of the runtime this payload runs on. |
|
List-of-strings. |
The full grammar.
The source of truth is
docs/spec/schemas/payload-manifest.yaml
in the product repository; this page is regenerated from it by
tools/sync-schemas.rb.
See also: Manifest reference · Create a data payload