@intentius/chant 0.33.0 → 0.33.1

package/dist/cli/handlers/search.d.ts

@@ -24,6 +24,19 @@ import type { CommandContext } from "../registry.js";
  * thousands.
  */
 export declare function runSearch(ctx: CommandContext): Promise<number>;
+/**
+ * Name the facts chant computed for the kinds in this result that the query did not use.
+ *
+ * A provider API can only return what it stores; chant additionally folds multi-hop topology
+ * onto a node, and a caller has no way to know that surface exists. Reporting it turns a
+ * one-shot query into a conversation with the graph — ask something, learn what else is
+ * knowable about the same resources, refine.
+ *
+ * The names come from {@link GraphIR.derivedAttrs}, recorded by whichever enrichment pass
+ * produced them. Nothing here knows what any attribute means or which question it answers;
+ * add a pass and its facts appear, remove one and they stop.
+ */
+declare function derivedSurface(terms: Term[], matches: IRNode[], ir: GraphIR): void;
 /**
  * `--explain` footer (#1139): a compact, model-DERIVED summary that gives a
  * small model a reason to trust the result instead of re-deriving it with a
@@ -34,6 +47,15 @@ export declare function runSearch(ctx: CommandContext): Promise<number>;
  * any expected answer, so it stays a fair, question-agnostic capability.
  */
 declare function explain(terms: Term[], matches: IRNode[], ir: GraphIR, byId: Map<string, IRNode>, query: string): void;
+/**
+ * On a miss, name the attributes the queried kind actually carries. A graph knows
+ * its own schema, so a caller who guessed an attribute name — or did not know a
+ * derived one existed — can see what is queryable instead of falling back to a
+ * lossy CLI sweep. Read off the nodes present, so it stays a property of the
+ * graph rather than of any expected answer: whatever the estate holds is what
+ * this lists, and it says nothing about which attribute answers a question.
+ */
+declare function availableAttrs(terms: Term[], ir: GraphIR): void;
 declare function describeTerm(t: Term): string;
 interface Term {
     kind: "word" | "kind" | "tag" | "attr" | "edge";
@@ -53,6 +75,8 @@ export declare const __searchInternals: {
     formatRow: typeof formatRow;
     explain: typeof explain;
     describeTerm: typeof describeTerm;
+    derivedSurface: typeof derivedSurface;
+    availableAttrs: typeof availableAttrs;
 };
 export {};
 //# sourceMappingURL=search.d.ts.map

package/dist/cli/handlers/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/search.ts"],"names":[],"mappings":"AAEA,OAAO,EAAuD,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAShH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAwFpE;AAED;;;;;;;;GAQG;AACH,iBAAS,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAwB9G;AAED,iBAAS,YAAY,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAMrC;AAED,UAAU,IAAI;IACZ,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAChD,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,kFAAkF;IAClF,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACnB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAcD,iBAAS,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CASzC;AAeD,iBAAS,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CA6BxF;AAED,iBAAS,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAcpD;AAED,wCAAwC;AACxC,eAAO,MAAM,iBAAiB;;;;;;CAA8D,CAAC"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/search.ts"],"names":[],"mappings":"AAEA,OAAO,EAAuD,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAShH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA0FpE;AAED;;;;;;;;;;;GAWG;AACH,iBAAS,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAa3E;AAED;;;;;;;;GAQG;AACH,iBAAS,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAyB9G;AAED;;;;;;;GAOG;AACH,iBAAS,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAWxD;AAED,iBAAS,YAAY,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAMrC;AAED,UAAU,IAAI;IACZ,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAChD,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,kFAAkF;IAClF,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACnB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAcD,iBAAS,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CASzC;AAeD,iBAAS,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CA6BxF;AAED,iBAAS,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAcpD;AAED,wCAAwC;AACxC,eAAO,MAAM,iBAAiB;;;;;;;;CAA8F,CAAC"}

package/dist/graph-effective.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-effective.d.ts","sourceRoot":"","sources":["../src/graph-effective.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAU,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAqF5D"}
+{"version":3,"file":"graph-effective.d.ts","sourceRoot":"","sources":["../src/graph-effective.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAU,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CA2F5D"}

package/dist/graph-ir.d.ts

@@ -173,6 +173,13 @@ export interface GraphIR {
     imports?: IRImport[];
     /** The CI/pipeline projection alongside the component graph (#989) — see {@link IRPipeline}. */
     pipeline?: IRPipeline;
+    /**
+     * Attributes chant computed rather than read back from the provider, keyed by the kind
+     * they were folded onto. An enrichment pass records what it derived here so callers can
+     * report the graph's own surface without knowing any attribute name — the set is whatever
+     * the passes produced, not a list maintained by hand.
+     */
+    derivedAttrs?: Record<string, string[]>;
 }
 /**
  * Build the graph IR from resolved entities (the output of `discover`). Pure and

package/dist/graph-ir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-ir.d.ts","sourceRoot":"","sources":["../src/graph-ir.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graph-ir.d.ts","sourceRoot":"","sources":["../src/graph-ir.ts"],"names":[],"mappings":"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"}

package/dist/observation.d.ts

@@ -120,4 +120,75 @@ export declare function mergeObservations(parts: Iterable<NormalizedObservation>
 export declare function unobservedReasonText(reason: UnobservedReason): string;
 /** `name — reason (detail)`, the shared rendering for CLI and plan output. */
 export declare function formatUnobserved(name: string, entry: UnobservedEntity): string;
+/** One declared entity handed to the harness. */
+export interface DeclaredEntity {
+    /** chant entity name — the key every outcome is filed under. */
+    name: string;
+    /** Declared entity type (e.g. `AWS::EC2::VPC`). */
+    type: string;
+    /** Declared properties, for the adapter to derive a physical address from. */
+    props: Record<string, unknown>;
+}
+/**
+ * The outcome of reading one entity, mapped onto the tri-state:
+ * - `present` — a key in `resources`.
+ * - `absent` — in neither map (the provider was asked and reported it missing).
+ * - `unobserved` — a typed NOT-OBSERVED (unsupported kind, filtered, read error).
+ */
+export type EntityObservation = {
+    present: ResourceMetadata;
+} | {
+    absent: true;
+} | {
+    unobserved: {
+        reason: UnobservedReason;
+        detail?: string;
+    };
+};
+/** What a lexicon supplies to drive the harness. `Client` is its transport handle. */
+export interface ObserverAdapter<Client> {
+    /**
+     * Reach the provider on the applier's transport. Throw for a whole-lexicon
+     * failure; {@link classifyBindFailure} decides what the throw means.
+     */
+    bind(): Promise<Client>;
+    /**
+     * Map a `bind()` throw to a typed whole-lexicon reason (every entity becomes
+     * NOT-OBSERVED with it), or `"rethrow"` for a loud refusal that must not be
+     * swallowed — a context/subscription mismatch, which core turns into an
+     * honest hole per entity at a higher layer.
+     */
+    classifyBindFailure(err: unknown): {
+        reason: UnobservedReason;
+        detail?: string;
+    } | "rethrow";
+    /** Read one declared entity. A throw here is caught and recorded `read-failed`. */
+    read(client: Client, entity: DeclaredEntity): Promise<EntityObservation>;
+    /**
+     * Run `fn` over `items` concurrently. Supply the transport's own bounded pool
+     * (the k8s client's `concurrently`, say); when omitted the harness uses
+     * {@link boundedConcurrently}, so "N entities is not N serial spawns" holds
+     * for every lexicon whether or not its transport ships a pool.
+     */
+    concurrently?<T>(items: readonly T[], fn: (item: T) => Promise<void>): Promise<void>;
+}
+/** Default concurrency for {@link boundedConcurrently} when a transport ships no pool. */
+export declare const DEFAULT_OBSERVE_CONCURRENCY = 16;
+/**
+ * Run `fn` over `items` with at most `limit` in flight. A rejected `fn` rejects
+ * the whole run (the harness wraps per-entity reads so this stays for genuinely
+ * unexpected faults).
+ */
+export declare function boundedConcurrently<T>(items: readonly T[], fn: (item: T) => Promise<void>, limit?: number): Promise<void>;
+/**
+ * The shared observer control flow (#1201). Binds via the adapter, reads every
+ * declared entity concurrently, and assembles the tri-state {@link ObservationResult}.
+ *
+ * A `bind()` throw becomes NOT-OBSERVED for every entity (typed by
+ * {@link ObserverAdapter.classifyBindFailure}) unless the adapter asks to
+ * rethrow. A per-entity `read()` throw the adapter did not itself map becomes
+ * `read-failed` for that one entity — never a silent absence, which would
+ * classify as a spurious `create`.
+ */
+export declare function observeEntities<Client>(declared: readonly DeclaredEntity[], adapter: ObserverAdapter<Client>): Promise<ObservationResult>;
 //# sourceMappingURL=observation.d.ts.map

package/dist/observation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../src/observation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,gBAAgB,GAChB,YAAY,GACZ,kBAAkB,GAClB,UAAU,CAAC;AAEf,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EAMzD,CAAC;AAEF,6DAA6D;AAC7D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,kGAAkG;IAClG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,MAAM,EAAE,gBAAgB,CAAC;IACzB,qGAAqG;IACrG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,2GAA2G;IAC3G,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC5C,+GAA+G;IAC/G,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,iBAAiB,CAAC;AAE3F,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC9C;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAM9E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC3C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAC5C,iBAAiB,CAMnB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,uBAAuB,GAAG,SAAS,GAAG,qBAAqB,CAMtG;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,EACvB,MAAM,EAAE,gBAAgB,EACxB,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAYlC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,CAW/F;AAED,2DAA2D;AAC3D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAarE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAG9E"}
+{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../src/observation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

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

@@ -1,7 +1,7 @@
 import { describe, test, expect, vi } from "vitest";
 import { __searchInternals } from "./search";
 
-const { parseQuery, matchTerm, formatRow, explain, describeTerm } = __searchInternals;
+const { parseQuery, matchTerm, formatRow, explain, describeTerm, derivedSurface, availableAttrs } = __searchInternals;
 
 function node(id: string, kind: string, attrs: Record<string, unknown> = {}) {
   return { id, kind, lexicon: "aws", attrs } as never;
@@ -111,3 +111,49 @@ describe("search edge traversal", () => {
       .toBe("→attr:MapPublicIpOnLaunch=true (no such edge)");
   });
 });
+
+describe("search surfaces what the graph derived", () => {
+  const insts = [
+    node("webServer", "AWS::EC2::Instance", { internetFacing: true, internetFacingVia: "rtb-1 → igw-1", effectiveIngress: ["tcp:22:0.0.0.0/0"] }),
+    node("privServer", "AWS::EC2::Instance", { internetFacing: false, effectiveIngress: [] }),
+  ];
+  const derivedIr = { nodes: insts, edges: [], groups: {}, derivedAttrs: { Instance: ["internetFacing", "effectiveIngress"] } } as never;
+
+  function capture(fn: () => void): string {
+    const lines: string[] = [];
+    const spy = vi.spyOn(console, "log").mockImplementation((s: string) => { lines.push(s); });
+    fn();
+    spy.mockRestore();
+    return lines.join("\n");
+  }
+
+  test("names derived facts the query did not use, and omits the ones it did", () => {
+    const out = capture(() => derivedSurface(parseQuery("kind:EC2::Instance attr:internetFacing=true") as never, insts as never, derivedIr));
+    expect(out).toContain("effectiveIngress");
+    expect(out).not.toContain("internetFacing");
+  });
+
+  test("says nothing when the query already used every derived fact", () => {
+    const q = "kind:EC2::Instance attr:internetFacing=true attr:effectiveIngress=tcp:22:0.0.0.0/0";
+    expect(capture(() => derivedSurface(parseQuery(q) as never, insts as never, derivedIr))).toBe("");
+  });
+
+  test("says nothing for a graph with no derived facts recorded", () => {
+    const plain = { nodes: insts, edges: [], groups: {} } as never;
+    expect(capture(() => derivedSurface(parseQuery("kind:EC2::Instance") as never, insts as never, plain))).toBe("");
+  });
+
+  test("a miss lists the attributes the queried kind actually carries", () => {
+    const out = capture(() => availableAttrs(parseQuery("kind:EC2::Instance attr:nosuchattr=1") as never, derivedIr));
+    expect(out).toContain("effectiveIngress");
+    expect(out).toContain("internetFacing");
+    expect(out).not.toContain("nosuchattr");
+  });
+
+  test("inclusion evidence is keyed off <attr>Via provenance, not a fixed attribute name", () => {
+    const byId = new Map(insts.map((n: { id: string }) => [n.id, n]));
+    const q = "attr:internetFacing=true";
+    const out = capture(() => explain(parseQuery(q) as never, [insts[0]] as never, derivedIr, byId as never, q));
+    expect(out).toContain("webServer internetFacing via rtb-1 → igw-1");
+  });
+});

package/src/cli/handlers/search.ts

@@ -114,16 +114,45 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
   const matches = ir.nodes.filter((n) => terms.every((t) => matchTerm(n, t, ir, nodeById)));
   if (matches.length === 0) {
     console.log("(no matches)");
+    availableAttrs(terms, ir);
     if (args.explain) explain(terms, matches, ir, nodeById, query);
     return 0;
   }
   for (const n of matches) {
     console.log(formatRow(n, show));
   }
+  derivedSurface(terms, matches, ir);
   if (args.explain) explain(terms, matches, ir, nodeById, query);
   return 0;
 }
 
+/**
+ * Name the facts chant computed for the kinds in this result that the query did not use.
+ *
+ * A provider API can only return what it stores; chant additionally folds multi-hop topology
+ * onto a node, and a caller has no way to know that surface exists. Reporting it turns a
+ * one-shot query into a conversation with the graph — ask something, learn what else is
+ * knowable about the same resources, refine.
+ *
+ * The names come from {@link GraphIR.derivedAttrs}, recorded by whichever enrichment pass
+ * produced them. Nothing here knows what any attribute means or which question it answers;
+ * add a pass and its facts appear, remove one and they stop.
+ */
+function derivedSurface(terms: Term[], matches: IRNode[], ir: GraphIR): void {
+  const derived = ir.derivedAttrs;
+  if (!derived || matches.length === 0) return;
+  const used = new Set(terms.filter((t) => t.kind === "attr").map((t) => t.a));
+  const unused = new Set<string>();
+  for (const n of matches) {
+    for (const [kind, names] of Object.entries(derived)) {
+      if (!n.kind?.includes(kind)) continue;
+      for (const name of names) if (!used.has(name)) unused.add(name);
+    }
+  }
+  if (unused.size === 0) return;
+  console.log(`— also derived for these resources: ${[...unused].sort().join(", ")}`);
+}
+
 /**
  * `--explain` footer (#1139): a compact, model-DERIVED summary that gives a
  * small model a reason to trust the result instead of re-deriving it with a
@@ -143,11 +172,12 @@ function explain(terms: Term[], matches: IRNode[], ir: GraphIR, byId: Map<string
   // Inclusion evidence: for a derived fact a CLI can't easily re-verify
   // (internetFacing, resolved across the default VPC's routing), name WHY each
   // match qualifies, so the agent trusts the result instead of dropping it.
-  if (terms.some((t) => t.kind === "attr" && t.a === "internetFacing")) {
+  for (const t of terms) {
+    if (t.kind !== "attr") continue;
     for (const n of matches) {
-      const via = (n.attrs as Record<string, unknown> | undefined)?.["internetFacingVia"];
+      const via = (n.attrs as Record<string, unknown> | undefined)?.[`${t.a}Via`];
       const id = n.id.includes("::") ? n.id.slice(n.id.lastIndexOf("::") + 2) : n.id;
-      if (typeof via === "string") console.log(`  ✓ ${id} internet-facing via ${via}`);
+      if (typeof via === "string") console.log(`  ✓ ${id} ${t.a} via ${via}`);
     }
   }
   const shown = excluded.slice(0, 8);
@@ -159,6 +189,27 @@ function explain(terms: Term[], matches: IRNode[], ir: GraphIR, byId: Map<string
   if (excluded.length > shown.length) console.log(`  · …and ${excluded.length - shown.length} more excluded`);
 }
 
+/**
+ * On a miss, name the attributes the queried kind actually carries. A graph knows
+ * its own schema, so a caller who guessed an attribute name — or did not know a
+ * derived one existed — can see what is queryable instead of falling back to a
+ * lossy CLI sweep. Read off the nodes present, so it stays a property of the
+ * graph rather than of any expected answer: whatever the estate holds is what
+ * this lists, and it says nothing about which attribute answers a question.
+ */
+function availableAttrs(terms: Term[], ir: GraphIR): void {
+  const kindTerm = terms.find((t) => t.kind === "kind");
+  if (!kindTerm) return;
+  const of = ir.nodes.filter((n) => n.kind?.includes(kindTerm.a));
+  if (of.length === 0) return;
+  const names = new Set<string>();
+  for (const n of of) for (const k of Object.keys((n.attrs as Record<string, unknown>) ?? {})) names.add(k);
+  const queried = new Set(terms.filter((t) => t.kind === "attr").map((t) => t.a));
+  const unused = [...names].filter((k) => !queried.has(k)).sort();
+  if (unused.length === 0) return;
+  console.log(`  · ${of.length} ${kindTerm.a} node(s) carry: ${unused.join(", ")}`);
+}
+
 function describeTerm(t: Term): string {
   const leaf = (x: Term): string =>
     x.kind === "kind" ? `kind:${x.a}` : x.kind === "attr" ? `attr:${x.a}${x.b !== undefined ? "=" + x.b : ""}`
@@ -260,4 +311,4 @@ function formatRow(n: IRNode, show: string[]): string {
 }
 
 /** Internals exposed for unit tests. */
-export const __searchInternals = { parseQuery, matchTerm, formatRow, explain, describeTerm };
+export const __searchInternals = { parseQuery, matchTerm, formatRow, explain, describeTerm, derivedSurface, availableAttrs };

package/src/codegen/release-wiring.test.ts

@@ -0,0 +1,82 @@
+/**
+ * The release path is two hand-maintained halves that must agree: the
+ * justfile recipes that create and push a tag, and publish.yml's tag
+ * trigger that decides whether pushing it does anything.
+ *
+ * They disagreed. `just release-lexicon <name>` has always tagged
+ * `lexicon-<name>-v<version>`, pushed it, and echoed "publish workflow
+ * triggered" — while publish.yml matched only `chant-v*`. The tag landed,
+ * no workflow ran, and the recipe reported success. fly's 0.33.0 shipped
+ * with zero rules and zero skills and could not be patched by the one
+ * recipe built for patching a single lexicon.
+ *
+ * A release that silently no-ops is worse than one that fails, so this
+ * turns the next divergence into a PR-time failure.
+ */
+
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+
+function publishTagPatterns(): string[] {
+  const workflow = readFileSync(join(repoRoot, ".github", "workflows", "publish.yml"), "utf-8");
+  const match = workflow.match(/^\s*tags:\s*\[([^\]]+)\]/m);
+  if (!match) throw new Error("publish.yml: `tags: [...]` trigger not found");
+  return match[1].split(",").map((s) => s.trim().replace(/^['"]|['"]$/g, ""));
+}
+
+/** Tags the justfile actually creates, as literal-prefix + wildcard shapes. */
+function releaseTagShapes(): Array<{ recipe: string; example: string }> {
+  const justfile = readFileSync(join(repoRoot, "justfile"), "utf-8");
+  const shapes: Array<{ recipe: string; example: string }> = [];
+
+  // `git tag "chant-v$next"` / `git tag "lexicon-{{name}}-v$next"`
+  for (const m of justfile.matchAll(/git tag "([^"]+)"/g)) {
+    const raw = m[1];
+    const example = raw
+      .replace(/\{\{name\}\}/g, "docker")
+      .replace(/\$\{?next\}?/g, "9.9.9");
+    shapes.push({ recipe: raw, example });
+  }
+  return shapes;
+}
+
+/** Minimal glob match for the `prefix*` shapes these patterns use. */
+function matchesGlob(pattern: string, value: string): boolean {
+  const rx = new RegExp(
+    "^" + pattern.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$",
+  );
+  return rx.test(value);
+}
+
+describe("release wiring: justfile tags vs publish.yml trigger", () => {
+  it("finds both halves", () => {
+    expect(publishTagPatterns().length).toBeGreaterThan(0);
+    expect(releaseTagShapes().length).toBeGreaterThan(0);
+  });
+
+  it("every tag a release recipe pushes triggers the publish workflow", () => {
+    const patterns = publishTagPatterns();
+
+    for (const { recipe, example } of releaseTagShapes()) {
+      const hit = patterns.some((p) => matchesGlob(p, example));
+      expect(
+        hit,
+        `justfile creates tag "${recipe}" (e.g. ${example}) but publish.yml triggers on ` +
+          `[${patterns.join(", ")}] — pushing it would publish nothing while the recipe ` +
+          `reports success`,
+      ).toBe(true);
+    }
+  });
+
+  it("covers the two shapes the repo releases by", () => {
+    const examples = releaseTagShapes().map((s) => s.example);
+    // Whole-repo release and single-lexicon patch. If a recipe stops
+    // producing one of these, the assertion above would pass vacuously.
+    expect(examples).toContain("chant-v9.9.9");
+    expect(examples).toContain("lexicon-docker-v9.9.9");
+  });
+});

package/src/graph-effective.ts

@@ -106,5 +106,11 @@ export function enrichEffectiveTopology(ir: GraphIR): GraphIR {
       attrs: { ...attrs, effectiveIngress, internetFacing: liveFacing || !!declaredVia, ...(via ? { internetFacingVia: via } : {}) },
     };
   });
-  return { ...ir, nodes };
+  // Record what this pass computed, so a caller can report the graph's derived surface
+  // without hardcoding attribute names. Only kinds actually enriched are listed.
+  const enriched = nodes.some((n) => isKind(n, "Instance"));
+  const derivedAttrs = enriched
+    ? { ...(ir.derivedAttrs ?? {}), Instance: ["internetFacing", "effectiveIngress"] }
+    : ir.derivedAttrs;
+  return { ...ir, nodes, ...(derivedAttrs ? { derivedAttrs } : {}) };
 }

package/src/graph-ir.ts

@@ -191,6 +191,13 @@ export interface GraphIR {
   imports?: IRImport[];
   /** The CI/pipeline projection alongside the component graph (#989) — see {@link IRPipeline}. */
   pipeline?: IRPipeline;
+  /**
+   * Attributes chant computed rather than read back from the provider, keyed by the kind
+   * they were folded onto. An enrichment pass records what it derived here so callers can
+   * report the graph's own surface without knowing any attribute name — the set is whatever
+   * the passes produced, not a list maintained by hand.
+   */
+  derivedAttrs?: Record<string, string[]>;
 }
 
 /** A node is anything that serializes to a resource — not a property or output. */

package/src/observation.test.ts

@@ -5,14 +5,19 @@
 import { describe, test, expect } from "vitest";
 import {
   UNOBSERVED_REASONS,
+  boundedConcurrently,
   formatUnobserved,
   isObservationResult,
   isUnobservedReason,
   mergeObservations,
   normalizeObservation,
   observation,
+  observeEntities,
   unobservedAll,
   unobservedReasonText,
+  type DeclaredEntity,
+  type EntityObservation,
+  type ObserverAdapter,
 } from "./observation";
 import type { ResourceMetadata } from "./lexicon";
 
@@ -94,3 +99,133 @@ describe("reason totality", () => {
     ).toBe("widget (K8s::X::Widget) — no reader for this resource kind: no mapping");
   });
 });
+
+describe("boundedConcurrently", () => {
+  test("processes every item", async () => {
+    const seen: number[] = [];
+    await boundedConcurrently([1, 2, 3, 4, 5], async (n) => {
+      seen.push(n);
+    }, 2);
+    expect([...seen].sort((a, b) => a - b)).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  test("never exceeds the limit in flight", async () => {
+    let inFlight = 0;
+    let peak = 0;
+    await boundedConcurrently(Array.from({ length: 20 }, (_, i) => i), async () => {
+      inFlight += 1;
+      peak = Math.max(peak, inFlight);
+      await new Promise((r) => setTimeout(r, 1));
+      inFlight -= 1;
+    }, 4);
+    expect(peak).toBeLessThanOrEqual(4);
+    expect(peak).toBeGreaterThan(1); // it did run concurrently, not serially
+  });
+
+  test("an empty list is a no-op", async () => {
+    await expect(boundedConcurrently([], async () => {})).resolves.toBeUndefined();
+  });
+});
+
+describe("observeEntities harness (#1201)", () => {
+  const entity = (name: string, type = "Fake::Resource"): DeclaredEntity => ({ name, type, props: {} });
+
+  /** A fake adapter whose `read` is table-driven by entity name. */
+  const adapterOf = (
+    reads: Record<string, EntityObservation | (() => Promise<EntityObservation>)>,
+    over: Partial<ObserverAdapter<{ ok: true }>> = {},
+  ): ObserverAdapter<{ ok: true }> => ({
+    bind: async () => ({ ok: true }),
+    classifyBindFailure: () => ({ reason: "read-failed" }),
+    read: async (_client, e) => {
+      const r = reads[e.name];
+      if (typeof r === "function") return r();
+      if (!r) throw new Error(`no fake read for ${e.name}`);
+      return r;
+    },
+    ...over,
+  });
+
+  test("routes the tri-state: present -> resources, absent -> neither, unobserved -> unobserved", async () => {
+    const result = await observeEntities(
+      [entity("a"), entity("b"), entity("c", "Fake::Odd")],
+      adapterOf({
+        a: { present: meta({ physicalId: "id-a" }) },
+        b: { absent: true },
+        c: { unobserved: { reason: "unsupported-kind", detail: "no reader" } },
+      }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["a"]);
+    expect(result.resources.a.physicalId).toBe("id-a");
+    // absent 'b' is in neither map
+    expect(result.unobserved).toEqual({
+      c: { type: "Fake::Odd", reason: "unsupported-kind", detail: "no reader" },
+    });
+  });
+
+  test("a bind failure marks every entity NOT-OBSERVED with the typed reason and declared type", async () => {
+    const result = await observeEntities(
+      [entity("a", "AWS::S3::Bucket"), entity("b", "AWS::S3::Bucket")],
+      adapterOf(
+        {},
+        {
+          bind: async () => {
+            throw new Error("no creds");
+          },
+          classifyBindFailure: () => ({ reason: "no-credentials", detail: "token expired" }),
+        },
+      ),
+    );
+    expect(result.resources).toEqual({});
+    expect(result.unobserved).toEqual({
+      a: { reason: "no-credentials", type: "AWS::S3::Bucket", detail: "token expired" },
+      b: { reason: "no-credentials", type: "AWS::S3::Bucket", detail: "token expired" },
+    });
+  });
+
+  test("a loud refusal rethrows instead of degrading to a hole", async () => {
+    await expect(
+      observeEntities(
+        [entity("a")],
+        adapterOf(
+          {},
+          {
+            bind: async () => {
+              throw new Error("context mismatch");
+            },
+            classifyBindFailure: () => "rethrow",
+          },
+        ),
+      ),
+    ).rejects.toThrow("context mismatch");
+  });
+
+  test("a per-entity read throw degrades to read-failed for that one entity, not an absence", async () => {
+    const result = await observeEntities(
+      [entity("a"), entity("b")],
+      adapterOf({
+        a: () => Promise.reject(new Error("boom")),
+        b: { present: meta() },
+      }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["b"]);
+    expect(result.unobserved?.a).toEqual({ type: "Fake::Resource", reason: "read-failed", detail: "boom" });
+  });
+
+  test("uses the adapter's own concurrency pool when it supplies one", async () => {
+    let usedPool = false;
+    await observeEntities(
+      [entity("a")],
+      adapterOf(
+        { a: { present: meta() } },
+        {
+          concurrently: async (items, fn) => {
+            usedPool = true;
+            for (const it of items) await fn(it);
+          },
+        },
+      ),
+    );
+    expect(usedPool).toBe(true);
+  });
+});

package/src/observation.ts

@@ -211,3 +211,154 @@ export function formatUnobserved(name: string, entry: UnobservedEntity): string
   const base = `${name}${entry.type ? ` (${entry.type})` : ""} — ${unobservedReasonText(entry.reason)}`;
   return entry.detail ? `${base}: ${entry.detail}` : base;
 }
+
+/* ------------------------------------------------------------------------- *
+ * The observer harness (#1201).
+ *
+ * Every native observer runs the same control flow: bind to the provider on
+ * the applier's own transport, read the declared entities concurrently, and
+ * turn each read into one of the tri-state outcomes above. The k8s observer
+ * (#1074) and Fly (#767) already embody it. Rather than have aws/gcp/azure each
+ * re-derive it — and re-derive it inconsistently, which is how the shell-out
+ * observers drifted apart — a lexicon supplies an {@link ObserverAdapter} and
+ * the harness owns the shape: bind-or-not-observe-all with a typed reason,
+ * bounded concurrency, per-entity tri-state routing, and a per-entity throw
+ * degrading to `read-failed` rather than a silent absence.
+ *
+ * The adapter owns transport and endpoint resolution (an emulator override is
+ * resolved inside `bind()` via the shared live-endpoint helper), so the
+ * emulator override behaves identically across lexicons by construction — the
+ * harness never touches an endpoint itself.
+ * ------------------------------------------------------------------------- */
+
+/** One declared entity handed to the harness. */
+export interface DeclaredEntity {
+  /** chant entity name — the key every outcome is filed under. */
+  name: string;
+  /** Declared entity type (e.g. `AWS::EC2::VPC`). */
+  type: string;
+  /** Declared properties, for the adapter to derive a physical address from. */
+  props: Record<string, unknown>;
+}
+
+/**
+ * The outcome of reading one entity, mapped onto the tri-state:
+ * - `present` — a key in `resources`.
+ * - `absent` — in neither map (the provider was asked and reported it missing).
+ * - `unobserved` — a typed NOT-OBSERVED (unsupported kind, filtered, read error).
+ */
+export type EntityObservation =
+  | { present: ResourceMetadata }
+  | { absent: true }
+  | { unobserved: { reason: UnobservedReason; detail?: string } };
+
+/** What a lexicon supplies to drive the harness. `Client` is its transport handle. */
+export interface ObserverAdapter<Client> {
+  /**
+   * Reach the provider on the applier's transport. Throw for a whole-lexicon
+   * failure; {@link classifyBindFailure} decides what the throw means.
+   */
+  bind(): Promise<Client>;
+  /**
+   * Map a `bind()` throw to a typed whole-lexicon reason (every entity becomes
+   * NOT-OBSERVED with it), or `"rethrow"` for a loud refusal that must not be
+   * swallowed — a context/subscription mismatch, which core turns into an
+   * honest hole per entity at a higher layer.
+   */
+  classifyBindFailure(err: unknown): { reason: UnobservedReason; detail?: string } | "rethrow";
+  /** Read one declared entity. A throw here is caught and recorded `read-failed`. */
+  read(client: Client, entity: DeclaredEntity): Promise<EntityObservation>;
+  /**
+   * Run `fn` over `items` concurrently. Supply the transport's own bounded pool
+   * (the k8s client's `concurrently`, say); when omitted the harness uses
+   * {@link boundedConcurrently}, so "N entities is not N serial spawns" holds
+   * for every lexicon whether or not its transport ships a pool.
+   */
+  concurrently?<T>(items: readonly T[], fn: (item: T) => Promise<void>): Promise<void>;
+}
+
+/** Default concurrency for {@link boundedConcurrently} when a transport ships no pool. */
+export const DEFAULT_OBSERVE_CONCURRENCY = 16;
+
+/**
+ * Run `fn` over `items` with at most `limit` in flight. A rejected `fn` rejects
+ * the whole run (the harness wraps per-entity reads so this stays for genuinely
+ * unexpected faults).
+ */
+export async function boundedConcurrently<T>(
+  items: readonly T[],
+  fn: (item: T) => Promise<void>,
+  limit: number = DEFAULT_OBSERVE_CONCURRENCY,
+): Promise<void> {
+  const queue = [...items];
+  const size = Math.max(1, Math.min(limit, queue.length || 1));
+  const workers = Array.from({ length: size }, async () => {
+    for (;;) {
+      const next = queue.shift();
+      if (next === undefined) return;
+      await fn(next);
+    }
+  });
+  await Promise.all(workers);
+}
+
+/**
+ * The shared observer control flow (#1201). Binds via the adapter, reads every
+ * declared entity concurrently, and assembles the tri-state {@link ObservationResult}.
+ *
+ * A `bind()` throw becomes NOT-OBSERVED for every entity (typed by
+ * {@link ObserverAdapter.classifyBindFailure}) unless the adapter asks to
+ * rethrow. A per-entity `read()` throw the adapter did not itself map becomes
+ * `read-failed` for that one entity — never a silent absence, which would
+ * classify as a spurious `create`.
+ */
+export async function observeEntities<Client>(
+  declared: readonly DeclaredEntity[],
+  adapter: ObserverAdapter<Client>,
+): Promise<ObservationResult> {
+  const typesByName: Record<string, string> = {};
+  for (const d of declared) typesByName[d.name] = d.type;
+
+  let client: Client;
+  try {
+    client = await adapter.bind();
+  } catch (err) {
+    const verdict = adapter.classifyBindFailure(err);
+    if (verdict === "rethrow") throw err;
+    return observation(
+      {},
+      unobservedAll(
+        declared.map((d) => d.name),
+        verdict.reason,
+        verdict.detail,
+        typesByName,
+      ),
+    );
+  }
+
+  const resources: Record<string, ResourceMetadata> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+  const run = adapter.concurrently ?? ((items, fn) => boundedConcurrently(items, fn));
+
+  await run(declared, async (entity) => {
+    let result: EntityObservation;
+    try {
+      result = await adapter.read(client, entity);
+    } catch (err) {
+      result = {
+        unobserved: {
+          reason: "read-failed",
+          detail: err instanceof Error ? err.message : String(err),
+        },
+      };
+    }
+    if ("present" in result) {
+      resources[entity.name] = result.present;
+    } else if ("unobserved" in result) {
+      unobserved[entity.name] = { type: entity.type, ...result.unobserved };
+    }
+    // `absent`: record nothing — in neither map is how the contract spells absence.
+  });
+
+  return observation(resources, unobserved);
+}