@ifc-lite/flow 0.2.0

package/dist/document.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The `*.flow.json` document: a git-diffable description of a graph.
+ *
+ * Hand-validated like extension manifests (no schema library), with a
+ * migration chain keyed on `flowVersion`. Positions live here; tracked
+ * element sets do not (they are model-specific and live in a sidecar, see
+ * `tracking.ts`).
+ */
+import type { Lacing } from './values.js';
+export declare const FLOW_VERSION = 1;
+export type TrackingMode = 'update' | 'replace' | 'disabled';
+/** Player input kinds — what a form can ask for (Dynamo Player parity). */
+export type InputKind = 'scalar' | 'enum' | 'entitySet' | 'storey' | 'file' | 'table';
+export interface FlowNode {
+    readonly id: string;
+    readonly type: string;
+    readonly params?: Readonly<Record<string, unknown>>;
+    readonly lacing?: Lacing;
+    readonly tracking?: TrackingMode;
+    /** User-visible identity of a write node's output; drives GlobalIds. */
+    readonly trackingKey?: string;
+    readonly label?: string;
+    readonly pos?: readonly [number, number];
+}
+export interface FlowEdge {
+    readonly from: readonly [nodeId: string, port: string];
+    readonly to: readonly [nodeId: string, port: string];
+}
+/** "Is Input": a node param the Player form sets. */
+export interface FlowInput {
+    readonly nodeId: string;
+    readonly param: string;
+    readonly label: string;
+    readonly kind: InputKind;
+    readonly options?: readonly string[];
+}
+/** "Is Output": a node port shown as a result. */
+export interface FlowOutput {
+    readonly nodeId: string;
+    readonly port: string;
+    readonly label: string;
+}
+export interface FlowDocument {
+    readonly flowVersion: number;
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly capabilities: readonly string[];
+    readonly inputs: readonly FlowInput[];
+    readonly outputs: readonly FlowOutput[];
+    readonly nodes: readonly FlowNode[];
+    readonly edges: readonly FlowEdge[];
+    /** Per-graph override of the cross-lacing guard. */
+    readonly maxCross?: number;
+}
+export interface DocumentProblem {
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * Structural validation of an untrusted document. Node *types* are checked
+ * against a registry by the scheduler, not here, so a document can be
+ * validated without one.
+ */
+export declare function validateFlowDocument(value: unknown): DocumentProblem[];
+/** Parse + validate; throws with every problem listed. */
+export declare function parseFlowDocument(text: string): FlowDocument;
+/**
+ * Migration chain: each step lifts `flowVersion` by one. There is only
+ * version 1 today; the chain exists so a v1 file keeps opening after v2.
+ */
+export declare function migrateFlowDocument(value: unknown): unknown;
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

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

package/dist/document.js

@@ -0,0 +1,158 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+export const FLOW_VERSION = 1;
+const LACINGS = ['shortest', 'longest', 'cross'];
+const TRACKINGS = ['update', 'replace', 'disabled'];
+const INPUT_KINDS = ['scalar', 'enum', 'entitySet', 'storey', 'file', 'table'];
+function isRecord(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+function str(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+/**
+ * Structural validation of an untrusted document. Node *types* are checked
+ * against a registry by the scheduler, not here, so a document can be
+ * validated without one.
+ */
+export function validateFlowDocument(value) {
+    const problems = [];
+    const add = (path, message) => problems.push({ path, message });
+    if (!isRecord(value))
+        return [{ path: '', message: 'must be an object' }];
+    if (value.flowVersion !== FLOW_VERSION)
+        add('flowVersion', `must be ${FLOW_VERSION} (run migrateFlowDocument first)`);
+    if (!str(value.id))
+        add('id', 'must be a non-empty string');
+    if (!str(value.name))
+        add('name', 'must be a non-empty string');
+    if (value.description !== undefined && typeof value.description !== 'string')
+        add('description', 'must be a string');
+    // `!Number.isFinite` first: `NaN < 1` is false, so a NaN bound would pass a
+    // one-ended check and then disable the cross guard entirely (every
+    // `size > NaN` is false).
+    if (value.maxCross !== undefined && (typeof value.maxCross !== 'number' || !Number.isFinite(value.maxCross) || value.maxCross < 1))
+        add('maxCross', 'must be a finite number >= 1');
+    for (const key of ['capabilities', 'inputs', 'outputs', 'nodes', 'edges']) {
+        if (!Array.isArray(value[key]))
+            add(key, 'must be an array');
+    }
+    if (problems.length > 0)
+        return problems;
+    value.capabilities.forEach((c, i) => {
+        if (!str(c))
+            add(`capabilities[${i}]`, 'must be a non-empty string');
+    });
+    const nodeIds = new Set();
+    value.nodes.forEach((n, i) => {
+        const p = `nodes[${i}]`;
+        if (!isRecord(n))
+            return add(p, 'must be an object');
+        if (!str(n.id))
+            add(`${p}.id`, 'must be a non-empty string');
+        else if (nodeIds.has(n.id))
+            add(`${p}.id`, `duplicate node id "${n.id}"`);
+        else
+            nodeIds.add(n.id);
+        if (!str(n.type))
+            add(`${p}.type`, 'must be a non-empty string');
+        if (n.params !== undefined && !isRecord(n.params))
+            add(`${p}.params`, 'must be an object');
+        if (n.lacing !== undefined && !LACINGS.includes(n.lacing))
+            add(`${p}.lacing`, `must be one of ${LACINGS.join(', ')}`);
+        if (n.tracking !== undefined && !TRACKINGS.includes(n.tracking))
+            add(`${p}.tracking`, `must be one of ${TRACKINGS.join(', ')}`);
+        if (n.trackingKey !== undefined && !str(n.trackingKey))
+            add(`${p}.trackingKey`, 'must be a non-empty string');
+        if (n.label !== undefined && typeof n.label !== 'string')
+            add(`${p}.label`, 'must be a string');
+        if (n.pos !== undefined && !(Array.isArray(n.pos) && n.pos.length === 2 && n.pos.every((x) => typeof x === 'number')))
+            add(`${p}.pos`, 'must be [x, y]');
+    });
+    const endpoint = (v, p) => {
+        if (!Array.isArray(v) || v.length !== 2 || !str(v[0]) || !str(v[1])) {
+            add(p, 'must be [nodeId, port]');
+            return false;
+        }
+        if (!nodeIds.has(v[0])) {
+            add(p, `unknown node "${v[0]}"`);
+            return false;
+        }
+        return true;
+    };
+    const targets = new Set();
+    value.edges.forEach((e, i) => {
+        const p = `edges[${i}]`;
+        if (!isRecord(e))
+            return add(p, 'must be an object');
+        endpoint(e.from, `${p}.from`);
+        if (endpoint(e.to, `${p}.to`)) {
+            const k = `${e.to[0]}.${e.to[1]}`;
+            if (targets.has(k))
+                add(`${p}.to`, `input ${k} has more than one incoming edge`);
+            targets.add(k);
+        }
+    });
+    value.inputs.forEach((inp, i) => {
+        const p = `inputs[${i}]`;
+        if (!isRecord(inp))
+            return add(p, 'must be an object');
+        if (!str(inp.nodeId) || !nodeIds.has(inp.nodeId))
+            add(`${p}.nodeId`, 'must name a node');
+        if (!str(inp.param))
+            add(`${p}.param`, 'must be a non-empty string');
+        if (!str(inp.label))
+            add(`${p}.label`, 'must be a non-empty string');
+        if (!INPUT_KINDS.includes(inp.kind))
+            add(`${p}.kind`, `must be one of ${INPUT_KINDS.join(', ')}`);
+        if (inp.options !== undefined && !(Array.isArray(inp.options) && inp.options.every(str)))
+            add(`${p}.options`, 'must be an array of strings');
+    });
+    value.outputs.forEach((o, i) => {
+        const p = `outputs[${i}]`;
+        if (!isRecord(o))
+            return add(p, 'must be an object');
+        if (!str(o.nodeId) || !nodeIds.has(o.nodeId))
+            add(`${p}.nodeId`, 'must name a node');
+        if (!str(o.port))
+            add(`${p}.port`, 'must be a non-empty string');
+        if (!str(o.label))
+            add(`${p}.label`, 'must be a non-empty string');
+    });
+    return problems;
+}
+/** Parse + validate; throws with every problem listed. */
+export function parseFlowDocument(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`flow document is not valid JSON: ${err.message}`);
+    }
+    const migrated = migrateFlowDocument(value);
+    const problems = validateFlowDocument(migrated);
+    if (problems.length > 0) {
+        throw new Error(`invalid flow document:\n${problems.map((p) => `  ${p.path || '<root>'}: ${p.message}`).join('\n')}`);
+    }
+    return migrated;
+}
+/**
+ * Migration chain: each step lifts `flowVersion` by one. There is only
+ * version 1 today; the chain exists so a v1 file keeps opening after v2.
+ */
+export function migrateFlowDocument(value) {
+    if (!isRecord(value))
+        return value;
+    let doc = value;
+    while (typeof doc.flowVersion === 'number' && doc.flowVersion < FLOW_VERSION) {
+        const step = MIGRATIONS[doc.flowVersion];
+        if (!step)
+            break;
+        doc = step(doc);
+    }
+    return doc;
+}
+const MIGRATIONS = {};
+//# sourceMappingURL=document.js.map

package/dist/document.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export { item, list, group, flatten, asGroup, countItems, isAssignable, SINGLE_BRANCH, } from './values.js';
+export type { Access, Lacing, GroupKey, FlowData, Scalar, EntityRef, Point, Polyline, Placement, Profile, ValueKind, PortType, } from './values.js';
+export { COLUMN_TYPES, validateTable, column, rowKey, groupRows, pivot } from './table.js';
+export type { ColumnType, Column, Cell, Row, Table, TableProblem, GroupedRows } from './table.js';
+export { canonicalJson, digest, digestFlowData, trackingGuid } from './digest.js';
+export { NodeRegistry, resolveParams } from './registry.js';
+export type { PortDef, ParamDef, ParamKind, LogLevel, LaneTracking, NodeRunContext, NodeOutputs, NodeDef } from './registry.js';
+export { planLift, assemble, CrossProductTooLarge } from './lift.js';
+export type { LiftInput, Lane, LiftPlan, LiftOptions } from './lift.js';
+export { FLOW_VERSION, validateFlowDocument, parseFlowDocument, migrateFlowDocument } from './document.js';
+export type { TrackingMode, InputKind, FlowNode, FlowEdge, FlowInput, FlowOutput, FlowDocument, DocumentProblem, } from './document.js';
+export { TRACKING_SIDECAR_VERSION, emptyTrackedSet, planTracking, trackedSetFrom, withTrackedSet, TrackingPinMismatch, isTrackedSet, trackedSetsFrom, MemoryTrackingStore, } from './tracking.js';
+export type { TrackedEntry, TrackedSet, TrackingSidecar, TrackingStore, DesiredLane, TrackingPlan } from './tracking.js';
+export { validateFlowWiring } from './wiring.js';
+export { describeFlowIO, declaredInputKeys, resolveDeclaredParam, unknownInputKeys } from './introspect.js';
+export type { FlowIO, FlowInputInfo, FlowOutputInfo } from './introspect.js';
+export { nodeAvailability, checkAvailability } from './availability.js';
+export type { HostFeatures, AvailabilityStatus, NodeAvailability } from './availability.js';
+export { runFlow, topologicalOrder, MemoCache, FlowCycleError, DEFAULT_MAX_CROSS } from './scheduler.js';
+export { trackingKeyOf, ORPHAN_NODE_ID } from './orphans.js';
+export type { RunOptions, RunResult, RunLogEntry, NodeReport, NodeStatus, GraphOutputValue } from './scheduler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,OAAO,EACP,OAAO,EACP,UAAU,EACV,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,MAAM,EACN,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,QAAQ,EACR,SAAS,EACT,OAAO,EACP,SAAS,EACT,QAAQ,GACT,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC3F,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAElG,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAElF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC5D,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAEhI,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACrE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC3G,YAAY,EACV,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,UAAU,EACV,YAAY,EACZ,eAAe,GAChB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,YAAY,EACZ,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEzH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC5G,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACxE,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE5F,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACzG,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+export { item, list, group, flatten, asGroup, countItems, isAssignable, SINGLE_BRANCH, } from './values.js';
+export { COLUMN_TYPES, validateTable, column, rowKey, groupRows, pivot } from './table.js';
+export { canonicalJson, digest, digestFlowData, trackingGuid } from './digest.js';
+export { NodeRegistry, resolveParams } from './registry.js';
+export { planLift, assemble, CrossProductTooLarge } from './lift.js';
+export { FLOW_VERSION, validateFlowDocument, parseFlowDocument, migrateFlowDocument } from './document.js';
+export { TRACKING_SIDECAR_VERSION, emptyTrackedSet, planTracking, trackedSetFrom, withTrackedSet, TrackingPinMismatch, isTrackedSet, trackedSetsFrom, MemoryTrackingStore, } from './tracking.js';
+export { validateFlowWiring } from './wiring.js';
+export { describeFlowIO, declaredInputKeys, resolveDeclaredParam, unknownInputKeys } from './introspect.js';
+export { nodeAvailability, checkAvailability } from './availability.js';
+export { runFlow, topologicalOrder, MemoCache, FlowCycleError, DEFAULT_MAX_CROSS } from './scheduler.js';
+export { trackingKeyOf, ORPHAN_NODE_ID } from './orphans.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAE/D,OAAO,EACL,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,OAAO,EACP,OAAO,EACP,UAAU,EACV,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AAgBrB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAG3F,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAElF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG5D,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAGrE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAY3G,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,YAAY,EACZ,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE5G,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGxE,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACzG,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/introspect.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared flow introspection + input-validation helpers used by every
+ * headless caller of a `.flow.json` graph: the CLI's `flow describe`/`flow
+ * run` and MCP's `describe_flow`/`run_flow`.
+ *
+ * Kept in one place because the input-validation rule here is a
+ * correctness rule, not a formatting choice. The CLI had exactly this bug
+ * once: `--input rating=REI90` (missing the node id) named no declared
+ * parameter, was silently dropped, and the graph ran on its defaults while
+ * reporting success (issue #5167). A second, independently written copy of
+ * "is this key a declared parameter" in another caller is exactly how that
+ * regresses somewhere else — so both go through {@link resolveDeclaredParam}.
+ */
+import type { FlowDocument, InputKind } from './document.js';
+import type { NodeRegistry, ParamDef, ParamKind } from './registry.js';
+import type { Access, ValueKind } from './values.js';
+export interface FlowInputInfo {
+    readonly key: string;
+    readonly label: string;
+    readonly kind: InputKind;
+    readonly options?: readonly string[];
+    readonly default?: unknown;
+    readonly paramKind?: ParamKind;
+}
+export interface FlowOutputInfo {
+    readonly key: string;
+    readonly label: string;
+    readonly kind?: ValueKind;
+    readonly access?: Access;
+}
+export interface FlowIO {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly capabilities: readonly string[];
+    readonly inputs: readonly FlowInputInfo[];
+    readonly outputs: readonly FlowOutputInfo[];
+}
+/** The declared inputs/outputs schema of a graph — the Hops `/io` equivalent. */
+export declare function describeFlowIO(doc: FlowDocument, registry: NodeRegistry<unknown>): FlowIO;
+/** `nodeId.param` for every declared Player input — the list a caller echoes back on a bad key. */
+export declare function declaredInputKeys(doc: FlowDocument): readonly string[];
+/**
+ * Resolve a `nodeId.param` input key against the document + registry — the
+ * ONE lookup every caller uses to decide whether a key is a declared
+ * parameter. Returns undefined for a malformed key (no dot), a key naming
+ * no node, or a node with no such param — regardless of whether the key
+ * also appears in `doc.inputs` (a node can accept a param override the
+ * Player form never exposed).
+ */
+export declare function resolveDeclaredParam(key: string, doc: FlowDocument, registry: NodeRegistry<unknown>): {
+    readonly nodeId: string;
+    readonly param: ParamDef;
+} | undefined;
+/**
+ * Every key in `inputs` that names no declared parameter. Empty when every
+ * key resolves. A run must refuse rather than silently ignore any key this
+ * returns — see the module doc for why.
+ */
+export declare function unknownInputKeys(inputs: Readonly<Record<string, unknown>> | undefined, doc: FlowDocument, registry: NodeRegistry<unknown>): readonly string[];
+//# sourceMappingURL=introspect.d.ts.map

package/dist/introspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspect.d.ts","sourceRoot":"","sources":["../src/introspect.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,MAAM,CAYzF;AAED,mGAAmG;AACnG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,CAEtE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,YAAY,CAAC,OAAO,CAAC,GAC9B;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,GAAG,SAAS,CAQnE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EACrD,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,YAAY,CAAC,OAAO,CAAC,GAC9B,SAAS,MAAM,EAAE,CAGnB"}

package/dist/introspect.js

@@ -0,0 +1,51 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/** The declared inputs/outputs schema of a graph — the Hops `/io` equivalent. */
+export function describeFlowIO(doc, registry) {
+    const inputs = doc.inputs.map((i) => {
+        const def = registry.get(doc.nodes.find((n) => n.id === i.nodeId)?.type ?? '');
+        const param = def?.params.find((p) => p.name === i.param);
+        return { key: `${i.nodeId}.${i.param}`, label: i.label, kind: i.kind, options: i.options, default: param?.default, paramKind: param?.kind };
+    });
+    const outputs = doc.outputs.map((o) => {
+        const def = registry.get(doc.nodes.find((n) => n.id === o.nodeId)?.type ?? '');
+        const port = def?.outputs.find((p) => p.name === o.port);
+        return { key: `${o.nodeId}.${o.port}`, label: o.label, kind: port?.type.kind, access: port?.type.access };
+    });
+    return { id: doc.id, name: doc.name, description: doc.description, capabilities: doc.capabilities, inputs, outputs };
+}
+/** `nodeId.param` for every declared Player input — the list a caller echoes back on a bad key. */
+export function declaredInputKeys(doc) {
+    return doc.inputs.map((i) => `${i.nodeId}.${i.param}`);
+}
+/**
+ * Resolve a `nodeId.param` input key against the document + registry — the
+ * ONE lookup every caller uses to decide whether a key is a declared
+ * parameter. Returns undefined for a malformed key (no dot), a key naming
+ * no node, or a node with no such param — regardless of whether the key
+ * also appears in `doc.inputs` (a node can accept a param override the
+ * Player form never exposed).
+ */
+export function resolveDeclaredParam(key, doc, registry) {
+    const dot = key.lastIndexOf('.');
+    if (dot <= 0)
+        return undefined;
+    const nodeId = key.slice(0, dot);
+    const node = doc.nodes.find((n) => n.id === nodeId);
+    if (!node)
+        return undefined;
+    const param = registry.get(node.type)?.params.find((p) => p.name === key.slice(dot + 1));
+    return param ? { nodeId, param } : undefined;
+}
+/**
+ * Every key in `inputs` that names no declared parameter. Empty when every
+ * key resolves. A run must refuse rather than silently ignore any key this
+ * returns — see the module doc for why.
+ */
+export function unknownInputKeys(inputs, doc, registry) {
+    if (!inputs)
+        return [];
+    return Object.keys(inputs).filter((key) => !resolveDeclaredParam(key, doc, registry));
+}
+//# sourceMappingURL=introspect.js.map

package/dist/introspect.js.map

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

package/dist/lift.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Lifting: how a node declared over items/lists/groups is applied to the
+ * structured data that actually arrives on its ports.
+ *
+ * Rules (the whole data-tree story fits in these):
+ *  1. A `group` port receives the input as a group (an item or list becomes
+ *     the single branch `""`). No lifting.
+ *  2. If any `item`/`list` port receives a group, the node is lifted over
+ *     the union of branch keys, and branches match **by key**, never by
+ *     position. A key absent on a required port is reported under
+ *     `missing`, and that lane is skipped.
+ *  3. Inside a branch (or at top level), `item` ports that receive lists are
+ *     laced: `shortest`, `longest` (repeat last), or `cross` (cartesian, key
+ *     `i|j`). `list` ports receive the whole list. A single `item` value is
+ *     broadcast.
+ *  4. Lane keys come from the driving entity's GlobalId when there is one,
+ *     else from the index — which is reported as a warning, because index
+ *     lanes shift when the driving list changes and tracking then updates
+ *     the wrong element.
+ *  5. A `null` arriving on a non-nullable `item` port short-circuits that
+ *     lane: `run` is not called and every output of the lane is `null`.
+ */
+import type { NodeOutputs, PortDef } from './registry.js';
+import type { FlowData, GroupKey, Lacing } from './values.js';
+export interface LiftInput {
+    readonly port: PortDef;
+    /** `undefined` when the port is unconnected. */
+    readonly data: FlowData | undefined;
+}
+export interface Lane {
+    readonly laneKey: GroupKey | null;
+    readonly branchKey: GroupKey | null;
+    readonly args: Readonly<Record<string, unknown>>;
+    /** True when a non-nullable item port received `null`: run is skipped. */
+    readonly nullLane: boolean;
+}
+export interface LiftPlan {
+    readonly lifted: boolean;
+    readonly overGroup: boolean;
+    readonly lanes: readonly Lane[];
+    /** Per port, the branch keys it lacked while other ports had them. */
+    readonly missing: Readonly<Record<string, readonly GroupKey[]>>;
+    readonly warnings: readonly string[];
+}
+export interface LiftOptions {
+    readonly lacing: Lacing;
+    readonly maxCross: number;
+    readonly laneKeyPort?: string;
+}
+export declare class CrossProductTooLarge extends Error {
+    readonly size: number;
+    readonly limit: number;
+    constructor(size: number, limit: number);
+}
+export declare function planLift(inputs: readonly LiftInput[], opts: LiftOptions): LiftPlan;
+/** Reassemble per-lane outputs into structured data, one entry per output port. */
+export declare function assemble(plan: LiftPlan, outputs: readonly PortDef[], results: readonly (NodeOutputs | null)[]): Map<string, FlowData>;
+//# sourceMappingURL=lift.d.ts.map

package/dist/lift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lift.d.ts","sourceRoot":"","sources":["../src/lift.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE1D,OAAO,KAAK,EAAqB,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEjF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAC,CAAC,CAAC;IAChE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAApC,IAAI,EAAE,MAAM,EAAW,KAAK,EAAE,MAAM;CAI1D;AA8ED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,IAAI,EAAE,WAAW,GAAG,QAAQ,CAyElF;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,OAAO,EAAE,EAAE,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAkCrI"}