tubeless 0.1.0

package/dist/workbench-ui.js

@@ -0,0 +1,262 @@
+import { stat } from "node:fs/promises";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { createRunId } from "./pipeline.js";
+import { executePipelineCommandValues, } from "./workbench-run.js";
+import { commandContext, errorMessage, loadPipelineCommand, TUBELESS_WORKBENCH_EXIT_CODE, writeUsageError, } from "./workbench-shared.js";
+const UI_USAGE = `Usage: tubeless ui [options] [studio-file]
+
+Serve the local pipeline studio from an append-only SQLite run store. Register
+definePipelineCommand modules directly or through one studio config file.
+
+Options:
+      --command <path> Register a launchable pipeline command (repeatable)
+  -e, --export <name>  Select the export when registering exactly one command
+      --store <path>    SQLite database (default: .tubeless/runs.sqlite)
+      --host <value>    Bind address (default: 127.0.0.1)
+      --port <number>   HTTP port (default: 4317)
+  -h, --help            Show this help
+`;
+function parseUiArgs(argv) {
+    return parseArgs({
+        args: [...argv],
+        allowPositionals: true,
+        options: {
+            command: { type: "string", multiple: true },
+            export: { type: "string", short: "e" },
+            help: { type: "boolean", short: "h" },
+            host: { type: "string" },
+            port: { type: "string" },
+            store: { type: "string" },
+        },
+        strict: true,
+    });
+}
+async function loadPipelineStudioConfig(fileArgument, io) {
+    const filePath = path.resolve(io.cwd, fileArgument);
+    try {
+        const fileStat = await stat(filePath);
+        if (!fileStat.isFile())
+            throw new Error(`${filePath} is not a file.`);
+        const [{ isPipelineStudioConfig }, moduleExports] = await Promise.all([
+            import("./workbench-studio.js"),
+            // SAFETY: A dynamic import of an arbitrary user module yields an untyped
+            // export namespace; every value is validated by isPipelineStudioConfig
+            // before use, so the Record<string, unknown> shape is the module boundary.
+            import(pathToFileURL(filePath).href),
+        ]);
+        const configs = Object.entries(moduleExports).filter((entry) => isPipelineStudioConfig(entry[1]));
+        const unique = configs.filter(([, value], index) => configs.findIndex(([, other]) => other === value) === index);
+        if (unique.length === 0) {
+            throw new Error("Module does not export a definePipelineStudio config.");
+        }
+        if (unique.length > 1) {
+            throw new Error(`Module exports multiple studio configs (${unique.map(([name]) => name).join(", ")}).`);
+        }
+        // SAFETY: unique[0] passed isPipelineStudioConfig, whose type guard
+        // establishes the PipelineStudioConfig shape before it is returned.
+        return { config: unique[0][1], filePath };
+    }
+    catch (error) {
+        io.stderr.write(`Error: ${errorMessage(error)}\n`);
+        return { exitCode: TUBELESS_WORKBENCH_EXIT_CODE.load };
+    }
+}
+export async function runUi(argv, io) {
+    let parsed;
+    try {
+        parsed = parseUiArgs(argv);
+    }
+    catch (error) {
+        return writeUsageError(io, errorMessage(error), UI_USAGE);
+    }
+    if (parsed.values.help) {
+        io.stdout.write(UI_USAGE);
+        return TUBELESS_WORKBENCH_EXIT_CODE.success;
+    }
+    if (parsed.positionals.length > 1) {
+        return writeUsageError(io, "Pass at most one studio config file.", UI_USAGE);
+    }
+    const directCommandFiles = parsed.values.command ?? [];
+    const studioFile = parsed.positionals[0];
+    if (parsed.values.export && (directCommandFiles.length !== 1 || studioFile)) {
+        return writeUsageError(io, "--export requires exactly one registered --command.", UI_USAGE);
+    }
+    const port = Number(parsed.values.port ?? "4317");
+    if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        return writeUsageError(io, "--port must be an integer from 0 to 65535.", UI_USAGE);
+    }
+    const specs = directCommandFiles.map((file) => {
+        const spec = {
+            cwd: io.cwd,
+            filePath: path.resolve(io.cwd, file),
+        };
+        if (parsed.values.export !== undefined) {
+            spec.exportName = parsed.values.export;
+        }
+        return spec;
+    });
+    if (studioFile) {
+        const loadedConfig = await loadPipelineStudioConfig(studioFile, io);
+        if ("exitCode" in loadedConfig)
+            return loadedConfig.exitCode;
+        const configDirectory = path.dirname(loadedConfig.filePath);
+        const configCwd = path.resolve(configDirectory, loadedConfig.config.cwd ?? ".");
+        specs.push(...loadedConfig.config.commands.map((command) => {
+            const spec = {
+                cwd: configCwd,
+                filePath: path.resolve(configDirectory, command.file),
+            };
+            if (command.export !== undefined) {
+                spec.exportName = command.export;
+            }
+            if (command.name !== undefined) {
+                spec.name = command.name;
+            }
+            return spec;
+        }));
+    }
+    const identities = new Set();
+    for (const spec of specs) {
+        const identity = `${spec.filePath}\0${spec.exportName ?? ""}`;
+        if (identities.has(identity)) {
+            return writeUsageError(io, `Command module ${JSON.stringify(spec.filePath)} is duplicated.`, UI_USAGE);
+        }
+        identities.add(identity);
+    }
+    const host = (parsed.values.host ?? "127.0.0.1").toLowerCase();
+    const isLoopbackHost = host === "127.0.0.1" || host === "::1" || host === "localhost";
+    if (specs.length > 0 && !isLoopbackHost) {
+        return writeUsageError(io, "Browser-triggered execution requires a loopback --host.", UI_USAGE);
+    }
+    const launchController = new AbortController();
+    const activeLaunches = new Set();
+    const registrations = [];
+    for (const spec of specs) {
+        const commandIo = { ...io, cwd: spec.cwd };
+        const loaded = await loadPipelineCommand(spec.filePath, spec.exportName, commandIo);
+        if ("exitCode" in loaded)
+            return loaded.exitCode;
+        if (!("parseValues" in loaded.command) ||
+            typeof loaded.command.parseValues !== "function" ||
+            !("execute" in loaded.command) ||
+            typeof loaded.command.execute !== "function") {
+            io.stderr.write(`Error: ${spec.filePath} does not support structured studio launches.\n`);
+            return TUBELESS_WORKBENCH_EXIT_CODE.load;
+        }
+        // SAFETY: the guard above verified the cross-realm loaded command exposes
+        // both parseValues and execute as functions, matching the
+        // WorkbenchStructuredPipelineCommand runtime surface.
+        const launchableCommand = loaded.command;
+        const commandName = spec.name ?? loaded.command.descriptor.name;
+        const descriptor = {
+            canPlan: true,
+            id: `${spec.filePath}#${loaded.exportName}`,
+            name: commandName,
+            parameters: loaded.command.descriptor.parameters,
+        };
+        if (loaded.command.descriptor.description !== undefined) {
+            descriptor.description = loaded.command.descriptor.description;
+        }
+        registrations.push({
+            command: launchableCommand,
+            commandIo,
+            descriptor,
+            runIdPrefix: loaded.command.descriptor.name,
+        });
+    }
+    const filename = path.resolve(io.cwd, parsed.values.store ?? ".tubeless/runs.sqlite");
+    let store;
+    let server;
+    try {
+        const { openSqlitePipelineRunStore } = await import("./run-store-sqlite.js");
+        const { startPipelineRunStudio } = await import("./run-store-ui.js");
+        store = await openSqlitePipelineRunStore(filename);
+        const commandById = new Map(registrations.map((registration) => [registration.descriptor.id, registration]));
+        const launcher = registrations.length === 0
+            ? undefined
+            : {
+                commands: registrations.map(({ descriptor }) => descriptor),
+                plan(commandId, input) {
+                    const registration = commandById.get(commandId);
+                    if (!registration?.command.plan) {
+                        throw new Error("Pipeline planning is not available for this command.");
+                    }
+                    return registration.command.plan(input);
+                },
+                async launch(commandId, values) {
+                    const registration = commandById.get(commandId);
+                    if (!registration)
+                        return { accepted: false, errors: ["Pipeline command not found."] };
+                    const runId = createRunId(registration.runIdPrefix);
+                    const pipelineContext = { runId, tracing: { exporter: store } };
+                    let parsedCommand;
+                    try {
+                        parsedCommand = registration.command.parseValues(values, commandContext(registration.commandIo, launchController.signal, pipelineContext));
+                    }
+                    catch (error) {
+                        return { accepted: false, errors: [errorMessage(error)] };
+                    }
+                    if (parsedCommand.kind === "error") {
+                        return { accepted: false, errors: parsedCommand.errors };
+                    }
+                    if (parsedCommand.kind === "help") {
+                        return { accepted: false, errors: ["Help is not a launchable value set."] };
+                    }
+                    const execution = executePipelineCommandValues(registration.command, parsedCommand.values, registration.commandIo, launchController.signal, pipelineContext);
+                    activeLaunches.add(execution);
+                    void execution.finally(() => activeLaunches.delete(execution));
+                    return { accepted: true, runId };
+                },
+            };
+        const studioOptions = {
+            host,
+            launcher,
+            port,
+            store,
+        };
+        if (isLoopbackHost) {
+            studioOptions.history = {
+                clear: () => store.clearHistory(),
+                isBusy: () => activeLaunches.size > 0,
+            };
+        }
+        server = await startPipelineRunStudio(studioOptions);
+        io.stdout.write(`Tubeless local studio: ${server.url}\n`);
+        io.stdout.write(`Run store: ${filename}\n`);
+        if (registrations.length > 0) {
+            io.stdout.write(`Launchable commands: ${registrations.map(({ descriptor }) => descriptor.name).join(", ")}\n`);
+        }
+        io.stdout.write("Press Ctrl-C to stop.\n");
+        await new Promise((resolve) => {
+            if (io.signal?.aborted) {
+                resolve();
+                return;
+            }
+            if (io.signal) {
+                io.signal.addEventListener("abort", () => resolve(), { once: true });
+                return;
+            }
+            const stop = () => {
+                process.removeListener("SIGINT", stop);
+                process.removeListener("SIGTERM", stop);
+                resolve();
+            };
+            process.once("SIGINT", stop);
+            process.once("SIGTERM", stop);
+        });
+        return TUBELESS_WORKBENCH_EXIT_CODE.success;
+    }
+    catch (error) {
+        io.stderr.write(`Error: ${errorMessage(error)}\n`);
+        return TUBELESS_WORKBENCH_EXIT_CODE.execution;
+    }
+    finally {
+        await server?.close();
+        launchController.abort(new DOMException("The local studio is stopping.", "AbortError"));
+        await Promise.allSettled(activeLaunches);
+        await store?.close();
+    }
+}
+//# sourceMappingURL=workbench-ui.js.map

package/dist/workbench-ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbench-ui.js","sourceRoot":"","sources":["../src/workbench-ui.ts"],"names":[],"mappings":"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"}

package/dist/workbench.d.ts

@@ -0,0 +1,5 @@
+import { type WorkbenchCliIo } from "./workbench-shared.js";
+export { TUBELESS_WORKBENCH_EXIT_CODE, type WorkbenchCliIo } from "./workbench-shared.js";
+/** Run the `tubeless` development workbench. Execution requires a definePipelineCommand export. */
+export declare function runWorkbenchCli(argv: readonly string[], io: WorkbenchCliIo): Promise<number>;
+//# sourceMappingURL=workbench.d.ts.map

package/dist/workbench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbench.d.ts","sourceRoot":"","sources":["../src/workbench.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,4BAA4B,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAgB1F,mGAAmG;AACnG,wBAAsB,eAAe,CACnC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,cAAc,GACjB,OAAO,CAAC,MAAM,CAAC,CAejB"}

package/dist/workbench.js

@@ -0,0 +1,43 @@
+import { runGraph } from "./workbench-graph.js";
+import { runInspect } from "./workbench-inspect.js";
+import { runPlan } from "./workbench-plan.js";
+import { runCommand } from "./workbench-run.js";
+import { TUBELESS_WORKBENCH_EXIT_CODE, writeUsageError, } from "./workbench-shared.js";
+import { runUi } from "./workbench-ui.js";
+export { TUBELESS_WORKBENCH_EXIT_CODE } from "./workbench-shared.js";
+const WORKBENCH_USAGE = `Usage: tubeless <command> [options] <pipeline-file>
+
+Inspect, plan, visualize, or safely run exported tubeless workflows.
+
+Commands:
+  tubeless inspect   Show pipeline identity and the default structural plan
+  tubeless plan      Preview step selection without executing the pipeline
+  tubeless graph     Generate Mermaid flowchart source
+  tubeless run       Execute an exported definePipelineCommand
+  tubeless ui        Open the optional local run studio
+
+Run tubeless <command> --help for command-specific options.
+`;
+/** Run the `tubeless` development workbench. Execution requires a definePipelineCommand export. */
+export async function runWorkbenchCli(argv, io) {
+    const [command, ...commandArgs] = argv;
+    if (command === "--help" || command === "-h" || command === "help") {
+        io.stdout.write(WORKBENCH_USAGE);
+        return TUBELESS_WORKBENCH_EXIT_CODE.success;
+    }
+    if (command === undefined) {
+        return writeUsageError(io, "Pass a command.", WORKBENCH_USAGE);
+    }
+    if (command === "inspect")
+        return runInspect(commandArgs, io);
+    if (command === "plan")
+        return runPlan(commandArgs, io);
+    if (command === "graph")
+        return runGraph(commandArgs, io);
+    if (command === "run")
+        return runCommand(commandArgs, io);
+    if (command === "ui")
+        return runUi(commandArgs, io);
+    return writeUsageError(io, `Unknown command ${JSON.stringify(command)}.`, WORKBENCH_USAGE);
+}
+//# sourceMappingURL=workbench.js.map

package/dist/workbench.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbench.js","sourceRoot":"","sources":["../src/workbench.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EACL,4BAA4B,EAC5B,eAAe,GAEhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE1C,OAAO,EAAE,4BAA4B,EAAuB,MAAM,uBAAuB,CAAC;AAE1F,MAAM,eAAe,GAAG;;;;;;;;;;;;CAYvB,CAAC;AAEF,mGAAmG;AACnG,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAuB,EACvB,EAAkB;IAElB,MAAM,CAAC,OAAO,EAAE,GAAG,WAAW,CAAC,GAAG,IAAI,CAAC;IACvC,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACnE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QACjC,OAAO,4BAA4B,CAAC,OAAO,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,eAAe,CAAC,EAAE,EAAE,iBAAiB,EAAE,eAAe,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC9D,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACxD,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC1D,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,UAAU,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC1D,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACpD,OAAO,eAAe,CAAC,EAAE,EAAE,mBAAmB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;AAC7F,CAAC"}

package/docs/README.md

@@ -0,0 +1,31 @@
+# `tubeless` documentation
+
+## Start here
+
+| Document                                | Use it for                                            |
+| --------------------------------------- | ----------------------------------------------------- |
+| [Package README](../README.md)          | What it is, a first example, and a pattern table      |
+| [Getting started](./getting-started.md) | Building, running, and testing a first pipeline       |
+| [Recipe index](./recipes.md)            | Choosing an executable example by intent              |
+| [Core concepts](./concepts.md)          | Dependencies, skips, failures, dry runs, and contexts |
+| [Agent guide](./agent-guide.md)         | Rules for generating and modifying pipeline code      |
+
+## How to
+
+| Document                    | Use it for                                        |
+| --------------------------- | ------------------------------------------------- |
+| [CLI](./cli.md)             | `inspect`, `plan`, `graph`, `run`, and exit codes |
+| [Local studio](./studio.md) | Optional run history, `tubeless ui`, and catalogs |
+
+## Deeper reference
+
+| Document                                                      | Use it for                                           |
+| ------------------------------------------------------------- | ---------------------------------------------------- |
+| [Child-pipeline composition](./child-pipeline-composition.md) | Opaque child and fan-out semantics                   |
+| [Generated API inventory](./api-reference.md)                 | Entrypoints, exported symbols, and surface hashes    |
+| [Machine-readable API report](./api-report.json)              | Automated public-surface review                      |
+| [Agent evaluations](./agent-evaluations.md)                   | Forward-testing the guidance against realistic tasks |
+| [LLM index](./llms.txt)                                       | Compact machine-readable documentation map           |
+
+The generated API inventory is an audit artifact, not a tutorial. Prefer the
+recipe index when deciding how to implement a workflow.

package/docs/agent-guide.md

@@ -0,0 +1,168 @@
+# Agent guide for `tubeless`
+
+Use this guide when generating or modifying pipelines, pipeline-backed scripts,
+or shared helpers in this repository.
+
+## Workflow
+
+1. Read the [recipe index](./recipes.md) and open the smallest matching example.
+2. Inspect a nearby production pipeline for domain conventions.
+3. Declare stable IDs and operational descriptions. Add `name` only when printed
+   output needs a friendlier display name.
+4. Model data dependencies before failure policy or CLI concerns.
+5. Typecheck the example or consumer, then run focused tests.
+6. Run `make check` from the package root after changing the package or its learning surface.
+
+## Primitive selection
+
+- Use `createSteps<TDomainOptions>()` once per pipeline and `definePipeline` once
+  after declaring its steps. Domain option types contain domain input only;
+  callers pass built-in controls alongside domain fields to `run(options)`, while
+  `plan(controls)` accepts controls alone.
+- Treat a `PipelineDefinitionError` during module loading as an authoring bug;
+  static graph mistakes are rejected when `definePipeline` is called.
+- Use `dependsOn` when the output is required, `optionalDependsOn` when absence
+  is expected, and `skipAfterFailureOf` for a failure gate that supplies no data.
+- Use `createSteps(optionsSchema)` when external domain options need Standard
+  Schema validation or transformation. Add `outputSchema` only at step
+  boundaries that receive untrusted or independently checked values, and
+  `resultSchema` when the finalized public result must be checked. Core imports
+  no schema library.
+- Set `dryRun: "skip"` on filesystem writes, database mutations, publication,
+  email, and other steps whose normal `run` must not execute in a dry run. Use a
+  typed `dryRun` handler when the step should produce a preview value instead.
+- Use `step.skippable` only for an intentional successful outcome. Handle its
+  resulting `T | undefined` output type explicitly.
+- Use `fromPipeline` for one independently useful child workflow and
+  `forEachPipeline` for runtime fan-out with stable keys and bounded concurrency.
+  Parent plans keep these steps opaque but expose `nestedPipeline` with the child
+  pipeline id, declared step ids, and single/fan-out mode for presentation.
+- Use `runConcurrent` for bounded lightweight functions that do not need child
+  lifecycle events.
+- Use `definePipelineCommand` for scripts centered on a pipeline. Do not parse
+  `process.argv` manually or redeclare built-in dry-run, step, or target flags.
+  Omit `mapOptions` when validated flags already satisfy same-name pipeline
+  options; provide it when names, types, defaults, or derived values differ.
+  The returned command exposes an immutable `descriptor`; UI adapters should
+  render that structured parameter contract instead of parsing help text.
+  Use `command.plan()` or `tubeless plan` for a selection-only preview. Do not
+  simulate planning with `--plan`.
+- Use `pipeline.toMermaid()` when documentation needs the static graph; do not
+  duplicate dependency edges by hand.
+- Use `tubeless inspect <pipeline-file>` for a module inventory, `tubeless plan` to
+  preview selection without domain options or execution, and `tubeless graph`
+  when generating documentation. `tubeless plan` accepts a pipeline or a marked
+  command and prefers the command when both are exported. Let the workbench
+  discover the sole matching export or pass `--export`.
+- Use `tubeless run <command-file> -- <command-args>` only for modules exporting a
+  `definePipelineCommand`. Keep application flags after `--`; the command must
+  continue to own domain validation and option mapping.
+
+## Runtime rules
+
+- Library entrypoints are ESM-only and require Node.js 22 or later. The
+  `tubeless` CLI requires Bun 1.3.14 or later (`#!/usr/bin/env bun`).
+- Use `context.log`, never direct `console` calls inside steps.
+- Pass `context.signal` into network calls, batching, retry, rate limiting, and
+  long waits. Use `context.sleep` for retry-aware or testable delays.
+- Call `context.reportProgress` for long loops and `context.reportAttempt` for
+  retries that operators should see.
+- Resolve relative files from `context.cwd`; prefer helpers from
+  `tubeless/node`.
+- Use `runOrThrow` when every step must succeed and the caller expects a value.
+  It always throws for an unsuccessful run, including `continueOnError` runs.
+  Use `run` when the caller must inspect failures, skips, timings, or best-effort
+  output. Its versioned `PipelineRun` exposes `runId`, terminal status and
+  timestamps, errors, and timestamped step reports with correlated attempt IDs;
+  structural skips have no attempt ID or start timestamp. Use hooks or tracing
+  for streaming logs and progress. Use `plan` when nothing may run.
+- Declare supported downstream goals with `targets: [step]` on
+  `definePipeline`, then select their literal IDs through run controls. Required
+  inputs and failure gates are selected recursively. Use `stepIds` only when
+  exact low-level filtering of any step is intentional; never combine the two.
+- Read `PipelinePlanStep.selectionReasons` when explaining selection. It already
+  includes originating targets and immediate dependents; do not reconstruct
+  provenance by walking dependency arrays in application or CLI code. Use
+  `renderPipelinePlan` from `tubeless/render` for shared human or JSON output
+  instead of maintaining another selection-reason formatter. Use
+  `createPipelineReporter` / `createRunReporter` from `tubeless/reporter` for
+  TTY presentation; do not import reporters from the root kernel.
+- Use focused hooks for ordinary observation: `onStepStart`,
+  `onStepProgress`, `onStepComplete`, `onStepSkip`, `onStepCancel`, and
+  `onStepFail`. Their event metadata is already narrowed. Use additive
+  `onStepStatus` only when one consumer genuinely needs the whole discriminated
+  lifecycle, such as a status-aware renderer or event store.
+- Use `createPipelineTestRuntime` from `tubeless/testing` for deterministic
+  pipeline tests. Inspect its structured logs, statuses, and latest progress;
+  keep test-framework matchers outside the package.
+- Branch on `PipelineError.code`, `phase`, and `kind`, never message prose.
+  Underlying thrown codes live in `sourceCode`. Failed and cancelled reports
+  expose the structured error under `error`; skipped reports expose `reason`,
+  optional `message`, and optional `dependencyId`. `PipelineError.cause` is a
+  bounded JSON-safe snapshot; a thrown `PipelineExecutionError` retains the
+  original value through native `Error.cause`. Use `renderPipelineError` when a
+  diagnostic crosses a human or JSON presentation boundary.
+- Standard Schema failures use `kind: "validation"`, retain normalized `issues`,
+  and have boundary-specific codes for options, step outputs, and final results.
+  Async schemas run during `run`; synchronous `plan()` previews graph and
+  selection only and never invokes schemas.
+- Wrap normal finalizers in `requireOutputs` when a valid result requires
+  specific step outputs. Use a plain finalizer only when partial output is a
+  valid domain result.
+- Preserve the dependency-free runtime. Keep application telemetry SDKs at the
+  exporter boundary.
+- Keep durable local observation opt-in. Use the append-only adapter from
+  `tubeless/run-store/sqlite` or `tubeless run --store`; do not make pipeline
+  definitions depend on storage or the studio.
+- Use `createPipelineRunProjector` from `tubeless/run-store` when a custom
+  reader pages `listEvents({ afterId })`. Append each newer page and call
+  `snapshot()`; a refresh with no new ids returns the cached view. Duplicate
+  and out-of-order ids are ignored; `0` is a valid first id. Use
+  `projectPipelineRunStore` only for a one-shot fold of a complete list. See
+  [`local-observability.ts`](../examples/local-observability.ts).
+- Pass caller-owned `runId` and `parentRunId` values through `PipelineContext`
+  when joining an external execution tree. Do not derive correlation from step
+  IDs or timestamps.
+- Treat `tubeless ui` as a local projection with no execution capability by
+  default. Use `definePipelineStudio` for a checked-in command catalog, and
+  register only explicit `definePipelineCommand` modules; never make execution
+  require the studio server or infer executable modules from observed history.
+
+## Failure and safety rules
+
+- Do not use `step.skippable` to swallow an exception.
+- Do not treat dry run as rollback; external side effects require
+  `dryRun: "skip"` or a side-effect-free custom `dryRun` handler.
+- Do not publish after a failed or cancelled validation step. Make validation
+  required, or use `skipAfterFailureOf` when its output is intentionally optional;
+  the gate blocks both unsuccessful terminal statuses.
+- Do not hide absent required finalizer outputs behind defaults. Declare them
+  with `requireOutputs`; handle optional outputs explicitly.
+- Keep step IDs stable because reports, hooks, traces, and CLI selection use them.
+- Treat `name` as presentation only. Dependencies, outputs, traces, and CLI
+  selection continue to use the stable step ID.
+
+## Required references
+
+- Read [core concepts](./concepts.md) for skip, failure, or selection changes.
+- Read [the CLI](./cli.md) for inspect, plan, graph, run, and exit codes.
+- Read [the studio](./studio.md) before changing `tubeless ui` or
+  `definePipelineStudio`.
+- Read [child composition](./child-pipeline-composition.md) before changing child
+  propagation, progress, or parent/child selection.
+- Read the relevant executable example linked from the
+  [recipe index](./recipes.md) before writing new usage.
+- Use the [generated API inventory](./api-reference.md) only to verify exports;
+  it is not implementation guidance.
+
+## Validation
+
+For package changes:
+
+```sh
+make check
+```
+
+For a consumer-only change, run its focused tests and the repository typecheck.
+If the public surface changes intentionally, regenerate the checked API artifacts
+with `bun run api:generate` from the package root.