@intentius/chant 0.124.51 → 0.124.54

package/src/cli/handlers/run-groups-cli.test.ts

@@ -0,0 +1,229 @@
+/**
+ * `chant components fan-out` and `chant run --components` form composed
+ * groups (ws-107, #4465), driven through their CLI handlers (chant#4505).
+ * `release-groups.test.ts` covers `runFanOut` and `runInterpretDriver` given
+ * a grouped plan; this drives the commands that form the plan themselves, the
+ * path that went red at round 1's epic-ready (`run --components` forming its
+ * groups before the graph was resolved).
+ *
+ * Discovery, config, the capability registry and the gate ledger are fakes.
+ * The fake `cfn-deploy` creates one stack whose `id` is known only after it
+ * applies; with the group pair it declares `planGroup` and `runGroup`. b reads
+ * a's id and c reads b's, so a, b and c form one group.
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { Component } from "../../components/component";
+import type { ParsedArgs } from "../registry";
+
+const affectedStacksMock = vi.fn();
+const discoverComponentsMock = vi.fn();
+const buildCapabilityRegistryMock = vi.fn();
+
+vi.mock("../../lifecycle/affected", () => ({
+  affectedStacks: (...args: unknown[]) => affectedStacksMock(...args),
+}));
+
+vi.mock("../../components/discover", () => ({
+  discoverComponents: (...args: unknown[]) => discoverComponentsMock(...args),
+}));
+
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: async () => ({ config: { lexicons: ["aws"] } }) };
+});
+
+vi.mock("../../components/capability-plugin-loader", () => ({
+  buildCapabilityRegistry: (...args: unknown[]) => buildCapabilityRegistryMock(...args),
+}));
+
+/** The real gate ledger is this repository's `chant/lifecycle` branch; a test never appends to it. */
+vi.mock("../../op/gate", async () => {
+  const actual = await vi.importActual<typeof import("../../op/gate")>("../../op/gate");
+  return { ...actual, gitGateLedgerPort: () => actual.memoryGateLedgerPort(), gateIsSealed: async () => false };
+});
+
+/** The release ledger, for the same reason. */
+vi.mock("../../components/auto-release", async () => {
+  const actual = await vi.importActual<typeof import("../../components/auto-release")>("../../components/auto-release");
+  return { ...actual, maybeRecordAutoRelease: async () => ({ recorded: false, reason: "opted-out" }) };
+});
+
+/** `run --components` on the local runtime: the real `runComponents`, with the test's registry. */
+vi.mock("../../op/runtimes/local", async () => {
+  const { runComponents } = await import("../../components/cli-support");
+  const { memoryGateLedgerPort } = await import("../../op/gate");
+  return {
+    createLocalOpRuntime: () => ({
+      name: "local",
+      runComponents: async (path: string, selector: string, options: object) =>
+        runComponents(path, selector, { ...options, registry: await buildCapabilityRegistryMock(), config: {}, revision: null, gates: memoryGateLedgerPort() }),
+    }),
+  };
+});
+
+const { CapabilityRegistry } = await import("../../components/capability");
+const { computePlanDigest } = await import("../../lifecycle/plan-digest");
+const { runComponentsFanOut } = await import("./fan-out");
+const { runOpComponents } = await import("./run");
+
+interface StackInput {
+  stack: string;
+  vars?: Record<string, unknown>;
+}
+
+const so = (stack: string, name: string) => ({ stackOutput: { stack, name } });
+const stack = (name: string, dependsOn: string[] = [], vars?: Record<string, unknown>): Component => ({
+  name,
+  dependsOn,
+  deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: name, ...(vars ? { vars } : {}) }] }],
+});
+/** a; b reads a's new id; c reads b's. */
+const ABC = [stack("a"), stack("b", ["a"], { upstream: so("a", "id") }), stack("c", ["b"], { upstream: so("b", "id") })];
+
+let group = true;
+let planned: string[] = [];
+let applied: string[] = [];
+let planGroupCalls: string[][] = [];
+let runGroupCalls: string[][] = [];
+let stderrLines: string[] = [];
+
+function registry() {
+  const r = new CapabilityRegistry();
+  const planOf = (input: StackInput) => {
+    const planDigest = computePlanDigest("cfn-deploy", { stack: input.stack, vars: input.vars ?? null });
+    return {
+      member: input.stack,
+      planDigest,
+      artifact: { planDigest },
+      outputs: { known: {}, unknown: ["id"] },
+      changeSet: {
+        member: { member: input.stack, lexicon: "aws", planner: "tofu" as const, status: "planned" as const, planDigest, holes: [] },
+        entries: [{ member: input.stack, lexicon: "aws", planner: "tofu" as const, address: "res.x", type: "res", action: "create" as const, attributes: [] }],
+      },
+    };
+  };
+  r.register({
+    kind: "cfn-deploy",
+    async plan(_ctx: unknown, input: StackInput) {
+      planned.push(input.stack);
+      return planOf(input);
+    },
+    async run(_ctx: unknown, input: StackInput) {
+      applied.push(input.stack);
+      return { outputs: { id: `${input.stack}-id` } };
+    },
+    ...(group
+      ? {
+          async planGroup(_ctx: unknown, members: ReadonlyArray<{ component: string; input?: StackInput }>) {
+            planGroupCalls.push(members.map((m) => m.component));
+            return {
+              members: Object.fromEntries(members.map((m) => [m.component, planOf(m.input!)])),
+              digest: computePlanDigest("fake-composition", members.map((m) => m.component)),
+              artifact: { composed: members.map((m) => m.component) },
+            };
+          },
+          async runGroup(_ctx: unknown, _run: unknown, members: ReadonlyArray<{ component: string }>) {
+            runGroupCalls.push(members.map((m) => m.component));
+            return { members: Object.fromEntries(members.map((m) => [m.component, { status: "applied" as const, outputs: { id: `${m.component}-id` } }])) };
+          },
+        }
+      : {}),
+  } as never);
+  return r;
+}
+
+const baseArgs = { format: "", fix: false, watch: false, verbose: false, help: false, live: false };
+const fanOutCtx = (overrides: Partial<ParsedArgs> = {}) => ({ args: { command: "components", path: "fan-out", ...baseArgs, ...overrides } as ParsedArgs, plugins: [], serializers: [] }) as never;
+const runCtx = (selector: string) => ({ args: { command: "run", path: selector, components: true, on: "local", ...baseArgs } as ParsedArgs, plugins: [] }) as never;
+const stderr = () => stderrLines.join("\n");
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  group = true;
+  planned = [];
+  applied = [];
+  planGroupCalls = [];
+  runGroupCalls = [];
+  stderrLines = [];
+  discoverComponentsMock.mockResolvedValue({
+    components: new Map(ABC.map((c) => [c.name, { component: c, exportName: c.name, filePath: `${c.name}.component.ts` }])),
+    sourceFiles: [],
+    errors: [],
+  });
+  buildCapabilityRegistryMock.mockImplementation(async () => registry());
+  affectedStacksMock.mockResolvedValue({ changed: ["a"], dependents: [], indeterminate: [] });
+  vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+    stderrLines.push(args.map(String).join(" "));
+  });
+  vi.spyOn(console, "log").mockImplementation(() => {});
+  vi.spyOn(process.stderr, "write").mockImplementation((chunk: unknown) => {
+    stderrLines.push(String(chunk));
+    return true;
+  });
+  vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("chant components fan-out forms groups (#4465, chant#4505)", () => {
+  test("a changed a pulls in b and c; the three plan with one planGroup and apply with one runGroup, and the report names the group", async () => {
+    const exit = await runComponentsFanOut(fanOutCtx({ base: "main" }));
+    expect(exit).toBe(0);
+    expect(planGroupCalls).toEqual([["a", "b", "c"]]);
+    expect(runGroupCalls).toEqual([["a", "b", "c"]]);
+    // No member ran its own deploy.
+    expect(applied).toEqual([]);
+    expect(stderr()).toContain("a, b and c plan and apply as one (cfn-deploy, wave 1");
+    expect(stderr()).toContain("a applied; b applied; c applied");
+  });
+
+  test("without the group pair each component applies by itself, as before", async () => {
+    group = false;
+    const exit = await runComponentsFanOut(fanOutCtx({ base: "main" }));
+    expect(exit).toBe(0);
+    expect(planGroupCalls).toEqual([]);
+    expect(runGroupCalls).toEqual([]);
+    expect(applied).toEqual(["a", "b", "c"]);
+    expect(stderr()).not.toContain("plan and apply as one");
+  });
+});
+
+describe("chant run --components forms groups (#4465, chant#4505)", () => {
+  test("all: one planGroup and one runGroup over a, b and c, and no member's own deploy", async () => {
+    expect(await runOpComponents(runCtx("all"))).toBe(0);
+    expect(planGroupCalls).toEqual([["a", "b", "c"]]);
+    expect(runGroupCalls).toEqual([["a", "b", "c"]]);
+    expect(applied).toEqual([]);
+  });
+
+  test("a list that pulls in its dependency groups the whole set the run resolved", async () => {
+    expect(await runOpComponents(runCtx("b,c"))).toBe(0);
+    expect(planGroupCalls).toEqual([["a", "b", "c"]]);
+    expect(runGroupCalls).toEqual([["a", "b", "c"]]);
+    expect(applied).toEqual([]);
+  });
+
+  test("a dependency outside the discovered set fails as it does without groups, before any group plans (round 1's red)", async () => {
+    const withUnknown = [...ABC, stack("d", ["missing"])];
+    discoverComponentsMock.mockResolvedValue({
+      components: new Map(withUnknown.map((c) => [c.name, { component: c, exportName: c.name, filePath: `${c.name}.component.ts` }])),
+      sourceFiles: [],
+      errors: [],
+    });
+    const exit = await runOpComponents(runCtx("all")).catch(() => 1);
+    expect(exit).not.toBe(0);
+    expect(stderr()).toContain("missing");
+    expect(planGroupCalls).toEqual([]);
+    expect(runGroupCalls).toEqual([]);
+    expect(applied).toEqual([]);
+  });
+
+  test("without the group pair each component applies by itself, in order", async () => {
+    group = false;
+    expect(await runOpComponents(runCtx("all"))).toBe(0);
+    expect(planGroupCalls).toEqual([]);
+    expect(applied).toEqual(["a", "b", "c"]);
+  });
+});

package/src/cli/handlers/scenario.test.ts

@@ -24,6 +24,19 @@ vi.mock("../../lifecycle/git", () => ({
   fetchLifecycle: () => fetchLifecycleMock(),
   readEnvironmentSnapshots: (...args: unknown[]) => readEnvironmentSnapshotsMock(...args),
 }));
+// `snapshot(env)` reads the index store (#4519); this one hands the read to the mocks above.
+vi.mock("../../lifecycle/snapshot-store", async () => {
+  const { fakeSnapshotStore } = await import("../../lifecycle/snapshot-store-fake");
+  const store = fakeSnapshotStore({
+    fetch: async () => {
+      await fetchLifecycleMock();
+    },
+  });
+  return {
+    resolveSnapshotStore: async () => store,
+    readEnvironmentSnapshotsFrom: async (_store: unknown, environment: string) => readEnvironmentSnapshotsMock(environment),
+  };
+});
 vi.mock("../../config", async () => {
   const actual = await vi.importActual<typeof import("../../config")>("../../config");
   return { ...actual, loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args) };

package/src/cli/handlers/scenario.ts

@@ -2,7 +2,7 @@ import { resolve } from "node:path";
 import { readFile } from "node:fs/promises";
 import { commandBuildParams } from "../build-params-cli";
 import { build, type BuildResult } from "../../build";
-import { readEnvironmentSnapshots, fetchLifecycle } from "../../lifecycle/git";
+import { readEnvironmentSnapshotsFrom, resolveSnapshotStore } from "../../lifecycle/snapshot-store";
 import { buildChangeSet, type ChangeSet, type ChangeSetEntry } from "../../lifecycle/change-set";
 import {
   planReceipts,
@@ -88,11 +88,11 @@ export async function runScenarioCheck(ctx: CommandContext): Promise<number> {
   // of any one scenario's fixture.
   const receipts = collectEffectReceipts(buildResult.entities);
 
-  // `snapshot(env)` reads the chant/lifecycle orphan branch — fetch once,
-  // up front, the same pre-read `runLifecyclePlan` does, rather than once per
-  // scenario that needs it.
+  // `snapshot(env)` reads the index store (#4519) — fetch once, up front,
+  // the same pre-read `runLifecyclePlan` does, rather than once per scenario
+  // that needs it.
   if ([...scenarios.values()].some((s) => s.given.kind === "env")) {
-    await fetchLifecycle();
+    await (await resolveSnapshotStore()).fetch();
   }
 
   const results: Array<{ entityName: string; scenario: ScenarioDeclaration; verdict: ScenarioVerdict; env: string }> = [];
@@ -234,9 +234,10 @@ async function resolveGiven(given: ScenarioGiven): Promise<GivenResolution> {
     };
   }
 
-  const stored = await readEnvironmentSnapshots(given.env);
+  const store = await resolveSnapshotStore();
+  const stored = await readEnvironmentSnapshotsFrom(store, given.env);
   if (stored.size === 0) {
-    const error = `no recorded snapshot for environment "${given.env}" on chant/lifecycle — record one with \`chant lifecycle snapshot ${given.env}\``;
+    const error = `no recorded snapshot for environment "${given.env}" in ${store.where} — record one with \`chant lifecycle snapshot ${given.env}\`, or name a checked-in fixture`;
     return { env: given.env, perLexicon: new Map(), error, behaviour: { missing: error } };
   }
   const perLexicon = new Map<string, LifecycleSnapshot>();

package/src/cli/handlers/search-index.test.ts

@@ -0,0 +1,255 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import type { ParsedArgs } from "../registry";
+import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
+import { createMockPlugin } from "../../../../test-utils/src/mock-plugin";
+import { NO_LEXICON_DETECTED_MESSAGE } from "../../detectLexicon";
+import type { DeclaredIdentity, IndexIdentity } from "../../lifecycle/identity-match";
+import type { IndexDocument } from "../../lifecycle/index-document";
+import { typeListing, type ListedResource, type ListingResult } from "../../lifecycle/type-listing";
+import { fakeSnapshotStore } from "../../lifecycle/snapshot-store-fake";
+
+// #4525: `chant search --index <ref>` answers from an index version in the
+// store: the declared rows joined to it, each with its verdict, or the index
+// alone with no project. No cloud is read; the store is a fake holding one
+// fixture version typed the way behold#1026 writes one.
+
+const discoverMock = vi.fn();
+vi.mock("../../discovery/index", () => ({
+  discover: (...a: unknown[]) => discoverMock(...a),
+}));
+const loadPluginsMock = vi.fn();
+const resolveLexMock = vi.fn();
+vi.mock("../plugins", async () => {
+  const actual = await vi.importActual<typeof import("../plugins")>("../plugins");
+  return {
+    ...actual,
+    loadPlugins: (...a: unknown[]) => loadPluginsMock(...a),
+    resolveProjectLexicons: (...a: unknown[]) => resolveLexMock(...a),
+  };
+});
+const loadChantConfigMock = vi.fn();
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: (...a: unknown[]) => loadChantConfigMock(...a) };
+});
+const storeMock = vi.fn();
+vi.mock("../../lifecycle/snapshot-store", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/snapshot-store")>("../../lifecycle/snapshot-store");
+  return { ...actual, resolveSnapshotStore: (...a: unknown[]) => Promise.resolve(storeMock(...a)) };
+});
+const liveRead = vi.fn();
+
+import searchSchema from "../../workspace/search.schema.json";
+import { contract } from "../../workspace/__fixtures__/contract-repo";
+const { expectValid } = contract(searchSchema);
+const { runSearch } = await import("./search");
+
+const PARTS: Record<string, string[]> = { "Store::Bucket": ["BucketName"] };
+const identity: IndexIdentity = {
+  substrate: "aws",
+  declaredIdentity(entityType, props): DeclaredIdentity {
+    const parts = PARTS[entityType];
+    if (entityType === "Queue::Queue") return { kind: "unmatchable", reason: "no-binding", detail: "the queue URL is assigned by the service" };
+    if (!parts) return { kind: "unmatchable", reason: "unsupported-kind", detail: `${entityType} has no primary identifier on record` };
+    const v = props[parts[0]];
+    if (typeof v !== "string") return { kind: "unmatchable", reason: "no-binding", detail: "identity is not in the declaration" };
+    return { kind: "identifier", listedType: entityType, identifier: v, global: false };
+  },
+};
+
+const r = (listedType: string, nativeId: string, properties: Record<string, unknown>, tags: Record<string, string> = {}): ListedResource => ({
+  listedType,
+  location: "us-east-1",
+  nativeId,
+  cloudIds: [{ kind: "import-id", value: nativeId }],
+  tags,
+  properties,
+  observedAt: "2026-10-26T09:00:01.000Z",
+});
+const listing: ListingResult = {
+  listing: "v1",
+  source: { name: "behold-lister", version: "0.0.0-test" },
+  scope: { substrate: "aws", scopeId: "000000000000", locations: ["us-east-1"], types: ["Store::Bucket", "Queue::Queue"] },
+  startedAt: "2026-10-26T09:00:00.000Z",
+  completedAt: "2026-10-26T09:00:04.000Z",
+  resources: [
+    r("Store::Bucket", "shop-assets", { BucketName: "shop-assets", Arn: "arn:aws:s3:::shop-assets" }, { team: "web" }),
+    r("Store::Bucket", "made-by-hand", { BucketName: "made-by-hand" }, { team: "data" }),
+    r("Queue::Queue", "https://sqs.us-east-1.amazonaws.com/000000000000/orders", { QueueName: "orders" }),
+  ],
+  coverage: [
+    { listedType: "Store::Bucket", location: "us-east-1", verdict: "listed" },
+    { listedType: "Queue::Queue", location: "us-east-1", verdict: "listed" },
+  ],
+  notes: [],
+};
+const doc: IndexDocument = typeListing(listing, [{ name: "fake", listedTypes: { substrate: "aws", kindFor: (t) => t } }]);
+const KEY = doc.stamp.scopeKey;
+const indexStore = fakeSnapshotStore({
+  readIndexLatest: async (k) => (k === KEY ? doc : null),
+  readIndexAt: async () => null,
+});
+
+function decl<T extends object>(base: T): Declarable & T {
+  return { [DECLARABLE_MARKER]: true, ...base } as Declarable & T;
+}
+
+function makeArgs(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
+  return {
+    command: "search", path: "kind:Bucket",
+    format: "", fix: false, watch: false, verbose: false, help: false, live: false, index: KEY,
+    ...overrides,
+  };
+}
+
+const plugin = { ...createMockPlugin({ name: "fake", describeResources: async (...a: unknown[]) => liveRead(...a) }), indexIdentity: identity };
+
+let out: string[];
+let err: string[];
+beforeEach(() => {
+  out = [];
+  err = [];
+  vi.spyOn(console, "log").mockImplementation((s: string) => { out.push(s); });
+  vi.spyOn(console, "error").mockImplementation((s: string) => { err.push(s); });
+  discoverMock.mockReset();
+  loadPluginsMock.mockReset();
+  resolveLexMock.mockReset();
+  loadChantConfigMock.mockReset();
+  storeMock.mockReset();
+  storeMock.mockReturnValue(indexStore);
+  liveRead.mockReset();
+});
+
+describe("search --index with no project", () => {
+  beforeEach(() => {
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    resolveLexMock.mockRejectedValue(new Error(NO_LEXICON_DETECTED_MESSAGE));
+    loadPluginsMock.mockResolvedValue([]);
+  });
+
+  test("answers from the index alone, each row an indexed node, with the stamp on the provenance line", async () => {
+    expect(await runSearch({ args: makeArgs(), plugins: [], serializers: [] })).toBe(0);
+    const stdout = out.join("\n");
+    expect(stdout).toContain("aws/000000000000/us-east-1/Store::Bucket/made-by-hand  Store::Bucket  made-by-hand");
+    expect(stdout).toContain("aws/000000000000/us-east-1/Store::Bucket/shop-assets  Store::Bucket  shop-assets");
+    expect(stdout).not.toContain("Queue::Queue");
+    expect(stdout).toMatch(/— index only, no project · cloud\/aws\/000000000000\/[0-9a-f]{12}@20261026T090000Z-[0-9a-f]{12} taken 2026-10-26T09:00:00.000Z by behold-lister 0.0.0-test · 2 rows/);
+    expect(discoverMock).not.toHaveBeenCalled();
+  });
+
+  test("a tag: term reads an indexed node's tag map", async () => {
+    expect(await runSearch({ args: makeArgs({ path: "tag:team=data" }), plugins: [], serializers: [] })).toBe(0);
+    const stdout = out.join("\n");
+    expect(stdout).toContain("made-by-hand");
+    expect(stdout).not.toContain("shop-assets  ");
+  });
+
+  test("--json is a search document whose source is the index version", async () => {
+    expect(await runSearch({ args: makeArgs({ json: true }), plugins: [], serializers: [] })).toBe(0);
+    const json = JSON.parse(out.join(""));
+    expectValid(json);
+    expect(json.source).toMatchObject({ kind: "index", scopeKey: KEY, observedAt: "2026-10-26T09:00:00.000Z", digest: doc.stamp.digest, project: false });
+    expect(json.matches.map((m: { id: string }) => m.id)).toEqual([
+      "aws/000000000000/us-east-1/Store::Bucket/made-by-hand",
+      "aws/000000000000/us-east-1/Store::Bucket/shop-assets",
+    ]);
+    expect(json.matches[0].displayId).toBe(json.matches[0].id);
+    expect(json.matches[0].join).toBeUndefined();
+  });
+
+  test("an empty answer still names the version it read", async () => {
+    expect(await runSearch({ args: makeArgs({ path: "kind:Bucket attr:BucketName=nothing-like-this" }), plugins: [], serializers: [] })).toBe(0);
+    const stdout = out.join("\n");
+    expect(stdout).toContain("(no matches)");
+    expect(stdout).toContain("— index only, no project");
+  });
+});
+
+describe("search --index with a project", () => {
+  const east = new Map<string, Declarable>([
+    ["assets", decl({ lexicon: "fake", entityType: "Store::Bucket", props: { BucketName: "shop-assets" } })],
+    ["archive", decl({ lexicon: "fake", entityType: "Store::Bucket", props: { BucketName: "never-made" } })],
+    ["orders", decl({ lexicon: "fake", entityType: "Queue::Queue", props: { QueueName: "orders" } })],
+  ]);
+
+  beforeEach(() => {
+    loadChantConfigMock.mockResolvedValue({ config: { stacks: [{ name: "east", region: "us-east-1", src: "east" }] } });
+    resolveLexMock.mockResolvedValue(["fake"]);
+    loadPluginsMock.mockResolvedValue([plugin]);
+    discoverMock.mockResolvedValue({ entities: east, errors: [], sourceFiles: [] });
+  });
+
+  test("declared rows join through the lexicon's index match, each row showing its verdict, and nothing reads live", async () => {
+    expect(await runSearch({ args: makeArgs(), plugins: [], serializers: [] })).toBe(0);
+    const stdout = out.join("\n");
+    expect(stdout).toContain("assets  Store::Bucket  shop-assets");
+    expect(stdout).toContain("archive  Store::Bucket  (absent)");
+    // An indexed bucket no declaration binds is not a declared row.
+    expect(stdout).not.toContain("made-by-hand");
+    expect(stdout).toMatch(/— observed from index cloud\/aws\/000000000000\/[0-9a-f]{12}@20261026T090000Z-[0-9a-f]{12} taken 2026-10-26T09:00:00.000Z · bound 1\/2 · absent 1/);
+    expect(liveRead).not.toHaveBeenCalled();
+  });
+
+  test("a declaration with no identity to match is no-binding, never absent", async () => {
+    expect(await runSearch({ args: makeArgs({ path: "kind:Queue" }), plugins: [], serializers: [] })).toBe(0);
+    const stdout = out.join("\n");
+    expect(stdout).toContain("orders  Queue::Queue  (no-binding)");
+    expect(stdout).toContain("bound 0/1 · no-binding 1");
+  });
+
+  test("--json carries each row's join and validates against the search schema", async () => {
+    expect(await runSearch({ args: makeArgs({ path: "kind:Store::Bucket", json: true, show: "Arn" }), plugins: [], serializers: [] })).toBe(0);
+    const json = JSON.parse(out.join(""));
+    expectValid(json);
+    expect(json.source).toMatchObject({ kind: "index", project: true });
+    const byId = Object.fromEntries(json.matches.map((m: { id: string }) => [m.id, m]));
+    expect(byId["east::assets"]).toMatchObject({
+      physicalId: "shop-assets",
+      show: { Arn: "arn:aws:s3:::shop-assets" },
+      join: { verdict: "bound", node: "aws/000000000000/us-east-1/Store::Bucket/shop-assets", nativeId: "shop-assets" },
+    });
+    expect(byId["east::archive"]).toMatchObject({ join: { verdict: "absent", identifier: "never-made", location: "us-east-1" } });
+    expect(byId["east::archive"].physicalId).toBeUndefined();
+    expect(json.provenance).toContain("bound 1/2 · absent 1");
+  });
+});
+
+describe("search --index refusals", () => {
+  beforeEach(() => {
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    resolveLexMock.mockRejectedValue(new Error(NO_LEXICON_DETECTED_MESSAGE));
+    loadPluginsMock.mockResolvedValue([]);
+  });
+
+  test("--index with --live, --snapshot or --ambient is refused before anything is read", async () => {
+    for (const extra of [{ live: true, env: "dev" }, { snapshot: "latest", env: "dev" }, { ambient: true }] as Partial<ParsedArgs>[]) {
+      out = [];
+      expect(await runSearch({ args: makeArgs({ ...extra, json: true }), plugins: [], serializers: [] })).toBe(1);
+      const json = JSON.parse(out.join(""));
+      expectValid(json);
+      expect(json.error.code).toBe("usage-invalid");
+      expect(json.error.message).toContain("--index or");
+    }
+    expect(storeMock).not.toHaveBeenCalled();
+  });
+
+  test("a ref that is not a scope key is usage-invalid, with the shape in the hint", async () => {
+    expect(await runSearch({ args: makeArgs({ index: "my-account", json: true }), plugins: [], serializers: [] })).toBe(1);
+    const json = JSON.parse(out.join(""));
+    expectValid(json);
+    expect(json.error).toMatchObject({ code: "usage-invalid", hint: expect.stringContaining("scope key") });
+  });
+
+  test("a scope key the store holds nothing under is index-unavailable", async () => {
+    expect(await runSearch({ args: makeArgs({ index: "cloud/aws/111111111111/0123456789ab", json: true }), plugins: [], serializers: [] })).toBe(1);
+    const json = JSON.parse(out.join(""));
+    expectValid(json);
+    expect(json.error.code).toBe("index-unavailable");
+    expect(json.error.message).toContain("cloud/aws/111111111111/0123456789ab");
+  });
+
+  test("a version the store does not hold is index-unavailable", async () => {
+    expect(await runSearch({ args: makeArgs({ index: `${KEY}@20261026T090000Z-ffffffffffff` }), plugins: [], serializers: [] })).toBe(1);
+    expect(err.join("\n")).toContain("no index version 20261026T090000Z-ffffffffffff");
+  });
+});

package/src/cli/handlers/search-json.test.ts

@@ -229,7 +229,7 @@ describe("search --json refusals are a document with error, exit 1 (#4367)", ()
       error: {
         code: "query-invalid",
         message: "\"effectiveIngress:tcp:22\" is not a term — there is no \"effectiveIngress:\" prefix",
-        hint: "for an attribute, say attr:effectiveIngress=tcp:22; the prefixes are kind:, attr:, tag:, and ->/<- for edges",
+        hint: "for an attribute, say attr:effectiveIngress=tcp:22; the prefixes are kind:, attr:, tag:, id:, and ->/<- for edges",
       },
     });
     expect(err.join("\n")).toContain("is not a term");