@intentius/chant 0.124.52 → 0.124.54

package/dist/lifecycle/derive-edges.js

@@ -0,0 +1,126 @@
+import { containmentGroups, reconstructIdentityEdges, reconstructIndexedEdges, } from "../graph-refs.js";
+import { indexDocumentDigest } from "./index-document.js";
+/** Locations that hold global types: AWS's `global`, Kubernetes' cluster-scoped objects. */
+const GLOBAL_LOCATIONS = new Set(["global", "cluster", ""]);
+/** The scope an indexed node's identifiers are unique in, from its document's stamp and its own location. */
+export function indexedNodeScope(doc, node) {
+    const scope = doc.stamp.scope;
+    const account = scope.kind === "cloud" ? `${scope.substrate}/${scope.scopeId}` : doc.stamp.scopeKey;
+    const location = node.location ?? "";
+    return GLOBAL_LOCATIONS.has(location) ? { account } : { account, region: location };
+}
+const byString = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function noteKey(n) {
+    return `${n.kind}\u0000${n.listedType ?? ""}\u0000${n.location ?? ""}\u0000${n.message}`;
+}
+/** Derived edges over one index document. */
+export function deriveEdges(doc, lexicons) {
+    return deriveEdgesAcross([doc], lexicons)[0];
+}
+/**
+ * Derived edges over every document of one account from one read (behold#1023
+ * Q7): regional documents and an account-level one for global types, or the
+ * single document a `behold index` run writes (behold#1025 Q6). The documents
+ * must be cloud reads of one substrate and scope id with one `observedAt`;
+ * anything else is refused, because joining two reads would carry a name from
+ * one read to an object of another.
+ */
+export function deriveEdgesAcross(docs, lexicons) {
+    if (docs.length === 0)
+        return [];
+    const first = docs[0].stamp;
+    for (const d of docs) {
+        const s = d.stamp.scope;
+        if (s.kind !== "cloud" || first.scope.kind !== "cloud") {
+            throw new Error(`derived edges run over cloud index documents; ${d.stamp.scopeKey} is a ${s.kind} source`);
+        }
+        if (s.substrate !== first.scope.substrate || s.scopeId !== first.scope.scopeId) {
+            throw new Error(`derived edges run over one account: ${first.scope.substrate}/${first.scope.scopeId} and ${s.substrate}/${s.scopeId} are two`);
+        }
+        if (d.stamp.observedAt !== first.observedAt) {
+            throw new Error(`derived edges run over one read: ${first.observedAt} and ${d.stamp.observedAt} are two`);
+        }
+    }
+    const named = [...lexicons]
+        .filter((l) => l.referenceCatalog !== undefined)
+        .sort((a, b) => byString(a.name, b.name))
+        .map((l) => ({ lexicon: l.name, catalog: l.referenceCatalog }));
+    const withCatalog = new Set(named.map((c) => c.lexicon));
+    const holderDoc = new Map();
+    const scopes = new Map();
+    const all = [];
+    docs.forEach((d, i) => {
+        for (const n of d.graph.nodes) {
+            holderDoc.set(n.id, i);
+            scopes.set(n.id, indexedNodeScope(d, n));
+            all.push(n);
+        }
+    });
+    const derived = reconstructIndexedEdges(all, named, (n) => scopes.get(n.id));
+    const owners = [...lexicons]
+        .filter((l) => l.indexIdentity !== undefined)
+        .sort((a, b) => byString(a.name, b.name))
+        .map((l) => ({ lexicon: l.name, ...(l.indexIdentity.nodeIdentities ? { identities: l.indexIdentity.nodeIdentities } : {}) }));
+    const identity = owners.length > 0
+        ? reconstructIdentityEdges(all, owners, (n) => scopes.get(n.id), derived.edges)
+        : { edges: [], ambiguous: [] };
+    return docs.map((d, i) => {
+        const mine = (from) => holderDoc.get(from) === i;
+        const edges = [...d.graph.edges.filter((e) => e.origin !== "derived"), ...derived.edges.filter((e) => mine(e.from)), ...identity.edges.filter((e) => mine(e.from))];
+        const pairs = derived.containment.filter((p) => mine(p.child));
+        const dangling = new Map();
+        for (const r of [
+            ...(d.graph.dangling ?? []),
+            ...derived.dangling.filter((x) => mine(x.from)).map((x) => ({ from: x.from, kind: "ref", path: x.path, value: x.value })),
+        ]) {
+            dangling.set(`${r.from}\u0000${r.kind}\u0000${r.path}\u0000${r.value}`, r);
+        }
+        const notes = (d.notes ?? []).filter((n) => n.kind !== "no-catalog" && n.kind !== "ambiguous-reference" && n.kind !== "ambiguous-identity");
+        for (const a of derived.ambiguous.filter((x) => mine(x.from))) {
+            notes.push({
+                kind: "ambiguous-reference",
+                message: `${a.from} ${a.path} = ${JSON.stringify(a.value)} matches ${a.candidates.length} nodes (${a.candidates.join(", ")}); rule ${a.rule} drew no edge`,
+            });
+        }
+        for (const a of identity.ambiguous.filter((x) => mine(x.from))) {
+            notes.push({
+                kind: "ambiguous-identity",
+                message: `${a.from} ${a.path} = ${JSON.stringify(a.value)} names ${a.candidates.length} nodes (${a.candidates.join(", ")}); the identity-match pass drew no edge`,
+            });
+        }
+        const counts = new Map();
+        for (const n of d.graph.nodes)
+            if (!n.unmappedKind)
+                counts.set(n.lexicon, (counts.get(n.lexicon) ?? 0) + 1);
+        for (const lexicon of [...counts.keys()].sort()) {
+            if (withCatalog.has(lexicon))
+                continue;
+            notes.push({
+                kind: "no-catalog",
+                message: `the ${lexicon} lexicon has no referenceCatalog, so its ${counts.get(lexicon)} node(s) have no derived edges`,
+            });
+        }
+        notes.sort((a, b) => byString(noteKey(a), noteKey(b)));
+        const groups = { ...d.graph.groups };
+        const byContainer = containmentGroups(pairs);
+        if (Object.keys(byContainer).length > 0)
+            groups.byContainer = byContainer;
+        else
+            delete groups.byContainer;
+        const graph = { ...d.graph, edges, groups };
+        if (dangling.size > 0)
+            graph.dangling = [...dangling.values()];
+        else
+            delete graph.dangling;
+        const out = {
+            ...d,
+            stamp: { ...d.stamp, digest: indexDocumentDigest({ graph, coverage: d.coverage }) },
+            graph,
+        };
+        if (notes.length > 0)
+            out.notes = notes;
+        else
+            delete out.notes;
+        return out;
+    });
+}

package/dist/lifecycle/git.d.ts

@@ -124,26 +124,28 @@ export declare function snapshotStorageKey(lexicon: string, stack?: string): str
 /**
  * Write a state snapshot JSON to the orphan branch.
  *
+ * Nothing in chant calls this since #4519: snapshots go through the index
+ * store (./snapshot-store.ts), whose default is `refs/chant/snapshots`. Kept
+ * for code outside chant that wrote snapshots here itself.
+ *
  * Pipeline: hash-object → mktree → commit-tree → update-ref
  */
 export declare function writeSnapshot(environment: string, lexicon: string, json: string, opts?: {
     cwd?: string;
 }): Promise<string>;
 /**
- * Read a snapshot from the orphan branch.
+ * Read a snapshot from the orphan branch. Since #4519 this is the read side
+ * of the read-only orphan-branch store (./snapshot-store.ts); chant's own
+ * readers go through the store.
  */
-export declare function readSnapshot(environment: string, lexicon: string, opts?: {
-    cwd?: string;
-}): Promise<string | null>;
+export declare function readSnapshot(environment: string, lexicon: string, opts?: LedgerLocation): Promise<string | null>;
 /**
  * Read a snapshot at a specific orphan-branch commit (#822). `readSnapshot` reads
  * the branch tip; this reads `<ref>:<env>/<lexicon>.json` for any commit `ref`
  * (as listed by {@link listSnapshots}), so two historical snapshots can be diffed.
  * Returns null if that env/lexicon wasn't captured at `ref`.
  */
-export declare function readSnapshotAt(environment: string, lexicon: string, ref: string, opts?: {
-    cwd?: string;
-}): Promise<string | null>;
+export declare function readSnapshotAt(environment: string, lexicon: string, ref: string, opts?: LedgerLocation): Promise<string | null>;
 /**
  * Append one immutable release record line to `<environment>/releases.jsonl`
  * on the orphan branch (#568, epic #551 "Build & deploy observability"). Same
@@ -227,8 +229,7 @@ export declare function readEnvironmentSnapshots(environment: string, opts?: {
 /**
  * List snapshot history from the orphan branch.
  */
-export declare function listSnapshots(opts?: {
-    cwd?: string;
+export declare function listSnapshots(opts?: LedgerLocation & {
     environment?: string;
 }): Promise<Array<{
     commit: string;

package/dist/lifecycle/git.d.ts.map

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

package/dist/lifecycle/git.js

@@ -382,13 +382,19 @@ export function snapshotStorageKey(lexicon, stack) {
 /**
  * Write a state snapshot JSON to the orphan branch.
  *
+ * Nothing in chant calls this since #4519: snapshots go through the index
+ * store (./snapshot-store.ts), whose default is `refs/chant/snapshots`. Kept
+ * for code outside chant that wrote snapshots here itself.
+ *
  * Pipeline: hash-object → mktree → commit-tree → update-ref
  */
 export async function writeSnapshot(environment, lexicon, json, opts) {
     return writeBlobToPath(environment, `${lexicon}.json`, json, "State snapshot", opts);
 }
 /**
- * Read a snapshot from the orphan branch.
+ * Read a snapshot from the orphan branch. Since #4519 this is the read side
+ * of the read-only orphan-branch store (./snapshot-store.ts); chant's own
+ * readers go through the store.
  */
 export async function readSnapshot(environment, lexicon, opts) {
     return readBlobFromPath(environment, `${lexicon}.json`, opts);

package/dist/lifecycle/identity-match.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Declared entities matched to indexed resources by identity (#4523, tier 2
+ * of INTENTIUS/behold#1025, rule written out on behold#1025's design comment,
+ * join rules ruled on behold#1023 2026-10-26).
+ *
+ * A lexicon whose live read needs a stack chant deployed (aws: the
+ * CloudFormation stack named after the environment) cannot see source that
+ * was never deployed. Its identity fallback (#1647, lexicons/aws/src/
+ * identity-observe.ts) asks Cloud Control `GetResource` for the identifier
+ * the declared props spell. {@link matchDeclaredToIndex} is that rule run
+ * against an index version instead of a live call:
+ *
+ *     A declared entity of type T with props P matches the indexed node whose
+ *     `listedType` is T, whose `location` is the entity's region (or `global`
+ *     for a global type), and whose `nativeId` equals the identifier P spells.
+ *
+ * - one node binds;
+ * - two or more are refused, naming every candidate. A refusal never reads
+ *   as absent or as bound;
+ * - no node is absent only when the index's coverage lists (T, location) as
+ *   `listed` ({@link indexCoverageFor}, where `"*"` matches every type or
+ *   location). Otherwise the entity is not observed, with the coverage's
+ *   reason: `filtered` when the scope left the type or location out (or the
+ *   read had a tag filter, which cannot tell an untagged object from a
+ *   missing one), `not-reached` when nothing covered it;
+ * - an identity the declaration does not spell (a server-assigned id such as
+ *   an instance id or a queue URL, a Ref, an intrinsic) cannot match: not
+ *   observed, reason `no-binding`.
+ *
+ * The lexicon says how its props spell an identifier ({@link IndexIdentity},
+ * a plugin's `indexIdentity`); this module holds the rule. Pure.
+ */
+import type { IRNode } from "../graph-ir.js";
+import type { NodeIdentityValue } from "../graph-refs.js";
+import type { UnobservedReason } from "../observation.js";
+import { type CloudIndexScope, type IndexDocument } from "./index-document.js";
+/** What a declared entity's props say about its identity. */
+export type DeclaredIdentity = {
+    kind: "identifier";
+    /** The inventory API's type name the identifier belongs to (the CloudFormation type for aws). */
+    listedType: string;
+    /** The identifier as the index's `nativeId` spells it (Cloud Control's, `|`-joined for a multi-part one). */
+    identifier: string;
+    /** A global type is indexed once per account at location `global`. */
+    global: boolean;
+} | {
+    kind: "unmatchable";
+    /** `no-binding` for an identity the declaration does not spell; `unsupported-kind` for a type with none on record. */
+    reason: UnobservedReason;
+    detail: string;
+};
+/**
+ * How a lexicon matches its declared entities to its substrate's indexed
+ * nodes (a plugin's `indexIdentity`). Data plus pure functions.
+ */
+export interface IndexIdentity {
+    substrate: CloudIndexScope["substrate"];
+    /** The identifier a declared entity's props spell, or why there is none. */
+    declaredIdentity(entityType: string, props: Record<string, unknown>): DeclaredIdentity;
+    /**
+     * The values that name an indexed node of this lexicon, for the
+     * identity-match edge pass (../graph-refs.ts `reconstructIdentityEdges`).
+     * Absent: its native id and its ARN cloud ids.
+     */
+    nodeIdentities?(node: IRNode): NodeIdentityValue[];
+}
+/** One declared entity, as the build output names it. */
+export interface DeclaredEntity {
+    name: string;
+    entityType: string;
+    props: Record<string, unknown>;
+    /** The entity's region; falls back to the match's `region` option. */
+    region?: string;
+}
+interface MatchBase {
+    entity: string;
+    entityType: string;
+}
+/** The verdict for one declared entity. */
+export type IdentityMatch = (MatchBase & {
+    verdict: "bound";
+    identifier: string;
+    listedType: string;
+    location: string;
+    node: string;
+    nativeId: string;
+}) | (MatchBase & {
+    verdict: "refused";
+    identifier: string;
+    listedType: string;
+    candidates: string[];
+    detail: string;
+}) | (MatchBase & {
+    verdict: "absent";
+    identifier: string;
+    listedType: string;
+    location: string;
+}) | (MatchBase & {
+    verdict: "not-observed";
+    reason: UnobservedReason;
+    detail: string;
+    identifier?: string;
+    listedType?: string;
+    location?: string;
+});
+export interface IdentityMatchResult {
+    /** Keyed by entity name, in name order. */
+    matches: Record<string, IdentityMatch>;
+}
+export interface MatchOptions {
+    /** The region of an entity that names none. */
+    region?: string;
+}
+/**
+ * Whether the index looked at (type, location), from its coverage. `listed`
+ * means a missing node is absent; anything else is a reason it is not
+ * observed.
+ */
+export declare function indexCoverageVerdict(docs: readonly IndexDocument[], listedType: string, location: string): {
+    listed: true;
+} | {
+    listed: false;
+    reason: UnobservedReason;
+    detail: string;
+};
+/**
+ * Match each declared entity to the index by identity. `docs` are the
+ * documents of one read of one account (one `behold index` run, or its
+ * regional and account-level documents); `identity` is the lexicon's.
+ */
+export declare function matchDeclaredToIndex(entities: readonly DeclaredEntity[], docs: readonly IndexDocument[], identity: IndexIdentity, options?: MatchOptions): IdentityMatchResult;
+export {};
+//# sourceMappingURL=identity-match.d.ts.map

package/dist/lifecycle/identity-match.d.ts.map

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

package/dist/lifecycle/identity-match.js

@@ -0,0 +1,147 @@
+import { indexCoverageFor } from "./index-document.js";
+const byString = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** The documents must be cloud reads of one substrate, one account and one read, or a candidate from another read would bind. */
+function cloudScopes(docs, substrate) {
+    const scopes = [];
+    for (const d of docs) {
+        const s = d.stamp.scope;
+        if (s.kind !== "cloud")
+            throw new Error(`identity matching reads cloud index documents; ${d.stamp.scopeKey} is a ${s.kind} source`);
+        if (s.substrate !== substrate)
+            throw new Error(`identity matching for ${substrate} was given a ${s.substrate} index (${d.stamp.scopeKey})`);
+        scopes.push(s);
+    }
+    for (const d of docs) {
+        const s = d.stamp.scope;
+        if (s.scopeId !== scopes[0].scopeId)
+            throw new Error(`identity matching runs over one account: ${scopes[0].scopeId} and ${s.scopeId} are two`);
+        if (d.stamp.observedAt !== docs[0].stamp.observedAt) {
+            throw new Error(`identity matching runs over one read: ${docs[0].stamp.observedAt} and ${d.stamp.observedAt} are two`);
+        }
+    }
+    return scopes;
+}
+function scopeIncludes(list, value) {
+    return list === "*" || list.includes(value);
+}
+/**
+ * Whether the index looked at (type, location), from its coverage. `listed`
+ * means a missing node is absent; anything else is a reason it is not
+ * observed.
+ */
+export function indexCoverageVerdict(docs, listedType, location) {
+    let firstRefusal;
+    let tagFiltered;
+    let scoped = false;
+    for (const d of docs) {
+        const scope = d.stamp.scope;
+        if (scope.kind !== "cloud")
+            continue;
+        const entry = indexCoverageFor(d.coverage, listedType, location);
+        if (entry?.verdict === "listed") {
+            if (scope.tagFilter && Object.keys(scope.tagFilter).length > 0) {
+                tagFiltered ?? (tagFiltered = Object.entries(scope.tagFilter).map(([k, v]) => `${k}=${v}`).join(","));
+                continue;
+            }
+            return { listed: true };
+        }
+        if (entry && !firstRefusal) {
+            firstRefusal = {
+                reason: entry.verdict,
+                detail: entry.detail ?? `the index read ${listedType} in ${location} as ${entry.verdict}`,
+            };
+        }
+        // A global type sits at location `global`, which a region list never names.
+        if (scopeIncludes(scope.types, listedType) && (location === "global" || scopeIncludes(scope.locations, location)))
+            scoped = true;
+    }
+    if (firstRefusal)
+        return { listed: false, ...firstRefusal };
+    if (tagFiltered !== undefined) {
+        return {
+            listed: false,
+            reason: "filtered",
+            detail: `the index listed ${listedType} in ${location} under the tag filter ${tagFiltered}, so an untagged object and a missing one look the same`,
+        };
+    }
+    if (!scoped)
+        return { listed: false, reason: "filtered", detail: `the index scope left out ${listedType} in ${location}` };
+    return { listed: false, reason: "not-reached", detail: `the index has no coverage for ${listedType} in ${location}` };
+}
+/** The node's listed type: `listedType` on an indexed node, else its kind. */
+const listedTypeOf = (n) => n.listedType ?? n.kind;
+/**
+ * Match each declared entity to the index by identity. `docs` are the
+ * documents of one read of one account (one `behold index` run, or its
+ * regional and account-level documents); `identity` is the lexicon's.
+ */
+export function matchDeclaredToIndex(entities, docs, identity, options = {}) {
+    cloudScopes(docs, identity.substrate);
+    // listedType -> nativeId -> nodes
+    const byIdentity = new Map();
+    for (const d of docs) {
+        for (const n of d.graph.nodes) {
+            if (n.nativeId === undefined)
+                continue;
+            const t = listedTypeOf(n);
+            const m = byIdentity.get(t) ?? byIdentity.set(t, new Map()).get(t);
+            (m.get(n.nativeId) ?? m.set(n.nativeId, []).get(n.nativeId)).push(n);
+        }
+    }
+    const matches = {};
+    for (const entity of [...entities].sort((a, b) => byString(a.name, b.name))) {
+        const base = { entity: entity.name, entityType: entity.entityType };
+        const declared = identity.declaredIdentity(entity.entityType, entity.props ?? {});
+        if (declared.kind === "unmatchable") {
+            matches[entity.name] = { ...base, verdict: "not-observed", reason: declared.reason, detail: declared.detail };
+            continue;
+        }
+        const { listedType, identifier } = declared;
+        const region = entity.region ?? options.region;
+        const location = declared.global ? "global" : region;
+        const all = byIdentity.get(listedType)?.get(identifier) ?? [];
+        const inScope = location === undefined ? all : all.filter((n) => n.location === location);
+        const candidates = [...new Set(inScope.map((n) => n.id))].sort(byString);
+        if (candidates.length > 1) {
+            matches[entity.name] = {
+                ...base,
+                verdict: "refused",
+                identifier,
+                listedType,
+                candidates,
+                detail: `${listedType} ${identifier} names ${candidates.length} indexed resources (${candidates.join(", ")}); none is bound`,
+            };
+            continue;
+        }
+        if (candidates.length === 1) {
+            const node = inScope.find((n) => n.id === candidates[0]);
+            matches[entity.name] = {
+                ...base,
+                verdict: "bound",
+                identifier,
+                listedType,
+                location: node.location ?? location ?? "",
+                node: node.id,
+                nativeId: node.nativeId,
+            };
+            continue;
+        }
+        if (location === undefined) {
+            // No region, so there is no (type, location) whose coverage could make absence true.
+            matches[entity.name] = {
+                ...base,
+                verdict: "not-observed",
+                reason: "no-binding",
+                detail: `${entity.name} names no region and no match option gives one, so absence of ${listedType} ${identifier} cannot be scoped`,
+                identifier,
+                listedType,
+            };
+            continue;
+        }
+        const coverage = indexCoverageVerdict(docs, listedType, location);
+        matches[entity.name] = coverage.listed
+            ? { ...base, verdict: "absent", identifier, listedType, location }
+            : { ...base, verdict: "not-observed", reason: coverage.reason, detail: coverage.detail, identifier, listedType, location };
+    }
+    return { matches };
+}