@intentius/chant 0.124.12 → 0.124.14

package/dist/cdk/tier-map.js

@@ -0,0 +1,64 @@
+/**
+ * CloudFormation-type → native-spec tier for the CDK carve advisor (#1056).
+ *
+ * The Terraform path's hardest layer — translating `aws_s3_bucket` into
+ * `AWS::S3::Bucket` and a tier — does not exist here: a synthesized template is
+ * already in CloudFormation type space, which is the space
+ * `AWS_CARVE_TYPES.nativeType` is written in. So this is the same table read
+ * from the other end, not a second table to keep in step. Adding an AWS type to
+ * the carve-out table lights it up for both advisors at once.
+ *
+ * `mapsTo` is the CloudFormation type itself, because that identity is the
+ * point: chant's AWS lexicon constructors take CloudFormation PascalCase props,
+ * so a CDK resource needs no translation to become one.
+ */
+import { AWS_CARVE_TYPES } from "../terraform/aws-resources.js";
+/**
+ * CloudFormation type → tier. Two Terraform types can name one CloudFormation
+ * type (`aws_lb` and `aws_alb` are the same load balancer); the first entry
+ * wins, and since aliases share a tier by construction there is nothing to
+ * reconcile.
+ */
+export const CFN_TIER_MAP = (() => {
+    const map = {};
+    for (const entry of AWS_CARVE_TYPES) {
+        if (map[entry.nativeType])
+            continue;
+        map[entry.nativeType] = { tier: entry.tier, mapsTo: entry.nativeType };
+    }
+    return map;
+})();
+/** The chant AWS lexicon constructor a CloudFormation type would carve into. */
+export const CFN_CTOR = (() => {
+    var _a;
+    const map = {};
+    for (const entry of AWS_CARVE_TYPES)
+        map[_a = entry.nativeType] ?? (map[_a] = entry.ctor);
+    return map;
+})();
+export function resolveCfnTier(cfnType) {
+    return CFN_TIER_MAP[cfnType] ?? null;
+}
+/**
+ * A nested stack is an assembly of its own: its resources live in a separate
+ * template that this advisor does not descend into, so carving the
+ * `AWS::CloudFormation::Stack` resource means carving everything under it.
+ */
+export const NESTED_STACK_TYPE = "AWS::CloudFormation::Stack";
+/**
+ * CloudFormation resources CDK synthesizes for its own bookkeeping. They
+ * describe the synthesis, not the infrastructure, so they never appear in the
+ * ranking.
+ */
+export const SCAFFOLDING_TYPES = new Set(["AWS::CDK::Metadata"]);
+/**
+ * Template parameters CDK adds for bootstrap and asset plumbing. A reference to
+ * one is not a sign the resource is parameterized by its author — it is the
+ * synthesizer talking to itself — so these do not mark a construct dynamic.
+ */
+export function isScaffoldingParameter(name) {
+    return (name === "BootstrapVersion" ||
+        name === "CdkBootstrapVersion" ||
+        name.startsWith("AssetParameters") ||
+        name.startsWith("BootstrapVersion"));
+}

package/dist/cdk/types.js

@@ -0,0 +1,24 @@
+/**
+ * The parts of a CDK cloud assembly the carve advisor reads (#1056).
+ *
+ * A cloud assembly is already JSON, so there is no parser to install and no
+ * expression AST to resolve — the Terraform path's two hardest layers do not
+ * exist here. Three files carry everything the advisor needs:
+ *
+ *  - `manifest.json` — which artifacts are stacks, which template file each
+ *    one synthesized to, and (crucially) whether any context lookup went
+ *    unresolved.
+ *  - `tree.json` — the construct tree, so CloudFormation resources can be
+ *    grouped back under the construct that emitted them. Optional: CDK can be
+ *    told not to write it, and the advisor degrades to a coarser grouping.
+ *  - `*.template.json` — the CloudFormation templates themselves, already in
+ *    `AWS::*` type space, which is exactly what the AWS tier map keys on.
+ *
+ * Everything here is post-jsii, so a Python or Java CDK app reads through the
+ * same code path as a TypeScript one. Nothing in this module reads CDK source.
+ *
+ * The declarations are deliberately loose — every field optional, unknown keys
+ * tolerated — because the assembly schema is not chant's to own and gains
+ * fields between CDK releases.
+ */
+export {};

package/dist/change-set.js

@@ -0,0 +1,312 @@
+/**
+ * One change-set document across planners (#3181).
+ *
+ * Several things plan changes, each with its own output: `chant lifecycle
+ * plan` for the cloud lexicons, terraform, tofu and choudoufu plans, and a
+ * warden's reconcile plan. This module is the one typed document they all
+ * become, so a reader can ask one question of every plan in a run: what will
+ * change, where, and how risky it is. Its schema is
+ * `./workspace/change-set.schema.json`, part of the workspace read contract.
+ *
+ * Each planner reaches it through an adapter that returns a
+ * {@link ChangeSetPart}: one member and its entries. The lifecycle and
+ * reconcile adapters are here; the terraform-family ones live in the
+ * terraform lexicon's `change-set` subpath. {@link composeChangeSet} joins
+ * the parts.
+ *
+ * ## The digest
+ *
+ * Every member carries the plan digest a gate on that member alone binds
+ * (#2300): `terraformPlanDigest` for a terraform-family root, and here
+ * `computePlanDigest("lifecycle-plan", …)` and `computePlanDigest(
+ * "reconcile-plan", …)`. {@link changeSetDigest} over the sorted `{ member,
+ * planDigest }` pairs is the set digest #3049 describes, and a wave's digest
+ * is that function over the wave's members.
+ *
+ * The document's digest is {@link changeSetDocumentDigest}: the set digest,
+ * each member's status and holes, the entries and the side effects. An
+ * approval of the document binds what it says as well as the plans it came
+ * from, so a pull request's apply that resumes from a record (#3464) can
+ * check a re-planned member against the record's entries without trusting
+ * whoever wrote the record. The summary is computed from the entries and is
+ * not hashed. A change to how chant projects a plan into entries moves the
+ * document's digest, so an approval given under one chant does not carry to
+ * an apply under a chant that projects the same plan differently.
+ *
+ * ## The import graph
+ *
+ * terragucci runs this in customer CI as one bundled file with no TypeScript
+ * toolchain (#3421). Everything here imports `./lifecycle/plan-digest` and
+ * types only, and `change-set-bundle.test.ts` holds that.
+ */
+import { computePlanDigest } from "./lifecycle/plan-digest.js";
+/** The schema a change-set document names in `$schema`. */
+export const CHANGE_SET_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/change-set/v1/change-set.schema.json";
+/** The read-contract version the document follows. */
+export const CHANGE_SET_CONTRACT = 1;
+/** Every action, in the order the summary lists them. */
+export const CHANGE_SET_ACTIONS = ["create", "update", "replace", "delete", "read", "no-op", "forget"];
+const byString = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function entryKey(e) {
+    return `${e.member}\u0000${e.address}\u0000${e.deposed ?? ""}\u0000${e.action}`;
+}
+const bySideEffect = (a, b) => byString(a.member, b.member) || byString(a.address, b.address) || byString(a.trigger ?? "", b.trigger ?? "");
+/**
+ * The set digest over members' plan digests: `computePlanDigest("change-set",
+ * …)` over `{ member, planDigest }` sorted by member. Order-independent,
+ * and different whenever one member's plan digest is. Refuses a set that
+ * names a member twice, which has no single plan for that member.
+ *
+ * Provisional members are left out: their plans may stand on values that do
+ * not exist yet, so an approval of this digest never covers them.
+ */
+export function changeSetDigest(members) {
+    const pairs = members
+        .filter((m) => m.provisional !== true)
+        .map((m) => ({ member: m.member, planDigest: m.planDigest }))
+        .sort((a, b) => byString(a.member, b.member));
+    for (let i = 1; i < pairs.length; i++) {
+        if (pairs[i - 1].member === pairs[i].member)
+            throw new Error(`the change set names member ${pairs[i].member} twice`);
+    }
+    return computePlanDigest("change-set", pairs);
+}
+/**
+ * The document's digest: `computePlanDigest("change-set-document", …)` over
+ * the set digest ({@link changeSetDigest}), each member's name, status and
+ * holes, the entries and the side effects. Members are sorted by name and
+ * entries and side effects by the keys {@link composeChangeSet} sorts them by,
+ * so order makes no difference.
+ *
+ * A provisional member is left out, with its entries and side effects, as
+ * the set digest leaves it out: no approval of the document covers it.
+ */
+export function changeSetDocumentDigest(doc) {
+    const provisional = new Set(doc.members.filter((m) => m.provisional === true).map((m) => m.member));
+    const members = doc.members
+        .filter((m) => !provisional.has(m.member))
+        .map((m) => ({ member: m.member, status: m.status, holes: m.holes }))
+        .sort((a, b) => byString(a.member, b.member));
+    const entries = doc.entries.filter((e) => !provisional.has(e.member)).sort((a, b) => byString(entryKey(a), entryKey(b)));
+    const sideEffects = (doc.sideEffects ?? []).filter((s) => !provisional.has(s.member)).sort(bySideEffect);
+    return computePlanDigest("change-set-document", { set: changeSetDigest(doc.members), members, entries, sideEffects });
+}
+/** The summary of a set of members and entries. */
+export function summarizeChangeSet(members, entries) {
+    const actions = Object.fromEntries(CHANGE_SET_ACTIONS.map((a) => [a, 0]));
+    const types = {};
+    const byMember = {};
+    const deletes = [];
+    const replacements = [];
+    const bump = (into, key, action) => {
+        const counts = (into[key] ?? (into[key] = {}));
+        counts[action] = (counts[action] ?? 0) + 1;
+    };
+    for (const e of entries) {
+        actions[e.action]++;
+        bump(types, e.type, e.action);
+        bump(byMember, e.member, e.action);
+        const named = {
+            member: e.member, address: e.address, type: e.type,
+            ...(e.deposed !== undefined ? { deposed: e.deposed } : {}),
+            ...(e.disruption !== undefined ? { disruption: e.disruption } : {}),
+        };
+        if (e.action === "delete")
+            deletes.push(named);
+        if (e.action === "replace")
+            replacements.push(named);
+    }
+    return {
+        members: members.length,
+        entries: entries.length,
+        actions,
+        types: sortKeys(types),
+        byMember: sortKeys(byMember),
+        deletes,
+        replacements,
+        failed: members.filter((m) => m.status === "failed").map((m) => m.member),
+        holes: members.reduce((n, m) => n + m.holes.length, 0),
+    };
+}
+function sortKeys(o) {
+    return Object.fromEntries(Object.entries(o).sort(([a], [b]) => byString(a, b)));
+}
+/**
+ * Join adapters' parts into one document: members sorted by name, entries
+ * by member, address, deposed key and action, the summary, and the digest.
+ * Throws when two parts name the same member, or an entry names a member
+ * other than its part's.
+ */
+export function composeChangeSet(parts, options = {}) {
+    const members = parts.map((p) => p.member).sort((a, b) => byString(a.member, b.member));
+    const entries = [];
+    for (const part of parts) {
+        for (const e of part.entries) {
+            if (e.member !== part.member.member)
+                throw new Error(`an entry at ${e.address} names member ${e.member}, inside member ${part.member.member}`);
+            entries.push(e);
+        }
+    }
+    entries.sort((a, b) => byString(entryKey(a), entryKey(b)));
+    const sideEffects = parts
+        .flatMap((p) => (p.sideEffects ?? []).map((s) => ({ member: p.member.member, ...s })))
+        .sort(bySideEffect);
+    const digest = changeSetDocumentDigest({ members, entries, sideEffects });
+    return {
+        $schema: CHANGE_SET_SCHEMA_ID,
+        contract: CHANGE_SET_CONTRACT,
+        ...(options.chant !== undefined ? { chant: options.chant } : {}),
+        digest,
+        members,
+        entries,
+        ...(sideEffects.length > 0 ? { sideEffects } : {}),
+        summary: summarizeChangeSet(members, entries),
+    };
+}
+/**
+ * Whether a document's digest is the one its members, entries and side
+ * effects give ({@link changeSetDocumentDigest}). A document that names a
+ * member twice has no digest and is not verified.
+ */
+export function verifyChangeSetDigest(doc) {
+    try {
+        return changeSetDocumentDigest(doc) === doc.digest;
+    }
+    catch {
+        return false;
+    }
+}
+function lifecycleAttributes(entry) {
+    const because = new Set(entry.disruptionBecause ?? []);
+    return (entry.deltas ?? []).map((d) => ({
+        path: d.path,
+        ...(d.oldValue !== undefined ? { before: d.oldValue } : {}),
+        ...(d.newValue !== undefined ? { after: d.newValue } : {}),
+        ...(because.has(d.path) ? { forcesReplacement: true } : {}),
+    }));
+}
+/**
+ * A chant member's part, from `chant lifecycle plan <env> --json`.
+ *
+ * `create`, `update`, `delete` and `noop` map across. An `update` whose
+ * lexicon says it replaces or destroys becomes a `replace`. An `effect`
+ * entry is the receipt its effect step writes: a `create` when the receipt
+ * is absent, else an `update`. `unobserved` entries are holes. `adopt` and
+ * `runtime` propose nothing and are left out.
+ *
+ * The member's plan digest is `computePlanDigest("lifecycle-plan", plan)`
+ * over the whole document, which carries no timestamp or run id.
+ */
+export function lifecyclePlanPart(input) {
+    const { plan } = input;
+    const fallback = input.lexicon ?? "chant";
+    const entries = [];
+    const holes = [];
+    for (const e of plan.entries ?? []) {
+        const lexicon = e.lexicon ?? fallback;
+        if (e.action === "unobserved") {
+            holes.push({ address: e.name, ...(e.type ? { type: e.type } : {}), reason: e.unobservedReason ?? "unobserved" });
+            continue;
+        }
+        let action;
+        let disruption;
+        switch (e.action) {
+            case "create":
+                action = "create";
+                break;
+            case "noop":
+                action = "no-op";
+                break;
+            case "delete":
+                action = "delete";
+                disruption = "destroy";
+                break;
+            case "effect":
+                action = e.effectReason === "receipt-absent" ? "create" : "update";
+                break;
+            case "update":
+                disruption = e.disruption ?? "unknown";
+                action = disruption === "replace" || disruption === "destroy" ? "replace" : "update";
+                break;
+            default: continue; // adopt, runtime: not a proposal
+        }
+        entries.push({
+            member: input.member,
+            lexicon,
+            planner: "chant",
+            address: e.name,
+            type: e.type ?? "unknown",
+            ...(e.physicalId ? { id: e.physicalId } : {}),
+            action,
+            ...(disruption ? { disruption } : {}),
+            scope: plan.env,
+            attributes: lifecycleAttributes(e),
+        });
+    }
+    const lexicons = [...new Set(entries.map((e) => e.lexicon))].sort();
+    return {
+        member: {
+            member: input.member,
+            lexicon: lexicons.length === 1 ? lexicons[0] : fallback,
+            planner: "chant",
+            scope: plan.env,
+            status: "planned",
+            planDigest: computePlanDigest("lifecycle-plan", plan),
+            holes,
+        },
+        entries,
+    };
+}
+function topLevelKeys(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? Object.keys(value).sort() : [];
+}
+/**
+ * A warden member's part, from the reconcile `ChangeSet`s it planned
+ * (`./reconcile.ts`). The address is `<resourceType>.<key>`, unique within
+ * one org, and the scope is the org. An update's disruption is `unknown`:
+ * the reconcile model says nothing about it.
+ *
+ * The plan digest covers each change set's org and entries, and leaves out
+ * the managed counts, which are guardrail denominators rather than changes.
+ */
+export function reconcilePlanPart(input) {
+    const sets = (Array.isArray(input.plan) ? input.plan : [input.plan])
+        .map((cs) => ({ org: cs.org, entries: [...cs.entries].sort((a, b) => byString(`${a.resourceType}\u0000${a.key}`, `${b.resourceType}\u0000${b.key}`)) }))
+        .sort((a, b) => byString(a.org, b.org));
+    const lexicon = input.lexicon ?? "github";
+    const entries = [];
+    for (const cs of sets) {
+        for (const e of cs.entries) {
+            const attributes = e.kind === "update"
+                ? (e.fields ?? []).map((f) => ({ path: f.field, ...(f.before !== undefined ? { before: f.before } : {}), ...(f.after !== undefined ? { after: f.after } : {}) }))
+                : e.kind === "create"
+                    ? topLevelKeys(e.after).map((k) => ({ path: k, after: e.after[k] }))
+                    : [];
+            entries.push({
+                member: input.member,
+                lexicon,
+                planner: "warden",
+                address: `${e.resourceType}.${e.key}`,
+                type: e.resourceType,
+                name: e.key,
+                action: e.kind,
+                ...(e.kind === "delete" ? { disruption: "destroy" } : e.kind === "update" ? { disruption: "unknown" } : {}),
+                scope: cs.org,
+                attributes,
+            });
+        }
+    }
+    const orgs = [...new Set(sets.map((s) => s.org))];
+    return {
+        member: {
+            member: input.member,
+            lexicon,
+            planner: "warden",
+            ...(orgs.length === 1 ? { scope: orgs[0] } : {}),
+            status: "planned",
+            planDigest: computePlanDigest("reconcile-plan", sets),
+            holes: [],
+        },
+        entries,
+    };
+}

package/dist/child-project.js

@@ -0,0 +1,21 @@
+/**
+ * Child Project — represents a nested project directory that gets built
+ * independently and referenced from a parent as a single deployment unit.
+ *
+ * Lexicons create ChildProjectInstance via their own factory (e.g. `nestedStack()`).
+ * The core build pipeline detects these and recursively builds children.
+ */
+import { DECLARABLE_MARKER } from "./declarable.js";
+/**
+ * Marker symbol for child project identification.
+ */
+export const CHILD_PROJECT_MARKER = Symbol.for("chant.childProject");
+/**
+ * Type guard for ChildProjectInstance.
+ */
+export function isChildProject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        CHILD_PROJECT_MARKER in value &&
+        value[CHILD_PROJECT_MARKER] === true);
+}

package/dist/claimed-fields.js

@@ -0,0 +1,135 @@
+/**
+ * The claimed-field set (#2160) — which properties this declaration ever set.
+ *
+ * chant's ownership question has always been answered per resource, from a
+ * marker: is this thing mine. The finer question was never asked. A live
+ * property tree carries fields nobody declared — an autoscaler's replica count,
+ * a controller's annotation, a value a person typed into a console — and the
+ * deep diff (./lifecycle/deep-diff.ts) reported every one of them as a
+ * difference, because a difference is all a two-way comparison can produce.
+ *
+ * Every lexicon has been paying for that in hand-written knowledge.
+ * `DeepNormalizationHooks.prune` is where the noise goes, and three of the four
+ * hooks exist because the live tree holds fields the declaration never
+ * mentions. Kubernetes is the one substrate that escapes it: the API server
+ * records a field manager per field (`metadata.managedFields`), so a foreign
+ * write is a fact about the object rather than a rule somebody maintains.
+ * `lexicons/gcp/src/deep-observe.ts` says why nobody else can do that — "a REST
+ * payload carries no field ownership" — and answers with a static per-kind
+ * table instead.
+ *
+ * The declaration is the table they are missing. A `ResourceDeclarable`'s
+ * `props` are exactly the fields chant set, they are available on every
+ * substrate, and they come from the same build that produced the entity.
+ * Nothing has to come back from the provider.
+ *
+ * ## The grammar is the diff's grammar
+ *
+ * A claim is a set of property paths in the form `flattenDeepProperties`
+ * produces: `spec.replicas`, `Tags[#env].Value`, `ingress[0].fromPort`. Same
+ * hooks, same normalization, same flattening — so a path in the claim and a
+ * path in the diff are the same string or they are different fields. Deriving
+ * the claim any other way (walking raw props, say) would give a set that agrees
+ * with the diff for most trees and disagrees for exactly the ones the hooks
+ * were written for.
+ *
+ * ## Membership is exact, deliberately
+ *
+ * A claimed path is matched exactly, never by its index-erased pattern
+ * (`Tags[].Value`). The pattern is the right test for
+ * {@link import("./deep-observation.js").DeepNode.counterpart}, which asks a
+ * shape question ("did source declare tag values at all") before array order is
+ * canonical. Classification asks a value question, and it pairs a declared
+ * value with a live one at the same path. A pattern match would answer
+ * "declared" for a path that has no declared value to compare against, which is
+ * neither of the two declared classifications and would quietly become a third
+ * meaning of "drift".
+ *
+ * ## What the claim does not decide
+ *
+ * It does not prune. A field chant never declared still reaches the diff, still
+ * appears in the report, and still carries its live value — it is reported as
+ * unclaimed rather than dropped, because chant #1191 already lost a
+ * console-added label by pruning what it could not attribute. What the claim
+ * changes is the verdict: unclaimed is not drift, and drift is the only thing
+ * that may become an update.
+ */
+import { deepValueEqual, flattenDeepProperties, normalizeDeepProperties, } from "./deep-observation.js";
+/** An empty claim — a declaration with no props, and the safe default. */
+export const NO_CLAIMED_FIELDS = { paths: new Set() };
+/**
+ * Build a claim from an already-normalized declared property tree.
+ *
+ * `options` must be the same {@link FlattenDeepOptions} the diff flattens the
+ * declared side with, or the two disagree about keyed list segments.
+ */
+export function claimedFieldsOfTree(declared, options) {
+    const flat = flattenDeepProperties(declared, {
+        entityType: options.entityType,
+        side: "declared",
+        ...(options.hooks ? { hooks: options.hooks } : {}),
+    });
+    return { paths: new Set(flat.keys()) };
+}
+/**
+ * Build a claim straight from a declaration's raw `props` — the entry point for
+ * a consumer that has an entity and no diff.
+ *
+ * Normalizes with the lexicon's own hooks first, exactly as the diff does, so
+ * pruned and masked paths land the same way on both routes. `livePaths` is the
+ * counterpart set (`deepPathSet` over the live tree) where the caller has one:
+ * without it the pass runs one-sided and any hook gated on
+ * {@link import("./deep-observation.js").DeepNode.counterpart} sees `"unknown"`,
+ * which is the honest answer and prunes nothing default-related.
+ */
+export function claimedFieldsOfProps(props, options) {
+    const normalized = normalizeDeepProperties(props, {
+        entityType: options.entityType,
+        side: "declared",
+        ...(options.hooks ? { hooks: options.hooks } : {}),
+        ...(options.livePaths ? { counterpartPaths: options.livePaths } : {}),
+    });
+    return claimedFieldsOfTree(normalized, options);
+}
+/** True when this declaration set the property at `path`. */
+export function isClaimed(claimed, path) {
+    return claimed !== undefined && claimed.paths.has(path);
+}
+/**
+ * The claim as a sorted array — the wire form, for
+ * {@link import("./deep-observation.js").DeepResourceObservation.claimedFields}
+ * and for anything serializing a result to JSON.
+ */
+export function claimedFieldPaths(claimed) {
+    return [...claimed.paths].sort();
+}
+/** Rebuild a claim from its wire form. */
+export function claimedFieldsFromPaths(paths) {
+    return { paths: new Set(paths) };
+}
+/**
+ * Classify one live value against the claim.
+ *
+ * `declaredValue` is only read when the path is claimed; pass whatever the
+ * declared tree holds there (including `undefined`, which is a legal declared
+ * value on a claimed path only in the sense that the flattener never emits it).
+ */
+export function classifyLiveField(input) {
+    if (!isClaimed(input.claimed, input.path))
+        return "undeclared";
+    return deepValueEqual(input.declaredValue, input.liveValue) ? "declared-equal" : "declared-changed";
+}
+/**
+ * Who holds an undeclared live field, and which source said so.
+ *
+ * The manager wins where the substrate records one: "owned by `hpa-controller`"
+ * and "chant never set it" are the same verdict with very different amounts of
+ * information in them, and an operator can act on the first. The claim is the
+ * fallback, and it answers on every substrate.
+ */
+export function heldBy(fieldOwners, path) {
+    const manager = fieldOwners?.[path];
+    if (manager)
+        return { holder: manager, source: "field-manager" };
+    return { source: "claimed-fields" };
+}

package/dist/cli/build-options.js

@@ -0,0 +1,70 @@
+/**
+ * The one place chant assembles `build()`'s options for a project directory.
+ *
+ * chant #2002 — `chant build` (./commands/build.ts) and the `policyGate` Op
+ * step (../lint/policy.ts's `evaluateProjectPolicies`) both build the same
+ * directory, and each used to assemble that option object itself. The two lists
+ * drifted to nine options against two: the gate built with fold off (the path
+ * `chant build` retired as its default in #1134), without the project's config
+ * (so serializers lost their lexicon-scoped dialect settings and a policy
+ * reading `ctx.docs` inspected different documents), and without `buildRoots`
+ * (so config-declared roots contributed no entities at all). A gate can only
+ * decide on a build `chant build` would produce if the two are assembled from
+ * one place, so they are.
+ *
+ * Two functions rather than one because the *modes* are needed earlier than the
+ * rest: `chant build` arms sandboxed policy execution from the resolved
+ * `sandbox` before it loads any policy module, which happens before build-time
+ * parameters and the ownership marker exist. {@link resolveBuildModes} is that
+ * early half; {@link resolveProjectBuildOptions} takes its result and assembles
+ * everything `build()` is given.
+ */
+import { resolveFoldEnabled, resolveSandboxEnabled } from "../config.js";
+import { collectBuildRootContributors, resolveLexiconVersions } from "./plugins.js";
+/**
+ * Resolve this build's execution modes: an explicit CLI flag wins over
+ * `chant.config.ts`'s `build.fold`/`build.sandbox`, which wins over the default
+ * (fold on, sandbox off). Callers with no flags to offer (the `policyGate` step)
+ * pass no overrides and get the project's own answer.
+ */
+export function resolveBuildModes(config, overrides) {
+    return {
+        fold: resolveFoldEnabled(config, overrides?.fold),
+        sandbox: resolveSandboxEnabled(config, overrides?.sandbox),
+    };
+}
+/**
+ * Assemble the option object `build()` takes for a project directory.
+ *
+ * Every option here is derived from the project (its config, its plugins, its
+ * resolved parameters) rather than from the command that asked, so two callers
+ * handing in the same project get byte-identical builds. A new option belongs
+ * in this function, never at a call site.
+ */
+export function resolveProjectBuildOptions(input) {
+    const { config, configDir, plugins, modes, ownership, buildParams, telemetry } = input;
+    // #1039 — each loaded plugin's registered intrinsics (e.g. AWS's `Sub`), so
+    // a file using a registered intrinsic tagged template folds instead of
+    // unconditionally falling back to run. `intrinsics` is an optional plugin
+    // extension, hence the guard.
+    const intrinsics = plugins?.flatMap((plugin) => plugin.intrinsics?.() ?? []) ?? [];
+    // #1063 — the same loaded plugins, by NAME, are this build's allowlist for
+    // following a bare import specifier into a lexicon package (so `Azure`,
+    // `GCP`, `S3Actions`, `CI` fold as values).
+    const lexicons = plugins?.map((plugin) => plugin.name) ?? [];
+    return {
+        ownership,
+        ...(telemetry ? { telemetry } : {}),
+        config: config,
+        fold: modes.fold,
+        sandbox: modes.sandbox,
+        intrinsics,
+        lexicons,
+        // chant #1442 — which lexicon VERSION interpreted each declaration.
+        lexiconVersions: resolveLexiconVersions(lexicons),
+        buildParams,
+        // #1548 piece 3 — config-declared build roots (kustomize dirs, committed
+        // ciphertext), rendered into entities by the owning lexicon's hook.
+        buildRoots: collectBuildRootContributors(plugins, config, configDir),
+    };
+}