@intentius/chant 0.124.22 → 0.124.24

package/src/components/cli-support.ts

@@ -228,6 +228,28 @@ export async function computeComponentGraph(
 /** A generate-mode target lexicon name — any lexicon whose plugin implements `generateComponentPipeline` (gitlab, github, and forgejo today). */
 export type GenerateLexicon = string;
 
+/**
+ * The components an "all" run takes, in `discovered` order (chant #1522). A
+ * seam-gated component (`enabled: false`, computed from this run's own
+ * params) sits out: the run deploys the estate the parameters describe, not
+ * the units the seams turned off. A disabled dependency is satisfied
+ * vacuously, since ordering is dependsOn's only meaning, so it is also
+ * stripped from the survivors' dependsOn rather than failing wave resolution
+ * as an unknown name. `chant run --components all`, a component list's
+ * dependency closure (#3950) and the generated pipelines (#3951) all select
+ * through this.
+ */
+export function withoutDisabled<T extends { name: string; dependsOn?: string[] }>(
+  discovered: ReadonlyArray<{ name: string; enabled?: boolean }>,
+  components: T[],
+): T[] {
+  const disabled = new Set(discovered.filter((c) => c.enabled === false).map((c) => c.name));
+  if (disabled.size === 0) return components;
+  return components
+    .filter((c) => !disabled.has(c.name))
+    .map((c) => (c.dependsOn?.some((d) => disabled.has(d)) ? { ...c, dependsOn: c.dependsOn.filter((d) => !disabled.has(d)) } : c));
+}
+
 /** Result of `chant build --components --generate <lexicon>`. */
 export interface GenerateComponentsResult {
   success: boolean;
@@ -301,11 +323,13 @@ export async function generateComponentsPipeline(
     return { success: false, error: result.errors.map((e) => e.message).join("\n") };
   }
 
-  const driverComponents: DriverComponent[] = [...result.components.values()].map(({ component }) => ({
-    name: component.name,
-    dependsOn: component.dependsOn,
-    deploy: component.deploy,
-  }));
+  // #3951: the pipeline holds the jobs `chant run --components all` would
+  // run, so a disabled component has no job and no other job needs it.
+  const discovered = [...result.components.values()].map(({ component }) => component);
+  const driverComponents = withoutDisabled(
+    discovered,
+    discovered.map((component) => ({ name: component.name, dependsOn: component.dependsOn, deploy: component.deploy })),
+  );
 
   try {
     const { yaml, stages, jobs, env } = plugin.generateComponentPipeline(driverComponents, options);
@@ -404,7 +428,7 @@ export interface RunComponentsOptions {
   /**
    * Opt-in structured progress observer (`chant run --components <name|all>
    * --progress-json`, see ./run-progress.ts). Threaded straight through to
-   * `runInterpretDriver` for `selector === "all"`; for a single-component
+   * `runInterpretDriver` for `"all"` and a list; for a single-component
    * selector (which bypasses `runInterpretDriver` — see the docstring above),
    * this function emits the same `run-start`/`wave-start`/`component-start`/
    * …/`run-done` envelope itself, treating the one component as a run with a
@@ -430,6 +454,12 @@ export interface RunComponentsOptions {
   buildParams?: BuildParamProvenance[];
   /** Where a `gate` step's facts are read and written (#2119). Defaults to the `chant/lifecycle` orphan branch; a test passes `memoryGateLedgerPort()` from `../op/gate.ts`. */
   gates?: GateLedgerPort;
+  /**
+   * Called once for a list selector (`a,b,c`, #3950) with the resolved run
+   * order, waves and the dependencies the list pulled in, after selection and
+   * before the first component runs. The CLI prints it.
+   */
+  onPlan?: (plan: ComponentRunPlan) => void;
   /**
    * The commit the run deploys, for the workloads' `vcs.ref.head.revision`
    * (#3061). Default: `git rev-parse HEAD` in the project, or nothing outside
@@ -438,7 +468,15 @@ export interface RunComponentsOptions {
   revision?: string | null;
 }
 
-/** Result of `chant run --components <name|all>`. */
+/** The resolved order of a list run (#3950), reported through `RunComponentsOptions.onPlan`. */
+export interface ComponentRunPlan {
+  order: string[];
+  waves: string[][];
+  /** Dependencies the list did not name but the run includes. */
+  added: string[];
+}
+
+/** Result of `chant run --components <name|all|a,b,c>`. */
 export interface RunComponentsResult {
   success: boolean;
   /** The driver's run result, when the run reached the driver (even on a failed component). */
@@ -468,6 +506,10 @@ export interface RunComponentsResult {
  *  - `selector === "all"`: resolves the whole set's dependency order/waves
  *    and dispatches every component through `runInterpretDriver`, in the same
  *    order `chant graph --components` reports.
+ *  - a list (`a,b,c`, #3950): the named components plus everything they
+ *    depend on, through the same `runInterpretDriver` path as `"all"`, so the
+ *    subset runs in the order `"all"` would give it, in one process. The
+ *    resolved order goes to `onPlan` before the first component starts.
  *  - a single name: dispatches just that component via `runComponentDeploy`,
  *    without requiring the rest of its `dependsOn` graph to be present in
  *    this invocation. This mirrors generate mode's per-job invocation model
@@ -483,17 +525,24 @@ export interface RunComponentsResult {
  * stops the run there with `gated` set, which the CLI turns into exit code 3
  * and the `chant approve` line.
  */
-/** Result of resolving a `<name|all>` selector against discovered components. */
+/** Result of resolving a `<name|all|a,b,c>` selector against discovered components. */
 export interface ResolvedComponentTargets {
   success: boolean;
   targets: DriverComponent[];
+  /** For a list selector (#3950): the dependencies the closure added that the list did not name, in discovery order. */
+  added?: string[];
   error?: string;
 }
 
+/** Whether `selector` is a comma-separated component list (#3950), as opposed to `all` or one name. */
+export function isComponentList(selector: string): boolean {
+  return selector.includes(",");
+}
+
 /**
- * Discover every component under `path` and resolve `selector` (`"all"` or a
- * single component name) to the `DriverComponent`(s) to run, with no gate
- * check and no dispatch — just discovery + selection, factored out of
+ * Discover every component under `path` and resolve `selector` (`"all"`, a
+ * single component name, or a comma-separated list, #3950) to the
+ * `DriverComponent`(s) to run, with no gate check and no dispatch — just discovery + selection, factored out of
  * `runComponents` so another entrypoint can reuse the exact same selection
  * semantics without inheriting the run itself.
  */
@@ -512,19 +561,9 @@ export async function resolveComponentTargets(
   const discovered = [...result.components.values()].map(({ component }) => component);
   const all = discovered.map((component) => toDriverComponent(component));
 
-  if (selector === "all") {
-    // chant #1522 — a seam-gated component (`enabled: false`, computed from
-    // this run's own params) sits out of "all": the run deploys the estate
-    // the parameters describe, not the units the seams turned off. A disabled
-    // dependency is satisfied vacuously — ordering is dependsOn's only
-    // semantics — so it is also stripped from the survivors' dependsOn,
-    // rather than failing wave resolution as an unknown name.
-    const disabled = new Set(discovered.filter((c) => c.enabled === false).map((c) => c.name));
-    const targets = all
-      .filter((c) => !disabled.has(c.name))
-      .map((c) => (c.dependsOn?.some((d) => disabled.has(d)) ? { ...c, dependsOn: c.dependsOn.filter((d) => !disabled.has(d)) } : c));
-    return { success: true, targets };
-  }
+  if (isComponentList(selector)) return resolveComponentList(selector, discovered, all);
+
+  if (selector === "all") return { success: true, targets: withoutDisabled(discovered, all) };
 
   const found = all.find((c) => c.name === selector);
   const disabledByName = discovered.find((c) => c.name === selector && c.enabled === false);
@@ -548,6 +587,65 @@ export async function resolveComponentTargets(
   return { success: true, targets: [found] };
 }
 
+/**
+ * A list selector (`a,b,c`, #3950): the named components plus every component
+ * they depend on, transitively, so the list runs as one dependency-ordered
+ * set. Refused before anything runs when a name is unknown, disabled, or `all`
+ * (which already means every component). Dependencies are followed through
+ * `withoutDisabled`, the selection `"all"` uses, so a disabled *dependency*
+ * is dropped and stripped from dependsOn exactly as `"all"` drops it. A
+ * dependsOn name that matches no discovered component is left in place, so
+ * wave resolution reports it as `"all"` would.
+ */
+function resolveComponentList(
+  selector: string,
+  discovered: ReadonlyArray<{ name: string; enabled?: boolean }>,
+  all: DriverComponent[],
+): ResolvedComponentTargets {
+  const names = [...new Set(selector.split(",").map((n) => n.trim()).filter((n) => n.length > 0))];
+  if (names.length === 0) {
+    return { success: false, targets: [], error: `Component list "${selector}" names no components.` };
+  }
+  if (names.includes("all")) {
+    return { success: false, targets: [], error: `"all" cannot be part of a component list; pass --components all on its own, or name the components.` };
+  }
+  // An explicit ask for a unit the parameters excluded is a mistake to
+  // surface, not to skip silently, as it is for a single name.
+  const off = names.filter((n) => discovered.some((c) => c.name === n && c.enabled === false));
+  if (off.length > 0) {
+    const one = off.length === 1;
+    return {
+      success: false,
+      targets: [],
+      error: `${one ? "Component" : "Components"} ${off.map((n) => `"${n}"`).join(", ")} ${one ? "is" : "are"} disabled under this run's parameters (enabled: false). Enable the seam ${one ? "it is" : "they are"} gated on, or leave ${one ? "it" : "them"} out of the list.`,
+    };
+  }
+  const unknown = names.filter((n) => !all.some((c) => c.name === n));
+  if (unknown.length > 0) {
+    const known = all.map((c) => c.name).sort().join(", ");
+    return {
+      success: false,
+      targets: [],
+      error: `${unknown.length === 1 ? "Component" : "Components"} ${unknown.map((n) => `"${n}"`).join(", ")} not found.${known ? ` Known components: ${known}` : " No components discovered."}`,
+    };
+  }
+
+  const enabled = withoutDisabled(discovered, all);
+  const byName = new Map(enabled.map((c) => [c.name, c]));
+  const included = new Set<string>();
+  const visit = (name: string): void => {
+    const component = byName.get(name);
+    if (!component || included.has(name)) return;
+    included.add(name);
+    for (const dep of component.dependsOn ?? []) visit(dep);
+  };
+  for (const name of names) visit(name);
+
+  const targets = enabled.filter((c) => included.has(c.name));
+  const named = new Set(names);
+  return { success: true, targets, added: targets.map((c) => c.name).filter((n) => !named.has(n)) };
+}
+
 export async function runComponents(
   path: string,
   selector: string,
@@ -595,7 +693,14 @@ export async function runComponents(
   const releaseIdentity = () => (revision ? { revision } : {});
 
   try {
-    if (selector === "all") {
+    if (selector === "all" || isComponentList(selector)) {
+      if (isComponentList(selector) && options.onPlan) {
+        // Resolved here, before dispatch, so the order is printed before any
+        // component runs. A cycle or unknown dependency throws the same error
+        // `runInterpretDriver` would, caught below.
+        const graph = resolveComponentGraph(resolvedTargets);
+        options.onPlan({ order: graph.order, waves: graph.waves, added: resolved.added ?? [] });
+      }
       const run = await runInterpretDriver(resolvedTargets, registry, {
         env,
         releaseIdentity,

package/src/components/driver.test.ts

@@ -239,6 +239,34 @@ describe("runComponentDeploy — gate as fact (#2119)", () => {
     return { registry, calls, rolledBack };
   }
 
+  // #3955: a run that records nothing cannot spend an approval or leave a
+  // pending fact, so the gate fails even with an approval standing for it.
+  it("fails at the gate under CHANT_NO_RECORD, writing nothing and running nothing after it", async () => {
+    const { registry, calls } = registryWithCalls();
+    const port = memoryGateLedgerPort({
+      resolutions: [{ op: "neo4j-cluster", gate: "approve-node-1", resolvedBy: "alice", timestamp: NOW, environment: "dev" } as never],
+    });
+    process.env.CHANT_NO_RECORD = "1";
+    let result;
+    try {
+      result = await runComponentDeploy(
+        gatedComponent(), { env: "dev", component: "neo4j-cluster" }, registry, {}, undefined,
+        { port, now: NOW },
+      );
+    } finally {
+      delete process.env.CHANT_NO_RECORD;
+    }
+
+    expect(result.status).toBe("fail");
+    expect(port.appended).toHaveLength(0);
+    // A failure, so the component unwinds as any failed step would; nothing after the gate ran.
+    expect(calls).not.toContain("code-deploy");
+    const gate = result.records.find((r) => r.kind === "gate:approve-node-1");
+    expect(gate).toMatchObject({ status: "fail" });
+    expect(gate!.error).toContain("cannot be passed under --no-record");
+    expect(result.records.find((r) => r.kind === "code-deploy")).toMatchObject({ status: "skipped" });
+  });
+
   it("ends gated, records the pending fact, and runs nothing after the gate", async () => {
     const { registry, calls, rolledBack } = registryWithCalls();
     const port = memoryGateLedgerPort();

package/src/components/driver.ts

@@ -50,6 +50,7 @@ import { topoSort } from "../codegen/topo-sort";
 import { kahnLayers } from "./layers";
 import { evaluateGate, gitGateLedgerPort, type GateDigestMismatch, type GateLedgerPort } from "../op/gate";
 import { gateName } from "../op/gate-name";
+import { GateNotRecordableError } from "../lifecycle/no-record";
 import { componentPlanDigest } from "./gate-plan";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
@@ -473,17 +474,29 @@ async function runPhase(
     const gateRecords: DriverStepRecord[] = [];
     for (const gate of phaseDef.steps.filter(isGateStep)) {
       const start = Date.now();
-      const check = await evaluateGate(gates.port, {
-        op: ctx.component,
-        gate: gateName(gate),
-        // #2574: an approval counts only for this environment and this plan.
-        environment: ctx.env,
-        ...(gates.planDigest !== undefined ? { planDigest: gates.planDigest } : {}),
-        ...(gate.description ? { description: gate.description } : {}),
-        ...(gate.timeout ? { timeout: gate.timeout } : {}),
-        ...(gates.now ? { now: gates.now } : {}),
-      });
       const base = { component: ctx.component, phase: phaseDef.phase, kind: `gate:${gateName(gate)}` };
+      let check: Awaited<ReturnType<typeof evaluateGate>>;
+      try {
+        check = await evaluateGate(gates.port, {
+          op: ctx.component,
+          gate: gateName(gate),
+          // #2574: an approval counts only for this environment and this plan.
+          environment: ctx.env,
+          ...(gates.planDigest !== undefined ? { planDigest: gates.planDigest } : {}),
+          ...(gate.description ? { description: gate.description } : {}),
+          ...(gate.timeout ? { timeout: gate.timeout } : {}),
+          ...(gates.now ? { now: gates.now } : {}),
+        });
+      } catch (err) {
+        // #3955: a run that records nothing fails at the gate, as the Op
+        // executor's gate step does, and the component unwinds like any failure.
+        if (!(err instanceof GateNotRecordableError)) throw err;
+        gateRecords.push({ ...base, status: "fail" as const, durationMs: Date.now() - start, error: err.message });
+        for (const skipped of phaseDef.steps.filter((s): s is DriverStep | DriverPhase => !isGateStep(s))) {
+          gateRecords.push(skippedRecord(skipped));
+        }
+        throw new StepFailure(gateRecords, []);
+      }
       if (!check.satisfied) {
         gateRecords.push({ ...base, status: "skipped" as const, durationMs: Date.now() - start });
         for (const skipped of phaseDef.steps.filter((s): s is DriverStep | DriverPhase => !isGateStep(s))) {

package/src/components/generate-disabled.test.ts

@@ -0,0 +1,56 @@
+/**
+ * `chant build --components --generate <forge>` leaves out a component with
+ * `enabled: false` (#3951), the same way `chant run --components all` skips it
+ * (#1522): no job for it, and no other job needs it. Runs against the real
+ * GitHub, GitLab and Forgejo plugins, not a stand-in, so each forge's own
+ * `needs` rendering is what the assertions read.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { generateComponentsPipeline, resolveComponentTargets } from "./cli-support";
+
+describe.each(["github", "gitlab", "forgejo"])("generateComponentsPipeline %s: enabled: false (#3951)", (forge) => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-generate-disabled-${forge}-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+    await writeFile(
+      join(testDir, "tunnel.component.ts"),
+      `export const tunnel = { name: "tunnel", enabled: false, dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "t" }] }] };`,
+    );
+    await writeFile(
+      join(testDir, "db.component.ts"),
+      `export const db = { name: "db", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "t" }] }] };`,
+    );
+    await writeFile(
+      join(testDir, "api.component.ts"),
+      `export const api = { name: "api", dependsOn: ["db", "tunnel"], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "t" }] }] };`,
+    );
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("the disabled component has no job, and its dependent no longer needs it", async () => {
+    const result = await generateComponentsPipeline(testDir, forge, { env: "prod" });
+
+    expect(result.success).toBe(true);
+    expect(result.jobs?.map((j) => j.component).sort()).toEqual(["api", "db"]);
+    const api = result.jobs?.find((j) => j.component === "api");
+    const db = result.jobs?.find((j) => j.component === "db");
+    expect(api?.needs).toEqual([db?.jobName]);
+    expect(result.yaml).not.toMatch(/tunnel/);
+  });
+
+  test("the pipeline holds the components an \"all\" run takes", async () => {
+    const result = await generateComponentsPipeline(testDir, forge, { env: "prod" });
+    const run = await resolveComponentTargets(testDir, "all");
+
+    expect(result.jobs?.map((j) => j.component).sort()).toEqual(run.targets.map((t) => t.name).sort());
+  });
+});

package/src/graph-ci-edges.test.ts

@@ -95,3 +95,53 @@ describe("detail and lens keep CI edges (#3910)", () => {
     expect(focused.groups.byPipeline).toEqual({ ci: ["test"], shared: ["shared"] });
   });
 });
+
+describe("detail tiers carry groups.byPipeline (#3921)", () => {
+  // `build` and `test` sit inside one composite instance; `lint` in another
+  // that also holds a job of the `shared` pipeline.
+  const composed: GraphIR = {
+    nodes: [
+      { id: "ci", kind: "GitHub::Actions::Workflow", lexicon: "github", attrs: {} },
+      { id: "build", kind: "GitHub::Actions::Job", lexicon: "github", attrs: {}, compositeInstance: "pair", compositeParent: "Pair" },
+      { id: "test", kind: "GitHub::Actions::Job", lexicon: "github", attrs: {}, compositeInstance: "pair", compositeParent: "Pair" },
+      { id: "lint", kind: "GitHub::Actions::Job", lexicon: "github", attrs: {}, compositeInstance: "mixed", compositeParent: "Mixed" },
+      { id: "publish", kind: "GitHub::Actions::Job", lexicon: "github", attrs: {}, compositeInstance: "mixed", compositeParent: "Mixed" },
+      { id: "shared", kind: "GitHub::Actions::Workflow", lexicon: "github", attrs: {} },
+    ],
+    edges: [],
+    groups: {
+      byLexicon: { github: ["build", "ci", "lint", "publish", "shared", "test"] },
+      byPipeline: { ci: ["build", "ci", "lint", "test"], shared: ["publish", "shared"], gone: ["ghost"] },
+    },
+  };
+
+  test("the composite tier maps members to the composites that hold them, deduped", () => {
+    expect(applyDetail(composed, 1).groups.byPipeline).toEqual({
+      ci: ["ci", "mixed", "pair"],
+      shared: ["mixed", "shared"],
+    });
+  });
+
+  test("the composite tier keeps plain members as they are", () => {
+    expect(applyDetail(merged, 1).groups.byPipeline).toEqual({ ci: ["build", "ci", "test"], shared: ["shared"] });
+  });
+
+  test("a pipeline with no kept member is dropped, and no pipelines means no byPipeline", () => {
+    const none = applyDetail({ ...composed, groups: { byPipeline: { gone: ["ghost"] } } }, 1);
+    expect(none.groups.byPipeline).toBeUndefined();
+  });
+
+  test("the stacks tier has no pipelines: each would hold only its lexicon's node", () => {
+    expect(applyDetail(composed, 0).groups.byPipeline).toBeUndefined();
+  });
+
+  test("a lens then the composite tier keeps the pipelines of what survives", () => {
+    const t1 = applyDetail(applyLens(composed, parseLens("blast:shared")), 1);
+    expect(t1.groups.byPipeline).toEqual({ shared: ["shared"] });
+  });
+
+  test("declarable and attribute tiers pass byPipeline through", () => {
+    expect(applyDetail(composed, 2).groups.byPipeline).toEqual(composed.groups.byPipeline);
+    expect(applyDetail(composed, 3).groups.byPipeline).toEqual(composed.groups.byPipeline);
+  });
+});

package/src/graph-detail.ts

@@ -99,7 +99,9 @@ function byLexiconOf(nodes: IRNode[]): Record<string, string[]> {
   return sorted;
 }
 
-/** T0 — collapse every resource to its lexicon; edges become cross-lexicon deps. */
+/** T0 — collapse every resource to its lexicon; edges become cross-lexicon deps.
+ * No groups: a pipeline never spans lexicons, so `byPipeline` would put every
+ * pipeline of a lexicon around that lexicon's one stack node (#3921). */
 function toStacks(ir: GraphIR): GraphIR {
   const lexOf = new Map(ir.nodes.map((n) => [n.id, n.lexicon]));
   const lexicons = [...new Set(ir.nodes.map((n) => n.lexicon))].sort();
@@ -178,10 +180,27 @@ function toComposites(ir: GraphIR): GraphIR {
   const imports = ir.imports?.filter((i) => surviving.has(i.node));
   // Unresolved references (#3910) stay with whichever node now holds them.
   const dangling = ir.dangling?.map((d) => ({ ...d, from: idMap.get(d.from) ?? d.from }));
+  // Pipeline membership (#3921) follows each member to the node that now holds
+  // it: a job inside a collapsed composite is drawn as that composite. A
+  // composite that spans two pipelines sits in both; a pipeline whose members
+  // all fell away is dropped.
+  const groups: GraphIR["groups"] = { byLexicon: byLexiconOf(nodes) };
+  if (ir.groups.byPipeline) {
+    const byPipeline: Record<string, string[]> = {};
+    for (const name of Object.keys(ir.groups.byPipeline).sort()) {
+      const kept = new Set<string>();
+      for (const m of ir.groups.byPipeline[name]) {
+        const id = idMap.get(m) ?? m;
+        if (surviving.has(id)) kept.add(id);
+      }
+      if (kept.size) byPipeline[name] = [...kept].sort();
+    }
+    if (Object.keys(byPipeline).length) groups.byPipeline = byPipeline;
+  }
   return {
     nodes,
     edges: sortEdges([...seen.values()]),
-    groups: { byLexicon: byLexiconOf(nodes) },
+    groups,
     ...(imports && imports.length ? { imports } : {}),
     ...(dangling && dangling.length ? { dangling } : {}),
   };

package/src/graph-ir.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { buildGraphIr } from "./graph-ir";
+import { applyLexiconOutputs, buildGraphIr } from "./graph-ir";
 import { DECLARABLE_MARKER, type Declarable } from "./declarable";
 import { AttrRef } from "./attrref";
 import { LexiconOutput } from "./lexicon-output";
@@ -370,3 +370,25 @@ describe("whole declarables held in an entity's fields (#3257)", () => {
     expect(ir.edges).toEqual([{ from: "lb", to: "vpc", kind: "ref", viaAttr: "actions" }]);
   });
 });
+
+describe("applyLexiconOutputs (#3931)", () => {
+  test("adds each reported output to exports on the node that declares it, keeping a hand-written export", () => {
+    const orders = decl({ lexicon: "sql", entityType: "Postgres::Table", props: {} });
+    const ir = buildGraphIr(new Map<string, Declarable>([["orders", orders]]));
+    const withOutputs = applyLexiconOutputs({ ...ir, exports: [{ name: "public.orders", node: "orders", attr: "name" }] }, [
+      {
+        outputs: [
+          { name: "public.orders", entity: "orders" },
+          { name: "public.orders.buyer_id", entity: "orders", previously: ["public.orders.customer_id"] },
+          { name: "other.thing", entity: "notANode" },
+        ],
+      },
+    ]);
+    expect(withOutputs.exports).toEqual([
+      { name: "other.thing" },
+      { name: "public.orders", node: "orders", attr: "name" },
+      { name: "public.orders.buyer_id", node: "orders", previously: ["public.orders.customer_id"] },
+    ]);
+    expect(applyLexiconOutputs(ir, [{ outputs: [] }])).toBe(ir);
+  });
+});

package/src/graph-ir.ts

@@ -155,6 +155,43 @@ export interface LexiconGraphReference {
   dangling?: boolean;
 }
 
+/**
+ * One output a lexicon reports for its own declarations (#3931): a name a
+ * workspace link may target, such as a sql table's `public.orders` or a
+ * column's `public.orders.customer_id`.
+ */
+export interface LexiconWorkspaceOutput {
+  /** The output's name, as a link's `output` names it. */
+  name: string;
+  /** The entity key that declares it. */
+  entity: string;
+  /**
+   * Names the output had before, from a rename hint in source (a sql
+   * `-- previously:` comment). A link to one of them is told where it went.
+   */
+  previously?: string[];
+}
+
+/** One file the reader was handed but could not read without running it (#3931). */
+export interface LexiconUnreadSource {
+  /** The file's path, as the caller names it in messages. */
+  file: string;
+  text: string;
+  /** Why it was not read: the fold's located reason. */
+  reason: string;
+}
+
+/** What a lexicon's `workspaceOutputs` hook returns (#3931). */
+export interface LexiconWorkspaceOutputs {
+  outputs: LexiconWorkspaceOutput[];
+  /**
+   * Why the list may be incomplete, one line each: a declaration whose name
+   * can't be known statically, a file of this lexicon's that did not fold, a
+   * view whose columns can't be derived. Empty or absent when it is complete.
+   */
+  gaps?: string[];
+}
+
 /** What a lexicon's `graphEdges` hook returns (#3910). */
 export interface LexiconGraphEdges {
   references: LexiconGraphReference[];
@@ -304,6 +341,8 @@ export interface IRExport {
   value?: unknown;
   /** The deployed stack that publishes it, on an observed graph (#1279). */
   stack?: string;
+  /** Names the output had before, from a rename hint a lexicon read (#3931). */
+  previously?: string[];
 }
 
 /** A cross-stack import this stack consumes — a `Parameter` fed from another
@@ -834,6 +873,32 @@ export function applyLexiconGraphEdges(ir: GraphIR, reports: readonly LexiconGra
   return out;
 }
 
+/**
+ * Add the outputs the lexicons' `workspaceOutputs` hooks report (#3931) to a
+ * built IR's `exports`, each on the node that declares it. An output whose
+ * name is already exported (a hand-written `output()`) keeps the existing
+ * export. Pure. Returns `ir` itself when no report added anything.
+ */
+export function applyLexiconOutputs(ir: GraphIR, reports: readonly LexiconWorkspaceOutputs[]): GraphIR {
+  const nodeIds = new Set(ir.nodes.map((n) => n.id));
+  const names = new Set((ir.exports ?? []).map((e) => e.name));
+  const added: IRExport[] = [];
+  for (const report of reports) {
+    for (const o of report.outputs) {
+      if (names.has(o.name)) continue;
+      names.add(o.name);
+      added.push({
+        name: o.name,
+        ...(nodeIds.has(o.entity) ? { node: o.entity } : {}),
+        ...(o.previously && o.previously.length > 0 ? { previously: [...o.previously] } : {}),
+      });
+    }
+  }
+  if (added.length === 0) return ir;
+  const exports = [...(ir.exports ?? []), ...added].sort((a, b) => a.name.localeCompare(b.name));
+  return { ...ir, exports };
+}
+
 function danglingKey(d: IRDanglingRef): string {
   return `${d.from}\0${d.path}\0${d.value}`;
 }

package/src/lexicon.ts

@@ -23,7 +23,7 @@ import type { OwnershipChannel, OwnershipMarker } from "./ownership";
 import type { LexiconConfigSchema } from "./lexicon-config";
 import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
-import type { IREdge, LexiconGraphEdges } from "./graph-ir";
+import type { IREdge, LexiconGraphEdges, LexiconUnreadSource, LexiconWorkspaceOutputs } from "./graph-ir";
 import type { DescribeResourcesResult, UnobservedReason } from "./observation";
 import type { DescribeIdentityOptions, DescribeIdentityResult } from "./identity";
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
@@ -1450,6 +1450,31 @@ export interface LexiconPlugin {
    */
   graphEdges?(entities: ReadonlyMap<string, Declarable>): LexiconGraphEdges | undefined;
 
+  /**
+   * The workspace outputs this lexicon's declarations expose (#3931): names
+   * another member's link may target, without anyone writing `output(...)`.
+   * The sql lexicon answers each table and view as `<schema>.<table>` and
+   * each column as `<schema>.<table>.<column>`.
+   *
+   * Called two ways, with the same answer expected from both:
+   *
+   * - by `chant workspace check`, offline, with the entities the member's
+   *   source folds to (`foldProject` under `sandbox`: no member code runs),
+   *   and `unread` listing the files that did not fold, with their text. A
+   *   file of this lexicon's among them is a gap: the list is then incomplete
+   *   and a link to a name not in it is unresolved rather than missing;
+   * - by `chant graph --format ir`, with the built entities and no `unread`.
+   *   The outputs land on the IR's `exports`, which `chant workspace graph`
+   *   resolves links against.
+   *
+   * Names come from the declarations as written in source, never from an
+   * environment's or profile's rendering, so they stay the same everywhere
+   * the member deploys. Pure: no I/O. Return `undefined` when the project
+   * declares nothing this lexicon reports. Omit for lexicons with no such
+   * declarations.
+   */
+  workspaceOutputs?(entities: ReadonlyMap<string, Declarable>, unread?: readonly LexiconUnreadSource[]): LexiconWorkspaceOutputs | undefined;
+
   // LSP
   /** Provide completions for LSP */
   completionProvider?(ctx: CompletionContext): CompletionItem[];