@intentius/chant 0.124.51 → 0.124.54

package/src/cli/main.ts

@@ -173,7 +173,9 @@ Commands:
                         terms, ->* / ->{1,3} for depth, ->[via=attr] / [to=attr]
                         by attribute; --live or --snapshot <ref> (also --at
                         <ref>) with --env <name> reads the estate or a
-                        recorded snapshot; --show <attr>,
+                        recorded snapshot; --index <scope key>[@<version>]
+                        answers from an index version, joined to the
+                        declared rows, or alone with no project; --show <attr>,
                         --count-by kind|module|attr:<name>, --explain prints
                         paths, --json, --check-live,
                         --check-snapshot, --fail-on-drift; cap:<name> and
@@ -191,6 +193,16 @@ Commands:
                         --where <field><op><value> (= != < <= > >= ~,
                         repeatable), --since <time|7d>, --at <rev> of
                         chant/lifecycle, --member <name>, --json
+  index <substrate>     Read one aws account, azure subscription, gcp project
+                        or kubernetes cluster through its inventory API, type
+                        it, derive its edges and write one index version to
+                        the index store. Read-only: refuses action flags.
+                        --account|--subscription|--project|--cluster, --regions,
+                        --types, --tag k=v, --endpoint, --store <spec>, --json
+                        (chant index --help for the rest)
+  index diff <a> [<b>]  What changed between two index versions of one scope:
+                        <scopeKey>/<version>, or <scopeKey> for its last two.
+                        --store <spec>, --json (chant index diff --help)
   generate             Generate typed code from sources chant.config declares
                         (k8s.crds, helm.charts) into src/generated/<lexicon>/
                         (codegen.outDir); --check exits 1 when the committed
@@ -624,6 +636,12 @@ Workspace (level 1, #2524):
                         choudoufu runs live-check and the adoption report;
                         choudoufu or other to chant runs chant import), staged
                         in a worktree and gated on the patch digest like upgrade
+  workspace promote --all [--state-dir <dir>] [--state <member>=<tfstate>]... [--canary <member>] [--wave-size <n>] [--dry-run] [--json]
+                        Adopt every terraform member into choudoufu in waves:
+                        the canary first (default the first member), then
+                        --wave-size roots a wave (default 5), one gate per
+                        root bound to its live-import report digest. A wave
+                        that does not land stops the later ones (#4461)
   workspace ls [dir]    List the declaration's members and example groups.
                         A member that can't be read is listed with a reason
                         code and still exits 0. --at <rev> reads a commit's
@@ -981,6 +999,15 @@ Workspace (level 1, #2524):
                         --no-cache reads every member
                         --capability-view: each member's chant adds its
                         capability view, mapped by its own lexicons
+  workspace drift --member <name> [--read <state|plan|refresh|live-read|ownership>] [--resource <addr>] [--env <name>] [--stream] [-o <file>]
+                        One member's drift, read by its own engine: a chant
+                        member through lifecycle diff --live (needs --env), a
+                        terraform member through its state or a plan, a
+                        choudoufu member through live-plan (and a plan for
+                        --read plan), one resource through choudoufu
+                        live-plan -resource. One drift document, or with
+                        --stream the NDJSON stream (drift-start, records,
+                        drift-settle)
   workspace search "<query>" [--member <name>] [--env <name>] [--snapshot <ref> | --live] [--at <rev>] [--explain] [--count-by ...] [--json]
                         chant search in every chant member, each under its own
                         chant, as one read-contract document: ids are
@@ -1038,6 +1065,8 @@ Lifecycle (alias: lc):
                             (lexicons with a deep reader also report
                             property-level drift; --update-baseline records
                             what it reports as accepted so it stops alerting)
+                            --index <ref>: compare source with an index version
+                            in the store, no deploy and no cloud read (#4526)
   lifecycle plan <env>      Typed change set (create/update/delete/adopt) vs live
                             --deep: also report properties declared
                             heldElsewhere(). Never changes what the plan
@@ -1050,6 +1079,9 @@ Lifecycle (alias: lc):
                             drift: ECS running vs desired, Route 53 health
                             checks, Container Apps revisions, Cloud Run Ready.
                             A failed read is "not read", never unhealthy (--json)
+  lifecycle drift           Each lexicon's own drift read, as drift-record
+                            NDJSON (--member, --read, --resource); what
+                            workspace drift runs in a member's reader project
   lifecycle whoami <env>    Who chant would act as in each configured lexicon,
                             and what that principal is scoped to — read-only,
                             before anything acts (--json, --strict)
@@ -1354,6 +1386,7 @@ Examples:
   chant import manifest.yaml --lexicon k8s --output ./infra/
   chant import dash.json --lexicon grafana --parser-option acceptLossyV1
   chant import --from prod --name my-bucket --output src/
+  chant import --index index.json --type AWS::S3::Bucket --output src/imported/
   chant lint ./infra/
   chant lint ./infra/ --format sarif
   chant lint ./infra/ --watch
@@ -1564,6 +1597,10 @@ export const commandRegistry: CommandDef[] = [
   // #4297 — SQL over the snapshots, runs, gates, deploys and releases on chant/lifecycle. Imported on first use.
   { name: "query", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/query")).runQueryCommand(ctx) },
   { name: "ledger", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/ledger")).runLedgerCommand(ctx) },
+  // chant#4532 — a read-only cloud index. main() hands `index`'s raw argv to
+  // its own parser before parseArgs; this entry answers "is it a verb" and
+  // runs the words a caller already parsed (substrate, --json, --help).
+  { name: "index", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/index-cloud")).runIndexCommand(ctx) },
   // chant#2591 — `import --agents` and `audit` read chant.config statically
   // and never evaluate it (chant#2589 for audit, which audits code it must not run).
   { name: "import", handler: runImport, runsNoConfig: (args) => args.agents === true },
@@ -1702,6 +1739,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "workspace run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/workspace-run")).runWorkspaceRun(ctx) },
   // #2554 — a release train: one release of every chant member, pinned in the workspace ledger.
   { name: "workspace train", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/release-train")).runWorkspaceTrain(ctx) },
+  { name: "workspace drift", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/drift-cli")).runWorkspaceDrift(ctx) },
   { name: "workspace search", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/search-cli")).runWorkspaceSearch(ctx) },
   // Each unit decides for itself whether its config is loaded (runCommandInProcess).
   { name: "workspace member-run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-run")).runWorkspaceMemberRun(ctx, runCommandInProcess) },
@@ -1730,6 +1768,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "lifecycle rollback", handler: runLifecycleRollback },
   { name: "lifecycle plan", requiresPlugins: true, handler: runLifecyclePlan },
   { name: "lifecycle affected", requiresPlugins: true, handler: runLifecycleAffected },
+  { name: "lifecycle drift", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/lifecycle-drift")).runLifecycleDrift(ctx) },
   { name: "lifecycle whoami", requiresPlugins: true, handler: runLifecycleWhoami },
   // #4177 — runtime health, separate from drift. Imported on first use.
   { name: "lifecycle health", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/lifecycle-health")).runLifecycleHealth(ctx) },
@@ -1790,6 +1829,22 @@ async function main(): Promise<void> {
   installCompiledCli();
   const rawArgv = process.argv.slice(2);
 
+  // chant#4532 — `chant index <substrate>` takes its own flags (--account,
+  // --regions, --endpoint, ...) that core's one flat parser does not know, and
+  // must refuse an action flag (--apply, --yes, ...) that the parser would
+  // accept. So its argv goes to its own parser, before parseArgs.
+  if (rawArgv[0] === "index" && rawArgv[1] === "diff") {
+    // #4533 — `chant index diff <a> [<b>]`: two stored versions of one scope.
+    const { runIndexDiff } = await import("./handlers/index-diff");
+    await flushAndExit(await runIndexDiff(rawArgv.slice(2)));
+    return;
+  }
+  if (rawArgv[0] === "index") {
+    const { runCloudIndex } = await import("../lifecycle/cloud-index");
+    await flushAndExit(await runCloudIndex(rawArgv.slice(1)));
+    return;
+  }
+
   let args: ParsedArgs;
   try {
     args = parseArgs(rawArgv);

package/src/cli/mcp/lifecycle-tools.ts

@@ -1,7 +1,7 @@
 import { resolve } from "node:path";
 import type { LexiconPlugin } from "../../lexicon";
 import type { ToolDefinition, ToolHandler } from "./types";
-import { readSnapshot } from "../../lifecycle/git";
+import { resolveSnapshotStore } from "../../lifecycle/snapshot-store";
 import { build } from "../../build";
 import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
 import { takeSnapshot } from "../../lifecycle/snapshot";
@@ -71,8 +71,9 @@ export function createDiffTool(plugins: LexiconPlugin[]): ToolRegistration {
       const currentDigest = computeBuildDigest(buildResult);
       const lexicons = lexiconFilter ? [lexiconFilter] : buildResult.manifest.lexicons;
       const results: Record<string, unknown> = {};
+      const store = await resolveSnapshotStore();
       for (const lex of lexicons) {
-        const content = await readSnapshot(env, lex);
+        const content = await store.readLatest(env, lex);
         let previousDigest = undefined;
         if (content) {
           const snapshot: LifecycleSnapshot = JSON.parse(content);

package/src/cli/mcp/resource-handlers.ts

@@ -4,7 +4,7 @@ import type { ResourceDefinition } from "./types";
 import type { LexiconPlugin } from "../../lexicon";
 import { collectComposites } from "./tools/composites";
 import { getContext } from "./resources/context";
-import { readSnapshot, readEnvironmentSnapshots } from "../../lifecycle/git";
+import { readEnvironmentSnapshotsFrom, resolveSnapshotStore } from "../../lifecycle/snapshot-store";
 import { discoverOps } from "../../op/discover";
 import { createLocalOpRuntime } from "../../op/runtimes/local";
 import { loadOkfBundle } from "../../okf-read";
@@ -224,14 +224,15 @@ export async function handleResourcesRead(
     const environment = parts[0];
     const lexicon = parts[1];
 
+    const store = await resolveSnapshotStore();
     if (lexicon) {
-      const content = await readSnapshot(environment, lexicon);
+      const content = await store.readLatest(environment, lexicon);
       if (!content) throw new Error(`No snapshot found for ${environment}/${lexicon}`);
       return {
         contents: [{ uri, mimeType: "application/json", text: content }],
       };
     } else {
-      const snapshots = await readEnvironmentSnapshots(environment);
+      const snapshots = await readEnvironmentSnapshotsFrom(store, environment);
       const result: Record<string, unknown> = {};
       for (const [lex, content] of snapshots) {
         result[lex] = JSON.parse(content);

package/src/cli/mcp/workspace-tools.ts

@@ -127,7 +127,7 @@ export const workspaceReadTools: ToolDefinition[] = [
     name: "workspace-search",
     description:
       "Answer an estate question over every chant member of the workspace with a few rows instead of the whole graph: chant workspace search <query> --json (search.schema.json, #4374). Returns that document unchanged. Each member is searched under its own chant and alone, ids are <member>/<id> as workspace-graph names the same nodes, and a member that can't be searched is listed with a reason code, never as zero matches. " +
-      "The query is space-separated terms that must all match: a bare word (substring of id, kind or attributes), kind:<substr> (a Terraform resource matches its type, kind:aws_instance), attr:<name>=<value>, tag:<key>=<value>, and edge terms ->X (this node references a node matching X) and <-X (referenced by one); ->*X is any depth, ->{2}X or ->{1,3}X a number of hops, ->[via=attr]X and ->[to=attr]X pick the edge by attribute, and !term negates. " +
+      "The query is space-separated terms that must all match: a bare word (substring of id, kind or attributes), kind:<substr> (a Terraform resource matches its type, kind:aws_instance), attr:<name>=<value>, tag:<key>=<value>, id:<cloud id> (exact, over physical and cloud ids), and edge terms ->X (this node references a node matching X) and <-X (referenced by one); ->*X is any depth, ->{2}X or ->{1,3}X a number of hops, ->[via=attr]X and ->[to=attr]X pick the edge by attribute, and !term negates. " +
       "at is the git revision of the source; snapshot (with env) answers from a recorded lifecycle snapshot such as latest. They are two different times, and at refuses a snapshot ref.",
     inputSchema: {
       type: "object",

package/src/cli/parse-args.ts

@@ -24,6 +24,7 @@ const BOOLEAN_FLAGS = new Set([
   "--agents",
   "--agent",
   "--all-projects",
+  "--all",
   "--force",
   "--fix",
   "--watch",
@@ -78,6 +79,7 @@ const BOOLEAN_FLAGS = new Set([
   "--no-require-review",
   "--expire",
   "--check-live",
+  "--stream",
   "--check-snapshot",
   "--fail-on-drift",
   "--durable-requests",
@@ -247,6 +249,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       const v = args[++i];
       if (!v || v.startsWith("-")) throw new Error("--parser-option needs key or key=value: --parser-option acceptLossyV1");
       (result.parserOption ??= []).push(v);
+    } else if (arg === "--tag") {
+      // `chant import --index <ref> --tag key=value` (#4524), repeatable: every tag must match.
+      const v = args[++i];
+      if (!v || v.startsWith("-") || !v.includes("=")) throw new Error("--tag needs key=value: --tag team=payments");
+      (result.selectTags ??= []).push(v);
     } else if (arg === "--type") {
       result.selectType = args[++i];
     } else if (arg === "--name") {
@@ -266,6 +273,20 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.skipUndeclarable = true;
     } else if (arg === "--state") {
       result.statePath = args[++i];
+      // `chant workspace promote --all --state <member>=<path>` (#4461), repeatable.
+      if (result.statePath !== undefined) (result.statePaths ??= []).push(result.statePath);
+    } else if (arg === "--state-dir") {
+      // `chant workspace promote --all --state-dir <dir>` (#4461): <dir>/<member>.tfstate.
+      result.stateDir = args[++i];
+      if (!result.stateDir || result.stateDir.startsWith("-")) throw new Error("--state-dir needs a directory: --state-dir <dir>");
+    } else if (arg === "--wave-size") {
+      const raw = args[++i];
+      const size = Number(raw);
+      if (!Number.isInteger(size) || size < 1) throw new Error(`--wave-size needs a whole number from 1: got "${raw ?? ""}"`);
+      result.waveSize = size;
+    } else if (arg === "--all") {
+      // `chant workspace promote --all` (#4461): every terraform member.
+      result.all = true;
     } else if (arg === "--select") {
       result.selectAddress = args[++i];
     } else if (arg === "--live-name") {
@@ -980,9 +1001,14 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.tags = args[++i];
       if (!result.tags || result.tags.startsWith("-")) throw new Error("--tags needs a tag glob: --tags 'v*'");
     } else if (arg === "--index") {
-      // #2551 — `chant workspace adopt-lineage --index <file>`.
+      // #2551 — `chant workspace adopt-lineage --index <file>`; #4525 — `chant search --index <ref>`;
+      // #4526 — `chant lifecycle diff <env> --index <ref>`.
       result.index = args[++i];
-      if (!result.index || result.index.startsWith("-")) throw new Error("--index needs a hash index file: --index <file>");
+      if (!result.index || result.index.startsWith("-")) throw new Error("--index needs a value: --index <file> for workspace adopt-lineage, --index <scope key>[@<version>] for search and lifecycle diff");
+    } else if (arg === "--adopt-out") {
+      // #4536 — `chant import --index <ref> --adopt-out <file>`: write the adoption file (`adopt: v1`) for what was imported.
+      result.adoptOut = args[++i];
+      if (!result.adoptOut || result.adoptOut.startsWith("-")) throw new Error("--adopt-out needs a file: --adopt-out <file>");
     } else if (arg === "--remove") {
       // #2552 — `chant workspace import --remove` removes the export member instead of writing it again.
       result.remove = true;
@@ -1024,6 +1050,18 @@ export function parseArgs(args: string[]): ParsedArgs {
       const value = args[++i];
       if (value === undefined || value.startsWith("--")) throw new Error("--where needs a clause: --where <field><op><value>");
       result.where = [...(result.where ?? []), value];
+    } else if (arg === "--read") {
+      // behold#995 - `chant workspace drift --read <read>`: which read the member's engine answers with.
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error("--read needs a read: --read <state|plan|refresh|live-read|ownership>");
+      result.driftRead = value;
+    } else if (arg === "--stream") {
+      result.stream = true;
+    } else if (arg === "--resource") {
+      // behold#995 - `chant workspace drift --resource <addr>`: one resource's drift.
+      const value = args[++i];
+      if (!value || value.startsWith("--")) throw new Error("--resource needs an address: --resource <addr>");
+      result.resource = value;
     } else if (arg === "--since") {
       result.since = args[++i];
     } else if (arg === "--limit") {

package/src/cli/registry.ts

@@ -91,6 +91,14 @@ export interface ParsedArgs {
   parserOption?: string[];
   /** `chant carve advise --state <path>` — opt-in .tfstate for accurate instance counts */
   statePath?: string;
+  /** Every `--state` value in order (#4461): `chant workspace promote --all --state <member>=<path>`, repeatable. */
+  statePaths?: string[];
+  /** `chant workspace promote --all --state-dir <dir>` (#4461): a member's state is `<dir>/<member>.tfstate`. */
+  stateDir?: string;
+  /** `chant workspace promote --all --wave-size <n>` (#4461): roots per wave after the canary. */
+  waveSize?: number;
+  /** `chant workspace promote --all` (#4461): promote every terraform member, in waves. */
+  all?: boolean;
   /** `chant carve emit --select <tf-address>` — the Terraform resource to carve */
   selectAddress?: string;
   /** `chant carve emit --live-name <logicalId>` — CFN logical ID for live adoption */
@@ -127,6 +135,8 @@ export interface ParsedArgs {
   selectType?: string;
   /** `chant import --name <name>` selector */
   selectName?: string;
+  /** `chant import --index <ref> --tag key=value` (#4524), repeatable */
+  selectTags?: string[];
   /** `chant import --owned` — restrict live import to chant-owned resources */
   owned?: boolean;
   /**
@@ -157,7 +167,9 @@ export interface ParsedArgs {
   source?: string;
   /** `chant workspace adopt-lineage --tags <glob>` and `hash-index --tags` (#2551): the tags to compare. */
   tags?: string;
-  /** `chant workspace adopt-lineage --index <file>` (#2551): a cached hash index. */
+  /** `chant workspace adopt-lineage --index <file>` (#2551): a cached hash index. `chant search --index <ref>` (#4525) and `chant lifecycle diff <env> --index <ref>` (#4526): an index version. */
+  /** `chant import --index <ref> --adopt-out <file>` (#4536): where to write the adoption file. */
+  adoptOut?: string;
   index?: string;
   /** `chant workspace versions --available` (#2551): list each git template's version tags. */
   available?: boolean;
@@ -496,6 +508,12 @@ export interface ParsedArgs {
   store?: "tree" | "ledger";
   /** `chant workspace points answer <id> --answer <value>` (#2739): the people's answer. */
   answer?: string;
+  /** `chant workspace drift --read <state|plan|refresh|live-read|ownership>` and `chant lifecycle drift --read` (behold#995): the read to ask the member's engine for. Unset, the member kind's default read. */
+  driftRead?: string;
+  /** `chant workspace drift --stream` (behold#995): print the drift stream (drift-start, records, drift-settle) as NDJSON instead of one document. */
+  stream?: boolean;
+  /** `chant workspace drift --resource <addr>` and `chant lifecycle drift --resource` (behold#995): read one resource, through `choudoufu live-plan -resource` on a choudoufu member. */
+  resource?: string;
   /** `chant workspace graph --no-cache` (#2876): read every member, bypassing the per-member cache. */
   noCache?: boolean;
   /** `chant workspace graph --composites` (#2662): print each composite instance with the components that can deploy it. */

package/src/cloud-lister/aws.test.ts

@@ -0,0 +1,202 @@
+/**
+ * behold#1029: the AWS lister against a fake Cloud Control. Response shapes
+ * follow the pinned floci's CloudControlJsonHandler (source c688f52ee):
+ * `{ TypeName, ResourceDescriptions: [{ Identifier, Properties }] }`, with
+ * `Properties` a JSON string.
+ */
+import { describe, expect, it } from "vitest";
+import { listCloud } from "./index";
+import { ListerConfigError } from "./credentials";
+import { MASKED } from "./mask";
+import { signV4 } from "./sigv4";
+import { fakeFetcher, json, refusingChains, steppingClock } from "./fakes";
+import type { WireCall } from "./guard";
+
+const ENDPOINT = "http://localhost:4566";
+const CREDS = { accessKeyId: "test", secretAccessKey: "test" };
+
+function target() {
+  return { substrate: "aws" as const, aws: { endpoint: ENDPOINT, credentials: CREDS } };
+}
+
+function typeOf(call: WireCall): { TypeName: string; NextToken?: string } {
+  return JSON.parse(call.body ?? "{}");
+}
+
+describe("signV4", () => {
+  // AWS's published SigV4 test suite, case get-vanilla.
+  it("matches the get-vanilla known answer", () => {
+    const headers = signV4({
+      method: "GET",
+      url: "https://example.amazonaws.com/",
+      headers: {},
+      body: "",
+      region: "us-east-1",
+      service: "service",
+      credentials: { accessKeyId: "AKIDEXAMPLE", secretAccessKey: "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY" },
+      now: new Date("2015-08-30T12:36:00Z"),
+    });
+    expect(headers.authorization).toBe(
+      "AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20150830/us-east-1/service/aws4_request, SignedHeaders=host;x-amz-date, Signature=5fa00fa31553b73ebf1942676e86291e8372ff2a2260956d9b8aae1d763fbf31",
+    );
+  });
+});
+
+describe("listing aws", () => {
+  it("lists each type per region, pages, and fills the listing-result shape", async () => {
+    const fake = fakeFetcher((call) => {
+      const { TypeName, NextToken } = typeOf(call);
+      if (TypeName === "AWS::S3::Bucket" && !NextToken) {
+        return json(200, {
+          TypeName,
+          ResourceDescriptions: [
+            { Identifier: "web-assets", Properties: JSON.stringify({ BucketName: "web-assets", Arn: "arn:aws:s3:::web-assets", Tags: [{ Key: "tofu-estate", Value: "web" }, { Key: "tofu-address", Value: "aws_s3_bucket.assets" }] }) },
+          ],
+          NextToken: "page2",
+        });
+      }
+      if (TypeName === "AWS::S3::Bucket" && NextToken === "page2") {
+        return json(200, { TypeName, ResourceDescriptions: [{ Identifier: "logs", Properties: JSON.stringify({ BucketName: "logs" }) }] });
+      }
+      if (TypeName === "AWS::RDS::DBInstance") {
+        return json(200, {
+          TypeName,
+          ResourceDescriptions: [{ Identifier: "db1", Properties: JSON.stringify({ DBInstanceIdentifier: "db1", MasterUserPassword: "hunter2", Tags: [{ Key: "api-token", Value: "abc" }] }) }],
+        });
+      }
+      return undefined;
+    });
+    const result = await listCloud(
+      { substrate: "aws", scopeId: "000000000000", locations: ["us-east-1"], types: ["AWS::S3::Bucket", "AWS::RDS::DBInstance"] },
+      target(),
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [], version: "0.30.2" },
+    );
+
+    expect(result.listing).toBe("v1");
+    expect(result.source).toEqual({ name: "chant-lister", version: "0.30.2" });
+    expect(result.scope.types).toEqual(["AWS::RDS::DBInstance", "AWS::S3::Bucket"]);
+    expect(fake.calls.every((c) => c.url === `${ENDPOINT}/`)).toBe(true);
+    expect(fake.calls[0].headers.authorization).toMatch(/^AWS4-HMAC-SHA256 Credential=test\/\d{8}\/us-east-1\/cloudcontrolapi\/aws4_request/);
+    expect(fake.calls[0].headers["x-amz-target"]).toBe("CloudApiService.ListResources");
+
+    const bucket = result.resources.find((r) => r.nativeId === "web-assets")!;
+    expect(bucket.id).toBe("aws/000000000000/us-east-1/AWS::S3::Bucket/web-assets");
+    expect(bucket.listedType).toBe("AWS::S3::Bucket");
+    expect(bucket.location).toBe("us-east-1");
+    expect(bucket.cloudIds).toEqual([
+      { kind: "arn", value: "arn:aws:s3:::web-assets" },
+      { kind: "import-id", value: "web-assets" },
+    ]);
+    expect(bucket.tags).toEqual({ "tofu-estate": "web", "tofu-address": "aws_s3_bucket.assets" });
+    expect(bucket.facts).toEqual({
+      markers: { owner: "web", address: "aws_s3_bucket.assets", encoding: "escaped", source: "live" },
+      cloudIds: bucket.cloudIds,
+      observedAt: bucket.observedAt,
+    });
+    expect(Object.keys(bucket.facts).sort()).toEqual(["cloudIds", "markers", "observedAt"]);
+    expect(result.resources.map((r) => r.nativeId)).toContain("logs");
+
+    const db = result.resources.find((r) => r.nativeId === "db1")!;
+    expect(db.properties.MasterUserPassword).toBe(MASKED);
+    expect(db.tags["api-token"]).toBe(MASKED);
+    expect(JSON.stringify(result)).not.toContain("hunter2");
+    expect(JSON.stringify(result)).not.toContain('"abc"');
+
+    expect(result.coverage).toEqual([
+      { listedType: "AWS::RDS::DBInstance", location: "us-east-1", verdict: "listed" },
+      { listedType: "AWS::S3::Bucket", location: "us-east-1", verdict: "listed" },
+    ]);
+    expect(result.notes).toEqual([]);
+  });
+
+  it("lists a global type once, as location global", async () => {
+    const fake = fakeFetcher(() => json(200, { ResourceDescriptions: [{ Identifier: "app-role", Properties: JSON.stringify({ RoleName: "app-role", Arn: "arn:aws:iam::000000000000:role/app-role" }) }] }));
+    const result = await listCloud(
+      { substrate: "aws", scopeId: "000000000000", locations: ["us-east-1", "eu-west-1"], types: ["AWS::IAM::Role"] },
+      target(),
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [] },
+    );
+    expect(fake.calls.length).toBe(1);
+    expect(result.resources[0].id).toBe("aws/000000000000/global/AWS::IAM::Role/app-role");
+    expect(result.coverage).toEqual([{ listedType: "AWS::IAM::Role", location: "global", verdict: "listed" }]);
+  });
+
+  it("puts a type it cannot list in the notes, with its reason", async () => {
+    const fake = fakeFetcher((call) => {
+      const { TypeName } = typeOf(call);
+      if (TypeName === "AWS::Foo::Bar") return json(400, { __type: "com.amazon.cloudapiservice#UnsupportedActionException", message: "Resource type AWS::Foo::Bar does not support LIST action" });
+      if (TypeName === "AWS::EC2::SubnetRouteTableAssociation") return json(400, { __type: "InvalidRequestException", message: "Missing Or Invalid ResourceModel property in AWS::EC2::SubnetRouteTableAssociation list handler request input" });
+      if (TypeName === "AWS::S3::Bucket") return json(400, { __type: "AccessDeniedException", message: "not authorized" });
+      return undefined;
+    });
+    const result = await listCloud(
+      { substrate: "aws", scopeId: "000000000000", locations: ["us-east-1"], types: ["AWS::Foo::Bar", "AWS::EC2::SubnetRouteTableAssociation", "AWS::S3::Bucket"] },
+      target(),
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [] },
+    );
+    expect(result.resources).toEqual([]);
+    expect(result.coverage.map((c) => [c.listedType, c.verdict])).toEqual([
+      ["AWS::EC2::SubnetRouteTableAssociation", "unsupported-kind"],
+      ["AWS::Foo::Bar", "unsupported-kind"],
+      ["AWS::S3::Bucket", "no-credentials"],
+    ]);
+    expect(result.notes.map((n) => [n.code, n.listedType])).toEqual([
+      ["needs-parent", "AWS::EC2::SubnetRouteTableAssociation"],
+      ["no-lister", "AWS::Foo::Bar"],
+      ["no-credentials", "AWS::S3::Bucket"],
+    ]);
+    expect(result.notes[1].message).toContain("does not support LIST");
+  });
+
+  it("filters by tag after listing, and marks coverage filtered", async () => {
+    const fake = fakeFetcher(() =>
+      json(200, {
+        ResourceDescriptions: [
+          { Identifier: "a", Properties: JSON.stringify({ Tags: [{ Key: "env", Value: "prod" }] }) },
+          { Identifier: "b", Properties: JSON.stringify({ Tags: [{ Key: "env", Value: "dev" }] }) },
+        ],
+      }),
+    );
+    const result = await listCloud(
+      { substrate: "aws", scopeId: "000000000000", locations: ["us-east-1"], types: ["AWS::SQS::Queue"], tagFilter: { env: "prod" } },
+      target(),
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [] },
+    );
+    expect(result.resources.map((r) => r.nativeId)).toEqual(["a"]);
+    expect(result.coverage[0].verdict).toBe("filtered");
+    expect(result.notes.map((n) => n.code)).toEqual(["tag-filter"]);
+  });
+
+  it('lists the default types for types "*" and says so', async () => {
+    const fake = fakeFetcher(() => json(200, { ResourceDescriptions: [] }));
+    const result = await listCloud(
+      { substrate: "aws", scopeId: "000000000000", locations: ["us-east-1"], types: "*" },
+      target(),
+      { fetcher: fake.fetcher, chains: refusingChains(), now: steppingClock(), retryDelays: [] },
+    );
+    expect(result.notes[0].code).toBe("default-types");
+    expect(fake.calls.length).toBeGreaterThan(20);
+  });
+
+  it("refuses every region, which would need a call off the allowlist", async () => {
+    const fake = fakeFetcher(() => undefined);
+    await expect(
+      listCloud({ substrate: "aws", scopeId: "0", locations: "*", types: ["AWS::S3::Bucket"] }, target(), { fetcher: fake.fetcher, chains: refusingChains() }),
+    ).rejects.toThrow(ListerConfigError);
+    expect(fake.calls).toEqual([]);
+  });
+
+  it("never asks the default provider chain when an endpoint is given", async () => {
+    const chains = refusingChains();
+    const fake = fakeFetcher(() => undefined);
+    await expect(
+      listCloud(
+        { substrate: "aws", scopeId: "0", locations: ["us-east-1"], types: ["AWS::S3::Bucket"] },
+        { substrate: "aws", aws: { endpoint: ENDPOINT } },
+        { fetcher: fake.fetcher, chains },
+      ),
+    ).rejects.toThrow(/needs static credentials/);
+    expect(chains.count.aws).toBe(0);
+    expect(fake.calls).toEqual([]);
+  });
+});