@intentius/chant 0.124.52 → 0.124.54

package/src/lifecycle/derive-edges.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, test } from "vitest";
+import type { ReferenceCatalog } from "../graph-refs";
+import type { IndexDocument } from "./index-document";
+import { validateIndexDocument } from "./index-document";
+import { deriveEdges, deriveEdgesAcross, type EdgeLexicon } from "./derive-edges";
+import { typeListing, type ListedResource, type ListingLexicon, type ListingResult } from "./type-listing";
+
+// #4522, to the rules ruled on INTENTIUS/behold#1023 (2026-10-26).
+const catalog: ReferenceCatalog = {
+  identities: [
+    { kind: "Db::SubnetGroup", ids: ["Name"] },
+    { kind: "Iam::Role", ids: ["RoleName"] },
+    { kind: "Logs::Group", ids: ["GroupName"] },
+    { kind: "Svc::Cluster", ids: ["ClusterName"] },
+    { kind: "Eks::Cluster", ids: ["Name"] },
+  ],
+  refs: [
+    { from: "Db::Instance", path: "SubnetGroupName", targetKind: "Db::SubnetGroup", relation: "reference", label: "subnets" },
+    { from: "Task::Definition", path: "TaskRoleArn", targetKind: "Iam::Role", relation: "reference", label: "role" },
+    // Untargeted, the shape #1023 found false joins in: a name could be anything's.
+    { from: "Svc::Service", path: "Cluster", relation: "reference", label: "in cluster" },
+    { from: "Net::Subnet", path: "VpcId", targetKind: "Net::Vpc", relation: "containment", label: "in VPC" },
+  ],
+  tagRefs: [{ key: "kubernetes.io/cluster/", read: "key-suffix", targetKind: "Eks::Cluster" }],
+};
+
+const KINDS = ["Db::Instance", "Db::SubnetGroup", "Iam::Role", "Logs::Group", "Svc::Cluster", "Svc::Service", "Task::Definition", "Net::Subnet", "Net::Vpc", "Eks::Cluster"];
+const typing: ListingLexicon[] = [{ name: "fake", listedTypes: { substrate: "aws", kindFor: (t) => (KINDS.includes(t) ? t : undefined) } }];
+const lexicons: EdgeLexicon[] = [{ name: "fake", referenceCatalog: catalog }];
+
+const r = (listedType: string, location: string, nativeId: string, properties: Record<string, unknown>, extra: Partial<ListedResource> = {}): ListedResource => ({
+  listedType,
+  location,
+  nativeId,
+  cloudIds: [{ kind: "import-id", value: nativeId }],
+  tags: {},
+  properties,
+  observedAt: "2026-10-26T09:00:01.000Z",
+  ...extra,
+});
+
+const RESOURCES: ListedResource[] = [
+  r("Db::Instance", "us-east-1", "orders", { SubnetGroupName: "default" }),
+  r("Db::SubnetGroup", "us-east-1", "default", { Name: "default" }),
+  r("Db::SubnetGroup", "us-west-2", "default", { Name: "default" }),
+  r("Iam::Role", "global", "app", { RoleName: "app" }, { cloudIds: [{ kind: "arn", value: "arn:aws:iam::000000000000:role/app" }, { kind: "import-id", value: "app" }] }),
+  r("Task::Definition", "us-east-1", "arn:aws:ecs:us-east-1:000000000000:task-definition/web:1", { TaskRoleArn: "arn:aws:iam::000000000000:role/app" }),
+  r("Svc::Cluster", "us-east-1", "default", { ClusterName: "default" }),
+  r("Logs::Group", "us-east-1", "default", { GroupName: "default" }),
+  r("Svc::Service", "us-east-1", "web", { Cluster: "default" }),
+  r("Net::Vpc", "us-east-1", "vpc-1", {}),
+  r("Net::Subnet", "us-east-1", "subnet-1", { VpcId: "vpc-1" }, { tags: { "kubernetes.io/cluster/prod": "shared", team: "prod" } }),
+  r("Net::Subnet", "us-east-1", "subnet-2", { VpcId: "vpc-gone" }),
+  r("Eks::Cluster", "us-east-1", "prod", { Name: "prod" }),
+  // A node whose value equals the cluster's name, only by its tag value: tags never join by value.
+  r("Logs::Group", "us-east-1", "team", { GroupName: "team" }),
+];
+
+function listing(resources: ListedResource[], extra: Partial<ListingResult> = {}): ListingResult {
+  return {
+    listing: "v1",
+    source: { name: "behold-lister", version: "0.0.0-test" },
+    scope: { substrate: "aws", scopeId: "000000000000", locations: ["us-east-1", "us-west-2"], types: "*" },
+    startedAt: "2026-10-26T09:00:00.000Z",
+    completedAt: "2026-10-26T09:00:04.000Z",
+    resources,
+    coverage: [{ listedType: "*", location: "*", verdict: "listed" }],
+    notes: [],
+    ...extra,
+  };
+}
+
+const id = (location: string, type: string, nativeId: string) => `aws/000000000000/${location}/${type}/${nativeId}`;
+const pairsOf = (doc: IndexDocument) => doc.graph.edges.map((e) => `${e.from} -> ${e.to} [${e.viaAttr}] ${e.relation} ${e.rule}`);
+
+describe("deriveEdges", () => {
+  const doc = deriveEdges(typeListing(listing(RESOURCES), typing), lexicons);
+
+  test("every edge is derived, with its rule and property grain", () => {
+    expect(doc.graph.edges.length).toBeGreaterThan(0);
+    for (const e of doc.graph.edges) {
+      expect(e).toMatchObject({ kind: "ref", origin: "derived", grain: "property" });
+      expect(e.rule).toMatch(/^fake:/);
+    }
+    expect(() => validateIndexDocument(doc)).not.toThrow();
+  });
+
+  test("the join key is scoped: a name joins in its own region, and a global type by account", () => {
+    expect(pairsOf(doc)).toEqual(
+      expect.arrayContaining([
+        `${id("us-east-1", "Db::Instance", "orders")} -> ${id("us-east-1", "Db::SubnetGroup", "default")} [SubnetGroupName] reference fake:Db::Instance:SubnetGroupName`,
+        `${id("us-east-1", "Task::Definition", "arn:aws:ecs:us-east-1:000000000000:task-definition/web:1")} -> ${id("global", "Iam::Role", "app")} [TaskRoleArn] reference fake:Task::Definition:TaskRoleArn`,
+      ]),
+    );
+    expect(pairsOf(doc).some((p) => p.includes(id("us-west-2", "Db::SubnetGroup", "default")))).toBe(false);
+  });
+
+  test("a value matching several nodes draws no edge and is noted with every candidate", () => {
+    const service = id("us-east-1", "Svc::Service", "web");
+    expect(doc.graph.edges.some((e) => e.from === service)).toBe(false);
+    const note = doc.notes?.find((n) => n.kind === "ambiguous-reference");
+    expect(note?.message).toContain(service);
+    expect(note?.message).toContain(id("us-east-1", "Svc::Cluster", "default"));
+    expect(note?.message).toContain(id("us-east-1", "Logs::Group", "default"));
+    expect(note?.message).toContain("fake:Svc::Service:Cluster");
+  });
+
+  test("containment is an edge with its relation, and a box in groups.byContainer", () => {
+    const subnet = id("us-east-1", "Net::Subnet", "subnet-1");
+    const vpc = id("us-east-1", "Net::Vpc", "vpc-1");
+    expect(doc.graph.edges).toContainEqual(expect.objectContaining({ from: subnet, to: vpc, viaAttr: "VpcId", relation: "containment" }));
+    expect(doc.graph.groups.byContainer?.[vpc]).toEqual([subnet]);
+  });
+
+  test("a reference to nothing in the index is dangling, never an edge", () => {
+    expect(doc.graph.dangling).toContainEqual({ from: id("us-east-1", "Net::Subnet", "subnet-2"), kind: "ref", path: "VpcId", value: "vpc-gone" });
+  });
+
+  test("tags join only through a typed rule for a key that names a cloud id", () => {
+    const subnet = id("us-east-1", "Net::Subnet", "subnet-1");
+    expect(doc.graph.edges).toContainEqual(
+      expect.objectContaining({ from: subnet, to: id("us-east-1", "Eks::Cluster", "prod"), viaAttr: "Tags", rule: "fake:Net::Subnet:tag:kubernetes.io/cluster/" }),
+    );
+    // `team: prod` equals a cluster's name and a log group's name: no edge from a tag value.
+    expect(doc.graph.edges.some((e) => e.from === subnet && e.to === id("us-east-1", "Logs::Group", "team"))).toBe(false);
+  });
+
+  test("a lexicon with no catalog is named in the notes, and its nodes get no edges", () => {
+    const withAzure = typeListing(
+      listing([r("microsoft.storage/storageaccounts", "eastus", "/subscriptions/s/x", {})], {
+        scope: { substrate: "azure", scopeId: "s", locations: "*", types: "*" },
+      }),
+      [{ name: "azure", listedTypes: { substrate: "azure", kindFor: () => "Microsoft.Storage/storageAccounts" } }],
+    );
+    const out = deriveEdges(withAzure, [...lexicons, { name: "azure" }]);
+    expect(out.graph.edges).toEqual([]);
+    expect(out.notes?.find((n) => n.kind === "no-catalog")?.message).toContain("azure");
+  });
+
+  test("derivation is idempotent", () => {
+    expect(deriveEdges(doc, lexicons)).toEqual(doc);
+  });
+});
+
+describe("node order", () => {
+  // A small seeded shuffle, so a failure reproduces.
+  function shuffled<T>(xs: readonly T[], seed: number): T[] {
+    const out = [...xs];
+    let s = seed;
+    for (let i = out.length - 1; i > 0; i--) {
+      s = (s * 1103515245 + 12345) % 2147483648;
+      const j = s % (i + 1);
+      [out[i], out[j]] = [out[j], out[i]];
+    }
+    return out;
+  }
+
+  test("the edge set, dangling set and notes do not depend on the order nodes were listed in", () => {
+    const base = deriveEdges(typeListing(listing(RESOURCES), typing), lexicons);
+    for (const seed of [1, 2, 3, 7, 42, 1009]) {
+      const doc = typeListing(listing(RESOURCES), typing);
+      // Shuffle the typed nodes themselves, past typeListing's own sort.
+      const scrambled: IndexDocument = { ...doc, graph: { ...doc.graph, nodes: shuffled(doc.graph.nodes, seed) } };
+      const out = deriveEdges(scrambled, [...lexicons].reverse());
+      expect(out.graph.edges).toEqual(base.graph.edges);
+      expect(out.graph.dangling).toEqual(base.graph.dangling);
+      expect(out.graph.groups.byContainer).toEqual(base.graph.groups.byContainer);
+      expect(out.notes).toEqual(base.notes);
+    }
+  });
+});
+
+describe("deriveEdgesAcross", () => {
+  const regional = typeListing(listing(RESOURCES.filter((x) => x.location !== "global")), typing);
+  const accountLevel = typeListing(
+    listing(RESOURCES.filter((x) => x.location === "global"), { scope: { substrate: "aws", scopeId: "000000000000", locations: ["global"], types: "*" } }),
+    typing,
+  );
+
+  test("joins every document of one account from one read, and stores each edge with its holder", () => {
+    const [r1, g1] = deriveEdgesAcross([regional, accountLevel], lexicons);
+    const task = id("us-east-1", "Task::Definition", "arn:aws:ecs:us-east-1:000000000000:task-definition/web:1");
+    expect(r1.graph.edges).toContainEqual(expect.objectContaining({ from: task, to: id("global", "Iam::Role", "app"), rule: "fake:Task::Definition:TaskRoleArn" }));
+    expect(g1.graph.edges).toEqual([]);
+  });
+
+  test("refuses two accounts, or two reads", () => {
+    const other = typeListing(listing(RESOURCES, { scope: { substrate: "aws", scopeId: "111111111111", locations: ["us-east-1"], types: "*" } }), typing);
+    expect(() => deriveEdgesAcross([regional, other], lexicons)).toThrow(/one account/);
+    const later = typeListing(listing(RESOURCES, { startedAt: "2026-10-27T09:00:00.000Z" }), typing);
+    expect(() => deriveEdgesAcross([regional, later], lexicons)).toThrow(/one read/);
+  });
+});

package/src/lifecycle/derive-edges.ts

@@ -0,0 +1,182 @@
+/**
+ * Derived edges for indexed resources (#4522, tier 1 of INTENTIUS/behold#1025,
+ * rules ruled on INTENTIUS/behold#1023 2026-10-26).
+ *
+ * An index typed by ./type-listing.ts has nodes and no edges: with no project
+ * there are no declared references. {@link deriveEdges} runs each lexicon's
+ * `referenceCatalog` (the one `chant graph --live` uses, #778) over the
+ * indexed nodes through `reconstructIndexedEdges` (../graph-refs.ts), and
+ * writes what it finds into the document:
+ *
+ * - every edge is `origin: "derived"` with the `rule` that drew it and
+ *   `grain: "property"`; containment edges say `relation: "containment"` and
+ *   fill `groups.byContainer`;
+ * - the join key is the scoped value: substrate and account, subscription,
+ *   project or cluster, plus region for a regional type, account only for a
+ *   global one (Q2);
+ * - a value matching several nodes draws no edge; an `ambiguous-reference`
+ *   note records it with every candidate (Q3);
+ * - a reference to nothing in the index goes in `graph.dangling`;
+ * - tags make edges only through a catalog's typed tag rules (Q5);
+ * - a lexicon with no catalog is named in a `no-catalog` note, and its nodes
+ *   get no derived edges: nothing guesses;
+ * - derivation runs over every document of one account from the same read
+ *   (Q7, {@link deriveEdgesAcross}), and each edge is stored in its holder's
+ *   document. Edges are per read and never carried to another read.
+ *
+ * After the catalog pass, the identity-match pass (#4523, behold#1023 Q1)
+ * runs over the same nodes: an attribute value equal to the native id or ARN
+ * of a node whose lexicon declares an `indexIdentity` draws an edge whose
+ * `rule` starts `identity-match:`, under the same scoped join key, and a
+ * value naming several nodes draws none and is recorded in an
+ * `ambiguous-identity` note with every candidate. A pair the catalog joined
+ * gets no second edge. Pure.
+ */
+import type { GraphIR, IRDanglingRef, IRNode } from "../graph-ir";
+import {
+  containmentGroups,
+  reconstructIdentityEdges,
+  reconstructIndexedEdges,
+  type IdentityOwners,
+  type IndexedNodeScope,
+  type NamedCatalog,
+  type ReferenceCatalog,
+} from "../graph-refs";
+import type { IndexIdentity } from "./identity-match";
+import { indexDocumentDigest, type IndexDocument, type IndexNote } from "./index-document";
+
+/** What {@link deriveEdges} needs from a lexicon. A `LexiconPlugin` is one. */
+export interface EdgeLexicon {
+  name: string;
+  referenceCatalog?: ReferenceCatalog;
+  /** Its identity rule (#4523): when present, the identity-match pass can name this lexicon's nodes. */
+  indexIdentity?: IndexIdentity;
+}
+
+/** Locations that hold global types: AWS's `global`, Kubernetes' cluster-scoped objects. */
+const GLOBAL_LOCATIONS: ReadonlySet<string> = 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: IndexDocument, node: IRNode): IndexedNodeScope {
+  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: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+
+function noteKey(n: IndexNote): string {
+  return `${n.kind}\u0000${n.listedType ?? ""}\u0000${n.location ?? ""}\u0000${n.message}`;
+}
+
+/** Derived edges over one index document. */
+export function deriveEdges(doc: IndexDocument, lexicons: readonly EdgeLexicon[]): IndexDocument {
+  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: readonly IndexDocument[], lexicons: readonly EdgeLexicon[]): IndexDocument[] {
+  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: NamedCatalog[] = [...lexicons]
+    .filter((l): l is EdgeLexicon & { referenceCatalog: ReferenceCatalog } => 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<string, number>();
+  const scopes = new Map<string, IndexedNodeScope>();
+  const all: IRNode[] = [];
+  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: IdentityOwners[] = [...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: string) => 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<string, IRDanglingRef>();
+    for (const r of [
+      ...(d.graph.dangling ?? []),
+      ...derived.dangling.filter((x) => mine(x.from)).map((x) => ({ from: x.from, kind: "ref" as const, path: x.path, value: x.value })),
+    ]) {
+      dangling.set(`${r.from}\u0000${r.kind}\u0000${r.path}\u0000${r.value}`, r);
+    }
+
+    const notes: IndexNote[] = (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<string, number>();
+    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: GraphIR = { ...d.graph, edges, groups };
+    if (dangling.size > 0) graph.dangling = [...dangling.values()];
+    else delete graph.dangling;
+
+    const out: IndexDocument = {
+      ...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/src/lifecycle/git.ts

@@ -475,6 +475,10 @@ export function snapshotStorageKey(lexicon: string, stack?: string): string {
 /**
  * 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(
@@ -487,12 +491,14 @@ export async function writeSnapshot(
 }
 
 /**
- * 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: string,
   lexicon: string,
-  opts?: { cwd?: string },
+  opts?: LedgerLocation,
 ): Promise<string | null> {
   return readBlobFromPath(environment, `${lexicon}.json`, opts);
 }
@@ -507,7 +513,7 @@ export async function readSnapshotAt(
   environment: string,
   lexicon: string,
   ref: string,
-  opts?: { cwd?: string },
+  opts?: LedgerLocation,
 ): Promise<string | null> {
   const rt = getRuntime();
   const dir = await ledgerDir(environment, opts);
@@ -704,7 +710,7 @@ export async function readEnvironmentSnapshots(
  * List snapshot history from the orphan branch.
  */
 export async function listSnapshots(
-  opts?: { cwd?: string; environment?: string },
+  opts?: LedgerLocation & { environment?: string },
 ): Promise<Array<{ commit: string; date: string; message: string }>> {
   const rt = getRuntime();
   // A member sees the commits that touched its own ledger (#2538); the flat