@olivervea/pipelines 2.0.0-beta.29 → 2.0.0-beta.30

package/README.md

@@ -79,7 +79,7 @@ export const deployBeta = step({
   name: "deploy-beta",                         // identity: lower-case kebab, ≤ 63 chars
   description: "Deploys to beta.",             // required (may be ""); shown in the UI, not versioned
   image: "alpine:latest",                      // any image; the harness brings its own runtime
-  input: { artifact: BuildArtifact },          // model | optional(model) | plain zod schema | external(model, …)
+  input: { artifact: BuildArtifact },          // model | optional(model) | cells(model) | plain zod schema | external(model, …)
   output: BetaDeployment,                      // a model, or omitted (no output)
   secrets: [SSH_PRIVATE_KEY],                  // only these are mounted; ctx.secrets is typed to them
   timeoutSeconds: 900,                         // optional
@@ -96,6 +96,7 @@ Rules:
 - **Trigger mappers** produce `z.input`, so fields with defaults may be left out. **Handlers, mapper refs and `when`** see `z.output`.
 - 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.
+- **`cells(M)`** reads every cell of a matrix step whose output is `M` (see "Matrix steps").
 - **`external(M, { title, description?, from? })`** is answered from outside the run; `from` lists `callback()` (another system POSTs to the URL an earlier step gets from `ctx.inputUrl(step, input)`), `poll({ url, valuePath, intervalSeconds? })` and `person()` (the default). It needs no producer and no mapper entry; the step waits until it is answered, then the value (validated against `M`) is in its input like any other. Failure handlers can't have one.
 
 ### Config
@@ -192,6 +193,37 @@ export function smokeTest<const N extends string>(def: { name: LiteralName<N>; d
 - **`settings`**: what the step was set up with, recorded as the step's manifest `config` (so part of its version). JSON values and config references; the step receives every entry its settings reference.
 - `implement` refuses a step that already carries an implementation.
 
+### Matrix steps
+
+```ts
+import { cascadeFailure, cells, implement, step } from "@olivervea/pipelines";
+
+export const buildCli = implement(step({
+  name: "build-cli", description: "", image: "oven/bun:1.4.3-slim",
+  input: { source: Source }, output: BuiltBinary,
+  matrix: {
+    axes: { os: ["linux", "windows", "macos"], arch: ["x64", "arm64"] },   // key order is the axis order
+    exclude: [{ os: "windows", arch: "arm64" }],                          // names one or more axes
+    failure: cascadeFailure(),                                            // default keepRunning()
+    maxParallel: 2,                                                       // optional
+  },
+}), async ({ source }, ctx) => {
+  const { os, arch } = ctx.cell;          // { os: "linux" | "windows" | "macos"; arch: "x64" | "arm64" }
+  // …
+});
+
+export const publish = implement(step({
+  name: "publish", description: "", image: "alpine", input: { binaries: cells(BuiltBinary) },
+}), async ({ binaries }) => { for (const { cell, output } of binaries) { /* … */ } });
+```
+
+- **Cells.** The step runs once per cell: the cross product of the axes (first axis outermost) minus the excludes. 1 to 4 axes, 1 to 64 cells. An axis name matches `^[a-z][a-zA-Z0-9]{0,30}$`, a value `^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$`, values unique per axis. Exclude keys and values are type-checked against the axes.
+- **`ctx.cell`** is the cell, typed from the axes' literals. It exists only on a matrix step's ctx.
+- **A cell's name** is `build-cli[os=linux,arch=x64]`: `ctx.run.step` and the `step` of the cell's file references hold it.
+- **Failure.** `keepRunning()` lets every cell run to the end; `cascadeFailure()` cancels the cells still running or waiting once a cell has failed its last allowed attempt.
+- **Reading a matrix step.** A later step reads it only through `cells(M)`, matched by model like other inputs or wired whole with a mapper (`[publish, from => ({ binaries: from["build-cli"] })]`; a field of a matrix step is a type error). The value is `{ cell, output }[]` in cell order, one entry per cell with an output; `cell` is `Readonly<Record<string, string>>`. A matrix step can't be read as one output, and a matrix step inside a `when` can't be read by `cells` (it may be skipped).
+- **Failure handlers** can't be matrix steps.
+
 ### Handlers
 
 ```ts
@@ -219,7 +251,8 @@ export const deployBeta = implement(step({ name: "deploy-beta", /* … */ }), as
 | `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). |
+| `run` | `{ pipeline, id, number, attempt, step, version }` (from the env, see below). For a matrix step `step` is the cell's name. |
+| `cell` | Matrix steps only: the cell being run, in axis order (from `OLVE_CELL`). |
 | `tmpDir` | A writable scratch directory (`$OLVE_DIR/tmp`). Kaniko has no `/tmp`. |
 | `skip(reason)` | Produce no output (prefer `when`). |
 
@@ -257,6 +290,8 @@ const r = await testHandler(deployBeta, { artifact }, { secrets: { SSH_PRIVATE_K
 expect(r).toMatchObject({ status: "succeeded", output: { release: "olve-pipelines" } });   // r.filesDir, r.logs, r.exitCode
 ```
 
+A matrix step takes the cell to run: `testHandler(buildCli, { source }, { cell: { os: "linux", arch: "x64" } })`; without one it fails with `kind: "input"` and exit code 65, like a pod without `OLVE_CELL`.
+
 `testHandler` uses the same validation path as a real run. Invalid input gives `status: "failed"` with `kind: "input"`; an invalid return value gives `kind: "output"`. Any part of `ctx` can be replaced; whatever you don't replace is the real implementation. `testHandler` takes any implementation: a custom step, a library step or a reusable step.
 
 ## Harness contract (service ⇄ step binary)
@@ -272,7 +307,7 @@ This section is everything the C# side needs in order to run the binary.
 | Mode | Reads | Writes | Notes |
 |---|---|---|---|
 | `describe [--sentinels]` | the binary itself | stdout: the manifest (canonical JSON) | With `--sentinels`, stdout gets the manifest between `---OLVE-MANIFEST-BEGIN---` and `---OLVE-MANIFEST-END---`. Needs no env and no files. |
-| `run <step>` | `$OLVE_DIR/input.json` | `$OLVE_DIR/work/output.json`, `$OLVE_DIR/work/files/…` | Steps in stages and failure-handler steps. |
+| `run <step>` | `$OLVE_DIR/input.json` | `$OLVE_DIR/work/output.json`, `$OLVE_DIR/work/files/…` | Steps in stages and failure-handler steps. A matrix step's cell runs as `run <step>` (the step's own name) with `OLVE_CELL`. |
 | `map-trigger <trigger>` | `$OLVE_DIR/input.json` (the event) | `$OLVE_DIR/work/output.json` | `<trigger>` is the trigger's `name` from the manifest. |
 
 `run` and `map-trigger` also print the envelope on stdout, as one compact JSON line between `---OLVE-RESULT-BEGIN---` and `---OLVE-RESULT-END---`. The block always comes last. Use it as a fallback channel from the pod log. User output and stderr logs also go to the pod log, so never parse anything outside the sentinels.
@@ -281,7 +316,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. 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`). |
+| `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`. A `cells` input is a list in cell order, one entry per cell whose latest successful attempt has an output: `[{"cell": {"os": "linux", "arch": "x64"}, "output": {…}}, …]`. **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. |
@@ -298,6 +333,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_CELL` | run | Only for a matrix step: the cell, as compact JSON in axis order (`{"os":"linux","arch":"x64"}`) → `ctx.cell`. Missing, or not one of the step's cells → exit 65. `ctx.run.step` and produced file refs carry the cell's name, `build-cli[os=linux,arch=x64]`. |
 | `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. |
@@ -336,7 +372,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), including its `$config` | failed / `input` |
+| 65 | `input.json` missing, not JSON, or invalid for the step (or event), including its `$config`; a matrix step's `OLVE_CELL` missing or not one of its cells | 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 step without an implementation) | none |
@@ -357,6 +393,8 @@ The service unpacks the archive into `runs/<p>/<run>/<step>/<attempt>/`.
 { "run": 412, "step": "build", "attempt": 1, "path": "chart/", "sha256": "<64 hex>" }
 ```
 
+- `step` is the step's name, or a matrix cell's name (`build-cli[os=linux,arch=x64]`).
+
 - In JSON Schema, a reference is marked `"x-olve-kind": "fileRef"`.
 - `path` is relative, with no `.`/`..` segments, no `\`, no NUL and no leading `/`. The pattern is in the schema. A **trailing `/` means a directory**.
 - **Storage rule:** the object path is `path` for files. For directories, it is `path` without the trailing `/`, plus `.tar`: `chart/` → `chart.tar`, an uncompressed deterministic tar.
@@ -365,7 +403,7 @@ The service unpacks the archive into `runs/<p>/<run>/<step>/<attempt>/`.
 
 ## Manifest
 
-Exact format: [`manifest.schema.json`](manifest.schema.json) (JSON Schema 2020-12, `$defs` `Manifest`, `Step`, `Stage`, `Mapping`, `Trigger`, `InputType`, `ModelSchemas`). The text is canonical JSON: sorted keys, 2-space indent, a trailing newline, and no `$schema` in the model schemas. Hash the text as printed.
+Exact format: [`manifest.schema.json`](manifest.schema.json) (JSON Schema 2020-12, `$defs` `Manifest`, `Step`, `Stage`, `Mapping`, `Trigger`, `InputType`, `ModelSchemas`, `Matrix`). The text is canonical JSON: sorted keys, 2-space indent, a trailing newline, and no `$schema` in the model schemas. Hash the text as printed.
 
 - **`apiVersion`** is `"2.0"`.
 - **`harness`** is `{ bun, sdk, sdkHash }`.
@@ -380,7 +418,8 @@ 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"}`).
 - **Step `externalInputs`** (when present) maps each external input key to `{model, title, description, from}`, `from` being `{kind: "person"}`, `{kind: "callback"}` or `{kind: "poll", url, valuePath, intervalSeconds}`. Those keys are not in `input` or `inputTypes`; the service merges the answers into `input.json`.
-- **`inputTypes`** declares each input key: `{model, optional}`, or `{schema: {output, input?}}` for a plain schema.
+- **`inputTypes`** declares each input key: `{model, optional}`, `{model, optional: false, cells: true}` for a `cells` input (mapped with a whole-step ref to a matrix step whose output is that model), or `{schema: {output, input?}}` for a plain schema.
+- **Step `matrix`** (matrix steps only, never a failure handler) is `{axes: [{name, values}…], exclude?: [{axis: value…}…], failure: {kind: "keepRunning" | "cascadeFailure"}, maxParallel?}`. `axes` is a list because canonical JSON sorts keys; `exclude` is omitted when empty; `failure.kind` is always written. All of it is part of what the step declares.
 - **`codeHash`** is the build's identity: `sha256(canonical {bundle, harness})`. `bundle` hashes the entry point bundled with everything it imports, with `@olivervea/pipelines` external. It is tree-shaken and includes embedded scripts and dependencies, so any change to code in use changes it, and with it the manifest, which makes a new pipeline version. A step version covers what the step declares: image, `inputTypes`/model versions, `output` model version, `secrets`, `configEntries` (and those entries' schemas), `input` mappings and `config`.
 - **`stages`** is an array whose items are either `{steps: [Step…]}` (parallel, with a barrier) or `{when: {field: [values]}, stages: [...]}`.
 - **`triggers`**:
@@ -404,7 +443,8 @@ Describe runs these checks; reconcile should re-run the manifest-level ones:
 - 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.
+- an `onFailure` scope naming an unknown step, and failure-handler inputs;
+- a matrix's axes, values, excludes, cell count, failure strategy and `maxParallel`, a matrix failure handler, and reading a matrix step other than whole through a `cells` input (or a `cells` input reading anything else).
 
 ## Build tool
 
@@ -447,7 +487,7 @@ olve-dev run <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--s
 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. `--config-file` (a JSON object of config entries) becomes the input's `$config`.
+`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`. A matrix step's cell comes from `OLVE_CELL` in the environment, as in the pod.
 
 ## Development
 
@@ -455,7 +495,6 @@ olve-dev map-trigger <dir> <trigger> --event-file f [--olve-dir d]
 bun install
 bunx tsc --noEmit -p .                         # type-check (TS 7)
 bun scripts/check-compile-fail.ts              # compile-fail cases (also run by bun test)
-TSC=/path/to/tsc-5.9/bin/tsc bun scripts/check-compile-fail.ts   # the other TS line
 bun test                                       # runtime + build/e2e tests
 bun scripts/gen-manifest-schema.ts             # after changing src/describe/manifest-schema.ts
 ```

package/manifest.schema.json

@@ -5,6 +5,11 @@
         {
           "additionalProperties": false,
           "properties": {
+            "cells": {
+              "const": true,
+              "description": "cells(Model): every cell of a matrix step whose output is the model, mapped with a whole-step ref; the value is [{cell, output}, …] in cell order. Omitted otherwise.",
+              "type": "boolean"
+            },
             "model": {
               "description": "Model name (key of `models`).",
               "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
@@ -284,6 +289,84 @@
         }
       ]
     },
+    "Matrix": {
+      "additionalProperties": false,
+      "description": "A matrix step runs once per cell, named '<step>[<axis>=<value>,…]' in axis order; OLVE_CELL holds the cell as compact JSON.",
+      "properties": {
+        "axes": {
+          "description": "In order: the cells are the cross product, first axis outermost, minus the excludes (1 to 64 cells).",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "name": {
+                "pattern": "^[a-z][a-zA-Z0-9]{0,30}$",
+                "type": "string"
+              },
+              "values": {
+                "description": "Unique per axis.",
+                "items": {
+                  "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$",
+                  "type": "string"
+                },
+                "minItems": 1,
+                "type": "array"
+              }
+            },
+            "required": [
+              "name",
+              "values"
+            ],
+            "type": "object"
+          },
+          "maxItems": 4,
+          "minItems": 1,
+          "type": "array"
+        },
+        "exclude": {
+          "description": "Each entry names one or more axes with one of their values; a cell matching every named axis is left out (omitted when none).",
+          "items": {
+            "additionalProperties": {
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$",
+              "type": "string"
+            },
+            "propertyNames": {
+              "pattern": "^[a-z][a-zA-Z0-9]{0,30}$",
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "failure": {
+          "additionalProperties": false,
+          "description": "keepRunning: every cell runs to the end. cascadeFailure: a cell whose last allowed attempt failed cancels the step's other scheduled or running cells.",
+          "properties": {
+            "kind": {
+              "enum": [
+                "keepRunning",
+                "cascadeFailure"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "type": "object"
+        },
+        "maxParallel": {
+          "description": "At most this many of the step's cells running at once in a run.",
+          "maximum": 9007199254740991,
+          "minimum": 1,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "axes",
+        "failure"
+      ],
+      "type": "object"
+    },
     "ModelSchemas": {
       "additionalProperties": false,
       "properties": {
@@ -556,6 +639,10 @@
           "minLength": 1,
           "type": "string"
         },
+        "matrix": {
+          "$ref": "#/$defs/Matrix",
+          "description": "Set on a matrix step (never on a failure handler); omitted otherwise."
+        },
         "name": {
           "description": "Step name: lower-case kebab, 1-63 chars. The step's identity.",
           "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$",

package/package.json

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

package/src/builder/pipeline.ts

@@ -1,7 +1,8 @@
 import { PIPELINE } from '../core/brands.ts';
 import type { AnyModel, Infer, InferInput, Plain } from '../core/models.ts';
 import type { Secret } from '../core/secrets.ts';
-import type { AnyStep, OutputValue, Step } from '../core/steps.ts';
+import type { AnyStep, CellOf, OutputValue, Step } from '../core/steps.ts';
+import type { Cells, CellOutput } from '../core/matrix.ts';
 import { isStep } from '../core/steps.ts';
 import type { WebhookEvent, WebhookVerify } from '../core/webhooks.ts';
 import type { IsUnion, OrError, Simplify } from '../core/types.ts';
@@ -66,15 +67,25 @@ type EntryError<
       : IsUnion<ProducersOf<A, M['name']>> extends true
         ? `❌ ${M['name']} (input '${Key}' of step '${SN}') has several producers; use a mapper to pick one`
         : never
-    : E extends AnyModel
-      ? [ProducersOf<A, E['name']>] extends [never]
-        ? `❌ ${E['name']} (input '${Key}' of step '${SN}') is not available at this stage`
-        : [DefiniteProducersOf<A, E['name']>] extends [never]
-          ? `❌ ${E['name']} (input '${Key}' of step '${SN}') is only maybe-available (produced inside a when block); declare it optional(${E['name']})`
-          : IsUnion<ProducersOf<A, E['name']>> extends true
-            ? `❌ ${E['name']} (input '${Key}' of step '${SN}') has several producers; use a mapper to pick one`
+    : E extends Cells<infer M>
+      ? [ProducersOf<A, `cells:${M['name']}`>] extends [never]
+        ? `❌ ${M['name']} (input '${Key}' of step '${SN}') has no matrix step producing it at this stage; cells() reads a matrix step`
+        : [DefiniteProducersOf<A, `cells:${M['name']}`>] extends [never]
+          ? `❌ ${M['name']} (input '${Key}' of step '${SN}') is only maybe-available (produced inside a when block); cells() cannot read a maybe-skipped matrix step`
+          : IsUnion<ProducersOf<A, `cells:${M['name']}`>> extends true
+            ? `❌ ${M['name']} (input '${Key}' of step '${SN}') has several matrix steps producing it; use a mapper to pick one`
             : never
-      : `❌ input '${Key}' of step '${SN}' is a plain schema, not a model, so it cannot be matched by model; add a mapper`;
+      : E extends AnyModel
+        ? [ProducersOf<A, E['name']>] extends [never]
+          ? [ProducersOf<A, `cells:${E['name']}`>] extends [never]
+            ? `❌ ${E['name']} (input '${Key}' of step '${SN}') is not available at this stage`
+            : `❌ ${E['name']} (input '${Key}' of step '${SN}') is produced by a matrix step; read it with cells(${E['name']})`
+          : [DefiniteProducersOf<A, E['name']>] extends [never]
+            ? `❌ ${E['name']} (input '${Key}' of step '${SN}') is only maybe-available (produced inside a when block); declare it optional(${E['name']})`
+            : IsUnion<ProducersOf<A, E['name']>> extends true
+              ? `❌ ${E['name']} (input '${Key}' of step '${SN}') has several producers; use a mapper to pick one`
+              : never
+        : `❌ input '${Key}' of step '${SN}' is a plain schema, not a model, so it cannot be matched by model; add a mapper`;
 
 type DefaultMatchError<S extends AnyStep, A extends AvailMap> = {
   [K in keyof S['input'] & string]: EntryError<S['name'], K, S['input'][K], A>;
@@ -138,12 +149,19 @@ export type CheckStage<E extends readonly unknown[], A extends AvailMap> = {
   [K in keyof E]: CheckEntry<NoInfer<E>, K, E[K], A>;
 };
 
+// A matrix step's slot holds its cells, under `cells:<model>`: only cells() inputs match it.
 type OutputsOf<E extends readonly unknown[], Maybe extends boolean> = {
-  [S in StepOfEntry<E[number]> as S['name']]: Slot<
-    S['output'] extends AnyModel ? S['output']['name'] : null,
-    OutputValue<S>,
-    Maybe
-  >;
+  [S in StepOfEntry<E[number]> as S['name']]: [CellOf<S>] extends [never]
+    ? Slot<
+        S['output'] extends AnyModel ? S['output']['name'] : null,
+        OutputValue<S>,
+        Maybe
+      >
+    : Slot<
+        S['output'] extends AnyModel ? `cells:${S['output']['name']}` : null,
+        S['output'] extends AnyModel ? CellOutput<S['output'], CellOf<S>>[] : void,
+        Maybe
+      >;
 };
 type MakeMaybe<X extends AvailMap> = {
   [K in keyof X]: Slot<X[K]['model'], X[K]['value'], true>;

package/src/core/handlers.ts

@@ -4,8 +4,15 @@ import {
   type ImplementationBrand,
   type SkippedBrand,
 } from './brands.ts';
-import type { Ctx } from '../ctx/types.ts';
-import type { AnyStep, ConfigOf, OutputValue, SecretsOf, StepInput } from './steps.ts';
+import type { StepCtx } from '../ctx/types.ts';
+import type {
+  AnyStep,
+  CellOf,
+  ConfigOf,
+  OutputValue,
+  SecretsOf,
+  StepInput,
+} from './steps.ts';
 import type { Awaitable } from './types.ts';
 
 /** Returned by `ctx.skip(reason)`: the step produced no output on purpose. */
@@ -25,9 +32,11 @@ export function isSkipped(v: unknown): v is Skipped {
 }
 
 export type HandlerResult<S extends AnyStep> = OutputValue<S> | Skipped;
+/** The ctx a handler of `S` gets. */
+export type CtxOf<S extends AnyStep> = StepCtx<SecretsOf<S>, ConfigOf<S>, CellOf<S>>;
 export type Handler<S extends AnyStep> = (
   input: StepInput<S['input']>,
-  ctx: Ctx<SecretsOf<S>, ConfigOf<S>>,
+  ctx: CtxOf<S>,
 ) => Awaitable<HandlerResult<S>>;
 
 /** A step with its handler. It is itself a step: stage it like any value. */
@@ -58,7 +67,7 @@ export function implement<S extends AnyStep, R extends HandlerResult<S>>(
       : unknown),
   handler: (
     input: StepInput<S['input']>,
-    ctx: Ctx<SecretsOf<S>, ConfigOf<S>>,
+    ctx: CtxOf<S>,
   ) => Awaitable<R & NoExtraFields<R, OutputValue<S>>>,
 ): Implementation<S> {
   if (isImplementation(step))

package/src/core/matrix.ts

@@ -0,0 +1,150 @@
+import { isModel, type AnyModel, type Infer } from './models.ts';
+import type { Simplify } from './types.ts';
+
+/** Axis name → its values, in order. Object key order is the axis order. */
+export type Axes = { readonly [axis: string]: readonly string[] };
+/** One combination of axis values. */
+export type Cell = Readonly<Record<string, string>>;
+/** The cell type of a step whose axes are `Ax`. */
+export type CellOfAxes<Ax extends Axes> = Simplify<{
+  readonly [K in keyof Ax as string extends K ? never : K]: Ax[K][number];
+}>;
+
+/** What the step's other cells do when one fails. */
+export type FailureStrategy =
+  { readonly kind: 'keepRunning' } | { readonly kind: 'cascadeFailure' };
+
+/** Every cell runs to the end (the default). */
+export function keepRunning(): FailureStrategy {
+  return Object.freeze({ kind: 'keepRunning' as const });
+}
+/** The first failed cell cancels the cells still running or waiting. */
+export function cascadeFailure(): FailureStrategy {
+  return Object.freeze({ kind: 'cascadeFailure' as const });
+}
+
+export interface MatrixDef<Ax extends Axes> {
+  /** The cells are the cross product of the axes, first axis outermost. */
+  axes: Ax;
+  /** Each entry names axes with one of their values; a cell matching all of them is left out. */
+  exclude?: readonly NoInfer<Partial<CellOfAxes<Ax>>>[];
+  /** Default `keepRunning()`. */
+  failure?: FailureStrategy;
+  /** At most this many of the step's cells running at once in a run. */
+  maxParallel?: number;
+}
+
+/** A matrix step's matrix, as the step carries it. */
+export interface Matrix<Ax extends Axes = Axes> {
+  readonly axes: Ax;
+  readonly exclude: readonly Cell[];
+  readonly failure: FailureStrategy;
+  readonly maxParallel?: number;
+}
+
+export const AXIS_NAME = /^[a-z][a-zA-Z0-9]{0,30}$/;
+export const AXIS_VALUE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/;
+export const MAX_AXES = 4;
+export const MAX_CELLS = 64;
+
+export function makeMatrix(def: MatrixDef<Axes>): Matrix {
+  return Object.freeze({
+    axes: Object.freeze(
+      Object.fromEntries(
+        Object.entries(def.axes ?? {}).map(([k, v]) => [
+          k,
+          Object.freeze(Array.isArray(v) ? [...v] : v),
+        ]),
+      ),
+    ),
+    exclude: Object.freeze((def.exclude ?? []).map((e) => Object.freeze({ ...e }))),
+    failure: def.failure ?? keepRunning(),
+    ...(def.maxParallel !== undefined ? { maxParallel: def.maxParallel } : {}),
+  }) as Matrix;
+}
+
+const matches = (cell: Cell, x: Cell) =>
+  Object.entries(x).every(([k, v]) => cell[k] === v);
+
+/** The cells in order: the cross product in axis order (first axis outermost) minus the excludes. */
+export function matrixCells(m: Matrix): Cell[] {
+  let cells: Record<string, string>[] = [{}];
+  for (const [axis, values] of Object.entries(m.axes))
+    cells = cells.flatMap((c) =>
+      (Array.isArray(values) ? values : []).map((v) => ({ ...c, [axis]: v })),
+    );
+  return cells.filter((c) => !m.exclude.some((x) => matches(c, x)));
+}
+
+/** `build-cli[os=linux,arch=x64]`: the name a cell's attempts, files and address use. */
+export function cellName(step: string, cell: Cell): string {
+  return `${step}[${Object.entries(cell)
+    .map(([k, v]) => `${k}=${v}`)
+    .join(',')}]`;
+}
+
+/** The cell `raw` (JSON text, as in `OLVE_CELL`) names, in axis order, or what is wrong. */
+export function parseCell(
+  step: string,
+  m: Matrix,
+  raw: string | undefined,
+): { ok: true; cell: Cell } | { ok: false; message: string } {
+  const axes = Object.keys(m.axes);
+  const example = JSON.stringify(matrixCells(m)[0] ?? {});
+  if (raw === undefined || raw === '')
+    return {
+      ok: false,
+      message: `step '${step}' is a matrix step: OLVE_CELL must name the cell to run, e.g. ${example}`,
+    };
+  let v: unknown;
+  try {
+    v = JSON.parse(raw);
+  } catch (e) {
+    return { ok: false, message: `OLVE_CELL is not JSON: ${(e as Error).message}` };
+  }
+  if (typeof v !== 'object' || v === null || Array.isArray(v))
+    return {
+      ok: false,
+      message: `OLVE_CELL must be a JSON object of axis values, e.g. ${example}`,
+    };
+  const given = v as Record<string, unknown>;
+  const ordered: Record<string, string> = {};
+  for (const a of axes) {
+    if (typeof given[a] !== 'string') break;
+    ordered[a] = given[a] as string;
+  }
+  const exact =
+    Object.keys(given).length === axes.length &&
+    Object.keys(ordered).length === axes.length;
+  const all = matrixCells(m);
+  if (exact && all.some((c) => cellName(step, c) === cellName(step, ordered)))
+    return { ok: true, cell: Object.freeze(ordered) };
+  return {
+    ok: false,
+    message: `OLVE_CELL ${raw} is not a cell of step '${step}' (cells: ${all.map((c) => cellName(step, c)).join(', ')})`,
+  };
+}
+
+// ─── cells(): reading a matrix step ──────────────────────────────────────────────────────────
+
+/** A step input that reads every cell of a matrix step whose output is `model`. */
+export interface Cells<M extends AnyModel = AnyModel> {
+  readonly kind: 'cells';
+  readonly model: M;
+}
+export function cells<M extends AnyModel>(model: M): Cells<M> {
+  return Object.freeze({ kind: 'cells' as const, model });
+}
+export function isCells(v: unknown): v is Cells {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as { kind?: unknown }).kind === 'cells' &&
+    isModel((v as { model?: unknown }).model)
+  );
+}
+/** One entry of a `cells` input, in cell order. */
+export interface CellOutput<M extends AnyModel, C extends Cell = Cell> {
+  readonly cell: C;
+  readonly output: Infer<M>;
+}

package/src/core/models.ts

@@ -48,11 +48,16 @@ export const FILE_PATH_PATTERN = `^(?:${SEGMENT}/)*${SEGMENT}/?$`;
 export const FILE_PATH = new RegExp(FILE_PATH_PATTERN);
 /** Step names: lower-case kebab, ≤ 63 chars (usable as K8s label values, URL segments and storage paths). */
 export const STEP_NAME = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const CELL_PART = String.raw`[a-z][a-zA-Z0-9]{0,30}=[A-Za-z0-9][A-Za-z0-9._-]{0,62}`;
+/** A step name, or a matrix cell's name (`build-cli[os=linux,arch=x64]`): what a file reference's `step` holds. */
+export const ATTEMPT_STEP = new RegExp(
+  String.raw`^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\[${CELL_PART}(?:,${CELL_PART})*\])?$`,
+);
 
 const FileRefSchema = z
   .object({
     run: z.number().int().nonnegative(),
-    step: z.string().regex(STEP_NAME),
+    step: z.string().regex(ATTEMPT_STEP),
     attempt: z.number().int().positive(),
     path: z.string().regex(FILE_PATH),
     sha256: z.string().regex(/^[0-9a-f]{64}$/),

package/src/core/steps.ts

@@ -6,24 +6,35 @@ import type { AnyConfigEntry } from './config.ts';
 import { configRefsIn } from './config-refs.ts';
 import type { Secret } from './secrets.ts';
 import type { Simplify } from './types.ts';
+import {
+  makeMatrix,
+  type Axes,
+  type CellOfAxes,
+  type CellOutput,
+  type Cells,
+  type Matrix,
+  type MatrixDef,
+} from './matrix.ts';
 
 /**
- * A step input entry: a model (matchable by model), `optional(model)`, a plain zod schema (mapper required),
- * or `external(model, …)`, answered from outside the run.
+ * A step input entry: a model (matchable by model), `optional(model)`, `cells(model)` (every cell of a
+ * matrix step), a plain zod schema (mapper required), or `external(model, …)`, answered from outside the run.
  */
-export type InputEntry = AnyModel | Optional | External | z.ZodType;
+export type InputEntry = AnyModel | Optional | Cells | External | z.ZodType;
 export type InputSpec = { readonly [key: string]: InputEntry };
 
 export type InferEntry<E> =
   E extends Optional<infer M>
     ? Infer<M> | undefined
-    : E extends External<infer M>
-      ? Infer<M>
-      : E extends AnyModel
-        ? Infer<E>
-        : E extends z.ZodType
-          ? z.output<E>
-          : never;
+    : E extends Cells<infer M>
+      ? CellOutput<M>[]
+      : E extends External<infer M>
+        ? Infer<M>
+        : E extends AnyModel
+          ? Infer<E>
+          : E extends z.ZodType
+            ? z.output<E>
+            : never;
 /** What a handler receives: the output view of every input entry. */
 export type StepInput<I> = Simplify<{ -readonly [K in keyof I]: InferEntry<I[K]> }>;
 
@@ -56,6 +67,8 @@ export interface Step<
   readonly clusterAccess?: boolean;
   /** How the step is set up, as written in the definition (may hold config references). */
   readonly settings?: Readonly<Record<string, unknown>>;
+  /** Set on a matrix step: it runs once per cell. */
+  readonly matrix?: Matrix;
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type AnyStep = Step<string, any, AnyModel | null, any, any>;
@@ -64,6 +77,10 @@ export type AnyStep = Step<string, any, AnyModel | null, any, any>;
 export type SecretsOf<S> = S extends Step<any, any, any, infer Sec, any> ? Sec : never;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ConfigOf<S> = S extends Step<any, any, any, any, infer C> ? C : never;
+/** The cell type of a matrix step (`never` for any other step). */
+export type CellOf<S> = S extends { readonly matrix: Matrix<infer Ax> }
+  ? CellOfAxes<Ax>
+  : never;
 export type OutputValue<S extends AnyStep> = S['output'] extends AnyModel
   ? Infer<S['output']>
   : void;
@@ -82,6 +99,7 @@ export interface StepDef<
   O extends AnyModel | null,
   Sec extends readonly Secret[],
   Cfg extends readonly AnyConfigEntry[] = [],
+  Ax extends Axes = never,
 > {
   name: LiteralName<N>;
   /** What the step does, shown in the UI. Required; may be empty. */
@@ -109,6 +127,8 @@ export interface StepDef<
    * references is delivered to the step, and `resolveConfigRefs(value, ctx.config)` resolves them.
    */
   settings?: Readonly<Record<string, unknown>>;
+  /** Run the step once per cell of these axes; the handler reads its cell from `ctx.cell`. */
+  matrix?: MatrixDef<Ax>;
 }
 
 function makeStep(def: Record<string, unknown>): AnyStep {
@@ -130,6 +150,9 @@ function makeStep(def: Record<string, unknown>): AnyStep {
     ...(def.retries !== undefined ? { retries: def.retries } : {}),
     ...(def.clusterAccess === true ? { clusterAccess: true } : {}),
     ...(def.settings !== undefined ? { settings: def.settings } : {}),
+    ...(def.matrix !== undefined
+      ? { matrix: makeMatrix(def.matrix as MatrixDef<Axes>) }
+      : {}),
   };
   return Object.freeze(s) as unknown as AnyStep;
 }
@@ -150,6 +173,10 @@ export function step<
   O extends AnyModel | null = null,
   const Sec extends readonly Secret[] = [],
   const Cfg extends readonly AnyConfigEntry[] = [],
->(def: StepDef<N, I, O, Sec, Cfg>): Step<N, I, O, Sec[number]['name'], Cfg[number]> {
+  const Ax extends Axes = never,
+>(
+  def: StepDef<N, I, O, Sec, Cfg, Ax>,
+): Step<N, I, O, Sec[number]['name'], Cfg[number]> &
+  ([Ax] extends [never] ? unknown : { readonly matrix: Matrix<Ax> }) {
   return makeStep(def as never) as never;
 }

package/src/ctx/index.ts

@@ -3,6 +3,7 @@ import { resolve } from 'node:path';
 import { skipped } from '../core/handlers.ts';
 import { createLinks } from './links.ts';
 import type { Secret } from '../core/secrets.ts';
+import type { Cell } from '../core/matrix.ts';
 import { createFetch, createOutput, redactUrl } from './files.ts';
 import { createSh } from './sh.ts';
 import type { Ctx, Http, RetryOptions, RunInfo } from './types.ts';
@@ -21,6 +22,8 @@ export interface CtxOptions {
   logSink?: (line: string) => void;
   /** `<step>/<input>` → callback URL (`ctx.inputUrl`). */
   callbackUrls?: Readonly<Record<string, string>>;
+  /** A matrix step's cell (`ctx.cell`). */
+  cell?: Cell;
 }
 
 export function formatLog(message: string, fields?: Record<string, unknown>): string {
@@ -151,6 +154,7 @@ export function createCtx(o: CtxOptions): Ctx {
     log,
   };
   return {
+    ...(o.cell ? { cell: o.cell } : {}),
     secrets: createSecrets(o.secrets, o.secretValues) as Ctx['secrets'],
     config: Object.freeze({ ...o.config }) as Ctx['config'],
     sh,

package/src/ctx/types.ts

@@ -124,3 +124,10 @@ export interface Ctx<Sec extends string = string, Cfg extends AnyConfigEntry = n
    */
   inputUrl(step: string | { readonly name: string }, input: string): string;
 }
+
+/** The ctx a step's handler gets: a matrix step's also carries its cell (`ctx.cell`), in axis order. */
+export type StepCtx<Sec extends string, Cfg extends AnyConfigEntry, Cell> = Ctx<
+  Sec,
+  Cfg
+> &
+  ([Cell] extends [never] ? unknown : { readonly cell: Cell });

package/src/describe/context.ts

@@ -12,10 +12,11 @@ import { schemaViews, type JsonSchema } from './schemas.ts';
 export const FAILURE_ROOT = 'failure';
 const RESERVED = new Set([...RESERVED_STEP_NAMES, FAILURE_ROOT]);
 
-/** What a step can read at a point of the pipeline: its output model, and whether it may have been skipped. */
+/** What a step can read at a point of the pipeline: its output model, whether it may have been skipped, and whether it is a matrix step. */
 export interface Avail {
   model: string | null;
   maybe: boolean;
+  matrix?: boolean;
 }
 
 /** A select case a step sits in: which select (numbered in describe order), which value, and its condition text. */
@@ -154,6 +155,10 @@ export class DescribeContext {
       problems.push(
         `step '${s.name}': its select cases must give it the same output model`,
       );
+    else if (prev.some((p) => !p.step.matrix !== !s.matrix))
+      problems.push(
+        `step '${s.name}': its select cases must all make it a matrix step, or none`,
+      );
     this.placements.set(s.name, [...prev, { step: s, cases }]);
     if (!this.steps.has(s.name)) this.steps.set(s.name, s);
   }

package/src/describe/manifest-schema.ts

@@ -76,6 +76,12 @@ export const InputType = z
       optional: z
         .boolean()
         .describe('optional(Model): may be absent because its producer was skipped.'),
+      cells: z
+        .literal(true)
+        .optional()
+        .describe(
+          'cells(Model): every cell of a matrix step whose output is the model, mapped with a whole-step ref; the value is [{cell, output}, …] in cell order. Omitted otherwise.',
+        ),
     }),
     z.strictObject({
       schema: ModelSchemas.describe(
@@ -85,6 +91,45 @@ export const InputType = z
   ])
   .meta({ id: 'InputType' });
 
+const axisName = z.string().regex(/^[a-z][a-zA-Z0-9]{0,30}$/);
+const axisValue = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/);
+
+export const Matrix = z
+  .strictObject({
+    axes: z
+      .array(
+        z.strictObject({
+          name: axisName,
+          values: z.array(axisValue).min(1).describe('Unique per axis.'),
+        }),
+      )
+      .min(1)
+      .max(4)
+      .describe(
+        'In order: the cells are the cross product, first axis outermost, minus the excludes (1 to 64 cells).',
+      ),
+    exclude: z
+      .array(z.record(axisName, axisValue))
+      .optional()
+      .describe(
+        'Each entry names one or more axes with one of their values; a cell matching every named axis is left out (omitted when none).',
+      ),
+    failure: z
+      .strictObject({ kind: z.enum(['keepRunning', 'cascadeFailure']) })
+      .describe(
+        "keepRunning: every cell runs to the end. cascadeFailure: a cell whose last allowed attempt failed cancels the step's other scheduled or running cells.",
+      ),
+    maxParallel: z
+      .int()
+      .min(1)
+      .optional()
+      .describe("At most this many of the step's cells running at once in a run."),
+  })
+  .describe(
+    "A matrix step runs once per cell, named '<step>[<axis>=<value>,…]' in axis order; OLVE_CELL holds the cell as compact JSON.",
+  )
+  .meta({ id: 'Matrix' });
+
 export const StepDescriptor = z
   .strictObject({
     name: stepName,
@@ -114,6 +159,9 @@ export const StepDescriptor = z
       ),
     timeoutSeconds: z.number().int().positive().optional(),
     retries: z.number().int().nonnegative().optional(),
+    matrix: Matrix.optional().describe(
+      'Set on a matrix step (never on a failure handler); omitted otherwise.',
+    ),
     config: z
       .record(z.string(), Json)
       .optional()

package/src/describe/stages.ts

@@ -54,6 +54,7 @@ function describeStage(
       avail.set(ss.step.name, {
         model: ss.step.output?.name ?? null,
         maybe: false,
+        ...(ss.step.matrix ? { matrix: true } : {}),
       });
   return descs.length ? { steps: descs } : undefined;
 }
@@ -96,7 +97,7 @@ function describeWhen(
   const inner = new Map(avail);
   const stages = describeStages(ctx, input, n.nodes, inner, cases);
   for (const [name, a] of inner)
-    if (!avail.has(name)) avail.set(name, { model: a.model, maybe: true });
+    if (!avail.has(name)) avail.set(name, { ...a, maybe: true });
   return { when, stages };
 }
 
@@ -153,7 +154,7 @@ function describeSelect(
       .map((b) => b.inner.get(name))
       .filter((a): a is Avail => a !== undefined);
     avail.set(name, {
-      model: present[0]!.model,
+      ...present[0]!,
       maybe: present.length < branches.length || present.some((a) => a.maybe),
     });
   }

package/src/describe/step.ts

@@ -1,6 +1,15 @@
 import { z } from 'zod';
 import { isModel, isOptional } from '../core/models.ts';
 import { isExternal } from '../core/external.ts';
+import {
+  AXIS_NAME,
+  AXIS_VALUE,
+  MAX_AXES,
+  MAX_CELLS,
+  isCells,
+  matrixCells,
+  type Matrix,
+} from '../core/matrix.ts';
 import type { AnyStep } from '../core/steps.ts';
 import { isImplementation } from '../core/handlers.ts';
 import { recordConfigRefs } from '../core/config-refs.ts';
@@ -20,6 +29,7 @@ import {
 } from './context.ts';
 
 type InputTypes = StepDescriptorT['inputTypes'];
+type MatrixT = NonNullable<StepDescriptorT['matrix']>;
 type ExternalInputs = NonNullable<StepDescriptorT['externalInputs']>;
 type InputEntries = [string, unknown][];
 
@@ -77,6 +87,9 @@ export function describeStep(
     problems.push(`${at}: timeoutSeconds must be a positive integer`);
   if (s.retries !== undefined && !(Number.isInteger(s.retries) && s.retries >= 0))
     problems.push(`${at}: retries must be a non-negative integer`);
+  if (s.matrix !== undefined && failureHandler)
+    problems.push(`${at}: a failure handler cannot be a matrix step`);
+  const matrix = s.matrix !== undefined ? describeMatrix(ctx, at, s.matrix) : undefined;
 
   const out: StepDescriptorT = {
     name: s.name,
@@ -89,6 +102,7 @@ export function describeStep(
     secrets: secretNames,
     ...(s.timeoutSeconds !== undefined ? { timeoutSeconds: s.timeoutSeconds } : {}),
     ...(s.retries !== undefined ? { retries: s.retries } : {}),
+    ...(matrix !== undefined ? { matrix } : {}),
     ...(settings !== undefined
       ? { config: settings as Record<string, z.core.util.JSONType> }
       : {}),
@@ -156,7 +170,13 @@ function describeInputTypes(
 ): InputTypes {
   const inputTypes: InputTypes = {};
   for (const [key, e] of entries) {
-    if (isOptional(e))
+    if (isCells(e))
+      inputTypes[key] = {
+        model: ctx.useModel(e.model, `${at} input '${key}'`),
+        optional: false,
+        cells: true,
+      };
+    else if (isOptional(e))
       inputTypes[key] = {
         model: ctx.useModel(e.model, `${at} input '${key}'`),
         optional: true,
@@ -176,7 +196,7 @@ function describeInputTypes(
       }
     } else
       ctx.problems.push(
-        `${at} input '${key}': must be a model, optional(model) or a zod schema`,
+        `${at} input '${key}': must be a model, optional(model), cells(model) or a zod schema`,
       );
   }
   return inputTypes;
@@ -209,6 +229,25 @@ function matchInputsByModel(
   const problems = ctx.problems;
   const input: Record<string, Mapping> = {};
   for (const [key, e] of entries) {
+    if (isCells(e)) {
+      const producers = [...avail].filter(
+        ([, a]) => a.matrix && a.model === e.model.name,
+      );
+      if (producers.length === 1) {
+        const [producer, a] = producers[0]!;
+        if (a.maybe) problems.push(maybeCells(at, e.model.name, key));
+        input[key] = { ref: producer };
+      } else
+        problems.push(
+          producers.length === 0
+            ? `${at}: ${e.model.name} (input '${key}') has no matrix step producing it at this stage; cells() reads a matrix step`
+            : `${at}: ${e.model.name} (input '${key}') has several matrix steps producing it (${producers
+                .map(([n]) => n)
+                .sort()
+                .join(', ')}); use a mapper to pick one`,
+        );
+      continue;
+    }
     const optional = isOptional(e);
     const m = optional ? e.model : isModel(e) ? e : undefined;
     if (!m) {
@@ -217,8 +256,13 @@ function matchInputsByModel(
       );
       continue;
     }
-    const producers = [...avail].filter(([, a]) => a.model === m.name);
-    if (producers.length === 0) {
+    const producers = [...avail].filter(([, a]) => !a.matrix && a.model === m.name);
+    const matrixProducer = [...avail].find(([, a]) => a.matrix && a.model === m.name);
+    if (producers.length === 0 && matrixProducer) {
+      problems.push(
+        `${at}: ${m.name} (input '${key}') is produced by matrix step '${matrixProducer[0]}'; read it with cells(${m.name})`,
+      );
+    } else if (producers.length === 0) {
       problems.push(
         `${at}: ${m.name} (input '${key}') is not available at this stage${optional ? ' (optional() means maybe-skipped; there must still be an earlier producer)' : ''}`,
       );
@@ -273,11 +317,47 @@ function mapStep(
   for (const k of Object.keys(recorded))
     if (!(k in declared))
       problems.push(`${at}: mapper provides '${k}', which is not an input of the step`);
-  for (const [k, m] of Object.entries(recorded))
-    checkMapping(ctx, `${at} input '${k}'`, m, avail, isOptional(declared[k]), true);
+  for (const [k, m] of Object.entries(recorded)) {
+    const e = declared[k];
+    if (isCells(e)) checkCellsMapping(ctx, `${at} input '${k}'`, m, avail, e.model.name);
+    else checkMapping(ctx, `${at} input '${k}'`, m, avail, isOptional(e), true);
+  }
   return recorded;
 }
 
+const maybeCells = (at: string, model: string, key: string) =>
+  `${at}: ${model} (input '${key}') is only maybe-available (produced inside a when block); cells() cannot read a maybe-skipped matrix step`;
+
+function checkCellsMapping(
+  ctx: DescribeContext,
+  at: string,
+  m: Mapping,
+  avail: Map<string, Avail>,
+  model: string,
+): void {
+  const problems = ctx.problems;
+  const ref =
+    Object.keys(m).length === 1 && typeof (m as { ref?: unknown }).ref === 'string'
+      ? (m as { ref: string }).ref
+      : undefined;
+  if (ref === undefined || ref.includes('.'))
+    return void problems.push(
+      `${at}: a cells() input takes a whole matrix step (from['<step>']), not a field or an object`,
+    );
+  const a = avail.get(ref);
+  if (!a) return void problems.push(`${at}: '${ref}' is not available at this stage`);
+  if (!a.matrix)
+    return void problems.push(
+      `${at}: '${ref}' is not a matrix step; cells() reads a matrix step`,
+    );
+  if (a.model !== model)
+    problems.push(`${at}: '${ref}' outputs ${a.model ?? 'nothing'}, not ${model}`);
+  if (a.maybe)
+    problems.push(
+      `${at}: '${ref}' is only maybe-available (produced inside a when block); cells() cannot read a maybe-skipped matrix step`,
+    );
+}
+
 function checkMapping(
   ctx: DescribeContext,
   at: string,
@@ -299,6 +379,10 @@ function checkMapping(
     ];
     const a = avail.get(root);
     if (!a) return void problems.push(`${at}: '${root}' is not available at this stage`);
+    if (a.matrix)
+      return void problems.push(
+        `${at}: '${(m as { ref: string }).ref}' — '${root}' is a matrix step; read it whole through a cells() input`,
+      );
     if (!resolveField(ctx.outputViewOf(a.model), path))
       problems.push(
         `${at}: '${(m as { ref: string }).ref}' — model ${a.model} has no field '${path.join('.')}'`,
@@ -393,3 +477,68 @@ function checkConfigRefs(
       );
   }
 }
+
+function describeMatrix(
+  ctx: DescribeContext,
+  at: string,
+  m: Matrix,
+): MatrixT | undefined {
+  const problems = ctx.problems;
+  const before = problems.length;
+  const axes = Object.entries(
+    typeof m.axes === 'object' && m.axes !== null ? m.axes : {},
+  ) as [string, unknown][];
+  if (axes.length < 1 || axes.length > MAX_AXES)
+    problems.push(
+      `${at}: a matrix has 1 to ${MAX_AXES} axes (this one has ${axes.length})`,
+    );
+  for (const [name, values] of axes) {
+    if (!AXIS_NAME.test(name))
+      problems.push(`${at}: matrix axis name '${name}' must match ${AXIS_NAME}`);
+    if (!Array.isArray(values) || values.some((v) => typeof v !== 'string')) {
+      problems.push(`${at}: matrix axis '${name}' must be a list of strings`);
+      continue;
+    }
+    if (values.length === 0) problems.push(`${at}: matrix axis '${name}' has no values`);
+    for (const v of values as string[])
+      if (!AXIS_VALUE.test(v))
+        problems.push(
+          `${at}: matrix axis '${name}': value '${v}' must match ${AXIS_VALUE}`,
+        );
+    for (const v of new Set(
+      (values as string[]).filter((v, i) => values.indexOf(v) !== i),
+    ))
+      problems.push(`${at}: matrix axis '${name}': value '${v}' is listed twice`);
+  }
+  const known = new Map(axes);
+  m.exclude.forEach((x, i) => {
+    const where = `${at}: matrix exclude ${i + 1}`;
+    if (Object.keys(x).length === 0)
+      problems.push(`${where} must name at least one axis`);
+    for (const [k, v] of Object.entries(x)) {
+      const values = known.get(k);
+      if (!values) problems.push(`${where}: '${k}' is not an axis`);
+      else if (!(Array.isArray(values) && values.includes(v)))
+        problems.push(`${where}: '${String(v)}' is not a value of axis '${k}'`);
+    }
+  });
+  const kind = (m.failure as { kind?: unknown } | undefined)?.kind;
+  if (kind !== 'keepRunning' && kind !== 'cascadeFailure')
+    problems.push(`${at}: matrix failure must be keepRunning() or cascadeFailure()`);
+  if (
+    m.maxParallel !== undefined &&
+    !(Number.isInteger(m.maxParallel) && m.maxParallel >= 1)
+  )
+    problems.push(`${at}: matrix maxParallel must be a positive integer`);
+  if (problems.length > before) return undefined;
+  const count = matrixCells(m).length;
+  if (count === 0) problems.push(`${at}: the matrix excludes every cell`);
+  else if (count > MAX_CELLS)
+    problems.push(`${at}: the matrix has ${count} cells (at most ${MAX_CELLS})`);
+  return {
+    axes: axes.map(([name, values]) => ({ name, values: [...(values as string[])] })),
+    ...(m.exclude.length ? { exclude: m.exclude.map((x) => ({ ...x })) } : {}),
+    failure: { kind: kind as MatrixT['failure']['kind'] },
+    ...(m.maxParallel !== undefined ? { maxParallel: m.maxParallel } : {}),
+  };
+}

package/src/harness/env.ts

@@ -9,6 +9,8 @@ export const ENV = {
   run: 'OLVE_RUN',
   attempt: 'OLVE_ATTEMPT',
   versionStamp: 'OLVE_VERSION_STAMP',
+  /** A matrix step's cell, as compact JSON in axis order (`{"os":"linux","arch":"x64"}`). */
+  cell: 'OLVE_CELL',
   /** Pre-signed PUT for result.tar.gz (run / map-trigger). Optional. */
   resultUrl: 'OLVE_RESULT_URL',
   /** JSON object: file key (`<run>/<step>/<attempt>/<path>`) → pre-signed GET URL. Optional. */

package/src/harness/main.ts

@@ -7,6 +7,7 @@ import { join } from 'node:path';
 import { isImplementation } from '../core/handlers.ts';
 import { configRefPath, isConfigRef, unionAt } from '../core/config.ts';
 import type { AnyStep } from '../core/steps.ts';
+import { cellName, parseCell } from '../core/matrix.ts';
 import type { WebhookEvent } from '../core/webhooks.ts';
 import { pipelineData, type PipelineData, type StageNode } from '../builder/pipeline.ts';
 import { createCtx, formatLog } from '../ctx/index.ts';
@@ -193,17 +194,21 @@ async function runMode(
   mkdirSync(p.files, { recursive: true });
   mkdirSync(p.tmp, { recursive: true });
   const raw = readJson(p.input);
+  const cell = step.matrix
+    ? parseCell(step.name, step.matrix, process.env[ENV.cell])
+    : undefined;
   const cancel = cancellation();
   try {
     let exec: Execution;
-    if (!raw.ok) {
-      io.stderr(raw.message);
+    if (!raw.ok || (cell && !cell.ok)) {
+      const message = !raw.ok ? raw.message : cell && !cell.ok ? cell.message : '';
+      io.stderr(message);
       exec = {
-        envelope: { status: 'failed', error: { kind: 'input', message: raw.message } },
+        envelope: { status: 'failed', error: { kind: 'input', message } },
         exitCode: EXIT.inputInvalid,
       };
     } else {
-      const run = runInfoFromEnv(step.name);
+      const run = runInfoFromEnv(cell?.ok ? cellName(step.name, cell.cell) : step.name);
       const ctx = createCtx({
         run,
         secrets: step.secrets,
@@ -211,6 +216,7 @@ async function runMode(
         signal: cancel.signal,
         logSink: io.stderr,
         callbackUrls: callbackUrlsFromEnv(),
+        ...(cell?.ok ? { cell: cell.cell } : {}),
       });
       exec = await executeStep({
         step,

package/src/harness/validate.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { isModel, isOptional } from '../core/models.ts';
 import { isExternal } from '../core/external.ts';
+import { isCells } from '../core/matrix.ts';
 import type { AnyStep } from '../core/steps.ts';
 
 export type Validation<T> = { ok: true; value: T } | { ok: false; issues: string[] };
@@ -57,6 +58,10 @@ export function parseStrict(
 }
 
 function entrySchema(e: unknown): z.ZodType {
+  if (isCells(e))
+    return z.array(
+      z.object({ cell: z.record(z.string(), z.string()), output: e.model.schema }),
+    );
   if (isOptional(e) || isExternal(e)) return e.model.schema;
   if (isModel(e)) return e.schema;
   return e as z.ZodType;

package/src/index.ts

@@ -14,6 +14,18 @@ export {
   type Optional,
 } from './core/models.ts';
 export { secret, type Secret, type DeclaredSecrets } from './core/secrets.ts';
+export {
+  cells,
+  keepRunning,
+  cascadeFailure,
+  type Axes,
+  type Cell,
+  type CellOutput,
+  type Cells,
+  type FailureStrategy,
+  type Matrix,
+  type MatrixDef,
+} from './core/matrix.ts';
 export {
   config,
   secretRef,
@@ -53,6 +65,7 @@ export {
   type StepInput,
   type StepKind,
   type ConfigOf,
+  type CellOf,
   type InputEntry,
   type InputSpec,
   type LiteralName,
@@ -62,12 +75,14 @@ export type { Simplify } from './core/types.ts';
 export {
   implement,
   type Implementation,
+  type CtxOf,
   type Handler,
   type HandlerResult,
   type Skipped,
 } from './core/handlers.ts';
 export type {
   Ctx,
+  StepCtx,
   RunInfo,
   Sh,
   ShOptions,

package/src/testing/index.ts

@@ -4,9 +4,11 @@ import { mkdtempSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { isImplementation, type Implementation } from '../core/handlers.ts';
+import { cellName, parseCell } from '../core/matrix.ts';
 import type { FileRef } from '../core/models.ts';
 import type {
   AnyStep,
+  CellOf,
   ConfigOf,
   OutputValue,
   SecretsOf,
@@ -15,6 +17,7 @@ import type {
 import { createCtx } from '../ctx/index.ts';
 import type { Ctx, RunInfo } from '../ctx/types.ts';
 import type { StepLink } from '../ctx/links.ts';
+import { EXIT } from '../harness/exit.ts';
 import { executeStep, type FailureKind, type StepFunction } from '../harness/execute.ts';
 import { sha256Hex } from '../util/hash.ts';
 
@@ -32,6 +35,8 @@ export interface TestHandlerOptions<S extends AnyStep> {
   signal?: AbortSignal;
   /** `<step>/<input>` → URL returned by `ctx.inputUrl`. */
   callbackUrls?: Record<string, string>;
+  /** The cell to run a matrix step in (`ctx.cell`), like `OLVE_CELL`. */
+  cell?: CellOf<S>;
 }
 
 export type TestResult<S extends AnyStep> = {
@@ -65,9 +70,27 @@ export async function testHandler<S extends AnyStep>(
   const step: AnyStep = target.step;
   const fn = target.handler as unknown as StepFunction;
 
+  const cell = step.matrix
+    ? parseCell(
+        step.name,
+        step.matrix,
+        opts.cell === undefined ? undefined : JSON.stringify(opts.cell),
+      )
+    : undefined;
   const dir = opts.dir ?? mkdtempSync(join(tmpdir(), `olve-test-${step.name}-`));
   const filesDir = join(dir, 'work', 'files');
   const logs: string[] = [];
+  if (cell && !cell.ok) {
+    logs.push(cell.message);
+    return {
+      dir,
+      filesDir,
+      logs,
+      exitCode: EXIT.inputInvalid,
+      status: 'failed',
+      error: { kind: 'input', message: cell.message },
+    };
+  }
   const run: RunInfo = {
     pipeline: 'test',
     id: 'test',
@@ -75,7 +98,7 @@ export async function testHandler<S extends AnyStep>(
     attempt: 1,
     version: '0.0.0-test',
     ...opts.run,
-    step: step.name,
+    step: cell?.ok ? cellName(step.name, cell.cell) : step.name,
   };
   const real = createCtx({
     run,
@@ -85,6 +108,7 @@ export async function testHandler<S extends AnyStep>(
     signal: opts.signal ?? new AbortController().signal,
     logSink: (l) => logs.push(l),
     callbackUrls: opts.callbackUrls,
+    ...(cell?.ok ? { cell: cell.cell } : {}),
   });
   const ctx = { ...real, ...opts.ctx } as Ctx;
   // Round-trip through JSON like input.json does (drops undefined, rejects non-JSON values early).