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

package/README.md

@@ -1,6 +1,6 @@
 # @olivervea/pipelines
 
-The [Olve.Pipelines](https://github.com/OliverVea/Olve.Pipelines) v2 SDK, imported as `@olve/pipelines`. It has four parts:
+The [Olve.Pipelines](https://github.com/OliverVea/Olve.Pipelines) v2 SDK. It has four parts:
 
 - 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`);
@@ -12,14 +12,14 @@ The manifest format is in [`manifest.schema.json`](manifest.schema.json), genera
 
 ```
 sdk/
-  src/index.ts            authoring API (`@olve/pipelines`)
+  src/index.ts            authoring API (`@olivervea/pipelines`)
   src/core/               models, secrets, 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/describe/           describe: manifest, checks, mapper recording + source analysis, manifest schema
-  src/harness/            harness CLI modes, env contract, envelope, result upload (`@olve/pipelines/harness`)
+  src/harness/            harness CLI modes, env contract, envelope, result upload (`@olivervea/pipelines/harness`)
   src/ctx/                the ctx handed to handlers
-  src/testing/            testHandler (`@olve/pipelines/testing`)
+  src/testing/            testHandler (`@olivervea/pipelines/testing`)
   src/build/              olve-build
   src/dev/                olve-dev
   examples/self-deploy/   fixture pipeline (the self-deploy shape) used by the tests
@@ -30,13 +30,12 @@ sdk/
 
 ## Install
 
-The package is `@olivervea/pipelines` on npm; pipelines import it as `@olve/pipelines` through an alias
-in the pipeline directory's `package.json`:
+The package is `@olivervea/pipelines` on npm; a pipeline directory's `package.json` depends on it by that name:
 
 ```json
 {
   "type": "module",
-  "dependencies": { "@olve/pipelines": "npm:@olivervea/pipelines@2.0.0-beta.1" },
+  "dependencies": { "@olivervea/pipelines": "2.0.0-beta.3" },
   "devDependencies": { "@types/bun": "1.4.3", "typescript": "7.0.2" }
 }
 ```
@@ -47,18 +46,16 @@ bunx olve-dev describe .
 bunx olve-build . --out .olve/out
 ```
 
-- Keep the alias name: `olve-build` generates imports of `@olve/pipelines/harness`, so an unaliased
-  `@olivervea/pipelines` dependency does not build.
 - The package ships TypeScript sources (Bun runs them directly; `harness.sdkHash` hashes them), so the
   same version gives the same `sdkHash` and handler hashes from npm or from `file:../sdk`.
-- Inside this repo, `.pipelines/` and `.pipelines-test/` use `"@olve/pipelines": "file:../sdk"`.
+- Inside this repo, `.pipelines/` and `.pipelines-test/` use `"@olivervea/pipelines": "file:../sdk"`.
 
 ### Releases
 
 Versions are `2.0.0-beta.N` on the `beta` dist-tag (`publishConfig`) until v2 reaches prod, then
-`latest`. To release, bump `version` in `package.json` and push to `v2`: the self-deploy's
-`publish-sdk` step runs `bun run check` and `bun publish` when that version is not on npm yet. It
-skips when the version exists, or when the pipeline secret `NPM_TOKEN` is unset.
+`latest`. To release, bump `version` in `package.json`, push to `v2`: once the run reaches prod, the
+self-deploy's `publish-sdk` step runs `bun run check` and `bun publish` when that version is not on npm yet. It
+skips when the version exists, or when the pipeline secret `NPM_TOKEN` is unset. Published versions: `npm view @olivervea/pipelines versions`.
 
 ## Authoring
 
@@ -67,7 +64,7 @@ A pipeline directory (the binding path, `.pipelines/` by default) looks like thi
 ```
 models.ts                 data models                         (contract file)
 pipeline.ts               steps + `export default pipeline(…)` (contract file)
-handlers/<step-name>.ts   one per custom step: `export default implement(step, fn)`
+handlers/*.ts             one per custom step: `export default implement(step, fn)` (pairs by the step, not the file name)
 handlers/lib/…            shared helpers (not handlers)
 scripts/*.sh              embedded with `import s from "../scripts/x.sh" with { type: "file" }`
 ```
@@ -77,7 +74,7 @@ Contract files hold contracts only. Describe evaluates them without loading hand
 ### Models, secrets, steps
 
 ```ts
-import { model, z, fileRef, optional, secret, step, steps, Source } from "@olve/pipelines";
+import { model, z, fileRef, optional, secret, step, steps, Source } from "@olivervea/pipelines";
 
 export const BuildArtifact = model("BuildArtifact", z.object({
   version: z.string(),
@@ -123,27 +120,38 @@ In the output JSON, an object of the form `{"$file": "<path>"}` or `{"$dir": "<p
 
 ### Library steps
 
-Library steps carry their own implementation and image; they take typed config and use the SDK models `Source`, `BuiltImage` and `HelmRelease`. The set grows from real use: a step or an option exists because a pipeline uses it.
+Library steps carry their own implementation and image; they take typed config and use the SDK models `Source`, `BuiltImage`, `PushedImage` and `HelmRelease`. The set grows from real use: a step or an option exists because a pipeline uses it.
 
 | 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 }` | `repository` (image name; tag = run version, `-attempt<n>` on reruns), `cacheRepo?` (kaniko layer cache), `registryMap?` (kaniko `--registry-map`: registry → mirror prefix, falls back upstream), `stallTimeoutSeconds?` (default 300, 0 = off), `retries?` (default 2) |
-| `steps.helmDeployOverSsh` | `alpine:3.22` (+ `apk add openssh-client` at run time) | `{ source: Source, image: BuiltImage }` → `HelmRelease { release, namespace, image }` | `host` (`user@host`), `sshKey: Secret`, `release`, `namespace`, `chart` (dir in the source), `values?` (chart-relative `-f`), `set?`, `healthUrl?` |
+| `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? }`) |
 
 - `gitHubSource` downloads `https://api.github.com/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 `Dockerfile` at the tree root with `--no-push --tar-path --digest-file`, and outputs the tarball. `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.
-- `helmDeployOverSsh` streams the image tar into the host's **k3s** containerd (`nerdctl --address /run/k3s/containerd/containerd.sock --namespace k8s.io load`), copies the chart to `/tmp/<release>-helm-<namespace>`, runs `helm upgrade --install` from inside it (values, then `set`, then `image.repository`/`image.tag`/`image.pullPolicy=Never`, which always win), waits for `kubectl rollout status deploy/<release>`, and with `healthUrl` polls it (5 × 5 s) from the harness.
+- `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.
+- `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
+  steps.helmDeployOverSsh({ name: "deploy-beta", description: "", host: "oliver@bulwark-m2", sshKey: SSH_PRIVATE_KEY,
+    release: "olve-slimerepublics", namespace: "apps-beta", chart: "helm",
+    images: { server: "image", web: "web.image" }, deployments: ["olve-slimerepublics-server", "olve-slimerepublics-web"] });
+  ```
 
 **Helpers.** General functions the library steps are built on, exported for custom handlers:
 
 | Helper | What it does |
 |---|---|
 | `httpHealthCheck(ctx, url, { attempts?, delaySeconds?, headers? })` | GETs `url` until it returns 2xx (redirects followed), retrying network errors and non-2xx statuses; defaults 5 attempts, 5 s apart (v1's deploy-beta loop). Throws the last error when the attempts run out. Runs in the harness, so the image needs no curl. `helmDeployOverSsh`'s `healthUrl` uses it. |
+| `serviceUrl(release)` | `http://<release>.<namespace>.svc.cluster.local` for a `HelmRelease` (charts that name the Service after the release). |
+| `checkSpa(ctx, url)` | `GET <url>/` must reference an `/assets/*.js` bundle (Vite's layout) and the bundle must be served as JavaScript; returns `{ html, bundle }` for app-specific checks. |
+| `sshSession(ctx, { host, key })` | Installs openssh-client (apk), writes the key to `<tmpDir>/ssh/id` (trailing newline, mode 600; host key not verified) and returns `{ run(remote), text(remote), copy(local, remote), shell(remote) }`; `shell` is the quoted ssh command for pipes (`ctx.sh(`printf '%s' "$V" \| ${s.shell("kubectl apply -f -")}`)`). `helmDeployOverSsh` uses it. `shq(s)` is the POSIX quoting it uses. |
 
 ```ts
-import { httpHealthCheck, implement } from "@olve/pipelines";
+import { httpHealthCheck, implement } from "@olivervea/pipelines";
 export default implement(smoke, async (_, ctx) => { await httpHealthCheck(ctx, "http://app.ns.svc.cluster.local/api/health", { attempts: 10 }); });
 ```
 
@@ -151,7 +159,7 @@ export default implement(smoke, async (_, ctx) => { await httpHealthCheck(ctx, "
 
 ```ts
 // handlers/deploy-beta.ts
-import { implement } from "@olve/pipelines";
+import { implement } from "@olivervea/pipelines";
 import { deployBeta } from "../pipeline";
 import deployScript from "../scripts/deploy.sh" with { type: "file" };
 
@@ -164,7 +172,7 @@ export default implement(deployBeta, async ({ artifact }, ctx) => {
 
 | `ctx.` | |
 |---|---|
-| `sh(cmd \| script, { env, cwd, args })`, `sh.text(…)` | Runs a command string, or an embedded script, through the image's shell. The script is copied to `$OLVE_DIR/tmp/scripts/` first. The shell is the first of `/bin/sh`, `/busybox/sh`, `/bin/bash` that exists; a shell-less image gets a clear `ShellNotFoundError`. A script's shebang is honoured when its interpreter exists. A string counts as an embedded script when it is a `/$bunfs/…` path, or an absolute path to an existing `*.sh` or `*.bash` file. Pass `{ script }` to force script mode. A non-zero exit throws a `CommandError` that carries `exitCode`. |
+| `sh(cmd \| script, { env, cwd, args })`, `sh.text(…)` | Runs a command string, or an embedded script, through the image's shell. The script is copied to `$OLVE_DIR/tmp/scripts/` first. The shell is the first of `/bin/sh`, `/busybox/sh`, `/bin/bash` that exists; a shell-less image gets a clear `ShellNotFoundError`. A script's shebang is honoured when its interpreter exists. A string counts as an embedded script when it is a `/$bunfs/…` path, or an absolute path to an existing `*.sh` or `*.bash` file. Pass `{ script }` to force script mode. `args` are the script's arguments, or `$1`, `$2`… of a command string. A non-zero exit throws a `CommandError` that carries `exitCode`. |
 | `exec([argv…], { env, cwd, idleTimeoutSeconds })` | Runs a binary directly, with no shell (works on distroless). `idleTimeoutSeconds` (also on `sh`) is an inactivity watchdog: no stdout/stderr output for that long → SIGTERM, SIGKILL 10 s later, and a `CommandStalledError`. |
 | `readText(path)`, `readJson(path)` | Paths are relative to the cwd. |
 | `files.fetch(ref)` | Downloads a file reference and verifies its sha256. Directory refs are extracted. Returns a local path. |
@@ -197,13 +205,13 @@ export default pipeline({ name: "Olve.Pipelines", description: "…", input: M.D
 - **Stage forms.** `.stage(a)`, `.stage(a, b)`, `.stage([a, from => ({…})])` and `.stage([a, mapA], [b, mapB])` are accepted, and tuples can be mixed with plain steps. The old `.stage(step, mapper)` form is a type error and a describe error.
 - **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` needs a distinct `name` (default `"poll"`).
+- **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.
 - **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
 
 ```ts
-import { testHandler, testFileRef } from "@olve/pipelines/testing";
+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 } });
@@ -234,7 +242,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**: the GitHub push payload. **map-trigger poll**: `{"value": "<extracted value as string>"}`. |
+| `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`). |
 | `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. |
@@ -329,15 +337,16 @@ 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.
-  - Custom steps: `sha256(canonical {bundle, harness})`. `bundle` hashes the handler bundled on its own, with `pipeline.ts`, `models.ts` and `@olve/pipelines` external. It is tree-shaken and includes embedded scripts, so it changes only when that handler's code (or code it uses) changes.
+  - 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.
 - **`stages`** is an array whose items are either `{steps: [Step…]}` (parallel, with a barrier) or `{when: {field: [values]}, stages: [...]}`.
 - **`triggers`**:
   - `{kind: "push", name: "push"}`;
-  - `{kind: "poll", name, url, headers, secrets, valuePath, intervalSeconds}`, where header values may contain `$SECRET:NAME`.
+  - `{kind: "poll", name, url, headers, secrets, valuePath, intervalSeconds}`, where header values may contain `$SECRET:NAME`;
+  - `{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 and polls, sorted, as `{name, description}`.
+- **`secrets`** lists every secret used by steps, polls and webhooks, sorted, as `{name, description}`.
 
 Describe runs these checks; reconcile should re-run the manifest-level ones:
 
@@ -358,7 +367,7 @@ olve-build <pipelineDir> --out <dir> [--target bun-linux-x64|bun-linux-x64-musl]
 olve-build <pipelineDir> --hash-only          # print handler hashes (diagnostics)
 ```
 
-1. Hash every `handlers/*.ts` (see `handlerHash`).
+1. Pair each `handlers/*.ts` with the step its `implement(step, …)` names, and hash it (see `handlerHash`).
 2. Generate `<pipelineDir>/.olve/gen/handlers.ts` (a registry of literal `import()` paths, plus hashes and harness info) and `entry.ts`. Add `.olve/` to `.gitignore`.
 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.
@@ -376,9 +385,9 @@ bun install --frozen-lockfile
 bunx olve-build .pipelines --out /work/out --upload-url "$STEP_PUT_URL" --sentinels
 ```
 
-From npm (the alias), nothing else is needed. A local `file:`/`link:` dependency (`"@olve/pipelines": "file:../sdk"`, as Olve.Pipelines' own `.pipelines/` does) resolves to its **source directory**, not the copy in `node_modules`, so its own dependencies must be installed there too: the build Job runs `bun install --frozen-lockfile --production` in every local dependency of the binding's `package.json` that is inside the repo, before building.
+From npm, nothing else is needed. A local `file:`/`link:` dependency (`"@olivervea/pipelines": "file:../sdk"`, as Olve.Pipelines' own `.pipelines/` does) resolves to its **source directory**, not the copy in `node_modules`, so its own dependencies must be installed there too: the build Job runs `bun install --frozen-lockfile --production` in every local dependency of the binding's `package.json` that is inside the repo, before building.
 
-The repo depends on the SDK as a normal package. It resolves through `exports` (`@olve/pipelines`, `@olve/pipelines/harness`, `@olve/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`.
+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.
 

package/manifest.schema.json

@@ -92,7 +92,7 @@
               "type": "string"
             },
             "sdk": {
-              "description": "@olve/pipelines package version.",
+              "description": "@olivervea/pipelines package version.",
               "type": "string"
             },
             "sdkHash": {
@@ -483,6 +483,78 @@
             "intervalSeconds"
           ],
           "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "Inbound HTTP delivery to /api/hooks/<pipeline id>/<name>. Event = {headers, body}; a null mapping ignores it.",
+          "properties": {
+            "kind": {
+              "const": "webhook",
+              "type": "string"
+            },
+            "name": {
+              "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$",
+              "type": "string"
+            },
+            "verify": {
+              "oneOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "header": {
+                      "minLength": 1,
+                      "type": "string"
+                    },
+                    "prefix": {
+                      "description": "Text before the hex digest in the header, e.g. 'sha256='.",
+                      "type": "string"
+                    },
+                    "scheme": {
+                      "const": "hmac-sha256",
+                      "type": "string"
+                    },
+                    "secret": {
+                      "description": "Secret name; also the env var name in the step container.",
+                      "pattern": "^[A-Z_][A-Z0-9_]*$",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "scheme",
+                    "secret",
+                    "header",
+                    "prefix"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "scheme": {
+                      "const": "bearer",
+                      "type": "string"
+                    },
+                    "secret": {
+                      "description": "Secret name; also the env var name in the step container.",
+                      "pattern": "^[A-Z_][A-Z0-9_]*$",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "scheme",
+                    "secret"
+                  ],
+                  "type": "object"
+                }
+              ]
+            }
+          },
+          "required": [
+            "kind",
+            "name",
+            "verify"
+          ],
+          "type": "object"
         }
       ]
     },

package/package.json

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

package/src/build/build.ts

@@ -48,7 +48,7 @@ export function generateEntry(project: Project, hashes: Record<string, string>,
   writeFileSync(
     join(gen, "handlers.ts"),
     `// GENERATED by olve-build — do not edit.\n` +
-      `import type { HandlerRegistry, HarnessInfo } from "@olve/pipelines/harness";\n\n` +
+      `import type { HandlerRegistry, HarnessInfo } from "@olivervea/pipelines/harness";\n\n` +
       `export const handlers: HandlerRegistry = {\n${registry}\n};\n\n` +
       `export const handlerHashes: Record<string, string> = ${JSON.stringify(hashes, null, 2)};\n\n` +
       `export const harness: HarnessInfo = ${JSON.stringify(harness, null, 2)};\n`,
@@ -58,7 +58,7 @@ export function generateEntry(project: Project, hashes: Record<string, string>,
     entry,
     `// GENERATED by olve-build — do not edit. Entry point of the step binary.\n` +
       `import pipeline from ${JSON.stringify(relPosix(gen, project.pipelineFile))};\n` +
-      `import { runHarness } from "@olve/pipelines/harness";\n` +
+      `import { runHarness } from "@olivervea/pipelines/harness";\n` +
       `import { handlers, handlerHashes, harness } from "./handlers.ts";\n\n` +
       `process.exit(await runHarness({ pipeline, handlers, handlerHashes, harness }, process.argv.slice(2)));\n`,
   );
@@ -69,7 +69,7 @@ export async function build(dir: string, opts: BuildOptions): Promise<BuildResul
   const log = opts.log ?? ((l: string) => process.stderr.write(l + "\n"));
   const stdout = opts.stdout ?? (async (t: string) => void (await Bun.write(Bun.stdout, t)));
   const target = opts.target ?? "bun-linux-x64";
-  const project = loadProject(dir);
+  const project = await loadProject(dir);
   const out = resolve(opts.out);
   mkdirSync(out, { recursive: true });
   const harness = harnessInfo();

package/src/build/cli.ts

@@ -32,7 +32,7 @@ async function main(): Promise<number> {
   const dir = positionals[0]!;
   try {
     if (values["hash-only"]) {
-      const h = await handlerHashes(loadProject(dir), harnessInfo());
+      const h = await handlerHashes(await loadProject(dir), harnessInfo());
       await Bun.write(Bun.stdout, canonicalJson({ harness: harnessInfo(), handlers: h }));
       return 0;
     }

package/src/build/hashes.ts

@@ -22,7 +22,7 @@ function externals(project: Project): BunPlugin {
   return {
     name: "olve-handler-hash-externals",
     setup(b) {
-      b.onResolve({ filter: /^@olve\/pipelines(\/.*)?$/ }, (args) => ({ path: args.path, external: true }));
+      b.onResolve({ filter: /^@olivervea\/pipelines(\/.*)?$/ }, (args) => ({ path: args.path, external: true }));
       b.onResolve({ filter: /^\.{1,2}\// }, (args) => {
         const base = resolve(dirname(args.importer), args.path);
         for (const cand of [base, `${base}.ts`, join(base, "index.ts")]) if (contracts.has(cand)) return { path: args.path, external: true };

package/src/build/project.ts

@@ -1,6 +1,7 @@
 // Layout of a pipeline directory and the identity of the SDK building it.
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
+import { isImplementation } from "../core/handlers.ts";
 import { sha256Hex } from "../util/hash.ts";
 import type { HarnessInfo } from "../util/handler-hash.ts";
 
@@ -11,7 +12,7 @@ export interface Project {
   pipelineFile: string;
   /** Contract files (excluded from handler bundles): pipeline.ts, models.ts. */
   contractFiles: string[];
-  /** step name → absolute handler file, sorted by name. */
+  /** step name → absolute handler file, sorted by step name. The step is the one the file's `implement(step, …)` names. */
   handlers: [string, string][];
 }
 
@@ -19,20 +20,40 @@ export class ProjectError extends Error {
   override name = "ProjectError";
 }
 
-export function loadProject(dirArg: string): Project {
+export async function loadProject(dirArg: string): Promise<Project> {
   const dir = resolve(dirArg);
   if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new ProjectError(`${dirArg} is not a directory`);
   const pipelineFile = join(dir, "pipeline.ts");
   if (!existsSync(pipelineFile)) throw new ProjectError(`${join(dirArg, "pipeline.ts")} not found (it must default-export pipeline({...}))`);
   const contractFiles = ["pipeline.ts", "models.ts"].map((f) => join(dir, f)).filter((f) => existsSync(f));
   const hdir = join(dir, "handlers");
-  const handlers: [string, string][] = existsSync(hdir)
+  const files = existsSync(hdir)
     ? readdirSync(hdir)
         .filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts") && !f.endsWith(".d.ts") && statSync(join(hdir, f)).isFile())
         .sort()
-        .map((f) => [f.slice(0, -3), join(hdir, f)])
     : [];
-  return { dir, pipelineFile, contractFiles, handlers };
+  return { dir, pipelineFile, contractFiles, handlers: await resolveHandlers(hdir, files) };
+}
+
+/** Pairs each handler file with the step its default export implements (file names don't matter). */
+async function resolveHandlers(hdir: string, files: string[]): Promise<[string, string][]> {
+  const byStep = new Map<string, string>();
+  for (const f of files) {
+    const file = join(hdir, f);
+    let impl: unknown;
+    try {
+      impl = ((await import(file)) as { default?: unknown }).default;
+    } catch (e) {
+      throw new ProjectError(`handlers/${f} failed to load: ${(e as Error)?.message ?? String(e)}`);
+    }
+    if (!isImplementation(impl))
+      throw new ProjectError(`handlers/${f} must default-export implement(<step>, …); put shared code in a subfolder such as handlers/lib/`);
+    const step = (impl.step as { name: string }).name;
+    const other = byStep.get(step);
+    if (other) throw new ProjectError(`handlers/${other.slice(hdir.length + 1)} and handlers/${f} both implement step '${step}'`);
+    byStep.set(step, file);
+  }
+  return [...byStep].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
 function listFiles(dir: string): string[] {

package/src/builder/pipeline.ts

@@ -3,6 +3,7 @@ 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 { isStep } from "../core/steps.ts";
+import type { WebhookEvent, WebhookVerify } from "../core/webhooks.ts";
 import type { IsUnion, OrError, Simplify } from "../core/types.ts";
 import type { Optional } from "../core/models.ts";
 import type { FailureContext } from "../library/models.ts";
@@ -70,7 +71,7 @@ type SiblingNames<E extends readonly unknown[], K> = {
 }[number];
 
 /**
- * Per-entry check. Inference constraints (see spikes/sdk-types):
+ * Per-entry check. Inference constraints:
  *  - the [step, mapper] branch must be exactly `readonly [S, (from) => …]` — wrapping S or the whole
  *    mapper type in a conditional/intersection breaks inference of E or contextual typing of `from`;
  *    so name errors of tuple entries are reported on the mapper's return type instead;
@@ -146,7 +147,8 @@ export type TriggerNode =
       readonly valuePath: string;
       readonly intervalSeconds: number;
       readonly map: (value: string) => unknown;
-    };
+    }
+  | { readonly kind: "webhook"; readonly name: string; readonly verify: WebhookVerify; readonly map: (event: WebhookEvent) => unknown };
 
 export interface FailureHandlerNode {
   readonly step: AnyStep;
@@ -176,6 +178,11 @@ export function isPipeline(p: unknown): boolean {
 
 // ─── Pipeline builder ────────────────────────────────────────────────────────────────────────
 
+// Builder calls record into shared data and hand back a fresh handle; a handle that was already
+// extended no longer matches its type (it would claim fewer stages than the data has), so reuse is a problem.
+const extended = new WeakSet<object>();
+const ReusedProblem = "a pipeline value was extended twice: chain the calls (pipeline({...}).stage(a).stage(b)) instead of reusing an earlier value";
+
 export interface PipelineDef<In extends AnyModel> {
   /** Display name. */
   name: string;
@@ -201,10 +208,19 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     };
   }
 
+  private next(): never {
+    const data = this[PIPELINE];
+    if (extended.has(this) && !data.problems.includes(ReusedProblem)) data.problems.push(ReusedProblem);
+    extended.add(this);
+    const handle = Object.create(Object.getPrototypeOf(this)) as Pipeline<In, A>;
+    (handle as { [PIPELINE]: PipelineData })[PIPELINE] = data;
+    return handle as never;
+  }
+
   /** Map a GitHub push to the pipeline input (`z.input` view). Runs as code in a `map-trigger` Job per event. */
   onPush<R extends InferInput<In>>(map: (event: PushEvent) => Exact<R, InferInput<In>>): this {
     this[PIPELINE].triggers.push({ kind: "push", name: "push", map: map as (event: unknown) => unknown });
-    return this;
+    return this.next();
   }
 
   /**
@@ -233,7 +249,19 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
       intervalSeconds: cfg.intervalSeconds,
       map: map as (value: string) => unknown,
     });
-    return this;
+    return this.next();
+  }
+
+  /**
+   * Start a run from a delivery to `/api/hooks/<pipeline id>/<name>`, authenticated by `verify`. Map it to the
+   * pipeline input (`z.input` view), or return `null` to ignore it. Runs as code in a `map-trigger` Job per delivery.
+   */
+  onWebhook<R extends InferInput<In>>(
+    cfg: { name: string; verify: WebhookVerify },
+    map: (event: WebhookEvent) => Exact<R, InferInput<In>> | null,
+  ): this {
+    this[PIPELINE].triggers.push({ kind: "webhook", name: cfg.name, verify: cfg.verify, map: map as (event: WebhookEvent) => unknown });
+    return this.next();
   }
 
   /**
@@ -258,7 +286,7 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     });
     if (entries.length === 0) data.problems.push("empty stage");
     data.nodes.push({ kind: "stage", steps });
-    return this;
+    return this.next();
   }
 
   /** Declarative condition on literal-like pipeline-input fields. Outputs produced inside become maybe-available after. */
@@ -266,9 +294,10 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     const data = this[PIPELINE];
     const inner = new Pipeline<In, A>({ name: data.name, input: data.input as In }, data);
     const returned = block(inner);
-    if (returned !== (inner as unknown)) data.problems.push("a when block must return the pipeline it was given (p => p.stage(...))");
+    if (!isPipeline(returned) || pipelineData(returned) !== inner[PIPELINE])
+      data.problems.push("a when block must return the pipeline it was given (p => p.stage(...))");
     data.nodes.push({ kind: "when", cond: { ...(cond as object) }, nodes: inner[PIPELINE].nodes });
-    return this as never;
+    return this.next();
   }
 
   /** Run `handler` (a step whose inputs are all FailureContext) when one of `steps` (default: any) fails. Untracked, best-effort. */
@@ -281,7 +310,7 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     opts?: { steps?: readonly Step<StepNames<A>, any, any, any>[] },
   ): this {
     this[PIPELINE].failureHandlers.push({ step: handler as AnyStep, steps: opts?.steps ? [...(opts.steps as readonly AnyStep[])] : null });
-    return this;
+    return this.next();
   }
 }
 

package/src/core/webhooks.ts

@@ -0,0 +1,30 @@
+import type { Secret } from "./secrets.ts";
+
+/** How a webhook trigger authenticates deliveries. Build one with `hmacSha256`, `githubSignature` or `bearer`. */
+export type WebhookVerify =
+  | { readonly scheme: "hmac-sha256"; readonly secret: Secret; readonly header: string; readonly prefix: string }
+  | { readonly scheme: "bearer"; readonly secret: Secret };
+
+/** HMAC-SHA256 of the raw body keyed by `secret`, hex, in `header` after `prefix`. */
+export function hmacSha256(o: { secret: Secret; header: string; prefix?: string }): WebhookVerify {
+  return Object.freeze({ scheme: "hmac-sha256", secret: o.secret, header: o.header, prefix: o.prefix ?? "" });
+}
+
+/** GitHub's delivery signature: `X-Hub-Signature-256: sha256=<hex>`. */
+export function githubSignature(secret: Secret): WebhookVerify {
+  return hmacSha256({ secret, header: "X-Hub-Signature-256", prefix: "sha256=" });
+}
+
+/** `Authorization: Bearer <secret>`. */
+export function bearer(secret: Secret): WebhookVerify {
+  return Object.freeze({ scheme: "bearer", secret });
+}
+
+/**
+ * What a webhook trigger mapper receives: the request headers (lower-case names, without `authorization`
+ * and the signature header) and the body (parsed JSON, or the raw text when it isn't JSON).
+ */
+export interface WebhookEvent {
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: unknown;
+}

package/src/ctx/sh.ts

@@ -85,7 +85,8 @@ export function createSh(deps: ShDeps): { sh: Sh; exec: (argv: readonly string[]
     const scriptPath = typeof cmd === "object" ? cmd.script : isEmbeddedScript(cmd) ? cmd : undefined;
     if (scriptPath === undefined) {
       const shell = detectShell(deps.shellCandidates);
-      return { argv: [shell, "-c", cmd as string], what: `command \`${truncate(cmd as string)}\`` };
+      // `sh -c cmd sh a b`: the args are $1, $2… of the command.
+      return { argv: [shell, "-c", cmd as string, "sh", ...args], what: `command \`${truncate(cmd as string)}\`` };
     }
     const file = materialize(scriptPath);
     const first = readFileSync(file, "utf8").split("\n", 1)[0] ?? "";