@uipath/maestro-builder-sdk 6.18.10 → 6.19.0

package/dist/decompile.js

@@ -28,13 +28,11 @@
  * display labels on plain steps, and formatting are not preserved (layout is
  * re-attached by `flow-merge`; see `docs/FLOW_PARITY.md`).
  */
-import { readFileSync } from 'node:fs';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { preserveSchemaVersion } from './schema-version.js';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { inferScriptShape } from './core/script-return.js';
-import { DEFAULT_TRIGGER_ID } from './core/expr.js';
+import { BUNDLED_DEFINITIONS, bundledVersions, hasBundledDefinition } from './flow-definitions.js';
+import { DEFAULT_TRIGGER_ID, Expr } from './core/expr.js';
+import { FLOW_NODE_TYPES } from './flow-node-registry.js';
 import { commentText } from './core/comment-text.js';
 import { tsLiteral, tsNumber, tsText } from './core/ts-literal.js';
 import { parseIxpProjectType } from './core/actions.js';
@@ -89,16 +87,6 @@ function warnOnce(message) {
     runWarned.add(message);
     runWarn?.(message);
 }
-/**
- * The `<nodeType>@<version>` pairs this SDK bundles for core nodes — the same
- * file `serialize` resolves an explicit `{ version }` against (design §2.6:
- * exact, no floating). Decompile preserves the file's pair (design §5.3), so
- * when the file pins a version the bundle lacks, `compile` WILL refuse the
- * emitted source; saying so here is the difference between a loop that fails
- * at step 2 with a hint and one that fails at step 2 with a puzzle.
- */
-const CORE_DEFINITIONS = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'core-definitions.json'), 'utf8'));
-const CORE_DEFINITION_KEYS = new Set(Object.keys(CORE_DEFINITIONS));
 /**
  * The label the canvas gives a freshly dropped `node`: its definition's
  * `display.label`, from the file's own `definitions[]`, else the bundled core
@@ -106,7 +94,7 @@ const CORE_DEFINITION_KEYS = new Set(Object.keys(CORE_DEFINITIONS));
  */
 function definitionLabel(node) {
     const key = `${node.type}@${node.typeVersion}`;
-    const def = runDefs.get(key) ?? CORE_DEFINITIONS[key] ?? runDefs.get(node.type);
+    const def = runDefs.get(key) ?? BUNDLED_DEFINITIONS[key] ?? runDefs.get(node.type);
     const label = def?.display?.label;
     return typeof label === 'string' ? label : undefined;
 }
@@ -124,11 +112,17 @@ function verClause(node) {
                 + `the file's definitions[] disagrees with the instance.`);
         }
     }
-    if (node.type.startsWith('core.') && !CORE_DEFINITION_KEYS.has(`${node.type}@${tv}`)) {
-        const shipped = [...CORE_DEFINITION_KEYS]
-            .filter((k) => k.startsWith(`${node.type}@`))
-            .map((k) => k.slice(node.type.length + 1));
-        warnOnce(`node ${tsLiteral(node.id)} pins ${node.type}@${tv}, but this SDK bundles ${node.type}@${shipped.join(', ') || '<none>'} only; `
+    // Decompile preserves the file's pair (design §5.3), but `serialize` resolves an
+    // explicit { version } against the bundle exactly (design §2.6), so a pin the
+    // bundle lacks WILL fail `compile`; saying so here is the difference between a
+    // loop that fails at step 2 with a hint and one that fails with a puzzle.
+    // A registered type resolves against its registered versions, which the bundle
+    // may exceed; every other core type against the bundle.
+    const registered = FLOW_NODE_TYPES.byTypeName(node.type);
+    const shipped = registered ? Object.keys(registered.type.versions)
+        : node.type.startsWith('core.') && !hasBundledDefinition(node.type, tv) ? bundledVersions(node.type) : undefined;
+    if (shipped && !shipped.includes(tv)) {
+        warnOnce(`node ${tsLiteral(node.id)} pins ${node.type}@${tv}, but this SDK ${registered ? 'registers' : 'bundles'} ${node.type}@${shipped.join(', ') || '<none>'} only; `
             + `\`compile\` will refuse the emitted { version: ${tsLiteral(tv)} } (versions resolve exactly, flow-builder-sdk#71). `
             + `The source keeps the file's pair; to recompile, drop that { version } and the node takes the SDK's pinned version.`);
     }
@@ -210,21 +204,11 @@ const T = {
     endCall: 'uipath.conversational.voice.end-call',
     http: 'core.action.http',
     httpV2: 'core.action.http.v2',
-    script: 'core.action.script',
-    transform: 'core.action.transform',
-    delay: 'core.logic.delay',
-    mock: 'core.logic.mock',
     decision: 'core.logic.decision',
     switch: 'core.logic.switch',
     merge: 'core.logic.merge',
     loop: 'core.logic.loop',
     doWhile: 'core.logic.dowhile',
-    dataFabricRead: 'core.datafabric.read',
-    dataFabricCreate: 'core.datafabric.create',
-    dataFabricDelete: 'core.datafabric.delete',
-    documentClassify: 'uipath.document.classify',
-    dynamicExtract: 'uipath.ixp.extract-document-builder',
-    dataFabricUpdate: 'core.datafabric.update',
     subflow: 'core.subflow',
     terminate: 'core.logic.terminate',
     end: 'core.control.end',
@@ -503,147 +487,91 @@ class Graph {
     }
 }
 // ─── Node → step-spec source ──────────────────────────────────────────────────
+/**
+ * A serialized value back as a spec holds it: `=js:` text (bare, or in a
+ * `{ type: 'jsExpression', expression }` object) becomes an `Expr`; anything else
+ * is a literal and stays itself.
+ */
+function specValue(raw) {
+    if (typeof raw === 'string')
+        return raw.startsWith('=js:') ? new Expr(raw.slice(4)) : raw;
+    const o = raw;
+    if (o && typeof o === 'object' && o.type === 'jsExpression' && typeof o.expression === 'string')
+        return new Expr(o.expression);
+    return raw;
+}
+/**
+ * Print a node whose type is registered (flow-node-registry.ts): the node type
+ * deserializes it to its spec and prints the factory call. A node at a version
+ * the type does not register is lifted by its default version's implementation —
+ * as every built-in family lifts any version today — and keeps its own
+ * `{ version }` on the step, which compile then refuses; `verClause` warns at
+ * decompile time that it will. `undefined` when the type is not registered, or the node type declines
+ * the node; the caller's branches take it from there.
+ */
+function emitRegisteredSpec(node, imp, inputNames) {
+    const entry = typeof node.type === 'string' ? FLOW_NODE_TYPES.byTypeName(node.type) : undefined;
+    if (!entry)
+        return undefined;
+    const version = String(node.typeVersion ?? '');
+    const impl = (Object.hasOwn(entry.type.versions, version)
+        ? entry.type.versions[version]
+        : entry.type.versions[entry.type.defaultVersion]);
+    const ctx = {
+        nodeId: node.id,
+        expr: specValue,
+        sourceText: unwrapSource,
+        plainValue: unwrapPlain,
+        stepName: (nodeId) => nodeId,
+        definition: () => runDefs.get(`${node.type}@${version}`) ?? runDefs.get(node.type),
+        warn: warnOnce,
+    };
+    const spec = impl.deserialize(node, ctx);
+    if (spec === undefined)
+        return undefined;
+    // A spec value as source, recursing into arrays and plain objects so an Expr
+    // nested in one (a filter row's value) prints as the helper an author writes —
+    // in the `{ k: v }` / `[a, b]` spelling the hand-written printers use.
+    const printValue = (v) => {
+        if (v instanceof Expr)
+            return v.literal ? tsLiteral(v.value) : emitRef(v.js, imp, inputNames);
+        if (Array.isArray(v))
+            return `[${v.map(printValue).join(', ')}]`;
+        if (v && typeof v === 'object') {
+            const parts = Object.entries(v).filter(([, x]) => x !== undefined).map(([k, x]) => `${key(k)}: ${printValue(x)}`);
+            return parts.length ? `{ ${parts.join(', ')} }` : '{}';
+        }
+        return tsLiteral(v);
+    };
+    const print = {
+        value: printValue,
+        string: (t) => tsLiteral(t),
+        json: (v) => tsLiteral(v),
+        key: (k) => key(k),
+        helper: (name) => imp.use(name),
+    };
+    const call = impl.print?.(spec, print) ?? {
+        factory: impl.factory,
+        options: Object.entries(spec.inputs ?? {})
+            .map(([k, v]) => [k, v === undefined ? undefined : print.value(v)]),
+    };
+    const options = opts((call.options ?? []).map(([k, v]) => [k, v]));
+    const args = [...(call.positional ?? []), ...(options ? [options] : [])];
+    return `${imp.use(call.factory)}(${args.join(', ')})`;
+}
 /**
  * Emit the action-spec argument for a `.step(id, <spec>)` call — e.g.
  * `script({ code: "…" })`. Returns `undefined` for a node that is not a plain
  * action (control-flow / trigger / end), which the traversal handles specially.
  */
 function emitStepSpec(node, imp, inputNames, o, graph) {
+    // A registered node type lifts itself; every other type falls through to the
+    // branches below until its family is ported (FB014's pins are the list).
+    const lifted = emitRegisteredSpec(node, imp, inputNames);
+    if (lifted !== undefined)
+        return lifted;
     const inputs = node.inputs ?? {};
     switch (node.type) {
-        case T.mock:
-            return `${imp.use('mock')}()`;
-        case T.script: {
-            const code = typeof inputs.script === 'string' ? inputs.script : '';
-            // `returns` is emitted only when the node's declared output type is
-            // something re-compiling the body would NOT produce on its own. Serialize
-            // infers from the body first (see `scriptOutputs`), so a script whose type
-            // is already plain in its code round-trips without it — emitting one there
-            // would add an argument the author never wrote to every such step.
-            return `${imp.use('script')}(${opts([['code', tsLiteral(code)], ...scriptReturnsOpt(node, code)])})`;
-        }
-        case T.delay: {
-            // serialize's `delayInputs` writes `{timerType, timerPreset, timerValue?}`
-            // for a duration and `{timerType:'timeDate', timerDate}` for an absolute
-            // wait. Invert all three spellings.
-            if (inputs.timerType === 'timeDate') {
-                const until = typeof inputs.timerDate === 'string' ? inputs.timerDate : '';
-                return `${imp.use('delay')}(${opts([['until', tsLiteral(until)]])})`;
-            }
-            const duration = inputs.timerPreset === 'custom'
-                ? (typeof inputs.timerValue === 'string' ? inputs.timerValue : '')
-                : (typeof inputs.timerPreset === 'string' ? inputs.timerPreset : '');
-            return `${imp.use('delay')}(${opts([['duration', tsLiteral(duration)]])})`;
-        }
-        case T.documentClassify:
-        case T.dynamicExtract: {
-            const fr = unwrapSource(inputs.fileRef) ?? '';
-            const fileSrc = fr.startsWith('=js:') ? emitBareExpr(fr.slice(4), imp, inputNames) : tsLiteral(fr);
-            const pageRange = typeof inputs.pageRange === 'string' && inputs.pageRange !== '' ? tsLiteral(inputs.pageRange) : undefined;
-            if (node.type === T.documentClassify) {
-                const split = unwrapPlain(inputs.splitPages);
-                return `${imp.use('documentClassify')}(${opts([
-                    ['fileRef', fileSrc],
-                    ['pageRange', pageRange],
-                    ['splitPages', split === true ? 'true' : undefined],
-                ])})`;
-            }
-            const schema = inputs.schemaDocument !== undefined ? tsLiteral(inputs.schemaDocument) : undefined;
-            return `${imp.use('dynamicExtract')}(${opts([
-                ['fileRef', fileSrc],
-                ['schema', schema],
-                ['pageRange', pageRange],
-            ])})`;
-        }
-        case T.dataFabricRead:
-        case T.dataFabricCreate:
-        case T.dataFabricUpdate:
-        case T.dataFabricDelete: {
-            const cfg = (inputs.entityConfig ?? {});
-            const entity = tsText(cfg.entityName);
-            const folder = typeof cfg._folderKey === 'string' ? tsLiteral(cfg._folderKey) : undefined;
-            const resourceKey = typeof cfg._resourceKey === 'string' ? tsLiteral(cfg._resourceKey) : undefined;
-            const val = (v) => {
-                // 1.3 let `recordId` and a create's field value be a `{ type:
-                // 'jsExpression', expression }` object as well as a `=js:` string. A
-                // product-authored node can carry either; both recover as an expression.
-                const obj = v;
-                if (obj && typeof obj === 'object' && obj.type === 'jsExpression') {
-                    return emitBareExpr(String(obj.expression ?? ''), imp, inputNames);
-                }
-                const raw = typeof v === 'string' ? v : String(v ?? '');
-                return raw.startsWith('=js:') ? emitBareExpr(raw.slice(4), imp, inputNames) : tsLiteral(raw);
-            };
-            const fieldObject = (rows) => {
-                const list = Array.isArray(rows) ? rows : [];
-                return `{ ${list.map((r) => `${key(String(r.field ?? ''))}: ${val(r.value)}`).join(', ')} }`;
-            };
-            const record = cfg.recordSource === 'fromRead'
-                ? `{ fromRead: ${tsText(cfg.readEntityNodeId)} }`
-                : `{ byId: ${val(cfg.recordId)} }`;
-            if (node.type === T.dataFabricRead) {
-                // The array is what the platform serializer reads and what compile
-                // writes; the grouped object is the newer authoring shape, tolerated
-                // here so a canvas-authored file still decompiles. Both flatten to the
-                // builder's row list, where `or: true` marks each new OR alternative.
-                const filterRow = (r, or = false) => opts([
-                    ['field', tsText(r.field)],
-                    ['operator', r.operator !== undefined && r.operator !== '=' ? tsLiteral(String(r.operator)) : undefined],
-                    ['value', val(r.value)],
-                    ['or', or ? 'true' : undefined],
-                ]);
-                const q = cfg._filters;
-                let rows = [];
-                if (Array.isArray(q)) {
-                    rows = q.map((r, i) => filterRow(r, i > 0 && r['join'] === 'OR'));
-                }
-                else if (q && typeof q === 'object') {
-                    // Grouped: each root row and each group is one alternative, so every
-                    // one but the first opens with `or: true`.
-                    const alts = [
-                        ...(Array.isArray(q.rows) ? q.rows.map((r) => [r]) : []),
-                        ...(Array.isArray(q.groups) ? q.groups : [])
-                            .map((g) => (Array.isArray(g.rows) ? g.rows : [])),
-                    ].filter((a) => a.length);
-                    rows = alts.flatMap((alt, ai) => alt.map((r, ri) => filterRow(r, ai > 0 && ri === 0)));
-                }
-                const filters = rows.length ? `[${rows.join(', ')}]` : undefined;
-                // `resultMode` only exists from 1.4, and recovering it re-selects 1.4 on
-                // the way back out — so a 1.0 node stays a 1.0 node through the round trip.
-                const mode = cfg.resultMode === 'single' || cfg.resultMode === 'multiple'
-                    ? tsLiteral(cfg.resultMode) : undefined;
-                const sort = cfg._sort && typeof cfg._sort === 'object'
-                    ? opts([
-                        ['field', tsText(cfg._sort.field)],
-                        ['direction', cfg._sort.direction === 'desc' ? tsLiteral('desc') : undefined],
-                    ])
-                    : undefined;
-                const fields = Array.isArray(cfg._selectedFieldNames) && cfg._selectedFieldNames.length
-                    ? `[${cfg._selectedFieldNames.map((f) => tsLiteral(String(f))).join(', ')}]`
-                    : undefined;
-                return `${imp.use('dataFabricRead')}(${opts([
-                    ['entity', entity], ['filters', filters], ['resultMode', mode],
-                    ['limit', typeof cfg._recordLimit === 'number' ? String(cfg._recordLimit) : undefined],
-                    ['skip', typeof cfg._skip === 'number' ? String(cfg._skip) : undefined],
-                    ['sort', sort], ['fields', fields],
-                    ['folderKey', folder], ['resourceKey', resourceKey],
-                ])})`;
-            }
-            if (node.type === T.dataFabricCreate) {
-                return `${imp.use('dataFabricCreate')}(${opts([
-                    ['entity', entity], ['values', fieldObject(cfg.fieldValues)], ['folderKey', folder], ['resourceKey', resourceKey],
-                ])})`;
-            }
-            if (node.type === T.dataFabricDelete) {
-                return `${imp.use('dataFabricDelete')}(${opts([
-                    ['entity', entity], ['record', record], ['folderKey', folder], ['resourceKey', resourceKey],
-                ])})`;
-            }
-            return `${imp.use('dataFabricUpdate')}(${opts([
-                ['entity', entity], ['record', record], ['set', fieldObject(cfg.fieldUpdates)],
-                ['folderKey', folder], ['resourceKey', resourceKey],
-            ])})`;
-        }
         case T.createOutgoingCall:
         case T.endCall: {
             const i = (node.inputs ?? {});
@@ -766,8 +694,6 @@ function emitStepSpec(node, imp, inputNames, o, graph) {
         case T.httpV2:
             return emitHttp(node, true, imp, inputNames);
         default:
-            if (node.type.startsWith('core.action.transform'))
-                return emitTransform(node, imp, inputNames);
             // A connector action node: `uipath.connector.<key>.<action>` (but NOT the
             // event nodes `uipath.connector.event.*` / `.trigger.*`, which are triggers).
             if (node.type.startsWith('uipath.connector.') && !node.type.startsWith('uipath.connector.event.') && !node.type.startsWith('uipath.connector.trigger.')) {
@@ -823,49 +749,6 @@ function emitStepSpec(node, imp, inputNames, o, graph) {
             return unsupportedSpec(node, imp, o);
     }
 }
-/**
- * The `returns` argument for a script step, or nothing.
- *
- * Recovers what the author declared by DIFFERENCE: the node says what its output
- * is, `inferScriptShape` says what re-compiling the body would declare on its
- * own, and only a gap between the two needs writing down. Fields are recovered
- * the same way — a property map the body does not produce is one the author gave
- * as `returns: {…}`.
- */
-function scriptReturnsOpt(node, code) {
-    const out = node.outputs?.output;
-    const declared = typeof out?.type === 'string' ? out.type : undefined;
-    if (!declared)
-        return [];
-    const props = out?.properties;
-    // What re-compiling this body with NO `returns` would declare. Mirror
-    // `scriptOutputs` exactly: an inference of a bare `object` (or none at all)
-    // leaves the definition's own `{type:'object'}` standing, untouched.
-    const inferred = inferScriptShape(code);
-    const effective = inferred && !(inferred.type === 'object' && !inferred.properties)
-        ? inferred
-        : { type: 'object', properties: undefined };
-    const same = effective.type === declared
-        && JSON.stringify(sortKeys(effective.properties ?? {})) === JSON.stringify(sortKeys(props ?? {}));
-    if (same)
-        return [];
-    // Not what the body alone would say — so the author declared it, and it has to
-    // be written back or the round-trip loses it. That includes declaring the OPEN
-    // object over a body that looks typed, which is a real thing to want.
-    if (props && Object.keys(props).length > 0) {
-        // A field map is the richer statement, so it wins when there is one.
-        const entries = Object.entries(props)
-            .filter(([, v]) => typeof v?.type === 'string')
-            .map(([k, v]) => [k, tsLiteral(v.type)]);
-        if (entries.length > 0)
-            return [['returns', opts(entries)]];
-    }
-    return [['returns', tsLiteral(declared)]];
-}
-/** Key-sorted copy, so a property map compares by content and not by order. */
-function sortKeys(o) {
-    return Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b)));
-}
 /**
  * Invert an HTTP node. The plain node (`core.action.http`) keeps its request at
  * the top level (`url` / `method` / `headers` / `queryParams` / `body` /
@@ -926,68 +809,6 @@ function emitHttp(node, managed, imp, inputNames) {
     ]);
     return `${imp.use('http')}(${spec})`;
 }
-/**
- * Invert a Transform node (generic `core.action.transform` or a `.map` / `.filter`
- * / `.group-by` variant). The `collection` is a bare `$vars.…` path; each
- * operation's serialized `{id,type,config}` becomes a builder operation object.
- * (The variant node types carry a `groupBy` operation spelled with a hyphen in
- * the type — `group-by` — but `groupBy` in the operation, the platform's own
- * mismatch, mirrored here.)
- */
-function emitTransform(node, imp, inputNames) {
-    const inputs = node.inputs ?? {};
-    const suffix = node.type.slice('core.action.transform'.length).replace(/^\./, '');
-    const variant = suffix || undefined; // 'map' | 'filter' | 'group-by' | undefined
-    const collRaw = unwrapSource(inputs.collection);
-    const collection = collRaw !== undefined
-        ? emitBareExpr(collRaw.startsWith('=js:') ? collRaw.slice(4) : collRaw, imp, inputNames)
-        : `${imp.use('lit')}([])`;
-    const ops = Array.isArray(inputs.operations) ? inputs.operations : [];
-    const opSrcs = ops.map((op) => {
-        const cfg = op?.config ?? {};
-        if (op?.type === 'filter') {
-            const filters = (cfg.filters ?? []).map((f) => objLit([
-                ['field', tsLiteral(f.field)],
-                ['condition', tsLiteral(f.condition)],
-                ...(f.value !== undefined ? [['value', tsLiteral(f.value)]] : []),
-            ]));
-            return objLit([
-                ['type', tsLiteral('filter')],
-                ...(cfg.operation !== undefined ? [['operation', tsLiteral(cfg.operation)]] : []),
-                ['filters', `[${filters.join(', ')}]`],
-            ]);
-        }
-        if (op?.type === 'map') {
-            const mappings = (cfg.mappings ?? []).map((m) => objLit([
-                ['field', tsLiteral(m.field)],
-                ...(m.transformation && m.transformation !== 'copy' ? [['transformation', tsLiteral(m.transformation)]] : []),
-                ...(m.renameTo ? [['renameTo', tsLiteral(m.renameTo)]] : []),
-            ]));
-            return objLit([
-                ['type', tsLiteral('map')],
-                ...(cfg.keepOriginalFields ? [['keepOriginalFields', boolLit(cfg.keepOriginalFields)]] : []),
-                ['mappings', `[${mappings.join(', ')}]`],
-            ]);
-        }
-        // groupBy
-        const aggs = (cfg.aggregations ?? []).map((a) => objLit([
-            ['operation', tsLiteral(a.operation)],
-            ['alias', tsLiteral(a.alias)],
-            ...(a.field ? [['field', tsLiteral(a.field)]] : []),
-        ]));
-        return objLit([
-            ['type', tsLiteral('groupBy')],
-            ['groupByField', tsLiteral(cfg.groupByField)],
-            ['aggregations', `[${aggs.join(', ')}]`],
-        ]);
-    });
-    const spec = opts([
-        ['collection', collection],
-        ['variant', variant ? tsLiteral(variant) : undefined],
-        ['operations', `[${opSrcs.join(', ')}]`],
-    ]);
-    return `${imp.use('transform')}(${spec})`;
-}
 /**
  * Split a connector `nodeType` (`uipath.connector.<key>.<action>`) into key +
  * action. Mirrors `core/connectors.ts`'s `splitConnectorNodeType`.

package/dist/flow-definitions.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The bundled definitions, keyed `<nodeType>@<version>`. Deep-frozen: every reader
+ * shares this one copy, so a write meant for one node must clone first, and one
+ * that does not throws at its own site instead of leaking into another reader.
+ */
+export declare const BUNDLED_DEFINITIONS: Readonly<Record<string, any>>;
+/** Whether the SDK bundles `<typeName>@<version>`. */
+export declare function hasBundledDefinition(typeName: string, version: string): boolean;
+/** The versions of `typeName` the SDK bundles, in bundle order. */
+export declare function bundledVersions(typeName: string): string[];

package/dist/flow-definitions.js

@@ -0,0 +1,35 @@
+/**
+ * The node definitions this SDK bundles for Flow (`core-definitions.json`, keyed
+ * `<nodeType>@<version>`): the one parse of the bundle, shared by `serialize`,
+ * `decompile` and the node-type registry's validation.
+ *
+ * Kept apart from `serialize.ts` so the registry can depend on the bundle without
+ * importing the serializer that depends on the registry.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The bundled definitions, keyed `<nodeType>@<version>`. Deep-frozen: every reader
+ * shares this one copy, so a write meant for one node must clone first, and one
+ * that does not throws at its own site instead of leaking into another reader.
+ */
+export const BUNDLED_DEFINITIONS = deepFreeze(JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'core-definitions.json'), 'utf8')));
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+const BUNDLED_KEYS = new Set(Object.keys(BUNDLED_DEFINITIONS));
+/** Whether the SDK bundles `<typeName>@<version>`. */
+export function hasBundledDefinition(typeName, version) {
+    return BUNDLED_KEYS.has(`${typeName}@${version}`);
+}
+/** The versions of `typeName` the SDK bundles, in bundle order. */
+export function bundledVersions(typeName) {
+    const prefix = `${typeName}@`;
+    return [...BUNDLED_KEYS].filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+}

package/dist/flow-node-registry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Flow's node-type registry: every Flow node family, listed explicitly
+ * (docs/NODE_TYPE_ARCHITECTURE_DESIGN.md §4.5).
+ *
+ * While a kind is not listed here, `serialize`, `check` and `decompile` handle it
+ * with their existing branches — the FB014 pins in `tests/lint/pins.txt` are what
+ * is left to port.
+ */
+import { NodeTypeRegistry } from './core/nodes/registry.js';
+import type { FlowContexts, FlowNodeFamily } from './flow-node-type.js';
+/** The families, in no significant order. Adding one is the whole of registering it. */
+export declare const FLOW_NODE_FAMILIES: readonly FlowNodeFamily[];
+export declare const FLOW_NODE_TYPES: NodeTypeRegistry<FlowContexts>;

package/dist/flow-node-registry.js

@@ -0,0 +1,19 @@
+/**
+ * Flow's node-type registry: every Flow node family, listed explicitly
+ * (docs/NODE_TYPE_ARCHITECTURE_DESIGN.md §4.5).
+ *
+ * While a kind is not listed here, `serialize`, `check` and `decompile` handle it
+ * with their existing branches — the FB014 pins in `tests/lint/pins.txt` are what
+ * is left to port.
+ */
+import { NodeTypeRegistry } from './core/nodes/registry.js';
+import { hasBundledDefinition } from './flow-definitions.js';
+import { dataFabricFlowFamily } from './nodes/data-fabric/flow/family.js';
+import { delayFlowFamily } from './nodes/delay/flow/family.js';
+import { documentFlowFamily } from './nodes/document/flow/family.js';
+import { mockFlowFamily } from './nodes/mock/flow/family.js';
+import { scriptFlowFamily } from './nodes/script/flow/family.js';
+import { transformFlowFamily } from './nodes/transform/flow/family.js';
+/** The families, in no significant order. Adding one is the whole of registering it. */
+export const FLOW_NODE_FAMILIES = [dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, mockFlowFamily, scriptFlowFamily, transformFlowFamily];
+export const FLOW_NODE_TYPES = new NodeTypeRegistry('flow', FLOW_NODE_FAMILIES, { hasBundledDefinition });