@intentius/chant 0.124.52 → 0.124.54

package/src/lifecycle/index-drift.ts

@@ -0,0 +1,304 @@
+/**
+ * Drift without a deploy (#4526, tier 2 of INTENTIUS/behold#1025): the deep
+ * diff of declared source against an index version, for source chant never
+ * applied. `chant lifecycle diff <env> --index <ref>` is the command.
+ *
+ * Three steps, all pure:
+ *
+ * 1. Every declared entity is joined to the index through its lexicon's
+ *    index match, with {@link joinDeclaredToIndex} (./index-join.ts, #4525).
+ *    `chant search --index` joins the same way, so a row that binds there
+ *    binds here.
+ * 2. A bound row's declared property tree is compared with its indexed
+ *    node's `attrs` by the live deep diff ({@link diffDeepObservation},
+ *    ./deep-observe.ts): both sides normalized with the lexicon's own hooks,
+ *    and the observation baseline (`.chant/observation-baseline/<env>.json`,
+ *    #4519) subtracted, value-bound. An accepted deviation stays quiet until
+ *    the indexed value moves again.
+ * 3. Every row becomes one drift record (`drift: "v1"`, ../drift-record.ts).
+ *
+ * A row that is not bound is reported with its join verdict and never
+ * diffed. The verdict rides in `evidence.engineCode`:
+ *
+ * - `absent`: the index's coverage listed the type and location and holds
+ *   no resource with the identity the declaration spells. The record is
+ *   `pending` (declared, confirmed absent). The rule is
+ *   {@link indexAbsence}, the one `chant index diff` reads "removed" by
+ *   (./index-diff.ts, #4533);
+ * - `not-observed`: the index did not look there (filtered, not reached, a
+ *   read failure), or the lexicon has no index match. An uncovered entity is
+ *   not observed, never drifted and never in sync;
+ * - `no-binding`: the declaration spells no identity to join on;
+ * - `ambiguous`: two or more indexed resources carry the identity, and chant
+ *   will not pick one.
+ *
+ * The last three are status `not-observed` with a reason from the
+ * observation contract's closed list. `not-observed` is also the index
+ * diff's word ({@link IndexChangeKind}), so the two comparisons against an
+ * index use one vocabulary.
+ *
+ * Every record's read is `live-read`, observed at the index's
+ * `stamp.observedAt`: an index version is a read of the provider, taken
+ * then. `evidence.command` names the index version that answered.
+ */
+import type { ChangeSetGraphNodes } from "../change-set-graph";
+import type { DeepNormalizationHooks, DeepResourceObservation } from "../deep-observation";
+import {
+  deepDiffDriftRecords,
+  driftDocument,
+  driftRecord,
+  placeDriftRecord,
+  type DriftDocument,
+  type DriftRecord,
+  type DriftStatus,
+  type DriftUnobserved,
+} from "../drift-record";
+import type { GraphIR, IRNode } from "../graph-ir";
+import { isUnobservedReason } from "../observation";
+import { countPropertyDrift, type DeepDiffResult } from "./deep-diff";
+import { diffDeepObservation, type DeclaredEntities } from "./deep-observe";
+import { indexAbsence, type IndexChangeKind } from "./index-diff";
+import type { IndexDocument } from "./index-document";
+import { formatIndexRef, joinDeclaredToIndex, type IndexJoin, type JoinLexicon } from "./index-join";
+import { baselineForLexicon, type ObservationBaseline } from "./observation-baseline";
+
+/** The status an unbound row takes when the index could not say: the index diff's word and the drift record's. */
+export const INDEX_NOT_OBSERVED: Extract<IndexChangeKind, DriftStatus> = "not-observed";
+
+/** What the drift read needs of a lexicon: its index match and its deep hooks. A `LexiconPlugin` is one. */
+export interface IndexDriftLexicon extends JoinLexicon {
+  deepNormalizationHooks?: DeepNormalizationHooks;
+}
+
+export interface IndexDriftInput {
+  /** The index version to compare against, as {@link readIndexRef} returned it. */
+  doc: IndexDocument;
+  /** Its version name, with or without `.json`. */
+  version: string;
+  /** Declared entities per lexicon, as the live deep diff takes them. */
+  entities: ReadonlyMap<string, DeclaredEntities>;
+  lexicons: readonly IndexDriftLexicon[];
+  /** The environment's accepted deviations, or null when none are recorded. */
+  baseline?: ObservationBaseline | null;
+  /** The drift record's `member`. */
+  member: string;
+  /** A stack of a multi-stack project: record addresses are `<stack>::<name>`, as search ids are. */
+  stack?: string;
+  /** The region the entities live in, from the stack (or the single stack) they belong to. */
+  region?: string;
+  /** The chant version, for `evidence.version` and the document's `chant`. */
+  chant?: string;
+  /** The member's graph, to place each record. Omit to leave `node` null. */
+  graph?: ChangeSetGraphNodes | null;
+}
+
+/** One lexicon's half of the read. */
+export interface IndexDriftLexiconResult {
+  /** Every declared entity's join verdict, by entity name. */
+  joins: Record<string, IndexJoin>;
+  /** The deep diff over the bound rows only. Unbound rows are never in it. */
+  deep: DeepDiffResult;
+}
+
+export interface IndexDriftCounts {
+  /** Declared entities compared. */
+  declared: number;
+  bound: number;
+  /** Reported property differences across every bound row. */
+  properties: number;
+  /** Bound rows with at least one reported difference. */
+  drifted: number;
+  /** Differences the baseline suppressed. */
+  accepted: number;
+  /** Rows the index listed the place of and does not hold. */
+  pending: number;
+  /** Rows the index could not say anything about. */
+  notObserved: number;
+}
+
+export interface IndexDriftResult {
+  /** `<scope key>@<version>`. */
+  ref: string;
+  observedAt: string;
+  byLexicon: Record<string, IndexDriftLexiconResult>;
+  /** One record per declared entity, sorted by address. */
+  records: DriftRecord[];
+  counts: IndexDriftCounts;
+}
+
+/** The command an index read's records name. */
+export function indexDriftCommand(ref: string): string {
+  return `chant lifecycle diff --index ${ref}`;
+}
+
+function declaredGraph(lexicon: string, entities: DeclaredEntities): GraphIR {
+  const nodes: IRNode[] = [...entities.entries()]
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([name, e]) => ({ id: name, kind: e.entityType, lexicon, attrs: e.props ?? {} }));
+  return { nodes, edges: [], groups: { byLexicon: { [lexicon]: nodes.map((n) => n.id) } } };
+}
+
+function queriedOf(j: IndexJoin): string | undefined {
+  if (!j.listedType) return undefined;
+  return `${j.listedType}${j.identifier !== undefined ? ` ${j.identifier}` : ""}${j.location ? ` @ ${j.location}` : ""}`;
+}
+
+/** An unbound row's status and why, from its verdict. Never diffed. */
+function unboundStatus(doc: IndexDocument, j: Exclude<IndexJoin, { verdict: "bound" }>): { status: DriftStatus; unobserved?: DriftUnobserved } {
+  const queried = queriedOf(j);
+  const q = queried ? { queried } : {};
+  switch (j.verdict) {
+    case "absent": {
+      // The join said absent from the index's coverage. Read it again with the
+      // index diff's rule, so "absent" means one thing in both comparisons.
+      const a = j.listedType && j.location ? indexAbsence(doc.coverage, j.listedType, j.location) : ({ kind: "removed" } as const);
+      if (a.kind === "removed") return { status: "pending" };
+      return {
+        status: INDEX_NOT_OBSERVED,
+        unobserved: {
+          reason: isUnobservedReason(a.verdict) ? a.verdict : "not-reached",
+          detail: a.detail ?? `the index's coverage says ${a.verdict} for ${j.listedType} at ${j.location}`,
+          ...q,
+        },
+      };
+    }
+    case "not-observed":
+      return { status: INDEX_NOT_OBSERVED, unobserved: { reason: j.reason, detail: j.detail, ...q } };
+    case "no-binding":
+      return { status: INDEX_NOT_OBSERVED, unobserved: { reason: "no-binding", detail: j.detail, ...q } };
+    case "ambiguous":
+      return {
+        status: INDEX_NOT_OBSERVED,
+        unobserved: { reason: "no-binding", detail: `${j.detail} (candidates: ${j.candidates.join(", ")})`, ...q },
+      };
+  }
+}
+
+/**
+ * Compare every declared entity with the index version, lexicon by lexicon.
+ * Deterministic: the same index, declaration and baseline give the same
+ * records.
+ */
+export function diffDeclaredAgainstIndex(input: IndexDriftInput): IndexDriftResult {
+  const { doc } = input;
+  const ref = formatIndexRef(doc.stamp.scopeKey, input.version.endsWith(".json") ? input.version : `${input.version}.json`);
+  const observedAt = doc.stamp.observedAt;
+  const command = indexDriftCommand(ref);
+  const address = (name: string) => (input.stack ? `${input.stack}::${name}` : name);
+  const indexed = new Map(doc.graph.nodes.map((n) => [n.id, n]));
+  const byLexicon: Record<string, IndexDriftLexiconResult> = {};
+  const records: DriftRecord[] = [];
+  const counts: IndexDriftCounts = { declared: 0, bound: 0, properties: 0, drifted: 0, accepted: 0, pending: 0, notObserved: 0 };
+  const adapter = {
+    member: input.member,
+    observedAt,
+    ...(input.graph !== undefined ? { graph: input.graph } : {}),
+    ...(input.chant ? { version: input.chant } : {}),
+  };
+  const evidence = (engineCode?: string) => ({ tool: "chant", ...(input.chant ? { version: input.chant } : {}), command, ...(engineCode ? { engineCode } : {}) });
+
+  for (const lexicon of [...input.entities.keys()].sort()) {
+    const entities = input.entities.get(lexicon)!;
+    if (entities.size === 0) continue;
+    const plugin = input.lexicons.find((l) => l.name === lexicon) ?? { name: lexicon };
+    const { joins } = joinDeclaredToIndex(declaredGraph(lexicon, entities), doc, [plugin], {
+      regionOf: () => input.region,
+    });
+
+    // The bound rows are the observed side, each its indexed node's tree.
+    const bound: DeclaredEntities = new Map();
+    const resources: Record<string, DeepResourceObservation> = {};
+    for (const [name, entity] of entities) {
+      const j = joins[name];
+      if (j?.verdict !== "bound") continue;
+      const hit = indexed.get(j.node);
+      if (!hit) continue;
+      bound.set(name, entity);
+      resources[name] = { type: entity.entityType, physicalId: hit.physicalId ?? j.nativeId, properties: (hit.attrs ?? {}) as Record<string, unknown> };
+    }
+    const deep = diffDeepObservation(bound, { resources, unobserved: {} }, plugin.deepNormalizationHooks, baselineForLexicon(input.baseline, lexicon));
+    byLexicon[lexicon] = { joins, deep };
+
+    // Bound rows: the deep diff's records, and in-sync for a row whose every
+    // difference is accepted (the deep diff lists it under neither).
+    const deepRecords = new Map(deepDiffDriftRecords({ ...adapter, diff: deep, command }).map((r) => [r.address, r]));
+    for (const name of [...entities.keys()].sort()) {
+      const entity = entities.get(name)!;
+      const j = joins[name];
+      counts.declared++;
+      const at = { ...placeDriftRecord(adapter, "chant", address(name)) };
+      if (j?.verdict === "bound" && bound.has(name)) {
+        counts.bound++;
+        const r = deepRecords.get(name);
+        records.push(
+          driftRecord({
+            ...(r ?? {
+              member: input.member,
+              engine: "chant" as const,
+              address: name,
+              observedAt,
+              read: "live-read" as const,
+              status: "in-sync" as const,
+              evidence: evidence(),
+            }),
+            address: address(name),
+            ...at,
+            resourceType: entity.entityType,
+          }),
+        );
+        continue;
+      }
+      // Unbound: the verdict, never a diff.
+      const verdict = j ?? { verdict: "not-observed" as const, reason: "not-reached" as const, detail: "the join gave this row no verdict" };
+      if (verdict.verdict === "bound") {
+        // Bound to a node the index does not hold: the document disagrees with itself.
+        records.push(
+          driftRecord({
+            member: input.member,
+            engine: "chant",
+            address: address(name),
+            ...at,
+            resourceType: entity.entityType,
+            observedAt,
+            read: "live-read",
+            status: INDEX_NOT_OBSERVED,
+            unobserved: { reason: "read-failed", detail: `the index binds ${name} to ${verdict.node}, which its graph does not hold` },
+            evidence: evidence("bound"),
+          }),
+        );
+        counts.notObserved++;
+        continue;
+      }
+      const s = unboundStatus(doc, verdict);
+      if (s.status === "pending") counts.pending++;
+      else counts.notObserved++;
+      records.push(
+        driftRecord({
+          member: input.member,
+          engine: "chant",
+          address: address(name),
+          ...at,
+          resourceType: entity.entityType,
+          observedAt,
+          read: "live-read",
+          status: s.status,
+          ...(s.unobserved ? { unobserved: s.unobserved } : {}),
+          evidence: evidence(verdict.verdict),
+        }),
+      );
+    }
+    counts.properties += countPropertyDrift(deep);
+    counts.drifted += deep.drifted.length;
+    counts.accepted += deep.accepted.reduce((n, e) => n + e.changes.length, 0);
+  }
+
+  records.sort((a, b) => (a.address < b.address ? -1 : a.address > b.address ? 1 : 0));
+  return { ref, observedAt, byLexicon, records, counts };
+}
+
+/** The records as one drift document. */
+export function indexDriftDocument(results: Iterable<IndexDriftResult>, chant?: string): DriftDocument {
+  const records: DriftRecord[] = [];
+  for (const r of results) records.push(...r.records);
+  return driftDocument(records, chant ? { chant } : {});
+}

package/src/lifecycle/index-import.test.ts

@@ -0,0 +1,255 @@
+/**
+ * #4524: the pure part of `chant import --index` over a hand-made index,
+ * with a fake lexicon seam, so every rule is checked without a generated
+ * lexicon: selection, references from derived edges, secrets as parameters,
+ * declared nodes left out, unsupported nodes named, groups and determinism.
+ * The aws seam and its round trip through the generator and a build are in
+ * lexicons/aws/src/index-import.test.ts.
+ */
+import { describe, expect, test } from "vitest";
+import { MASKED } from "../deep-observation";
+import type { IREdge, IRNode } from "../graph-ir";
+import type { IndexIdentity } from "./identity-match";
+import { indexDocumentDigest, indexScopeKey, type CloudIndexScope, type IndexDocument } from "./index-document";
+import {
+  declaredNodes,
+  edgeRulePath,
+  indexImportHeader,
+  nodeSelected,
+  planIndexImport,
+  selectionIsEmpty,
+  type IndexImportCodegen,
+  type IndexImportLexicon,
+} from "./index-import";
+
+const SCOPE: CloudIndexScope = { kind: "cloud", substrate: "aws", scopeId: "111", locations: ["r1", "r2"], types: "*" };
+
+function node(kind: string, location: string, nativeId: string, attrs: Record<string, unknown>, extra: Partial<IRNode> = {}): IRNode {
+  return {
+    id: `aws/111/${location}/${kind}/${nativeId}`,
+    kind,
+    lexicon: "fake",
+    attrs,
+    listedType: kind,
+    location,
+    nativeId,
+    physicalId: nativeId,
+    tags: {},
+    facts: { cloudIds: [{ kind: "arn", value: `arn:${kind}:${nativeId}` }], observedAt: "2026-10-26T00:00:00.000Z" },
+    ...extra,
+  };
+}
+
+function edge(from: IRNode, to: IRNode, path: string, extra: Partial<IREdge> = {}): IREdge {
+  return { from: from.id, to: to.id, kind: "ref", origin: "derived", grain: "property", rule: `fake:${from.kind}:${path}`, viaAttr: path, ...extra };
+}
+
+function docOf(nodes: IRNode[], edges: IREdge[]): IndexDocument {
+  const graph = { version: 1 as const, nodes, edges, groups: {} };
+  return {
+    index: "v1",
+    stamp: {
+      source: { kind: "cloud", name: "behold-lister" },
+      scope: SCOPE,
+      scopeKey: indexScopeKey(SCOPE),
+      observedAt: "2026-10-26T00:00:00.000Z",
+      digest: indexDocumentDigest({ graph, coverage: [] }),
+    },
+    coverage: [{ listedType: "*", location: "*", verdict: "listed" }],
+    graph,
+  };
+}
+
+const fake: IndexImportCodegen = {
+  resource: (n) => (n.kind === "Fake::Refused" ? { unsupported: "refused by the fake lexicon" } : { type: n.kind, properties: n.attrs }),
+  reference: (value, target) =>
+    value === target.node.nativeId ? { ref: target.logicalId } : value === `arn:${target.node.kind}:${target.node.nativeId}` ? { arn: target.logicalId } : undefined,
+  secretParameter: (name, ctx) => ({ name, type: "String", description: `${ctx.path} of ${ctx.node.id}` }),
+  parameterReference: (name) => ({ param: name }),
+};
+const LEX: IndexImportLexicon[] = [{ name: "fake", indexImport: fake }];
+
+const net = node("Fake::Net", "r1", "net-1", { Cidr: "10.0.0.0/16" });
+const sub = node("Fake::Sub", "r1", "sub-1", { NetId: "net-1", Cidr: "10.0.1.0/24" }, { tags: { team: "a" } });
+const vm = node("Fake::Vm", "r1", "vm-1", {
+  SubIds: ["sub-1", "sub-elsewhere"],
+  Role: "arn:Fake::Role:role-1",
+  Password: MASKED,
+  Disks: [{ Key: MASKED }],
+}, { tags: { team: "a" } });
+const role = node("Fake::Role", "global", "role-1", { Name: "role-1" });
+const far = node("Fake::Net", "r2", "net-2", { Cidr: "10.1.0.0/16" });
+const odd = node("Unmapped::Thing", "r1", "t-1", {}, { unmappedKind: true, lexicon: "aws" });
+const refused = node("Fake::Refused", "r1", "x-1", {});
+const other = { ...node("Other::Kind", "r1", "o-1", {}), lexicon: "other" };
+
+const EDGES = [
+  edge(sub, net, "NetId", { relation: "containment" }),
+  edge(vm, sub, "SubIds[]"),
+  { ...edge(vm, role, "Role"), rule: "identity-match:fake:Fake::Vm:arn" },
+  edge(far, net, "Peer"),
+];
+const DOC = docOf([net, sub, vm, role, far, odd, refused, other], EDGES);
+
+describe("selection", () => {
+  test("an empty selection selects nothing", () => {
+    expect(selectionIsEmpty({})).toBe(true);
+    expect(nodeSelected(net, {})).toBe(false);
+    expect(planIndexImport([DOC], {}, LEX).report.resources).toEqual([]);
+  });
+
+  test("types, names, nodes and tags narrow; within one field any value matches", () => {
+    expect(nodeSelected(net, { types: ["Fake::Net", "Fake::Sub"] })).toBe(true);
+    expect(nodeSelected(vm, { types: ["Fake::Net"] })).toBe(false);
+    expect(nodeSelected(sub, { names: ["sub-1"] })).toBe(true);
+    expect(nodeSelected(sub, { nodes: [sub.id] })).toBe(true);
+    expect(nodeSelected(sub, { tags: { team: "a" } })).toBe(true);
+    expect(nodeSelected(net, { tags: { team: "a" } })).toBe(false);
+    expect(nodeSelected(vm, { types: ["Fake::Vm"], tags: { team: "b" } })).toBe(false);
+  });
+});
+
+describe("planIndexImport", () => {
+  const plan = planIndexImport([DOC], { all: true }, LEX);
+  const report = (n: IRNode) => plan.report.resources.find((r) => r.node === n.id)!;
+
+  test("a derived edge to an imported node in the same group becomes a reference", () => {
+    const g = plan.groups.find((x) => x.location === "r1")!;
+    const subIr = g.ir.resources.find((r) => r.type === "Fake::Sub")!;
+    expect(subIr.properties.NetId).toEqual({ ref: report(net).logicalId });
+    expect(report(sub).references).toEqual([{ path: "NetId", target: net.id, rule: "fake:Fake::Sub:NetId", written: "reference" }]);
+  });
+
+  test("an array path rewrites only the values that name the target", () => {
+    const g = plan.groups.find((x) => x.location === "r1")!;
+    const vmIr = g.ir.resources.find((r) => r.type === "Fake::Vm")!;
+    expect(vmIr.properties.SubIds).toEqual([{ ref: report(sub).logicalId }, "sub-elsewhere"]);
+  });
+
+  test("an identity-match edge, which names no path, is found by value", () => {
+    const one = planIndexImport([DOC], { types: ["Fake::Vm", "Fake::Role", "Fake::Sub"] }, LEX);
+    const vmIr = one.groups[0].ir.resources.find((r) => r.type === "Fake::Vm")!;
+    expect(vmIr.properties.Role).toEqual({ arn: one.report.resources.find((r) => r.node === role.id)!.logicalId });
+    expect(one.report.resources.find((r) => r.node === vm.id)!.references).toContainEqual({
+      path: "Role",
+      target: role.id,
+      rule: "identity-match:fake:Fake::Vm:arn",
+      written: "reference",
+    });
+  });
+
+  test("a masked value becomes a parameter and is never written", () => {
+    const vmIr = plan.groups.flatMap((g) => g.ir.resources).find((r) => r.type === "Fake::Vm")!;
+    expect(JSON.stringify(plan.groups.map((g) => g.ir))).not.toContain(MASKED);
+    const lid = report(vm).logicalId!;
+    expect(vmIr.properties.Password).toEqual({ param: `${lid}Password` });
+    expect((vmIr.properties.Disks as Array<Record<string, unknown>>)[0].Key).toEqual({ param: `${lid}Disks0Key` });
+    expect(plan.report.parameters.map((p) => p.path)).toEqual(["Disks[0].Key", "Password"]);
+    const params = plan.groups.flatMap((g) => g.ir.parameters).map((p) => p.name);
+    expect(params).toEqual([`${lid}Disks0Key`, `${lid}Password`]);
+    const g = plan.groups.find((x) => x.ir.resources.some((r) => r.type === "Fake::Vm"))!;
+    expect(indexImportHeader(plan, g)).toContain(`fill in the parameter ${lid}Password`);
+  });
+
+  test("an edge into another group stays a literal, and the header names the edge", () => {
+    const g2 = plan.groups.find((x) => x.location === "r2")!;
+    const farIr = g2.ir.resources[0];
+    expect(farIr.properties).toEqual({ Cidr: "10.1.0.0/16" });
+    expect(report(far).references?.[0]).toMatchObject({ path: "Peer", written: "literal" });
+    expect(report(far).references?.[0].reason).toMatch(/another group/);
+    expect(g2.header.join("\n")).toContain(`derived edge fake:Fake::Net:Peer to ${net.id}`);
+  });
+
+  test("two regions give two groups, and a global node with two regions to pick from gets its own", () => {
+    expect(plan.groups.map((g) => g.dir)).toEqual(["fake/global", "fake/r1", "fake/r2"]);
+  });
+
+  test("a global node joins the only region", () => {
+    const one = planIndexImport([DOC], { types: ["Fake::Vm", "Fake::Role"] }, LEX);
+    expect(one.groups.map((g) => g.dir)).toEqual([""]);
+    const vmIr = one.groups[0].ir.resources.find((r) => r.type === "Fake::Vm")!;
+    expect(vmIr.properties.Role).toEqual({ arn: one.report.resources.find((r) => r.node === role.id)!.logicalId });
+  });
+
+  test("unmapped kinds, a lexicon with no seam and a refused node are named as unsupported", () => {
+    expect(report(odd)).toMatchObject({ status: "unsupported" });
+    expect(report(odd).reason).toMatch(/no lexicon kind maps/);
+    expect(report(other).reason).toBe("the other lexicon is not loaded");
+    const withOther = planIndexImport([DOC], { all: true }, [...LEX, { name: "other" }]);
+    expect(withOther.report.resources.find((r) => r.node === other.id)!.reason).toMatch(/no index import codegen/);
+    expect(report(refused).reason).toBe("refused by the fake lexicon");
+  });
+
+  test("the report names each resource's identity and cloud ids", () => {
+    expect(report(vm).identity).toEqual({ substrate: "aws", scopeId: "111", listedType: "Fake::Vm", location: "r1", nativeId: "vm-1" });
+    expect(report(vm).cloudIds).toEqual([{ kind: "arn", value: "arn:Fake::Vm:vm-1" }]);
+    expect(plan.report.index).toEqual([{ scopeKey: DOC.stamp.scopeKey, observedAt: DOC.stamp.observedAt, digest: DOC.stamp.digest, source: "behold-lister" }]);
+  });
+
+  test("a declared node is reported with its entity and not imported; an edge to it stays a literal", () => {
+    const declared = new Map([[net.id, "network"]]);
+    const p = planIndexImport([DOC], { types: ["Fake::Net", "Fake::Sub"] }, LEX, { declared });
+    const r = p.report.resources.find((x) => x.node === net.id)!;
+    expect(r).toMatchObject({ status: "declared", entity: "network" });
+    // The other Fake::Net (net-2, in r2) is selected by type and not declared, so it is imported.
+    const imported = p.report.resources.filter((x) => x.status === "imported").map((x) => x.node);
+    expect(imported).not.toContain(net.id);
+    expect(imported).toEqual([far.id, sub.id].sort());
+    expect(p.groups.flatMap((g) => g.ir.resources).filter((x) => x.type === "Fake::Net")).toHaveLength(1);
+    const s = p.report.resources.find((x) => x.node === sub.id)!;
+    expect(s.references?.[0]).toMatchObject({ written: "literal", reason: "the target is already declared as network" });
+  });
+
+  test("the same index and selection give the same plan, whatever the node and edge order", () => {
+    // The same index version: same stamp, its nodes and edges listed in another order.
+    const shuffled = { ...docOf([other, refused, far, role, odd, vm, net, sub], [...EDGES].reverse()), stamp: DOC.stamp };
+    expect(JSON.stringify(planIndexImport([shuffled], { all: true }, LEX))).toBe(JSON.stringify(plan));
+    expect(JSON.stringify(planIndexImport([DOC], { all: true }, LEX))).toBe(JSON.stringify(plan));
+  });
+
+  test("two reads are refused", () => {
+    const later = { ...DOC, stamp: { ...DOC.stamp, observedAt: "2026-10-27T00:00:00.000Z" } };
+    expect(() => planIndexImport([DOC, later], { all: true }, LEX)).toThrow(/one read of one account/);
+  });
+
+  test("logical ids are letters and digits, stable, and drop a repeated type word", () => {
+    const ids = plan.report.resources.filter((r) => r.logicalId).map((r) => r.logicalId!);
+    for (const id of ids) expect(id).toMatch(/^[A-Za-z][A-Za-z0-9]*$/);
+    expect(new Set(ids).size).toBe(ids.length);
+    expect(report(net).logicalId).toBe("Net1");
+    expect(report(sub).logicalId).toBe("Sub1");
+  });
+});
+
+describe("edgeRulePath", () => {
+  test("a catalog rule names its path; tag and identity-match rules name none", () => {
+    expect(edgeRulePath(EDGES[0], sub)).toBe("NetId");
+    expect(edgeRulePath({ ...EDGES[0], rule: "fake:Fake::Sub:tag:owner" }, sub)).toBeUndefined();
+    expect(edgeRulePath(EDGES[2], vm)).toBeUndefined();
+  });
+});
+
+describe("declaredNodes", () => {
+  const identity: IndexIdentity = {
+    substrate: "aws",
+    declaredIdentity: (type, props) =>
+      typeof props.Name === "string"
+        ? { kind: "identifier", listedType: type, identifier: props.Name, global: type === "Fake::Role" }
+        : { kind: "unmatchable", reason: "no-binding", detail: "no name" },
+  };
+
+  test("an entity the matcher binds marks its node as declared", () => {
+    const entities = new Map([["fake", [
+      { name: "network", entityType: "Fake::Net", props: { Name: "net-1" } },
+      { name: "role", entityType: "Fake::Role", props: { Name: "role-1" } },
+      { name: "nameless", entityType: "Fake::Sub", props: {} },
+    ]]]);
+    const declared = declaredNodes([DOC], entities, [{ name: "fake", indexIdentity: identity }]);
+    expect([...declared.entries()].sort()).toEqual([[net.id, "network"], [role.id, "role"]].sort());
+  });
+
+  test("a lexicon with no identity rule declares nothing", () => {
+    const entities = new Map([["fake", [{ name: "network", entityType: "Fake::Net", props: { Name: "net-1" } }]]]);
+    expect(declaredNodes([DOC], entities, [{ name: "fake" }]).size).toBe(0);
+  });
+});