# =============================================================================
# store-config.yaml — the store configuration grammar (spec 18 §2.2, C13)
#
# The user-authored configuration of the local store (~/.tebako), plus the
# store's own layout marker. The dispatcher only READS config.yaml; the
# authored-config writes the toolchain performs are `tebako add-registry`
# and `tebako-shim use` (structural edits, tmp + rename). Shim-managed
# state (shims/.disabled.yaml) is kept OUT of the authored file.
#
# SSOT: this file owns the grammar; the store-layout module (today:
# crates/tebako-shim/src/config.rs — one model, parse + validate) mirrors
# it. The C13 layout-version marker is declared here; the read check
# (newer → upgrade refusal; older → the named migration) is spec 18
# implementation map item 8.
# =============================================================================
schema: store-config
schema_version: 1 # MAJOR — breaking changes only
schema_minor: 5 # MINOR — additive changes only (1: runtimes.*.source; 2: defaults/runtimes accept the [payload@]version qualified grammar — tebako-shim use writes them; 3: env per-tool interpreter-option maps — tebako#559; 4: defaults values may carry slices: + top-level auto_slices: — spec 07 §4 extension slices; 5: defaults keys gain the <registry>/<payload> payload-pin form covering every entrypoint of the payload — tebako#667)
status: normative
owner: crates/tebako-shim (the config model of record) in tamatebako/tebako
edge: C13 (everything local → store)
# 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. (defaults:/runtimes: are k/v SETTINGS maps,
not multiplicity data; registries: is a list.)
declaration:
where: ~/.tebako/config.yaml (user-authored)
format: YAML (authored-manifest rule, invariant 6)
grammar:
defaults:
type: map(command name | <registry>/<payload> → [payload@]version pin string | {version?, slices?})
required: false
notes: >-
Per-tool version pins, written by `tebako-shim use <tool> <pin>` —
the version chain's user-default link (S28). MINOR 2: the pin VALUE
is the [payload@]version qualified grammar (spec 07 §0/§2 step 0.5;
tpkg::toolpin::ToolPin is the ONE parser) — a payload-qualified
value makes the named payload THE provider. MINOR 4 (spec 07 §4):
the value may instead be the map form {version: "…", slices:
[<slice>@<version>, …]} — either key may be absent (a slices-only
entry pins no base version); `tebako-shim use` rewrites `version:`
in place and preserves `slices:`. MINOR 5 (spec 07 §4, tebako#667):
a KEY of the form <registry>/<payload> is the payload-level pin —
it covers every entrypoint the payload declares (one line moves a
whole suite to a chosen version). The value carries version: only
(slices: is per-tool; registry: would duplicate the key's alias).
A tool-level pin beats the payload pin for its own command
(specific beats general, the chain's first-hit rule within the
config tier); a version-less payload pin only scopes the payload's
registry-default lookup to the key's alias. Two payload pins
naming the same payload with different versions are the named
ambiguity error, never a silent winner.
auto_slices:
type: boolean
required: false
notes: >-
MINOR 4 (spec 07 §4): `false` kills the spec 07 §2 step-3a
store scan (auto-discovered extension slices never attach);
explicit slice pins still attach. Absent = auto discovery ON. A
project file's document-level `auto_slices:` wins over this value,
the same precedence as versions.
registries:
type: list of string
required: false
notes: spec 04 §2 registry refs; shipped config has ZERO registries (explicit only — no default service)
runtimes:
type: map(engine → {version, tebako, source?})
required: false
notes: >-
Per-engine runtime preference (the download fallback of spec 05 §5
needs an exact ref), written by `tebako-shim use --runtime
<engine>@<langver>[:<tebako>]` (MINOR 2 — the verb parses the
qualified form and writes this structured shape). `tebako` may be
ABSENT when written without the `:<tebako>` part — readers treat it
as the product default line.
version = the language version (e.g. "4.0.6"); tebako = the tebako
(launcher) abi version the runtime was built with — the <ver> of the
cache layout runtimes/<lang>-<lv>-<ver>-<triplet>/.
source (MINOR 1, PLANNED) = the per-engine download
base override (https or file://), the first channel of spec 05 §2's
per-engine base chain; absent → the chain's lower channels answer.
env:
type: map(command name → map(ENV key → string value))
required: false
notes: >-
MINOR 3 (IMPLEMENTED 2026-10-07 — tebako#559): the operator's
standing per-tool
interpreter-option policy — layer 2 of the spec 07 §9.1 interp_env
chain (user env > this map > package manifest > payload manifest >
interpreter built-in). Keyed by command name, the same axis
`defaults:` uses (a k/v SETTINGS map, not multiplicity data);
inner keys obey the spec 03 §2.7 grammar ([A-Z_][A-Z0-9_]*, never
TEBAKO_*; an offending key is the NAMED grammar error at READ,
never a silent skip). Written by hand or by `tebako-shim env
<tool> KEY=VALUE` / `--unset`; a dispatch NEVER writes it
implicitly.
store_layout_marker:
path: ~/.tebako/layout-version
grammar: a single integer — the store layout era
notes: >-
C13's second declaration (spec 18 §2.2). Verified on first access per
process: newer than the binary → upgrade refusal (S41); older → the
named migration runs or refuses explicitly, never a silent mixed
layout (S42).
refusals:
- case: layout-version newer than the binary (S41)
behavior: upgrade refusal
- case: layout-version older (S42)
behavior: the named migration — never a silent mix
- case: config.yaml unparseable
behavior: named error ("fix or remove it") — the dispatcher never guesses
- case: an unparseable "[payload@]version" value in "defaults:"
behavior: >-
the NAMED grammar error at READ (EX_TEBAKO_MANIFEST, naming the
chain link and the value — spec 07 §0/§7), never a silent skip to
the next chain link
- case: a defaults key carrying '/' outside the <registry>/<payload> grammar, or two payload pins naming one payload with different versions (MINOR 5, tebako#667)
behavior: >-
the NAMED grammar / ambiguity error at dispatch
(EX_TEBAKO_MANIFEST, naming the keys), never a silent no-match or
a silent winner
deprecated: [] # no field is in a deprecation window
REFERENCE · 20
The store configuration grammar.
The local store's configuration file carries the operator's registries, default versions, and per-tool environment, authored in YAML and edited through the toolchain. This page is the grammar of that file and of the store's layout marker.
What it defines.
The user-authored configuration of the local store (~/.tebako), plus the store’s own layout marker. The dispatcher only READS config.yaml; the authored-config writes the toolchain performs are tebako add-registry and tebako-shim use (structural edits, tmp + rename). Shim-managed state (shims/.disabled.yaml) is kept OUT of the authored file.
Identity.
| Field | Value |
|---|---|
schema |
store-config |
schema_version |
1 |
schema_minor |
5 |
status |
normative |
owner |
crates/tebako-shim (the config model of record) in tamatebako/tebako |
Sections.
| Section | What it declares |
|---|---|
|
Per-tool version pins, written by |
|
|
|
Spec-04 §2 registry refs; shipped config has ZERO registries (explicit only — no default service). |
|
Per-engine runtime preference, written by |
|
The operator’s standing per-tool interpreter-option policy — layer 2 of the spec-07 §9.1 interp_env chain (user env > this map > package manifest > payload manifest > interpreter built-in). |
|
The on-disk marker that records the store layout era, verified on first access. |
The full grammar.
The source of truth is
docs/spec/schemas/store-config.yaml
in the product repository; this page is regenerated from it by
tools/sync-schemas.rb.
See also: Environment variables · Shims & versions