@pond-ts/process 0.61.0 → 0.62.0

package/API.md

@@ -521,31 +521,31 @@ Typed dataflow graphs for pipelines whose **shape is data** (runtime-assembled,
 user-edited, one computation fanned out to several consumers). Chaining stays
 the default for pipelines known at authoring time — see the package README.
 
-| Group                   | Exports                                                                                                                                                                                                                                                                                                                                                                                                          | Source                                               |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| Worker pool (Node)      | `HostPool` (`start`, `run`, `close`, `size`, `inFlight`); types `HostPoolOptions`, `PoolSetup`, `PoolSetupConfig`; `toWire` / `fromWire`, types `WireResult`, `WireColumn` — subpath `@pond-ts/process/pool`                                                                                                                                                                                                     | `packages/process/src/pool/index.ts`                 |
-| Ports                   | `Inlet`, `Outlet` (typed fields on `node.in` / `node.out`; `get()`, `peek()`, `version`, `connect`, `disconnect`)                                                                                                                                                                                                                                                                                                | `packages/process/src/port.ts`                       |
-| Nodes                   | `Node` (`in`, `out`, `dirty`, `error`, `invalidate()`), `defineNode` (reusable multi-output node type), `derive` (single-output, wired inline)                                                                                                                                                                                                                                                                   | `packages/process/src/node.ts`                       |
-| Port declaration        | `port<T>({ equals, defaultValue })`; types `PortSpec`, `PortSpecMap`, `PortValue`, `PortValues`                                                                                                                                                                                                                                                                                                                  | `packages/process/src/types.ts`                      |
-| Sources                 | `source<T>()` → `SourceNode` (`set()`), `fromLive(liveSource)` → `LiveSourceNode` (`dispose()`); `GraphSource` (bind contract — looser than core's `LiveSource`, accepts `LiveAggregation`), `SnapshotSource`, `NoInputs`                                                                                                                                                                                        | `packages/process/src/source.ts`                     |
-| Graph view              | `Graph` (`Graph.from(...roots)`, `nodes`, `order()`, `edges()`, `toJSON()`); types `GraphEdge`, `GraphJson`, `GraphNodeJson`, `GraphEdgeJson`                                                                                                                                                                                                                                                                    | `packages/process/src/graph.ts`                      |
-| Range output buffers    | `prepareRange(length, keep, prior)` → `RangeOutput` (`values`, `bits`, `set`, `clear`) carrying `[0, keep)` forward as blocks — values **and** validity; `sealRange(out, length)` → `Float64Column`; `validityByteCount`. Reached from an op as `ctx.out[n]`                                                                                                                                                     | `packages/process/src/column.ts`                     |
-| Ranged recompute        | `graph.setSourceFrom(series, changedFrom)` — declares which row first changed; `graph.recomputes` → `{ ranged, full }`. An op opts in with `OpDef.runRange(ctx)`, receiving `{ from, to, previous, previousView, out }` (type `RangeContext`) — write into `out` and return nothing for the block path alongside the usual context. Requires `lookback`. Falls back to a full `run` whenever anything is missing | `packages/process/src/plan/graph.ts`                 |
-| Node budget             | `bind(series, { registry, budgetBytes })` — engine-wide cap on retained node values, LRU, enforced after each `run`; `graph.retainedBytes` / `graph.evictions` / `graph.enforceBudget()`. Unbounded when omitted. Skips a node whose consumer still holds its outlet                                                                                                                                             | `packages/process/src/plan/graph.ts`                 |
-| Plan history            | `requiredHistory(registry, plan)` → `{ known, rows?, undeclared, byOp }` — the minimum safe tail in rows, folded from per-op `OpDef.lookback`. Sums along nesting, maxes across siblings. `known: false` names ops with no declared lookback rather than defaulting to zero (type `HistoryResult`)                                                                                                               | `packages/process/src/plan/history.ts`               |
-| Column values           | `packColumn` (values → packed `Float64Column`, NaN = missing), `columnBytes` (retained size, for a byte budget), `appendColumn` (column → series; boxing-free when gapless), `columnBuffers` / `columnFromBuffers` (the buffer pair a column is, for an isolate boundary; type `ColumnBuffers`), `columnView` (zero-copy borrowed read view for in-process folds; type `ColumnView`)                             | `packages/process/src/column.ts`                     |
-| Plan — registry         | `createRegistry({ folds })` / `Registry` (`define`, `get`, `foldFor`, `outputsOf`, `resolveParams`, `byFamily`, `describe`, `toJsonSchema`), param builders `int` / `num` / `choice` / `flag`, `UnknownOpError`, `ParamError`                                                                                                                                                                                    | `packages/process/src/plan/registry.ts`, `params.ts` |
-| Plan — identity         | `specId` (content-addressed, param-order invariant, defaults materialized), `refToId`, `explain`, `unitOf`, `columnsOf`, `dependsOn`, `outputKey`                                                                                                                                                                                                                                                                | `packages/process/src/plan/identity.ts`              |
-| Plan — types            | `Spec`, `Plan`, `Input` (column name \| `Spec` \| `PickedOutput`), `SpecRef`, `Def` (`OpDef` \| `FoldDef`), `OpContext`, `OpResult`, `FoldContext`, `FactBody`, `isFold`, `ParamDef`, `Params`, `Units`, `InputDef`, `OutputDef`                                                                                                                                                                                 | `packages/process/src/plan/types.ts`                 |
-| Plan — bind / run       | `bind(series, { registry, units })` → `BoundGraph` (`compile`, `setSource`, `ids`, `series`, `columnOf`), `run(graph, { plan, select, onError })` → `RunResult`, `UnitError`                                                                                                                                                                                                                                     | `packages/process/src/plan/graph.ts`, `run.ts`       |
-| Plan — request/response | `RunRequest` (`PlanRequest` \| `SlotRequest`), `RunOptions`, `RunResult`, `Select` (`{ on, output?, name? }` — points at a node; what comes back is what that node produces), `ErrorPolicy`, `Fact` (carries `op`), `OutputInfo`, `Skipped`, `NodeTiming` (`slot`, `pulled`, `cached`, `ms`, `inputs`)                                                                                                           | `packages/process/src/plan/run.ts`                   |
-| Plan — host             | `createHost({ registry, units, sources })` → `Host` (`add`, `has`, `datasets`, `graphFor`, `run`, `runAsync`), `toWire`, `UnknownDatasetError`; local-string `Envelope` (`PlanEnvelope` \| `SlotEnvelope`), remote-capable `AsyncEnvelope` (`AsyncPlanEnvelope` \| `AsyncSlotEnvelope` \| `Envelope`), `DatasetInfo`, `WireResult`                                                                               | `packages/process/src/plan/host.ts`                  |
-| Plan — slots            | `expandSlots(slots, columns)` → `Map<slot, Spec>` (expands to the nested form, so ids match by construction; `slot#Output` picks one output), `SlotError`; types `SlotDef` (`{ op, params, in }`), `Slots`                                                                                                                                                                                                       | `packages/process/src/plan/slots.ts`                 |
-| Plan — builder          | `plan(from)` → low-level `PlanBuilder`; `process(registry, from)` → typed fluent `ProcessBuilder` (`column`, op methods, `outputs`), `BuilderError`; types `NodeHandle`, `OutputHandle`, `FluentColumnRef`, `SingleColumnNode`, `MultiColumnNode`, `ColumnSelection`, `FactRef`, `BuiltRequest`                                                                                                                  | `packages/process/src/plan/builder.ts`, `fluent.ts`  |
-| Plan — async sources    | `defineSource({ name, load })`, `createSourceRegistry()` / `SourceRegistry`, `sourceId`, `UnknownSourceError`; types `SourceRef`, `SourceParams`, `LoadedSource` (value + revision), `SourceLoadContext`, `SourceDef`                                                                                                                                                                                            | `packages/process/src/plan/source.ts`                |
-| Plan — folds            | `STANDARD_FOLDS` and the four it holds — `last`, `extremes`, `percentileRank`, `shape` — pre-registered by `createRegistry()`; each a plain `FoldDef`, so a consumer can `define` over one                                                                                                                                                                                                                       | `packages/process/src/plan/folds.ts`                 |
-| Errors                  | `ProcessError` (base), `CycleError`, `UnconnectedInputError`, `MissingOutputError`, `UnsetSourceError`                                                                                                                                                                                                                                                                                                           | `packages/process/src/errors.ts`                     |
-| Node type helpers       | `NodeSpec`, `NodeFactory`, `InletsFor`, `OutletsFor`, `OutletValue`, `SpecsForOutlets`, `DerivedOutput`                                                                                                                                                                                                                                                                                                          | `packages/process/src/node.ts`                       |
+| Group                   | Exports                                                                                                                                                                                                                                                                                                                                                                                                               | Source                                               |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| Worker pool (Node)      | `HostPool` (`start`, `run`, `close`, `size`, `inFlight`); types `HostPoolOptions`, `PoolSetup`, `PoolSetupConfig`; `toWire` / `fromWire`, types `WireResult`, `WireColumn` — subpath `@pond-ts/process/pool`                                                                                                                                                                                                          | `packages/process/src/pool/index.ts`                 |
+| Ports                   | `Inlet`, `Outlet` (typed fields on `node.in` / `node.out`; `get()`, `peek()`, `version`, `connect`, `disconnect`)                                                                                                                                                                                                                                                                                                     | `packages/process/src/port.ts`                       |
+| Nodes                   | `Node` (`in`, `out`, `dirty`, `error`, `invalidate()`), `defineNode` (reusable multi-output node type), `derive` (single-output, wired inline)                                                                                                                                                                                                                                                                        | `packages/process/src/node.ts`                       |
+| Port declaration        | `port<T>({ equals, defaultValue })`; types `PortSpec`, `PortSpecMap`, `PortValue`, `PortValues`                                                                                                                                                                                                                                                                                                                       | `packages/process/src/types.ts`                      |
+| Sources                 | `source<T>()` → `SourceNode` (`set()`), `fromLive(liveSource)` → `LiveSourceNode` (`dispose()`); `GraphSource` (bind contract — looser than core's `LiveSource`, accepts `LiveAggregation`), `SnapshotSource`, `NoInputs`                                                                                                                                                                                             | `packages/process/src/source.ts`                     |
+| Graph view              | `Graph` (`Graph.from(...roots)`, `nodes`, `order()`, `edges()`, `toJSON()`); types `GraphEdge`, `GraphJson`, `GraphNodeJson`, `GraphEdgeJson`                                                                                                                                                                                                                                                                         | `packages/process/src/graph.ts`                      |
+| Range output buffers    | `prepareRange(length, keep, prior)` → `RangeOutput` (`values`, `bits`, `set`, `clear`) carrying `[0, keep)` forward as blocks — values **and** validity; `sealRange(out, length)` → `Float64Column`; `validityByteCount`. Reached from an op as `ctx.out[n]`                                                                                                                                                          | `packages/process/src/column.ts`                     |
+| Ranged recompute        | `graph.setSourceFrom(series, changedFrom)` — declares which row first changed; `graph.recomputes` → `{ ranged, full }`. An op opts in with `OpDef.runRange(ctx)`, receiving `{ from, to, previous, previousView, out }` (type `RangeContext`) — write into `out` and return nothing for the block path alongside the usual context. Requires `lookback`. Falls back to a full `run` whenever anything is missing      | `packages/process/src/plan/graph.ts`                 |
+| Node budget             | `bind(series, { registry, budgetBytes })` — engine-wide cap on retained node values, LRU, enforced after each `run`; `graph.retainedBytes` / `graph.evictions` / `graph.enforceBudget()`. Unbounded when omitted. Skips a node whose consumer still holds its outlet                                                                                                                                                  | `packages/process/src/plan/graph.ts`                 |
+| Plan history            | `requiredHistory(registry, plan)` → `{ known, rows?, undeclared, byOp }` — the minimum safe tail in rows, folded from per-op `OpDef.lookback`. Sums along nesting, maxes across siblings. `known: false` names ops with no declared lookback rather than defaulting to zero (type `HistoryResult`)                                                                                                                    | `packages/process/src/plan/history.ts`               |
+| Column values           | `packColumn` (values → packed `Float64Column`, NaN = missing), `columnBytes` (retained size, for a byte budget), `appendColumn` (column → series; boxing-free when gapless), `columnBuffers` / `columnFromBuffers` (the buffer pair a column is, for an isolate boundary; type `ColumnBuffers`), `columnView` (zero-copy borrowed read view for in-process folds; type `ColumnView`)                                  | `packages/process/src/column.ts`                     |
+| Plan — registry         | `createRegistry({ folds })` / `Registry` (`define`, `get`, `foldFor`, `outputsOf`, `resolveParams` (`{ validate: false }` applies defaults and skips every check), `byFamily`, `describe`, `toJsonSchema`), param builders `int` / `num` / `choice` / `flag`, `UnknownOpError`, `ParamError`                                                                                                                          | `packages/process/src/plan/registry.ts`, `params.ts` |
+| Plan — identity         | `specId(registry, spec, { validate })` (content-addressed, param-order invariant, defaults materialized; `validate: false` is **total** — names a spec that would not compile in a separate `p1?:` namespace that cannot collide with a valid id; a valid spec's id is identical either way), `SpecIdOptions`, `refToId`, `explain`, `unitOf`, `columnsOf`, `dependsOn`, `outputKey`                                  | `packages/process/src/plan/identity.ts`              |
+| Plan — types            | `Spec`, `Plan`, `Input` (column name \| `Spec` \| `PickedOutput`), `SpecRef`, `Def` (`OpDef` \| `FoldDef`), `OpContext`, `OpResult`, `FoldContext`, `FactBody`, `isFold`, `ParamDef`, `Params`, `Units`, `InputDef`, `OutputDef`                                                                                                                                                                                      | `packages/process/src/plan/types.ts`                 |
+| Plan — bind / run       | `bind(series, { registry, units })` → `BoundGraph` (`compile`, `setSource`, `ids`, `series`, `columnOf`), `run(graph, { plan, select, onError })` → `RunResult`, `UnitError`, `UnknownColumnError` (a raw string input naming no column of the bound series, checked over the whole closure and re-checked on the warm path)                                                                                          | `packages/process/src/plan/graph.ts`, `run.ts`       |
+| Plan — request/response | `RunRequest` (`PlanRequest` \| `SlotRequest`), `RunOptions`, `RunResult`, `Select` (`{ on, output?, name? }` — points at a node; what comes back is what that node produces), `ErrorPolicy`, `Fact` (carries `op`), `OutputInfo`, `Skipped` (`spec`, `select`, `reason`, `code` — the failure's kind, matching the error class a throw would have carried), `NodeTiming` (`slot`, `pulled`, `cached`, `ms`, `inputs`) | `packages/process/src/plan/run.ts`                   |
+| Plan — host             | `createHost({ registry, units, sources })` → `Host` (`add`, `has`, `datasets`, `graphFor`, `run`, `runAsync`), `toWire`, `UnknownDatasetError`; local-string `Envelope` (`PlanEnvelope` \| `SlotEnvelope`), remote-capable `AsyncEnvelope` (`AsyncPlanEnvelope` \| `AsyncSlotEnvelope` \| `Envelope`), `DatasetInfo`, `WireResult`                                                                                    | `packages/process/src/plan/host.ts`                  |
+| Plan — slots            | `expandSlots(slots, columns)` → `Map<slot, Spec>` (expands to the nested form, so ids match by construction; `slot#Output` picks one output), `SlotError`; types `SlotDef` (`{ op, params, in }`), `Slots`                                                                                                                                                                                                            | `packages/process/src/plan/slots.ts`                 |
+| Plan — builder          | `plan(from)` → low-level `PlanBuilder`; `process(registry, from)` → typed fluent `ProcessBuilder` (`column`, op methods, `outputs`), `BuilderError`; types `NodeHandle`, `OutputHandle`, `FluentColumnRef`, `SingleColumnNode`, `MultiColumnNode`, `ColumnSelection`, `FactRef`, `BuiltRequest`                                                                                                                       | `packages/process/src/plan/builder.ts`, `fluent.ts`  |
+| Plan — async sources    | `defineSource({ name, load })`, `createSourceRegistry()` / `SourceRegistry`, `sourceId`, `UnknownSourceError`; types `SourceRef`, `SourceParams`, `LoadedSource` (value + revision), `SourceLoadContext`, `SourceDef`                                                                                                                                                                                                 | `packages/process/src/plan/source.ts`                |
+| Plan — folds            | `STANDARD_FOLDS` and the four it holds — `last`, `extremes`, `percentileRank`, `shape` — pre-registered by `createRegistry()`; each a plain `FoldDef`, so a consumer can `define` over one                                                                                                                                                                                                                            | `packages/process/src/plan/folds.ts`                 |
+| Errors                  | `ProcessError` (base; `code` — a stable per-class literal, minification-proof, also surfaced on `Skipped`), `CycleError`, `UnconnectedInputError`, `MissingOutputError`, `UnsetSourceError`                                                                                                                                                                                                                           | `packages/process/src/errors.ts`                     |
+| Node type helpers       | `NodeSpec`, `NodeFactory`, `InletsFor`, `OutletsFor`, `OutletValue`, `SpecsForOutlets`, `DerivedOutput`                                                                                                                                                                                                                                                                                                               | `packages/process/src/node.ts`                       |
 
 Note: this package's `npm test` includes a `test:dts` step that typechecks the
 **emitted** `dist/*.d.ts` from a consumer's perspective (`test-dts/`,

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 under a single `v*` tag, so this file covers them all. Pre-1.0: minor bumps may
 include new features and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pond-ts/pond/compare/v0.61.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.62.0...HEAD
+[0.62.0]: https://github.com/pond-ts/pond/compare/v0.61.0...v0.62.0
 [0.61.0]: https://github.com/pond-ts/pond/compare/v0.60.0...v0.61.0
 [0.60.0]: https://github.com/pond-ts/pond/compare/v0.59.0...v0.60.0
 [0.59.0]: https://github.com/pond-ts/pond/compare/v0.58.0...v0.59.0
@@ -64,6 +65,69 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.62.0] — 2026-08-16
+
+### Added
+
+- `@pond-ts/process`: **`specId` is total under `{ validate: false }`** — a
+  third options argument that names a spec which would not compile
+  (`specId(registry, spec, { validate: false })`). Identity used to be coupled
+  to validity, so the moments a consumer most needs an id — labelling the chip
+  it is skipping, keying "this persisted entry is broken", logging what was
+  rejected — were exactly the moments it threw, leaving the consumer to
+  re-implement canonicalization or carry a second key. Lenient mode still
+  applies defaults and sorts keys, carries an undeclared param through rather
+  than dropping it, and recurses into nested inputs; **a valid spec has the
+  same id under either mode**, so nothing needs a second cache line. Validity
+  stays `compile`'s job. `Registry.resolveParams` takes the same
+  `{ validate: false }`.
+
+  An id that did **not** validate is minted in a separate namespace — marked
+  `p1?:` instead of `p1:`, with type-preserving param encoding — so it can
+  never collide with a legal id. Both measures are confined to that branch:
+  a valid id is byte-identical to what shipped in 0.61.0. The mark rides up a
+  chain, so a spec over an unvalidated input is unvalidated too.
+
+- `@pond-ts/process`: **`Skipped.code`** — every entry in `RunResult.skipped`
+  now carries the failure's kind (`'UnknownColumnError'`, `'ParamError'`,
+  `'UnitError'`, `'SlotError'`, …) beside its human `reason`. Under
+  `onError: 'skip' | 'collect'` nothing is thrown, so `instanceof` — the right
+  discriminator when a consumer catches — never reached a consumer reading
+  `skipped`, leaving it to match on prose whose wording is not a contract. The
+  value is `ProcessError.code`, a **literal declared per class** rather than
+  `constructor.name`, so a consumer's minifier cannot silently rename it. It is
+  absent when the throw did not come from this package, which is itself the
+  signal: op code failed, not the plan layer.
+
+### Fixed
+
+- `@pond-ts/process`: **`run` under `onError: 'throw'` — the default — now
+  raises the original error rather than a base `ProcessError` rebuilt from its
+  message.** A caught `UnknownColumnError`, `ParamError`, `UnitError` or
+  `SlotError` reached the caller as a bare `ProcessError`, so `instanceof`
+  could not discriminate on the throw path at all.
+
+- `@pond-ts/process`: **a raw string input naming a column the bound series
+  does not carry is now rejected**, at `compile`, with a new
+  `UnknownColumnError`. Nothing checked it at compile or at pull: the op ran
+  against an un-widened series, and one that doesn't defend its own inputs
+  appended a plausible-looking column of garbage under the spec's id — with
+  `skipped` empty and `onError` never engaged. A persisted plan citing a column
+  the feed has since dropped now skips (or throws) instead of returning a
+  value. The check is the one `expandSlots` already made against the same
+  column list, so the two request forms no longer disagree; it runs before the
+  unit check, whose "is 'unitless'" answer for an absent column named the wrong
+  problem. The key/time column is not a value column and is rejected too.
+
+  The check covers the **whole spec closure** (a missing column under a typed
+  parent otherwise surfaced as `UnitError`) and runs on the **warm** path as
+  well as the cold one — `setSource` replaces the data under compiled nodes by
+  design, so a memoized node could outlive the column it reads and go on
+  emitting the garbage column this fix exists to prevent. A node that fails the
+  re-check is dropped from the graph.
+  (Both items reported by Tidal —
+  `docs/notes/tidal-process-adoption-friction-2026-08.md`.)
+
 ## [0.61.0] — 2026-08-16
 
 ### Added

package/dist/errors.d.ts

@@ -1,6 +1,38 @@
 /** Errors thrown by the graph engine. */
-/** Base class for every error this package throws. */
+/**
+ * Base class for every error this package throws.
+ *
+ * ## Why there is a `code` beside `name`
+ *
+ * `instanceof` is the right discriminator when a consumer **catches**.
+ * But `run` under `onError: 'skip' | 'collect'` does not hand the error
+ * back — it reports a `Skipped` record — and a consumer branching
+ * its UI on the failure kind (a dropped feed column is a dimmed chip; a
+ * bad persisted param is a broken one) then has only prose to go on
+ * (Tidal, `docs/notes/tidal-process-adoption-friction-2026-08.md`).
+ *
+ * Every subclass annotates `code` as `: string` rather than letting the
+ * literal type be inferred. Without it the static's type is the literal
+ * — `ParamError.code: 'ParamError'` — and a **consumer** subclassing to
+ * add its own code fails to compile with TS2417, which would make this
+ * additive field a source break for anyone already extending these
+ * classes (Codex, PR #667).
+ *
+ * `code` is that discriminator, and it is a **literal string per class**
+ * rather than `constructor.name` because a consumer's minifier may
+ * rename the class — leaving `name` as `'t'` in a production build,
+ * silently, which is exactly the shape of bug the string exists to let
+ * them avoid. Declared once as a `static`, read here through
+ * `new.target`, so a subclass states its code on one line.
+ */
 export declare class ProcessError extends Error {
+    /** The literal a subclass overrides. Read via `new.target`, not `this`. */
+    static readonly code: string;
+    /**
+     * Stable kind, safe to compare against a literal and to send over a
+     * wire. Rides on `Skipped.code` when a run reports rather than throws.
+     */
+    readonly code: string;
     constructor(message: string);
 }
 /**
@@ -9,14 +41,17 @@ export declare class ProcessError extends Error {
  * so a cycle surfaces at the line that wires it, not at some later pull.
  */
 export declare class CycleError extends ProcessError {
+    static readonly code: string;
 }
 /** Thrown when pulling through an inlet with no connection and no default. */
 export declare class UnconnectedInputError extends ProcessError {
+    static readonly code: string;
 }
 /**
  * Thrown when a node's `compute` omits a declared output, or when an
  * outlet is read before anything has produced a value for it.
  */
 export declare class MissingOutputError extends ProcessError {
+    static readonly code: string;
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -1,9 +1,42 @@
 /** Errors thrown by the graph engine. */
-/** Base class for every error this package throws. */
+/**
+ * Base class for every error this package throws.
+ *
+ * ## Why there is a `code` beside `name`
+ *
+ * `instanceof` is the right discriminator when a consumer **catches**.
+ * But `run` under `onError: 'skip' | 'collect'` does not hand the error
+ * back — it reports a `Skipped` record — and a consumer branching
+ * its UI on the failure kind (a dropped feed column is a dimmed chip; a
+ * bad persisted param is a broken one) then has only prose to go on
+ * (Tidal, `docs/notes/tidal-process-adoption-friction-2026-08.md`).
+ *
+ * Every subclass annotates `code` as `: string` rather than letting the
+ * literal type be inferred. Without it the static's type is the literal
+ * — `ParamError.code: 'ParamError'` — and a **consumer** subclassing to
+ * add its own code fails to compile with TS2417, which would make this
+ * additive field a source break for anyone already extending these
+ * classes (Codex, PR #667).
+ *
+ * `code` is that discriminator, and it is a **literal string per class**
+ * rather than `constructor.name` because a consumer's minifier may
+ * rename the class — leaving `name` as `'t'` in a production build,
+ * silently, which is exactly the shape of bug the string exists to let
+ * them avoid. Declared once as a `static`, read here through
+ * `new.target`, so a subclass states its code on one line.
+ */
 export class ProcessError extends Error {
+    /** The literal a subclass overrides. Read via `new.target`, not `this`. */
+    static code = 'ProcessError';
+    /**
+     * Stable kind, safe to compare against a literal and to send over a
+     * wire. Rides on `Skipped.code` when a run reports rather than throws.
+     */
+    code;
     constructor(message) {
         super(message);
         this.name = new.target.name;
+        this.code = new.target.code;
     }
 }
 /**
@@ -12,14 +45,17 @@ export class ProcessError extends Error {
  * so a cycle surfaces at the line that wires it, not at some later pull.
  */
 export class CycleError extends ProcessError {
+    static code = 'CycleError';
 }
 /** Thrown when pulling through an inlet with no connection and no default. */
 export class UnconnectedInputError extends ProcessError {
+    static code = 'UnconnectedInputError';
 }
 /**
  * Thrown when a node's `compute` omits a declared output, or when an
  * outlet is read before anything has produced a value for it.
  */
 export class MissingOutputError extends ProcessError {
+    static code = 'MissingOutputError';
 }
 //# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -41,8 +41,9 @@ export type { DefMap } from './plan/registry.js';
 export { isFold } from './plan/types.js';
 export { STANDARD_FOLDS, last, extremes, percentileRank, shape, } from './plan/folds.js';
 export type { OpDescriptor } from './plan/registry.js';
+export type { SpecIdOptions } from './plan/identity.js';
 export { specId, refToId, explain, unitOf, columnsOf, dependsOn, outputKey, } from './plan/identity.js';
-export { bind, BoundGraph, UnitError } from './plan/graph.js';
+export { bind, BoundGraph, UnitError, UnknownColumnError, } from './plan/graph.js';
 export { expandSlots, SlotError } from './plan/slots.js';
 export { plan, PlanBuilder, BuilderError } from './plan/builder.js';
 export type { NodeHandle, OutputHandle, InputRef, BuiltRequest, } from './plan/builder.js';

package/dist/index.js

@@ -35,7 +35,7 @@ export { UnknownOpError, ParamError } from './plan/registry.js';
 export { isFold } from './plan/types.js';
 export { STANDARD_FOLDS, last, extremes, percentileRank, shape, } from './plan/folds.js';
 export { specId, refToId, explain, unitOf, columnsOf, dependsOn, outputKey, } from './plan/identity.js';
-export { bind, BoundGraph, UnitError } from './plan/graph.js';
+export { bind, BoundGraph, UnitError, UnknownColumnError, } from './plan/graph.js';
 export { expandSlots, SlotError } from './plan/slots.js';
 export { plan, PlanBuilder, BuilderError } from './plan/builder.js';
 export { process, ProcessBuilder } from './plan/fluent.js';

package/dist/plan/builder.d.ts

@@ -43,6 +43,7 @@ import type { Slots } from './slots.js';
 import type { ParamValue } from './types.js';
 /** Thrown when a graph is built wrong — before it is ever sent. */
 export declare class BuilderError extends ProcessError {
+    static readonly code: string;
 }
 /**
  * The derived slot for a fold over `on` — a function of the node, the

package/dist/plan/builder.js

@@ -39,6 +39,7 @@
 import { ProcessError } from '../errors.js';
 /** Thrown when a graph is built wrong — before it is ever sent. */
 export class BuilderError extends ProcessError {
+    static code = 'BuilderError';
 }
 /**
  * The derived slot for a fold over `on` — a function of the node, the

package/dist/plan/graph.d.ts

@@ -15,6 +15,16 @@ import type { Registry } from './registry.js';
 import { type FactBody, type Params, type Spec, type Units } from './types.js';
 /** Thrown when an op demands an input unit its source does not carry. */
 export declare class UnitError extends ProcessError {
+    static readonly code: string;
+}
+/**
+ * Thrown when a spec's raw input names a column the bound series does
+ * not carry — its own class, because a persisted plan outliving a column
+ * is the one compile failure a consumer routinely expects and wants to
+ * handle rather than report as a bug.
+ */
+export declare class UnknownColumnError extends ProcessError {
+    static readonly code: string;
 }
 /** One node per spec, plus the spec and params it was compiled from. */
 interface Compiled {

package/dist/plan/graph.js

@@ -18,6 +18,20 @@ import { columnsOf, specId, unitOf } from './identity.js';
 import { isFold, isPicked, specOf, } from './types.js';
 /** Thrown when an op demands an input unit its source does not carry. */
 export class UnitError extends ProcessError {
+    static code = 'UnitError';
+}
+/**
+ * Thrown when a spec's raw input names a column the bound series does
+ * not carry — its own class, because a persisted plan outliving a column
+ * is the one compile failure a consumer routinely expects and wants to
+ * handle rather than report as a bug.
+ */
+export class UnknownColumnError extends ProcessError {
+    static code = 'UnknownColumnError';
+}
+/** The bound series' value columns — the key column is not readable as one. */
+function valueColumns(series) {
+    return series.schema.slice(1).map((c) => c.name);
 }
 /** The per-output key a node's outlets are addressed by. */
 function outletKey(output) {
@@ -221,6 +235,29 @@ export class BoundGraph {
             }
         }
     }
+    /**
+     * Drops a node's lookup AND its wiring — the same two halves eviction
+     * needs, without the budget's accounting.
+     *
+     * Deleting from `#nodes` alone frees nothing and leaves the node
+     * reachable from the source: `Outlet.#downstream` holds a strong
+     * `Set<Inlet>` and `Inlet.node` points back (learned on PR #571).
+     */
+    #forget(id) {
+        const compiled = this.#nodes.get(id);
+        if (compiled === undefined)
+            return;
+        for (const inlet of Object.values(compiled.node.in)) {
+            inlet.disconnect();
+        }
+        this.#nodes.delete(id);
+        this.#lru.delete(id);
+        this.#pendingFrom.delete(id);
+        this.#fullDirty.delete(id);
+        for (const upstream of compiled.upstream) {
+            this.#nodes.get(upstream)?.dependents.delete(id);
+        }
+    }
     #touch(id) {
         this.#lru.delete(id);
         this.#lru.add(id);
@@ -289,6 +326,48 @@ export class BoundGraph {
             this.#touch(id);
         return hit;
     }
+    /**
+     * Every raw input in a spec's whole closure names a column the bound
+     * series carries — [PND-PROCTOTAL].
+     *
+     * Nothing used to check this, at compile OR at pull: the op simply ran
+     * with `ctx.series` un-widened, and whatever a non-defensive op
+     * returned was appended under the spec's id. `skipped` stayed empty
+     * and `onError` never engaged, so a persisted plan citing a column the
+     * feed had dropped produced a plausible-looking column of garbage
+     * (Tidal, `docs/notes/tidal-process-adoption-friction-2026-08.md`).
+     * The honest outcomes are a skip or a throw, never a value.
+     *
+     * The check is not new so much as **completed**: `expandSlots` already
+     * rejects exactly this against exactly this column list, so one of the
+     * two request forms caught it and the other did not.
+     *
+     * **The whole closure, not just this spec's own inputs**, and that
+     * matters for the error a consumer sees rather than for whether one is
+     * raised: the typed-unit pass below resolves a nested input's unit
+     * before recursion ever reaches the nested spec, so a missing column
+     * under a *typed* parent surfaced as `UnitError` — "is 'unitless'",
+     * which is true and names the wrong problem, and misses the one class
+     * a consumer branches on (Codex, PR #667).
+     */
+    #checkRawInputs(spec) {
+        const columns = valueColumns(this.series);
+        const walk = (at) => {
+            const def = this.registry.get(at.op);
+            at.inputs.forEach((raw, i) => {
+                if (typeof raw !== 'string') {
+                    walk(specOf(raw));
+                    return;
+                }
+                if (columns.includes(raw))
+                    return;
+                throw new UnknownColumnError(`'${at.op}' names '${raw}' for input '${def.inputs[i]?.role ?? i}', which is not a column of the bound series — columns are ${columns.length === 0
+                    ? 'none'
+                    : columns.map((c) => `'${c}'`).join(', ')}`);
+            });
+        };
+        walk(spec);
+    }
     /**
      * Compiles a spec (and its inputs) into nodes, memoized by `specId`.
      *
@@ -309,6 +388,26 @@ export class BoundGraph {
         const id = specId(this.registry, spec);
         const existing = this.#nodes.get(id);
         if (existing) {
+            // Re-checked on the WARM path too, not just on the way in.
+            // `setSource` replaces the data under compiled nodes by design
+            // (`Host.add`, an async source refresh), so a node can outlive the
+            // column it reads — and it then recomputes happily against an
+            // un-widened series, which is the original garbage-column bug
+            // surviving through the memo. Found by the Codex review of
+            // PR #667, reproduced: swap `px` for `other`, re-run the same
+            // spec, get a column of 42s with `skipped: []`.
+            try {
+                this.#checkRawInputs(spec);
+            }
+            catch (e) {
+                // And FORGET it, rather than only refusing to hand it back here.
+                // A node left in place is still found by `graph.get`, which is
+                // how `run`'s selector pass reaches a node — so the plan pass
+                // reported the skip and the selector pulled the stale node
+                // anyway, producing the very column the check exists to prevent.
+                this.#forget(id);
+                throw e;
+            }
             this.#touch(id);
             return existing;
         }
@@ -317,6 +416,10 @@ export class BoundGraph {
         if (spec.inputs.length !== op.inputs.length) {
             throw new ProcessError(`${spec.op} takes ${op.inputs.length} input(s), got ${spec.inputs.length}`);
         }
+        // After arity — an input index past the declared list is an arity
+        // problem, not a column one — and before the typed-unit pass, whose
+        // answer for an absent column is a misleading 'unitless'.
+        this.#checkRawInputs(spec);
         // Typed inputs: an op may demand a unit its source must already
         // carry. Checked before compiling so the reason names both sides.
         op.inputs.forEach((def, i) => {

package/dist/plan/host.d.ts

@@ -21,6 +21,7 @@ import { type SourceRef, type SourceRegistry } from './source.js';
 import type { Plan, Units } from './types.js';
 /** Thrown when a request names a dataset the host has not been given. */
 export declare class UnknownDatasetError extends ProcessError {
+    static readonly code: string;
 }
 /**
  * A request as it arrives over a wire.

package/dist/plan/host.js

@@ -17,6 +17,7 @@ import { run } from './run.js';
 import { sourceId, } from './source.js';
 /** Thrown when a request names a dataset the host has not been given. */
 export class UnknownDatasetError extends ProcessError {
+    static code = 'UnknownDatasetError';
 }
 function isLocalEnvelope(envelope) {
     return typeof envelope.from === 'string';

package/dist/plan/identity.d.ts

@@ -36,14 +36,61 @@
  */
 import type { Registry } from './registry.js';
 import type { Params, Spec, SpecRef, Units } from './types.js';
+/** Options for {@link specId}. */
+export interface SpecIdOptions {
+    /**
+     * Whether the op must exist and its params must be legal — default
+     * `true`.
+     *
+     * Pass `false` to name a spec that would not compile. See
+     * {@link specId} for why identity is separable from validity.
+     */
+    readonly validate?: boolean;
+}
 /**
  * Canonical, versioned id for a spec — simultaneously the **column
  * name**, the **cache key**, and the **provenance citation**.
  *
  * Params are sorted by key and materialized post-defaults, so two
  * spellings of one computation collide deliberately.
+ *
+ * ## Identity is separable from validity — [PND-PROCTOTAL]
+ *
+ * By default this validates as it goes, because it resolves params to
+ * canonicalize them and an id built from a rejected param would be a
+ * cache key for a node that cannot exist.
+ *
+ * But the moments a consumer most needs an id for an **invalid** spec
+ * are exactly the failure paths: labelling the chip it is skipping,
+ * keying the "this one is broken" UI state, logging which persisted
+ * entry was rejected. Coupling the two left the consumer
+ * re-implementing canonicalization — the one thing this function exists
+ * to own — or carrying a second key beside a correct one (Tidal,
+ * `docs/notes/tidal-process-adoption-friction-2026-08.md`).
+ *
+ * So `specId(registry, spec, { validate: false })` is **total**: an
+ * unknown op keeps its given params verbatim, a known one still gets
+ * its defaults applied and its keys sorted, and nothing throws.
+ * Validity stays `compile`'s job.
+ *
+ * **A valid spec has one id under either mode.** Canonicalization is
+ * the same code path and `checkParam` never coerces, so the lenient id
+ * of a legal spec is the strict one — a consumer may key on it without
+ * a second cache line.
+ *
+ * **An unvalidated id cannot collide with a valid one**, and that takes
+ * more than putting the params in: it is marked `p1?:` rather than
+ * `p1:`, and its params are encoded type-preservingly. Without both, a
+ * spec whose param arrived as `"20"` instead of `20` — a JSON round
+ * trip, the very case this mode is for — named the *working* node, since
+ * `String(v)` erases the difference `checkParam` would have caught. A
+ * valid id is unaffected by either measure, which is why they are
+ * confined to this branch.
+ *
+ * The mark rides **up** a chain: a spec whose nested input did not
+ * validate cannot compile either, so it is unvalidated too.
  */
-export declare function specId(registry: Registry, spec: Spec): string;
+export declare function specId(registry: Registry, spec: Spec, options?: SpecIdOptions): string;
 /** Resolves a reference that may be an inline spec or an id string. */
 export declare function refToId(registry: Registry, ref: SpecRef): string;
 /**

package/dist/plan/identity.js

@@ -44,32 +44,133 @@ const VERSION = 'p1';
 function esc(v) {
     return String(v).replace(/[\\;,()=+]/g, (c) => `\\${c}`);
 }
+/**
+ * Marks an id whose spec did **not** validate — see {@link specId}.
+ *
+ * A valid id is `p1:…`, so an unvalidated one differs at the character
+ * after the version and can never equal one, whatever its params say.
+ */
+const UNVALIDATED = '?';
+/**
+ * Type-preserving encoding, used **only** inside an unvalidated id.
+ *
+ * `esc` is `String(v)`, which erases type — so `{period: '20'}` and
+ * `{period: 20}` encode identically. Strict mode is safe from that
+ * because `checkParam` rejects the string before it is ever encoded;
+ * leniency removes that guard, and a JSON or form round-trip turning a
+ * number into a string is precisely the broken persisted spec this whole
+ * mode exists to name (found by the Layer 2 and Codex reviews of
+ * PR #667, which reproduced `'20'` colliding with `20`).
+ *
+ * Applied to keys too, because leniency carries an **undeclared** param
+ * through: a key spelled `a=1,b` would otherwise forge the encoding of
+ * two params. Neither change touches a valid id, which is the property
+ * that must not move.
+ */
+function typedEsc(v) {
+    return esc(`${typeof v}:${String(v)}`);
+}
 /**
  * Canonical, versioned id for a spec — simultaneously the **column
  * name**, the **cache key**, and the **provenance citation**.
  *
  * Params are sorted by key and materialized post-defaults, so two
  * spellings of one computation collide deliberately.
+ *
+ * ## Identity is separable from validity — [PND-PROCTOTAL]
+ *
+ * By default this validates as it goes, because it resolves params to
+ * canonicalize them and an id built from a rejected param would be a
+ * cache key for a node that cannot exist.
+ *
+ * But the moments a consumer most needs an id for an **invalid** spec
+ * are exactly the failure paths: labelling the chip it is skipping,
+ * keying the "this one is broken" UI state, logging which persisted
+ * entry was rejected. Coupling the two left the consumer
+ * re-implementing canonicalization — the one thing this function exists
+ * to own — or carrying a second key beside a correct one (Tidal,
+ * `docs/notes/tidal-process-adoption-friction-2026-08.md`).
+ *
+ * So `specId(registry, spec, { validate: false })` is **total**: an
+ * unknown op keeps its given params verbatim, a known one still gets
+ * its defaults applied and its keys sorted, and nothing throws.
+ * Validity stays `compile`'s job.
+ *
+ * **A valid spec has one id under either mode.** Canonicalization is
+ * the same code path and `checkParam` never coerces, so the lenient id
+ * of a legal spec is the strict one — a consumer may key on it without
+ * a second cache line.
+ *
+ * **An unvalidated id cannot collide with a valid one**, and that takes
+ * more than putting the params in: it is marked `p1?:` rather than
+ * `p1:`, and its params are encoded type-preservingly. Without both, a
+ * spec whose param arrived as `"20"` instead of `20` — a JSON round
+ * trip, the very case this mode is for — named the *working* node, since
+ * `String(v)` erases the difference `checkParam` would have caught. A
+ * valid id is unaffected by either measure, which is why they are
+ * confined to this branch.
+ *
+ * The mark rides **up** a chain: a spec whose nested input did not
+ * validate cannot compile either, so it is unvalidated too.
  */
-export function specId(registry, spec) {
-    const op = registry.get(spec.op);
-    const params = registry.resolveParams(op, spec.params);
-    const p = Object.entries(params)
-        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-        .map(([k, v]) => `${k}=${esc(v)}`)
-        .join(',');
-    const inputs = spec.inputs
+export function specId(registry, spec, options = {}) {
+    return build(registry, spec, options.validate === false).id;
+}
+/** An id, and whether anything in its closure failed validation. */
+function build(registry, spec, lenient) {
+    let unvalidated = false;
+    // Inputs first: a nested spec that did not validate marks this one,
+    // and the mark has to be known before the params are encoded.
+    //
+    // `?? []` because a spec arriving from persistence may be missing the
+    // field entirely, and a mode whose promise is totality cannot answer a
+    // dropped key with a TypeError. Strict mode reaches `compile`'s arity
+    // check instead, which says what is actually wrong.
+    const inputs = (spec.inputs ?? [])
         .map((i) => {
         if (typeof i === 'string')
             return esc(i);
         // `#Lower` rather than a separate field: an input picking a
         // different output is a different computation, and the id is what
         // says so.
-        const base = specId(registry, specOf(i));
-        return isPicked(i) ? `${base}#${esc(i.output)}` : base;
+        const base = build(registry, specOf(i), lenient);
+        if (base.unvalidated)
+            unvalidated = true;
+        return isPicked(i) ? `${base.id}#${esc(i.output)}` : base.id;
     })
         .join('+');
-    return `${VERSION}:${spec.op}(${inputs};${p})`;
+    let params;
+    if (lenient && !registry.has(spec.op)) {
+        unvalidated = true;
+        params = spec.params ?? {};
+    }
+    else {
+        const op = registry.get(spec.op);
+        try {
+            // The strict resolve first even under leniency: when it succeeds
+            // the id is byte-identical to the validating one, which is the
+            // whole contract. Only its failure moves this spec into the
+            // unvalidated namespace.
+            params = registry.resolveParams(op, spec.params);
+        }
+        catch (e) {
+            if (!lenient)
+                throw e;
+            unvalidated = true;
+            params = registry.resolveParams(op, spec.params, { validate: false });
+        }
+    }
+    const encodeKey = unvalidated ? esc : (k) => k;
+    const encodeValue = unvalidated ? typedEsc : esc;
+    const p = Object.entries(params)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${encodeKey(k)}=${encodeValue(v)}`)
+        .join(',');
+    const mark = unvalidated ? UNVALIDATED : '';
+    return {
+        id: `${VERSION}${mark}:${spec.op}(${inputs};${p})`,
+        unvalidated,
+    };
 }
 /** Resolves a reference that may be an inline spec or an id string. */
 export function refToId(registry, ref) {

package/dist/plan/registry.d.ts

@@ -26,9 +26,11 @@ type OutputShape = {
 };
 /** Thrown when a plan names an op the registry does not have. */
 export declare class UnknownOpError extends ProcessError {
+    static readonly code: string;
 }
 /** Thrown when a param is missing, mistyped, or out of range. */
 export declare class ParamError extends ProcessError {
+    static readonly code: string;
 }
 /** Op metadata as a picker or a tool catalog wants it. */
 export interface OpDescriptor {
@@ -87,8 +89,20 @@ export declare class Registry<Defs extends DefMap = {}> {
      * an optional-chain at each of the nine call sites.
      */
     outputsOf(def: Def): readonly OutputShape[];
-    /** Applies defaults, then validates every declared param. */
-    resolveParams(op: Def, given?: Readonly<Record<string, ParamValue>>): Params;
+    /**
+     * Applies defaults, then validates every declared param.
+     *
+     * `validate: false` applies the defaults and skips every check,
+     * including the unknown-key rejection — an undeclared param is carried
+     * through rather than refused. Total by construction, which is what
+     * lets `specId` name a spec it would refuse to compile
+     * ([PND-PROCTOTAL]). A **valid** spec resolves identically either way:
+     * `checkParam` returns its input unchanged and never coerces, so
+     * leniency cannot move an id.
+     */
+    resolveParams(op: Def, given?: Readonly<Record<string, ParamValue>>, options?: {
+        validate?: boolean;
+    }): Params;
     /** Grouped for a picker. */
     byFamily(): Map<string, OpDescriptor[]>;
     describe(): OpDescriptor[];

package/dist/plan/registry.js

@@ -18,9 +18,11 @@ export { int, num, choice, flag } from './params.js';
 import { isFold } from './types.js';
 /** Thrown when a plan names an op the registry does not have. */
 export class UnknownOpError extends ProcessError {
+    static code = 'UnknownOpError';
 }
 /** Thrown when a param is missing, mistyped, or out of range. */
 export class ParamError extends ProcessError {
+    static code = 'ParamError';
 }
 /**
  * Validates one param and returns it.
@@ -170,15 +172,33 @@ export class Registry {
     outputsOf(def) {
         return isFold(def) ? [] : def.outputs;
     }
-    /** Applies defaults, then validates every declared param. */
-    resolveParams(op, given = {}) {
+    /**
+     * Applies defaults, then validates every declared param.
+     *
+     * `validate: false` applies the defaults and skips every check,
+     * including the unknown-key rejection — an undeclared param is carried
+     * through rather than refused. Total by construction, which is what
+     * lets `specId` name a spec it would refuse to compile
+     * ([PND-PROCTOTAL]). A **valid** spec resolves identically either way:
+     * `checkParam` returns its input unchanged and never coerces, so
+     * leniency cannot move an id.
+     */
+    resolveParams(op, given = {}, options = {}) {
+        const validate = options.validate !== false;
         const out = {};
         for (const [key, def] of Object.entries(op.params)) {
             const raw = Object.hasOwn(given, key) ? given[key] : def.default;
-            out[key] = checkParam(op.name, key, def, raw);
+            out[key] = validate ? checkParam(op.name, key, def, raw) : raw;
         }
         for (const key of Object.keys(given)) {
             if (!Object.hasOwn(op.params, key)) {
+                // Carried, not dropped: two specs differing only in a bogus param
+                // are two different broken specs, and an id that collapsed them
+                // would key one UI state onto both.
+                if (!validate) {
+                    out[key] = given[key];
+                    continue;
+                }
                 throw new ParamError(`${op.name} has no param '${key}' — takes ${Object.keys(op.params)
                     .map((k) => `'${k}'`)
                     .join(', ') || 'none'}`);

package/dist/plan/run.d.ts

@@ -171,6 +171,20 @@ export interface Skipped {
     };
     readonly select?: Select;
     readonly reason: string;
+    /**
+     * The failure's kind — {@link ProcessError.code}, e.g.
+     * `'UnknownColumnError'`. Absent when the throw did not come from this
+     * package, which is itself the useful signal: op code failed, not the
+     * plan layer.
+     *
+     * `reason` is prose for a human and its wording is not a contract.
+     * Under `onError: 'skip' | 'collect'` nothing is thrown, so without
+     * this a consumer branching on the kind — a dropped feed column is a
+     * dimmed, removable chip; a bad persisted param is a broken one — was
+     * left matching on that prose (Tidal,
+     * `docs/notes/tidal-process-adoption-friction-2026-08.md`).
+     */
+    readonly code?: string;
 }
 export interface RunResult {
     /** Present only when a `columns` selector asked for it, and `assemble`. */

package/dist/plan/run.js

@@ -64,6 +64,19 @@ function normalize(graph, request) {
     });
     return { plan: [...expanded.values()], select, slotOf };
 }
+/**
+ * The `reason` and `code` a caught throw contributes to a {@link Skipped}.
+ *
+ * One place, so every failure path reports its kind the same way — the
+ * column loop and the fact loop already diverged once on `onError`
+ * itself, which is the argument for not writing this twice.
+ */
+function describe(e) {
+    return {
+        reason: e instanceof Error ? e.message : String(e),
+        ...(e instanceof ProcessError && { code: e.code }),
+    };
+}
 export function run(graph, request) {
     const { onError = 'throw', assemble = true } = request;
     const registry = graph.registry;
@@ -85,15 +98,26 @@ export function run(graph, request) {
             outputs: {},
             facts: [],
             explain: {},
-            skipped: [{ reason: e instanceof Error ? e.message : String(e) }],
+            skipped: [describe(e)],
             nodes: [],
         };
     }
     const { plan, select, slotOf } = normalized;
-    const fail = (entry) => {
+    /**
+     * Reports a failure, or rethrows it — the ORIGINAL error, not a
+     * reconstruction.
+     *
+     * Rebuilding it as a base `ProcessError` from `entry.reason` erased the
+     * class on the default policy: `graph.compile` threw
+     * `UnknownColumnError` and `run` turned it into a `ProcessError`, so a
+     * consumer catching could not branch on the very class this PR added,
+     * and the documented "`code` matches what a throw would have carried"
+     * was false in one direction (Codex, PR #667).
+     */
+    const fail = (error, entry) => {
         if (onError === 'throw')
-            throw new ProcessError(entry.reason);
-        skipped.push(entry);
+            throw error;
+        skipped.push({ ...entry, ...describe(error) });
     };
     // ── resolve the plan ───────────────────────────────────────
     for (const spec of plan) {
@@ -102,13 +126,12 @@ export function run(graph, request) {
             resolved.push({ id: compiled.id, spec });
         }
         catch (e) {
-            fail({
+            fail(e, {
                 spec: {
                     op: spec.op,
                     params: { ...(spec.params ?? {}) },
                     inputs: spec.inputs,
                 },
-                reason: e instanceof Error ? e.message : String(e),
             });
         }
     }
@@ -136,7 +159,7 @@ export function run(graph, request) {
             }
         }
         catch (e) {
-            fail({ select: sel, reason: e instanceof Error ? e.message : String(e) });
+            fail(e, { select: sel });
             continue;
         }
         selectors.push({ sel, id });
@@ -265,10 +288,10 @@ export function run(graph, request) {
                 if (sel.output !== undefined &&
                     !declared.some((o) => o.id === sel.output)) {
                     const have = declared.map((o) => `'${o.id}'`).join(', ');
-                    fail({
-                        select: sel,
-                        reason: `'${compiled.spec.op}' has no output '${sel.output}' (has ${have})`,
-                    });
+                    // Built here rather than caught, so the kind is stated rather
+                    // than derived — a `Skipped` from the plan layer always
+                    // carries one, and the throw policy raises the same object.
+                    fail(new ProcessError(`'${compiled.spec.op}' has no output '${sel.output}' (has ${have})`), { select: sel });
                     continue;
                 }
                 // Pulling a column runs op code, which can throw like anything
@@ -299,12 +322,7 @@ export function run(graph, request) {
                     });
                 }
                 catch (e) {
-                    if (onError === 'throw')
-                        throw e;
-                    fail({
-                        select: sel,
-                        reason: e instanceof Error ? e.message : String(e),
-                    });
+                    fail(e, { select: sel });
                 }
             }
         }
@@ -314,7 +332,7 @@ export function run(graph, request) {
     for (const { sel, id } of selectors) {
         const compiled = graph.get(id);
         if (compiled === undefined) {
-            fail({ select: sel, reason: `'${id}' is not in this plan` });
+            fail(new ProcessError(`'${id}' is not in this plan`), { select: sel });
             continue;
         }
         if (!compiled.fold)
@@ -337,7 +355,7 @@ export function run(graph, request) {
             });
         }
         catch (e) {
-            fail({ select: sel, reason: e instanceof Error ? e.message : String(e) });
+            fail(e, { select: sel });
         }
     }
     // Anything the plan resolved but nothing selected. After the pulls, so

package/dist/plan/slots.d.ts

@@ -32,6 +32,7 @@ import { ProcessError } from '../errors.js';
 import type { ParamValue, Spec } from './types.js';
 /** Thrown when a slot graph cannot be expanded. */
 export declare class SlotError extends ProcessError {
+    static readonly code: string;
 }
 /** One node in a slot graph. `in` names source columns or other slots. */
 export interface SlotDef {

package/dist/plan/slots.js

@@ -31,6 +31,7 @@
 import { ProcessError } from '../errors.js';
 /** Thrown when a slot graph cannot be expanded. */
 export class SlotError extends ProcessError {
+    static code = 'SlotError';
 }
 /**
  * Expands a slot graph into the nested `Spec` form.

package/dist/plan/source.d.ts

@@ -37,6 +37,7 @@ export declare function defineSource<const Name extends string, const Params ext
     readonly load: SourceDef<Name, Params>['load'];
 }): SourceDef<Name, Params>;
 export declare class UnknownSourceError extends ProcessError {
+    static readonly code: string;
 }
 export declare class SourceRegistry {
     #private;

package/dist/plan/source.js

@@ -15,6 +15,7 @@ export function defineSource(definition) {
     };
 }
 export class UnknownSourceError extends ProcessError {
+    static code = 'UnknownSourceError';
 }
 export class SourceRegistry {
     #sources = new Map();

package/dist/source.d.ts

@@ -17,6 +17,7 @@ import type { PortSpec } from './types.js';
 export type NoInputs = Readonly<Record<string, never>>;
 /** Thrown when a source is pulled before a value has been set. */
 export declare class UnsetSourceError extends ProcessError {
+    static readonly code: string;
 }
 /**
  * A graph input whose value is pushed in from outside via {@link set}.

package/dist/source.js

@@ -7,6 +7,7 @@ import { ProcessError } from './errors.js';
 import { Node } from './node.js';
 /** Thrown when a source is pulled before a value has been set. */
 export class UnsetSourceError extends ProcessError {
+    static code = 'UnsetSourceError';
 }
 /**
  * A graph input whose value is pushed in from outside via {@link set}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/process",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "Computations as data over pond-ts: processing graphs authored fluently or composed as JSON, resolved against a declared op vocabulary with content-addressed caching, provenance, and per-node timings. Experimental, pre-1.0.",
   "license": "MIT",
   "repository": {
@@ -42,7 +42,7 @@
     "verify": "npm run format:check && npm run build && npm test"
   },
   "peerDependencies": {
-    "pond-ts": "^0.61.0"
+    "pond-ts": "^0.62.0"
   },
   "devDependencies": {
     "typescript": "^5.6.3",