@intentius/chant 0.124.13 → 0.124.14

package/dist/secret-materialization.js

@@ -0,0 +1,153 @@
+/**
+ * Generated-once secret materialization — the one implementation behind the
+ * `ensure-secret` capability verb (components/verbs/ensure-secret.ts) and the
+ * `ensureSecret(...)` op step builder (op/builders.ts). chant #1829, epic
+ * #1365 decisions 3 and 6.
+ *
+ * The contract is read-then-write:
+ *
+ * - Absent: mint once, through the store adapter, and report `created`.
+ * - Present: verify presence, the declared key-set, and any declared
+ *   metadata, then STOP — present means done. Never mint over an existing
+ *   value. Never rotate implicitly. A re-run of a whole deploy leaves the
+ *   stored bytes untouched.
+ * - Mismatch: fail loudly, naming what mismatched — key names and metadata
+ *   keys, never a value or a value-derived hash (#1365 decision 6).
+ *
+ * The constitutional line (../secret-provenance.ts): no code path here may
+ * hold, log, hash, or compare a secret value. That is structural, not
+ * discipline:
+ *
+ * - {@link ensureSecretMaterialization} never calls the generator. It hands
+ *   the generator to the store adapter's `create`, which consumes the
+ *   material as it writes. The engine's result type has no field that could
+ *   carry material.
+ * - The generator produces {@link SecretMaterial}, an opaque single-use
+ *   handle. The plaintext lives in a module-private WeakMap, not on the
+ *   object: enumeration, `JSON.stringify`, `String(...)`, and `util.inspect`
+ *   all see only a redaction marker. Only {@link consumeSecretMaterial} —
+ *   meant for store adapters, at the write — yields the plaintext, exactly
+ *   once; a second consume throws.
+ * - `describe` returns key names and metadata only, so the mismatch check
+ *   has nothing value-shaped to compare even by accident.
+ *
+ * Store adapters are per-provider (#1830 is the k8s row); core defines only
+ * the seam.
+ */
+import { randomBytes } from "node:crypto";
+// ── Opaque secret material ────────────────────────────────────────────────────
+/** Module-private plaintext vault. Keyed by handle identity; consuming deletes. */
+const vault = new WeakMap();
+const REDACTED = "[secret material]";
+/**
+ * A single-use, opaque handle to generated secret material. The plaintext is
+ * not a property of this object — it lives in a module-private WeakMap — so
+ * spreading, enumerating, stringifying, or logging the handle yields only a
+ * redaction marker. A store adapter redeems it with
+ * {@link consumeSecretMaterial} at the moment it writes; nothing else can.
+ */
+export class SecretMaterial {
+    constructor() { }
+    /** Wrap plaintext in an opaque handle. Call inside a generator only. */
+    static mint(plaintext) {
+        const handle = new SecretMaterial();
+        vault.set(handle, plaintext);
+        return handle;
+    }
+    toString() {
+        return REDACTED;
+    }
+    toJSON() {
+        return REDACTED;
+    }
+    /** node:util.inspect (console.log) sees the redaction marker, not the vault. */
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return REDACTED;
+    }
+}
+/**
+ * Redeem a {@link SecretMaterial} handle for its plaintext — exactly once.
+ * For store adapters only, at the write to the backing store. Throws if the
+ * handle was already consumed (or was never minted here): material flows to
+ * the store exactly once and is retained nowhere.
+ */
+export function consumeSecretMaterial(material) {
+    const plaintext = vault.get(material);
+    if (plaintext === undefined) {
+        throw new Error("secret material already consumed — material flows to the store adapter exactly once and is never retained");
+    }
+    vault.delete(material);
+    return plaintext;
+}
+/** 32 bytes from the CSPRNG, base64url — the default mint. */
+export const defaultSecretMaterialGenerator = () => SecretMaterial.mint(randomBytes(32).toString("base64url"));
+/**
+ * The loud failure: an existing secret does not match its declared contract.
+ * `mismatches` names what differed — key names and metadata keys only.
+ * Constructing one with anything value-shaped is the reviewer's tripwire;
+ * nothing in this module can, because nothing in this module holds a value.
+ */
+export class SecretContractMismatchError extends Error {
+    constructor(
+    /** The secret's name. */
+    secretName, 
+    /** Human-readable mismatch descriptions, naming keys — never values. */
+    mismatches) {
+        super(`secret "${secretName}" exists but does not match its declared contract: ${mismatches.join("; ")}. ` +
+            `chant never mints over or rotates an existing secret — reconcile the declaration or the stored secret explicitly.`);
+        this.secretName = secretName;
+        this.mismatches = mismatches;
+        this.name = "SecretContractMismatchError";
+    }
+}
+/**
+ * Ensure a `generated-once` secret exists and matches its declared contract.
+ * Read-then-write:
+ *
+ * - Absent: `store.create(name, keys, generate)` — one mint, then done.
+ * - Present and matching: no write of any kind; returns `present`.
+ * - Present and mismatching: throws {@link SecretContractMismatchError}
+ *   naming the missing/unexpected key names and mismatched metadata keys.
+ *
+ * The engine never calls `generate` itself and never sees what the adapter
+ * writes; its return value carries names only.
+ */
+export async function ensureSecretMaterialization(store, spec, generate = defaultSecretMaterialGenerator) {
+    if (typeof spec.name !== "string" || spec.name.length === 0) {
+        throw new Error("ensureSecret: `name` must be a non-empty string");
+    }
+    if (!Array.isArray(spec.keys) || spec.keys.length === 0) {
+        throw new Error(`ensureSecret("${spec.name}"): \`keys\` must name at least one key to materialize`);
+    }
+    if (await store.exists(spec.name)) {
+        const actual = await store.describe(spec.name);
+        const mismatches = [];
+        const actualKeys = new Set(actual.keys);
+        const declaredKeys = new Set(spec.keys);
+        const missing = spec.keys.filter((k) => !actualKeys.has(k));
+        const unexpected = actual.keys.filter((k) => !declaredKeys.has(k));
+        if (missing.length > 0) {
+            mismatches.push(`missing declared key(s): ${missing.join(", ")}`);
+        }
+        if (unexpected.length > 0) {
+            mismatches.push(`undeclared key(s) present: ${unexpected.join(", ")}`);
+        }
+        for (const [key, value] of Object.entries(spec.metadata ?? {})) {
+            const actualValue = actual.metadata?.[key];
+            if (actualValue === undefined) {
+                mismatches.push(`missing declared metadata key: ${key}`);
+            }
+            else if (actualValue !== value) {
+                // Name the KEY only — metadata values stay out of the error by rule,
+                // the same line the whole module holds for secret values.
+                mismatches.push(`metadata key differs: ${key}`);
+            }
+        }
+        if (mismatches.length > 0) {
+            throw new SecretContractMismatchError(spec.name, mismatches);
+        }
+        return { outcome: "present", name: spec.name, keys: spec.keys };
+    }
+    await store.create(spec.name, spec.keys, generate);
+    return { outcome: "created", name: spec.name, keys: spec.keys };
+}

package/dist/secret-provenance.js

@@ -0,0 +1,250 @@
+/**
+ * Secret provenance vocabulary (chant #1828, epic #1365).
+ *
+ * A secret's PROVENANCE is where its value comes from — never what the value
+ * is. chant's constitutional line on secrets: no code path may hold, log,
+ * hash, or compare a secret value. This module makes that structural: the
+ * declaration types have no field that could carry material, the factory
+ * rejects material-shaped fields at both the type level (`never` fields) and
+ * at runtime (own-property check, naming only the offending KEY), and
+ * "mismatch" anywhere downstream means presence, declared key-set, and
+ * metadata — never a value or a value-derived hash (#1365 decision 6).
+ *
+ * The closed kind set:
+ *
+ * - `referenced` — the value exists out of band (a human or an external
+ *   process put it where consumers read it). chant records only that the
+ *   estate depends on it, which is what lets the consumed-but-unproduced
+ *   check (#1382) ship as an error instead of a guess.
+ * - `from-provider` — a declared provider binding materializes it (the
+ *   operator/CRD seam; `K8s::Infisical::InfisicalSecret` from #1321 is the
+ *   exemplar). The declaration POINTS at that binding, it does not re-model
+ *   it.
+ * - `generated-once` — minted on first materialization, then never
+ *   regenerated (present means done). The declaration carries contract flags
+ *   only — e.g. the declared key-set — never mint parameters holding
+ *   material. `generated-once` secrets never enter the prunable set (#1365
+ *   decision 5).
+ * - `committed-encrypted` — sops-style ciphertext committed in the repo,
+ *   decrypted by the delivery system (Flux) straight into the target. The
+ *   declaration records a repo-relative PATH to the ciphertext, never the
+ *   bytes: the factory is pure and touches no filesystem, so it still folds
+ *   under `--sandbox`. The bytes are read at `buildRoots()` — the one
+ *   sanctioned impure seam — and emitted as a sidecar file, never as a
+ *   document in the primary output. See
+ *   `docs/design/committed-encrypted-sops-provenance.md`.
+ *
+ * Declarations are serializer-neutral: discovery collects them like any
+ * entity (they are Declarables), but `partitionByLexicon` (../build.ts)
+ * excludes them from every serializer partition, so no lexicon ever emits
+ * them. They are data that lint rules and lexicons READ (via
+ * {@link collectSecretDeclarations}), not output.
+ */
+import { DECLARABLE_MARKER } from "./declarable.js";
+/** Every provenance kind, for exhaustiveness checks. */
+export const SECRET_PROVENANCE_KINDS = [
+    "referenced",
+    "from-provider",
+    "generated-once",
+    "committed-encrypted",
+];
+/** Every encryption tool, for exhaustiveness checks. */
+export const SECRET_ENCRYPTION_TOOLS = ["sops"];
+/**
+ * File extensions a committed ciphertext path may carry (v1).
+ *
+ * The CLI writer round-trips every additional file through `JSON.parse` and
+ * re-emits it key-sorted when the parse succeeds
+ * (`./cli/commands/build.ts`), which would silently rewrite a `.sops.json`
+ * file and break the byte-for-byte guarantee. v1 refuses anything but YAML;
+ * the writer additionally skips the round trip for these files, so byte
+ * identity is structural rather than a happy accident of JSON.parse failing.
+ */
+const CIPHERTEXT_FILE_EXTENSIONS = [".yaml", ".yml"];
+/**
+ * Patterns that mean a PRIVATE key was pasted where a public recipient
+ * belongs. Matched against `recipients` entries; the thrown message names the
+ * field and the index, never the value.
+ */
+const PRIVATE_KEY_MARKERS = [/AGE-SECRET-KEY-/i, /-----BEGIN [A-Z ]*PRIVATE KEY-----/];
+/** Marker symbol identifying a secret provenance declaration. `Symbol.for` so
+ * it survives the entity-wire codec (../discovery/entity-wire-codec.ts). */
+export const SECRET_DECLARATION_MARKER = Symbol.for("chant.secret-declaration");
+/** The `entityType` every secret declaration carries. */
+export const SECRET_DECLARATION_ENTITY_TYPE = "Chant::SecretProvenance";
+const FORBIDDEN_MATERIAL_FIELDS = [
+    "value",
+    "data",
+    "stringData",
+    "material",
+    "plaintext",
+    "ciphertext",
+];
+/** Narrow a declaration to the committed-encrypted kind. */
+export function isCommittedEncryptedSecret(decl) {
+    return decl.provenance === "committed-encrypted";
+}
+export function declareSecret(input) {
+    if (typeof input.name !== "string" || input.name.length === 0) {
+        throw new Error("declareSecret: `name` must be a non-empty string");
+    }
+    if (!SECRET_PROVENANCE_KINDS.includes(input.provenance)) {
+        throw new Error(`declareSecret("${input.name}"): unknown provenance "${String(input.provenance)}" — ` +
+            `expected one of ${SECRET_PROVENANCE_KINDS.join(", ")}`);
+    }
+    for (const field of FORBIDDEN_MATERIAL_FIELDS) {
+        if (Object.prototype.hasOwnProperty.call(input, field)) {
+            // Name the key only. Never read, log, or echo the value.
+            throw new Error(`declareSecret("${input.name}"): field "${field}" is not allowed — ` +
+                `a secret declaration records provenance, never material`);
+        }
+    }
+    const base = {
+        [DECLARABLE_MARKER]: true,
+        [SECRET_DECLARATION_MARKER]: true,
+        lexicon: "chant",
+        entityType: SECRET_DECLARATION_ENTITY_TYPE,
+        name: input.name,
+    };
+    // Copy known fields per kind explicitly — never spread `input`, so a field
+    // that slipped past the type system still cannot land on the declaration.
+    // The top-level object stays extensible (discovery stamps logical-name and
+    // provenance symbols onto entities); the declared fields themselves are
+    // defined non-writable below, and nested structures are frozen.
+    switch (input.provenance) {
+        case "referenced": {
+            const decl = {
+                ...base,
+                provenance: "referenced",
+                ...(input.scope !== undefined ? { scope: input.scope } : {}),
+            };
+            return lockDeclaredFields(decl);
+        }
+        case "from-provider": {
+            if (typeof input.provider?.binding !== "string" || input.provider.binding.length === 0) {
+                throw new Error(`declareSecret("${input.name}"): from-provider requires \`provider.binding\` ` +
+                    `naming the provider binding entity`);
+            }
+            const decl = {
+                ...base,
+                provenance: "from-provider",
+                provider: Object.freeze({
+                    binding: input.provider.binding,
+                    ...(input.provider.entityType !== undefined ? { entityType: input.provider.entityType } : {}),
+                }),
+            };
+            return lockDeclaredFields(decl);
+        }
+        case "generated-once": {
+            const decl = {
+                ...base,
+                provenance: "generated-once",
+                ...(input.keys !== undefined ? { keys: Object.freeze([...input.keys]) } : {}),
+            };
+            return lockDeclaredFields(decl);
+        }
+        case "committed-encrypted": {
+            const decl = {
+                ...base,
+                provenance: "committed-encrypted",
+                file: validateCiphertextPath(input.name, input.file),
+                encryption: validateEncryption(input.name, input.encryption),
+                ...(input.recipients !== undefined
+                    ? { recipients: Object.freeze(validateRecipients(input.name, input.recipients)) }
+                    : {}),
+                ...(input.keys !== undefined ? { keys: Object.freeze([...input.keys]) } : {}),
+            };
+            return lockDeclaredFields(decl);
+        }
+    }
+}
+/**
+ * Validate the repo-relative ciphertext path. Pure and offline — the factory
+ * never stats the file, because discovery folds project source statically
+ * under `--sandbox` and a factory that touched the filesystem would either
+ * break folding or reintroduce the trust boundary that suite defends. The
+ * file's existence and shape are checked at `buildRoots()` instead.
+ */
+function validateCiphertextPath(name, file) {
+    if (typeof file !== "string" || file.length === 0) {
+        throw new Error(`declareSecret("${name}"): committed-encrypted requires \`file\`, a non-empty ` +
+            `repo-relative path to the committed ciphertext`);
+    }
+    if (file.startsWith("/") || /^[A-Za-z]:[\\/]/.test(file)) {
+        throw new Error(`declareSecret("${name}"): \`file\` must be repo-relative, not absolute — got "${file}"`);
+    }
+    const segments = file.split(/[\\/]/);
+    if (segments.includes("..")) {
+        throw new Error(`declareSecret("${name}"): \`file\` must not escape the project with a ".." segment — ` +
+            `got "${file}"`);
+    }
+    const dot = file.lastIndexOf(".");
+    const extension = dot === -1 ? "" : file.slice(dot).toLowerCase();
+    if (!CIPHERTEXT_FILE_EXTENSIONS.includes(extension)) {
+        throw new Error(`declareSecret("${name}"): \`file\` must be a YAML file ` +
+            `(${CIPHERTEXT_FILE_EXTENSIONS.join(", ")}) — got "${extension || "no extension"}". ` +
+            `Other formats are not emitted byte-for-byte yet.`);
+    }
+    return file;
+}
+/** Validate the encryption tool, defaulting to `"sops"`. */
+function validateEncryption(name, encryption) {
+    if (encryption === undefined)
+        return "sops";
+    if (!SECRET_ENCRYPTION_TOOLS.includes(encryption)) {
+        throw new Error(`declareSecret("${name}"): unknown encryption "${String(encryption)}" — ` +
+            `expected one of ${SECRET_ENCRYPTION_TOOLS.join(", ")}`);
+    }
+    return encryption;
+}
+/**
+ * Copy `recipients`, refusing a private key pasted where a public recipient
+ * belongs. The message names the field and the index — never the value, the
+ * same discipline the forbidden-material check above uses.
+ */
+function validateRecipients(name, recipients) {
+    const copied = [...recipients];
+    copied.forEach((recipient, index) => {
+        if (typeof recipient !== "string" || recipient.length === 0) {
+            throw new Error(`declareSecret("${name}"): \`recipients[${index}]\` must be a non-empty string`);
+        }
+        if (PRIVATE_KEY_MARKERS.some((pattern) => pattern.test(recipient))) {
+            throw new Error(`declareSecret("${name}"): \`recipients[${index}]\` looks like a PRIVATE key — ` +
+                `recipients are public identifiers (age recipients, PGP fingerprints). ` +
+                `Rotate it: it has been in a source file.`);
+        }
+    });
+    return copied;
+}
+/**
+ * Make every declared (string-keyed) field non-writable and non-configurable
+ * without sealing the object — discovery still stamps its own symbol-keyed
+ * metadata (logical name, build provenance) onto entities, which a frozen
+ * object would reject.
+ */
+function lockDeclaredFields(decl) {
+    for (const key of Object.keys(decl)) {
+        Object.defineProperty(decl, key, { writable: false, configurable: false });
+    }
+    return decl;
+}
+/** Type guard for a secret provenance declaration. */
+export function isSecretDeclaration(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        SECRET_DECLARATION_MARKER in value &&
+        value[SECRET_DECLARATION_MARKER] === true);
+}
+/**
+ * Extract the secret declarations from a discovered entity map — the read
+ * surface for lint rules (#1382) and lexicon materializers (#1830). Keyed by
+ * entity name (export name), the same key `DiscoveryResult.entities` uses.
+ */
+export function collectSecretDeclarations(entities) {
+    const out = new Map();
+    for (const [name, entity] of entities) {
+        if (isSecretDeclaration(entity))
+            out.set(name, entity);
+    }
+    return out;
+}

package/dist/serializer-walker.js

@@ -0,0 +1,112 @@
+/**
+ * Generic recursive value walker for lexicon serializers.
+ *
+ * Implements the dispatch chain: null → AttrRef → Intrinsic → Declarable → Array → Object,
+ * delegating format-specific behavior to a SerializerVisitor.
+ */
+import { isPropertyDeclarable } from "./declarable.js";
+import { isHeldElsewhere } from "./held-elsewhere.js";
+import { INTRINSIC_MARKER } from "./intrinsic.js";
+import { isAttrRefLike } from "./utils.js";
+/**
+ * The attribute an `{__attrRef}` envelope names. A fold writes the envelope
+ * with the property it read (`db.Endpoint_Address`), and the property's own
+ * AttrRef carries the attribute (`Endpoint.Address`); they differ when the
+ * attribute has a dot. The envelope's name is kept when the entity or
+ * property is not found.
+ */
+function envelopeAttribute(entityName, property, entityNames) {
+    for (const [entity, name] of entityNames) {
+        if (name !== entityName)
+            continue;
+        const held = entity[property];
+        return isAttrRefLike(held) ? held.attribute : property;
+    }
+    return property;
+}
+/**
+ * Recursively walk a value, converting AttrRefs, Intrinsics, Declarables,
+ * arrays, and objects using the provided visitor.
+ */
+export function walkValue(value, entityNames, visitor) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    // A `heldElsewhere()` marker (#2162) is never written to the applied
+    // payload — the provider defaults the field once at actual creation, and
+    // whoever the declaration names as holder owns it from there. Every apply
+    // this synthesizes therefore omits the field entirely, not only the
+    // first: re-asserting even the field's own value on a later apply would
+    // fight whatever the holder wrote in between. Checked first, ahead of
+    // every other dispatch branch below — a held marker is never an AttrRef,
+    // an Intrinsic, or authored Declarable data.
+    if (isHeldElsewhere(value))
+        return undefined;
+    // Handle AttrRef
+    if (isAttrRefLike(value)) {
+        const name = value.getLogicalName();
+        if (!name) {
+            throw new Error(`Cannot serialize AttrRef for attribute "${value.attribute}": logical name not set`);
+        }
+        return visitor.attrRef(name, value.attribute);
+    }
+    // Handle Intrinsics — walk the toJSON() result to resolve any embedded AttrRef markers
+    if (typeof value === "object" && value !== null && INTRINSIC_MARKER in value) {
+        if ("toJSON" in value && typeof value.toJSON === "function") {
+            return walkValue(value.toJSON(), entityNames, visitor);
+        }
+    }
+    // Handle Declarable references
+    if (typeof value === "object" && value !== null && "entityType" in value) {
+        const decl = value;
+        if (isPropertyDeclarable(decl)) {
+            return visitor.propertyDeclarable(decl, (v) => walkValue(v, entityNames, visitor));
+        }
+        const name = entityNames.get(decl);
+        if (name) {
+            return visitor.resourceRef(name);
+        }
+        // A resource-kind Declarable constructed inline rather than exported as
+        // its own top-level entity (e.g. K8s `new PersistentVolumeClaim({...})`
+        // embedded directly in a StatefulSet's `volumeClaimTemplates`) has no
+        // logical name to Ref — it was never a key in `entities`, so
+        // resolveAttrRefs() never assigns one. Falling through to the generic
+        // "object" branch below would walk the Declarable's own enumerable
+        // properties, which for a Declarable are its self-referencing attribute
+        // accessors (AttrRef instances whose parent is the Declarable itself,
+        // still unresolved) — never its authored `.props`. That either threw
+        // "logical name not set" (when the resource type declares any
+        // attributes) or silently serialized as `{}` (when it doesn't), instead
+        // of the embedded spec the caller wrote. Embed its own props inline
+        // instead, exactly like a property-kind Declarable already does.
+        return visitor.propertyDeclarable(decl, (v) => walkValue(v, entityNames, visitor));
+    }
+    // Handle arrays. A held marker element is filtered out before recursing —
+    // `walkValue` would return `undefined` for it too, but leaving it in the
+    // array would emit a hole (`[a, null, b]`) rather than omitting it.
+    if (Array.isArray(value)) {
+        return value
+            .filter((item) => !isHeldElsewhere(item))
+            .map((item) => walkValue(item, entityNames, visitor));
+    }
+    // Handle serialized AttrRef envelopes (produced by AttrRef.toJSON() inside intrinsics)
+    if (typeof value === "object" && "__attrRef" in value) {
+        const ref = value.__attrRef;
+        return visitor.attrRef(ref.entity, envelopeAttribute(ref.entity, ref.attribute, entityNames));
+    }
+    // Handle objects
+    if (typeof value === "object") {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            // A held marker key is omitted entirely (#2162), not set to
+            // `undefined` — the two read differently to a YAML emitter, and only
+            // omission is "the provider never hears about this field".
+            if (isHeldElsewhere(val))
+                continue;
+            const outKey = key;
+            result[outKey] = walkValue(val, entityNames, visitor);
+        }
+        return result;
+    }
+    return value;
+}

package/dist/serializer.js

@@ -0,0 +1 @@
+export {};

package/dist/sort.js

@@ -0,0 +1,45 @@
+import { BuildError } from "./errors.js";
+import { detectCycles } from "./discovery/cycles.js";
+/**
+ * Performs a topological sort on a dependency graph
+ * @param dependencies - Record where keys are entity names and values are arrays of their dependencies
+ * @returns Array of entity names in topological order (dependencies appear before dependents)
+ * @throws {BuildError} If a cycle is detected in the dependency graph
+ */
+export function topologicalSort(dependencies) {
+    // Check for cycles first
+    const cycles = detectCycles(dependencies);
+    if (cycles.length > 0) {
+        const cycleStr = cycles[0].join(" -> ");
+        throw new BuildError(cycles[0][0], `Circular dependency detected: ${cycleStr}`);
+    }
+    const sorted = [];
+    const visited = new Set();
+    const visiting = new Set();
+    /**
+     * DFS helper for topological sort
+     * @param node - Current node being visited
+     */
+    function visit(node) {
+        if (visited.has(node)) {
+            return;
+        }
+        visiting.add(node);
+        const deps = dependencies[node] || [];
+        for (const dep of deps) {
+            if (!visited.has(dep)) {
+                visit(dep);
+            }
+        }
+        visiting.delete(node);
+        visited.add(node);
+        sorted.push(node);
+    }
+    // Visit all nodes
+    for (const node of Object.keys(dependencies)) {
+        if (!visited.has(node)) {
+            visit(node);
+        }
+    }
+    return sorted;
+}

package/dist/stack-output.js

@@ -0,0 +1,115 @@
+/**
+ * Stack Output — marks a value for cross-stack export.
+ *
+ * When a child project declares `stackOutput(ref)`, the serializer emits
+ * it into the template's Outputs section. The parent can then reference
+ * it via `nestedStack().outputs.name`.
+ */
+import { DECLARABLE_MARKER, isDeclarable } from "./declarable.js";
+import { isIntrinsic } from "./intrinsic.js";
+import { isAttrRefLike } from "./utils.js";
+/**
+ * Marker symbol for stack output identification.
+ */
+export const STACK_OUTPUT_MARKER = Symbol.for("chant.stackOutput");
+/** Find the first AttrRef or directly-referenced Declarable anywhere inside a
+ * value (walking intrinsics/objects/arrays), so a wrapping intrinsic can
+ * still borrow its source's lexicon. Duck-type, not `instanceof` (chant
+ * #1137): a lexicon built against a separate copy of `@intentius/chant`
+ * produces AttrRefs/Declarables that fail `instanceof` here but carry the
+ * same shape (`isDeclarable`'s `Symbol.for` marker is already dual-copy-safe
+ * on its own) — missing one would make the walk recurse into its own
+ * (unhelpful) fields instead of stopping on it, silently failing to find the
+ * anchor. */
+function findAnchor(value, seen = new Set()) {
+    if (value === null || typeof value !== "object" || seen.has(value))
+        return undefined;
+    if (isAttrRefLike(value))
+        return { kind: "attrRef", ref: value };
+    if (isDeclarable(value))
+        return { kind: "declarable", entity: value };
+    seen.add(value);
+    const children = Array.isArray(value) ? value : Object.values(value);
+    for (const child of children) {
+        const found = findAnchor(child, seen);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/** Derive the lexicon an anchor belongs to: an AttrRef borrows its (deref'd)
+ * parent's `.lexicon`; a directly-referenced Declarable reports its own. */
+function anchorLexicon(anchor) {
+    if (!anchor)
+        return "unknown";
+    if (anchor.kind === "declarable")
+        return anchor.entity.lexicon;
+    const parent = anchor.ref.parent.deref();
+    return parent && typeof parent.lexicon === "string"
+        ? parent.lexicon
+        : "unknown";
+}
+/**
+ * Type guard for StackOutput.
+ */
+export function isStackOutput(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        STACK_OUTPUT_MARKER in value &&
+        value[STACK_OUTPUT_MARKER] === true);
+}
+/**
+ * Create a stack output that exports an attribute reference for cross-stack use.
+ *
+ * @param ref - The AttrRef to export (e.g. `vpc.vpcId`)
+ * @param options - Optional description for the output
+ * @returns A StackOutput Declarable
+ *
+ * @example
+ * ```ts
+ * import { stackOutput } from "@intentius/chant";
+ * import { vpc, subnet } from "./vpc";
+ *
+ * export const vpcId = stackOutput(vpc.vpcId);
+ * export const subnetId = stackOutput(subnet.subnetId, {
+ *   description: "Primary subnet ID",
+ * });
+ * ```
+ */
+export function stackOutput(ref, options) {
+    // Duck-type, not `instanceof` (chant #1137): AttrRef also implements
+    // Intrinsic (a global-symbol marker), so `isIntrinsic(ref)` alone already
+    // happens to accept a foreign-copy AttrRef here — this check would not
+    // misfire even with the raw `instanceof` left in. It is converted anyway
+    // so the guard's own logic states the invariant explicitly ("ref must be
+    // AttrRef-like or Intrinsic") rather than relying on that coincidence,
+    // matching the anchor selection right below it, which does misbehave.
+    if (typeof ref !== "string" && !isAttrRefLike(ref) && !isIntrinsic(ref)) {
+        throw new Error("stackOutput(ref): ref must be an attribute reference, an intrinsic wrapping one, or a literal string");
+    }
+    if (typeof ref === "string" && !options?.lexicon) {
+        throw new Error("stackOutput(literal): a literal output has no entity to derive its lexicon from — pass options.lexicon");
+    }
+    // Derive lexicon from the referenced entity — for a bare AttrRef, its parent;
+    // for an intrinsic (Join etc.), the first AttrRef or directly-referenced
+    // Declarable nested inside it (chant #1152: `Ref(param)`/`Ref(resource)`
+    // wrap the entity itself, not one of its attributes). A foreign-copy
+    // AttrRef/Declarable failing raw `instanceof` here would fall to
+    // `findAnchor`, which (before its own #1137 fix) would also miss it —
+    // silently anchoring on nothing and recording `lexicon: "unknown"`.
+    const anchor = typeof ref === "string" ? undefined : isAttrRefLike(ref) ? { kind: "attrRef", ref } : findAnchor(ref);
+    const lexicon = options?.lexicon ?? anchorLexicon(anchor);
+    const output = {
+        [STACK_OUTPUT_MARKER]: true,
+        [DECLARABLE_MARKER]: true,
+        lexicon,
+        entityType: "chant:output",
+        kind: "output",
+        sourceRef: ref,
+        description: options?.description,
+        exportName: options?.exportName,
+        condition: options?.condition,
+        ...(options?.name !== undefined ? { name: options.name } : {}),
+    };
+    return output;
+}