@intentius/chant 0.124.51 → 0.124.54

package/src/lifecycle/snapshot.test.ts

@@ -15,6 +15,19 @@ vi.mock("./git", () => ({
   pushLifecycle: () => pushLifecycleMock(),
 }));
 
+// Snapshots are written through the index store (#4519); this store hands each write to the mocks above.
+vi.mock("./snapshot-store", async () => {
+  const { fakeSnapshotStore } = await import("./snapshot-store-fake");
+  const store = fakeSnapshotStore({
+    write: async (environment, key, json) => ({ written: true, version: (await writeSnapshotMock(environment, key, json)) as string }),
+    publish: async () => {
+      await pushLifecycleMock();
+      return { status: "pushed" };
+    },
+  });
+  return { resolveSnapshotStore: async () => store };
+});
+
 const { takeSnapshot } = await import("./snapshot");
 
 function makeBuildResult(entitiesByLexicon: Record<string, string[]>): BuildResult {

package/src/lifecycle/snapshot.ts

@@ -10,7 +10,8 @@ import { observeDeep } from "./deep-observe";
 import type { DeepResourceObservation } from "../deep-observation";
 import { computeBuildDigest } from "./digest";
 import { collectDependencies, collectAmbient } from "./observe";
-import { writeSnapshot, snapshotStorageKey, getHeadCommit, pushLifecycle } from "./git";
+import { snapshotStorageKey, getHeadCommit } from "./git";
+import { resolveSnapshotStore, type SnapshotStore, type StorePublish } from "./snapshot-store";
 import { sortedJsonReplacer } from "../utils";
 import { formatUnobserved, normalizeObservation, unobservedAll, type UnobservedEntity } from "../observation";
 // One list of secret-bearing property names for both observation depths
@@ -72,9 +73,12 @@ function validateResources(
 
 export interface TakeSnapshotResult {
   snapshots: LifecycleSnapshot[];
+  /** The version the last write made: a commit on a git store, an object version on s3. Empty when nothing was written. */
   commit: string;
   warnings: string[];
   errors: string[];
+  /** Where the snapshots went (`refs/chant/snapshots`, a directory, `s3://...`), and whether they were kept (#4519). */
+  store?: { kind: SnapshotStore["kind"]; where: string; written: boolean; publish?: StorePublish };
 }
 
 /**
@@ -93,6 +97,8 @@ export async function takeSnapshot(
     /** Kinds the PROJECT manages, not just this stack — a region whose stack
      * declares no security group still has a default one (#1278). */
     ambientKinds?: string[];
+    /** The index store to write to (#4519). Default: the project's, from `snapshots` in chant.config.ts. */
+    store?: SnapshotStore;
   },
 ): Promise<TakeSnapshotResult> {
   const stack = opts?.stack;
@@ -285,21 +291,31 @@ export async function takeSnapshot(
     }
   }
 
-  // Write all successful snapshots to git
+  // Write every successful snapshot through the index store (#4519). Masking
+  // already happened above, so the store never sees a secret.
+  const store = opts?.store ?? (await resolveSnapshotStore({ cwd: opts?.cwd }));
   let commitSha = "";
+  let written = false;
   for (const snapshot of snapshots) {
     const json = JSON.stringify(snapshot, sortedJsonReplacer, 2);
-    commitSha = await writeSnapshot(
+    const result = await store.write(
       snapshot.environment,
       snapshotStorageKey(snapshot.lexicon, snapshot.stack),
       json,
-      opts,
+      opts?.cwd ? { cwd: opts.cwd } : undefined,
     );
+    if (result.written) {
+      written = true;
+      commitSha = result.version ?? commitSha;
+    } else if (result.reason) {
+      warnings.push(`${snapshot.lexicon}: snapshot not kept: ${result.reason}`);
+    }
   }
 
   // Push to remote
-  if (snapshots.length > 0) {
-    await pushLifecycle(opts);
+  const publish = written ? await store.publish() : undefined;
+  if (publish && (publish.status === "stale" || publish.status === "failed")) {
+    warnings.push(`snapshot kept locally in ${store.where}, not pushed: ${publish.detail ?? publish.status}`);
   }
 
   return {
@@ -307,5 +323,6 @@ export async function takeSnapshot(
     commit: commitSha,
     warnings,
     errors,
+    store: { kind: store.kind, where: store.where, written, ...(publish ? { publish } : {}) },
   };
 }

package/src/lifecycle/type-listing.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, test } from "vitest";
+import { MASKED } from "../deep-observation";
+import { indexCoverageFor, validateIndexDocument } from "./index-document";
+import { listedNodeId, typeListing, type ListingLexicon, type ListingResult } from "./type-listing";
+
+// #4521: a listing (behold#1029's shape) typed into an index version (behold#1025).
+const lexicons: ListingLexicon[] = [
+  {
+    name: "aws",
+    listedTypes: { substrate: "aws", kindFor: (t) => (t === "AWS::S3::Bucket" || t === "AWS::RDS::DBInstance" ? t : undefined) },
+    deepNormalizationHooks: {
+      // Stands in for a lexicon noise rule: an ARN is server-populated.
+      prune: (node) => node.side === "live" && node.key === "Arn",
+    },
+  },
+  {
+    name: "k8s",
+    listedTypes: {
+      substrate: "kubernetes",
+      kindFor: (t) => (t === "apps/v1/Deployment" ? "K8s::Apps::Deployment" : undefined),
+      observedTree: ({ apiVersion: _a, kind: _k, ...rest }) => rest,
+    },
+  },
+];
+
+function listing(overrides: Partial<ListingResult> = {}): ListingResult {
+  return {
+    listing: "v1",
+    source: { name: "behold-lister", version: "0.0.0-test" },
+    scope: { substrate: "aws", scopeId: "123456789012", locations: ["us-east-1"], types: "*" },
+    startedAt: "2026-10-26T09:14:03.120Z",
+    completedAt: "2026-10-26T09:14:09.000Z",
+    resources: [
+      {
+        listedType: "AWS::S3::Bucket",
+        location: "us-east-1",
+        nativeId: "assets-bucket",
+        cloudIds: [{ kind: "import-id", value: "assets-bucket" }],
+        tags: { team: "web", "api-token": "<masked>" },
+        properties: { BucketName: "assets-bucket", Arn: "arn:aws:s3:::assets-bucket", Tags: [{ Key: "team", Value: "web" }] },
+        observedAt: "2026-10-26T09:14:04.000Z",
+        facts: { cloudIds: [{ kind: "import-id", value: "assets-bucket" }], observedAt: "2026-10-26T09:14:04.000Z", markers: { owner: "web", encoding: "plain", source: "live" } },
+      },
+      {
+        listedType: "AWS::Pipes::Pipe",
+        location: "us-east-1",
+        nativeId: "orders-pipe",
+        cloudIds: [{ kind: "import-id", value: "orders-pipe" }],
+        tags: {},
+        properties: { Name: "orders-pipe", SourceParameters: { ClientSecret: "plain-text-if-the-lister-missed-it" } },
+        observedAt: "2026-10-26T09:14:05.000Z",
+      },
+    ],
+    coverage: [
+      { listedType: "AWS::S3::Bucket", location: "us-east-1", verdict: "listed" },
+      { listedType: "AWS::Pipes::Pipe", location: "us-east-1", verdict: "listed" },
+    ],
+    notes: [{ code: "default-types", message: "types * listed the default set" }],
+    ...overrides,
+  };
+}
+
+describe("typeListing", () => {
+  test("a mapped type becomes a typed node with its lexicon's normalization", () => {
+    const doc = typeListing(listing(), lexicons);
+    const bucket = doc.graph.nodes.find((n) => n.listedType === "AWS::S3::Bucket")!;
+    expect(bucket).toMatchObject({
+      id: "aws/123456789012/us-east-1/AWS::S3::Bucket/assets-bucket",
+      kind: "AWS::S3::Bucket",
+      lexicon: "aws",
+      location: "us-east-1",
+      nativeId: "assets-bucket",
+      physicalId: "assets-bucket",
+    });
+    expect(bucket.unmappedKind).toBeUndefined();
+    // The hook pruned Arn; the rest is key-sorted as the deep path leaves it.
+    expect(bucket.attrs).toEqual({ BucketName: "assets-bucket", Tags: [{ Key: "team", Value: "web" }] });
+    expect(bucket.facts).toEqual({
+      markers: { owner: "web", encoding: "plain", source: "live" },
+      cloudIds: [{ kind: "import-id", value: "assets-bucket" }],
+      observedAt: "2026-10-26T09:14:04.000Z",
+    });
+  });
+
+  test("an unmapped type is kept as an unknown-kind node, never dropped, and named in a note", () => {
+    const input = listing();
+    const doc = typeListing(input, lexicons);
+    // Every listed object is a node: the count is the guard against a drop.
+    expect(doc.graph.nodes).toHaveLength(input.resources.length);
+    const pipe = doc.graph.nodes.find((n) => n.listedType === "AWS::Pipes::Pipe");
+    expect(pipe).toBeDefined();
+    expect(pipe).toMatchObject({ kind: "AWS::Pipes::Pipe", lexicon: "aws", unmappedKind: true, nativeId: "orders-pipe" });
+    expect(doc.notes?.filter((n) => n.kind === "unmapped-type").map((n) => n.listedType)).toEqual(["AWS::Pipes::Pipe"]);
+  });
+
+  test("secrets are masked with the snapshot path's one list, on mapped and unmapped nodes and on tags", () => {
+    const doc = typeListing(listing(), lexicons);
+    const pipe = doc.graph.nodes.find((n) => n.listedType === "AWS::Pipes::Pipe")!;
+    expect((pipe.attrs.SourceParameters as Record<string, unknown>).ClientSecret).toBe(MASKED);
+    const bucket = doc.graph.nodes.find((n) => n.listedType === "AWS::S3::Bucket")!;
+    expect(bucket.tags).toEqual({ "api-token": MASKED, team: "web" });
+    expect(JSON.stringify(doc)).not.toContain("plain-text-if-the-lister-missed-it");
+  });
+
+  test("a lexicon's observed-tree reshape runs before its hooks", () => {
+    const doc = typeListing(
+      listing({
+        scope: { substrate: "kubernetes", scopeId: "kind-dev", locations: "*", types: "*" },
+        resources: [
+          {
+            listedType: "apps/v1/Deployment",
+            location: "web",
+            nativeId: "web/frontend",
+            cloudIds: [{ kind: "k8s-uid", value: "0d6f..." }],
+            tags: {},
+            properties: { apiVersion: "apps/v1", kind: "Deployment", metadata: { name: "frontend", namespace: "web" }, spec: { replicas: 2 } },
+            observedAt: "2026-10-26T09:14:04.000Z",
+          },
+        ],
+        coverage: [{ listedType: "*", location: "*", verdict: "listed" }],
+        notes: [],
+      }),
+      lexicons,
+    );
+    const [deploy] = doc.graph.nodes;
+    expect(deploy.id).toBe("kubernetes/kind-dev/web/apps%2Fv1%2FDeployment/web/frontend");
+    expect(deploy.kind).toBe("K8s::Apps::Deployment");
+    expect(deploy.attrs).toEqual({ metadata: { name: "frontend", namespace: "web" }, spec: { replicas: 2 } });
+  });
+
+  test("the document is stamped with the listing's scope and validates", () => {
+    const doc = typeListing(listing(), lexicons);
+    expect(() => validateIndexDocument(doc)).not.toThrow();
+    expect(doc.stamp.source).toEqual({ kind: "cloud", name: "behold-lister", version: "0.0.0-test" });
+    expect(doc.stamp.observedAt).toBe("2026-10-26T09:14:03.120Z");
+    expect(doc.stamp.scope).toEqual({ kind: "cloud", substrate: "aws", scopeId: "123456789012", locations: ["us-east-1"], types: "*" });
+    expect(doc.graph.edges).toEqual([]);
+    expect(doc.notes?.map((n) => n.kind)).toEqual(["default-types", "unmapped-type"]);
+  });
+
+  test("the same listing in another order gives the same document", () => {
+    const a = listing();
+    const b = listing({ resources: [...a.resources].reverse() });
+    expect(typeListing(b, [...lexicons].reverse())).toEqual(typeListing(a, lexicons));
+  });
+
+  test("the node id matches behold's listedNodeId: % and / escaped in the first four parts, the native id raw", () => {
+    expect(
+      listedNodeId({ substrate: "azure", scopeId: "sub-1", location: "eastus", listedType: "microsoft.storage/storageaccounts", nativeId: "/subscriptions/sub-1/resourceGroups/rg/providers/Microsoft.Storage/storageAccounts/st1" }),
+    ).toBe("azure/sub-1/eastus/microsoft.storage%2Fstorageaccounts//subscriptions/sub-1/resourceGroups/rg/providers/Microsoft.Storage/storageAccounts/st1");
+  });
+});
+
+describe("indexCoverageFor", () => {
+  test('"*" matches every type or location, and an exact entry wins', () => {
+    const coverage = [
+      { listedType: "*", location: "*", verdict: "listed" as const },
+      { listedType: "microsoft.web/sites", location: "*", verdict: "no-credentials" as const },
+      { listedType: "microsoft.web/sites", location: "westeurope", verdict: "read-failed" as const },
+    ];
+    expect(indexCoverageFor(coverage, "microsoft.storage/storageaccounts", "eastus")?.verdict).toBe("listed");
+    expect(indexCoverageFor(coverage, "microsoft.web/sites", "eastus")?.verdict).toBe("no-credentials");
+    expect(indexCoverageFor(coverage, "microsoft.web/sites", "westeurope")?.verdict).toBe("read-failed");
+    expect(indexCoverageFor([{ listedType: "AWS::S3::Bucket", location: "us-east-1", verdict: "listed" }], "AWS::S3::Bucket", "us-west-2")).toBeUndefined();
+  });
+});

package/src/lifecycle/type-listing.ts

@@ -0,0 +1,309 @@
+/**
+ * Typed nodes for indexed resources (#4521, tier 1 of INTENTIUS/behold#1025).
+ *
+ * behold#1029's cloud lister reads one account, subscription, project or
+ * cluster through that cloud's inventory API and returns a
+ * {@link ListingResult}. {@link typeListing} turns it into an
+ * {@link IndexDocument}: each listed object becomes an `IRNode` whose `kind`
+ * is the lexicon kind that describes it, with its properties normalized by
+ * that lexicon's own deep-observe hooks, so an indexed tree has the shape an
+ * observed one has and the capability catalog (#4375) applies to it.
+ *
+ * Pure: no I/O and no clock. The lexicons come in as data (each plugin's
+ * `listedTypes` and `deepNormalizationHooks`), so behold passes the plugins
+ * it already loads and a test passes a table.
+ *
+ * Rules:
+ * - a listed type no lexicon maps stays a node of unknown kind: `kind` is
+ *   the listed type, `lexicon` the substrate, `unmappedKind: true`. It is
+ *   never dropped, and a note names each such type once;
+ * - secret-bearing values are masked with the one list the snapshot path
+ *   uses (`isSensitiveKey`, ../sensitive-key.ts). The lister masked already;
+ *   masking again here means no listing reaches the index unmasked;
+ * - a node id is the path-style id ruled on behold#1025 (Q2):
+ *   `<substrate>/<scopeId>/<location>/<listedType>/<nativeId>`.
+ *
+ * Edges are #4522's (./derive-edges.ts); this module leaves `edges` empty.
+ */
+import type { DeepNormalizationHooks } from "../deep-observation";
+import { MASKED, isSensitiveKey, normalizeDeepProperties } from "../deep-observation";
+import type { EngineFacts } from "../engine-facts";
+import type { GraphIR, IRNode } from "../graph-ir";
+import {
+  canonicalScope,
+  indexDocumentDigest,
+  indexScopeKey,
+  type CloudIndexScope,
+  type CoverageEntry,
+  type IndexDocument,
+  type IndexNote,
+} from "./index-document";
+
+/** The four substrates the lister reads, one per run (behold#1025 Q6). */
+export type ListingSubstrate = CloudIndexScope["substrate"];
+
+/** One run's scope, as the lister names it. `"*"` means every location or type. */
+export interface CloudScope {
+  substrate: ListingSubstrate;
+  scopeId: string;
+  locations: readonly string[] | "*";
+  types: readonly string[] | "*";
+  tagFilter?: Readonly<Record<string, string>>;
+}
+
+/** A cloud id, kinds as #4520 ruled them (`EngineFacts.cloudIds`). */
+export interface ListedCloudId {
+  kind: "import-id" | "arn" | "provider-id" | "self-link" | "k8s-uid";
+  value: string;
+}
+
+/** The facts a cloud listing can supply: markers read off tags, cloud ids, when it was read. */
+export interface ListedFacts {
+  markers?: EngineFacts["markers"];
+  cloudIds: ListedCloudId[];
+  observedAt: string;
+}
+
+/** One listed object (behold#1025 `ListedResource`). */
+export interface ListedResource {
+  /** The path-style id; recomputed by {@link listedNodeId}, so a listing may leave it out. */
+  id?: string;
+  listedType: string;
+  location: string;
+  nativeId: string;
+  cloudIds: ListedCloudId[];
+  tags: Record<string, string>;
+  /** As returned, unnormalized, already masked by the lister. */
+  properties: Record<string, unknown>;
+  observedAt: string;
+  facts?: ListedFacts;
+}
+
+/** A lister note: a type with no lister, a disabled API, a tag filter. */
+export interface ListingNote {
+  code: string;
+  message: string;
+  listedType?: string;
+  location?: string;
+  command?: string;
+}
+
+/** The lister's whole output for one run (behold#1025 `ListingResult`, behold#1029). */
+export interface ListingResult {
+  listing: "v1";
+  source?: { name: string; version?: string };
+  scope: CloudScope;
+  startedAt: string;
+  completedAt: string;
+  resources: ListedResource[];
+  coverage: CoverageEntry[];
+  notes: ListingNote[];
+}
+
+/**
+ * How a lexicon reads one substrate's listed types (a plugin's
+ * `listedTypes`). Data plus two pure functions.
+ */
+export interface ListedTypeMapping {
+  substrate: ListingSubstrate;
+  /** The lexicon kind for a listed type, or undefined when the lexicon has none. */
+  kindFor(listedType: string): string | undefined;
+  /**
+   * The listed properties reshaped into the tree this lexicon's deep reader
+   * returns, before the hooks run: Azure flattens `properties.*` beside
+   * `location` and `sku`, Kubernetes drops `apiVersion` and `kind`. Absent
+   * means the listing's shape already is that tree (Cloud Control's
+   * CloudFormation model).
+   */
+  observedTree?(properties: Record<string, unknown>, context: { listedType: string; kind: string }): Record<string, unknown>;
+}
+
+/** What {@link typeListing} needs from a lexicon. A `LexiconPlugin` is one. */
+export interface ListingLexicon {
+  name: string;
+  listedTypes?: ListedTypeMapping;
+  deepNormalizationHooks?: DeepNormalizationHooks;
+}
+
+function escapeSegment(s: string): string {
+  return s.replace(/%/g, "%25").replace(/\//g, "%2F");
+}
+
+/**
+ * `<substrate>/<scopeId>/<location>/<listedType>/<nativeId>` (behold#1025
+ * Q2), exactly as behold's lister writes it (src/cloud-lister/ids.ts): `%`
+ * and `/` are escaped in the first four parts, and the native id is last and
+ * unescaped, so everything after the fourth `/` is it.
+ */
+export function listedNodeId(parts: { substrate: string; scopeId: string; location: string; listedType: string; nativeId: string }): string {
+  return [
+    escapeSegment(parts.substrate),
+    escapeSegment(parts.scopeId),
+    escapeSegment(parts.location),
+    escapeSegment(parts.listedType),
+    parts.nativeId,
+  ].join("/");
+}
+
+/** The lexicon (and kind) for one listed type: the first mapping, by lexicon name, that answers. */
+export function resolveListedKind(
+  substrate: ListingSubstrate,
+  listedType: string,
+  lexicons: readonly ListingLexicon[],
+): { lexicon: ListingLexicon; kind: string } | undefined {
+  for (const lexicon of lexicons) {
+    const mapping = lexicon.listedTypes;
+    if (!mapping || mapping.substrate !== substrate) continue;
+    const kind = mapping.kindFor(listedType);
+    if (kind !== undefined) return { lexicon, kind };
+  }
+  return undefined;
+}
+
+function maskTags(tags: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const k of Object.keys(tags).sort()) out[k] = isSensitiveKey(k) ? MASKED : tags[k];
+  return out;
+}
+
+const byName = (a: ListingLexicon, b: ListingLexicon) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+
+/** One listed object as a typed (or unknown-kind) node. */
+export function typeListedResource(
+  scope: CloudScope,
+  resource: ListedResource,
+  lexicons: readonly ListingLexicon[],
+): IRNode {
+  const sorted = [...lexicons].sort(byName);
+  const resolved = resolveListedKind(scope.substrate, resource.listedType, sorted);
+  const id = listedNodeId({
+    substrate: scope.substrate,
+    scopeId: scope.scopeId,
+    location: resource.location,
+    listedType: resource.listedType,
+    nativeId: resource.nativeId,
+  });
+  let kind: string;
+  let lexicon: string;
+  let attrs: Record<string, unknown>;
+  if (resolved) {
+    kind = resolved.kind;
+    lexicon = resolved.lexicon.name;
+    const reshape = resolved.lexicon.listedTypes?.observedTree;
+    const tree = reshape ? reshape(resource.properties, { listedType: resource.listedType, kind }) : resource.properties;
+    attrs = normalizeDeepProperties(tree, { entityType: kind, side: "live", hooks: resolved.lexicon.deepNormalizationHooks });
+  } else {
+    kind = resource.listedType;
+    lexicon = scope.substrate;
+    // No lexicon, so no hooks: the listing's properties as returned, key-sorted and masked.
+    attrs = normalizeDeepProperties(resource.properties, { entityType: resource.listedType, side: "live" });
+  }
+  const cloudIds = resource.cloudIds.length > 0 ? resource.cloudIds : resource.facts?.cloudIds ?? [];
+  const facts: EngineFacts = {
+    ...(resource.facts?.markers ? { markers: resource.facts.markers } : {}),
+    ...(cloudIds.length > 0 ? { cloudIds: cloudIds.map((c) => ({ kind: c.kind, value: c.value })) } : {}),
+    observedAt: resource.facts?.observedAt ?? resource.observedAt,
+  };
+  return {
+    id,
+    kind,
+    lexicon,
+    attrs,
+    physicalId: resource.nativeId,
+    facts,
+    listedType: resource.listedType,
+    location: resource.location,
+    nativeId: resource.nativeId,
+    tags: maskTags(resource.tags ?? {}),
+    ...(resolved ? {} : { unmappedKind: true }),
+  };
+}
+
+/** The listing's scope as the index stamp's cloud scope. */
+export function listingIndexScope(scope: CloudScope): CloudIndexScope {
+  return canonicalScope({
+    kind: "cloud",
+    substrate: scope.substrate,
+    scopeId: scope.scopeId,
+    locations: scope.locations,
+    types: scope.types,
+    ...(scope.tagFilter ? { tagFilter: scope.tagFilter } : {}),
+  }) as CloudIndexScope;
+}
+
+/** Every listed object as a node, sorted by id. */
+export function typeListingNodes(listing: ListingResult, lexicons: readonly ListingLexicon[]): IRNode[] {
+  const nodes = listing.resources.map((r) => typeListedResource(listing.scope, r, lexicons));
+  nodes.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return nodes;
+}
+
+const compareNotes = (a: IndexNote, b: IndexNote): number => {
+  const ka = `${a.kind}\u0000${a.listedType ?? ""}\u0000${a.location ?? ""}\u0000${a.message}`;
+  const kb = `${b.kind}\u0000${b.listedType ?? ""}\u0000${b.location ?? ""}\u0000${b.message}`;
+  return ka < kb ? -1 : ka > kb ? 1 : 0;
+};
+
+/**
+ * The listing as one index version (behold#1025 schema). `graph.edges` is
+ * empty; chant#4522's `deriveEdges` fills it. Coverage passes through as the
+ * lister wrote it, wildcards included. The lister's notes keep their code as
+ * `kind`, and each unmapped listed type gets one `unmapped-type` note.
+ */
+export function typeListing(listing: ListingResult, lexicons: readonly ListingLexicon[]): IndexDocument {
+  const nodes = typeListingNodes(listing, lexicons);
+  const graph: GraphIR = {
+    version: 1,
+    nodes,
+    edges: [],
+    groups: { byLexicon: groupByLexicon(nodes) },
+  };
+  const coverage = [...listing.coverage].map((c) => ({ ...c }));
+  const notes: IndexNote[] = listing.notes.map((n) => ({
+    kind: n.code,
+    message: n.message,
+    ...(n.listedType !== undefined ? { listedType: n.listedType } : {}),
+    ...(n.location !== undefined ? { location: n.location } : {}),
+    ...(n.command !== undefined ? { command: n.command } : {}),
+  }));
+  const unmapped = [...new Set(nodes.filter((n) => n.unmappedKind).map((n) => n.listedType!))].sort();
+  for (const t of unmapped) {
+    notes.push({
+      kind: "unmapped-type",
+      listedType: t,
+      message: `no lexicon kind maps the listed type ${t}; its objects are kept as nodes of unknown kind, with the listing's properties masked`,
+    });
+  }
+  notes.sort(compareNotes);
+  return assembleIndexDocument(listing, graph, coverage, notes);
+}
+
+/** Stamp a graph, coverage and notes read from `listing` as one index version. */
+export function assembleIndexDocument(
+  listing: ListingResult,
+  graph: GraphIR,
+  coverage: CoverageEntry[],
+  notes: IndexNote[],
+): IndexDocument {
+  const scope = listingIndexScope(listing.scope);
+  return {
+    index: "v1",
+    stamp: {
+      source: { kind: "cloud", name: listing.source?.name ?? "behold-lister", ...(listing.source?.version ? { version: listing.source.version } : {}) },
+      scope,
+      scopeKey: indexScopeKey(scope),
+      observedAt: listing.startedAt,
+      completedAt: listing.completedAt,
+      digest: indexDocumentDigest({ graph, coverage }),
+    },
+    coverage,
+    graph,
+    ...(notes.length > 0 ? { notes } : {}),
+  };
+}
+
+function groupByLexicon(nodes: readonly IRNode[]): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const n of nodes) (out[n.lexicon] ??= []).push(n.id);
+  return Object.fromEntries(Object.keys(out).sort().map((k) => [k, out[k].sort()]));
+}

package/src/lint/component-checks.ts

@@ -57,6 +57,21 @@ export interface ComponentCheckContext {
    * `none-by-design`, i.e. flags nothing).
    */
   rollbackPolicies?: ReadonlyMap<string, RollbackPolicy>;
+  /**
+   * The project's `terraform.roots` entries marked `signalOnly` (#4484),
+   * keyed by root name. Supplied by `chant lint` from the project's config
+   * (`signalOnlyRootsOf` in ./rules/comp/comp008-applies-signal-only-root.ts);
+   * undefined when none was resolved, in which case COMP008 flags nothing.
+   */
+  signalOnlyRoots?: ReadonlyMap<string, SignalOnlyRoot>;
+}
+
+/** One `terraform.roots` entry marked `signalOnly` (#4490). */
+export interface SignalOnlyRoot {
+  /** The root's `dir` as the config writes it. */
+  dir: string;
+  /** The workspace member whose directory holds the root, when the workspace reads. */
+  owner?: string;
 }
 
 /** A diagnostic from a component composition check. Shaped like `PostSynthDiagnostic`, plus a `file` so it can be merged into `LintDiagnostic`s and reported per-file like every other lint diagnostic. */
@@ -104,7 +119,7 @@ export interface ComponentCheck {
 export async function runComponentChecks(
   path: string,
   checks: ComponentCheck[],
-  registryContext?: Pick<ComponentCheckContext, "knownKinds" | "rollbackPolicies">,
+  registryContext?: Pick<ComponentCheckContext, "knownKinds" | "rollbackPolicies" | "signalOnlyRoots">,
   sandbox?: boolean,
   buildParams?: BuildParamProvenance[],
 ): Promise<ComponentCheckDiagnostic[]> {
@@ -137,6 +152,7 @@ export async function runComponentChecks(
     components,
     knownKinds: registryContext?.knownKinds,
     rollbackPolicies: registryContext?.rollbackPolicies,
+    signalOnlyRoots: registryContext?.signalOnlyRoots,
   };
   for (const check of checks) {
     diagnostics.push(...check.check(ctx));

package/src/lint/config.test.ts

@@ -424,6 +424,7 @@ describe("loadConfig", () => {
       COMP005: "error",
       COMP006: "error",
       COMP007: "warning",
+      COMP008: "warning",
     });
   });
 
@@ -474,6 +475,7 @@ describe("loadConfig", () => {
       COMP005: "off",
       COMP006: "off",
       COMP007: "off",
+      COMP008: "warning",
     });
   });
 
@@ -511,6 +513,7 @@ describe("loadConfig", () => {
       COMP005: "error",
       COMP006: "error",
       COMP007: "warning",
+      COMP008: "warning",
     });
   });
 

package/src/lint/presets/relaxed.json

@@ -21,6 +21,7 @@
     "COMP004": "warning",
     "COMP005": "off",
     "COMP006": "off",
-    "COMP007": "off"
+    "COMP007": "off",
+    "COMP008": "warning"
   }
 }

package/src/lint/presets/strict.json

@@ -21,6 +21,7 @@
     "COMP004": "error",
     "COMP005": "error",
     "COMP006": "error",
-    "COMP007": "warning"
+    "COMP007": "warning",
+    "COMP008": "warning"
   }
 }

package/src/lint/rules/__fixtures__/comp/comp008/fail/dns.component.ts

@@ -0,0 +1,15 @@
+import type { Component } from "../../../../../../components/component";
+import { phase } from "../../../../../../components/component";
+
+/** COMP008 fail case: a terraform-apply step deploys "azure", which the test marks signalOnly. */
+export const dns: Component = {
+  name: "dns",
+  archetype: "infra",
+  dependsOn: [],
+  deploy: [
+    phase("Apply", [
+      { kind: "terraform-apply", root: "dns" },
+      { kind: "terraform-apply", root: "azure" },
+    ]),
+  ],
+};