@intentius/chant 0.124.51 → 0.124.54

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

@@ -0,0 +1,10 @@
+import type { Component } from "../../../../../../components/component";
+import { phase } from "../../../../../../components/component";
+
+/** COMP008 pass case: the component deploys only its own root, "dns". */
+export const dns: Component = {
+  name: "dns",
+  archetype: "infra",
+  dependsOn: [],
+  deploy: [phase("Apply", [{ kind: "terraform-apply", root: "dns" }])],
+};

package/src/lint/rules/comp/comp.test.ts

@@ -54,7 +54,7 @@ describe("COMP000: component discovery errors", () => {
 });
 
 describe("loadComponentChecks()", () => {
-  it("returns all seven COMP* checks, sorted by id, each error or warning severity", () => {
+  it("returns all eight COMP* checks, sorted by id, each error or warning severity", () => {
     expect(checks.map((c) => c.id)).toEqual([
       "COMP001",
       "COMP002",
@@ -63,6 +63,7 @@ describe("loadComponentChecks()", () => {
       "COMP005",
       "COMP006",
       "COMP007",
+      "COMP008",
     ]);
     for (const check of checks) {
       expect(["error", "warning"]).toContain(check.severity);

package/src/lint/rules/comp/comp008-applies-signal-only-root.ts

@@ -0,0 +1,121 @@
+/**
+ * COMP008: applies-signal-only-root (#4490)
+ *
+ * Flags a component whose `terraform-apply` step deploys a root the project
+ * marks `signalOnly: true` in `terraform.roots` (#4484). Such a root belongs
+ * to another workspace member and is declared here only so a change to it
+ * brings this project into the change: the build skips it, so this
+ * project's graph does not draw it, and the live reads skip it too. A
+ * component that applies it would apply a root chant otherwise treats as
+ * the other member's, so the warning names the root and the member that
+ * owns it (the workspace member whose directory holds the root's `dir`).
+ *
+ * The roots come from the project's chant config, resolved by `chant lint`
+ * ({@link signalOnlyRootsOf}) and handed to the check on
+ * `ComponentCheckContext.signalOnlyRoots`. A check run without them (a
+ * direct unit test, a project with no terraform roots) flags nothing.
+ *
+ * Triggers on: `{ kind: "terraform-apply", root: "azure" }` where
+ * `terraform.roots.azure.signalOnly` is `true`.
+ * OK: the same step on a root without the marker, or no `terraform-apply`
+ * step naming the marked root.
+ */
+
+import { isAbsolute, relative, resolve } from "node:path";
+import type { ComponentCheck, ComponentCheckContext, ComponentCheckDiagnostic, SignalOnlyRoot } from "../../component-checks";
+import { walkComponent } from "./support";
+
+export const comp008AppliesSignalOnlyRootRule: ComponentCheck = {
+  id: "COMP008",
+  severity: "warning",
+  category: "correctness",
+  description: "A terraform-apply step deploys a root marked signalOnly, which another workspace member owns",
+  check(ctx: ComponentCheckContext): ComponentCheckDiagnostic[] {
+    const roots = ctx.signalOnlyRoots;
+    if (!roots || roots.size === 0) return [];
+    const diagnostics: ComponentCheckDiagnostic[] = [];
+
+    for (const [name, { component, filePath }] of ctx.components) {
+      const seen = new Set<string>();
+      for (const { step, phaseName } of walkComponent(component).steps) {
+        if (step.kind !== "terraform-apply") continue;
+        const root = (step as { root?: unknown }).root;
+        if (typeof root !== "string" || seen.has(root)) continue;
+        const marked = roots.get(root);
+        if (!marked) continue;
+        seen.add(root);
+        const owner = marked.owner
+          ? `workspace member "${marked.owner}" owns it`
+          : "no workspace member was found to own it";
+        diagnostics.push({
+          checkId: "COMP008",
+          severity: "warning",
+          component: name,
+          file: filePath,
+          message:
+            `Component "${name}": the "terraform-apply" step (phase "${phaseName}") deploys root "${root}" ` +
+            `(${marked.dir}), which terraform.roots marks signalOnly; ${owner}. This project declares the root ` +
+            `only so a change to it brings the project into the change, and its build and live reads skip it. ` +
+            `Deploy the root from ${marked.owner ? `"${marked.owner}"` : "the member that owns it"}, or drop signalOnly ` +
+            `if this project owns it.`,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};
+
+/**
+ * The roots a project's `terraform.roots` marks `signalOnly`, keyed by root
+ * name, each with its `dir` as written and the workspace member whose
+ * directory holds it. `projectDir` is the directory holding the chant
+ * config. Tolerant: a config that does not load, or no marked root, gives an
+ * empty map; a workspace declaration that does not read leaves `owner` off.
+ */
+export async function signalOnlyRootsOf(projectDir: string): Promise<Map<string, SignalOnlyRoot>> {
+  const out = new Map<string, SignalOnlyRoot>();
+  let roots: Record<string, unknown> | undefined;
+  try {
+    const { loadChantConfig } = await import("../../../config");
+    const loaded = await loadChantConfig(projectDir);
+    roots = (loaded.config as { terraform?: { roots?: Record<string, unknown> } }).terraform?.roots;
+  } catch {
+    return out;
+  }
+  const marked: Array<[string, string]> = [];
+  for (const [name, entry] of Object.entries(roots ?? {})) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const { dir, signalOnly } = entry as { dir?: unknown; signalOnly?: unknown };
+    if (signalOnly !== true || typeof dir !== "string") continue;
+    marked.push([name, dir]);
+  }
+  if (marked.length === 0) return out;
+
+  const ownerOfDir = await workspaceOwnerLookup(projectDir);
+  for (const [name, dir] of marked) {
+    const owner = ownerOfDir?.(resolve(projectDir, dir));
+    out.set(name, { dir, ...(owner ? { owner } : {}) });
+  }
+  return out;
+}
+
+/** A lookup from an absolute directory to the workspace member owning it, or undefined outside a readable workspace. */
+async function workspaceOwnerLookup(projectDir: string): Promise<((abs: string) => string | undefined) | undefined> {
+  try {
+    const { findWorkspaceRoot } = await import("../../../project-root");
+    const found = findWorkspaceRoot(projectDir);
+    if (!found) return undefined;
+    const { readDeclaration, ownerOf } = await import("../../../workspace/declaration");
+    const { workingTree } = await import("../../../workspace/tree");
+    const declaration = readDeclaration(workingTree(found.dir));
+    return (abs: string) => {
+      const rel = relative(found.dir, abs);
+      if (rel.startsWith("..") || isAbsolute(rel)) return undefined;
+      const owner = ownerOf(declaration, [], rel === "" ? "." : rel.split("\\").join("/"));
+      return owner && "member" in owner ? owner.member.name : undefined;
+    };
+  } catch {
+    return undefined;
+  }
+}

package/src/lint/rules/comp/comp008.test.ts

@@ -0,0 +1,77 @@
+/**
+ * COMP008 (#4490): a component's terraform-apply step deploys a root the
+ * project marks signalOnly. The check runs over fixture components with the
+ * marked roots handed in, the way `chant lint` hands them; the config read
+ * (`signalOnlyRootsOf`) runs over a temporary workspace.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import { runComponentChecks, type SignalOnlyRoot } from "../../component-checks";
+import { comp008AppliesSignalOnlyRootRule, signalOnlyRootsOf } from "./comp008-applies-signal-only-root";
+
+const FIXTURES = join(import.meta.dirname, "..", "__fixtures__", "comp", "comp008");
+const MARKED = new Map<string, SignalOnlyRoot>([["azure", { dir: "../azure", owner: "azure" }]]);
+
+describe("COMP008: applies-signal-only-root", () => {
+  it("warns on a terraform-apply step deploying a signalOnly root, naming the root and its owner", async () => {
+    const diagnostics = await runComponentChecks(join(FIXTURES, "fail"), [comp008AppliesSignalOnlyRootRule], { signalOnlyRoots: MARKED });
+    expect(diagnostics).toHaveLength(1);
+    const [d] = diagnostics;
+    expect(d.checkId).toBe("COMP008");
+    expect(d.severity).toBe("warning");
+    expect(d.component).toBe("dns");
+    expect(d.message).toContain('root "azure"');
+    expect(d.message).toContain('workspace member "azure" owns it');
+  });
+
+  it("says no owner was found when the workspace names none", async () => {
+    const roots = new Map<string, SignalOnlyRoot>([["azure", { dir: "../azure" }]]);
+    const [d] = await runComponentChecks(join(FIXTURES, "fail"), [comp008AppliesSignalOnlyRootRule], { signalOnlyRoots: roots });
+    expect(d.message).toContain("no workspace member was found to own it");
+  });
+
+  it("passes a component that deploys only its own roots", async () => {
+    const diagnostics = await runComponentChecks(join(FIXTURES, "pass"), [comp008AppliesSignalOnlyRootRule], { signalOnlyRoots: MARKED });
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  it("flags nothing when no marked roots were resolved", async () => {
+    expect(await runComponentChecks(join(FIXTURES, "fail"), [comp008AppliesSignalOnlyRootRule])).toHaveLength(0);
+  });
+});
+
+describe("signalOnlyRootsOf", () => {
+  const ws = mkdtempSync(join(tmpdir(), "comp008-"));
+  afterAll(() => rmSync(ws, { recursive: true, force: true }));
+  // findWorkspaceRoot walks up to the git root, so the workspace root holds a .git.
+  mkdirSync(join(ws, ".git"));
+  mkdirSync(join(ws, "dns"));
+  mkdirSync(join(ws, "azure"));
+  writeFileSync(
+    join(ws, "chant.workspace.json"),
+    JSON.stringify({
+      name: "estate",
+      schema: 1,
+      members: [
+        { name: "dns", dir: "dns", kind: "chant", because: "the dns zone" },
+        { name: "azure", dir: "azure", kind: "chant", because: "the azure estate" },
+      ],
+    }),
+  );
+  writeFileSync(
+    join(ws, "dns", "chant.config.json"),
+    JSON.stringify({ terraform: { roots: { dns: { dir: "./estate" }, azure: { dir: "../azure", signalOnly: true } } } }),
+  );
+
+  it("lists only the marked roots, with the member whose directory holds each", async () => {
+    const roots = await signalOnlyRootsOf(join(ws, "dns"));
+    expect([...roots]).toEqual([["azure", { dir: "../azure", owner: "azure" }]]);
+  });
+
+  it("gives an empty map for a project with no config", async () => {
+    expect((await signalOnlyRootsOf(join(ws, "azure"))).size).toBe(0);
+  });
+});

package/src/lint/rules/comp/index.ts

@@ -14,6 +14,7 @@ import { comp004GateNeedsDurableRuntimeRule } from "./comp004-gate-needs-durable
 import { comp005CapabilityKindIsNounRule } from "./comp005-capability-kind-is-noun";
 import { comp006ShellNeedsReasonRule } from "./comp006-shell-needs-reason";
 import { comp007CompositionSprawlRule } from "./comp007-composition-sprawl";
+import { comp008AppliesSignalOnlyRootRule } from "./comp008-applies-signal-only-root";
 
 export { comp001PublishesNeverAppliesRule } from "./comp001-publishes-never-applies";
 export { comp002DanglingWiringRefRule } from "./comp002-dangling-wiring-ref";
@@ -22,8 +23,9 @@ export { comp004GateNeedsDurableRuntimeRule } from "./comp004-gate-needs-durable
 export { comp005CapabilityKindIsNounRule } from "./comp005-capability-kind-is-noun";
 export { comp006ShellNeedsReasonRule } from "./comp006-shell-needs-reason";
 export { comp007CompositionSprawlRule } from "./comp007-composition-sprawl";
+export { comp008AppliesSignalOnlyRootRule, signalOnlyRootsOf } from "./comp008-applies-signal-only-root";
 
-/** All seven COMP* checks, sorted by id. */
+/** All eight COMP* checks, sorted by id. */
 export function loadComponentChecks(): ComponentCheck[] {
   return [
     comp001PublishesNeverAppliesRule,
@@ -33,5 +35,6 @@ export function loadComponentChecks(): ComponentCheck[] {
     comp005CapabilityKindIsNounRule,
     comp006ShellNeedsReasonRule,
     comp007CompositionSprawlRule,
+    comp008AppliesSignalOnlyRootRule,
   ];
 }

package/src/observation-edges.test.ts

@@ -0,0 +1,33 @@
+// An observation's own edges (chant#4528): the terraform lexicon's read of
+// `choudoufu live-graph` returns block edges with its resources, and core
+// carries them through the envelope to `LiveObservation.edges`.
+import { describe, it, expect } from "vitest";
+import { mergeObservations, normalizeObservation, observation } from "./observation";
+import { buildLiveGraphIr, type IREdge } from "./graph-ir";
+
+const block: IREdge = { from: "web/module.app/aws_instance.web", to: "web/aws_s3_bucket.logs", kind: "ref", viaAttr: "dependencies", grain: "block" };
+const instance: IREdge = { ...block, grain: "instance" };
+
+describe("observation edges (#4528)", () => {
+  it("the envelope carries edges, and leaves the field off when there are none", () => {
+    expect(observation({}, undefined, undefined, undefined, undefined, undefined, undefined, undefined, [block]).edges).toEqual([block]);
+    expect("edges" in observation({}, undefined, undefined, undefined, undefined, undefined, undefined, undefined, [])).toBe(false);
+    expect(normalizeObservation(observation({}, undefined, undefined, undefined, undefined, undefined, undefined, undefined, [block])).edges).toEqual([block]);
+    expect(normalizeObservation({}).edges).toBeUndefined();
+  });
+
+  it("a merge keeps each edge once, and two grains between one pair as two", () => {
+    const part = normalizeObservation(observation({}, undefined, undefined, undefined, undefined, undefined, undefined, undefined, [block, instance]));
+    expect(mergeObservations([part, part]).edges).toEqual([block, instance]);
+    expect(mergeObservations([normalizeObservation({})]).edges).toBeUndefined();
+  });
+
+  it("buildLiveGraphIr keeps an observation edge whose endpoints were both observed", () => {
+    const resources = {
+      "web/module.app/aws_instance.web": { type: "Terraform::Resource", status: "bound" },
+      "web/aws_s3_bucket.logs": { type: "Terraform::Resource", status: "bound" },
+    };
+    const ir = buildLiveGraphIr([{ lexicon: "terraform", resources, edges: [block, { ...block, to: "web/aws_sqs_queue.gone" }] }]);
+    expect(ir.edges).toEqual([block]);
+  });
+});

package/src/observation.ts

@@ -33,6 +33,7 @@
  */
 
 import type { ResourceMetadata } from "./lexicon";
+import type { IREdge } from "./graph-ir";
 
 /**
  * Why a declared entity was not observed. Total: a lexicon that cannot observe
@@ -49,13 +50,18 @@ import type { ResourceMetadata } from "./lexicon";
  *   filter (`owned: true` against a resource carrying no chant marker). The
  *   result deliberately says nothing about it, which is still not absence: a
  *   declared resource that exists but is foreign must not classify as `create`.
+ * - `not-reached` — the read that would have answered never reported this
+ *   entity (#4451): a drift stream settled without a row for an address its
+ *   start line expected, or a read was never run for it at all. Says nothing
+ *   about the entity, only that no answer arrived.
  */
 export type UnobservedReason =
   | "read-failed"
   | "no-credentials"
   | "no-binding"
   | "unsupported-kind"
-  | "filtered";
+  | "filtered"
+  | "not-reached";
 
 /**
  * Every legal {@link UnobservedReason}, for validation and conformance checks.
@@ -79,6 +85,7 @@ const UNOBSERVED_REASON_WITNESS: Record<UnobservedReason, true> = {
   "no-binding": true,
   "unsupported-kind": true,
   filtered: true,
+  "not-reached": true,
 };
 
 export const UNOBSERVED_REASONS: readonly UnobservedReason[] = Object.keys(
@@ -192,6 +199,16 @@ export interface ObservationResult {
    * question. Values are already scrubbed of anything that looks secret.
    */
   stackExports?: Record<string, Record<string, unknown>>;
+  /**
+   * Relationships the read observed between the resources it returned
+   * (chant#4528): an ownership engine's graph, such as the block edges
+   * `choudoufu live-graph` prints, with their `grain`. Core carries them to
+   * `LiveObservation.edges` beside the ones `describeDependencies` reports;
+   * `buildLiveGraphIr` drops any whose endpoints were not both observed.
+   * `from`/`to` are node ids in the space of {@link resources} keys and the
+   * instance node ids built from them.
+   */
+  edges?: IREdge[];
 }
 
 /**
@@ -230,6 +247,8 @@ export interface NormalizedObservation {
   notes: string[];
   /** Per-stack exports (#1279), keyed by stack name. Absent when the lexicon reported none. */
   stackExports?: Record<string, Record<string, unknown>>;
+  /** Observed relationships (chant#4528). Absent when the lexicon reported none. */
+  edges?: IREdge[];
 }
 
 /** True when `value` is the versioned {@link ObservationResult} envelope. */
@@ -254,6 +273,7 @@ export function observation(
   sources?: Record<string, string>,
   annotations?: Record<string, Record<string, unknown>>,
   rootReads?: Record<string, RootRead>,
+  edges?: IREdge[],
 ): ObservationResult {
   return {
     observation: "v1",
@@ -265,6 +285,7 @@ export function observation(
     ...(rootReads && Object.keys(rootReads).length > 0 ? { rootReads } : {}),
     ...(notes && notes.length > 0 ? { notes } : {}),
     ...(stackExports && Object.keys(stackExports).length > 0 ? { stackExports } : {}),
+    ...(edges && edges.length > 0 ? { edges } : {}),
   };
 }
 
@@ -286,6 +307,7 @@ export function normalizeObservation(value: DescribeResourcesResult | undefined)
       ...(value.annotations && Object.keys(value.annotations).length > 0 ? { annotations: value.annotations } : {}),
       ...(value.rootReads && Object.keys(value.rootReads).length > 0 ? { rootReads: value.rootReads } : {}),
       ...(value.stackExports && Object.keys(value.stackExports).length > 0 ? { stackExports: value.stackExports } : {}),
+      ...(Array.isArray(value.edges) && value.edges.length > 0 ? { edges: value.edges } : {}),
     };
   }
   return { resources: value, unobserved: {}, queried: {}, sources: {}, notes: [] };
@@ -339,6 +361,10 @@ export function mergeObservations(parts: Iterable<NormalizedObservation>): Norma
   // Annotations (#4372) merge like `sources`: per entity, disjoint parts.
   const annotations: Record<string, Record<string, unknown>> = {};
   const rootReads: Record<string, RootRead> = {};
+  // Edges (#4528) concatenate, once each: the parts read disjoint entity sets,
+  // and two parts reporting the same edge is one edge.
+  const edges: IREdge[] = [];
+  const edgeKeys = new Set<string>();
   for (const part of parts) {
     Object.assign(resources, part.resources);
     Object.assign(unobserved, part.unobserved);
@@ -348,6 +374,12 @@ export function mergeObservations(parts: Iterable<NormalizedObservation>): Norma
     Object.assign(rootReads, part.rootReads ?? {});
     for (const n of part.notes) notes.add(n);
     Object.assign(stackExports, part.stackExports ?? {});
+    for (const e of part.edges ?? []) {
+      const key = `${e.from}\0${e.to}\0${e.viaAttr ?? ""}\0${e.toAttr ?? ""}\0${e.grain ?? ""}`;
+      if (edgeKeys.has(key)) continue;
+      edgeKeys.add(key);
+      edges.push(e);
+    }
   }
   // Present wins: a stack that could not be read does not un-observe a resource
   // another stack returned.
@@ -361,6 +393,7 @@ export function mergeObservations(parts: Iterable<NormalizedObservation>): Norma
     ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
     ...(Object.keys(rootReads).length > 0 ? { rootReads } : {}),
     ...(Object.keys(stackExports).length > 0 ? { stackExports } : {}),
+    ...(edges.length > 0 ? { edges } : {}),
   };
 }
 
@@ -377,6 +410,8 @@ export function unobservedReasonText(reason: UnobservedReason): string {
       return "no reader for this resource kind";
     case "filtered":
       return "withheld by the --owned filter";
+    case "not-reached":
+      return "the read never reported it";
   }
 }
 

package/src/op/activities/activity-contracts.ts

@@ -309,7 +309,7 @@ export const lifecyclePlanChangeSetContract = activityContract(
 
 export const readChangeSetPartContract = activityContract(
   "readChangeSetPart",
-  z.strictObject({ member: z.string(), planner: z.enum(["chant", "warden", "sql"]), file: z.string(), lexicon: z.string().optional() }),
+  z.strictObject({ member: z.string(), planner: z.enum(["chant", "warden", "sql", "pulumi"]), file: z.string(), lexicon: z.string().optional() }),
   z.object({ part: changeSetPart }),
 );
 

package/src/op/activities/change-set.ts

@@ -90,10 +90,11 @@ export interface ReadChangeSetPartArgs {
   member: string;
   /**
    * Which planner wrote the file: `chant` (`lifecycle plan --json`), `warden`
-   * (its reconcile change sets), or `sql` (a part the sql lexicon's
-   * `change-set` adapters produced, written as JSON).
+   * (its reconcile change sets), `sql` (a part the sql lexicon's
+   * `change-set` adapters produced, written as JSON), or `pulumi` (a part
+   * the pulumi lexicon's `pulumiPreviewPart` produced, written as JSON).
    */
-  planner: "chant" | "warden" | "sql";
+  planner: "chant" | "warden" | "sql" | "pulumi";
   /** The plan file, relative to the current directory. */
   file: string;
   /** The lexicon the entries belong to, when the plan does not say. */
@@ -104,7 +105,8 @@ export interface ReadChangeSetPartArgs {
  * A plan another step or job wrote to a file, as a member's part. A warden
  * plan is the reconcile `ChangeSet` (`@intentius/chant/reconcile`), or an
  * array of them, one per cycle and org. A sql plan is already a part
- * (`@intentius/chant-lexicon-sql/change-set`), renamed to `member` here.
+ * (`@intentius/chant-lexicon-sql/change-set`), renamed to `member` here,
+ * and so is a pulumi one (`@intentius/chant-lexicon-pulumi/change-set`).
  */
 export async function readChangeSetPart(args: ReadChangeSetPartArgs): Promise<ChangeSetPartResult> {
   const plan: unknown = JSON.parse(readFileSync(resolve(args.file), "utf-8"));
@@ -115,7 +117,8 @@ export async function readChangeSetPart(args: ReadChangeSetPartArgs): Promise<Ch
     case "warden":
       return { part: reconcilePlanPart({ member: args.member, plan: plan as ReconcileChangeSet | ReconcileChangeSet[], ...lexicon }) };
     case "sql":
-      return { part: readChangeSetPartFile(plan, "sql", args.member, args.lexicon) };
+    case "pulumi":
+      return { part: readChangeSetPartFile(plan, args.planner, args.member, args.lexicon) };
     default:
       throw new Error(`readChangeSetPart: no adapter for planner ${String(args.planner)}; terraform-family plans come from terraformPlan's changeSet`);
   }

package/src/op/activity-failure.ts

@@ -32,3 +32,39 @@ export class NonRetryableActivityError extends Error {
 export function nonRetryableFailure(message: string, type: string): NonRetryableActivityError {
   return new NonRetryableActivityError(message, type);
 }
+
+/**
+ * The property a failing activity sets on the error it throws to publish
+ * outputs it already knew when it failed (chant#4512). terraformInit knows its
+ * root's directory once the root resolves and before `terraform init` runs, so
+ * a failed init still names the root it was for.
+ *
+ * It is a plain property, not a class, so a lexicon can set it without
+ * importing anything newer from core: an executor that predates it reads the
+ * error as any other failure.
+ */
+export const KNOWN_OUTPUTS_KEY = "knownOutputs";
+
+/** An activity error carrying the outputs it knew before it failed (chant#4512). */
+export type ErrorWithKnownOutputs = Error & { [KNOWN_OUTPUTS_KEY]: Record<string, unknown> };
+
+/**
+ * Attach `outputs` to `err` as the outputs the activity knew when it failed,
+ * and hand the error back for the activity to rethrow. A thrown non-Error is
+ * wrapped in one, so its message survives.
+ */
+export function withKnownOutputs(err: unknown, outputs: Record<string, unknown>): ErrorWithKnownOutputs {
+  const e = err instanceof Error ? err : new Error(String(err));
+  return Object.assign(e, { [KNOWN_OUTPUTS_KEY]: outputs });
+}
+
+/**
+ * The outputs a failed activity published on its error (chant#4512), or
+ * undefined when it published none. An executor resolves a failed step's
+ * `outcomeAttribute` paths against these, as it does against a result.
+ */
+export function knownOutputsOf(err: unknown): Record<string, unknown> | undefined {
+  if (typeof err !== "object" || err === null) return undefined;
+  const known = (err as Record<string, unknown>)[KNOWN_OUTPUTS_KEY];
+  return typeof known === "object" && known !== null && !Array.isArray(known) ? (known as Record<string, unknown>) : undefined;
+}

package/src/op/index.ts

@@ -123,7 +123,8 @@ export { loadActivityContracts, mergeActivityContracts } from "./activity-contra
 export type { LexiconActivityContractContributor } from "./activity-contract-registry";
 export { ACTIVITY_PROFILES, ACTIVITY_PROFILE_NAMES, MAX_STEP_TIMEOUT } from "./activity-profiles";
 export type { ActivityProfile, ActivityProfileName } from "./activity-profiles";
-export { NonRetryableActivityError, nonRetryableFailure } from "./activity-failure";
+export { NonRetryableActivityError, nonRetryableFailure, KNOWN_OUTPUTS_KEY, withKnownOutputs, knownOutputsOf } from "./activity-failure";
+export type { ErrorWithKnownOutputs } from "./activity-failure";
 export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor";
 export type { StepRecord, OpRunResult, RunOpOptions } from "./local-executor";
 export { currentOpRun, withOpRunContext } from "./run-context";

package/src/op/local-executor.test.ts

@@ -9,6 +9,7 @@ import {
 import { memoryGateLedgerPort, type GateLedgerPort } from "./gate";
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import { renderHuman } from "./local-output";
+import { knownOutputsOf, withKnownOutputs } from "./activity-failure";
 
 // #3521: whether the workspace seals a gate is read from identity.gates in the
 // working directory; a test says which gates are sealed instead.
@@ -264,6 +265,85 @@ describe("runOpLocally — outcomeAttribute", () => {
   });
 });
 
+describe("runOpLocally — a failed step records the outputs it knew (#4512)", () => {
+  /** The failed run's records, off the OpRunFailure it rejects with. */
+  async function failedRecords(config: OpConfig, activities: Map<string, ActivityFn>, profiles = PROFILES) {
+    const failure = await runOpLocally(config, activities, profiles).then(
+      () => undefined,
+      (err: unknown) => err,
+    );
+    expect(failure).toBeInstanceOf(OpRunFailure);
+    return (failure as OpRunFailure).result.records;
+  }
+
+  const initConfig = op({
+    phases: [
+      { name: "Init", steps: [{ kind: "activity", fn: "init", outcomeAttribute: [{ name: "TerraformRootPath", from: "rootPath" }, { name: "Workspace", from: "workspace" }] }] },
+      { name: "Plan", steps: [{ kind: "activity", fn: "plan" }] },
+    ],
+  });
+
+  test("a failed step's outcomes come from the known outputs on its error", async () => {
+    const init: ActivityFn = async () => {
+      throw withKnownOutputs(new Error("terraform init: backend unreachable"), { dir: "/w/estates/aws", rootPath: "estates/aws" });
+    };
+    let planRan = false;
+    const plan: ActivityFn = async () => {
+      planRan = true;
+      return {};
+    };
+    const records = await failedRecords(initConfig, new Map<string, ActivityFn>([["init", init], ["plan", plan]]));
+    expect(records[0]).toMatchObject({ phase: "Init", fn: "init", status: "fail", error: expect.stringContaining("backend unreachable") });
+    // Workspace is not among the known outputs, so it is left off.
+    expect(records[0].outcomes).toEqual([{ name: "TerraformRootPath", value: "estates/aws" }]);
+    expect(records[0].outcome).toEqual({ name: "TerraformRootPath", value: "estates/aws" });
+    // A failed phase ends the run there: Plan does not run, and a failure (unlike
+    // a gate, a decision point or a stopped claim) leaves no record for it.
+    expect(planRan).toBe(false);
+    expect(records.filter((r) => r.phase === "Plan")).toEqual([]);
+  });
+
+  test("a failed step with no known outputs records no outcome, as before", async () => {
+    const init: ActivityFn = async () => {
+      throw new Error("chant.config.ts failed to evaluate");
+    };
+    const records = await failedRecords(initConfig, new Map<string, ActivityFn>([["init", init], ["plan", async () => ({})]]));
+    expect(records[0].status).toBe("fail");
+    expect(records[0].outcome).toBeUndefined();
+    expect(records[0].outcomes).toBeUndefined();
+  });
+
+  test("a property set by hand, without core's helper, is read the same way", async () => {
+    const init: ActivityFn = async () => {
+      throw Object.assign(new Error("init failed"), { knownOutputs: { rootPath: "roots/app", workspace: "prod" } });
+    };
+    const records = await failedRecords(initConfig, new Map<string, ActivityFn>([["init", init], ["plan", async () => ({})]]));
+    expect(records[0].outcomes).toEqual([{ name: "TerraformRootPath", value: "roots/app" }, { name: "Workspace", value: "prod" }]);
+  });
+
+  test("after retries, the last attempt's known outputs are the ones recorded", async () => {
+    let calls = 0;
+    const init: ActivityFn = async () => {
+      calls++;
+      throw withKnownOutputs(new Error(`attempt ${calls}`), { rootPath: `attempt-${calls}` });
+    };
+    const config = op({
+      phases: [{ name: "Init", steps: [{ kind: "activity", fn: "init", outcomeAttribute: { name: "TerraformRootPath", from: "rootPath" } }] }],
+    });
+    const records = await failedRecords(config, new Map<string, ActivityFn>([["init", init]]));
+    expect(calls).toBe(3);
+    expect(records[0].outcomes).toEqual([{ name: "TerraformRootPath", value: "attempt-3" }]);
+  });
+
+  test("a thrown non-Error keeps its message when known outputs are attached", async () => {
+    expect(withKnownOutputs("plain string", { a: 1 }).message).toBe("plain string");
+    expect(knownOutputsOf(withKnownOutputs("plain string", { a: 1 }))).toEqual({ a: 1 });
+    expect(knownOutputsOf(new Error("none"))).toBeUndefined();
+    expect(knownOutputsOf(Object.assign(new Error("list"), { knownOutputs: ["x"] }))).toBeUndefined();
+    expect(knownOutputsOf(undefined)).toBeUndefined();
+  });
+});
+
 describe("runOpLocally — onFailure", () => {
   test("runs compensation phases in reverse and rejects with status=fail", async () => {
     const order: string[] = [];