@techspokes/typescript-wsdl-client 1.1.4 → 1.1.5

package/dist/compiler/semanticTypeDependencies.d.ts

@@ -0,0 +1,8 @@
+import type { SemanticContext } from './semanticContext.js';
+import type { SemanticTypeDependency } from './semanticTypeReference.js';
+/** Call inside the request guard; inputs are borrowed internal receipt data. */
+export declare function collectSemanticTypeDependencies(context: SemanticContext): Readonly<{
+    add(required: readonly SemanticTypeDependency[]): void;
+    snapshot(): readonly SemanticTypeDependency[];
+}>;
+//# sourceMappingURL=semanticTypeDependencies.d.ts.map

package/dist/compiler/semanticTypeDependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticTypeDependencies.d.ts","sourceRoot":"","sources":["../../src/compiler/semanticTypeDependencies.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AASvE,gFAAgF;AAChF,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAAC;IAClF,GAAG,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,GAAG,IAAI,CAAC;IACvD,QAAQ,IAAI,SAAS,sBAAsB,EAAE,CAAC;CAC/C,CAAC,CAwDD"}

package/dist/compiler/semanticTypeDependencies.js

@@ -0,0 +1,64 @@
+/** Charged accumulation of already-owned type dependency facts; no validity authority. */
+import { assertSemanticContext } from './semanticContext.js';
+import { semanticTypeKey } from './schemaTypeIdentity.js';
+const ownedByContext = new WeakMap();
+/** Call inside the request guard; inputs are borrowed internal receipt data. */
+export function collectSemanticTypeDependencies(context) {
+    assertSemanticContext(context);
+    const budget = context.budget;
+    budget.chargeWork(7);
+    let owned = ownedByContext.get(context);
+    if (!owned) {
+        budget.chargeWork(7);
+        owned = { facts: new Map(), keys: new WeakMap() };
+        ownedByContext.set(context, owned);
+    }
+    const facts = new Map();
+    let published;
+    return Object.freeze({
+        add(required) {
+            budget.chargeWork();
+            for (const dependency of required) {
+                budget.chargeWork(4);
+                if (!dependency || typeof dependency !== 'object')
+                    throw new TypeError('Expected a semantic type dependency');
+                let key = owned.keys.get(dependency);
+                if (key === undefined) {
+                    // No accessor execution and no lasting trust in a borrowed input's
+                    // identity. Its current primitive values are checked on every visit.
+                    budget.chargeWork(48);
+                    const origin = Object.getOwnPropertyDescriptor(dependency, 'contextId');
+                    const type = Object.getOwnPropertyDescriptor(dependency, 'type');
+                    if (!origin || !('value' in origin) || typeof origin.value !== 'string' || !type || !('value' in type))
+                        throw new TypeError('Expected own-data semantic type dependency fields');
+                    const identity = semanticTypeKey(context, type.value);
+                    budget.chargeWork(40 + origin.value.length * 2 + identity.length);
+                    key = `${origin.value.length}:${origin.value}:${identity}`;
+                }
+                budget.chargeWork(2);
+                let fact = owned.facts.get(key);
+                if (!fact) {
+                    fact = budget.freeze(budget.snapshot(dependency));
+                    budget.chargeWork(4);
+                    owned.facts.set(key, fact);
+                    owned.keys.set(fact, key);
+                }
+                if (!facts.has(key)) {
+                    budget.chargeWork(3);
+                    facts.set(key, fact);
+                    published = undefined;
+                }
+            }
+        },
+        snapshot() {
+            budget.chargeWork(2);
+            if (published)
+                return published;
+            // Every member is a private owned immutable result. Only this array is
+            // newly copied/frozen; traversing those member graphs again adds no safety.
+            budget.chargeWork(3 + facts.size * 3);
+            published = Object.freeze([...facts.values()]);
+            return published;
+        },
+    });
+}

package/dist/compiler/semanticTypeReference.d.ts

@@ -0,0 +1,24 @@
+/** Internal semantic references. Canonical/public/persisted Reference is unchanged. */
+import type { NodeId, Reference } from './canonicalGraph.js';
+import type { ExpandedName } from '../loader/orderedSyntax.js';
+import type { SemanticBudget } from './semanticBudget.js';
+/** Plain selector data, not an issued component or validity receipt. */
+export type OriginalGeneratedScalarReference = Readonly<{
+    kind: 'original-generated';
+    owner: NodeId;
+}>;
+export type SemanticTypeReference = Reference | OriginalGeneratedScalarReference;
+export type SemanticTypeIdentity = Readonly<{
+    kind: 'component';
+    id: NodeId;
+} | {
+    kind: 'builtin';
+    name: ExpandedName;
+}> | OriginalGeneratedScalarReference;
+export type SemanticTypeDependency = Readonly<{
+    contextId: string;
+    type: SemanticTypeIdentity;
+}>;
+/** Checks only reference shape; authenticated context resolution owns membership. */
+export declare function assertSemanticTypeReferenceShape(value: unknown, budget: SemanticBudget): asserts value is SemanticTypeReference;
+//# sourceMappingURL=semanticTypeReference.d.ts.map

package/dist/compiler/semanticTypeReference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticTypeReference.d.ts","sourceRoot":"","sources":["../../src/compiler/semanticTypeReference.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,KAAK,EAAC,MAAM,EAAE,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AAExD,wEAAwE;AACxE,MAAM,MAAM,gCAAgC,GAAG,QAAQ,CAAC;IAAC,IAAI,EAAE,oBAAoB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC;AACrG,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,gCAAgC,CAAC;AACjF,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAC,GAAG;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAC,CAAC,GAChH,gCAAgC,CAAC;AACrC,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,oBAAoB,CAAA;CAAC,CAAC,CAAC;AAE/F,qFAAqF;AACrF,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,IAAI,qBAAqB,CAoB/H"}

package/dist/compiler/semanticTypeReference.js

@@ -0,0 +1,36 @@
+/** Checks only reference shape; authenticated context resolution owns membership. */
+export function assertSemanticTypeReferenceShape(value, budget) {
+    const field = (input, key) => {
+        budget.chargeWork(44 + key.length);
+        if (!input || typeof input !== 'object' || Array.isArray(input))
+            throw new TypeError('Expected semantic type reference data');
+        const own = Object.getOwnPropertyDescriptor(input, key);
+        if (own && !('value' in own))
+            throw new TypeError('Semantic type references cannot contain accessors');
+        return own?.value;
+    };
+    const id = (input) => { budget.chargeWork(); if (typeof input !== 'string' || !input)
+        throw new TypeError('Expected semantic type identity'); };
+    const kind = field(value, 'kind');
+    if (kind === 'original-generated') {
+        id(field(value, 'owner'));
+        return;
+    }
+    if (kind === 'local') {
+        id(field(value, 'target'));
+        return;
+    }
+    if (kind !== 'symbol' && kind !== 'builtin')
+        throw new TypeError('Unknown semantic type reference kind');
+    const name = field(value, 'name');
+    if (typeof field(name, 'namespace') !== 'string')
+        throw new TypeError('Expected semantic type namespace');
+    id(field(name, 'local'));
+    if (kind === 'symbol') {
+        if (field(value, 'role') !== 'type')
+            throw new TypeError('Expected a type symbol');
+        const target = field(value, 'target');
+        if (target !== undefined)
+            id(target);
+    }
+}

package/dist/compiler/shapeResolver.d.ts

@@ -1,5 +1,6 @@
 import { type CompiledCatalog } from "./schemaCompiler.js";
 import type { StreamConfig } from "../util/streamConfig.js";
+export { prepareResolvedCompilationInput } from "./semanticCatalog.js";
 export interface ApplyShapeCatalogsOptions {
     /** Directory against which relative `catalogFile`/`wsdlSource` paths resolve. Defaults to process.cwd(). */
     baseDir?: string;

package/dist/compiler/shapeResolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shapeResolver.d.ts","sourceRoot":"","sources":["../../src/compiler/shapeResolver.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAqC,KAAK,eAAe,EAAoB,MAAM,qBAAqB,CAAC;AAGhH,OAAO,KAAK,EAAkB,YAAY,EAAC,MAAM,yBAAyB,CAAC;AAG3E,MAAM,WAAW,yBAAyB;IACxC,4GAA4G;IAC5G,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,eAAe,EACzB,YAAY,EAAE,YAAY,EAC1B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CAoDf"}
+{"version":3,"file":"shapeResolver.d.ts","sourceRoot":"","sources":["../../src/compiler/shapeResolver.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAqC,KAAK,eAAe,EAAoB,MAAM,qBAAqB,CAAC;AAGhH,OAAO,KAAK,EAAkB,YAAY,EAAC,MAAM,yBAAyB,CAAC;AAM3E,OAAO,EAAC,+BAA+B,EAAC,MAAM,sBAAsB,CAAC;AAErE,MAAM,WAAW,yBAAyB;IACxC,4GAA4G;IAC5G,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,eAAe,EACzB,YAAY,EAAE,YAAY,EAC1B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CAoDf"}

package/dist/compiler/shapeResolver.js

@@ -14,12 +14,15 @@
  *   - Existing buffered generation stays byte-for-byte identical when no
  *     streamConfig.shapeCatalogs entries are declared.
  */
-import fs from "node:fs";
 import path from "node:path";
 import { compileCatalog } from "./schemaCompiler.js";
 import { loadWsdl } from "../loader/wsdlLoader.js";
 import { resolveCompilerOptions } from "../config.js";
 import { WsdlCompilationError } from "../util/errors.js";
+import { readLegacyCatalogFile, CatalogError } from "./semanticCatalog.js";
+// Internal faithful counterpart consumes namespace/role roots and the typed reader.
+// Public StreamConfig generation continues to call the legacy adapter below.
+export { prepareResolvedCompilationInput } from "./semanticCatalog.js";
 /**
  * Apply a parsed StreamConfig to a compiled catalog:
  *   1. Verify every opted-in operation's record type is resolvable.
@@ -76,19 +79,14 @@ export async function applyShapeCatalogs(compiled, streamConfig, options = {}) {
 async function loadCompanionCatalog(name, ref, baseDir, compiled) {
     if (ref.catalogFile) {
         const abs = path.resolve(baseDir, ref.catalogFile);
-        let text;
         try {
-            text = fs.readFileSync(abs, "utf-8");
+            return readLegacyCatalogFile(abs);
         }
         catch (err) {
+            if (err instanceof CatalogError)
+                throw err;
             throw new WsdlCompilationError(`Failed to read companion catalog "${name}" at ${abs}: ${err.message}`, { suggestion: `Check that shapeCatalogs.${name}.catalogFile points to an existing catalog.json.` });
         }
-        try {
-            return JSON.parse(text);
-        }
-        catch (err) {
-            throw new WsdlCompilationError(`Companion catalog "${name}" at ${abs} is not valid JSON: ${err.message}`);
-        }
     }
     if (ref.wsdlSource) {
         // Relative paths resolve against baseDir; URLs pass through untouched.

package/dist/compiler/sourceSchemaBinding.d.ts

@@ -0,0 +1,26 @@
+import type { SchemaInput, SchemaInterpretation } from '../loader/schemaInput.js';
+import type { SyntaxSource } from '../loader/orderedSyntax.js';
+import { GraphError } from './canonicalGraph.js';
+import { SemanticError } from './resolveCanonicalGraph.js';
+import type { ResolvedGraph, SemanticLimits } from './resolveCanonicalGraph.js';
+import type { ResourceLimitFailure, SemanticBudget } from './semanticBudget.js';
+export type SourcePreparationFailure = Readonly<{
+    kind: 'source-preparation-failed';
+    stage: 'canonical-build' | 'reference-resolution';
+    category: GraphError['category'] | SemanticError['category'];
+    message: string;
+    source?: SyntaxSource;
+}>;
+export type BoundSourcePreparation = Readonly<{
+    kind: 'prepared';
+    resolved: ResolvedGraph;
+}> | SourcePreparationFailure | ResourceLimitFailure;
+/** Reads only private identity. A copied/forged resolved handle has no binding. */
+export declare function sourceSchemasForResolvedGraph(resolved: ResolvedGraph): readonly SchemaInterpretation[] | undefined;
+/** One issued source snapshot constructs both the immutable graph and its source universe. */
+export declare function prepareBoundSourceGraph(input: SchemaInput, options: Readonly<{
+    budget: SemanticBudget;
+    sourceLimits?: SemanticLimits;
+    accountPreparation?: true;
+}>): BoundSourcePreparation;
+//# sourceMappingURL=sourceSchemaBinding.d.ts.map

package/dist/compiler/sourceSchemaBinding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sourceSchemaBinding.d.ts","sourceRoot":"","sources":["../../src/compiler/sourceSchemaBinding.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,WAAW,EAAE,oBAAoB,EAAC,MAAM,0BAA0B,CAAC;AAChF,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,4BAA4B,CAAC;AAE7D,OAAO,EAAC,UAAU,EAAC,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAwB,aAAa,EAAC,MAAM,4BAA4B,CAAC;AAChF,OAAO,KAAK,EAAC,aAAa,EAAE,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAC9E,OAAO,KAAK,EAAC,oBAAoB,EAAE,cAAc,EAAC,MAAM,qBAAqB,CAAC;AAE9E,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAAC,IAAI,EAAE,2BAA2B,CAAC;IACjF,KAAK,EAAE,iBAAiB,GAAG,sBAAsB,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IAChH,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAC,CAAC,CAAC;AAC3C,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAA;CAAC,CAAC,GAAG,wBAAwB,GAAG,oBAAoB,CAAC;AAG7I,mFAAmF;AACnF,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,oBAAoB,EAAE,GAAG,SAAS,CAElH;AAED,8FAA8F;AAC9F,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,CAAC;IAC5E,MAAM,EAAE,cAAc,CAAC;IAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IAAC,kBAAkB,CAAC,EAAE,IAAI,CAAC;CAClF,CAAC,GAAG,sBAAsB,CAyB1B"}

package/dist/compiler/sourceSchemaBinding.js

@@ -0,0 +1,39 @@
+/** Exact source-built resolved handles; no caller-issued association or validity receipt. */
+import { assertLoadedSchemaInput } from '../loader/schemaInput.js';
+import { buildCanonicalGraph } from './buildCanonicalGraph.js';
+import { GraphError } from './canonicalGraph.js';
+import { resolveCanonicalGraph, SemanticError } from './resolveCanonicalGraph.js';
+const sourceBindings = new WeakMap();
+/** Reads only private identity. A copied/forged resolved handle has no binding. */
+export function sourceSchemasForResolvedGraph(resolved) {
+    return sourceBindings.get(resolved);
+}
+/** One issued source snapshot constructs both the immutable graph and its source universe. */
+export function prepareBoundSourceGraph(input, options) {
+    assertLoadedSchemaInput(input);
+    const budget = options.budget;
+    return budget.guard(() => {
+        // The loader authenticates this exact input handle. Claim its complete
+        // immutable source tree before any build or caller access can intervene.
+        // The shared budget charges the freeze traversal before each field read.
+        const owned = budget.freeze(input);
+        let stage = 'canonical-build';
+        try {
+            const graph = buildCanonicalGraph(owned, { maxNodes: options.sourceLimits?.maxNodes, requestBudget: options.accountPreparation ? budget : undefined });
+            stage = 'reference-resolution';
+            // The fixed resolver deep-freezes its complete result before returning it.
+            // No caller code receives this exact handle before the private association.
+            const resolved = resolveCanonicalGraph(graph, { ...options.sourceLimits, requestBudget: options.accountPreparation ? budget : undefined });
+            budget.chargeWork(6);
+            sourceBindings.set(resolved, owned.schemas);
+            return Object.freeze({ kind: 'prepared', resolved });
+        }
+        catch (error) {
+            if (!(error instanceof GraphError || error instanceof SemanticError))
+                throw error;
+            budget.chargeWork(200 + error.message.length);
+            return Object.freeze({ kind: 'source-preparation-failed', stage, category: error.category,
+                message: error.message, ...(error.source ? { source: error.source } : {}) });
+        }
+    });
+}

package/dist/compiler/structuralCompanions.d.ts

@@ -0,0 +1,16 @@
+import type { CanonicalGraph, NodeId } from "./canonicalGraph.js";
+import type { SemanticLimits } from "./resolveCanonicalGraph.js";
+export type StructuralCompanion = Readonly<{
+    graph: CanonicalGraph;
+    roots: readonly NodeId[];
+}>;
+export type StructuralMerge = Readonly<{
+    graph: CanonicalGraph;
+    copied: readonly NodeId[];
+    deduplicated: readonly NodeId[];
+    metrics: Readonly<{
+        steps: number;
+    }>;
+}>;
+export declare function mergeStructuralCompanions(primary: CanonicalGraph, companions: readonly StructuralCompanion[], limits?: SemanticLimits): StructuralMerge;
+//# sourceMappingURL=structuralCompanions.d.ts.map

package/dist/compiler/structuralCompanions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuralCompanions.d.ts","sourceRoot":"","sources":["../../src/compiler/structuralCompanions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,cAAc,EAA0B,MAAM,EAAC,MAAM,qBAAqB,CAAC;AAGxF,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAI/D,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IAAC,KAAK,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAC,CAAC,CAAC;AAC9F,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,KAAK,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;CACvH,CAAC,CAAC;AAEH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,mBAAmB,EAAE,EAAE,MAAM,GAAE,cAAmB,GAAG,eAAe,CAuI3J"}

package/dist/compiler/structuralCompanions.js

@@ -0,0 +1,232 @@
+/** Required structural closures over one declared graph; no public-symbol renaming. */
+import { deepFreeze, globalId } from "./canonicalGraph.js";
+import { containedNodes, referenceSlots, mapNodeReferences } from "./graphTraversal.js";
+import { referenceTarget, SemanticError, semanticBudget, countSemanticData } from "./resolveCanonicalGraph.js";
+import { semanticGraphRepresentation } from "./catalogProvenance.js";
+import { canonicalJson } from "./catalogErrors.js";
+export function mergeStructuralCompanions(primary, companions, limits = {}) {
+    const budget = semanticBudget(limits);
+    if (primary.nodes.length > budget.maxNodes)
+        throw new SemanticError("resource-limit", `Primary input exceeds ${budget.maxNodes} graph nodes`);
+    const nodes = new Map(primary.nodes.map(n => { budget.step(n); return [n.id, n]; }));
+    const checkSize = () => { if (nodes.size > budget.maxNodes)
+        throw new SemanticError("resource-limit", `Companion graph exceeds ${budget.maxNodes} nodes`); };
+    checkSize();
+    // Bound normalization and provenance copying before recursive serialization allocates.
+    const countData = (value, node) => countSemanticData(value, budget, node);
+    const owned = (root, index) => {
+        const stack = [root.id], seen = new Set(), result = [];
+        while (stack.length) {
+            const id = stack.pop();
+            if (seen.has(id))
+                continue;
+            const node = index.get(id);
+            if (!node)
+                throw new SemanticError("invalid-schema", `Missing owned component ${id}`, root.id, root.context.source);
+            budget.step(node);
+            seen.add(id);
+            result.push(node);
+            for (const child of containedNodes(node)) {
+                budget.step(node);
+                stack.push(child);
+            }
+            for (const slot of referenceSlots(node))
+                if (slot.reference.kind === "local") {
+                    budget.step(node);
+                    stack.push(slot.reference.target);
+                }
+        }
+        return result;
+    };
+    const representation = (root, index) => {
+        const declarations = owned(root, index);
+        countData(declarations, root);
+        return semanticGraphRepresentation({ ...primary, nodes: declarations, globals: [root.id], origins: {}, schemaAnnotations: [], schemaRetained: [], loading: { ...primary.loading, edges: [] } }, { referenceIdentityOnly: true });
+    };
+    const origins = Object.create(null), originKeys = new Map();
+    const addOrigins = (id, values, node) => {
+        const list = origins[id] ??= [], keys = originKeys.get(id) ?? new Set();
+        originKeys.set(id, keys);
+        for (const origin of values) {
+            countData(origin, node);
+            const key = canonicalJson(origin);
+            if (!keys.has(key)) {
+                keys.add(key);
+                list.push(origin);
+            }
+        }
+    };
+    for (const node of primary.nodes) {
+        budget.step(node);
+        addOrigins(node.id, primary.origins[node.id] ?? [], node);
+    }
+    const edges = [...primary.loading.edges], retained = [...primary.schemaRetained], annotations = [...primary.schemaAnnotations];
+    countData([edges, retained, annotations]);
+    const edgeKeys = new Set(edges.map(canonicalJson)), retainedKeys = new Set(retained.map(canonicalJson)), annotationKeys = new Set(annotations.map(canonicalJson));
+    const copied = new Set(), deduplicated = new Set();
+    // Index requested pools before walking, so a cross-companion dependency is
+    // resolved by availability rather than the caller's request order.
+    const providers = new Map();
+    const pools = companions.map((companion, pool) => {
+        budget.step();
+        if (companion.graph.nodes.length > budget.maxNodes)
+            throw new SemanticError("resource-limit", `Companion input exceeds ${budget.maxNodes} graph nodes`);
+        const source = new Map(companion.graph.nodes.map(n => { budget.step(n); return [n.id, n]; }));
+        if (companion.roots.length)
+            for (const node of source.values()) {
+                budget.step(node);
+                if (node.identity.kind !== "global")
+                    continue;
+                const available = providers.get(node.id) ?? [];
+                available.push(pool);
+                providers.set(node.id, available);
+            }
+        return { companion, source, selected: new Set() };
+    });
+    const queue = [];
+    const enqueueAvailable = (id, node) => {
+        for (const pool of providers.get(id) ?? []) {
+            budget.step(node);
+            queue.push({ pool, id });
+        }
+    };
+    pools.forEach(({ companion, source }, pool) => {
+        for (const root of companion.roots) {
+            budget.step();
+            const node = source.get(root);
+            if (!node || node.identity.kind !== "global")
+                throw new SemanticError("invalid-schema", `Companion root must identify a declared global component: ${root}`, root, node?.context.source);
+            queue.push({ pool, id: root });
+        }
+    });
+    for (const node of primary.nodes)
+        for (const { reference } of referenceSlots(node)) {
+            budget.step(node);
+            if (reference.kind === "symbol") {
+                const id = globalId(reference.role, reference.name);
+                if (!nodes.has(id))
+                    enqueueAvailable(id, node);
+            }
+        }
+    while (queue.length) {
+        const { pool, id } = queue.pop(), { source, selected } = pools[pool];
+        if (selected.has(id))
+            continue;
+        const node = source.get(id);
+        if (!node)
+            throw new SemanticError("invalid-schema", `Missing companion component ${id}`, id);
+        budget.step(node);
+        selected.add(id);
+        for (const child of containedNodes(node)) {
+            budget.step(node);
+            queue.push({ pool, id: child });
+        }
+        for (const { reference } of referenceSlots(node)) {
+            budget.step(node);
+            const candidate = reference.kind === "local" ? reference.target : reference.kind === "symbol" ? globalId(reference.role, reference.name) : undefined;
+            if (candidate && source.has(candidate)) {
+                referenceTarget(reference, source, node);
+                queue.push({ pool, id: candidate });
+            }
+            else if (candidate && reference.kind === "symbol" && !nodes.has(candidate) && providers.has(candidate)) {
+                for (const available of providers.get(candidate))
+                    referenceTarget(reference, pools[available].source, node);
+                enqueueAvailable(candidate, node);
+            }
+            else
+                referenceTarget(reference, nodes, node);
+        }
+    }
+    for (const { companion, source, selected } of pools) {
+        const interpretations = new Set(), contexts = new Set(), documents = new Set();
+        for (const id of selected) {
+            const node = source.get(id);
+            for (const origin of companion.graph.origins[id] ?? []) {
+                countData(origin, node);
+                interpretations.add(origin.interpretation);
+                contexts.add(canonicalJson([origin.context.source.uri, origin.context.source.digest, origin.context.effectiveNamespace]));
+                documents.add(canonicalJson([origin.context.source.uri, origin.context.source.digest]));
+            }
+        }
+        const mapping = new Map();
+        for (const id of [...selected].sort((a, b) => { budget.step(); return a < b ? -1 : a > b ? 1 : 0; })) {
+            const root = source.get(id);
+            if (root.identity.kind !== "global")
+                continue;
+            const current = nodes.get(id);
+            if (current) {
+                const a = representation(current, nodes), b = representation(root, source);
+                if (a.structure !== b.structure)
+                    throw new SemanticError("invalid-schema", `Structural companion collision for ${id}; reconcile the original declarations`, id, root.context.source, [current.context.source]);
+                // Equal normalized positions identify corresponding scoped declarations.
+                const positions = new Map([...a.identities].map(([original, normalized]) => [normalized, original]));
+                for (const [original, normalized] of b.identities) {
+                    budget.step(root);
+                    mapping.set(original, positions.get(normalized));
+                }
+                deduplicated.add(id);
+            }
+            else {
+                for (const node of owned(root, source)) {
+                    budget.step(node);
+                    nodes.set(node.id, node);
+                    checkSize();
+                    mapping.set(node.id, node.id);
+                }
+                copied.add(id);
+            }
+        }
+        for (const id of selected) {
+            const target = mapping.get(id), node = source.get(id);
+            if (!target)
+                throw new SemanticError("invalid-schema", "Companion closure lost scoped ownership", id, node.context.source);
+            addOrigins(target, companion.graph.origins[id] ?? [], node);
+        }
+        for (const edge of companion.graph.loading.edges) {
+            budget.step();
+            if (!interpretations.has(edge.from))
+                continue;
+            countData(edge);
+            const key = canonicalJson(edge);
+            if (!edgeKeys.has(key)) {
+                edgeKeys.add(key);
+                edges.push(edge);
+            }
+        }
+        for (const entry of companion.graph.schemaRetained) {
+            budget.step();
+            if (!contexts.has(canonicalJson([entry.context.source.uri, entry.context.source.digest, entry.context.effectiveNamespace])))
+                continue;
+            countData(entry);
+            const key = canonicalJson(entry);
+            if (!retainedKeys.has(key)) {
+                retainedKeys.add(key);
+                retained.push(entry);
+            }
+        }
+        for (const annotation of companion.graph.schemaAnnotations) {
+            budget.step();
+            if (!documents.has(canonicalJson([annotation.source.uri, annotation.source.digest])))
+                continue;
+            countData(annotation);
+            const key = canonicalJson(annotation);
+            if (!annotationKeys.has(key)) {
+                annotationKeys.add(key);
+                annotations.push(annotation);
+            }
+        }
+    }
+    const linked = [...nodes.values()].map(node => {
+        budget.step(node);
+        return mapNodeReferences(node, reference => {
+            budget.step(node);
+            if (reference.kind !== "symbol")
+                return reference;
+            const id = globalId(reference.role, reference.name);
+            if (reference.target !== undefined && reference.target !== id)
+                throw new SemanticError("invalid-schema", "Stored companion reference has a mismatched target", node.id, reference.lexical.context.source);
+            return nodes.has(id) ? { ...reference, target: id } : reference;
+        });
+    }).sort((a, b) => { budget.step(); return a.id < b.id ? -1 : a.id > b.id ? 1 : 0; });
+    return deepFreeze({ graph: { ...primary, nodes: linked, globals: linked.filter(n => n.identity.kind === "global").map(n => n.id).sort(), origins, schemaAnnotations: annotations, schemaRetained: retained, loading: { ...primary.loading, edges } }, copied: [...copied].sort(), deduplicated: [...deduplicated].sort(), metrics: { steps: budget.steps } });
+}

package/dist/compiler/validateSemanticGraph.d.ts

@@ -0,0 +1,5 @@
+import type { CanonicalGraph } from "./canonicalGraph.js";
+export declare function validateSemanticGraph(input: unknown, options?: {
+    maxNodes?: number;
+}): asserts input is CanonicalGraph;
+//# sourceMappingURL=validateSemanticGraph.d.ts.map

package/dist/compiler/validateSemanticGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateSemanticGraph.d.ts","sourceRoot":"","sources":["../../src/compiler/validateSemanticGraph.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,cAAc,EAAmC,MAAM,qBAAqB,CAAC;AAoF1F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAM,GAAG,OAAO,CAAC,KAAK,IAAI,cAAc,CAqLxH"}