@olivervea/pipelines 2.0.0-beta.3 → 2.0.0-beta.7

package/README.md

@@ -4,7 +4,7 @@ The [Olve.Pipelines](https://github.com/OliverVea/Olve.Pipelines) v2 SDK. It has
 
 - the **authoring API**: models, steps, handlers and the typed pipeline builder;
 - the **step harness**: the runtime compiled into each pipeline's single executable (`describe`, `run`, `map-trigger`);
-- the **build tool** (`olve-build`), which turns a pipeline directory into `step.tar.gz` and `manifest.json`;
+- the **build tool** (`olve-build`), which turns a pipeline directory into `step.tar.zst` and `manifest.json`;
 - the **dev runner** (`olve-dev`), which runs the same harness path from source (used by `pl dev`).
 
 Design: [`docs/design/pipelines-v2.md`](https://github.com/OliverVea/Olve.Pipelines/blob/v2/docs/design/pipelines-v2.md). Spike findings: [`pipelines-v2-spikes.md`](https://github.com/OliverVea/Olve.Pipelines/blob/v2/docs/design/pipelines-v2-spikes.md).
@@ -13,9 +13,9 @@ The manifest format is in [`manifest.schema.json`](manifest.schema.json), genera
 ```
 sdk/
   src/index.ts            authoring API (`@olivervea/pipelines`)
-  src/core/               models, secrets, steps, implement()
+  src/core/               models, secrets, config, steps, implement()
   src/builder/            pipeline builder (types + runtime records), Ref<T>
-  src/library/            library steps (script, gitHubSource, imageBuild, helmDeployOverSsh), their exported helpers (httpHealthCheck) and SDK models
+  src/library/            library steps (script, gitHubSource, imageBuild, helmDeployOverSsh, helmDeployInCluster, composeDeploy), their exported helpers (httpHealthCheck, registryTag, npmDistTag) and SDK models
   src/describe/           describe: manifest, checks, mapper recording + source analysis, manifest schema
   src/harness/            harness CLI modes, env contract, envelope, result upload (`@olivervea/pipelines/harness`)
   src/ctx/                the ctx handed to handlers
@@ -108,6 +108,40 @@ Rules:
 - A **plain-schema input** has no model to match on, so the step needs a mapper.
 - **`optional(M)`** means "maybe skipped": `M` must still have an earlier producer.
 
+### Config
+
+Values that differ per deployment (hosts, namespaces, which identity provider) are **config**: typed entries the pipeline declares, whose values live on the instance (one YAML document per pipeline, edited with `pl config` or the dashboard), not in the repo.
+
+```ts
+import { config, secret, secretRef, step, z } from "@olivervea/pipelines";
+
+export const DEX_CLIENT_SECRET = secret("DEX_CLIENT_SECRET", "Dex client secret.");
+export const AUTH = config("auth", "How users authenticate.", z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("none") }),
+  z.object({ mode: z.literal("dex"), issuer: z.string().url(), clientSecret: secretRef(DEX_CLIENT_SECRET) }),
+]));
+export const TARGET = config("target", "Where the release is deployed.",
+  z.object({ host: z.string(), namespace: z.string().default("olve-pipelines") }));
+
+export const deploy = step({ name: "deploy", description: "Deploys the release.", image: "alpine:3.22",
+  config: [AUTH, TARGET],              // ctx.config is typed to exactly these
+  secrets: [DEX_CLIENT_SECRET] });     // a secretRef's secret must be declared too
+```
+
+```yaml
+# the instance's config document for this pipeline
+auth: { mode: dex, issuer: https://dex.example.com, clientSecret: { secret: DEX_CLIENT_SECRET } }
+target: { host: deploy@box }
+```
+
+- `config(name, description, schema)` mirrors `secret(...)`. Names match `^[a-z][a-zA-Z0-9]*$` (they are YAML keys).
+- An entry whose schema accepts `undefined` (`.optional()`, `.default(…)`) is optional; every other entry is required. Defaults are applied when config is read, never written into the document.
+- Handlers see `ctx.config` with the output view (defaults applied); a discriminated union narrows as usual.
+- `secretRef(S)` is a field whose value is `{ secret: "<S.name>" }`: it names a secret, never holds its value. The handler reads the value from `ctx.secrets`. A step that receives an entry containing a `secretRef` must declare that secret.
+- Config is per **run**: the run pins a config snapshot at start; continues and step reruns reuse it. Secrets are per attempt.
+- Library steps take **config references** in place of values: `host: TARGET.host`, `target: TARGET.beta`. A reference is a typed proxy (`ConfigRef<T>`, `T` = the field's output type; `Configurable<T> = T | ConfigRef<T>`), so a `number` field or an optional field can't go where a `string` is required. Fields named `kind`, `name`, `description` or `schema` (the entry's own properties) are reached through `$` (`TARGET.$.name`); `TARGET.$` and `TARGET` itself reference the whole entry. The step's `config` gets every referenced entry (`configEntries` in the manifest); `manifestConfig` records each reference as `{"$config": "<entry>.<path>"}` (field names must not contain `.`; literal keys starting with `$` are reserved); `run()` resolves them from `ctx.config` (defaults applied) before doing anything. `describe` and reconcile reject a reference to an entry the step doesn't receive or a field the entry doesn't have.
+- `clusterAccess: true` on a step asks for the instance's step ServiceAccount token (`Kubernetes:StepServiceAccount`; manifest `clusterAccess: true`, omitted otherwise). Without the instance setting the pod gets no token, like every step.
+
 **`steps.script` contract** (for the script):
 
 | Name | What it holds |
@@ -125,14 +159,16 @@ Library steps carry their own implementation and image; they take typed config a
 | Step | Image | Input → output | Config |
 |---|---|---|---|
 | `steps.script` | yours | yours | `script` (embedded), `env` (see above) |
-| `steps.gitHubSource` | `alpine:3.22` (work happens in the harness) | `{ repo: "owner/name", sha }` (plain schemas: needs a mapper) → `Source` | `token?: Secret` (sent as `Authorization: Bearer`; becomes the step's secret) |
-| `steps.imageBuild` | `gcr.io/kaniko-project/executor:debug` | `{ source: Source }` → `BuiltImage { repository, tag, digest, tar }`; with `push`: `PushedImage { repository, tag, digest }` | `repository` (image name; tag = run version, `-attempt<n>` on reruns), `context?` (dir in the source tree; default the root), `dockerfile?` (relative to the context; default `Dockerfile`), `push?` (push to `repository` instead of a tarball), `contentTag?` (with `push`: tag `src-<context hash>`, skip when the registry has it), `cacheRepo?` (kaniko layer cache), `registryMap?` (kaniko `--registry-map`: registry → mirror prefix; default: the homelab pull-through caches, `{}` = off), `stallTimeoutSeconds?` (default 300, 0 = off), `retries?` (default 2) |
-| `steps.helmDeployOverSsh` | `alpine:3.22` (+ `apk add openssh-client` at run time) | `{ source: Source, <key>: BuiltImage }` per `images` (`PushedImage` with `fromRegistry`) → `HelmRelease { release, namespace, image }` (`image`: the first image) | `host` (`user@host`), `sshKey: Secret`, `release`, `namespace`, `chart` (dir in the source), `values?` (chart-relative `-f`), `set?`, `images?` (input key → values prefix; default `{ image: "image" }`), `fromRegistry?`, `deployments?` (default `[release]`), `rolloutTimeoutSeconds?` (default 120), `healthUrl?` (URL or `{ url, attempts?, delaySeconds? }`) |
+| `steps.gitHubSource` | `alpine:3.22` (work happens in the harness) | `{ repo: "owner/name", sha }` (plain schemas: needs a mapper) → `Source` | `token?: Secret` (sent as `Authorization: Bearer` when set; unset = anonymous; becomes the step's secret), `apiUrl?` (default `https://api.github.com`) |
+| `steps.imageBuild` | `gcr.io/kaniko-project/executor:debug` | `{ source: Source }` → `BuiltImage { repository, tag, digest, tar }`; with `push`: `PushedImage { repository, tag, digest }` | `repository` (image name; tag = run version, `-attempt<n>` on reruns), `context?` (dir in the source tree; default the root), `dockerfile?` (relative to the context; default `Dockerfile`), `push?` (push to `repository` instead of a tarball), `contentTag?` (with `push`: tag `src-<context hash>`, skip when the registry has it), `cacheRepo?` (kaniko layer cache), `registryMap?` (kaniko `--registry-map`: registry → mirror prefix; default: the homelab pull-through caches, `{}` = off), `stallTimeoutSeconds?` (default 300, 0 = off), `retries?` (default 2), `registryAuth?` (`{ username, password: Secret }`: log in to the `repository` registry; or a config reference to `{ username, password: { secret: NAME } }`, with `NAME` in `secrets`), `insecureRegistry?` (that registry is plain HTTP), `secrets?` (declared secrets a config `registryAuth` may name), `enabled?` (`false` skips the step) |
+| `steps.helmDeployOverSsh` | `alpine:3.22` (+ `apk add openssh-client` at run time) | `{ source: Source, <key>: BuiltImage }` per `images` (`PushedImage` with `fromRegistry`) → `HelmRelease { release, namespace, image }` (`image`: the first image) | `host` (`user@host`), `sshKey: Secret`, `release`, `namespace`, `chart` (dir in the source), `values?` (chart-relative `-f`), `set?`, `images?` (input key → values prefix; default `{ image: "image" }`), `fromRegistry?`, `imageRefs?` (`PushedImage` input key → values prefix: set as `<prefix>.repository`/`.tag`/`.digest`, not pulled; works next to tarball `images`), `deployments?` (default `[release]`), `rolloutTimeoutSeconds?` (default 120), `healthUrl?` (URL or `{ url, attempts?, delaySeconds? }`) |
+| `steps.helmDeployInCluster` (and the `target` form of `helmDeployOverSsh`) | `alpine/helm:3.16.2` (ssh: `alpine:3.22`) | `{ source: Source, <key>: PushedImage }` per `images`, `<key>: optional(PushedImage)` per `imageRefs` → `HelmRelease` (`image`: `repository:tag@digest` of the first image) | `target` (a `select` case's reference to a `helmTarget()` variant: `{ kind: "inCluster", namespace, release, values, set, url? }` for helmDeployInCluster, the same plus `host` with `kind: "ssh"` for helmDeployOverSsh; `url` is where step pods reach the release, default its in-cluster Service URL, and is passed on in `HelmRelease.url`), `sshKey: Secret` (ssh only), `chart`, `inlineValues?` (objects written as values files after the target's), `images?`, `imageRefs?`, `deployments?` (ssh), `rolloutTimeoutSeconds?` (default 120), `healthPath?`; helmDeployInCluster declares `clusterAccess` |
+| `steps.composeDeploy` | `alpine:3.22` (work happens in the harness) | `{ image: PushedImage }` → `HelmRelease { release: <service>, namespace: "compose", image: <repository>@<digest> }` | `target` (a `select` case's reference to the compose variant of `deployTarget()`: `{ kind: "compose", deployerUrl, service, token: { secret }, healthUrl? }`), `token: Secret` (must be the secret the target names; the step's only secret), `timeoutSeconds?` |
 
-- `gitHubSource` downloads `https://api.github.com/repos/<repo>/tarball/<sha>` (retrying 5xx), strips the top-level directory and outputs it as `tree`.
+- `gitHubSource` downloads `<apiUrl>/repos/<repo>/tarball/<sha>` (retrying 5xx), strips the top-level directory and outputs it as `tree`.
 - `imageBuild` copies the tree to `/kaniko/build-context` (kaniko wipes other directories between multi-stage builds), builds `--context=/kaniko/build-context[/<context>] --dockerfile=<that>/<dockerfile>` with `--no-push --tar-path --digest-file`, and outputs the tarball. A missing context or Dockerfile fails the step before kaniko starts. `repository` in the output is fully qualified the way a runtime names a loaded image (`x` → `docker.io/library/x`). A **stall watchdog** kills kaniko when it prints nothing for `stallTimeoutSeconds` (a base-image pull can stall on an idle connection at "Unpacking rootfs", and kaniko has no read timeout), failing the attempt; `retries` then starts a fresh attempt. The retry is deliberately a new pod, never a second kaniko in the same container: kaniko unpacks the base image over the container root and does not clean up when killed.
 - **Caches never block a build.** `registryMap` defaults to the homelab pull-through caches (`DEFAULT_REGISTRY_MAP`: `mcr.microsoft.com` → `mcr-cache.ovea.pro`, `index.docker.io` → `hub-cache.ovea.pro`; kaniko under gVisor stalls pulling from mcr.microsoft.com directly). A map you pass replaces the default; `{}` turns mapping off. Before kaniko starts, every mirror host and the `cacheRepo` registry gets a 5 s `GET https://<host>/v2/` (200 or 401 = up); one that doesn't answer is dropped with a log line (`mcr-cache.ovea.pro unreachable; pulling from mcr.microsoft.com directly`, or no `--cache` for the layer cache). After that, kaniko itself copes: it falls back to the original registry when a mirror can't serve an image's manifest (`RetrieveRemoteImage`; `--skip-default-registry-fallback` is never set), a layer-cache lookup error is a cache miss, a cache push error is a warning, and `--skip-push-permission-check` stops its startup check of the cache repo from exiting. A cache that dies mid-download (after the manifest came from it) fails or stalls the attempt; `retries` starts a fresh one, which probes again.
-- **Registry mode** (`push: true`, for images too big for the step's ~1 GiB scratch space and Garage): kaniko runs without `--no-push`/`--tar-path`, pushes to `repository` (it must start with a registry host; pushes are anonymous) and the output is a `PushedImage` with the digest from `--digest-file`. With `contentTag`, the tag is `src-` + the first 12 hex of the sha256 of the context directory's deterministic tar (the bytes `ctx.output.dir` would write), computed from the fetched tree; an anonymous `HEAD https://<host>/v2/<path>/manifests/<tag>` that answers a `Docker-Content-Digest` skips kaniko and outputs that digest.
+- **Registry mode** (`push: true`, for images too big for the step's ~1 GiB scratch space and Garage): kaniko runs without `--no-push`/`--tar-path`, pushes to `repository` (it must start with a registry host; anonymous unless `registryAuth`) and the output is a `PushedImage` with the digest from `--digest-file`. With `contentTag`, the tag is `src-` + the first 12 hex of the sha256 of the context directory's deterministic tar (the bytes `ctx.output.dir` would write), computed from the fetched tree; a `HEAD https://<host>/v2/<path>/manifests/<tag>` (answering a Basic or Bearer challenge: anonymous token, or the `registryAuth` login; an anonymous lookup that is denied counts as "not there") that answers a `Docker-Content-Digest` skips kaniko and outputs that digest. With `registryAuth`, the step declares the password secret and writes `$DOCKER_CONFIG/config.json` (`/kaniko/.docker` in the kaniko image) for that registry before kaniko runs, so pushes, base-image and cache pulls from it are logged in. `insecureRegistry` makes the lookups plain HTTP and adds kaniko `--insecure --insecure-registry=<host>`.
 - `helmDeployOverSsh` gets each image into the host's **k3s** containerd: a `BuiltImage` tar is streamed in (`nerdctl --address /run/k3s/containerd/containerd.sock --namespace k8s.io load`), a `PushedImage` (`fromRegistry`) is pulled there (`… pull -q`, so the rollout doesn't wait on the pull). It copies the chart to `/tmp/<release>-helm-<namespace>`, runs `helm upgrade --install` from inside it (values, then `set`, then per image `<prefix>.repository`/`.tag`/`.pullPolicy` — `Never` for tarballs, `IfNotPresent` for registry images — which always win), waits for `kubectl rollout status` of each of `deployments` in order (`deploy/<name>` for a bare name), and with `healthUrl` polls it (5 × 5 s unless given) from the harness. Several images (one chart, two Deployments):
 
   ```ts
@@ -141,6 +177,9 @@ Library steps carry their own implementation and image; they take typed config a
     images: { server: "image", web: "web.image" }, deployments: ["olve-slimerepublics-server", "olve-slimerepublics-web"] });
   ```
 
+- **Deploy targets.** `helmTarget(defaults?, extend?)` is the `inCluster | ssh` union. `deployTarget({ namespace?, release?, extend?, composeToken, optional? })` adds `compose` (`{ deployerUrl, service, token: secretRef(composeToken), healthUrl?, …extend }`) and, with `optional: true`, `none` (`{ kind: "none" }`, no other fields; its `select` case usually has no steps). A library step that references a target narrowed to one case needs only that case's secrets: the helm steps don't declare the compose `token`.
+- `composeDeploy` resolves its target, checks `kind` is `compose` and that `token.secret` is the declared secret, then `POST <deployerUrl>/v1/deploy` `{ service, image: "<repository>@<digest>" }` with `Authorization: Bearer <token>`. Each line of the answer's `log` is logged as `deployer: …`; anything but HTTP 2xx with `status: "deployed"` fails the step with the deployer's status and message. With `healthUrl` it then runs `httpHealthCheck` (12 × 5 s). The deployer itself (`compose/deployer`) and its API: [docs/setup/compose-deploy.md](../docs/setup/compose-deploy.md).
+
 **Helpers.** General functions the library steps are built on, exported for custom handlers:
 
 | Helper | What it does |
@@ -180,6 +219,7 @@ export default implement(deployBeta, async ({ artifact }, ctx) => {
 | `http.fetch`, `http.getJson(url, { headers })`, `http.expectOk(url, { method, headers })` | Bound to `ctx.signal`. A non-2xx status throws a readable error, with the URL redacted after `?`. |
 | `retry({ attempts, delaySeconds, backoff? }, fn)` | Retries `fn`. Can be cancelled. |
 | `secrets.NAME` | Typed to the step's declared secrets. Read from the env var `NAME`. Throws if the variable is missing. |
+| `config.<entry>` | Typed to the step's declared config entries (output view, defaults applied). From input.json's `$config`. An optional entry that is not set is `undefined`. |
 | `log(message, fields?)` | Writes a `message k=v …` line to stderr. |
 | `signal` | Aborted on SIGTERM/SIGINT. Running commands are sent SIGTERM. |
 | `run` | `{ pipeline, id, number, attempt, step, version }` (from the env, see below). |
@@ -206,6 +246,7 @@ export default pipeline({ name: "Olve.Pipelines", description: "…", input: M.D
 - **The `from` argument.** It is keyed by step name, plus `input` for the pipeline input. It holds `Ref<T>` values, so only property access and literals compile. Use `from["deploy-beta"].url` for names that contain hyphens.
 - **Describe checks the mapper twice.** It records the mapper with proxies, and it statically analyses the mapper's source. The source must be an object literal of member chains, literals, constant arrays and nested object literals. Ternaries, `&&`, `||`, `??`, `!`, comparisons, arithmetic, template strings, calls, spread and optional chaining are all rejected. Free identifiers such as module constants are allowed; they are recorded as `{const}`.
 - **Triggers.** A pipeline may call `onPush` at most once. Each `onPoll` and `onWebhook` needs a distinct `name` (`onPoll` defaults to `"poll"`). `onWebhook({ name, verify }, ({ headers, body }) => input | null)` maps a delivery to `/api/hooks/<pipeline id>/<name>`; `verify` is `hmacSha256({ secret, header, prefix? })`, `githubSignature(secret)` or `bearer(secret)`, and `null` ignores the delivery.
+- **`select` (branch on config).** `.select(TARGET.prod, { ssh: (p, prod) => p.stage(…), inCluster: (p, prod) => p.stage(…) })`: the first argument references a `z.discriminatedUnion` in a config entry (`DiscriminatorOf<U>` is its one literal field; a union with no or several literal fields is a type error). Cases are exhaustive and checked at compile time; each gets the reference narrowed to its variant (`ConfigNode<VariantOf<U, D, V>>`), recorded as `{"$config": "target.prod", "$case": "target.prod.kind=ssh"}` and usable only inside that case. The manifest records `{select, discriminator, cases}`; the service resolves it per run from the pinned config snapshot (`when` is per run input). The same step name may appear in several cases (same output model; not two different custom steps, since handlers pair by name); a step every case has is definitely available afterwards, one only some have is maybe-available. The harness picks the variant of a same-named step from `OLVE_CASES` (a JSON array of the case conditions the step sits in, set by the service).
 - **Failure handlers.** `.onFailure(handler, { steps? })` takes a step whose inputs are all `FailureContext`. When a run fails, the service runs each handler whose scope (default: any step) contains a failed step, once per failure: `run <handler>` in the handler's image with its declared secrets, from the run's pinned binary. It is untracked and best-effort — not an attempt of the run, never retried, and its own failure triggers nothing; its log is kept at `runs/<p>/<run>/_failure/<handler>/<id>/log`. `FailureContext` carries `pipeline {id, name}`, `run {id, number, address, versionStamp, trigger, url}`, `version {number, commit}`, the run's `input`, a one-line `reason`, and `failedSteps[]` (`step, attempt, address, reason, logUrl`) — only the steps in the handler's scope, never empty.
 
 ### Testing handlers
@@ -214,7 +255,7 @@ export default pipeline({ name: "Olve.Pipelines", description: "…", input: M.D
 import { testHandler, testFileRef } from "@olivervea/pipelines/testing";
 import deployBeta from "../handlers/deploy-beta";
 
-const r = await testHandler(deployBeta, { artifact }, { secrets: { SSH_PRIVATE_KEY: "k" }, ctx: { http: fakeHttp }, run: { number: 412 } });
+const r = await testHandler(deployBeta, { artifact }, { secrets: { SSH_PRIVATE_KEY: "k" }, config: { target: { host: "h" } }, ctx: { http: fakeHttp }, run: { number: 412 } });
 expect(r).toMatchObject({ status: "succeeded", output: { release: "olve-pipelines" } });   // r.filesDir, r.logs, r.exitCode
 ```
 
@@ -242,7 +283,7 @@ This section is everything the C# side needs in order to run the binary.
 
 | Path | Who | What |
 |---|---|---|
-| `input.json` | service (via olve-init) | **run**: a JSON object with exactly the step's input keys, built from the manifest's `input` mappings. Leave out a key whose ref root step was skipped; this is allowed only for `optional` inputs. Unknown keys → exit 65. **map-trigger push**: `{"ref": "refs/heads/<branch>", "after": "<sha>", "repository": {"full_name": "<owner>/<repo>"}}` (`PushEvent`). **map-trigger poll**: `{"value": "<extracted value as string>"}`. **map-trigger webhook**: `{"headers": {…}, "body": …}` (`WebhookEvent`). |
+| `input.json` | service (via olve-init) | **run**: a JSON object with exactly the step's input keys, built from the manifest's `input` mappings. Leave out a key whose ref root step was skipped; this is allowed only for `optional` inputs. Unknown keys → exit 65. For a step with `configEntries`, the reserved key `"$config"` holds `{ <entry>: <value> }` from the run's config (entries that are not set are left out); each entry is parsed with its schema, and a missing required entry or an invalid value → exit 65 (`config.<entry>…`). Other steps ignore `$config`. **map-trigger push**: `{"ref": "refs/heads/<branch>", "after": "<sha>", "repository": {"full_name": "<owner>/<repo>"}}` (`PushEvent`). **map-trigger poll**: `{"value": "<extracted value as string>"}`. **map-trigger webhook**: `{"headers": {…}, "body": …}` (`WebhookEvent`). |
 | `work/output.json` | harness | The envelope. Any stale copy is deleted at start, and the new file is written atomically. |
 | `work/files/<object path>` | harness | Output files and directory tars (see "File references"). |
 | `tmp/` | harness | Scratch space. Point `TMPDIR` here. |
@@ -259,6 +300,7 @@ This section is everything the C# side needs in order to run the binary.
 | `OLVE_RUN` | run | Run number (integer ≥ 0). Written into produced file refs. Default 0. |
 | `OLVE_ATTEMPT` | run | Attempt number (integer ≥ 1). Written into produced file refs. Default 1. |
 | `OLVE_VERSION_STAMP` | run | Derived version, e.g. `2026.10.21.412` → `ctx.run.version`. |
+| `OLVE_CASES` | run | Only for a step inside a `select`: a JSON array of the case conditions it sits in (`["target.prod.kind=ssh"]`); `run <step>` uses it to pick the variant of a name several cases use. |
 | `<SECRET_NAME>` | per step | Each declared secret as an env var of the **same name**: `secretKeyRef` key = name. Mount only the step's `secrets` (for poll triggers, the poll's `secrets`). Child processes inherit them. The mount is optional: an unset secret leaves the variable unset and `ctx.secrets.<NAME>` throws on access, so a handler can check `process.env.<NAME>` first and skip. |
 | `OLVE_RESULT_URL` | optional | Pre-signed **PUT** for `result.tar.gz` (see below). Unset means no upload. |
 | `OLVE_FILE_URLS` | optional | JSON object mapping file key → pre-signed **GET** URL, one entry per file ref in the input. The key is `<run>/<step>/<attempt>/<path>` (`path` exactly as in the ref, including a trailing `/` for directories). The URL points at the stored object (see the storage rule). |
@@ -293,7 +335,7 @@ For `map-trigger`, `output` is the pipeline input after it has been parsed by th
 | 0 | ok (succeeded or skipped) | yes |
 | 1 | the handler or trigger mapper threw | failed / `handler` |
 | 64 | usage: unknown mode, step or trigger | none |
-| 65 | `input.json` missing, not JSON, or invalid for the step (or event) | failed / `input` |
+| 65 | `input.json` missing, not JSON, or invalid for the step (or event), including its `$config` | failed / `input` |
 | 66 | the return value failed strict validation, or an own file ref is missing or changed | failed / `output` |
 | 74 | the `result.tar.gz` upload failed after retries. Used only when the step itself succeeded; otherwise the step's own code wins. | yes (printed) |
 | 78 | the pipeline is invalid (describe problems, or a missing or wrong handler module) | none |
@@ -327,6 +369,7 @@ Exact format: [`manifest.schema.json`](manifest.schema.json) (JSON Schema 2020-1
 - **`apiVersion`** is `"2.0"`.
 - **`harness`** is `{ bun, sdk, sdkHash }`.
 - **`models[name]`** is `{ output, input? }`.
+- **Step `kind`** is `custom` or the library step's name (`imageBuild`, `composeDeploy`, …). To the service it is a label: any non-empty kind is accepted, so a new library step needs no service change.
   - `output` is the `z.output` view, with `additionalProperties: false` on every object. It validates outputs, the pool and trigger results.
   - `input` is the `z.input` view (defaults optional). Use it for trigger forms and manual input. It is emitted only when it differs from `output` beyond `additionalProperties`.
 - **Step `input`** maps each input key to a mapping:
@@ -336,7 +379,7 @@ Exact format: [`manifest.schema.json`](manifest.schema.json) (JSON Schema 2020-1
 
   An object whose only key is `ref` (with a string value) or `const` is a tag. Describe never emits a nested object with exactly that key set. Model-matched inputs are emitted already resolved (`{"ref": "build"}`).
 - **`inputTypes`** declares each input key: `{model, optional}`, or `{schema: {output, input?}}` for a plain schema.
-- **`handlerHash`** is the step's implementation identity. A step version can be computed from image + `inputTypes`/model versions + `output` model version + `secrets` + `input` mappings + `handlerHash`. Stage placement, `when` and the step's `description` are not part of it.
+- **`handlerHash`** is the step's implementation identity. A step version can be computed from image + `inputTypes`/model versions + `output` model version + `secrets` + `configEntries` (and those entries' schemas) + `input` mappings + `handlerHash`. Stage placement, `when` and the step's `description` are not part of it.
   - Custom steps: `sha256(canonical {bundle, harness})`. `bundle` hashes the handler bundled on its own, with `pipeline.ts`, `models.ts` and `@olivervea/pipelines` external. It is tree-shaken and includes embedded scripts, so it changes only when that handler's code (or code it uses) changes.
   - Library steps: `sha256(canonical {library: kind, config, harness})`.
   - Because `harness` is part of both hashes, a Bun or SDK bump changes every handler.
@@ -347,6 +390,8 @@ Exact format: [`manifest.schema.json`](manifest.schema.json) (JSON Schema 2020-1
   - `{kind: "webhook", name, verify: {scheme: "hmac-sha256", secret, header, prefix} | {scheme: "bearer", secret}}`. The `map-trigger` event is `{headers, body}`; a `null` mapping yields a `skipped` envelope (the delivery is ignored).
 - **`failureHandlers`** is a list of `{step: Step, steps: [names] | null}`. Each handler's inputs are all FailureContext (`{"ref": "failure"}`).
 - **`secrets`** lists every secret used by steps, polls and webhooks, sorted, as `{name, description}`.
+- **`config`** lists every config entry steps declare, sorted by name, as `{name, description, required, schema}`. `schema` is the `z.input` view (defaults listed); it validates the entry's value in the config document. `required` is false when the schema accepts a missing value. A `secretRef` field is marked `"x-olve-kind": "secretRef"`, with the secret's name as `properties.secret.const`. Omitted when there are no entries.
+- **Step `configEntries`** names the entries the step receives (sorted; omitted when none). It is part of the step's content, like `secrets`. The step key `config` is the library-step configuration.
 
 Describe runs these checks; reconcile should re-run the manifest-level ones:
 
@@ -358,6 +403,7 @@ Describe runs these checks; reconcile should re-run the manifest-level ones:
 - `when` on an unknown or non-literal field, or with an invalid value;
 - a poll header referencing an undeclared secret, duplicate triggers;
 - conflicting secret descriptions;
+- config names, one description and schema per config name, a step receiving a `secretRef` without declaring its secret, and input keys starting with `$` (reserved);
 - an `onFailure` scope naming an unknown step, and failure-handler inputs.
 
 ## Build tool
@@ -372,8 +418,8 @@ olve-build <pipelineDir> --hash-only          # print handler hashes (diagnostic
 3. Run `bun build --compile --target=bun-linux-x64 --no-compile-autoload-dotenv --no-compile-autoload-bunfig --bytecode --format=esm` → `<out>/step`. The output is never minified, because mapper source analysis needs real source.
 4. Check that `PT_INTERP` is `/lib64/ld-linux-x86-64.so.2`. On alpine, Bun silently produces a musl binary; the check fails it.
 5. Run `<out>/step describe` → `<out>/manifest.json`. A describe problem is a build failure with exit 78. **A custom step without a handler file is an error.**
-6. Write `<out>/step.tar.gz` (deterministic, `step` at the root, mode 0755) and `<out>/build.json` (diagnostics).
-7. With `--upload-url`, PUT `step.tar.gz`, using the same retry rules as the result upload. With `--sentinels`, print the manifest between the manifest sentinels.
+6. Write `<out>/step.tar.zst` (a deterministic tar, `step` at the root, mode 0755, zstd level 3: it unpacks in the step pod far faster than gzip; harness-base also still unpacks the gzip archives of older SDKs; from 2.0.0-beta.7 the SDK needs an instance whose harness-base unpacks zstd, i.e. one deployed on or after 2026-10-25) and `<out>/build.json` (diagnostics).
+7. With `--upload-url`, PUT `step.tar.zst`, using the same retry rules as the result upload. With `--sentinels`, print the manifest between the manifest sentinels.
 
 Exit codes: 0 ok, 1 build failure, 64 usage, 78 pipeline invalid.
 
@@ -389,7 +435,7 @@ From npm, nothing else is needed. A local `file:`/`link:` dependency (`"@oliverv
 
 The repo depends on the SDK as a normal package. It resolves through `exports` (`@olivervea/pipelines`, `@olivervea/pipelines/harness`, `@olivervea/pipelines/testing`), and the tests cover this with a `file:` install. `bun` must be on `PATH`, because the bins use `#!/usr/bin/env bun`. A consumer `tsconfig.json` has to include the dot-directory explicitly (`"include": [".pipelines/**/*.ts"]`), and should exclude `.pipelines/.olve`.
 
-How the service runs it (reconcile, `BuildJobBuilder`): one Job per (pipeline, config commit), named `olve-build-<pipeline12>-<sha12>`. The repo tarball comes from `codeload.github.com/<repo>/tar.gz/<sha>` anonymously (public repos), or from the GitHub API tarball endpoint with the binding's credentials key from the pipeline Secret. The binary is PUT to `versions/<pipeline>/builds/<sha>/step.tar.gz`, and a version added from that build keeps this key as its `BinaryKey`. The in-repo fixture `.pipelines-test/` (bound on v2 beta) uses exactly this layout.
+How the service runs it (reconcile, `BuildJobBuilder`): one Job per (pipeline, config commit), named `olve-build-<pipeline12>-<sha12>`. The repo tarball comes from `codeload.github.com/<repo>/tar.gz/<sha>` anonymously (public repos), or from the GitHub API tarball endpoint with the binding's credentials key from the pipeline Secret. The archive is PUT to `versions/<pipeline>/builds/<sha>/step.tar.gz` (the key predates zstd; the init container tells the formats apart by content), and a version added from that build keeps this key as its `BinaryKey`. The in-repo fixture `.pipelines-test/` (bound on v2 beta) uses exactly this layout.
 
 The manifest is the text between the sentinels in the pod log. The manifest text is identical across checkouts. The binary and archive bytes are identical for the same checkout layout.
 
@@ -397,11 +443,11 @@ The manifest is the text between the sentinels in the pod log. The manifest text
 
 ```
 olve-dev describe <dir> [--sentinels]                     # same bytes as the compiled binary's describe
-olve-dev run <dir> <step> [--input-file f] [--olve-dir d] [--secret NAME=value]...
+olve-dev run <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--secret NAME=value]...
 olve-dev map-trigger <dir> <trigger> --event-file f [--olve-dir d]
 ```
 
-`olve-dev` runs handlers from source, through the same validation path as the binary. `$OLVE_DIR` defaults to `<dir>/.olve`, and outputs land in `<dir>/.olve/work/`. Set `OLVE_FILES_DIR` to a local pool to fetch file refs.
+`olve-dev` runs handlers from source, through the same validation path as the binary. `$OLVE_DIR` defaults to `<dir>/.olve`, and outputs land in `<dir>/.olve/work/`. Set `OLVE_FILES_DIR` to a local pool to fetch file refs. `--config-file` (a JSON object of config entries) becomes the input's `$config`.
 
 ## Development
 

package/manifest.schema.json

@@ -47,6 +47,42 @@
           "const": "2.0",
           "type": "string"
         },
+        "config": {
+          "description": "Config entries used by steps, sorted by name (omitted when none). Fields of kind secretRef ({secret: NAME}) name a secret.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "description": {
+                "type": "string"
+              },
+              "name": {
+                "description": "Config entry name; a key of the pipeline's config document.",
+                "pattern": "^[a-z][a-zA-Z0-9]*$",
+                "type": "string"
+              },
+              "required": {
+                "description": "False when the schema accepts a missing value (optional, or a default).",
+                "type": "boolean"
+              },
+              "schema": {
+                "additionalProperties": {},
+                "description": "z.input view: validates the config document's value for this entry (defaults listed).",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "type": "object"
+              }
+            },
+            "required": [
+              "name",
+              "description",
+              "required",
+              "schema"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
         "description": {
           "type": "string"
         },
@@ -297,22 +333,70 @@
             "stages"
           ],
           "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "cases": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "#/$defs/Stage"
+                },
+                "type": "array"
+              },
+              "description": "Discriminator value → stages. Exactly one case runs; a step name may repeat across cases, nowhere else.",
+              "propertyNames": {
+                "type": "string"
+              },
+              "type": "object"
+            },
+            "discriminator": {
+              "description": "The union's literal field whose value names the case.",
+              "minLength": 1,
+              "type": "string"
+            },
+            "select": {
+              "description": "Config reference (`<entry>.<field>…`) to a discriminated union; the run's config snapshot picks the case.",
+              "minLength": 1,
+              "type": "string"
+            }
+          },
+          "required": [
+            "select",
+            "discriminator",
+            "cases"
+          ],
+          "type": "object"
         }
       ]
     },
     "Step": {
       "additionalProperties": false,
       "properties": {
+        "clusterAccess": {
+          "const": true,
+          "description": "The step pod gets the instance's step ServiceAccount token (Kubernetes:StepServiceAccount), if the instance grants one. Omitted = no token.",
+          "type": "boolean"
+        },
         "config": {
           "additionalProperties": {
             "$ref": "#/$defs/Json"
           },
-          "description": "Library-step configuration (display only; already covered by handlerHash).",
+          "description": "Library-step configuration (display only; already covered by handlerHash). A config reference is recorded as {\"$config\": \"<entry>.<field>…\"}; the entry is in configEntries.",
           "propertyNames": {
             "type": "string"
           },
           "type": "object"
         },
+        "configEntries": {
+          "description": "Config entries the step receives (sorted; omitted when none). The service delivers them in input.json under '$config'.",
+          "items": {
+            "description": "Config entry name; a key of the pipeline's config document.",
+            "pattern": "^[a-z][a-zA-Z0-9]*$",
+            "type": "string"
+          },
+          "type": "array"
+        },
         "description": {
           "description": "What the step does, shown in the UI (may be empty).",
           "type": "string"
@@ -348,14 +432,8 @@
           "type": "object"
         },
         "kind": {
-          "description": "'custom' = handlers/<name>.ts; others are SDK library steps.",
-          "enum": [
-            "custom",
-            "script",
-            "gitHubSource",
-            "imageBuild",
-            "helmDeployOverSsh"
-          ],
+          "description": "'custom' = handlers/<name>.ts; others are SDK library steps. A label: the service accepts any kind.",
+          "minLength": 1,
           "type": "string"
         },
         "name": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olivervea/pipelines",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.7",
   "description": "Olve.Pipelines v2 SDK: typed pipeline authoring, the step harness, and the build tool.",
   "type": "module",
   "license": "MIT",

package/src/build/build.ts

@@ -1,10 +1,10 @@
-// olve-build: pipeline dir → single executable + step.tar.gz + manifest.json.
+// olve-build: pipeline dir → single executable + step.tar.zst + manifest.json.
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { canonicalJson } from "../util/canonical.ts";
 import { sha256File } from "../util/hash.ts";
 import type { HarnessInfo } from "../util/handler-hash.ts";
-import { writeTarGz } from "../util/tar.ts";
+import { writeTarZst } from "../util/tar.ts";
 import { MANIFEST_BEGIN, MANIFEST_END, uploadFile } from "../harness/result.ts";
 import { GLIBC_INTERP, MUSL_INTERP, readInterpreter } from "./elf.ts";
 import { handlerHashes, type HandlerHash } from "./hashes.ts";
@@ -23,7 +23,7 @@ export class BuildError extends Error {
 export interface BuildOptions {
   out: string;
   target?: Target;
-  /** Pre-signed PUT for step.tar.gz. */
+  /** Pre-signed PUT for the step archive. */
   uploadUrl?: string;
   /** Print the manifest between sentinels on stdout (for the build Job's pod log). */
   sentinels?: boolean;
@@ -107,9 +107,9 @@ export async function build(dir: string, opts: BuildOptions): Promise<BuildResul
   const manifestFile = join(out, "manifest.json");
   writeFileSync(manifestFile, manifest);
 
-  // 4. step.tar.gz (deterministic: `step` at the root, 0755, mtime 0)
-  const archive = join(out, "step.tar.gz");
-  await writeTarGz(archive, [{ path: "step", type: "file", mode: 0o755, source: binary }]);
+  // 4. step.tar.zst (deterministic: `step` at the root, 0755, mtime 0)
+  const archive = join(out, "step.tar.zst");
+  await writeTarZst(archive, [{ path: "step", type: "file", mode: 0o755, source: binary }]);
   writeFileSync(
     join(out, "build.json"),
     canonicalJson({ target, flags: BUILD_FLAGS, harness, handlers: hashes, binarySha256: sha256File(binary), archiveSha256: sha256File(archive) }),
@@ -118,7 +118,7 @@ export async function build(dir: string, opts: BuildOptions): Promise<BuildResul
 
   if (opts.uploadUrl) {
     await uploadFile(opts.uploadUrl, archive, log);
-    log("olve-build: uploaded step.tar.gz");
+    log("olve-build: uploaded step.tar.zst");
   }
   if (opts.sentinels) await stdout(`${MANIFEST_BEGIN}\n${manifest}${MANIFEST_END}\n`);
   return { binary, archive, manifestFile, manifest, hashes, harness };

package/src/builder/pipeline.ts

@@ -8,6 +8,7 @@ import type { IsUnion, OrError, Simplify } from "../core/types.ts";
 import type { Optional } from "../core/models.ts";
 import type { FailureContext } from "../library/models.ts";
 import type { MapperResult, Ref } from "./refs.ts";
+import { isConfigRef, narrowConfigRef, unionAt, type ConfigNode, type ConfigRef, type DiscriminatorOf, type VariantOf } from "../core/config.ts";
 
 // ─── Availability (builder state, type level) ────────────────────────────────────────────────
 
@@ -96,6 +97,29 @@ type OutputsOf<E extends readonly unknown[], Maybe extends boolean> = {
 };
 type MakeMaybe<X extends AvailMap> = { [K in keyof X]: Slot<X[K]["model"], X[K]["value"], true> };
 
+// ─── select (branching on config) ────────────────────────────────────────────────────────────
+
+type KeysOfUnion<T> = T extends unknown ? keyof T : never;
+type SlotIn<B, K extends PropertyKey> = B extends { [P in K]: infer X extends Slot } ? X : never;
+/** A case function: the pipeline so far, and the select's reference narrowed to the case's variant. */
+export type SelectCase<In extends AnyModel, A extends AvailMap, R> = (p: Pipeline<In, A>, ref: R) => Pipeline<In, AvailMap>;
+export type SelectCases<In extends AnyModel, A extends AvailMap, U, D extends string> = {
+  readonly [V in Extract<U[D & keyof U], string>]: SelectCase<In, A, ConfigNode<VariantOf<U, D, V>>>;
+};
+type CaseAvail<C> = { [K in keyof C]: C[K] extends (...args: never[]) => Pipeline<AnyModel, infer B> ? B : never }[keyof C];
+/**
+ * After a select: a step every case has is as available as in its cases (one case always runs);
+ * a step only some cases have is maybe-available.
+ */
+export type AfterSelect<A extends AvailMap, B> = Simplify<
+  A &
+    { [K in Exclude<keyof B, keyof A>]: Slot<SlotIn<B, K>["model"], SlotIn<B, K>["value"], SlotIn<B, K>["maybe"]> } &
+    { [K in Exclude<KeysOfUnion<B>, keyof B | keyof A>]: Slot<SlotIn<B, K>["model"], SlotIn<B, K>["value"], true> }
+>;
+type SelectOnError<U> = [DiscriminatorOf<U>] extends [never]
+  ? "❌ select needs a reference to a discriminated union in config (z.discriminatedUnion)"
+  : IsUnion<DiscriminatorOf<U>> extends true ? "❌ the union has more than one literal field; select can't tell which is the discriminator" : never;
+
 // ─── Conditions / triggers ───────────────────────────────────────────────────────────────────
 
 type IsLiteralLike<T> = [T] extends [string | number | boolean]
@@ -134,7 +158,8 @@ export interface StageStepNode {
 }
 export type StageNode =
   | { readonly kind: "stage"; readonly steps: readonly StageStepNode[] }
-  | { readonly kind: "when"; readonly cond: Readonly<Record<string, unknown>>; readonly nodes: readonly StageNode[] };
+  | { readonly kind: "when"; readonly cond: Readonly<Record<string, unknown>>; readonly nodes: readonly StageNode[] }
+  | { readonly kind: "select"; readonly on: ConfigRef; readonly cases: Readonly<Record<string, readonly StageNode[]>> };
 
 export type TriggerNode =
   | { readonly kind: "push"; readonly name: string; readonly map: (event: unknown) => unknown }
@@ -300,6 +325,34 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     return this.next();
   }
 
+  /**
+   * Branch on config: `on` references a discriminated union in a config entry, and each case gets the
+   * pipeline and `on` narrowed to its variant. Exactly one case runs, chosen by the run's config
+   * snapshot (not by run input; that is `when`). The same step name may appear in several cases.
+   */
+  select<U, const C extends SelectCases<In, A, U, DiscriminatorOf<U>>>(
+    on: ConfigRef<U> & ([SelectOnError<U>] extends [never] ? unknown : SelectOnError<U>),
+    cases: C & { readonly [K in Exclude<keyof C, keyof SelectCases<In, A, U, DiscriminatorOf<U>>>]: `❌ '${K & string}' is not a case of this select` },
+  ): Pipeline<In, AfterSelect<A, CaseAvail<C>>> {
+    const data = this[PIPELINE];
+    const recorded: Record<string, StageNode[]> = {};
+    const union = isConfigRef(on) ? unionAt(on) : undefined;
+    if (!union) data.problems.push("select: the first argument must reference a z.discriminatedUnion in a config entry");
+    for (const [value, fn] of Object.entries(cases as Record<string, unknown>)) {
+      if (typeof fn !== "function") {
+        data.problems.push(`select: case '${value}' is not a function`);
+        continue;
+      }
+      const inner = new Pipeline<In, A>({ name: data.name, input: data.input as In }, data);
+      const returned = (fn as (p: unknown, ref: unknown) => unknown)(inner, union ? narrowConfigRef(on, union.discriminator, value) : on);
+      if (!isPipeline(returned) || pipelineData(returned) !== inner[PIPELINE])
+        data.problems.push(`select: case '${value}' must return the pipeline it was given ((p, ref) => p.stage(...))`);
+      recorded[value] = inner[PIPELINE].nodes;
+    }
+    data.nodes.push({ kind: "select", on, cases: recorded });
+    return this.next();
+  }
+
   /** Run `handler` (a step whose inputs are all FailureContext) when one of `steps` (default: any) fails. Untracked, best-effort. */
   onFailure<S extends AnyStep>(
     handler: S &
@@ -307,7 +360,7 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
         ? unknown
         : "❌ a failure handler's inputs must all be FailureContext"),
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    opts?: { steps?: readonly Step<StepNames<A>, any, any, any>[] },
+    opts?: { steps?: readonly Step<StepNames<A>, any, any, any, any>[] },
   ): this {
     this[PIPELINE].failureHandlers.push({ step: handler as AnyStep, steps: opts?.steps ? [...(opts.steps as readonly AnyStep[])] : null });
     return this.next();

package/src/core/config-refs.ts

@@ -0,0 +1,77 @@
+// Config references inside library-step definitions: collected (the step receives their entries),
+// recorded in the manifest as `{"$config": "<entry>.<path>"}`, and resolved from ctx.config at run time.
+import { configRefPath, configRefTarget, isConfigRef, type AnyConfigEntry, type ConfigRef } from "./config.ts";
+
+/** `T` with every config reference replaced by the type of its value. */
+export type Resolved<T> = T extends ConfigRef<infer U>
+  ? U
+  : T extends readonly (infer E)[]
+    ? Resolved<E>[]
+    : T extends (...args: never[]) => unknown
+      ? T
+      : T extends object
+        ? { [K in keyof T]: Resolved<T[K]> }
+        : T;
+
+/** Manifest key of a recorded config reference. */
+export const CONFIG_REF_KEY = "$config";
+/** Beside it on a reference narrowed by a `select` case: the case's condition, `<ref>.<discriminator>=<value>`. */
+export const CONFIG_CASE_KEY = "$case";
+
+function isPlain(v: unknown): v is Record<string, unknown> {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+
+/** Every config entry referenced anywhere in `v` (plain objects and arrays only), by name. */
+export function configRefsIn(v: unknown, into = new Map<string, AnyConfigEntry>()): AnyConfigEntry[] {
+  if (isConfigRef(v)) {
+    const { entry } = configRefTarget(v);
+    if (!into.has(entry.name)) into.set(entry.name, entry);
+  } else if (Array.isArray(v)) for (const x of v) configRefsIn(x, into);
+  else if (isPlain(v)) for (const x of Object.values(v)) configRefsIn(x, into);
+  return [...into.values()];
+}
+
+/** `v` as manifest JSON: references become `{"$config": "target.beta.host"}`; literal keys starting with `$` are reserved. */
+export function recordConfigRefs(v: unknown): unknown {
+  if (isConfigRef(v)) {
+    const { path, case: kase } = configRefTarget(v);
+    for (const seg of path) if (seg === "" || seg.includes(".")) throw new Error(`config reference '${configRefPath(v)}': field names must not be empty or contain '.'`);
+    return { [CONFIG_REF_KEY]: configRefPath(v), ...(kase ? { [CONFIG_CASE_KEY]: kase } : {}) };
+  }
+  if (Array.isArray(v)) return v.map(recordConfigRefs);
+  if (isPlain(v)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, x] of Object.entries(v)) {
+      if (k.startsWith("$")) throw new Error(`key '${k}': keys starting with '$' are reserved`);
+      out[k] = recordConfigRefs(x);
+    }
+    return out;
+  }
+  return v;
+}
+
+/** `v` with every reference replaced by its value in `config` (the step's parsed config entries). */
+export function resolveConfigRefs<T>(v: T, config: Readonly<Record<string, unknown>>): Resolved<T> {
+  if (isConfigRef(v)) {
+    const { entry, path } = configRefTarget(v);
+    if (!Object.hasOwn(config, entry.name)) throw new Error(`config entry '${entry.name}' was not delivered to the step`);
+    let cur: unknown = config[entry.name];
+    for (const seg of path) cur = cur !== null && typeof cur === "object" ? (cur as Record<string, unknown>)[seg] : undefined;
+    return cur as Resolved<T>;
+  }
+  if (Array.isArray(v)) return v.map((x) => resolveConfigRefs(x, config)) as Resolved<T>;
+  if (isPlain(v)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, x] of Object.entries(v)) out[k] = resolveConfigRefs(x, config);
+    return out as Resolved<T>;
+  }
+  return v as Resolved<T>;
+}
+
+/** Literal `v` (no reference inside), so define-time checks can run on it. */
+export function isLiteral(v: unknown): boolean {
+  return configRefsIn(v).length === 0;
+}