@intentius/chant 0.124.13 → 0.124.14

package/dist/build.js

@@ -0,0 +1,668 @@
+import { getProvenance } from "./provenance.js";
+import { foldProvenanceOfEntities } from "./fold-provenance.js";
+import { DiscoveryError, BuildError as BuildErrorClass } from "./errors.js";
+import { LexiconOutput, isLexiconOutput } from "./lexicon-output.js";
+import { isSecretDeclaration } from "./secret-provenance.js";
+import { splitReceiptEntities } from "./effect-receipt.js";
+import { isScenario } from "./lifecycle/scenario.js";
+import { isOpEntity } from "./op/resource.js";
+import { isAttrRefLike } from "./utils.js";
+import { isChildProject } from "./child-project.js";
+import { discover } from "./discovery/index.js";
+import { decodeEntitySet } from "./discovery/entity-wire.js";
+import { buildDependencyGraph } from "./discovery/graph.js";
+import { topologicalSort } from "./sort.js";
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Compute the cross-stack apply-ordering graph from resolved entities. Edges are
+ * inferred from cross-lexicon attribute references (a resource in lexicon A
+ * referencing an attribute of a resource in lexicon B ⇒ A depends on B). Returns
+ * the edge set plus a topological order, parallel-safe waves, and any cycles.
+ */
+/**
+ * Is this entity a member of a lexicon stack?
+ *
+ * Four kinds are not, and every one of them is serializer-neutral: a
+ * `LexiconOutput` is collected separately, a secret provenance declaration
+ * (#1828) and a plan scenario (#1292) are data lint and the CLI read off the
+ * entity map, and an Op (#2118) builds to its own `op.json` rather than
+ * through a lexicon serializer.
+ *
+ * {@link partitionByLexicon} has skipped all four since each landed, and
+ * {@link computeStackGraph}'s walk did not — so an entity with no `lexicon`
+ * (a `LexiconOutput`) entered `edges`, `order` and `waves` as `undefined`
+ * while `nodes`, built from the partition, could never contain it (#2480).
+ * One predicate for both sites, so they cannot drift apart again.
+ */
+export function isStackMember(entity) {
+    return (!isLexiconOutput(entity) &&
+        !isSecretDeclaration(entity) &&
+        !isScenario(entity) &&
+        !isOpEntity(entity));
+}
+export function computeStackGraph(entities, lexiconNames) {
+    const edges = [];
+    const edgeSet = new Set();
+    const addEdge = (from, to) => {
+        // A structural guard, not a defensive one: `nodes` comes from the
+        // partition, so an endpoint the partition would have dropped can never be
+        // a legitimate member of this graph (#2480).
+        if (typeof from !== "string" || typeof to !== "string")
+            return;
+        if (from === to)
+            return;
+        const key = `${from}\0${to}`;
+        if (edgeSet.has(key))
+            return;
+        edgeSet.add(key);
+        edges.push({ from, to });
+    };
+    const walk = (value, consumer, visited) => {
+        if (value === null || value === undefined || typeof value !== "object")
+            return;
+        if (visited.has(value))
+            return;
+        visited.add(value);
+        // Duck-type, not `instanceof` (chant #1137): a lexicon built against a
+        // separate copy of `@intentius/chant` produces AttrRefs that fail
+        // `instanceof AttrRef` here but carry the same shape. Without this, a
+        // real cross-stack dependency silently falls through to the generic
+        // object walk below instead of producing an edge, which can misorder —
+        // or entirely drop — the apply order this graph exists to compute.
+        if (isAttrRefLike(value)) {
+            const parent = value.parent.deref();
+            const producer = parent ? parent.lexicon : undefined;
+            if (typeof producer === "string" && producer !== consumer)
+                addEdge(consumer, producer);
+            return;
+        }
+        if (isLexiconOutput(value))
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                walk(item, consumer, visited);
+            return;
+        }
+        for (const val of Object.values(value))
+            walk(val, consumer, visited);
+    };
+    for (const [, entity] of entities) {
+        // #2480: the same four kinds `partitionByLexicon` drops. Walking one as a
+        // consumer takes its absent `lexicon` as the edge's `from`.
+        if (!isStackMember(entity))
+            continue;
+        const consumer = entity.lexicon;
+        const visited = new Set();
+        for (const val of Object.values(entity)) {
+            walk(val, consumer, visited);
+        }
+        if ("props" in entity && typeof entity.props === "object" && entity.props !== null) {
+            walk(entity.props, consumer, visited);
+        }
+    }
+    // Dependency map: node → producers it depends on.
+    const nodes = lexiconNames.length
+        ? [...lexiconNames]
+        : // The same predicate, rather than the partial copy of it this branch
+            // carried: it filtered secrets and scenarios but not outputs or Ops, so
+            // it could mint a node the partition would have dropped (#2480).
+            [...new Set([...entities.values()].filter(isStackMember).map((e) => e.lexicon))];
+    const deps = new Map();
+    for (const n of nodes)
+        deps.set(n, new Set());
+    for (const { from, to } of edges) {
+        if (!deps.has(from))
+            deps.set(from, new Set());
+        if (!deps.has(to))
+            deps.set(to, new Set());
+        deps.get(from).add(to);
+    }
+    // Kahn layering: a node is ready once every producer it depends on is placed.
+    const remaining = new Set(deps.keys());
+    const waves = [];
+    const order = [];
+    while (remaining.size > 0) {
+        const wave = [...remaining]
+            .filter((n) => [...deps.get(n)].every((d) => !remaining.has(d)))
+            .sort();
+        if (wave.length === 0)
+            break; // remaining nodes form a cycle
+        for (const n of wave) {
+            remaining.delete(n);
+            order.push(n);
+        }
+        waves.push(wave);
+    }
+    const cycles = remaining.size > 0 ? [[...remaining].sort()] : [];
+    edges.sort((a, b) => `${a.from}\0${a.to}`.localeCompare(`${b.from}\0${b.to}`));
+    return { nodes: [...nodes].sort(), edges, order, waves, cycles };
+}
+/**
+ * Partitions entities by their lexicon field.
+ * Property-kind Declarables are included in the same partition as their parent
+ * (they get inlined during serialization).
+ *
+ * @param entities - Map of entity name to Declarable
+ * @returns Map of lexicon name to Map of entity name to Declarable
+ */
+export function partitionByLexicon(entities) {
+    const partitions = new Map();
+    for (const [name, entity] of entities) {
+        // The four serializer-neutral kinds, each explained on {@link isStackMember}:
+        // a LexiconOutput is collected separately, and a secret declaration
+        // (#1828), a plan scenario (#1292) and an Op (#2118) are read off the
+        // entity map rather than routed through a lexicon serializer. Keeping them
+        // out of every partition is what stops a "No serializer found" warning
+        // firing for a pseudo-lexicon.
+        if (!isStackMember(entity))
+            continue;
+        const lexicon = entity.lexicon;
+        if (!partitions.has(lexicon)) {
+            partitions.set(lexicon, new Map());
+        }
+        partitions.get(lexicon).set(name, entity);
+    }
+    return partitions;
+}
+/**
+ * Collect LexiconOutput instances from all entity property trees.
+ * Walks entity properties recursively to find LexiconOutput values.
+ */
+export function collectLexiconOutputs(entities) {
+    const outputs = [];
+    const visited = new Set();
+    function walk(value) {
+        if (value === null || value === undefined || typeof value !== "object") {
+            return;
+        }
+        if (visited.has(value))
+            return;
+        visited.add(value);
+        if (isLexiconOutput(value)) {
+            outputs.push(value);
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                walk(item);
+            }
+            return;
+        }
+        for (const val of Object.values(value)) {
+            walk(val);
+        }
+    }
+    for (const [name, entity] of entities) {
+        if (isLexiconOutput(entity)) {
+            const lexiconOutput = entity;
+            // A literal-valued output (chant #1121) has no source entity at all —
+            // it isn't a reference to anything, so it must not fall back to the
+            // output's OWN map key the way an AttrRef whose parent didn't resolve
+            // would. Leaving `sourceEntity` empty keeps `getOutputValue()`'s
+            // (never-reached, for a literal) `Fn::GetAtt` fallback from ever being
+            // handed a bogus source, and keeps consumers that read `sourceEntity`
+            // directly (e.g. `graph-ir.ts`'s cross-stack export, the build
+            // manifest) from reporting the output as its own source.
+            if (lexiconOutput._literalValue === null) {
+                // Resolve source entity name from the WeakRef parent identity
+                const parent = lexiconOutput._sourceParent?.deref();
+                let sourceName = name;
+                if (parent) {
+                    for (const [entityName, e] of entities) {
+                        if (e === parent) {
+                            sourceName = entityName;
+                            break;
+                        }
+                    }
+                }
+                lexiconOutput._setSourceEntity(sourceName);
+            }
+            outputs.push(lexiconOutput);
+            continue;
+        }
+        if ("props" in entity && typeof entity.props === "object" && entity.props !== null) {
+            // Set source entity name for any LexiconOutputs found in props
+            const prevLength = outputs.length;
+            walk(entity.props);
+            for (let i = prevLength; i < outputs.length; i++) {
+                // Same #1121 guard as above — a literal has no source entity to name.
+                if (!outputs[i].sourceEntity && outputs[i]._literalValue === null) {
+                    outputs[i]._setSourceEntity(name);
+                }
+            }
+        }
+    }
+    return outputs;
+}
+/**
+ * Detect cross-lexicon AttrRefs by walking each entity's property tree.
+ * For each AttrRef whose parent entity belongs to a different lexicon than
+ * the consuming entity, auto-create a LexiconOutput.
+ *
+ * @param entities - Map of entity name to Declarable
+ * @returns Array of auto-detected LexiconOutput instances
+ */
+export function detectCrossLexiconRefs(entities) {
+    const outputs = [];
+    // Track by "sourceEntityName_attribute" to avoid duplicates
+    const seen = new Set();
+    // Build a reverse lookup: object identity -> entity name
+    const objectToName = new Map();
+    for (const [name, entity] of entities) {
+        objectToName.set(entity, name);
+    }
+    function walk(value, consumingLexicon, visited) {
+        if (value === null || value === undefined || typeof value !== "object") {
+            return;
+        }
+        if (visited.has(value))
+            return;
+        visited.add(value);
+        // Duck-type, not `instanceof` (chant #1137): a lexicon built against a
+        // separate copy of `@intentius/chant` produces AttrRefs that fail
+        // `instanceof AttrRef` here but carry the same shape. Without this, a
+        // real cross-lexicon reference silently falls through to the generic
+        // object walk below instead of auto-creating a `LexiconOutput`, and the
+        // whole `Outputs` entry for it vanishes (same failure shape as #1122).
+        if (isAttrRefLike(value)) {
+            const parent = value.parent.deref();
+            if (!parent)
+                return;
+            const parentLexicon = parent.lexicon;
+            if (typeof parentLexicon !== "string")
+                return;
+            if (parentLexicon !== consumingLexicon) {
+                // Find the parent's entity name
+                const parentName = objectToName.get(parent);
+                if (!parentName)
+                    return;
+                const key = `${parentName}_${value.attribute}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    outputs.push(LexiconOutput.auto(value, parentName));
+                }
+            }
+            return;
+        }
+        // Skip LexiconOutput instances — these are explicit outputs
+        if (isLexiconOutput(value))
+            return;
+        // Do not descend into a whole resource entity (e.g. `Ref(bucket)` embeds
+        // the resource object). Every resource instance carries a latent AttrRef
+        // for *every* attribute in its spec (see runtime.ts) — most are never
+        // referenced and, for config-gated attributes (S3 `WebsiteURL`,
+        // `MetadataConfiguration.*`), don't exist at deploy time unless the
+        // matching config block is set. Harvesting those as cross-lexicon outputs
+        // emits `Fn::GetAtt` outputs for nonexistent attributes, which real
+        // CloudFormation rejects (#959). Only an explicitly-accessed attribute
+        // (a standalone AttrRef value, handled above) should produce an output.
+        if (objectToName.has(value))
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                walk(item, consumingLexicon, visited);
+            }
+            return;
+        }
+        for (const val of Object.values(value)) {
+            walk(val, consumingLexicon, visited);
+        }
+    }
+    for (const [, entity] of entities) {
+        const visited = new Set();
+        const consumingLexicon = entity.lexicon;
+        // Walk entity-level properties (AttrRefs could be direct properties)
+        for (const val of Object.values(entity)) {
+            walk(val, consumingLexicon, visited);
+        }
+        // Walk props if present
+        if ("props" in entity &&
+            typeof entity.props === "object" &&
+            entity.props !== null) {
+            walk(entity.props, consumingLexicon, visited);
+        }
+    }
+    return outputs;
+}
+/**
+ * Compute deploy order: source lexicons before consuming lexicons.
+ */
+function computeDeployOrder(lexiconNames, lexiconOutputs) {
+    // Build a dependency graph: consuming lexicons depend on source lexicons
+    const deps = new Map();
+    for (const name of lexiconNames) {
+        deps.set(name, new Set());
+    }
+    for (const output of lexiconOutputs) {
+        // All lexicons other than the source lexicon implicitly depend on it
+        for (const name of lexiconNames) {
+            if (name !== output.sourceLexicon) {
+                deps.get(name)?.add(output.sourceLexicon);
+            }
+        }
+    }
+    // Simple topological sort for deploy order
+    const sorted = [];
+    const visited = new Set();
+    const visiting = new Set();
+    function visit(name) {
+        if (visited.has(name))
+            return;
+        if (visiting.has(name))
+            return; // cycle, just skip
+        visiting.add(name);
+        for (const dep of deps.get(name) ?? []) {
+            visit(dep);
+        }
+        visiting.delete(name);
+        visited.add(name);
+        sorted.push(name);
+    }
+    for (const name of lexiconNames) {
+        visit(name);
+    }
+    return sorted;
+}
+/**
+ * Generate the build manifest
+ */
+function generateManifest(lexiconNames, lexiconOutputs, entities) {
+    const outputsRecord = {};
+    for (const output of lexiconOutputs) {
+        outputsRecord[output.outputName] = {
+            source: output.sourceLexicon,
+            entity: output.sourceEntity,
+            attribute: output.sourceAttribute ?? "",
+        };
+    }
+    return {
+        lexicons: lexiconNames,
+        outputs: outputsRecord,
+        deployOrder: computeDeployOrder(lexiconNames, lexiconOutputs),
+        stackGraph: computeStackGraph(entities, lexiconNames),
+    };
+}
+/** The directory a build discovered from, for build-root contributors; undefined when the build's path is not one (an entity-set JSON's label). */
+function sourceDirOf(path) {
+    try {
+        return statSync(path).isDirectory() ? resolve(path) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Run each build-root contributor (#1548 piece 3) and merge its rendered
+ * entities into `entities`, in place. THE one merge implementation — `build()`
+ * uses it for step 4b, and the graph handler's discover-based paths reuse it
+ * so a rendered kustomize root joins the graphed entity set under exactly the
+ * rules the build applies (#1626):
+ *
+ * - a contributed name colliding with an existing entity is an error, never a
+ *   silent overwrite;
+ * - a contributor that throws becomes an error carrying its message (the k8s
+ *   hook's missing-binary refusal names the binaries), not a stack trace.
+ *
+ * Errors come back as plain messages; each caller wraps them in its own error
+ * vocabulary (`BuildErrorClass` in `build()`, the CLI's `formatError` on the
+ * graph paths).
+ */
+export async function mergeBuildRootEntities(entities, contributors, sourceDir) {
+    const warnings = [];
+    const errors = [];
+    for (const contribute of contributors) {
+        try {
+            // The discovered set, read-only, so a contributor can react to what the
+            // project DECLARED (a committed-encrypted `declareSecret()` naming a
+            // ciphertext file to resolve). Contributors run in order, so this also
+            // carries what earlier contributors added; the merge below is still the
+            // only writer, which is what keeps the collision refusal meaningful.
+            const contribution = await contribute({ entities, ...(sourceDir !== undefined ? { sourceDir } : {}) });
+            warnings.push(...(contribution.warnings ?? []));
+            for (const [name, entity] of contribution.entities) {
+                if (entities.has(name)) {
+                    errors.push(`Build-root entity "${name}" collides with a discovered entity of the same name`);
+                    continue;
+                }
+                entities.set(name, entity);
+            }
+        }
+        catch (error) {
+            errors.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return { warnings, errors };
+}
+/**
+ * Builds a lexicon specification by discovering entities, sorting them
+ * topologically, and serializing them using the lexicon serializers.
+ *
+ * @param path - The directory path containing the specification files
+ * @param serializers - The serializers to use for serialization
+ * @returns BuildResult with outputs, entities, warnings, and errors
+ */
+export async function build(path, serializers, parentBuildStack, options) {
+    // Step 1: Discover entities and dependencies
+    const discoveryResult = await discover(path, {
+        fold: options?.fold,
+        intrinsics: options?.intrinsics,
+        lexicons: options?.lexicons,
+        sandbox: options?.sandbox,
+        executing: options?.executing,
+        buildParams: options?.buildParams,
+    });
+    return buildFromDiscoveryResult(discoveryResult, path, serializers, parentBuildStack, options);
+}
+/**
+ * chant #1045 (Phase 1) — build from a discovery result produced OUTSIDE the
+ * normal `discover(path)` call, i.e. decoded from {@link DiscoveredEntitiesJson}
+ * (see {@link buildFromEntitiesJson}). Everything from here on (topological
+ * sort, recursive child-project builds, partitioning, output detection,
+ * serialization, manifest) is exactly what `build()` already does after its
+ * own `discover()` call — extracted so the JSON path reuses it verbatim
+ * instead of forking it.
+ *
+ * @param resolvedPathForChildStack - Used only to seed the circular-nested-
+ *   stack detection (`buildStack`); the JSON path has no single directory a
+ *   decoded entity set came from, so callers without one may pass any stable
+ *   label (child projects aren't supported by the JSON boundary yet — see
+ *   `discovery/entity-wire.ts` — so this is inert for that path today).
+ */
+async function buildFromDiscoveryResult(discoveryResult, resolvedPathForChildStack, serializers, parentBuildStack, options) {
+    const warnings = [];
+    const errors = [];
+    // Collect discovery errors
+    errors.push(...discoveryResult.errors);
+    // Step 2: Convert Map<string, Set<string>> to Record<string, string[]> for topologicalSort
+    const dependenciesRecord = {};
+    for (const [entityName, deps] of discoveryResult.dependencies) {
+        dependenciesRecord[entityName] = Array.from(deps);
+    }
+    // Step 3: Perform topological sort
+    try {
+        topologicalSort(dependenciesRecord);
+    }
+    catch (error) {
+        // BuildError from cycle detection
+        if (error instanceof Error && error.name === "BuildError") {
+            errors.push(error);
+        }
+        else {
+            // Unexpected error
+            errors.push(new BuildErrorClass("", error instanceof Error ? error.message : String(error)));
+        }
+    }
+    // Step 4: Recursively build child projects
+    const resolvedPath = resolve(resolvedPathForChildStack);
+    const buildStack = parentBuildStack
+        ? new Set(parentBuildStack)
+        : new Set();
+    buildStack.add(resolvedPath);
+    for (const [name, entity] of discoveryResult.entities) {
+        if (isChildProject(entity)) {
+            const childPath = resolve(entity.projectPath);
+            if (buildStack.has(childPath)) {
+                errors.push(new BuildErrorClass(childPath, `Circular nested stack: ${[...buildStack].join(" → ")} → ${childPath}`));
+                continue;
+            }
+            const childResult = await build(childPath, serializers, buildStack, options);
+            entity.buildResult = childResult;
+            if (childResult.errors.length > 0) {
+                for (const err of childResult.errors) {
+                    errors.push(err);
+                }
+            }
+        }
+    }
+    // Step 4b (#1548 piece 3): lexicon-contributed build roots — rendered
+    // non-source roots (kustomize dirs) joining the entity set before
+    // partitioning, so everything downstream (serialization with ownership
+    // stamping, post-synth checks, observation) treats them as declared.
+    // Top-level build only: nested child builds receive the same options
+    // object, and re-running the contributors there would duplicate every
+    // contributed entity once per child.
+    if (!parentBuildStack && options?.buildRoots) {
+        const merged = await mergeBuildRootEntities(discoveryResult.entities, options.buildRoots, sourceDirOf(resolvedPathForChildStack));
+        warnings.push(...merged.warnings);
+        for (const message of merged.errors) {
+            errors.push(new BuildErrorClass("", message));
+        }
+    }
+    // Step 5: Partition entities by lexicon
+    const partitions = partitionByLexicon(discoveryResult.entities);
+    // Build a serializer lookup by name
+    const serializersByName = new Map();
+    for (const serializer of serializers) {
+        serializersByName.set(serializer.name, serializer);
+    }
+    // Step 6: Collect explicit LexiconOutputs from all entities
+    const explicitOutputs = collectLexiconOutputs(discoveryResult.entities);
+    // Step 6b: Auto-detect cross-lexicon AttrRefs
+    const autoOutputs = detectCrossLexiconRefs(discoveryResult.entities);
+    // Merge: explicit outputs take precedence over auto-detected ones.
+    // Match by parent object identity + attribute to detect collisions.
+    const explicitRefs = explicitOutputs.map((o) => ({
+        parent: o._sourceParent?.deref(),
+        attribute: o.sourceAttribute,
+    }));
+    const lexiconOutputs = [
+        ...explicitOutputs,
+        ...autoOutputs.filter((auto) => {
+            const autoParent = auto._sourceParent?.deref();
+            return !explicitRefs.some((e) => e.parent === autoParent && e.attribute === auto.sourceAttribute);
+        }),
+    ];
+    // Group outputs by source lexicon.
+    // Intrinsic-based outputs (sourceLexicon === "") have no source entity to derive a lexicon from,
+    // so they are included in every lexicon's output list.
+    const outputsByLexicon = new Map();
+    const unassignedOutputs = [];
+    for (const output of lexiconOutputs) {
+        if (!output.sourceLexicon) {
+            unassignedOutputs.push(output);
+            continue;
+        }
+        if (!outputsByLexicon.has(output.sourceLexicon)) {
+            outputsByLexicon.set(output.sourceLexicon, []);
+        }
+        outputsByLexicon.get(output.sourceLexicon).push(output);
+    }
+    // Step 7: Serialize each lexicon's entities
+    const outputs = new Map();
+    for (const [lexiconName, lexiconEntities] of partitions) {
+        const serializer = serializersByName.get(lexiconName);
+        // #1832: effect receipts are withheld from the apply-bound entity set at
+        // this seam — the narrowest choke point every applier's input flows
+        // through, since appliers consume the serialized outputs assembled here.
+        // Receipts ride `SerializeContext.receipts` instead, so a lexicon can
+        // render them for visibility (#1835) without them ever entering the
+        // document an applier writes (or prunes) from. The `effect()` step is the
+        // sole receipt writer (epic #1703, decision 3).
+        const { applyBound, receipts } = splitReceiptEntities(lexiconEntities);
+        if (serializer) {
+            const lexiconLexiconOutputs = [
+                ...(outputsByLexicon.get(lexiconName) ?? []),
+                ...unassignedOutputs,
+            ];
+            const serialized = serializer.serialize(applyBound, lexiconLexiconOutputs, {
+                ownership: options?.ownership,
+                config: options?.config,
+                ...(options?.telemetry ? { telemetry: options.telemetry } : {}),
+                ...(receipts.size > 0 ? { receipts } : {}),
+            });
+            // Collect any non-fatal serializer diagnostics into the build warnings.
+            if (typeof serialized !== "string" && serialized.warnings) {
+                for (const w of serialized.warnings)
+                    warnings.push(w);
+            }
+            outputs.set(lexiconName, serialized);
+        }
+        else if (applyBound.size === 0 && receipts.size > 0) {
+            // A partition holding only receipts (the core factory's "chant"
+            // pseudo-lexicon) has nothing apply-bound to serialize; that is the
+            // designed shape until a lexicon materializes the receipt (#1835), not
+            // a missing-serializer problem.
+        }
+        else {
+            warnings.push(`No serializer found for lexicon "${lexiconName}". List the lexicon in chant.config.ts.`);
+        }
+    }
+    // Step 8: Generate manifest
+    const lexiconNames = Array.from(partitions.keys());
+    const manifest = generateManifest(lexiconNames, lexiconOutputs, discoveryResult.entities);
+    return {
+        outputs,
+        entities: discoveryResult.entities,
+        dependencies: discoveryResult.dependencies,
+        warnings,
+        errors,
+        manifest,
+        sourceFileCount: discoveryResult.sourceFiles.length,
+        foldDecisions: discoveryResult.foldDecisions,
+        lexiconVersions: { ...(options?.lexiconVersions ?? {}) },
+        buildParams: options?.buildParams ?? [],
+        // chant #2161 — read off the entities AFTER every step that can change
+        // them (the shared-props merge in `expandComposite`, the build-root merge
+        // above), and deliberately after Step 7, so nothing about computing it can
+        // reach a serializer.
+        foldProvenance: foldProvenanceOfEntities(discoveryResult.entities, getProvenance),
+    };
+}
+/**
+ * chant #1045 (Phase 1) — build directly from a JSON-encoded discovery
+ * result (see {@link discoverEntitySetJson} in `./discovery/entity-wire.ts`)
+ * instead of pointing `build()` at a directory.
+ *
+ * Decodes the wire entity set back into a live entities map — see
+ * `decodeEntitySet`'s doc for why the decoded entities are functionally
+ * indistinguishable from what `discover()` produces in-process (real
+ * `AttrRef` instances, whole-entity identity preserved by reference, not by
+ * clone) — then runs the exact same post-discovery pipeline `build()` uses
+ * ({@link buildFromDiscoveryResult}), so partitioning, output detection,
+ * serialization, and the manifest are the SAME code path, not a fork of it.
+ *
+ * Dependencies aren't part of the wire format: unlike entities, a dependency
+ * graph is plain name-to-name data with no identity problem, so it's cheaper
+ * and more honest to recompute it from the decoded entities via the same
+ * `buildDependencyGraph()` `discover()` itself uses than to carry a second,
+ * redundant wire shape across the boundary.
+ *
+ * @param label - Used only to seed circular-nested-stack detection; a JSON
+ *   entity set has no single source directory the way a `build(path, …)`
+ *   call does. Inert today — child projects (`nestedStack()`) aren't
+ *   supported by the JSON boundary yet (see `discovery/entity-wire.ts`).
+ */
+export async function buildFromEntitiesJson(json, serializers, label = "<json-entity-set>", parentBuildStack, options) {
+    const entities = decodeEntitySet(json.entitySet);
+    const dependencies = buildDependencyGraph(entities);
+    const errors = json.errors.map((e) => new DiscoveryError(e.file, e.message, e.type));
+    const discoveryResult = {
+        entities,
+        dependencies,
+        sourceFiles: json.sourceFiles,
+        errors,
+        foldDecisions: json.foldDecisions,
+    };
+    return buildFromDiscoveryResult(discoveryResult, label, serializers, parentBuildStack, options);
+}