Skip to content

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

defaults

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 — a payload-qualified value makes the named payload THE provider.

auto_slices

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

Spec-04 §2 registry refs; shipped config has ZERO registries (explicit only — no default service).

runtimes

Per-engine runtime preference, written by tebako-shim use --runtime <engine>@<langver>[:<tebako>] (MINOR 2 — the verb parses the qualified form and writes this structured shape).

env

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

store_layout_marker

The on-disk marker that records the store layout era, verified on first access.

The full grammar.

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

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.