@techspokes/typescript-wsdl-client 1.1.4 → 1.1.5

package/dist/compiler/semanticCatalog.d.ts

@@ -0,0 +1,122 @@
+import { GRAPH_MODEL } from "./canonicalGraph.js";
+import type { CanonicalGraph } from "./canonicalGraph.js";
+import { loadSchemaInput } from "../loader/schemaInput.js";
+import type { CompiledCatalog } from "./schemaCompiler.js";
+import type { CompilerOptions } from "../config.js";
+import type { CatalogLimits } from "./catalogErrors.js";
+import type { SemanticLimits } from "./resolveCanonicalGraph.js";
+import type { NodeId } from "./canonicalGraph.js";
+export { CatalogError } from "./catalogErrors.js";
+export declare const CATALOG_FORMAT: 2;
+export type CompilationMode = "legacy" | "faithful";
+export type SemanticCatalog = Readonly<{
+    catalogFormat: typeof CATALOG_FORMAT;
+    model: typeof GRAPH_MODEL;
+    profile: typeof GRAPH_MODEL;
+    graph: CanonicalGraph;
+    semanticFingerprint: string;
+}>;
+export type CatalogReadResult = Readonly<{
+    kind: "legacy";
+    catalog: CompiledCatalog;
+} | {
+    kind: "semantic";
+    catalog: SemanticCatalog;
+} | {
+    kind: "regeneration-required";
+    category: "incompatible-artifact";
+    reason: string;
+    requiredInput: "original-source";
+    command: string;
+}>;
+export declare function createSemanticCatalog(graph: CanonicalGraph, limits?: CatalogLimits): SemanticCatalog;
+export declare function serializeSemanticCatalog(catalog: SemanticCatalog, limits?: CatalogLimits): string;
+export declare function readCatalog(text: string, options?: CatalogLimits & {
+    mode?: CompilationMode;
+}): CatalogReadResult;
+/** Bounded regular-file read; no giant allocation or special-file blocking before format dispatch. */
+export declare function readCatalogFile(file: string, options?: CatalogLimits & {
+    mode?: CompilationMode;
+}): CatalogReadResult;
+export declare function readLegacyCatalogFile(file: string, limits?: CatalogLimits): CompiledCatalog;
+/** Development boundary for the S02 source/catalog matrix; no faithful emitter or activation. */
+export declare function prepareCompilationInput(input: {
+    kind: "source";
+    source: string;
+} | {
+    kind: "catalog";
+    text: string;
+}, options?: {
+    mode?: CompilationMode;
+    limits?: CatalogLimits;
+    compilerOptions?: Partial<CompilerOptions>;
+    loading?: Parameters<typeof loadSchemaInput>[1];
+}): Promise<CatalogReadResult>;
+/** Inspectable transitional view, always derived; it cannot replace the structural graph or feed emitters. */
+export declare function deriveCompatibilityView(graph: CanonicalGraph): {
+    derived: true;
+    model: "xsd10-faithful-v1";
+    symbols: {
+        id: string;
+        kind: "element" | "attribute" | "group" | "attributeGroup" | "particle" | "attributeUse" | "attributeGroupUse" | "attributeWildcard" | "simpleType" | "complexType" | "wsdl";
+        identity: import("./canonicalGraph.js").Identity;
+    }[];
+};
+/** Internal faithful companion dispatch. Regeneration never fabricates missing structure. */
+export declare function prepareResolvedCompilationInput(input: Parameters<typeof prepareCompilationInput>[0] | {
+    kind: "catalog-file";
+    file: string;
+}, options?: Omit<NonNullable<Parameters<typeof prepareCompilationInput>[1]>, "mode"> & {
+    companions?: readonly Readonly<{
+        input: Parameters<typeof prepareCompilationInput>[0] | {
+            kind: "catalog-file";
+            file: string;
+        };
+        roots: readonly NodeId[];
+    }>[];
+    semantics?: SemanticLimits;
+}): Promise<Readonly<{
+    kind: "legacy";
+    catalog: CompiledCatalog;
+}> | Readonly<{
+    kind: "regeneration-required";
+    category: "incompatible-artifact";
+    reason: string;
+    requiredInput: "original-source";
+    command: string;
+}> | {
+    kind: "semantic";
+    catalog: Readonly<{
+        catalogFormat: typeof CATALOG_FORMAT;
+        model: typeof GRAPH_MODEL;
+        profile: typeof GRAPH_MODEL;
+        graph: CanonicalGraph;
+        semanticFingerprint: string;
+    }>;
+    resolved: Readonly<{
+        graph: CanonicalGraph;
+        links: readonly import("./resolveCanonicalGraph.js").ResolvedLink[];
+        metrics: Readonly<{
+            steps: number;
+        }>;
+    }>;
+    composed: Readonly<{
+        resolved: import("./resolveCanonicalGraph.js").ResolvedGraph;
+        types: readonly import("./composeCanonicalGraph.js").ComposedType[];
+        metrics: Readonly<{
+            steps: number;
+        }>;
+    }>;
+    gathering: {
+        inputNodes: number;
+        steps: number;
+    };
+    merge: {
+        copied: readonly string[];
+        deduplicated: readonly string[];
+        metrics: Readonly<{
+            steps: number;
+        }>;
+    };
+}>;
+//# sourceMappingURL=semanticCatalog.d.ts.map

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

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

package/dist/compiler/semanticCatalog.js

@@ -0,0 +1,160 @@
+/** Internal catalog format 2: graph persistence and narrow format/model dispatch. */
+import { closeSync, fstatSync, openSync, readSync, constants } from "node:fs";
+import { GRAPH_MODEL, DEFAULT_GRAPH_NODES, deepFreeze } from "./canonicalGraph.js";
+import { buildCanonicalGraph } from "./buildCanonicalGraph.js";
+import { loadSchemaInput } from "../loader/schemaInput.js";
+import { loadWsdl } from "../loader/wsdlLoader.js";
+import { compileCatalog } from "./schemaCompiler.js";
+import { resolveCompilerOptions } from "../config.js";
+import { CatalogError, DEFAULT_CATALOG_BYTES, canonicalJson, parseCatalogJson, positiveLimit } from "./catalogErrors.js";
+import { artifactGraph, normalizeGraphTables, semanticGraphFingerprint } from "./catalogProvenance.js";
+import { validateSemanticGraph } from "./validateSemanticGraph.js";
+import { mergeStructuralCompanions } from "./structuralCompanions.js";
+import { resolveCanonicalGraph, semanticBudget, countSemanticData, SemanticError } from "./resolveCanonicalGraph.js";
+import { composeCanonicalGraph } from "./composeCanonicalGraph.js";
+export { CatalogError } from "./catalogErrors.js";
+export const CATALOG_FORMAT = 2;
+export function createSemanticCatalog(graph, limits = {}) {
+    const maxNodes = positiveLimit(limits.maxNodes, DEFAULT_GRAPH_NODES, "maxNodes");
+    if (graph.nodes.length > maxNodes)
+        throw new CatalogError("resource-limit", `Catalog graph exceeds ${maxNodes} nodes`);
+    const portable = artifactGraph(graph);
+    validateSemanticGraph(portable, limits);
+    return deepFreeze({ catalogFormat: CATALOG_FORMAT, model: GRAPH_MODEL, profile: GRAPH_MODEL, graph: portable, semanticFingerprint: semanticGraphFingerprint(portable) });
+}
+export function serializeSemanticCatalog(catalog, limits = {}) {
+    const text = canonicalJson(catalog) + "\n";
+    // The writer obeys the same byte/depth/field/reference boundary as the reader.
+    readCatalog(text, { mode: "faithful", ...limits });
+    return text;
+}
+function legacyCatalog(value) {
+    const bad = () => { throw new CatalogError("invalid-schema", "Malformed legacy catalog"); };
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return bad();
+    const v = value;
+    if (!Array.isArray(v.types) || !Array.isArray(v.aliases) || !Array.isArray(v.operations) || !v.options || typeof v.options !== "object" || !v.meta || typeof v.meta !== "object" || typeof v.wsdlTargetNS !== "string" || typeof v.wsdlUri !== "string")
+        return bad();
+    for (const item of [...v.types, ...v.aliases, ...v.operations])
+        if (!item || typeof item !== "object" || typeof item.name !== "string")
+            return bad();
+    // Legacy metadata remains unchanged; this adapter never invents graph structure or rename/options migrations.
+    return value;
+}
+export function readCatalog(text, options = {}) {
+    const mode = options.mode ?? "legacy";
+    if (mode !== "legacy" && mode !== "faithful")
+        throw new CatalogError("incompatible-artifact", "Unknown compilation mode");
+    const parsed = parseCatalogJson(text, options);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new CatalogError("invalid-schema", "Catalog must be an object");
+    const o = parsed;
+    if (!Object.hasOwn(o, "catalogFormat")) {
+        if (["model", "profile", "graph", "bundleFormat", "semanticFingerprint"].some(k => Object.hasOwn(o, k)))
+            throw new CatalogError("incompatible-artifact", "Unrecognized or missing catalog format identifier");
+        const catalog = legacyCatalog(parsed);
+        return mode === "legacy" ? { kind: "legacy", catalog } : { kind: "regeneration-required", category: "incompatible-artifact", reason: "Flattened legacy catalog lacks ordered schema structure; regenerate through the internal faithful source entry", requiredInput: "original-source", command: "prepareCompilationInput({kind: 'source', source: '<original.wsdl>'}, {mode: 'faithful', loading: {policy: {fileRoots: ['<authorized-root>']}}})" };
+    }
+    if (o.catalogFormat !== CATALOG_FORMAT || o.model !== GRAPH_MODEL || o.profile !== GRAPH_MODEL)
+        throw new CatalogError("incompatible-artifact", "Expected catalogFormat 2, model/profile xsd10-faithful-v1", "catalogFormat/model/profile");
+    if (Object.keys(o).some(k => !["catalogFormat", "model", "profile", "graph", "semanticFingerprint"].includes(k)))
+        throw new CatalogError("invalid-schema", "Unknown mandatory catalog field");
+    if (typeof o.semanticFingerprint !== "string" || !/^[a-f0-9]{64}$/.test(o.semanticFingerprint))
+        throw new CatalogError("invalid-schema", "Malformed semantic fingerprint");
+    validateSemanticGraph(o.graph, options);
+    const portable = artifactGraph(o.graph);
+    if (canonicalJson(normalizeGraphTables(o.graph)) !== canonicalJson(portable))
+        throw new CatalogError("invalid-schema", "Catalog contains nonportable retrieval provenance");
+    if (semanticGraphFingerprint(o.graph) !== o.semanticFingerprint)
+        throw new CatalogError("incompatible-artifact", "Catalog semantic fingerprint mismatch");
+    if (mode === "legacy")
+        throw new CatalogError("incompatible-artifact", "Legacy consumer cannot read a structural catalog; regenerate matched legacy artifacts from original source");
+    return { kind: "semantic", catalog: deepFreeze({ ...parsed, graph: portable }) };
+}
+/** Bounded regular-file read; no giant allocation or special-file blocking before format dispatch. */
+export function readCatalogFile(file, options = {}) {
+    const maxBytes = positiveLimit(options.maxBytes, DEFAULT_CATALOG_BYTES, "maxBytes");
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile())
+            throw new CatalogError("invalid-schema", "Catalog input must be a regular file");
+        if (stat.size > maxBytes)
+            throw new CatalogError("resource-limit", `Catalog exceeds ${maxBytes} bytes`);
+        const chunks = [], chunk = Buffer.alloc(Math.min(64 * 1024, maxBytes + 1));
+        let total = 0, count;
+        while ((count = readSync(fd, chunk, 0, Math.min(chunk.length, maxBytes + 1 - total), null)) > 0) {
+            total += count;
+            if (total > maxBytes)
+                throw new CatalogError("resource-limit", `Catalog exceeds ${maxBytes} bytes`);
+            chunks.push(Buffer.from(chunk.subarray(0, count)));
+        }
+        let text;
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+        }
+        catch {
+            throw new CatalogError("invalid-schema", "Catalog is not valid UTF-8");
+        }
+        return readCatalog(text, options);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function readLegacyCatalogFile(file, limits = {}) {
+    const result = readCatalogFile(file, { ...limits, mode: "legacy" });
+    if (result.kind !== "legacy")
+        throw new CatalogError("incompatible-artifact", "Expected legacy catalog");
+    return result.catalog;
+}
+/** Development boundary for the S02 source/catalog matrix; no faithful emitter or activation. */
+export async function prepareCompilationInput(input, options = {}) {
+    const mode = options.mode ?? "legacy";
+    if (input.kind === "catalog")
+        return readCatalog(input.text, { mode, ...options.limits });
+    if (mode === "legacy")
+        return { kind: "legacy", catalog: compileCatalog(await loadWsdl(input.source), resolveCompilerOptions(options.compilerOptions ?? {}, { wsdl: input.source, out: "" })) };
+    if (mode !== "faithful")
+        throw new CatalogError("incompatible-artifact", "Unknown compilation mode");
+    const loaded = await loadSchemaInput(input.source, options.loading ?? { policy: {} });
+    return { kind: "semantic", catalog: createSemanticCatalog(buildCanonicalGraph(loaded, { maxNodes: options.limits?.maxNodes }), options.limits) };
+}
+/** Inspectable transitional view, always derived; it cannot replace the structural graph or feed emitters. */
+export function deriveCompatibilityView(graph) {
+    return deepFreeze({ derived: true, model: graph.model, symbols: graph.nodes.filter(n => n.identity.kind === "global").map(n => ({ id: n.id, kind: n.kind, identity: n.identity })).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0) });
+}
+/** Internal faithful companion dispatch. Regeneration never fabricates missing structure. */
+export async function prepareResolvedCompilationInput(input, options = {}) {
+    const gathering = semanticBudget(options.semantics), limits = { ...options.limits, maxNodes: Math.min(options.limits?.maxNodes ?? gathering.maxNodes, gathering.maxNodes) };
+    const read = (source) => source.kind === "catalog-file" ? readCatalogFile(source.file, { mode: "faithful", ...limits }) : prepareCompilationInput(source, { ...options, limits, mode: "faithful" });
+    let inputNodes = 0;
+    const retain = (catalog) => {
+        inputNodes += catalog.graph.nodes.length;
+        if (inputNodes > gathering.maxNodes)
+            throw new SemanticError("resource-limit", `Companion gathering exceeds ${gathering.maxNodes} aggregate input nodes`);
+        countSemanticData(catalog.graph, gathering);
+    };
+    const primary = await read(input);
+    if (primary.kind !== "semantic")
+        return primary;
+    retain(primary.catalog);
+    const companions = [];
+    for (const request of options.companions ?? []) {
+        gathering.step();
+        countSemanticData(request.roots, gathering);
+        // No requested root means no file read, source loading or unrelated component copy.
+        if (!request.roots.length)
+            continue;
+        const companion = await read(request.input);
+        if (companion.kind !== "semantic")
+            return companion;
+        retain(companion.catalog);
+        companions.push({ graph: companion.catalog.graph, roots: request.roots });
+    }
+    const merge = mergeStructuralCompanions(primary.catalog.graph, companions, options.semantics);
+    const catalog = createSemanticCatalog(merge.graph, options.limits);
+    const resolved = resolveCanonicalGraph(catalog.graph, options.semantics);
+    const composed = composeCanonicalGraph(resolved, options.semantics);
+    return deepFreeze({ kind: "semantic", catalog, resolved, composed, gathering: { inputNodes, steps: gathering.steps }, merge: { copied: merge.copied, deduplicated: merge.deduplicated, metrics: merge.metrics } });
+}

package/dist/compiler/semanticContext.d.ts

@@ -0,0 +1,172 @@
+/** Internal structural contexts. Preparation never certifies actual or hypothetical XSD legality. */
+import { GRAPH_MODEL } from './canonicalGraph.js';
+import type { CanonicalGraph, ComplexTypeNode, GraphNode, Identity, NodeId, Reference } from './canonicalGraph.js';
+import type { ResolvedGraph } from './resolveCanonicalGraph.js';
+import type { ExpandedName } from '../loader/orderedSyntax.js';
+import type { ResourceLimitFailure, SemanticBudget } from './semanticBudget.js';
+import type { OriginalUrWildcardHandle, RawComplexTypeProperties } from './re01TypeProperties.js';
+import type { RawSimpleTypeProperties } from './schemaSimpleTypeProperties.js';
+import type { RawElementProperties } from './schemaElementProperties.js';
+import type { RawAttributeGroupProperties } from './schemaAttributeGroupProperties.js';
+import type { SchemaNotationProperties } from './schemaNotationProperties.js';
+import type { OriginalGeneratedScalarReference, SemanticTypeReference } from './semanticTypeReference.js';
+import type { RawAttributeProperties } from './schemaAttributeProperties.js';
+import type { RawParticleWildcardProperties } from './schemaParticleWildcardProperties.js';
+import type { OriginalIdentityConstraintRegistry } from './schemaIdentityConstraints.js';
+export declare const SEMANTIC_CONTEXT_CONTRACT: "RE01-domain-boundary-v1";
+export type ContextLookup = Readonly<{
+    kind: 'found';
+    node: GraphNode;
+} | {
+    kind: 'missing' | 'outside-context';
+    id: NodeId;
+}>;
+export type ContextResolution = ContextLookup | Readonly<{
+    kind: 'builtin';
+    name: ExpandedName;
+}>;
+export type SemanticReferenceSlot = Readonly<{
+    path: string;
+    reference: SemanticTypeReference;
+}>;
+export type ContextScalarSlotLookup = Readonly<{
+    kind: 'found';
+    slot: OriginalGeneratedScalarReference;
+} | {
+    kind: 'missing' | 'outside-context';
+    slot: OriginalGeneratedScalarReference;
+}>;
+export type ContextNotationLookup = Readonly<{
+    kind: 'found';
+    properties: SchemaNotationProperties;
+    origin: 'original' | 'addition';
+} | {
+    kind: 'missing' | 'outside-context';
+    name: ExpandedName;
+} | {
+    kind: 'unresolved';
+    name: ExpandedName;
+    rule: 'notation-source-universe' | 'notation-active-membership' | 'notation-original-properties';
+}>;
+export type SemanticContext = Readonly<{
+    contextId: string;
+    profileVersion: typeof GRAPH_MODEL;
+    contractVersion: typeof SEMANTIC_CONTEXT_CONTRACT;
+    kind: 'actual' | 'candidate';
+    acceptance: 'structural-only';
+    membership: 'complete-actual-plus-additions' | 'structural-subset';
+    budget: SemanticBudget;
+    members: readonly NodeId[];
+    scalarSlots: readonly OriginalGeneratedScalarReference[];
+    scalarSlotMembership: 'complete-original' | 'structural-subset';
+    lookupScalarSlot(reference: OriginalGeneratedScalarReference): ContextScalarSlotLookup;
+    /** Separate NOTATION symbol space; no persisted GraphNode role is introduced. */
+    notationMembers: readonly ExpandedName[];
+    notationMembership: 'complete-original-plus-additions' | 'structural-subset';
+    notationUniverse: 'source-bound' | 'retained-only';
+    lookupNotation(name: ExpandedName): ContextNotationLookup;
+    /** Private SOURCE universe, distinct from graph/TYPE membership and FULL owners. */
+    originalIdentityConstraints(): OriginalIdentityConstraintRegistry;
+    lookup(id: NodeId): ContextLookup;
+    /** Owns immutable selector data only; every resolution still checks current membership. */
+    ownTypeReference(reference: SemanticTypeReference): SemanticTypeReference;
+    resolve(reference: Reference): ContextResolution;
+    sourceNode(id: NodeId): GraphNode | undefined;
+    originalSourceComponentAbsent(id: NodeId): boolean;
+    /** Eligibility for reading retained original properties, never a validity receipt. */
+    originalComplexPropertySource(id: NodeId): ComplexTypeNode | undefined;
+    /** Actual source-mapping eligibility only, including owners later rewritten in H. */
+    originalComplexContentSource(id: NodeId): ComplexTypeNode | undefined;
+    /** Original semantic incidences only; undefined keeps the explicit child list. */
+    originalCompositorChildren(id: NodeId): readonly NodeId[] | undefined;
+    /** Authenticated unchanged SOURCE leaves, outside ordinary component membership. */
+    originalUrWildcards(): readonly OriginalUrWildcardHandle[];
+    originalUrWildcard(id: NodeId): OriginalUrWildcardHandle | undefined;
+    /** Original source operand interpretation, with the same request budget. */
+    originalContext(): SemanticContext;
+    /** Original schema syntax evidence, not implicit hypothetical symbol membership. */
+    sourceSchemaRetained(): CanonicalGraph['schemaRetained'];
+    /** Immutable supplied data; never an actual mapping or local-validity receipt. */
+    rawTypeProperties(id: NodeId): RawComplexTypeProperties | undefined;
+    rawSimpleTypeProperties(id: NodeId): RawSimpleTypeProperties | undefined;
+    rawElementProperties(id: NodeId): RawElementProperties | undefined;
+    rawAttributeProperties(id: NodeId): RawAttributeProperties | undefined;
+    rawAttributeGroupProperties(id: NodeId): RawAttributeGroupProperties | undefined;
+    rawParticleWildcardProperties(id: NodeId): RawParticleWildcardProperties | undefined;
+    /** Checked accessors throw SemanticContextAccessError for an inactive/missing owner. */
+    references(id: NodeId): readonly SemanticReferenceSlot[];
+    owner(id: NodeId): NodeId | undefined;
+    incomingAffiliates(id: NodeId): readonly NodeId[];
+}>;
+export type SemanticCandidateDelta = Readonly<{
+    key: string;
+    /** Explicit complete membership, including helper IDs and any replaced endpoint. */
+    active: readonly NodeId[];
+    additions?: readonly GraphNode[];
+    endpoint?: ComplexTypeNode;
+    rawTypes?: readonly RawComplexTypeProperties[];
+    rawSimpleTypes?: readonly RawSimpleTypeProperties[];
+    rawElements?: readonly RawElementProperties[];
+    rawAttributes?: readonly RawAttributeProperties[];
+    /** Independent scalar component membership; omission inherits the parent. */
+    scalarSlots?: readonly OriginalGeneratedScalarReference[];
+    rawAttributeGroups?: readonly RawAttributeGroupProperties[];
+    /** Complete abstract properties, admitted only with the particle's genuine first birth. */
+    rawParticleWildcards?: readonly RawParticleWildcardProperties[];
+    /** Borrow unchanged native SOURCE UR leaves; omission inherits the installed selections. */
+    originalUrWildcards?: readonly OriginalUrWildcardHandle[];
+    /** Omission inherits the parent; an explicit selection must include every new addition. */
+    notations?: Readonly<{
+        active: readonly ExpandedName[];
+        additions?: readonly SchemaNotationProperties[];
+    }>;
+}>;
+export type ContextFailure = Readonly<{
+    kind: 'input-error' | 'candidate-rejected';
+    code: 'identity' | 'missing' | 'outside-context' | 'reference' | 'cycle' | 'endpoint' | 'representation';
+    component?: NodeId;
+}>;
+export type CandidatePreparation = Readonly<{
+    kind: 'prepared';
+    context: SemanticContext;
+}> | ContextFailure | ResourceLimitFailure;
+export type SemanticRequest = Readonly<{
+    graph: CanonicalGraph;
+    actual: SemanticContext;
+    budget: SemanticBudget;
+    candidate(delta: SemanticCandidateDelta): CandidatePreparation;
+}>;
+export type SemanticPreparation = Readonly<{
+    kind: 'prepared';
+    request: SemanticRequest;
+}> | ContextFailure | ResourceLimitFailure;
+/** Full stored-tuple lookup, independent of ID spelling and active membership.
+ * Each caller retains its own active-only or any-stored collision policy.
+ */
+export declare function storedIdentityOccupant(context: SemanticContext, identity: Identity): NodeId | undefined;
+export declare function isSemanticCandidateOf(parent: SemanticContext, child: SemanticContext): boolean;
+/** Genuine handles must also have been prepared by the same request. */
+export declare function contextsShareRequest(a: SemanticContext, b: SemanticContext): boolean;
+export type SemanticGraphMetadata = Omit<CanonicalGraph, 'nodes' | 'globals'>;
+/** Borrowed original metadata only; never projects or indexes active members. */
+export declare function semanticContextGraphMetadata(context: SemanticContext): SemanticGraphMetadata;
+/** Persistent candidate overlay with the original request's source universe and budget. */
+export declare function forkSemanticCandidate(parent: SemanticContext, delta: SemanticCandidateDelta): CandidatePreparation;
+/** Structural active-node projection; does not authenticate a persisted source catalog. */
+export declare function graphForSemanticContext(context: SemanticContext): CanonicalGraph;
+/** Runtime identity, not a caller-supplied authority string or a copied property brand. */
+export declare function assertSemanticContext(context: SemanticContext): void;
+export declare class SemanticContextAccessError extends Error {
+    readonly code: 'missing' | 'outside-context' | 'reference';
+    readonly component?: NodeId | undefined;
+    constructor(code: 'missing' | 'outside-context' | 'reference', component?: NodeId | undefined);
+}
+/**
+ * The resolved input is a structural source entry, not a schema-validity receipt.
+ * Source/loader/catalog costs precede this adapter and retain their existing budgets.
+ * This request owns snapshotting, indexes, deltas and all subsequent consumer work.
+ */
+export declare function prepareSemanticRequest(resolved: ResolvedGraph, options?: Readonly<{
+    budget?: SemanticBudget;
+}>): SemanticPreparation;
+//# sourceMappingURL=semanticContext.d.ts.map

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

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