@pond-ts/process 0.54.0

package/dist/plan/builder.js

@@ -0,0 +1,166 @@
+/**
+ * A programmable API that **emits** a plan — [PND-PROCBUILD].
+ *
+ * Plans-as-data is right for a wire format and required for a cache key,
+ * but it is not how an application wants to *author* a graph. A consumer
+ * building studies over its own metrics should not be assembling nested
+ * JSON by hand.
+ *
+ * ```ts
+ * const g = plan('ACME_5m').as('bands_and_stretch');
+ * const bb = g.add('bb', 'bollinger', { period: 20 }, ['px']);
+ * const z = g.add('z', 'zscore', { period: 20 }, ['px']);
+ *
+ * g.expose('upper_band', bb.last({ output: 'Upper' }));
+ * g.expose('stretch', z.percentileRank());
+ * g.expose('band_series', bb.columns());
+ *
+ * host.run(g.toJSON());
+ * ```
+ *
+ * **Slots are what make this possible**, which is why this depends on
+ * [PND-PROCSLOT] rather than standing alone: a builder needs a stable
+ * handle to refer back to, and a content-addressed id cannot be one — it
+ * changes the moment a param does. A slot is exactly a handle, and
+ * passing `bb` rather than the string `'bb'` is what turns a typo into a
+ * compile error.
+ *
+ * **The builder emits a plan; it does not replace one.** `toJSON()`
+ * produces the same envelope a model would compose, so there is one
+ * resolution path, one cache, and one thing to test — a graph built in
+ * code and one composed by a model land on the same nodes.
+ *
+ * It deliberately knows nothing about the registry: no op-name checking,
+ * no param typing. That keeps it a pure authoring layer with no
+ * dependency on the op corpus, and leaves the resolver as the single
+ * place a bad plan is diagnosed. Typing params off `ParamDef` is the
+ * open question in the ticket, not a gap this file is hiding.
+ */
+import { ProcessError } from '../errors.js';
+/** Thrown when a graph is built wrong — before it is ever sent. */
+export class BuilderError extends ProcessError {
+}
+/**
+ * The derived slot for a fold over `on` — a function of the node, the
+ * fold, **and its params**. Params used to be omitted, so
+ * `shape({points: 20})` followed by `shape({points: 100})` landed on one
+ * slot and the second call silently kept 20. Sorted by key so two
+ * spellings of one param set collide deliberately, the same rule
+ * `specId` applies one layer down.
+ *
+ * One asymmetry is inherent: this builder holds no registry, so it
+ * cannot resolve defaults — `shape()` and `shape({points: 40})` derive
+ * two slots here even though `specId` resolves them to one computation.
+ * That is safe: resolution collapses them to one node, and the response
+ * labels it with the first slot that named it. The registry-bound
+ * fluent layer canonicalizes params before calling this, so it does not
+ * split.
+ */
+export function foldSlot(on, op, params) {
+    const entries = Object.entries(params ?? {});
+    if (entries.length === 0)
+        return `${on}:${op}`;
+    const p = entries
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${k}=${String(v)}`)
+        .join(',');
+    return `${on}:${op}(${p})`;
+}
+export class PlanBuilder {
+    #from;
+    #as;
+    #nodes = new Map();
+    #outputs = new Map();
+    constructor(from) {
+        this.#from = from;
+    }
+    /** Names the result, so a later request can refer back to it. */
+    as(name) {
+        this.#as = name;
+        return this;
+    }
+    /**
+     * Adds a node under a caller-chosen slot name.
+     *
+     * The name is required rather than derived, because it *is* the stable
+     * identity — deriving `sma2` from a counter would renumber the moment
+     * a node is inserted above it, which is the property slots exist to
+     * provide.
+     *
+     * @throws {BuilderError} if the slot is already taken.
+     */
+    add(slot, op, params, inputs) {
+        if (this.#nodes.has(slot)) {
+            throw new BuilderError(`slot '${slot}' is already used by a '${this.#nodes.get(slot).op}' node`);
+        }
+        this.#nodes.set(slot, {
+            op,
+            ...(params !== undefined && { params }),
+            in: inputs.map((i) => typeof i === 'string'
+                ? i
+                : 'output' in i
+                    ? `${i.slot}#${i.output}`
+                    : i.slot),
+        });
+        return this.#handle(slot);
+    }
+    /**
+     * Adds a fold over `on`, or returns the one already added.
+     *
+     * Idempotent because the derived slot is a function of the node, the
+     * fold and its params: writing `z.percentileRank()` in two places is
+     * one node, which is the same thing content-addressing does one layer
+     * down — while two different param sets are two nodes.
+     */
+    #fold(on, op, params) {
+        const slot = foldSlot(on, op, params);
+        if (!this.#nodes.has(slot)) {
+            this.#nodes.set(slot, {
+                op,
+                ...(params !== undefined && { params }),
+                in: [on],
+            });
+        }
+        return this.#handle(slot);
+    }
+    #handle(slot) {
+        return {
+            slot,
+            last: () => this.#fold(slot, 'last'),
+            extremes: () => this.#fold(slot, 'extremes'),
+            percentileRank: () => this.#fold(slot, 'percentileRank'),
+            shape: (options = {}) => this.#fold(slot, 'shape', options.points !== undefined ? { points: options.points } : undefined),
+        };
+    }
+    /**
+     * Surfaces a node under the caller's own name.
+     *
+     * Takes a handle, because a selector's only remaining job is to point
+     * at a node — what comes back is whatever that node produces.
+     *
+     * @throws {BuilderError} if the name is already used.
+     */
+    expose(name, node, options) {
+        if (this.#outputs.has(name)) {
+            throw new BuilderError(`output '${name}' is already exposed`);
+        }
+        this.#outputs.set(name, {
+            on: node.slot,
+            ...(options?.output !== undefined && { output: options.output }),
+        });
+        return this;
+    }
+    /** The envelope. Plain JSON — nothing here survives into the request. */
+    toJSON() {
+        return {
+            from: this.#from,
+            ...(this.#as !== undefined && { as: this.#as }),
+            nodes: Object.fromEntries(this.#nodes),
+            outputs: Object.fromEntries(this.#outputs),
+        };
+    }
+}
+export function plan(from) {
+    return new PlanBuilder(from);
+}
+//# sourceMappingURL=builder.js.map

package/dist/plan/fluent.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Registry-bound fluent authoring.
+ *
+ * This is a compiler into the slot envelope, not a second execution path.
+ * The registry's accumulated literal type supplies op names, params, input
+ * roles and output suffixes; runtime plans still pass through normal registry
+ * validation because requests may also arrive as JSON.
+ */
+import type { OpDef, ParamDef } from './types.js';
+import { type BuiltRequest, type NodeHandle } from './builder.js';
+import type { DefMap, Registry } from './registry.js';
+import type { SourceRef } from './source.js';
+type ValueFor<D extends ParamDef> = D extends {
+    readonly kind: 'integer' | 'number';
+} ? number : D extends {
+    readonly kind: 'boolean';
+} ? boolean : D extends {
+    readonly kind: 'enum';
+    readonly of: readonly (infer V extends string)[];
+} ? V : never;
+type ParamsFor<D extends OpDef> = {
+    readonly [K in keyof D['params']]?: ValueFor<D['params'][K]>;
+};
+type TailInputs<D extends OpDef> = D['inputs'] extends readonly [
+    unknown,
+    ...infer Rest
+] ? Rest : readonly [];
+type ExtraInputsFor<D extends OpDef> = {
+    readonly [I in TailInputs<D>[number] as I extends {
+        readonly role: infer Role extends string;
+    } ? Role : never]: FluentColumnRef<any>;
+};
+export type BuildOptions<D extends OpDef> = Readonly<{
+    as: string;
+} & ParamsFor<D> & ExtraInputsFor<D>>;
+type OutputNames<D extends OpDef> = D['outputs'][number]['id'];
+type OpMethods<Defs extends DefMap> = {
+    readonly [Name in keyof Defs as Defs[Name] extends OpDef ? Name : never]: Defs[Name] extends OpDef ? (options: BuildOptions<Defs[Name]>) => NodeFor<Defs, Defs[Name]> : never;
+};
+interface Selection {
+    readonly handle: NodeHandle;
+    readonly output?: string;
+}
+interface ColumnOps<Defs extends DefMap> {
+    /** Latest defined value, with its timestamp. */
+    last(): FactRef;
+    /** Minimum and maximum, each with its timestamp. */
+    extremes(): FactRef;
+    /** Where the latest value sits in its own history. */
+    percentileRank(): FactRef;
+    /** A bounded sample of the complete series. */
+    shape(options?: {
+        points?: number;
+    }): FactRef;
+}
+export type FluentColumnRef<Defs extends DefMap> = ColumnOps<Defs> & OpMethods<Defs>;
+export type SelectedColumnRef<Defs extends DefMap> = FluentColumnRef<Defs> & {
+    columns(): ColumnSelection;
+};
+export interface FactRef {
+    readonly selection: Selection;
+}
+export type SingleColumnNode<Defs extends DefMap> = SelectedColumnRef<Defs> & {
+    readonly slot: string;
+};
+export interface MultiColumnNode<Defs extends DefMap, Outputs extends string> {
+    readonly slot: string;
+    output<Name extends Outputs>(name: Name): SelectedColumnRef<Defs>;
+    columns(): ColumnSelection;
+}
+export interface ColumnSelection {
+    readonly selection: Selection;
+}
+type NodeFor<Defs extends DefMap, D extends OpDef> = '' extends OutputNames<D> ? SingleColumnNode<Defs> : MultiColumnNode<Defs, OutputNames<D>>;
+export type FluentRequest<From extends string | SourceRef = string> = BuiltRequest<From>;
+export declare class ProcessBuilder<Defs extends DefMap, From extends string | SourceRef = string> {
+    #private;
+    constructor(registry: Registry<Defs>, from: From);
+    /** Refers to one raw numeric column of the bound source. */
+    column(name: string): FluentColumnRef<Defs>;
+    /** Names the request so another request may refer to its result. */
+    as(name: string): this;
+    /**
+     * Finishes the request and names its surfaced values in one place.
+     *
+     * The result is still the exact plain-data envelope accepted by `Host`.
+     */
+    outputs(outputs: Readonly<Record<string, ColumnSelection | FactRef>>): FluentRequest<From>;
+}
+export declare function process<const Defs extends DefMap>(registry: Registry<Defs>, from: string): ProcessBuilder<Defs, string>;
+export declare function process<const Defs extends DefMap, const From extends SourceRef>(registry: Registry<Defs>, from: From): ProcessBuilder<Defs, From>;
+export {};
+//# sourceMappingURL=fluent.d.ts.map

package/dist/plan/fluent.js

@@ -0,0 +1,140 @@
+/**
+ * Registry-bound fluent authoring.
+ *
+ * This is a compiler into the slot envelope, not a second execution path.
+ * The registry's accumulated literal type supplies op names, params, input
+ * roles and output suffixes; runtime plans still pass through normal registry
+ * validation because requests may also arrive as JSON.
+ */
+import { isFold } from './types.js';
+import { BuilderError, foldSlot, PlanBuilder, } from './builder.js';
+const INPUT = Symbol.for('@pond-ts/process/input');
+export class ProcessBuilder {
+    #registry;
+    #builder;
+    #folds = new Map();
+    constructor(registry, from) {
+        this.#registry = registry;
+        this.#builder = new PlanBuilder(from);
+    }
+    /** Refers to one raw numeric column of the bound source. */
+    column(name) {
+        return this.#column(name);
+    }
+    /** Names the request so another request may refer to its result. */
+    as(name) {
+        this.#builder.as(name);
+        return this;
+    }
+    /**
+     * Finishes the request and names its surfaced values in one place.
+     *
+     * The result is still the exact plain-data envelope accepted by `Host`.
+     */
+    outputs(outputs) {
+        for (const [name, selected] of Object.entries(outputs)) {
+            this.#builder.expose(name, selected.selection.handle, selected.selection.output === undefined
+                ? undefined
+                : { output: selected.selection.output });
+        }
+        return this.#builder.toJSON();
+    }
+    #column(input, node, selectedOutput) {
+        const target = {
+            ...(node !== undefined && {
+                slot: node.slot,
+                columns: () => ({
+                    selection: {
+                        handle: node,
+                        ...(selectedOutput !== undefined && { output: selectedOutput }),
+                    },
+                }),
+            }),
+            last: () => this.#fold(input, 'last'),
+            extremes: () => this.#fold(input, 'extremes'),
+            percentileRank: () => this.#fold(input, 'percentileRank'),
+            shape: (options = {}) => this.#fold(input, 'shape', options),
+        };
+        Object.defineProperty(target, INPUT, { value: input });
+        return new Proxy(target, {
+            get: (base, property, receiver) => {
+                if (Reflect.has(base, property)) {
+                    return Reflect.get(base, property, receiver);
+                }
+                if (typeof property !== 'string')
+                    return undefined;
+                const def = this.#registry.get(property);
+                if (isFold(def))
+                    return undefined;
+                return (options) => this.#apply(input, def, options);
+            },
+        });
+    }
+    #apply(input, def, options) {
+        const slot = options['as'];
+        if (typeof slot !== 'string' || slot.length === 0) {
+            throw new BuilderError(`${def.name} requires a non-empty 'as' slot`);
+        }
+        const inputs = [input];
+        for (const declared of def.inputs.slice(1)) {
+            const ref = options[declared.role];
+            if (!isFluentColumn(ref)) {
+                throw new BuilderError(`${def.name} requires input '${declared.role}' to be a column reference`);
+            }
+            inputs.push(ref[INPUT]);
+        }
+        const params = Object.fromEntries(Object.keys(def.params)
+            .filter((key) => options[key] !== undefined)
+            .map((key) => [key, options[key]]));
+        const handle = this.#builder.add(slot, def.name, Object.keys(params).length === 0 ? undefined : params, inputs);
+        if (def.outputs.length === 1 && def.outputs[0].id === '') {
+            return this.#column(handle, handle);
+        }
+        return {
+            slot,
+            output: (name) => {
+                if (!def.outputs.some((output) => output.id === name)) {
+                    throw new BuilderError(`${def.name} has no output '${name}' — has ${def.outputs.map((o) => `'${o.id}'`).join(', ')}`);
+                }
+                const picked = { slot, output: name };
+                return this.#column(picked, handle, name);
+            },
+            columns: () => ({ selection: { handle } }),
+        };
+    }
+    #fold(input, op, params = {}) {
+        const inputName = typeof input === 'string'
+            ? `$${input}`
+            : 'output' in input
+                ? `${input.slot}#${input.output}`
+                : input.slot;
+        // The slot carries the fold's params — `foldSlot` — so asking the
+        // same node for `shape({points: 20})` and `shape({points: 100})`
+        // yields two nodes rather than the second silently reusing the
+        // first's 20. Params are canonicalized to their POST-DEFAULT form
+        // first, which this registry-bound layer can do and the plain
+        // builder cannot: `shape()` and `shape({points: 40})` are one
+        // computation to `specId`, so they must be one slot here too.
+        const given = params.points === undefined ? undefined : { points: params.points };
+        const def = this.#registry.get(op);
+        const explicit = given;
+        const canonical = Object.fromEntries(Object.entries(def.params).map(([key, d]) => [
+            key,
+            explicit?.[key] ?? d.default,
+        ]));
+        const slot = foldSlot(inputName, op, canonical);
+        let handle = this.#folds.get(slot);
+        if (handle === undefined) {
+            handle = this.#builder.add(slot, op, given, [input]);
+            this.#folds.set(slot, handle);
+        }
+        return { selection: { handle } };
+    }
+}
+function isFluentColumn(value) {
+    return (typeof value === 'object' && value !== null && Reflect.has(value, INPUT));
+}
+export function process(registry, from) {
+    return new ProcessBuilder(registry, from);
+}
+//# sourceMappingURL=fluent.js.map

package/dist/plan/folds.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The four folds every consumer wants, as ordinary registry entries.
+ *
+ * These were a hardcoded `reduce` enum on the selector — a second
+ * vocabulary alongside the registry, extensible only by editing this
+ * library, absent from every id, and recomputed on every request because
+ * the graph's memo stopped one step short of the thing callers read.
+ *
+ * They are pre-registered by `createRegistry()` because they apply to any
+ * numeric series and every consumer wants them, not because they are
+ * privileged. Each is a plain {@link FoldDef}: a consumer can `define`
+ * over a name to replace one, or add its own beside them.
+ *
+ * `at` is a function rather than an array on purpose. A fold reports two
+ * or three rows out of 150,000, and materializing the key column to
+ * answer that was most of what the old reductions cost.
+ */
+import type { FoldDef } from './types.js';
+export declare const last: FoldDef;
+export declare const extremes: FoldDef;
+export declare const percentileRank: FoldDef;
+export declare const shape: FoldDef;
+/** Registered by `createRegistry()`; nothing stops a consumer replacing one. */
+export declare const STANDARD_FOLDS: readonly FoldDef[];
+//# sourceMappingURL=folds.d.ts.map

package/dist/plan/folds.js

@@ -0,0 +1,190 @@
+/**
+ * The four folds every consumer wants, as ordinary registry entries.
+ *
+ * These were a hardcoded `reduce` enum on the selector — a second
+ * vocabulary alongside the registry, extensible only by editing this
+ * library, absent from every id, and recomputed on every request because
+ * the graph's memo stopped one step short of the thing callers read.
+ *
+ * They are pre-registered by `createRegistry()` because they apply to any
+ * numeric series and every consumer wants them, not because they are
+ * privileged. Each is a plain {@link FoldDef}: a consumer can `define`
+ * over a name to replace one, or add its own beside them.
+ *
+ * `at` is a function rather than an array on purpose. A fold reports two
+ * or three rows out of 150,000, and materializing the key column to
+ * answer that was most of what the old reductions cost.
+ */
+import { int } from './params.js';
+const day = (t) => new Date(t).toISOString().slice(0, 10);
+/**
+ * Six decimal places, applied at the boundary rather than in the graph.
+ *
+ * A column holds full `Float64Array` precision; a fact is read by a
+ * person or quoted by a model, and neither wants seventeen digits.
+ */
+const round = (v) => Math.round(v * 1e6) / 1e6;
+const source = [{ role: 'source' }];
+export const last = {
+    kind: 'fold',
+    name: 'last',
+    family: 'read',
+    summary: 'The most recent defined value, with its date. The usual way to ask "what is it now?".',
+    params: {},
+    inputs: source,
+    unit: 'inherit',
+    label: (_p, inputs) => `latest ${inputs}`,
+    fold: (ctx) => {
+        // The fold that makes [PND-PROCCOL] worth doing: it reads one cell,
+        // and on the boxed path it paid to densify all 500,000 first.
+        const v = read(ctx);
+        for (let i = v.length - 1; i >= 0; i -= 1) {
+            if (v.defined(i))
+                return { value: round(v.value(i)), at: day(ctx.at(i)) };
+        }
+        return { value: null };
+    },
+};
+export const extremes = {
+    kind: 'fold',
+    name: 'extremes',
+    family: 'read',
+    summary: 'The lowest and highest values over the whole series, each with its date.',
+    params: {},
+    inputs: source,
+    unit: 'inherit',
+    label: (_p, inputs) => `range of ${inputs}`,
+    fold: (ctx) => {
+        const v = read(ctx);
+        let lo = Infinity;
+        let hi = -Infinity;
+        let loAt = -1;
+        let hiAt = -1;
+        for (let i = 0; i < v.length; i += 1) {
+            if (!v.defined(i))
+                continue;
+            const x = v.value(i);
+            if (x < lo) {
+                lo = x;
+                loAt = i;
+            }
+            if (x > hi) {
+                hi = x;
+                hiAt = i;
+            }
+        }
+        if (loAt === -1)
+            return { min: null, max: null };
+        return {
+            min: { value: round(lo), at: day(ctx.at(loAt)) },
+            max: { value: round(hi), at: day(ctx.at(hiAt)) },
+        };
+    },
+};
+export const percentileRank = {
+    kind: 'fold',
+    name: 'percentileRank',
+    family: 'read',
+    summary: 'Where the latest value sits within the series’ own history, as a 0–1 fraction. Answers "is this unusual?" without needing a second series to compare against.',
+    params: {},
+    inputs: source,
+    // Not the input's unit: a rank is dimensionless, and inheriting made a
+    // percentile of an annualised vol report itself as '%/yr'.
+    unit: '%ile',
+    label: (_p, inputs) => `rank of ${inputs}`,
+    fold: (ctx) => {
+        const v = read(ctx);
+        // One pass, not the three the old reduction took: it densified, then
+        // filtered to find the last defined value, then filtered again to
+        // count below it.
+        let last;
+        let seen = 0;
+        for (let i = v.length - 1; i >= 0; i -= 1) {
+            if (v.defined(i)) {
+                last = v.value(i);
+                break;
+            }
+        }
+        if (last === undefined)
+            return { value: null };
+        let below = 0;
+        for (let i = 0; i < v.length; i += 1) {
+            if (!v.defined(i))
+                continue;
+            const x = v.value(i);
+            seen += 1;
+            if (x < last)
+                below += 1;
+        }
+        const fraction = below / seen;
+        return {
+            value: round(fraction),
+            note: `${Math.round(fraction * 100)}th percentile of ${seen} observations`,
+        };
+    },
+};
+export const shape = {
+    kind: 'fold',
+    name: 'shape',
+    family: 'read',
+    summary: 'A bounded sample of the whole series — the honest answer to "show me the series" for a caller paying by the token.',
+    // A param rather than a selector field, which is the difference that
+    // matters: it lands in the id, so two callers asking for 40 points
+    // share one answer instead of computing it twice.
+    params: {
+        points: int({ min: 2, max: 400, suggest: [20, 120], default: 40 }),
+    },
+    inputs: source,
+    unit: 'inherit',
+    label: (p, inputs) => `shape(${String(p['points'])}) of ${inputs}`,
+    fold: (ctx) => {
+        const v = read(ctx);
+        const want = ctx.params['points'];
+        // `ceil`, not `floor`: `floor` rounds the stride DOWN, which rounds
+        // the sample count UP — 200 points asked of 399 rows gave a stride
+        // of 1 and returned all 399, defeating the token bound this fold
+        // exists to keep. With `ceil` the sample never exceeds `points`.
+        const step = Math.max(1, Math.ceil(v.length / want));
+        const points = [];
+        for (let i = 0; i < v.length; i += step) {
+            if (v.defined(i))
+                points.push([day(ctx.at(i)), round(v.value(i))]);
+        }
+        return { points: points.length, series: points };
+    },
+};
+/**
+ * One reader over the `source` role, columnar where it can be.
+ *
+ * `ctx.numeric` is a zero-copy view and allocates nothing; `ctx.values`
+ * is the boxed fallback for a role that is not packed numeric, and is a
+ * lazy getter, so this only pays for densifying when it has to
+ * ([PND-PROCCOL]). Both are behind one shape so a fold body reads the
+ * same either way — `defined(i)` then `value(i)`, never a cell that
+ * might be `undefined`.
+ */
+function read(ctx) {
+    const view = ctx.numeric('source');
+    if (view !== undefined) {
+        const { values } = view;
+        return {
+            length: view.length,
+            defined: (i) => view.defined(i),
+            value: (i) => values[i],
+        };
+    }
+    const boxed = ctx.values['source'];
+    return {
+        length: boxed.length,
+        defined: (i) => boxed[i] !== undefined,
+        value: (i) => boxed[i],
+    };
+}
+/** Registered by `createRegistry()`; nothing stops a consumer replacing one. */
+export const STANDARD_FOLDS = [
+    last,
+    extremes,
+    percentileRank,
+    shape,
+];
+//# sourceMappingURL=folds.js.map