@uipath/maestro-builder-sdk 6.41.2 → 6.43.0

package/dist/core/library.d.ts

@@ -1,3 +1,12 @@
+/**
+ * library — resolve Integration Service connector definitions from the on-disk
+ * connector library cache (the same `library-json` the Flow Code arm uses).
+ *
+ * For a connector action we need two files per action:
+ *   <key>/<action>@<ver>.json        the entry (connector key, HTTP method, endpoint)
+ *   <key>/<action>@<ver>.v1def.json  the Flow `definitions[]` shape (model, ports, …)
+ */
+import { type ReadText } from './read-text.js';
 import { type LookupResolutions, type LookupSpec } from './lookups.js';
 import type { ByoaEventFacts, ByoaLedger } from './byoa.js';
 export interface ResolvedConnector {
@@ -217,8 +226,27 @@ export interface LibraryOpts {
      * library exposed (a thin `describe` response must not shrink what compiles).
      */
     overlayDir?: string;
+    /** Reads each library and overlay file. Defaults to the disk; a host without one passes its own. */
+    readText?: ReadText;
+    /** Receives the library's warnings. Defaults to stderr; a host without `process` passes its own. */
+    warn?: (message: string) => void;
 }
 export { ConnectorResolveError, type ConnectorResolveCode } from './connector-resolve-error.js';
+/** What `registry describe` renders one operation's page from. */
+export interface PageSource {
+    entry: any;
+    /** The Flow definition beside the entry, or `undefined` when there is none. */
+    v1def: any;
+    version: string;
+    /** True when the operation came from the prepared `connectors-local` overlay. */
+    prepared: boolean;
+    /** The folder the operation came from. */
+    dir: string;
+    /** That layer's index rows. The page names the operation's symbol from them. */
+    rows: readonly any[];
+    /** `objectName`s the ledgers declare connector-invariant. */
+    invariant: ReadonlySet<string>;
+}
 export declare class Library {
     private layers;
     /** The LIST-ENVELOPE LEDGER, overlay first so a prepared entry can add a row. */
@@ -239,6 +267,8 @@ export declare class Library {
     readonly byoaVerifications: ByoaLedger;
     /** Collections the ledger declares connector-invariant; overlay unions over baked. */
     private readonly invariantCollections;
+    private readonly read;
+    private readonly warn;
     constructor(dir: string, opts?: LibraryOpts);
     /**
      * Resolve a connector ACTION (`uipath.connector.<key>.<action>`).
@@ -267,6 +297,23 @@ export declare class Library {
      */
     lookupSpecs(key: string, action: string, version?: string, objectName?: string): Record<string, LookupSpec>;
     resolve(key: string, action: string, version?: string, objectName?: string): ResolvedConnector;
+    /**
+     * One operation's page source, for `registry describe`: the entry and definition
+     * of one index row, from the first layer that carries it. That is the prepared
+     * overlay before the library, the order `resolve` reads in. Without a version, the
+     * newest. A generic operation has a row per object, as `registry pull` writes a
+     * page per object: `objectName` picks the row; without it, the object-less row is
+     * used when there is one, else CONNECTOR_OBJECT_REQUIRED lists the objects. Rows are
+     * chosen as `resolveInLayer` chooses them, so a page shows only what `compile` accepts.
+     */
+    pageSource(nodeType: string, version?: string, objectName?: string): PageSource;
+    /**
+     * The row an object the layer does not list reads its page from, as `resolveInLayer`
+     * case 1 accepts it: the one object-less row of an un-expanded generic operation.
+     * A single non-generic operation takes no object at all.
+     */
+    private connectionScopedRow;
+    private pageOf;
     /**
      * Whether a connector step's schema is materialized locally — see
      * {@link SchemaReadiness}. Index rows are enough for the `object` question

package/dist/core/library.js

@@ -6,10 +6,8 @@
  *   <key>/<action>@<ver>.json        the entry (connector key, HTTP method, endpoint)
  *   <key>/<action>@<ver>.v1def.json  the Flow `definitions[]` shape (model, ports, …)
  */
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { prepareCommand } from './cli-spelling.js';
-import { PULL_COMMAND } from './library-cache.js';
+import { cacheFor, libraryPath, readJson, readTextFromDisk } from './read-text.js';
+import { PULL_COMMAND, prepareCommand } from './cli-spelling.js';
 import { editDistance } from './edit-distance.js';
 import { loadListEnvelopes, lookupListEnvelope } from './list-envelope.js';
 import { lookupSpecOf } from './lookups.js';
@@ -37,26 +35,35 @@ export class Library {
     byoaVerifications;
     /** Collections the ledger declares connector-invariant; overlay unions over baked. */
     invariantCollections;
+    read;
+    warn;
     constructor(dir, opts = {}) {
-        this.lookupResolutions = loadLookupResolutions(opts.overlayDir);
-        this.byoaVerifications = loadByoaLedger(opts.overlayDir);
+        const read = (this.read = opts.readText ?? readTextFromDisk);
+        this.warn = opts.warn ?? ((message) => { globalThis.process?.stderr?.write(message); });
+        // A new identity per Library, so the per-reader caches never keep an overlay file: `prepare` rewrites them.
+        const readOverlay = (path) => read(path);
+        this.lookupResolutions = loadLookupResolutions(opts.overlayDir, readOverlay);
+        this.byoaVerifications = loadByoaLedger(opts.overlayDir, readOverlay);
         this.invariantCollections = new Set([
-            ...loadInvariantCollections(dir),
-            ...loadInvariantCollections(opts.overlayDir),
+            ...loadInvariantCollections(dir, read),
+            ...loadInvariantCollections(opts.overlayDir, readOverlay),
         ]);
         // Overlay first (local wins), then the baked library.
         if (opts.overlayDir) {
-            const oidx = join(opts.overlayDir, 'index.json');
-            if (existsSync(oidx))
-                this.layers.push({ dir: opts.overlayDir, entries: JSON.parse(readFileSync(oidx, 'utf8')).entries ?? [], overlay: true });
-            this.envelopeRows.push(...loadListEnvelopes(opts.overlayDir));
+            const overlayIndex = readOverlay(libraryPath(opts.overlayDir, 'index.json'));
+            if (overlayIndex !== undefined)
+                this.layers.push({ dir: opts.overlayDir, entries: JSON.parse(overlayIndex).entries ?? [], overlay: true });
+            this.envelopeRows.push(...loadListEnvelopes(opts.overlayDir, readOverlay));
         }
-        this.envelopeRows.push(...loadListEnvelopes(dir));
-        const idx = join(dir, 'index.json');
-        if (!existsSync(idx))
-            throw new Error(`connector library not found at ${idx}. Build it first (uipath-flow-v2-setup-library) ` +
-                `or point --library / $FLOW_SDK_LIBRARY_JSON at a library-json dir.`);
-        this.layers.push({ dir, entries: JSON.parse(readFileSync(idx, 'utf8')).entries ?? [] });
+        this.envelopeRows.push(...loadListEnvelopes(dir, read));
+        const idx = libraryPath(dir, 'index.json');
+        const entries = libraryEntries(read, idx);
+        if (entries === undefined)
+            throw new Error(`connector library not found at ${idx}. `
+                + (read === readTextFromDisk
+                    ? `Run \`${PULL_COMMAND}\`, or point --library / $FLOW_SDK_LIBRARY_JSON at a library-json dir.`
+                    : 'The reader passed to Library has no such file.'));
+        this.layers.push({ dir, entries });
     }
     /**
      * Resolve a connector ACTION (`uipath.connector.<key>.<action>`).
@@ -102,6 +109,83 @@ export class Library {
     resolve(key, action, version, objectName) {
         return this.resolveType(`uipath.connector.${key}.${action}`, version, objectName);
     }
+    /**
+     * One operation's page source, for `registry describe`: the entry and definition
+     * of one index row, from the first layer that carries it. That is the prepared
+     * overlay before the library, the order `resolve` reads in. Without a version, the
+     * newest. A generic operation has a row per object, as `registry pull` writes a
+     * page per object: `objectName` picks the row; without it, the object-less row is
+     * used when there is one, else CONNECTOR_OBJECT_REQUIRED lists the objects. Rows are
+     * chosen as `resolveInLayer` chooses them, so a page shows only what `compile` accepts.
+     */
+    pageSource(nodeType, version, objectName) {
+        const layers = this.layers.flatMap((layer) => {
+            const matches = layer.entries.filter((e) => e?.nodeType === nodeType && (!version || String(e.version) === version)
+                && typeof e.path === 'string' && e.path.endsWith('.json'));
+            if (!matches.length)
+                return [];
+            const newest = matches.map((e) => String(e.version))
+                .reduce((a, b) => (b.localeCompare(a, undefined, { numeric: true }) > 0 ? b : a));
+            return [{ layer, rows: matches.filter((e) => String(e.version) === newest) }];
+        });
+        if (!layers.length) {
+            throw new ConnectorResolveError('CONNECTOR_NOT_IN_LIBRARY', `connector not in library: ${nodeType}${version ? '@' + version : ''}.`
+                + this.describeMiss(nodeType, version, undefined, false));
+        }
+        const objects = [...new Set(layers.flatMap(({ rows }) => rows.map((e) => e.objectName)
+                .filter((o) => typeof o === 'string' && o !== '')))].sort();
+        // `compile` refuses a missing object when any layer holds several rows with no one template row.
+        if (objectName === undefined && layers.some(({ rows }) => rows.length > 1 && rows.filter((e) => !e.objectName).length !== 1)) {
+            throw new ConnectorResolveError('CONNECTOR_OBJECT_REQUIRED', `connector ${nodeType} is a GENERIC operation covering ${objects.length} objects — `
+                + `say which one with --object, e.g. --object ${objects[0] ?? '<object>'}. ${describeObjects(objects)}`);
+        }
+        for (const { layer, rows } of layers) {
+            const row = objectName === undefined
+                ? (rows.length === 1 ? rows[0] : rows.find((e) => !e.objectName))
+                : rows.find((e) => e.objectName === objectName) ?? this.connectionScopedRow(nodeType, rows, objectName);
+            if (row)
+                return this.pageOf(nodeType, layer, row);
+        }
+        const parts = nodeType.split('.');
+        const eventNs = parts[2] === 'trigger' || parts[2] === 'event';
+        const near = nearest(objectName ?? '', objects);
+        throw new ConnectorResolveError('CONNECTOR_NOT_IN_LIBRARY', `connector ${nodeType} has no page for object "${objectName}"`
+            + `${near ? ` (nearest: "${near}")` : ''}. ${describeObjects(objects)} If it is a connection-scoped object, run `
+            + `\`${prepareCommand(eventNs ? parts[3] : parts[2], (eventNs ? parts.slice(4) : parts.slice(3)).join('.'), '--object', String(objectName))}\` `
+            + 'to prepare it, then describe again.');
+    }
+    /**
+     * The row an object the layer does not list reads its page from, as `resolveInLayer`
+     * case 1 accepts it: the one object-less row of an un-expanded generic operation.
+     * A single non-generic operation takes no object at all.
+     */
+    connectionScopedRow(nodeType, rows, objectName) {
+        if (rows.length !== 1)
+            return undefined;
+        const only = rows[0];
+        if (only.activityType === 'Generic' || only.activityType === 'GenericTrigger' || only.objectFromDiscovery === true) {
+            return only.objectName ? undefined : only;
+        }
+        throw new ConnectorResolveError('CONNECTOR_OBJECT_NOT_GENERIC', `connector ${nodeType} does not have an object "${objectName}": it is a single, `
+            + `non-generic operation addressing ${only.objectName ? `"${only.objectName}"` : 'no object'}. `
+            + 'Drop --object (it is only for generic operations, whose node type covers many objects).');
+    }
+    pageOf(nodeType, layer, row) {
+        const entryPath = libraryPath(layer.dir, row.path);
+        const entry = readLibraryFile(nodeType, entryPath, () => readJson(this.read, entryPath));
+        const sidecarPath = v1defPathOf(entryPath);
+        const sidecar = this.read(sidecarPath);
+        const raw = sidecar === undefined ? undefined : readLibraryFile(nodeType, sidecarPath, () => JSON.parse(sidecar));
+        return {
+            entry,
+            v1def: Array.isArray(raw) ? raw[0] : raw,
+            version: String(row.version),
+            prepared: layer.overlay === true,
+            dir: layer.dir,
+            rows: layer.entries,
+            invariant: this.invariantCollections,
+        };
+    }
     /**
      * Whether a connector step's schema is materialized locally — see
      * {@link SchemaReadiness}. Index rows are enough for the `object` question
@@ -158,7 +242,7 @@ export class Library {
         let entry;
         try {
             const source = rows.find(({ overlay }) => !overlay) ?? rows[0];
-            entry = JSON.parse(readFileSync(join(source.dir, source.row.path), 'utf8'));
+            entry = readJson(this.read, libraryPath(source.dir, source.row.path));
         }
         catch {
             return undefined;
@@ -191,7 +275,7 @@ export class Library {
                     continue;
                 if (wire.version && indexed.version !== wire.version)
                     continue;
-                const entry = JSON.parse(readFileSync(join(layer.dir, indexed.path), 'utf8'));
+                const entry = readJson(this.read, libraryPath(layer.dir, indexed.path));
                 const operation = entry.operation ?? {};
                 if (wire.httpMethod && String(operation.httpMethod ?? '').toUpperCase() !== wire.httpMethod.toUpperCase())
                     continue;
@@ -289,8 +373,9 @@ export class Library {
                     continue;
                 if (wire.version && indexed.version !== wire.version)
                     continue;
-                const entry = JSON.parse(readFileSync(join(layer.dir, indexed.path), 'utf8'));
-                const operation = normalizeEventOperation({ entry, v1def: readV1def(join(layer.dir, indexed.path)) }).entry.operation ?? {};
+                const entryPath = libraryPath(layer.dir, indexed.path);
+                const entry = readJson(this.read, entryPath);
+                const operation = normalizeEventOperation({ entry, v1def: readV1def(this.read, entryPath) }).entry.operation ?? {};
                 // A GENERIC event's entry names no object — the wire's object is the
                 // author's choice, so it identifies nothing here and comes back as `object`.
                 const generic = operation.activityType === 'GenericTrigger';
@@ -600,7 +685,7 @@ export class Library {
      * `connector not in library: …send-mail-v2.` said nothing that would reveal
      * that. It resorted to grepping the library's JSON out of `node_modules`.
      */
-    describeMiss(nodeType, version, objectName) {
+    describeMiss(nodeType, version, objectName, searched = true) {
         // `uipath.connector.<key>.<op>`, or `uipath.connector.(trigger|event).<key>.<ev>`
         // for the two event namespaces. No connector key contains a dot.
         const parts = nodeType.split('.');
@@ -609,7 +694,8 @@ export class Library {
         const asked = (eventNs ? parts.slice(4) : parts.slice(3)).join('.');
         if (!key)
             return '';
-        const where = ` Searched: ${this.layers.map((l) => l.dir).join(', ')}.`;
+        // `describe` names no folder: on a browser host it is a store the agent cannot open.
+        const where = searched ? ` Searched: ${this.layers.map((l) => l.dir).join(', ')}.` : '';
         if (eventNs)
             return this.describeEventMiss(parts[2], key, asked, where, version, objectName);
         const ops = this.opsUnder(`uipath.connector.${key}.`);
@@ -753,7 +839,7 @@ export class Library {
                     return this.build(layer.dir, { ...only, objectName }, nodeType, { objectNameUnverified: true });
                 }
                 if (only.activityType === 'Generic' || only.objectFromDiscovery === true) {
-                    process.stderr.write(`  warn:  connector ${nodeType}: the library carries this operation un-expanded `
+                    this.warn(`  warn:  connector ${nodeType}: the library carries this operation un-expanded `
                         + `(one object-less entry). Object "${objectName}" is accepted as a connection-scoped `
                         + `object — the schema comes from the generic entry and the tenant resolves the name at `
                         + `dispatch. If it is a typo, compile will not catch it.\n`);
@@ -784,7 +870,7 @@ export class Library {
         // sibling whose path template is exactly `/<its object>` — the only shape a
         // substitution can re-point cleanly.
         const near = nearest(objectName, objects);
-        process.stderr.write(`  warn:  connector ${nodeType}: object "${objectName}" is not one of the `
+        this.warn(`  warn:  connector ${nodeType}: object "${objectName}" is not one of the `
             + `${objects.length} the library lists for it${near ? ` (nearest: "${near}")` : ''}. `
             + `Accepted as a connection-scoped object — the schema comes from a sibling entry and the `
             + `tenant resolves the name at dispatch. If it is a typo, compile will not catch it.\n`);
@@ -800,7 +886,7 @@ export class Library {
     pickDerivationSibling(dir, matches) {
         const templateOf = (e) => {
             try {
-                const entry = JSON.parse(readFileSync(join(dir, e.path), 'utf8'));
+                const entry = readJson(this.read, libraryPath(dir, e.path));
                 return entry.operation?.pathTemplate ?? entry.operation?.path ?? '';
             }
             catch {
@@ -814,14 +900,14 @@ export class Library {
         return substitutable ?? matches[0];
     }
     build(dir, e, nodeType, opts = {}) {
-        const entryPath = join(dir, e.path);
+        const entryPath = libraryPath(dir, e.path);
         // The two files the index row promises. A missing or corrupt one is a fault in
         // the library on disk, not in the author's source, but compile cannot go on
         // without it, so it is a typed refusal like the others: `check` reports it with
         // the same code and text instead of passing a step compile then dies on with a
         // bare ENOENT (#1015).
-        const entry = readLibraryFile(nodeType, entryPath, () => JSON.parse(readFileSync(entryPath, 'utf8')));
-        const v1def = readLibraryFile(nodeType, v1defPathOf(entryPath), () => readV1def(entryPath));
+        const entry = readLibraryFile(nodeType, entryPath, () => readJson(this.read, entryPath));
+        const v1def = readLibraryFile(nodeType, v1defPathOf(entryPath), () => readV1def(this.read, entryPath));
         // A stamped object (case 4) reaches here with the index entry's `objectName`
         // replaced but the sibling's FILE on disk — so restate the object and derive
         // the endpoint from the sibling's own template, rather than shipping a node
@@ -846,7 +932,7 @@ export class Library {
             && entry.operation.objectName !== e.objectName) {
             const stale = entry.operation.objectName;
             const derived = deriveObjectPath(entry.operation, e.objectName);
-            process.stderr.write(`  warn:  connector ${nodeType}: the library index says objectName "${e.objectName}" but its `
+            this.warn(`  warn:  connector ${nodeType}: the library index says objectName "${e.objectName}" but its `
                 + `definition file says "${stale}". Using the index and deriving the endpoint`
                 + (derived.path ? ` (${entry.operation.path} -> ${derived.path})` : '')
                 + `; the definition is the stale side when these disagree.\n`);
@@ -950,13 +1036,28 @@ function v1defPathOf(entryPath) {
  * damaged after it was built: an interrupted pull, a hand-edited overlay. The
  * remedy is the same either way: rebuild the layer the file belongs to.
  */
+/** Each host reader's parsed library index. A library build does not change; the disk default still reads afresh. */
+const INDEX_CACHE = new WeakMap();
+/** The `entries` of the index at `path`, or `undefined` when there is none. */
+function libraryEntries(read, path) {
+    const cache = read === readTextFromDisk ? undefined : cacheFor(INDEX_CACHE, read);
+    const cached = cache?.get(path);
+    if (cached)
+        return cached;
+    const text = read(path);
+    if (text === undefined)
+        return undefined;
+    const entries = JSON.parse(text).entries ?? [];
+    cache?.set(path, entries);
+    return entries;
+}
 function readLibraryFile(nodeType, path, read) {
     try {
         return read();
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        // ENOENT already names the path; a JSON SyntaxError does not.
+        // A read error already names the path; a JSON SyntaxError does not.
         const reason = message.includes(path) ? message : `${path}: ${message}`;
         throw new ConnectorResolveError('CONNECTOR_LIBRARY_ENTRY_UNREADABLE', `connector library entry for ${nodeType} is unreadable: ${reason}. The library index lists `
             + `this operation, but the file is missing or not valid JSON, so the library on disk is incomplete. `
@@ -980,8 +1081,8 @@ function readLibraryFile(nodeType, path, read) {
  * reported both its connection and `FolderKey` as "not configured" (UV-16774) while
  * validate and debug — which fold the case — passed.
  */
-function readV1def(entryPath) {
-    const raw = JSON.parse(readFileSync(v1defPathOf(entryPath), 'utf8'));
+function readV1def(read, entryPath) {
+    const raw = readJson(read, v1defPathOf(entryPath));
     const v1def = Array.isArray(raw) ? raw[0] : raw;
     const bindings = v1def?.model?.bindings;
     if (typeof bindings?.resource === 'string' && bindings.resource.toLowerCase() === 'connection') {

package/dist/core/list-envelope.d.ts

@@ -1,3 +1,38 @@
+/**
+ * list-envelope — read the LIST-ENVELOPE LEDGER that sits beside the connector
+ * library's `index.json`.
+ *
+ * ## What the ledger answers
+ *
+ * A connector LIST operation's node output is either the array itself (**bare**,
+ * `envelope: null`) or that array inside a one-field wrapper object
+ * (`envelope: "records"` ⇒ `{records: […]}`). **Nothing in the library declares
+ * which**: `outputSchema.fields` describes ONE record either way, and the two
+ * operations that declare no fields at all sit on opposite sides of what the
+ * corpus guessed ([#156](https://github.com/UiPath/flow-builder-sdk/issues/156)).
+ * It cannot be derived, so it is measured and written down — one row per
+ * operation, each carrying the evidence that put it there.
+ *
+ * ## The rule this file exists to enforce
+ *
+ * **An operation with no row is UNDECLARED, and undeclared means every reader
+ * behaves exactly as it did before the ledger existed.** The emitter declares no
+ * container, and a reader must go on treating an unknown name on a list output as
+ * a possible wrapper. 2,149 of the shipped library's 7,029 entries are List
+ * operations and the ledger holds eight — that ratio is the design, not a gap.
+ * It grows on demand, one measurement at a time.
+ *
+ * Measured 2026-08-02 (card G13, eight `flow debug` / product-runtime readings):
+ * every operation measured so far is **bare**, including both the corpus called
+ * wrappers. The ledger's own `$comment` carries the mechanism and the evidence
+ * tiers; this module only reads it.
+ *
+ * If a second reader is ever needed outside this package, copy this one rather
+ * than sharing it through a new package boundary: a 40-line JSON reader is the
+ * cheaper half. The LEDGER is the single source of truth — the readers are
+ * interchangeable.
+ */
+import { type ReadText } from './read-text.js';
 /** One measured operation. `envelope: null` is the BARE array. */
 export interface ListEnvelopeRow {
     nodeType: string;
@@ -21,7 +56,7 @@ export interface ListEnvelopeRow {
  * an empty ledger — every operation undeclared — which is what a library built
  * before this card, or a bare fixture library, looks like.
  */
-export declare function loadListEnvelopes(libraryDir: string | undefined): ListEnvelopeRow[];
+export declare function loadListEnvelopes(libraryDir: string | undefined, read?: ReadText): ListEnvelopeRow[];
 /**
  * The row for one operation, or `undefined` when it is undeclared.
  *

package/dist/core/list-envelope.js

@@ -32,36 +32,41 @@
  * cheaper half. The LEDGER is the single source of truth — the readers are
  * interchangeable.
  */
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-const CACHE = new Map();
+import { cacheFor, libraryPath, readTextFromDisk } from './read-text.js';
+const CACHE = new WeakMap();
 /**
  * Every declared row, from `<libraryDir>/list-envelopes.json`. An absent file is
  * an empty ledger — every operation undeclared — which is what a library built
  * before this card, or a bare fixture library, looks like.
  */
-export function loadListEnvelopes(libraryDir) {
+export function loadListEnvelopes(libraryDir, read = readTextFromDisk) {
     if (!libraryDir)
         return [];
-    const cached = CACHE.get(libraryDir);
+    const cache = cacheFor(CACHE, read);
+    const cached = cache.get(libraryDir);
     if (cached)
         return cached;
+    let text;
+    try {
+        text = read(libraryPath(libraryDir, 'list-envelopes.json'));
+    }
+    catch {
+        // Not cached: the reader may serve the file on a later call.
+        return [];
+    }
     let rows = [];
-    const file = join(libraryDir, 'list-envelopes.json');
-    if (existsSync(file)) {
-        try {
-            const parsed = JSON.parse(readFileSync(file, 'utf8'));
-            if (Array.isArray(parsed.operations))
-                rows = parsed.operations;
-        }
-        catch {
-            // A malformed ledger reads as an EMPTY one rather than throwing: the
-            // permissive path is the pre-ledger behaviour, so the worst case of a bad
-            // edit is losing the exactness, never breaking a compile.
-            rows = [];
-        }
+    try {
+        const parsed = JSON.parse(text ?? '{}');
+        if (Array.isArray(parsed.operations))
+            rows = parsed.operations;
+    }
+    catch {
+        // A malformed ledger reads as an EMPTY one rather than throwing: the
+        // permissive path is the pre-ledger behaviour, so the worst case of a bad
+        // edit is losing the exactness, never breaking a compile.
+        rows = [];
     }
-    CACHE.set(libraryDir, rows);
+    cache.set(libraryDir, rows);
     return rows;
 }
 /**

package/dist/core/lookup-store.d.ts

@@ -1,3 +1,4 @@
+import { type ReadText } from './read-text.js';
 import type { ByoaLedger } from './byoa.js';
 import type { LookupResolutions } from './lookups.js';
 /**
@@ -8,7 +9,7 @@ import type { LookupResolutions } from './lookups.js';
  * — it is a compile error naming the `prepare` command to run, which is the
  * behaviour an author wants from a missing resolution anyway.
  */
-export declare function loadLookupResolutions(overlayDir: string | undefined): LookupResolutions;
+export declare function loadLookupResolutions(overlayDir: string | undefined, read?: ReadText): LookupResolutions;
 /**
  * Load the `byoa` section of `<overlayDir>/resolutions.json` — the BYOA checks
  * `registry prepare` recorded (see `core/byoa.ts`) — or an empty map.
@@ -19,7 +20,7 @@ export declare function loadLookupResolutions(overlayDir: string | undefined): L
  * call rather than cached: `prepare` rewrites this file, and a stale "never
  * checked" answer would refuse a flow that was just verified.
  */
-export declare function loadByoaLedger(overlayDir: string | undefined): ByoaLedger;
+export declare function loadByoaLedger(overlayDir: string | undefined, read?: ReadText): ByoaLedger;
 /**
  * The invariant-collection ledger's `objectName` set, from a library dir.
  *
@@ -31,4 +32,4 @@ export declare function loadByoaLedger(overlayDir: string | undefined): ByoaLedg
  * @param libraryDir - A `library-json` directory, or the local overlay.
  * @returns Every `objectName` declared connector-invariant.
  */
-export declare function loadInvariantCollections(libraryDir: string | undefined): Set<string>;
+export declare function loadInvariantCollections(libraryDir: string | undefined, read?: ReadText): Set<string>;

package/dist/core/lookup-store.js

@@ -1,5 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { cacheFor, libraryPath, readTextFromDisk } from './read-text.js';
 /**
  * core/lookup-store — the two on-disk side-tables the lookup surface reads.
  *
@@ -14,7 +13,7 @@ import { join } from 'node:path';
  * the CLIs need to read files. Keeping the split makes that structural rather
  * than a thing to remember.
  */
-const RESOLUTION_CACHE = new Map();
+const RESOLUTION_CACHE = new WeakMap();
 /**
  * Load `<overlayDir>/resolutions.json`, or an empty map.
  *
@@ -23,26 +22,32 @@ const RESOLUTION_CACHE = new Map();
  * — it is a compile error naming the `prepare` command to run, which is the
  * behaviour an author wants from a missing resolution anyway.
  */
-export function loadLookupResolutions(overlayDir) {
+export function loadLookupResolutions(overlayDir, read = readTextFromDisk) {
     if (!overlayDir)
         return {};
-    const cached = RESOLUTION_CACHE.get(overlayDir);
+    const cache = cacheFor(RESOLUTION_CACHE, read);
+    const cached = cache.get(overlayDir);
     if (cached)
         return cached;
+    let text;
+    try {
+        text = read(libraryPath(overlayDir, 'resolutions.json'));
+    }
+    catch {
+        // Not cached: the reader may serve the file on a later call.
+        return {};
+    }
     let rows = {};
-    const file = join(overlayDir, 'resolutions.json');
-    if (existsSync(file)) {
-        try {
-            const parsed = JSON.parse(readFileSync(file, 'utf8'));
-            if (parsed.resolutions && typeof parsed.resolutions === 'object') {
-                rows = parsed.resolutions;
-            }
-        }
-        catch {
-            rows = {};
+    try {
+        const parsed = JSON.parse(text ?? '{}');
+        if (parsed.resolutions && typeof parsed.resolutions === 'object') {
+            rows = parsed.resolutions;
         }
     }
-    RESOLUTION_CACHE.set(overlayDir, rows);
+    catch {
+        rows = {};
+    }
+    cache.set(overlayDir, rows);
     return rows;
 }
 /**
@@ -55,14 +60,11 @@ export function loadLookupResolutions(overlayDir) {
  * call rather than cached: `prepare` rewrites this file, and a stale "never
  * checked" answer would refuse a flow that was just verified.
  */
-export function loadByoaLedger(overlayDir) {
+export function loadByoaLedger(overlayDir, read = readTextFromDisk) {
     if (!overlayDir)
         return {};
-    const file = join(overlayDir, 'resolutions.json');
-    if (!existsSync(file))
-        return {};
     try {
-        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        const parsed = JSON.parse(read(libraryPath(overlayDir, 'resolutions.json')) ?? '{}');
         const byoa = parsed?.byoa;
         return byoa && typeof byoa === 'object' && !Array.isArray(byoa) ? byoa : {};
     }
@@ -81,30 +83,36 @@ export function loadByoaLedger(overlayDir) {
  * @param libraryDir - A `library-json` directory, or the local overlay.
  * @returns Every `objectName` declared connector-invariant.
  */
-export function loadInvariantCollections(libraryDir) {
+export function loadInvariantCollections(libraryDir, read = readTextFromDisk) {
     if (!libraryDir)
         return new Set();
-    const cached = INVARIANT_CACHE.get(libraryDir);
+    const cache = cacheFor(INVARIANT_CACHE, read);
+    const cached = cache.get(libraryDir);
     if (cached)
         return cached;
+    let text;
+    try {
+        text = read(libraryPath(libraryDir, 'invariant-collections.json'));
+    }
+    catch {
+        // Not cached: the reader may serve the file on a later call.
+        return new Set();
+    }
     const out = new Set();
-    const file = join(libraryDir, 'invariant-collections.json');
-    if (existsSync(file)) {
-        try {
-            const parsed = JSON.parse(readFileSync(file, 'utf8'));
-            if (Array.isArray(parsed.collections)) {
-                for (const row of parsed.collections) {
-                    const name = row?.objectName;
-                    if (typeof name === 'string')
-                        out.add(name);
-                }
+    try {
+        const parsed = JSON.parse(text ?? '{}');
+        if (Array.isArray(parsed.collections)) {
+            for (const row of parsed.collections) {
+                const name = row?.objectName;
+                if (typeof name === 'string')
+                    out.add(name);
             }
         }
-        catch {
-            /* an empty ledger — see above */
-        }
     }
-    INVARIANT_CACHE.set(libraryDir, out);
+    catch {
+        /* an empty ledger — see above */
+    }
+    cache.set(libraryDir, out);
     return out;
 }
-const INVARIANT_CACHE = new Map();
+const INVARIANT_CACHE = new WeakMap();

package/dist/core/node-id-placeholder.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `{nodeId}` placeholder a definition writes where a node's own id goes
+ * (an output's source, a model's context), filled in for one node. Every
+ * node's definition-derived fields go through this one rule, so an agent's
+ * outputs and every other node's cannot fill it differently.
+ */
+/** `obj` with every `{nodeId}` in its JSON replaced by `nodeId`, as a fresh copy. */
+export declare function subNodeId<T>(obj: T, nodeId: string): T;

package/dist/core/node-id-placeholder.js

@@ -0,0 +1,10 @@
+/**
+ * The `{nodeId}` placeholder a definition writes where a node's own id goes
+ * (an output's source, a model's context), filled in for one node. Every
+ * node's definition-derived fields go through this one rule, so an agent's
+ * outputs and every other node's cannot fill it differently.
+ */
+/** `obj` with every `{nodeId}` in its JSON replaced by `nodeId`, as a fresh copy. */
+export function subNodeId(obj, nodeId) {
+    return JSON.parse(JSON.stringify(obj).split('{nodeId}').join(nodeId));
+}