@loomwork/ui-hydration 0.0.0-stage → 0.1.0

package/dist/params.d.ts

@@ -0,0 +1,103 @@
+import type { Finding, MCPToolNode, ProviderSpec } from "@loomwork/ui-core";
+export type LoadParams = Readonly<Record<string, unknown>>;
+/** A time-range default a host may pass as `ControllerOptions.defaultParams`: the last 24 hours, relative to each pass. */
+export declare const DEFAULT_TIME_RANGE: LoadParams;
+/** `$now`, `$now-7d`, `$now+1h` (units s m h d w) as an ISO-8601 instant; `undefined` otherwise. */
+export declare function resolveTimeToken(token: string, now: number): string | undefined;
+/** Every token-shaped string leaf is resolved, or the whole value is refused. Other leaves pass. */
+export declare function resolveTimeTokens(value: unknown, now: number, where: string): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    finding: Finding;
+};
+/** A plain object `canonicalJson` can represent (no NaN/±Infinity, bigint, function, over-deep nest). */
+export declare function checkParams(params: unknown): Finding | undefined;
+/** Canonical identity of a param set (key order irrelevant); `""` for none. Throws only on what `checkParams` refuses. */
+export declare function paramsKey(params: LoadParams): string;
+/** Every argument name any step of the provider declares overridable, sorted. */
+export declare function providerParams(spec: ProviderSpec): string[];
+/**
+ * The named params the set actually holds (own keys only), as a fresh, FROZEN object — this is
+ * the object every step's `prepareArguments` call (and its argument hook) receives as `ctx.params`
+ * for the whole load, so a hook mutating it would leak into every other step's view of the load.
+ * Reads `params[n]` once per name: on params that crossed a trust boundary, snapshot them first
+ * (`snapshotParams`) — a live accessor that answered safely for an earlier, separate check (e.g.
+ * `checkParams` alone) is free to answer differently by the time THIS read runs.
+ */
+export declare function pickParams(params: LoadParams, names: readonly string[]): LoadParams;
+/**
+ * ONE plain, detached copy of untrusted params — a JSON round-trip through `canonicalJson`, so a
+ * value it refuses (a function, bigint, non-finite number, a cycle, past the depth cap) is caught
+ * HERE, and `JSON.parse` builds the result from that already-captured string alone: nothing
+ * downstream (`checkParams`, `pickParams`, `relevantParams`) ever reads a property of the SOURCE
+ * object again. Required wherever params cross a trust boundary (`serveHandle(s)`) — validating a
+ * live accessor and then separately picking named keys off it re-reads it, and a hostile getter is
+ * free to answer only the validating read safely and answer a later, picking read with something
+ * else entirely (observed: a plain value for the first two reads, a function for the third).
+ */
+export declare function snapshotParams(params: unknown): {
+    ok: true;
+    params: LoadParams;
+} | {
+    ok: false;
+    finding: Finding;
+};
+/** The params this provider can use: everything else cannot change its answer. */
+export declare function relevantParams(spec: ProviderSpec, params: LoadParams): LoadParams;
+export declare function applyParams(node: MCPToolNode, params: LoadParams): {
+    args: Record<string, unknown>;
+    findings: Finding[];
+};
+/** {@link applyParams}, plus which top-level arguments a param actually replaced (U9b needs them). */
+export declare function applyParamsDetailed(node: MCPToolNode, params: LoadParams): {
+    args: Record<string, unknown>;
+    findings: Finding[];
+    replaced: string[];
+};
+export interface ArgumentHookContext {
+    readonly handle: string;
+    readonly stepId: string;
+    readonly toolName: string;
+    /**
+     * The step's data-provider kind; absent for an MCP step. A hook that branches on `toolName`
+     * must also read this: an MCP tool `x` and a loom effect `x` are different targets.
+     */
+    readonly kind?: string;
+    /**
+     * The load's params as declared — under `executeProvider`, only those some step of the provider
+     * declares overridable — with time tokens NOT resolved (`now` is the instant they resolve against).
+     */
+    readonly params: LoadParams;
+    /** The instant this load resolved its time tokens against (epoch ms). */
+    readonly now: number;
+}
+/** The host's last word on a step's arguments: after params, time tokens and templates; before the call. */
+export type ArgumentHook = (args: Record<string, unknown>, ctx: ArgumentHookContext) => Record<string, unknown>;
+export interface PrepareContext {
+    readonly handle: string;
+    readonly params: LoadParams;
+    readonly now: number;
+    readonly hook?: ArgumentHook;
+    /**
+     * Runs after params are applied and before time tokens, templates or the hook (U9b's content-reference
+     * guard, `contentRefs.ts`, is the one user); a returned finding refuses the step. `replaced` names the
+     * top-level arguments a param actually replaced.
+     */
+    readonly guard?: (node: MCPToolNode, applied: {
+        readonly args: Record<string, unknown>;
+        readonly replaced: readonly string[];
+    }) => Finding | undefined;
+    /** Rewrites the arguments after templates resolve and before the hook (U9b strips JSON null at marked paths). */
+    readonly finish?: (args: Record<string, unknown>) => Record<string, unknown>;
+}
+export declare function prepareArguments(node: MCPToolNode, outputs: ReadonlyMap<string, unknown>, ctx: PrepareContext): {
+    ok: true;
+    args: Record<string, unknown>;
+    findings: Finding[];
+} | {
+    ok: false;
+    finding: Finding;
+};
+//# sourceMappingURL=params.d.ts.map

package/dist/params.d.ts.map

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

package/dist/params.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TIME_RANGE = void 0;
+exports.resolveTimeToken = resolveTimeToken;
+exports.resolveTimeTokens = resolveTimeTokens;
+exports.checkParams = checkParams;
+exports.paramsKey = paramsKey;
+exports.providerParams = providerParams;
+exports.pickParams = pickParams;
+exports.snapshotParams = snapshotParams;
+exports.relevantParams = relevantParams;
+exports.applyParams = applyParams;
+exports.applyParamsDetailed = applyParamsDetailed;
+exports.prepareArguments = prepareArguments;
+const core_1 = require("@loomwork/core");
+const plan_1 = require("./plan");
+/** A time-range default a host may pass as `ControllerOptions.defaultParams`: the last 24 hours, relative to each pass. */
+exports.DEFAULT_TIME_RANGE = Object.freeze({ from: "$now-24h", to: "$now" });
+/** Token-shaped: `$now` not followed by a word character. `$nowcast` is an ordinary string. */
+const TOKEN_LIKE = /^\$now(?![A-Za-z0-9_])/;
+const TIME_TOKEN = /^\$now(?:([+-])(\d{1,9})([smhdw]))?$/;
+const UNIT_MS = {
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+};
+const bad = (code, message) => ({ code, severity: "error", message });
+const note = (code, message) => ({ code, severity: "warn", message });
+/** An async argument hook returns one of these: `prepareArguments` never awaits it. */
+function isThenable(v) {
+    return (v !== null && typeof v === "object" && typeof v.then === "function");
+}
+/** `$now`, `$now-7d`, `$now+1h` (units s m h d w) as an ISO-8601 instant; `undefined` otherwise. */
+function resolveTimeToken(token, now) {
+    const m = TIME_TOKEN.exec(token);
+    if (!m)
+        return undefined;
+    const offset = m[1] === undefined
+        ? 0
+        : (m[1] === "-" ? -1 : 1) * Number(m[2]) * UNIT_MS[m[3]];
+    const at = new Date(now + offset);
+    // Past ±8.64e15 ms a Date is invalid and `toISOString` would throw: refuse instead.
+    return Number.isNaN(at.getTime()) ? undefined : at.toISOString();
+}
+/** Every token-shaped string leaf is resolved, or the whole value is refused. Other leaves pass. */
+function resolveTimeTokens(value, now, where) {
+    let failure;
+    const visit = (v) => {
+        if (failure)
+            return v;
+        if (typeof v === "string") {
+            if (!TOKEN_LIKE.test(v))
+                return v;
+            const iso = resolveTimeToken(v, now);
+            if (iso !== undefined)
+                return iso;
+            failure = bad("invalid-time-token", `${where}: "${v.slice(0, 64)}" is not a relative-time token ($now, $now-7d, $now+1h; units s m h d w)`);
+            return v;
+        }
+        if (Array.isArray(v))
+            return v.map(visit);
+        if (v !== null && typeof v === "object")
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, visit(x)]));
+        return v;
+    };
+    const out = visit(value);
+    return failure ? { ok: false, finding: failure } : { ok: true, value: out };
+}
+const STEP_REF = /\{\{\s*steps\./;
+function containsStepTemplate(v) {
+    if (typeof v === "string")
+        return STEP_REF.test(v);
+    if (Array.isArray(v))
+        return v.some(containsStepTemplate);
+    if (v !== null && typeof v === "object")
+        return Object.values(v).some(containsStepTemplate);
+    return false;
+}
+/** A plain object `canonicalJson` can represent (no NaN/±Infinity, bigint, function, over-deep nest). */
+function checkParams(params) {
+    if (params === null || typeof params !== "object" || Array.isArray(params))
+        return bad("invalid-params", "params must be a plain object");
+    try {
+        (0, core_1.canonicalJson)(params);
+        return undefined;
+    }
+    catch (e) {
+        return bad("invalid-params", `params cannot be represented as JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/** Canonical identity of a param set (key order irrelevant); `""` for none. Throws only on what `checkParams` refuses. */
+function paramsKey(params) {
+    return Object.keys(params).length === 0 ? "" : (0, core_1.fnv1a64)((0, core_1.canonicalJson)(params));
+}
+/** Every argument name any step of the provider declares overridable, sorted. */
+function providerParams(spec) {
+    const names = new Set();
+    for (const step of spec.executionGraph)
+        for (const n of step.overridable ?? [])
+            names.add(n);
+    return [...names].sort();
+}
+/**
+ * The named params the set actually holds (own keys only), as a fresh, FROZEN object — this is
+ * the object every step's `prepareArguments` call (and its argument hook) receives as `ctx.params`
+ * for the whole load, so a hook mutating it would leak into every other step's view of the load.
+ * Reads `params[n]` once per name: on params that crossed a trust boundary, snapshot them first
+ * (`snapshotParams`) — a live accessor that answered safely for an earlier, separate check (e.g.
+ * `checkParams` alone) is free to answer differently by the time THIS read runs.
+ */
+function pickParams(params, names) {
+    return Object.freeze(Object.fromEntries(names.filter((n) => Object.hasOwn(params, n)).map((n) => [n, params[n]])));
+}
+/**
+ * ONE plain, detached copy of untrusted params — a JSON round-trip through `canonicalJson`, so a
+ * value it refuses (a function, bigint, non-finite number, a cycle, past the depth cap) is caught
+ * HERE, and `JSON.parse` builds the result from that already-captured string alone: nothing
+ * downstream (`checkParams`, `pickParams`, `relevantParams`) ever reads a property of the SOURCE
+ * object again. Required wherever params cross a trust boundary (`serveHandle(s)`) — validating a
+ * live accessor and then separately picking named keys off it re-reads it, and a hostile getter is
+ * free to answer only the validating read safely and answer a later, picking read with something
+ * else entirely (observed: a plain value for the first two reads, a function for the third).
+ */
+function snapshotParams(params) {
+    if (params === null || typeof params !== "object" || Array.isArray(params))
+        return { ok: false, finding: bad("invalid-params", "params must be a plain object") };
+    try {
+        return { ok: true, params: JSON.parse((0, core_1.canonicalJson)(params)) };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            finding: bad("invalid-params", `params cannot be represented as JSON: ${e instanceof Error ? e.message : String(e)}`),
+        };
+    }
+}
+/** The params this provider can use: everything else cannot change its answer. */
+function relevantParams(spec, params) {
+    return pickParams(params, providerParams(spec));
+}
+function applyParams(node, params) {
+    const { args, findings } = applyParamsDetailed(node, params);
+    return { args, findings };
+}
+/** {@link applyParams}, plus which top-level arguments a param actually replaced (U9b needs them). */
+function applyParamsDetailed(node, params) {
+    const names = node.overridable ?? [];
+    const findings = [];
+    const replaced = [];
+    if (names.length === 0)
+        return { args: node.arguments, findings, replaced };
+    // A Map, then `Object.fromEntries`: every write is CreateDataProperty, so an argument named
+    // `__proto__` lands as an own key instead of setting a prototype.
+    const args = new Map(Object.entries(node.arguments));
+    for (const name of names) {
+        if (!Object.hasOwn(params, name))
+            continue;
+        if (containsStepTemplate(args.get(name))) {
+            findings.push(note("param-templated", `step "${node.stepId}": argument "${name}" is a {{steps.…}} template — another step's output — so no param replaces it`));
+            continue;
+        }
+        const value = params[name];
+        if (containsStepTemplate(value)) {
+            findings.push(note("param-template-refused", `step "${node.stepId}": the param for "${name}" contains a {{steps.…}} template; a param is a literal, so it is not applied`));
+            continue;
+        }
+        args.set(name, value);
+        replaced.push(name);
+    }
+    return { args: Object.fromEntries(args), findings, replaced };
+}
+function prepareArguments(node, outputs, ctx) {
+    const applied = applyParamsDetailed(node, ctx.params);
+    const refused = ctx.guard?.(node, applied);
+    if (refused !== undefined)
+        return { ok: false, finding: refused };
+    const timed = resolveTimeTokens(applied.args, ctx.now, `step "${node.stepId}"`);
+    if (!timed.ok)
+        return timed;
+    const templated = (0, plan_1.resolveArguments)({ ...node, arguments: timed.value }, outputs);
+    if (!templated.ok)
+        return templated;
+    const finished = ctx.finish ? ctx.finish(templated.args) : templated.args;
+    if (ctx.hook === undefined)
+        return { ok: true, args: finished, findings: applied.findings };
+    let hooked;
+    try {
+        hooked = ctx.hook(finished, {
+            handle: ctx.handle,
+            stepId: node.stepId,
+            toolName: node.toolName,
+            ...(node.kind !== undefined && { kind: node.kind }),
+            params: ctx.params,
+            now: ctx.now,
+        });
+    }
+    catch (e) {
+        return {
+            ok: false,
+            finding: bad("argument-hook-failed", `step "${node.stepId}": the argument hook threw: ${e instanceof Error ? e.message : String(e)}`),
+        };
+    }
+    if (isThenable(hooked)) {
+        // The step callback never awaits a hook (it is documented as synchronous): swallow whatever
+        // this thenable eventually does, so an async hook never surfaces as an unhandled rejection.
+        hooked.then(() => { }, () => { });
+        return {
+            ok: false,
+            finding: bad("argument-hook-failed", `step "${node.stepId}": the argument hook returned a thenable — hooks must return the arguments object synchronously, not a Promise`),
+        };
+    }
+    if (hooked === null || typeof hooked !== "object" || Array.isArray(hooked))
+        return {
+            ok: false,
+            finding: bad("argument-hook-failed", `step "${node.stepId}": the argument hook returned ${hooked === null ? "null" : Array.isArray(hooked) ? "an array" : typeof hooked}, not an arguments object`),
+        };
+    return { ok: true, args: hooked, findings: applied.findings };
+}
+//# sourceMappingURL=params.js.map

package/dist/params.js.map

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

package/dist/path.d.ts

@@ -0,0 +1,12 @@
+/** The hydration projection's top-level key; equal to `@loomwork/ui-core`'s constant of the same name. */
+export declare const HYDRATION_VALUES_PREFIX = "values";
+/**
+ * The hydration handle a binding path names: the exact inverse of core's `hydrationPath`.
+ * `undefined` for a path not of the form `values.<handle>` with a non-empty handle (including the
+ * bare prefix and `values.`). Everything after the first `values.` is the handle, spelled exactly
+ * as `hydrationPath` spelled it. Note: blueprint-runtime resolves a binding path by splitting on
+ * `.`, so a handle that itself contains a dot round-trips here but will not resolve at render time —
+ * keep handles dot-free. A reserved handle (`__proto__` etc.) is returned as-is; the store refuses it.
+ */
+export declare function handleOfPath(path: string): string | undefined;
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAUA,0GAA0G;AAC1G,eAAO,MAAM,uBAAuB,WAA6C,CAAC;AAElF;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI7D"}

package/dist/path.js

@@ -0,0 +1,28 @@
+"use strict";
+// ── Binding path ↔ hydration handle, browser-safe ────────────────────────────────
+// A compiled widget binds to `values.<handle>`. `@loomwork/ui-core` owns that spelling for the
+// compile side (`hydrationPath`), but the client entry must not pull core's runtime module graph
+// into a browser bundle, and core cannot import hydration (hydration depends on core). So the
+// client entry carries its own definition of the prefix and the inverse, pinned against core's
+// twice: at compile time (the `satisfies` below, type-only, erased at build) and by
+// `path.test.ts`, which compares the values and round-trips `hydrationPath`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HYDRATION_VALUES_PREFIX = void 0;
+exports.handleOfPath = handleOfPath;
+/** The hydration projection's top-level key; equal to `@loomwork/ui-core`'s constant of the same name. */
+exports.HYDRATION_VALUES_PREFIX = "values";
+/**
+ * The hydration handle a binding path names: the exact inverse of core's `hydrationPath`.
+ * `undefined` for a path not of the form `values.<handle>` with a non-empty handle (including the
+ * bare prefix and `values.`). Everything after the first `values.` is the handle, spelled exactly
+ * as `hydrationPath` spelled it. Note: blueprint-runtime resolves a binding path by splitting on
+ * `.`, so a handle that itself contains a dot round-trips here but will not resolve at render time —
+ * keep handles dot-free. A reserved handle (`__proto__` etc.) is returned as-is; the store refuses it.
+ */
+function handleOfPath(path) {
+    const head = `${exports.HYDRATION_VALUES_PREFIX}.`;
+    if (!path.startsWith(head) || path.length === head.length)
+        return undefined;
+    return path.slice(head.length);
+}
+//# sourceMappingURL=path.js.map

package/dist/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":";AAAA,oFAAoF;AACpF,+FAA+F;AAC/F,iGAAiG;AACjG,8FAA8F;AAC9F,+FAA+F;AAC/F,oFAAoF;AACpF,6EAA6E;;;AAe7E,oCAIC;AAfD,0GAA0G;AAC7F,QAAA,uBAAuB,GAAG,QAA0C,CAAC;AAElF;;;;;;;GAOG;AACH,SAAgB,YAAY,CAAC,IAAY;IACvC,MAAM,IAAI,GAAG,GAAG,+BAAuB,GAAG,CAAC;IAC3C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC5E,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACjC,CAAC"}

package/dist/plan.d.ts

@@ -0,0 +1,56 @@
+import type { Finding, MCPToolNode } from "@loomwork/ui-core";
+/**
+ * Kahn's algorithm over step IDS, O(V + E): in-degree counts (distinct in-graph dependencies per
+ * step) and a dependents list built once, then a FIFO of ids whose level never decreases. A step's
+ * wave is 1 + the latest wave among its in-graph dependencies (0 with none); an id is placed at the
+ * earliest wave any step carrying it is ready. Waves are then filled in the input's own order, so a
+ * wave lists its steps exactly as the input does. This is the semantics of the original
+ * re-filtering loop, pinned by an equivalence test: a step whose id another step already placed in
+ * an EARLIER wave never runs (a duplicate id), and `cycle` lists — in input order — every step
+ * whose id is never placed (a cycle, or anything behind one).
+ */
+export declare function topoWaves(nodes: readonly MCPToolNode[]): {
+    waves: MCPToolNode[][];
+    cycle: string[];
+};
+export declare function terminalSteps(nodes: readonly MCPToolNode[]): MCPToolNode[];
+/**
+ * Why a path walk found nothing. `out-of-range`: the walk stopped at an `[i]` applied to a value
+ * that IS an array, with `i >= length` — the path is right, the upstream just has no such row (the
+ * row count is DATA). `absent`: every other miss — a missing own key, `null` or a primitive
+ * mid-path, an index on a non-array, a malformed segment — a BAD PATH.
+ */
+export type PathMiss = "out-of-range" | "absent";
+/** Dotted path with optional `[i]` indices, own properties only. A present `null` resolves to `null`. */
+export declare function walkPath(obj: unknown, dotted: string): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    cause: PathMiss;
+};
+/** `walkPath`'s value, or `undefined` when anything is missing. */
+export declare function resolvePath(obj: unknown, dotted: string): unknown;
+export declare const STEP_TEMPLATE: RegExp;
+/**
+ * Every step id `arguments` references through a `{{steps.<id>.output…}}` template, in first-seen
+ * order, deduplicated — the same template grammar `resolveArguments` substitutes, so a planner can
+ * check a graph it builds before it ships. At execution a reference resolves only against a step
+ * in a STRICTLY EARLIER `topoWaves` wave than the referencing step; a step outside the graph, or in
+ * the same or a later wave, has no output yet and is `unresolved-step-reference`.
+ */
+export declare function stepReferences(args: unknown): string[];
+/**
+ * Substitute every `{{steps.<id>.output.<path>}}` in the step's arguments. EVERY template is
+ * walked: a bad path anywhere (`absent`, or a step with no output) is `unresolved-step-reference`
+ * (an error) and wins; otherwise an index past the end of a present upstream array is
+ * `upstream-empty` (a warn — the upstream answered with no such row; loom ADR 0100's `empty`).
+ */
+export declare function resolveArguments(node: MCPToolNode, outputs: ReadonlyMap<string, unknown>): {
+    ok: true;
+    args: Record<string, unknown>;
+} | {
+    ok: false;
+    finding: Finding;
+};
+//# sourceMappingURL=plan.d.ts.map

package/dist/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAY9D;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG;IACxD,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CA+CA;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,EAAE,CAG1E;AAID;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,QAAQ,CAAC;AAEjD,yGAAyG;AACzG,wBAAgB,QAAQ,CACtB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,GACb;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAiB/D;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAGjE;AAED,eAAO,MAAM,aAAa,QAAyD,CAAC;AAEpF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAWtD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CA+C/E"}

package/dist/plan.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STEP_TEMPLATE = void 0;
+exports.topoWaves = topoWaves;
+exports.terminalSteps = terminalSteps;
+exports.walkPath = walkPath;
+exports.resolvePath = resolvePath;
+exports.stepReferences = stepReferences;
+exports.resolveArguments = resolveArguments;
+// ── Graph scheduling and argument templating ──────────────────────────────────
+// A ProviderSpec's executionGraph is a DAG of MCP steps. Steps run in topological WAVES (every
+// step in a wave has all its in-graph dependencies in earlier waves). A dependency naming a step
+// outside the graph is treated as satisfied — the planner may reference a step it pruned — and a
+// cycle is reported, never looped over. Arguments may embed `{{steps.<id>.output.<path>}}`,
+// resolved from an earlier step's raw output over OWN properties only: the path is model-written
+// and walked over a tool response, so an unguarded walk is a prototype-pollution read. An index
+// past the end of a present array is not a bad path — the upstream answered with no such row —
+// and is reported apart from every other miss (`walkPath`), so it can publish `empty`.
+/**
+ * Kahn's algorithm over step IDS, O(V + E): in-degree counts (distinct in-graph dependencies per
+ * step) and a dependents list built once, then a FIFO of ids whose level never decreases. A step's
+ * wave is 1 + the latest wave among its in-graph dependencies (0 with none); an id is placed at the
+ * earliest wave any step carrying it is ready. Waves are then filled in the input's own order, so a
+ * wave lists its steps exactly as the input does. This is the semantics of the original
+ * re-filtering loop, pinned by an equivalence test: a step whose id another step already placed in
+ * an EARLIER wave never runs (a duplicate id), and `cycle` lists — in input order — every step
+ * whose id is never placed (a cycle, or anything behind one).
+ */
+function topoWaves(nodes) {
+    const ids = new Set(nodes.map((n) => n.stepId));
+    const pending = new Array(nodes.length);
+    const readyAt = new Array(nodes.length).fill(-1);
+    const latestDep = new Array(nodes.length).fill(-1);
+    const dependents = new Map();
+    const placedAt = new Map();
+    const queue = [];
+    const ready = (i, level) => {
+        readyAt[i] = level;
+        const id = nodes[i].stepId;
+        if (placedAt.has(id))
+            return;
+        placedAt.set(id, level);
+        queue.push(id);
+    };
+    nodes.forEach((n, i) => {
+        const deps = new Set(n.dependsOn.filter((d) => ids.has(d)));
+        pending[i] = deps.size;
+        for (const d of deps) {
+            const list = dependents.get(d);
+            if (list === undefined)
+                dependents.set(d, [i]);
+            else
+                list.push(i);
+        }
+    });
+    nodes.forEach((_, i) => {
+        if (pending[i] === 0)
+            ready(i, 0);
+    });
+    for (let head = 0; head < queue.length; head++) {
+        const id = queue[head];
+        const level = placedAt.get(id);
+        for (const i of dependents.get(id) ?? []) {
+            latestDep[i] = Math.max(latestDep[i], level);
+            pending[i] = pending[i] - 1;
+            if (pending[i] === 0)
+                ready(i, latestDep[i] + 1);
+        }
+    }
+    const waves = [];
+    const cycle = [];
+    nodes.forEach((n, i) => {
+        const at = placedAt.get(n.stepId);
+        if (at === undefined)
+            cycle.push(n.stepId);
+        else if (readyAt[i] === at) {
+            while (waves.length <= at)
+                waves.push([]);
+            waves[at].push(n);
+        }
+    });
+    return { waves, cycle };
+}
+function terminalSteps(nodes) {
+    const depended = new Set(nodes.flatMap((n) => n.dependsOn));
+    return nodes.filter((n) => !depended.has(n.stepId));
+}
+const SEGMENT = /^([^[\]]+)((?:\[\d+\])*)$/;
+/** Dotted path with optional `[i]` indices, own properties only. A present `null` resolves to `null`. */
+function walkPath(obj, dotted) {
+    const absent = { ok: false, cause: "absent" };
+    let cur = obj;
+    for (const part of dotted.split(".")) {
+        const m = SEGMENT.exec(part);
+        if (!m || cur === null || typeof cur !== "object")
+            return absent;
+        const key = m[1];
+        if (!Object.hasOwn(cur, key))
+            return absent;
+        cur = cur[key];
+        for (const idx of (m[2] ?? "").match(/\d+/g) ?? []) {
+            if (!Array.isArray(cur))
+                return absent;
+            const i = Number(idx);
+            if (i >= cur.length)
+                return { ok: false, cause: "out-of-range" };
+            cur = cur[i];
+        }
+    }
+    return { ok: true, value: cur };
+}
+/** `walkPath`'s value, or `undefined` when anything is missing. */
+function resolvePath(obj, dotted) {
+    const r = walkPath(obj, dotted);
+    return r.ok ? r.value : undefined;
+}
+exports.STEP_TEMPLATE = /^\{\{steps\.([A-Za-z0-9_-]+)\.output(?:\.(.+))?\}\}$/;
+/**
+ * Every step id `arguments` references through a `{{steps.<id>.output…}}` template, in first-seen
+ * order, deduplicated — the same template grammar `resolveArguments` substitutes, so a planner can
+ * check a graph it builds before it ships. At execution a reference resolves only against a step
+ * in a STRICTLY EARLIER `topoWaves` wave than the referencing step; a step outside the graph, or in
+ * the same or a later wave, has no output yet and is `unresolved-step-reference`.
+ */
+function stepReferences(args) {
+    const found = new Set();
+    const visit = (v) => {
+        if (typeof v === "string") {
+            const m = exports.STEP_TEMPLATE.exec(v);
+            if (m)
+                found.add(m[1]);
+        }
+        else if (Array.isArray(v))
+            for (const x of v)
+                visit(x);
+        else if (v !== null && typeof v === "object")
+            for (const x of Object.values(v))
+                visit(x);
+    };
+    visit(args);
+    return [...found];
+}
+/**
+ * Substitute every `{{steps.<id>.output.<path>}}` in the step's arguments. EVERY template is
+ * walked: a bad path anywhere (`absent`, or a step with no output) is `unresolved-step-reference`
+ * (an error) and wins; otherwise an index past the end of a present upstream array is
+ * `upstream-empty` (a warn — the upstream answered with no such row; loom ADR 0100's `empty`).
+ */
+function resolveArguments(node, outputs) {
+    let bad;
+    let empty;
+    const visit = (v) => {
+        if (typeof v === "string") {
+            const m = exports.STEP_TEMPLATE.exec(v);
+            if (!m)
+                return v;
+            const stepId = m[1];
+            if (!outputs.has(stepId)) {
+                bad ??= {
+                    code: "unresolved-step-reference",
+                    severity: "error",
+                    message: `step "${node.stepId}" references "${stepId}", which has no output`,
+                };
+                return v;
+            }
+            const path = m[2];
+            const out = path === undefined
+                ? { ok: true, value: outputs.get(stepId) }
+                : walkPath(outputs.get(stepId), path);
+            // A present `undefined` (never produced by JSON) is treated as nothing, as before.
+            if (out.ok && out.value !== undefined)
+                return out.value;
+            if (!out.ok && out.cause === "out-of-range")
+                empty ??= {
+                    code: "upstream-empty",
+                    severity: "warn",
+                    message: `step "${node.stepId}" references "${stepId}" at path "${path ?? ""}": the upstream has no such row`,
+                };
+            else
+                bad ??= {
+                    code: "unresolved-step-reference",
+                    severity: "error",
+                    message: `step "${node.stepId}" references "${stepId}" at path "${path ?? ""}", which resolves to nothing`,
+                };
+            return v;
+        }
+        if (Array.isArray(v))
+            return v.map(visit);
+        // `Object.fromEntries` writes with CreateDataProperty: an own `__proto__` argument stays an
+        // own key instead of becoming the args object's prototype (an assignment would set it).
+        if (v !== null && typeof v === "object")
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, visit(x)]));
+        return v;
+    };
+    const args = visit(node.arguments);
+    const failure = bad ?? empty;
+    return failure ? { ok: false, finding: failure } : { ok: true, args };
+}
+//# sourceMappingURL=plan.js.map