@uipath/maestro-builder-sdk 6.4.0 → 6.5.0

package/dist/registry/generators/markdown/sections/schema-dynamic.js

@@ -0,0 +1,86 @@
+/**
+ * The blockquote on an operation whose real inputs arrive from a live
+ * connection (`runtime.requiresConnectionForSchema`). It points the agent at
+ * `registry prepare` without claiming every marked operation is incomplete; a
+ * discovery entry (`objectFromDiscovery`) is missing its OBJECT rather than
+ * field values, so its prose and its `--object` flag differ.
+ */
+import { afterLast, pyStr } from "../../../compat/pystr.js";
+import { dictOf, listOf, pyOr, pyTruthy } from "../pyvalue.js";
+export function schemaDynamicLines(j, nodeType) {
+    if (!pyTruthy(dictOf(j.runtime).requiresConnectionForSchema))
+        return [];
+    const conn = dictOf(j.connector);
+    const op = dictOf(j.operation);
+    const key = pyStr(pyOr(conn.key, "<key>"));
+    const prefix = `uipath.connector.${key}.`;
+    const action = nodeType.startsWith(prefix) ? nodeType.slice(prefix.length) : afterLast(nodeType, ".");
+    const parents = listOf(pyOr(dictOf(op.schemaAction).parents, []));
+    const discovery = pyTruthy(op.objectFromDiscovery);
+    const out = [];
+    let supply;
+    if (discovery) {
+        out.push("> ⚠️ **The object is not in this catalog.** This node works on " +
+            "any object in the connection, including custom ones, so it " +
+            "carries no inputs here — what has to be resolved is the " +
+            "OBJECT, not a field value. Author first, then one command " +
+            "resolves it; **Choosing the object** below has the rules.");
+        supply = "--object <name-as-the-task-said-it>";
+    }
+    else {
+        out.push("> ⚠️ **This operation resolves its real inputs from a live " +
+            "connection.** The inputs listed below are only what the " +
+            "tenant-agnostic snapshot carries. Do NOT hand-guess the " +
+            "missing names.");
+        out.push(">");
+        if (parents.length) {
+            out.push("> Its parents are named outright, with the call that " +
+                "resolves each one, under **Resolving the field set** " +
+                "below. Read that first.");
+        }
+        else {
+            out.push("> Any input whose reference path carries a `{placeholder}` " +
+                "is a parent: resolve a value for EVERY parent first, then " +
+                "prepare the operation with all of them. Too few parents is " +
+                "refused; a wrong VALUE is not — it resolves right back to " +
+                "the parent fields.");
+        }
+        // The `-f` stays visible even when the catalog cannot name the parents.
+        supply = parents.length
+            ? parents.map((name) => `-f ${pyStr(name)}=<value>`).join(" ")
+            : "-f <parent-field>=<value> ...";
+    }
+    out.push(">");
+    out.push("> ```bash");
+    // ONE spelling on every page, the one `check` prints; no `--connection-id`.
+    if (discovery) {
+        out.push(`> npx flow-sdk registry prepare ${key} ${action} ${supply}`);
+    }
+    else if (supply) {
+        out.push(`> npx flow-sdk registry prepare ${key} ${action} \\`);
+        out.push(`>   ${supply}`);
+    }
+    else {
+        out.push(`> npx flow-sdk registry prepare ${key} ${action}`);
+    }
+    out.push("> ```");
+    out.push(">");
+    let overlay = "> It writes a `./connectors-local/` overlay the compiler " +
+        "auto-detects (its fields are unioned onto this entry).";
+    if (!discovery) {
+        overlay +=
+            " The full loop — how to find the parents and resolve their " +
+                "values — is in the connector guide " +
+                "(`references/connector-params.md`) under \"Schema-dynamic " +
+                "operations: the parent-field loop\".";
+    }
+    out.push(overlay);
+    out.push("> This requires a working live connection. For an explicitly " +
+        "offline/validate-only flow that needs no connection-specific fields, " +
+        "use the published static inputs below instead; a placeholder " +
+        "connection cannot materialize a live schema. If that input list is " +
+        "empty, pass `{}`: offline evidence proves operation identity and " +
+        "control routing, not the provider payload or dispatch.");
+    out.push("");
+    return out;
+}

package/dist/registry/generators/materialize.d.ts

@@ -0,0 +1,30 @@
+import { type Reporter } from "../reporter.js";
+export interface MaterializeOptions {
+    /** The extracted library; must hold an `index.json`. */
+    libraryJsonPath: string;
+    /** Where the Markdown goes. Omit to skip it. */
+    libraryMarkdownPath?: string;
+    /** Where the descriptor modules go. Omit to generate none. */
+    connectorsPath?: string;
+    /** Connector keys to emit descriptors for, instead of all of them. */
+    connectorSubset?: readonly string[];
+    /** Module specifier the generated TypeScript imports the SDK from. */
+    connectorImport?: string;
+    /** `registry-triggers.json`, for `<key>.triggers.ts` modules beside the descriptors. */
+    triggersPath?: string;
+    /** Also emit descriptors for GenericExpanded entries (the overlay's case). */
+    includeGenericExpanded?: boolean;
+    /** Fail when a page cites a symbol the modules do not export. */
+    checkSymbols?: boolean;
+    reporter?: Reporter;
+}
+export interface MaterializeResult {
+    markdownFiles: number;
+    typescriptModules: number;
+    /** `nodeType → exported const`, for callers that print a handoff. */
+    symbols: Map<string, string>;
+    warnings: string[];
+}
+export declare function materialize(options: MaterializeOptions): MaterializeResult;
+/** Remove a staging directory left by an interrupted run, if any. */
+export declare function cleanStaging(target: string): void;

package/dist/registry/generators/materialize.js

@@ -0,0 +1,132 @@
+/**
+ * Turn an extracted `library-json/` into the two derived views: Markdown pages
+ * an agent reads and TypeScript descriptor modules an author imports.
+ *
+ * This is `materialize_registry.py` without the subprocesses: the three
+ * generators it used to spawn are function calls. What it keeps is every
+ * observable rule of the Python — the connectors directory is wiped first, the
+ * Markdown is staged beside its target and swapped in, a missing trigger
+ * catalogue is an error, the trigger subset is deliberately NOT narrowed to the
+ * connector subset (the Python never forwarded it; file counts depend on that),
+ * and a required-input gap fails the run after the descriptor modules are
+ * written but before the trigger modules are, the way the descriptor
+ * generator's `sys.exit` did.
+ *
+ * New, behind a flag: `checkSymbols` runs the cross-check that used to be a
+ * separate script in `unpack-library.sh`, so a page can never cite a symbol
+ * the descriptors do not export.
+ */
+import { PACKAGE_NAME } from "../../package-name.js";
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pyJsonDocument } from "../codecs/pyjson.js";
+import { Refusal } from "../errors.js";
+import { listFiles, resetDir, stageAndSwap, writeText } from "../files.js";
+import { loadLibrary } from "../library-reader.js";
+import { silentReporter } from "../reporter.js";
+import { formatRequiredInputGaps, renderDescriptorModules } from "./descriptors.js";
+import { renderMarkdownLibrary } from "./markdown/index.js";
+import { citedSymbolMismatches, formatMismatches } from "./md-symbols.js";
+import { renderTriggerModules } from "./triggers.js";
+const DEFAULT_IMPORT = PACKAGE_NAME;
+function countFiles(dir, suffix, recursive) {
+    if (!dir || !existsSync(dir))
+        return 0;
+    if (recursive)
+        return listFiles(dir, (rel) => rel.endsWith(suffix)).length;
+    return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(suffix)).length;
+}
+/** The pages on disk under a Markdown tree, keyed like `renderMarkdownLibrary` keys them. */
+function readPages(markdownDir) {
+    const pages = new Map();
+    for (const rel of listFiles(markdownDir, (r) => r.endsWith(".md"))) {
+        pages.set(rel, readFileSync(join(markdownDir, rel), "utf8"));
+    }
+    return pages;
+}
+export function materialize(options) {
+    const reporter = options.reporter ?? silentReporter;
+    const libraryJson = resolve(options.libraryJsonPath);
+    const libraryMd = options.libraryMarkdownPath ? resolve(options.libraryMarkdownPath) : undefined;
+    const connectors = options.connectorsPath ? resolve(options.connectorsPath) : undefined;
+    if (!existsSync(join(libraryJson, "index.json"))) {
+        throw new Refusal(`materialize-registry: missing ${join(libraryJson, "index.json")}`, "LIBRARY_MISSING");
+    }
+    const outputs = [libraryMd, connectors].filter((p) => p !== undefined);
+    if (outputs.includes(libraryJson) || new Set(outputs).size !== outputs.length) {
+        throw new Refusal("materialize-registry: input and output directories must be distinct", "OUTPUTS_NOT_DISTINCT");
+    }
+    const warnings = [];
+    const library = loadLibrary(libraryJson);
+    if (connectors !== undefined)
+        resetDir(connectors);
+    let pages;
+    if (libraryMd !== undefined) {
+        // Generate beside the target and swap, exactly as pull-cli does for
+        // library-json: two `registry pull`s racing on the shared final path (a
+        // coding agent issues tool calls in parallel) once left one of them with
+        // "Directory not empty" mid-write.
+        const rendered = renderMarkdownLibrary(library);
+        for (const warning of rendered.warnings)
+            reporter.warn(warning);
+        warnings.push(...rendered.warnings);
+        stageAndSwap(libraryMd, (staging) => {
+            for (const [rel, text] of rendered.pages)
+                writeText(join(staging, rel), text);
+            writeText(join(staging, "index.json"), pyJsonDocument(rendered.index));
+        });
+        pages = rendered.pages;
+    }
+    let modules = new Map();
+    let symbols = new Map();
+    if (connectors !== undefined) {
+        const output = renderDescriptorModules(library, {
+            importSpecifier: options.connectorImport ?? DEFAULT_IMPORT,
+            connectors: options.connectorSubset?.filter((c) => c.length > 0),
+            includeGenericExpanded: options.includeGenericExpanded,
+        });
+        modules = output.modules;
+        symbols = output.symbols;
+        for (const [name, text] of modules)
+            writeText(join(connectors, name), text);
+        // The descriptor generator wrote every module and then exited 1 on a gap,
+        // and `materialize_registry.py` ran it with `check=True`, so the trigger
+        // generator that came next never ran. Same here: the descriptor modules
+        // are on disk, the failure is as loud, and no `.triggers.ts` is written
+        // beside them.
+        if (output.requiredInputGaps.length > 0) {
+            throw new Refusal(formatRequiredInputGaps(output.requiredInputGaps), "REQUIRED_INPUT_GAP");
+        }
+        if (options.triggersPath) {
+            const triggersPath = resolve(options.triggersPath);
+            if (!existsSync(triggersPath)) {
+                throw new Refusal(`materialize-registry: missing trigger catalog ${triggersPath}`, "TRIGGERS_MISSING");
+            }
+            const catalogue = JSON.parse(readFileSync(triggersPath, "utf8"));
+            // The connector subset is not forwarded here, as the Python never did.
+            for (const [name, text] of renderTriggerModules(catalogue, { importSpecifier: options.connectorImport ?? DEFAULT_IMPORT })) {
+                writeText(join(connectors, name), text);
+            }
+        }
+    }
+    if (options.checkSymbols && connectors !== undefined) {
+        const checked = pages ?? (libraryMd && existsSync(libraryMd) ? readPages(libraryMd) : undefined);
+        if (checked) {
+            const bad = citedSymbolMismatches(checked, modules);
+            if (bad.length > 0)
+                throw new Refusal(formatMismatches(bad), "MD_SYMBOL_MISMATCH");
+        }
+    }
+    const result = {
+        markdownFiles: countFiles(libraryMd, ".md", true),
+        typescriptModules: countFiles(connectors, ".ts", false),
+        symbols,
+        warnings,
+    };
+    reporter.info(`materialize-registry: generated ${result.markdownFiles} markdown file(s) and ${result.typescriptModules} TypeScript module(s)`);
+    return result;
+}
+/** Remove a staging directory left by an interrupted run, if any. */
+export function cleanStaging(target) {
+    rmSync(`${target}.tmp-${process.pid}`, { recursive: true, force: true });
+}

package/dist/registry/generators/md-symbols.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Every descriptor symbol the Markdown cites must exist in the emitted TypeScript.
+ *
+ * The `## Example` on each page names an exported const —
+ * `connector(SendMessageToUser, …)` — and imports it from
+ * `./connectors/<key>.ts`. Neither the const name nor the `.by*` aliases are in
+ * the JSON library: both are derived by `naming.symbolIndex`, which the
+ * Markdown and descriptor generators share precisely so they cannot disagree.
+ * This is the check that proves the sharing is real rather than intended.
+ * Ported from `check_md_symbols.py`.
+ */
+/** `{ connectorKey → exported const names }` from `<key>.ts` module texts, `.triggers.ts` excluded. */
+export declare function exportedSymbols(modules: ReadonlyMap<string, string>): Map<string, Set<string>>;
+/**
+ * One line per page that cites a symbol its module does not export, as
+ * `<page> cites <key>.<Symbol>`, in page order.
+ */
+export declare function citedSymbolMismatches(pages: ReadonlyMap<string, string>, modules: ReadonlyMap<string, string>): string[];
+/** How many mismatches to print before truncating. */
+export declare const MAX_REPORTED = 20;
+/** The stderr text `check_md_symbols.py` printed, for the same mismatches. */
+export declare function formatMismatches(bad: readonly string[]): string;

package/dist/registry/generators/md-symbols.js

@@ -0,0 +1,58 @@
+/**
+ * Every descriptor symbol the Markdown cites must exist in the emitted TypeScript.
+ *
+ * The `## Example` on each page names an exported const —
+ * `connector(SendMessageToUser, …)` — and imports it from
+ * `./connectors/<key>.ts`. Neither the const name nor the `.by*` aliases are in
+ * the JSON library: both are derived by `naming.symbolIndex`, which the
+ * Markdown and descriptor generators share precisely so they cannot disagree.
+ * This is the check that proves the sharing is real rather than intended.
+ * Ported from `check_md_symbols.py`.
+ */
+/** `export const X =` at a line start; `\w` as Python spells it, Unicode-aware. */
+const EXPORTED = /^export const ([\p{L}\p{N}_]+) =/gmu;
+/** `import { X } from './connectors/<key>.ts'` or `./connectors-local/…`. */
+const CITED = /import \{ ([\p{L}\p{N}_]+) \} from '\.\/connectors(?:-local)?\/([^']+)\.ts'/gu;
+/** `{ connectorKey → exported const names }` from `<key>.ts` module texts, `.triggers.ts` excluded. */
+export function exportedSymbols(modules) {
+    const out = new Map();
+    for (const [fileName, text] of modules) {
+        // `<key>.triggers.ts` is the connector-EVENT surface, a different catalogue
+        // with its own identity-only descriptors. Pages never import from it.
+        if (!fileName.endsWith(".ts") || fileName.endsWith(".triggers.ts"))
+            continue;
+        const names = new Set();
+        for (const match of text.matchAll(EXPORTED))
+            names.add(match[1]);
+        out.set(fileName.slice(0, -3), names);
+    }
+    return out;
+}
+/**
+ * One line per page that cites a symbol its module does not export, as
+ * `<page> cites <key>.<Symbol>`, in page order.
+ */
+export function citedSymbolMismatches(pages, modules) {
+    const exported = exportedSymbols(modules);
+    const bad = [];
+    for (const [page, text] of pages) {
+        for (const match of text.matchAll(CITED)) {
+            const [, symbol, key] = match;
+            if (!exported.get(key)?.has(symbol))
+                bad.push(`${page} cites ${key}.${symbol}`);
+        }
+    }
+    return bad;
+}
+/** How many mismatches to print before truncating. */
+export const MAX_REPORTED = 20;
+/** The stderr text `check_md_symbols.py` printed, for the same mismatches. */
+export function formatMismatches(bad) {
+    const lines = [`error: ${bad.length} markdown page(s) cite a descriptor symbol that was never emitted:`];
+    for (const line of bad.slice(0, MAX_REPORTED))
+        lines.push(`  ${line}`);
+    if (bad.length > MAX_REPORTED)
+        lines.push(`  … and ${bad.length - MAX_REPORTED} more`);
+    lines.push("       Both generators derive symbol names through registry/naming.ts (symbolIndex).", "       A mismatch means one of them stopped using it. See docs/CONNECTOR_LOOKUP_DESIGN.md §6.4.");
+    return lines.join("\n");
+}

package/dist/registry/generators/triggers.d.ts

@@ -0,0 +1,15 @@
+import { type TriggerCatalogue, type TriggerCatalogueRow } from "../model/library.js";
+export interface TriggerModulesOptions {
+    /** Module specifier for `import { triggerDescriptor }`. */
+    importSpecifier?: string;
+    /** Connector keys to emit; every connector when omitted or empty. */
+    connectors?: readonly string[];
+}
+/**
+ * `{ "<connector-key>.triggers.ts" → module text }` for the catalogue.
+ *
+ * Modules come out sorted by connector key, triggers within a module sorted by
+ * node type, both by code point — the order the shared symbol derivation
+ * assumes.
+ */
+export declare function renderTriggerModules(catalogue: TriggerCatalogue | TriggerCatalogueRow[], options?: TriggerModulesOptions): Map<string, string>;

package/dist/registry/generators/triggers.js

@@ -0,0 +1,85 @@
+/**
+ * Identity-only trigger descriptors from `registry-triggers.json`.
+ *
+ * The catalogue carries `{ NodeType, DisplayName, Description, Version,
+ * connectorKey }` and nothing else, because a trigger's field schema is
+ * connection-dependent. So one `triggerDescriptor()` const per event is
+ * emitted, one module per connector, and `onEvent`/`waitForEvent` take it in
+ * place of the stringly `{ connector, event }`. Ported from
+ * `generate_triggers_ts.py`. The module text was verified byte-for-byte
+ * against that script before the Python was deleted; the differential went
+ * with it, and `tests/registry-triggers-gen.test.ts` now pins the text.
+ */
+import { PACKAGE_NAME } from "../../package-name.js";
+import { pyJsonString, pyJsonStringify } from "../codecs/pyjson.js";
+import { sortedByCodePoint, sortedStrings } from "../compat/compare.js";
+import { afterLast, pyRstrip, pyStrip, upperFirst } from "../compat/pystr.js";
+import { TRIGGER_PREFIX } from "../model/library.js";
+/** The trigger generator's own pascal: same split, `Event` as the empty fallback. */
+function pascalEvent(eventId) {
+    const joined = eventId
+        .split(/[^A-Za-z0-9]+/)
+        .filter((w) => w.length > 0)
+        .map((w) => upperFirst(w))
+        .join("");
+    return joined || "Event";
+}
+function emitTrigger(row, seen) {
+    const eventId = afterLast(row.NodeType, ".");
+    let name = pascalEvent(eventId);
+    while (seen.has(name))
+        name += "_";
+    seen.add(name);
+    const version = "Version" in row ? row.Version : "1.0.0";
+    const label = row.DisplayName || eventId;
+    const description = pyStrip(String(row.Description || "")).replaceAll("\n", " ");
+    let doc = description ? `${label} — ${description}` : label;
+    doc = doc.replaceAll("*/", "* /"); // never let a description close the doc comment early
+    return [
+        `/** ${doc} */`,
+        `export const ${name} = triggerDescriptor()({`,
+        `  connector: ${pyJsonString(row.connectorKey)},`,
+        `  event: ${pyJsonString(eventId)},`,
+        `  version: ${pyJsonStringify(version)},`,
+        `  displayName: ${pyJsonString(label)},`,
+        "} as const);",
+    ];
+}
+/**
+ * `{ "<connector-key>.triggers.ts" → module text }` for the catalogue.
+ *
+ * Modules come out sorted by connector key, triggers within a module sorted by
+ * node type, both by code point — the order the shared symbol derivation
+ * assumes.
+ */
+export function renderTriggerModules(catalogue, options = {}) {
+    const rows = Array.isArray(catalogue) ? catalogue : catalogue.triggers;
+    const subset = new Set((options.connectors ?? []).filter((c) => c.length > 0));
+    const importSpecifier = options.importSpecifier ?? PACKAGE_NAME;
+    const byConnector = new Map();
+    for (const row of rows) {
+        const nodeType = row.NodeType ?? "";
+        if (!nodeType.startsWith(TRIGGER_PREFIX))
+            continue; // catalogue is trigger-only, but be defensive
+        const key = row.connectorKey;
+        if (subset.size > 0 && !subset.has(key))
+            continue;
+        const group = byConnector.get(key);
+        if (group)
+            group.push(row);
+        else
+            byConnector.set(key, [row]);
+    }
+    const modules = new Map();
+    for (const key of sortedStrings(byConnector.keys())) {
+        const seen = new Set();
+        const body = [`import { triggerDescriptor } from ${pyJsonString(importSpecifier)};`, ""];
+        for (const row of sortedByCodePoint(byConnector.get(key), (r) => r.NodeType)) {
+            body.push(...emitTrigger(row, seen), "");
+        }
+        // `"\n".join(body).rstrip() + "\n"`: `pyRstrip`, not `trimEnd`, because the
+        // two disagree on which characters are whitespace (`\x1f`, ``).
+        modules.set(`${key}.triggers.ts`, `${pyRstrip(body.join("\n"))}\n`);
+    }
+    return modules;
+}

package/dist/registry/generators/type-registry.d.ts

@@ -0,0 +1,50 @@
+import { type TypeNode, type TypeTree } from "./type-tree.js";
+export interface NamedTypeRegistryOptions {
+    /** Appended to every interface name; `"Input"` for the input registry. */
+    suffix?: string;
+    /** Render every property optional (outputs); inputs follow `required`. */
+    allOptional?: boolean;
+    /** Merge same-named nodes into one definition (outputs) or reuse exact shapes only (inputs). */
+    mergeReused?: boolean;
+    /** Wrap property types in `ConnectorValue<…>` / `ConnectorLookupValue<…>`. */
+    isInput?: boolean;
+}
+/**
+ * Renders one property line of an interface — `descriptors.ts`'s
+ * `emitNestedProperty`, handed to {@link NamedTypeRegistry.emit} so the
+ * registry need not import the module that imports it.
+ */
+export type PropertyRenderer = (name: string, node: TypeNode, indent: string, namedTypes: NamedTypeRegistry, allOptional: boolean, isInput: boolean) => string[];
+export declare class NamedTypeRegistry {
+    readonly isInput: boolean;
+    readonly suffix: string;
+    readonly allOptional: boolean;
+    readonly mergeReused: boolean;
+    private readonly byName;
+    /** Node identity → the name it was registered under (the Python's `id(node)` map). */
+    private readonly byNode;
+    /** `(baseName, fingerprint)` → name, for the exact-shape reuse of the input registry. */
+    private readonly shapeNames;
+    /** Names in definition order; `emit()` walks it while `register()` may still append. */
+    private readonly definitions;
+    private readonly registering;
+    constructor(options?: NamedTypeRegistryOptions);
+    /** Name the node (and, recursively, its object-valued children); return the name. */
+    register(fieldName: string, node: TypeNode): string;
+    /** Register every root that renders as an interface. */
+    discover(roots: TypeTree): void;
+    /**
+     * The one registered interface an opaque `array` field can be the element
+     * type of: `Contact`, or a de-collided `Contact2`, but not when both exist.
+     */
+    private knownArrayElement;
+    /** The TypeScript type of a property whose value is `node`. */
+    typeFor(fieldName: string, node: TypeNode): string;
+    /**
+     * Every registered interface, one blank line after each. Rendering a
+     * definition may register a further nested object, so the walk is by index
+     * over a list that can grow while it runs; a definition discovered late is
+     * emitted too.
+     */
+    emit(renderProperty: PropertyRenderer): string[];
+}

package/dist/registry/generators/type-registry.js

@@ -0,0 +1,154 @@
+/**
+ * Reusable named interfaces shared by all operations in one connector module.
+ *
+ * Every nested object in a connector's field trees becomes an exported
+ * interface, named from its segment. The OUTPUT registry merges every node that
+ * takes a name into one canonical definition (`Address` is enriched by each
+ * operation that returns one). The INPUT registry reuses a name only for an
+ * exact shape, because an input type that gained a field from a sibling
+ * operation would let an author send a field this operation does not take;
+ * a different shape under the same segment gets `AddressInput2`, `…3`.
+ * Ported from `NamedTypeRegistry` in `generate_connectors_ts.py`.
+ */
+import { sortedStrings } from "../compat/compare.js";
+import { mergeTypeNodes, nestedTypeName, typeFingerprint } from "./type-tree.js";
+export class NamedTypeRegistry {
+    isInput;
+    suffix;
+    allOptional;
+    mergeReused;
+    byName = new Map();
+    /** Node identity → the name it was registered under (the Python's `id(node)` map). */
+    byNode = new Map();
+    /** `(baseName, fingerprint)` → name, for the exact-shape reuse of the input registry. */
+    shapeNames = new Map();
+    /** Names in definition order; `emit()` walks it while `register()` may still append. */
+    definitions = [];
+    registering = new Set();
+    constructor(options = {}) {
+        this.suffix = options.suffix ?? "";
+        this.allOptional = options.allOptional ?? true;
+        this.mergeReused = options.mergeReused ?? true;
+        this.isInput = options.isInput ?? false;
+    }
+    /** Name the node (and, recursively, its object-valued children); return the name. */
+    register(fieldName, node) {
+        const known = this.byNode.get(node);
+        if (known)
+            return known;
+        const baseName = nestedTypeName(fieldName, node, this.suffix);
+        let typeName;
+        if (this.mergeReused) {
+            typeName = baseName;
+        }
+        else {
+            const shapeKey = JSON.stringify([baseName, typeFingerprint(node)]);
+            typeName = this.shapeNames.get(shapeKey) ?? "";
+            if (!typeName) {
+                typeName = baseName;
+                let suffix = 2;
+                while (this.byName.has(typeName)) {
+                    typeName = `${baseName}${suffix}`;
+                    suffix += 1;
+                }
+                this.shapeNames.set(shapeKey, typeName);
+            }
+        }
+        let canonical = this.byName.get(typeName);
+        if (canonical === undefined) {
+            canonical = node;
+            this.byName.set(typeName, canonical);
+            this.definitions.push(typeName);
+        }
+        else if (canonical !== node) {
+            if (this.mergeReused)
+                mergeTypeNodes(canonical, node);
+        }
+        this.byNode.set(node, typeName);
+        // A schema can recursively repeat the same segment name
+        // (`children[*].children[*]…`). Merge it into the shared interface, but do
+        // not recursively rediscover that interface while it is active.
+        if (this.registering.has(typeName))
+            return typeName;
+        this.registering.add(typeName);
+        try {
+            // Registration can enrich a canonical node, so iterate a snapshot.
+            for (const [childName, child] of [...canonical.children]) {
+                if (child.children.size > 0 || child.opaqueObject)
+                    this.register(childName, child);
+            }
+        }
+        finally {
+            this.registering.delete(typeName);
+        }
+        return typeName;
+    }
+    /** Register every root that renders as an interface. */
+    discover(roots) {
+        for (const [fieldName, node] of roots) {
+            if (node.children.size > 0 || node.opaqueObject)
+                this.register(fieldName, node);
+        }
+    }
+    /**
+     * The one registered interface an opaque `array` field can be the element
+     * type of: `Contact`, or a de-collided `Contact2`, but not when both exist.
+     */
+    knownArrayElement(fieldName, node) {
+        const candidate = nestedTypeName(fieldName, node, this.suffix);
+        const matches = [];
+        for (const name of this.byName.keys()) {
+            if (name === candidate || (name.startsWith(candidate) && /^[2-9][0-9]*$/.test(name.slice(candidate.length)))) {
+                matches.push(name);
+            }
+        }
+        return matches.length === 1 ? matches[0] : undefined;
+    }
+    /** The TypeScript type of a property whose value is `node`. */
+    typeFor(fieldName, node) {
+        let base;
+        if (node.children.size > 0 || node.opaqueObject) {
+            base = this.register(fieldName, node);
+        }
+        else if (node.opaqueArray) {
+            const knownElement = this.knownArrayElement(fieldName, node);
+            if (knownElement)
+                return `Array<${knownElement}>`;
+            return "unknown[]";
+        }
+        else {
+            base = sortedStrings(node.declaredTypes).join(" | ") || "unknown";
+        }
+        const hasArray = node.arrayModes.has(true);
+        const hasScalar = node.arrayModes.has(false);
+        if (hasArray && hasScalar)
+            return `${base} | Array<${base}>`;
+        if (hasArray)
+            return `Array<${base}>`;
+        return base;
+    }
+    /**
+     * Every registered interface, one blank line after each. Rendering a
+     * definition may register a further nested object, so the walk is by index
+     * over a list that can grow while it runs; a definition discovered late is
+     * emitted too.
+     */
+    emit(renderProperty) {
+        const lines = [];
+        let index = 0;
+        while (index < this.definitions.length) {
+            const typeName = this.definitions[index];
+            const node = this.byName.get(typeName);
+            lines.push(`export interface ${typeName} {`);
+            if (node.opaqueObject)
+                lines.push("  [key: string]: unknown;");
+            for (const [childName, child] of node.children) {
+                lines.push(...renderProperty(childName, child, "  ", this, this.allOptional, this.isInput));
+            }
+            lines.push("}");
+            lines.push("");
+            index += 1;
+        }
+        return lines;
+    }
+}