@pond-ts/process 0.54.0

package/dist/plan/identity.js

@@ -0,0 +1,158 @@
+/**
+ * Identity, lineage, and units — and the [PND-PROCIDENT] decision.
+ *
+ * ## Identity is content-addressed, and that is forced
+ *
+ * The investigation weighed content-addressed ids against params-as-Ins
+ * and measured the latter far cheaper under a parameter sweep (1 node vs
+ * 200, 6 MB of buffers vs 310 MB). But writing `run()` settles it the
+ * other way, because the *plan format* decides it:
+ *
+ * A plan may hold `sma(px, 20)` **and** `sma(px, 50)` at once. They are
+ * two entries, they need two nodes, and — decisively — they need two
+ * distinct output **column names**. A column is named by its spec's id,
+ * so an id that excluded params would collide. Params must be in the id.
+ *
+ * The sweep result is still real; it is just an argument about
+ * **lifetime**, not identity. Dragging a slider mints a node per
+ * position, and those nodes stop being referenced by the current plan the
+ * moment it moves on. The answer is a retained set plus a budget
+ * ([PND-PROCCACHE]) — not a different identity model.
+ *
+ * So: **content-addressed identity, budgeted lifetime.**
+ *
+ * ## Two properties that must not regress
+ *
+ * Both are requirements rather than accidents, because a persisted saved
+ * view and a freshly composed request have to land on the same cache
+ * entry:
+ *
+ * - `specId` is **invariant under param key order** — a caller's JSON
+ *   preserves insertion order and two callers will not agree on one.
+ * - An **omitted param collides with its explicit default**, so
+ *   `{op:'sma'}` and `{op:'sma',params:{period:20}}` are one node.
+ *
+ * Both are pinned by tests.
+ */
+import { isFold, isPicked, specOf } from './types.js';
+/** Id format version. Bumping it invalidates persisted ids deliberately. */
+const VERSION = 'p1';
+/**
+ * Escapes the separators an id is built from, so a string param cannot
+ * forge one. `sma(a\)b;…)` stays one id rather than closing early.
+ */
+function esc(v) {
+    return String(v).replace(/[\\;,()=+]/g, (c) => `\\${c}`);
+}
+/**
+ * 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.
+ */
+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
+        .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;
+    })
+        .join('+');
+    return `${VERSION}:${spec.op}(${inputs};${p})`;
+}
+/** Resolves a reference that may be an inline spec or an id string. */
+export function refToId(registry, ref) {
+    return typeof ref === 'string' ? ref : specId(registry, ref);
+}
+/**
+ * Human lineage, folded from the plan and the registry.
+ *
+ * Derived rather than reconstructed by hand — hand-built lineage is
+ * exactly what loses the inner `sma` in `ema(sma(x))`, which the RFC
+ * cites as a live consumer bug.
+ */
+export function explain(registry, spec) {
+    const op = registry.get(spec.op);
+    const params = registry.resolveParams(op, spec.params);
+    const inputs = spec.inputs
+        .map((i) => {
+        if (typeof i === 'string')
+            return i;
+        const base = explain(registry, specOf(i));
+        return isPicked(i) ? `${i.output} of ${base}` : base;
+    })
+        .join(', ');
+    if (op.label)
+        return op.label(params, inputs);
+    const p = Object.entries(params)
+        .map(([k, v]) => `${k}=${String(v)}`)
+        .join(', ');
+    return p ? `${op.name}(${p}) of ${inputs}` : `${op.name} of ${inputs}`;
+}
+/**
+ * Unit of a spec's output `n` — declared outright, or folded from input 0.
+ *
+ * `null` means unitless: the consumer supplied no unit for the raw column
+ * at the root of the chain. That is reported rather than guessed.
+ */
+export function unitOf(registry, spec, units, outputIndex = 0) {
+    const op = registry.get(spec.op);
+    const declared = isFold(op)
+        ? op.unit
+        : (op.outputs[outputIndex]?.unit ?? 'inherit');
+    if (declared !== 'inherit')
+        return declared;
+    const src = spec.inputs[0];
+    if (src === undefined)
+        return null;
+    if (typeof src === 'string')
+        return units[src] ?? null;
+    const upstream = specOf(src);
+    const index = isPicked(src)
+        ? registry
+            .outputsOf(registry.get(upstream.op))
+            .findIndex((o) => o.id === src.output)
+        : 0;
+    return unitOf(registry, upstream, units, Math.max(0, index));
+}
+/**
+ * Column names a spec produces, in output-declaration order.
+ *
+ * A single-output op declares suffix `''`, so its column *is* the id; a
+ * band's three columns share the id as a prefix, which is the corpus's
+ * own convention and needs no mapping layer.
+ */
+export function columnsOf(registry, spec, id) {
+    const def = registry.get(spec.op);
+    return registry.outputsOf(def).map((o) => id + o.id);
+}
+/**
+ * Which params an output depends on, defaulting to all of them.
+ *
+ * Declaring a narrower set is what lets a change to one param leave
+ * another output's version untouched ([PND-PROCSEL]).
+ */
+export function dependsOn(registry, spec, outputIndex) {
+    const op = registry.get(spec.op);
+    const declared = isFold(op) ? undefined : op.outputs[outputIndex]?.dependsOn;
+    return declared ? [...declared] : Object.keys(op.params);
+}
+/** Params reduced to the subset an output depends on — its cache key. */
+export function outputKey(params, keys) {
+    return [...keys]
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+        .map((k) => `${k}=${esc(params[k])}`)
+        .join(',');
+}
+//# sourceMappingURL=identity.js.map

package/dist/plan/params.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The param vocabulary, in its own module.
+ *
+ * Split out of the registry because `folds.ts` needs `int` to declare
+ * `shape`'s `points`, and the registry needs `folds.ts` to pre-register
+ * the standard folds — a cycle that ESM resolves by handing one side an
+ * uninitialised binding, which surfaces as `int is not a function` at
+ * import time rather than anywhere near the cause.
+ */
+import type { BooleanParam, EnumParam, NumberParam } from './types.js';
+export declare const int: (o: Omit<NumberParam, "kind">) => NumberParam;
+export declare const num: (o: Omit<NumberParam, "kind">) => NumberParam;
+export declare const choice: (o: Omit<EnumParam, "kind">) => EnumParam;
+export declare const flag: (o: Omit<BooleanParam, "kind">) => BooleanParam;
+//# sourceMappingURL=params.d.ts.map

package/dist/plan/params.js

@@ -0,0 +1,26 @@
+/**
+ * The param vocabulary, in its own module.
+ *
+ * Split out of the registry because `folds.ts` needs `int` to declare
+ * `shape`'s `points`, and the registry needs `folds.ts` to pre-register
+ * the standard folds — a cycle that ESM resolves by handing one side an
+ * uninitialised binding, which surfaces as `int is not a function` at
+ * import time rather than anywhere near the cause.
+ */
+export const int = (o) => ({
+    kind: 'integer',
+    ...o,
+});
+export const num = (o) => ({
+    kind: 'number',
+    ...o,
+});
+export const choice = (o) => ({
+    kind: 'enum',
+    ...o,
+});
+export const flag = (o) => ({
+    kind: 'boolean',
+    ...o,
+});
+//# sourceMappingURL=params.js.map

package/dist/plan/registry.d.ts

@@ -0,0 +1,162 @@
+/**
+ * The registry, and the param vocabulary it is declared in.
+ *
+ * One declaration, four readers: **param validation**, a **JSON Schema
+ * projection** so a tool caller can compose plans, a **UI picker**
+ * (family + params + defaults is exactly a grouped menu), and **unit
+ * propagation**.
+ *
+ * The internal param spec is the source of truth and the validator reads
+ * it; JSON Schema is a *projection* emitted for callers, not the
+ * authority ([PND-PROCREG]). Adopting JSON Schema as the source would
+ * mean taking on a schema-validator dependency to do work a dozen lines
+ * already do.
+ */
+import { ProcessError } from '../errors.js';
+export { int, num, choice, flag } from './params.js';
+import { type Def, type FoldDef } from './types.js';
+import type { InputDef, ParamDef, Params, ParamValue } from './types.js';
+/** The compile-time vocabulary retained by a registry as definitions are added. */
+export type DefMap = Readonly<Record<string, Def>>;
+type WithDef<Defs extends DefMap, D extends Def> = Omit<Defs, D['name']> & Readonly<Record<D['name'], D>>;
+/** One declared output, as `outputsOf` reports it. */
+type OutputShape = {
+    readonly id: string;
+    readonly unit: string;
+};
+/** Thrown when a plan names an op the registry does not have. */
+export declare class UnknownOpError extends ProcessError {
+}
+/** Thrown when a param is missing, mistyped, or out of range. */
+export declare class ParamError extends ProcessError {
+}
+/** Op metadata as a picker or a tool catalog wants it. */
+export interface OpDescriptor {
+    readonly name: string;
+    readonly family: string;
+    readonly summary: string;
+    readonly params: Readonly<Record<string, ParamDef>>;
+    /**
+     * The declared inputs, not a count of them.
+     *
+     * A count is enough to check arity and nothing else. A consumer
+     * labelling a two-input op cannot say which side is which, and one
+     * showing why a plan was rejected cannot name the unit an input
+     * demands — both facts the registry holds and used to drop here. Found
+     * by building a UI that wanted to label a node's wiring and could only
+     * show how many wires there were.
+     */
+    readonly inputs: readonly InputDef[];
+    /**
+     * `'fold'` for a terminal node — one that ends in a fact rather than a
+     * column, and so cannot be another node's input.
+     *
+     * A consumer needs this to know what surfacing the node will hand it
+     * back, and a picker needs it to know which entries can be wired
+     * onward. Absent would have meant every reader inferring it from an
+     * empty `outputs`, which is exactly the kind of thing the registry
+     * exists to state.
+     */
+    readonly kind: 'op' | 'fold';
+    /** Empty for a fold: a fact has no columns. */
+    readonly outputs: readonly {
+        readonly suffix: string;
+        readonly unit: string;
+    }[];
+}
+export declare class Registry<Defs extends DefMap = {}> {
+    #private;
+    /**
+     * Adds a definition and retains its literal shape in the return type.
+     *
+     * Runtime callers still validate through this registry. The accumulated
+     * type exists for the programmable fluent authoring layer, where it turns
+     * op names, params, input roles and output suffixes into compile-time facts.
+     */
+    define<const D extends Def>(def: D): Registry<WithDef<Defs, D>>;
+    has(name: string): boolean;
+    /** @throws {UnknownOpError} naming what is available, so an agent can retry. */
+    get(name: string): Def;
+    /** The entry as a fold, or `undefined` if it produces columns. */
+    foldFor(name: string): FoldDef | undefined;
+    /**
+     * Declared outputs, empty for a fold.
+     *
+     * Every caller that used to reach for `op.outputs` went through here
+     * once folds existed, because a fact has none and the alternative was
+     * 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;
+    /** Grouped for a picker. */
+    byFamily(): Map<string, OpDescriptor[]>;
+    describe(): OpDescriptor[];
+    /**
+     * The tool contract: ops as a discriminated union of param objects.
+     *
+     * The spec schema is **recursive** — an input is a column name *or*
+     * another spec — which is what lets a caller express *EMA of SMA of
+     * px* from the schema alone, without being taught a nesting concept.
+     * That recursion is the single most load-bearing thing here, and
+     * getting it to travel took three attempts.
+     *
+     * It lives in `$defs`, and the recursion goes through
+     * `#/$defs/<name>`. That is the only shape that is actually portable:
+     *
+     * - `#/items`, the original, dangles the moment the projection is
+     *   nested inside a larger schema, because a `$ref` resolves against
+     *   the **document root**. Silently — nothing requires a `$ref` to
+     *   resolve ([PND-PROCREG], M2).
+     * - `#/properties/process/items`, a pointer *into* the host document,
+     *   fixes that and passes local validators — including OpenAI's own
+     *   `toStrictJsonSchema` — but the API rejects it: *"reference can
+     *   only point to definitions defined at the top level of the
+     *   schema"* ([PND-PROCSCHEMA], M5).
+     *
+     * So a caller embedding this must lift `$defs` to its own root, where
+     * `#/$defs/<name>` resolves from anywhere:
+     *
+     * ```ts
+     * const plan = registry.toJsonSchema({ defs: 'spec' });
+     * const { $defs, ...body } = plan;
+     * const schema = {
+     *   type: 'object',
+     *   $defs,                                  // hoisted to the root
+     *   properties: { process: body },
+     * };
+     * ```
+     *
+     * `$schema` is emitted only at the root — a nested subschema declaring
+     * its own dialect is not what a caller means.
+     *
+     * Two more things learned by calling a real API rather than reading a
+     * spec, both cases where a **client-side** strict validator accepted
+     * what the server refused:
+     *
+     * - Unions are `anyOf`, not `oneOf`. Both branch sets here are
+     *   disjoint — the op union is discriminated by a `const`, and an
+     *   input is a string or an object, never both — so they are
+     *   equivalent in meaning, and `anyOf` is the one tool APIs accept
+     *   (*"'oneOf' is not permitted"*).
+     * - A `const` carries its `type` alongside. Redundant to a validator,
+     *   and required by the same API (*"schema must have a 'type' key"*).
+     */
+    toJsonSchema(options?: {
+        defs?: string;
+        root?: boolean;
+        shape?: 'nested' | 'slots';
+    }): Record<string, unknown>;
+}
+/**
+ * A registry with the standard folds already in it.
+ *
+ * Pre-registered because `last`, `extremes`, `percentileRank` and `shape`
+ * apply to any numeric series and every consumer wants them — not because
+ * they are privileged. They are plain defs: `define` over a name to
+ * replace one.
+ */
+export declare function createRegistry(options?: {
+    folds?: boolean;
+}): Registry<{}>;
+//# sourceMappingURL=registry.d.ts.map