@intentius/chant 0.124.45 → 0.124.48

package/src/lint/post-synth.ts

@@ -192,6 +192,11 @@ export interface PostSynthDiagnostic {
     /** Where it is missing from (e.g. a root module name). */
     scope: string;
   };
+  /**
+   * The build root the finding is about, set by a {@link CrossRootCheck}
+   * (chant #1939). Absent from a per-build finding.
+   */
+  root?: string;
 }
 
 /**
@@ -214,16 +219,26 @@ export interface PostSynthCheck {
    * new check would otherwise change the audit output of every project.
    */
   auditOptIn?: boolean;
+  /**
+   * `"build"`, the default: the check sees one build. A check that reads
+   * across build roots is a {@link CrossRootCheck} instead (chant #1939).
+   */
+  scope?: "build";
 }
 
-/** Structural type guard — used to collect project-authored policy checks. */
+/**
+ * Structural type guard — used to collect project-authored policy checks.
+ * A {@link CrossRootCheck} is not a `PostSynthCheck`, so a policy module or a
+ * lexicon's check directory that exports one never puts it in a per-build run.
+ */
 export function isPostSynthCheck(value: unknown): value is PostSynthCheck {
   return (
     typeof value === "object" &&
     value !== null &&
     typeof (value as PostSynthCheck).id === "string" &&
     typeof (value as PostSynthCheck).description === "string" &&
-    typeof (value as PostSynthCheck).check === "function"
+    typeof (value as PostSynthCheck).check === "function" &&
+    (value as { scope?: unknown }).scope !== "cross-root"
   );
 }
 
@@ -259,11 +274,206 @@ export function runPostSynthChecks(
 
   const diagnostics: PostSynthDiagnostic[] = [];
   for (const check of checks) {
+    // chant #1939: a cross-root check never runs in a per-build pass, even
+    // when a caller hands one over untyped. runCrossRootChecks runs it.
+    if ((check as { scope?: unknown }).scope === "cross-root") continue;
     diagnostics.push(...check.check(ctx));
   }
   return diagnostics;
 }
 
+// ---------------------------------------------------------------------------
+// Cross-build-root mode (chant #1939)
+// ---------------------------------------------------------------------------
+
+/**
+ * One build root handed to {@link runCrossRootChecks}: a name, and the build
+ * result the caller already has for it. The caller decides what a root is
+ * (a workspace member, a project directory, an environment's build) and
+ * builds it; this module never builds or reads the disk.
+ */
+export interface CrossRootInput {
+  /**
+   * The root's name, unique within one run. A workspace member's name, or a
+   * project-relative path. Findings name it in {@link PostSynthDiagnostic.root}.
+   */
+  root: string;
+  /** The root's directory, when it has one. */
+  dir?: string;
+  /** The environment this root was built for, when known. */
+  env?: string;
+  buildResult: PostSynthContext["buildResult"];
+  projectConfig?: Record<string, unknown>;
+}
+
+/**
+ * One build root as a cross-root check sees it: an ordinary
+ * {@link PostSynthContext} over that root's build, so a per-build helper
+ * (k8s's `allManifests(ctx)`) works on it unchanged, plus its name.
+ */
+export interface BuildRootView extends PostSynthContext {
+  readonly root: string;
+  readonly dir?: string;
+  readonly docs: OutputDoc[];
+}
+
+/** An {@link OutputDoc} tagged with the build root it came from. */
+export interface RootedOutputDoc extends OutputDoc {
+  root: string;
+}
+
+/**
+ * A link between two build roots, as the caller knows it (chant #2549): in a
+ * workspace, a member link from the declaration or one the members' graphs
+ * surface. A cross-root check that compares what the outputs say with what
+ * was written down reads these from {@link CrossRootContext.links}.
+ */
+export interface CrossRootLink {
+  consumer: string;
+  producer: string;
+  output: string;
+  /** How the link was found: `declared`, `kind-reader`, or `inferred:<rule>` for one the roots' graphs surface. */
+  origin: string;
+  /** The consumer's parameter an inferred link feeds; null or absent for a declared one. */
+  input?: string | null;
+  /** Whether the link resolved against the producer's outputs, as the caller judged it. */
+  status?: string;
+}
+
+/** An entity tagged with the build root that declared it. */
+export interface RootedEntity {
+  root: string;
+  name: string;
+  entity: Declarable;
+}
+
+/**
+ * Context provided to a {@link CrossRootCheck}. `roots` keeps every root's
+ * build apart; `docs` and `entities` are the union across roots, each entry
+ * tagged with its root, built lazily on first access.
+ */
+export interface CrossRootContext {
+  /** Every root in the run, in the order the caller gave them. */
+  readonly roots: readonly BuildRootView[];
+  /** Look a root up by name. */
+  root(name: string): BuildRootView | undefined;
+  /** Every root's parsed output documents, tagged by root. Lazy. */
+  readonly docs: readonly RootedOutputDoc[];
+  /** Every root's entities, tagged by root. Lazy. */
+  readonly entities: readonly RootedEntity[];
+  /** The run's environment, when the caller set one for the whole run. */
+  readonly env?: string;
+  readonly activityContracts?: ReadonlyMap<string, ActivityContract>;
+  /** The links between roots the caller passed (#2549), or absent when it passed none. */
+  readonly links?: readonly CrossRootLink[];
+}
+
+/** What a cross-root run takes besides its roots. */
+export interface CrossRootOptions {
+  env?: string;
+  activityContracts?: ReadonlyMap<string, ActivityContract>;
+  /** The links between roots (#2549), handed to every check as {@link CrossRootContext.links}. */
+  links?: readonly CrossRootLink[];
+}
+
+/**
+ * A check that reads across build roots (chant #1939). It declares
+ * `scope: "cross-root"`, and only {@link runCrossRootChecks} runs it:
+ * `chant build`, `chant lint` and every other per-build pass skip it, so a
+ * project that never asks for a cross-root run pays nothing for it.
+ */
+export interface CrossRootCheck {
+  id: string;
+  description: string;
+  scope: "cross-root";
+  check(ctx: CrossRootContext): PostSynthDiagnostic[];
+  /** As {@link PostSynthCheck.auditOptIn}. */
+  auditOptIn?: boolean;
+}
+
+/** Structural type guard for {@link CrossRootCheck}. */
+export function isCrossRootCheck(value: unknown): value is CrossRootCheck {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as CrossRootCheck).id === "string" &&
+    typeof (value as CrossRootCheck).description === "string" &&
+    typeof (value as CrossRootCheck).check === "function" &&
+    (value as CrossRootCheck).scope === "cross-root"
+  );
+}
+
+/**
+ * Build the {@link CrossRootContext} for a set of roots. Exported for tests
+ * and for a caller that runs checks itself; most callers want
+ * {@link runCrossRootChecks}. Throws on an empty or duplicate root name.
+ */
+export function createCrossRootContext(
+  inputs: readonly CrossRootInput[],
+  opts?: CrossRootOptions,
+): CrossRootContext {
+  const seen = new Set<string>();
+  const roots: BuildRootView[] = inputs.map((input) => {
+    if (input.root.length === 0) throw new Error("cross-root run: a build root needs a name");
+    if (seen.has(input.root)) throw new Error(`cross-root run: build root "${input.root}" appears twice`);
+    seen.add(input.root);
+    const getDocs = createDocsAccessor(input.buildResult.outputs);
+    const env = input.env ?? opts?.env;
+    return {
+      root: input.root,
+      ...(input.dir ? { dir: input.dir, projectDir: input.dir } : {}),
+      outputs: input.buildResult.outputs,
+      entities: input.buildResult.entities,
+      env,
+      buildResult: input.buildResult,
+      ...(opts?.activityContracts ? { activityContracts: opts.activityContracts } : {}),
+      ...(input.projectConfig ? { projectConfig: input.projectConfig } : {}),
+      get docs(): OutputDoc[] {
+        return getDocs();
+      },
+    };
+  });
+  const byName = new Map(roots.map((r) => [r.root, r]));
+  let docs: RootedOutputDoc[] | undefined;
+  let entities: RootedEntity[] | undefined;
+  return {
+    roots,
+    root: (name) => byName.get(name),
+    get docs(): readonly RootedOutputDoc[] {
+      docs ??= roots.flatMap((r) => r.docs.map((d) => ({ ...d, root: r.root })));
+      return docs;
+    },
+    get entities(): readonly RootedEntity[] {
+      entities ??= roots.flatMap((r) =>
+        [...r.entities].map(([name, entity]) => ({ root: r.root, name, entity })),
+      );
+      return entities;
+    },
+    ...(opts?.env ? { env: opts.env } : {}),
+    ...(opts?.activityContracts ? { activityContracts: opts.activityContracts } : {}),
+    ...(opts?.links ? { links: opts.links } : {}),
+  };
+}
+
+/**
+ * Run the cross-root checks in `checks` over `roots` (chant #1939). Anything
+ * in `checks` that is not a {@link CrossRootCheck} is skipped, so a caller can
+ * pass a lexicon's whole check list. With no cross-root check to run it
+ * returns at once, without building a context.
+ */
+export function runCrossRootChecks(
+  checks: ReadonlyArray<CrossRootCheck | PostSynthCheck>,
+  roots: readonly CrossRootInput[],
+  opts?: CrossRootOptions,
+): PostSynthDiagnostic[] {
+  const selected = checks.filter(isCrossRootCheck);
+  if (selected.length === 0) return [];
+  const ctx = createCrossRootContext(roots, opts);
+  const diagnostics: PostSynthDiagnostic[] = [];
+  for (const check of selected) diagnostics.push(...check.check(ctx));
+  return diagnostics;
+}
+
 // chant #1138 — `applyConfiguredSeverity` (the `lint.rules` severity-override
 // pass over a set of `PostSynthDiagnostic`s) lives in `./config.ts`, not here,
 // even though it operates on this module's own type. This file is a leaf:

package/src/lint/rule.ts

@@ -45,6 +45,12 @@ export interface LintDiagnostic {
   severity: Severity;
   /** Human-readable message */
   message: string;
+  /**
+   * The entity a post-synth check reported against, when it named one: the
+   * same name the message leads with in brackets, and the graph node's id
+   * (behold#919). Absent for a source-file rule.
+   */
+  entity?: string;
   /** Optional fix that can be applied */
   fix?: LintFix;
 }

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

@@ -28,6 +28,8 @@ export { ops016 } from "./ops016-gate-resume";
 export { ops017, ops017Check, workspaceIdentityGates } from "./ops017-gate-alias";
 export { ops018 } from "./ops018-shell-image-digest";
 export { sys010, sys010Check } from "./sys010-key-over-plain-http";
+// OPS019 (#2554) reads across members, so it is a cross-root check that only `chant workspace run` runs.
+export { ops019Check, parseWorkspaceOpTarget, formatWorkspaceOpTarget, OPS019_ID, type WorkspaceOpTarget } from "./ops019-workspace-op-target";
 
 export interface CoreOpCheckOptions {
   /** `decide.backends` from the project's chant.config, for SYS010 (#2828). */

package/src/lint/rules/op/ops019-workspace-op-target.ts

@@ -0,0 +1,89 @@
+/**
+ * OPS019: workspace-op-target (#2554, #2524 D17, ws-030). The design named
+ * this check OPS014; that id was already the ConvergeOp rule-table refusal,
+ * so it took the next free one.
+ *
+ * `chant workspace run` names its work as `<member>/<op>` targets. Before
+ * anything runs, every target is checked against the composed graph: each
+ * member's root, read under that member's own toolchain, with its Ops among
+ * its entities. A target fails when its member is not in the graph (not a
+ * `chant` member, or its read failed) or when the member declares no Op of
+ * that name.
+ *
+ * It is a {@link CrossRootCheck} (#1939), so only `runCrossRootChecks` runs
+ * it, and `chant build`, `chant lint` and a plain project never do.
+ */
+import type { CrossRootCheck, PostSynthDiagnostic } from "../../post-synth";
+import { isOpEntity } from "./support";
+
+export const OPS019_ID = "OPS019";
+
+/** One `<member>/<op>` target. */
+export interface WorkspaceOpTarget {
+  member: string;
+  op: string;
+}
+
+/**
+ * Split `<member>/<op>` at its first `/`. A member name has no `/` (the
+ * declaration's name pattern rules it out). Returns null for a string with no
+ * `/`, or an empty member or op.
+ */
+export function parseWorkspaceOpTarget(text: string): WorkspaceOpTarget | null {
+  const at = text.indexOf("/");
+  if (at <= 0 || at === text.length - 1) return null;
+  return { member: text.slice(0, at), op: text.slice(at + 1) };
+}
+
+export const formatWorkspaceOpTarget = (t: WorkspaceOpTarget): string => `${t.member}/${t.op}`;
+
+function opName(entity: unknown): string | undefined {
+  const props = (entity as { props?: { name?: unknown } } | null)?.props;
+  return typeof props?.name === "string" ? props.name : undefined;
+}
+
+/** The OPS019 check over `targets`. */
+export function ops019Check(targets: readonly WorkspaceOpTarget[]): CrossRootCheck {
+  return {
+    id: OPS019_ID,
+    description: "A workspace Op target names a member in the composed graph and an Op that member declares",
+    scope: "cross-root",
+    check(ctx) {
+      const diagnostics: PostSynthDiagnostic[] = [];
+      const opsByRoot = new Map<string, Set<string>>();
+      for (const e of ctx.entities) {
+        if (!isOpEntity(e.entity)) continue;
+        const name = opName(e.entity) ?? e.name;
+        const set = opsByRoot.get(e.root) ?? new Set<string>();
+        set.add(name);
+        opsByRoot.set(e.root, set);
+      }
+      for (const t of targets) {
+        const target = formatWorkspaceOpTarget(t);
+        if (!ctx.root(t.member)) {
+          diagnostics.push({
+            checkId: OPS019_ID,
+            severity: "error",
+            message: `${target}: member "${t.member}" is not in the composed graph. A workspace Op runs in a chant member whose graph could be read.`,
+            missing: { kind: "member", scope: t.member },
+          });
+          continue;
+        }
+        const ops = opsByRoot.get(t.member) ?? new Set<string>();
+        if (!ops.has(t.op)) {
+          const known = [...ops].sort();
+          diagnostics.push({
+            checkId: OPS019_ID,
+            severity: "error",
+            message:
+              `${target}: member "${t.member}" declares no Op named "${t.op}". ` +
+              (known.length > 0 ? `Its Ops: ${known.join(", ")}.` : "It declares no Ops."),
+            root: t.member,
+            missing: { kind: "op", scope: t.member },
+          });
+        }
+      }
+      return diagnostics;
+    },
+  };
+}

package/src/live-endpoint.ts

@@ -35,7 +35,7 @@
  * `--live --env floci` read against azure silently went to real Azure.
  */
 
-import { environmentEndpoint, type EnvironmentDeclaration } from "./config";
+import { environmentEndpoint, type EnvironmentDeclaration } from "./config-environments";
 import { emulatorsOf, endpointEnvVars, type EmulatorDeclaration } from "./op/emulator-lifecycle";
 
 /**

package/src/observation.test.ts

@@ -221,6 +221,31 @@ describe("observeEntities harness (#1201)", () => {
     });
   });
 
+  test("an absent entity's annotations are collected, and it stays in neither map (#4372)", async () => {
+    const result = await observeEntities(
+      [entity("a"), entity("b"), entity("c")],
+      adapterOf({
+        a: { present: meta() },
+        b: { absent: true, annotations: { planAction: "create", planAfterUnknown: ["id"] } },
+        c: { absent: true, annotations: {} },
+      }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["a"]);
+    expect(result.unobserved).toBeUndefined();
+    expect(result.annotations).toEqual({ b: { planAction: "create", planAfterUnknown: ["id"] } });
+    // Through the normalizer and a merge with another part, unchanged.
+    const merged = mergeObservations([normalizeObservation(result), normalizeObservation({ other: meta() })]);
+    expect(merged.annotations).toEqual({ b: { planAction: "create", planAfterUnknown: ["id"] } });
+    expect(Object.keys(merged.resources).sort()).toEqual(["a", "other"]);
+  });
+
+  test("no annotations means no annotations key, on the envelope and the normalized form", async () => {
+    const result = await observeEntities([entity("b")], adapterOf({ b: { absent: true } }));
+    expect("annotations" in result).toBe(false);
+    expect("annotations" in normalizeObservation(result)).toBe(false);
+    expect("annotations" in mergeObservations([normalizeObservation(result)])).toBe(false);
+  });
+
   test("collects the queried address from every variant — the absent one especially (#1620)", async () => {
     const result = await observeEntities(
       [entity("a"), entity("b"), entity("c")],

package/src/observation.ts

@@ -149,6 +149,31 @@ export interface ObservationResult {
    * before this field an observation gave it no way to tell them apart.
    */
   sources?: Record<string, string>;
+  /**
+   * Facts the read learned about an entity beside its verdict (#4372), keyed
+   * by chant entity name, as attribute name -> value. The case it exists for
+   * is a Terraform plan's planned create: the plan says the block will be
+   * created and which of its values stay unknown until apply, but the block
+   * has no row in the plan's prior state, so it is OBSERVED-ABSENT, and
+   * absence is spelled "in neither map". Without this map those facts had
+   * nowhere to go.
+   *
+   * Additive metadata over the tri-state, like {@link queried} and
+   * {@link sources}: classification never reads it, ownership never comes
+   * from it, and an entity with annotations and no `resources` row is still
+   * absent. A renderer or search carries the attributes onto the declared
+   * node (`carryAnnotations` in ./lifecycle/observe.ts), where they read like
+   * any other attribute without making the node present.
+   */
+  annotations?: Record<string, Record<string, unknown>>;
+  /**
+   * Which read answered each root, and why it fell back when it did (#4384
+   * follow-up), keyed by a lexicon-chosen root key (terraform uses
+   * `terraform.roots.<root>`). Structured beside {@link notes}, which say the
+   * same thing in prose: a consumer reads this field and never matches note
+   * text, so rewording a note cannot change what it reports.
+   */
+  rootReads?: Record<string, RootRead>;
   /**
    * Notices about the read as a whole, not about any one entity (#1265) —
    * "the ownership filter could not be applied on this surface" is the
@@ -169,6 +194,20 @@ export interface ObservationResult {
   stackExports?: Record<string, Record<string, unknown>>;
 }
 
+/**
+ * The read a root was asked for and the one that answered. `depth` is the read
+ * asked for (`"plan"` for a plan-depth root, `"live+plan"` for a live root at
+ * the plan depth). `fellBackTo` is set only when that read failed: the read that
+ * answered instead (`"live"` is live-plan alone, for a live root), or
+ * `"declared"` when none did.
+ * `reason` is a short machine-stable cause, not prose to match on.
+ */
+export interface RootRead {
+  depth: string;
+  fellBackTo?: "state" | "live" | "declared";
+  reason?: string;
+}
+
 /**
  * What `describeResources()` may return: the bare map (pre-#1089, still valid —
  * "I looked at everything") or the {@link ObservationResult} envelope.
@@ -183,6 +222,10 @@ export interface NormalizedObservation {
   queried: Record<string, string>;
   /** Which read answered, per entity name (#2267). Empty when the lexicon reported none. */
   sources: Record<string, string>;
+  /** Facts beside the verdict, per entity name (#4372). Absent when the lexicon reported none. */
+  annotations?: Record<string, Record<string, unknown>>;
+  /** Which read answered each root, structured. Absent when the lexicon reported none. */
+  rootReads?: Record<string, RootRead>;
   /** Run-level notices (#1265), distinct. Empty when the lexicon reported none. */
   notes: string[];
   /** Per-stack exports (#1279), keyed by stack name. Absent when the lexicon reported none. */
@@ -209,6 +252,8 @@ export function observation(
   notes?: string[],
   stackExports?: Record<string, Record<string, unknown>>,
   sources?: Record<string, string>,
+  annotations?: Record<string, Record<string, unknown>>,
+  rootReads?: Record<string, RootRead>,
 ): ObservationResult {
   return {
     observation: "v1",
@@ -216,6 +261,8 @@ export function observation(
     ...(unobserved && Object.keys(unobserved).length > 0 ? { unobserved } : {}),
     ...(queried && Object.keys(queried).length > 0 ? { queried } : {}),
     ...(sources && Object.keys(sources).length > 0 ? { sources } : {}),
+    ...(annotations && Object.keys(annotations).length > 0 ? { annotations } : {}),
+    ...(rootReads && Object.keys(rootReads).length > 0 ? { rootReads } : {}),
     ...(notes && notes.length > 0 ? { notes } : {}),
     ...(stackExports && Object.keys(stackExports).length > 0 ? { stackExports } : {}),
   };
@@ -236,6 +283,8 @@ export function normalizeObservation(value: DescribeResourcesResult | undefined)
       queried: value.queried ?? {},
       sources: value.sources ?? {},
       notes: [...new Set(value.notes ?? [])],
+      ...(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 } : {}),
     };
   }
@@ -287,11 +336,16 @@ export function mergeObservations(parts: Iterable<NormalizedObservation>): Norma
   // is one note (#1265).
   const notes = new Set<string>();
   const stackExports: Record<string, Record<string, unknown>> = {};
+  // Annotations (#4372) merge like `sources`: per entity, disjoint parts.
+  const annotations: Record<string, Record<string, unknown>> = {};
+  const rootReads: Record<string, RootRead> = {};
   for (const part of parts) {
     Object.assign(resources, part.resources);
     Object.assign(unobserved, part.unobserved);
     Object.assign(queried, part.queried);
     Object.assign(sources, part.sources);
+    Object.assign(annotations, part.annotations ?? {});
+    Object.assign(rootReads, part.rootReads ?? {});
     for (const n of part.notes) notes.add(n);
     Object.assign(stackExports, part.stackExports ?? {});
   }
@@ -304,6 +358,8 @@ export function mergeObservations(parts: Iterable<NormalizedObservation>): Norma
     queried,
     sources,
     notes: [...notes],
+    ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
+    ...(Object.keys(rootReads).length > 0 ? { rootReads } : {}),
     ...(Object.keys(stackExports).length > 0 ? { stackExports } : {}),
   };
 }
@@ -370,10 +426,14 @@ export interface DeclaredEntity {
  * issued against. The harness collects it into the result's `queried` map (and
  * onto the unobserved entry), so even an absent verdict — which records
  * nothing else — says where the provider was asked.
+ *
+ * An absent verdict may also carry `annotations` (#4372): attributes the read
+ * learned about the entity without finding it, collected into the result's
+ * `annotations` map. They never make it present.
  */
 export type EntityObservation =
   | { present: ResourceMetadata; queried?: string }
-  | { absent: true; queried?: string }
+  | { absent: true; queried?: string; annotations?: Record<string, unknown> }
   | { unobserved: { reason: UnobservedReason; detail?: string }; queried?: string };
 
 /** What a lexicon supplies to drive the harness. `Client` is its transport handle. */
@@ -463,6 +523,7 @@ export async function observeEntities<Client>(
   const resources: Record<string, ResourceMetadata> = {};
   const unobserved: Record<string, UnobservedEntity> = {};
   const queried: Record<string, string> = {};
+  const annotations: Record<string, Record<string, unknown>> = {};
   const run = adapter.concurrently ?? ((items, fn) => boundedConcurrently(items, fn));
 
   await run(declared, async (entity) => {
@@ -486,11 +547,14 @@ export async function observeEntities<Client>(
         ...result.unobserved,
         ...(result.queried ? { queried: result.queried } : {}),
       };
+    } else if (result.annotations && Object.keys(result.annotations).length > 0) {
+      // `absent`: the verdict records nothing — in neither map is how the
+      // contract spells absence — but its address, when the adapter supplied
+      // one, lands in `queried` (#1620) so the absence can explain itself, and
+      // what the read learned about it lands in `annotations` (#4372).
+      annotations[entity.name] = result.annotations;
     }
-    // `absent`: the verdict records nothing — in neither map is how the
-    // contract spells absence — but its address, when the adapter supplied
-    // one, lands in `queried` (#1620) so the absence can explain itself.
   });
 
-  return observation(resources, unobserved, queried);
+  return observation(resources, unobserved, queried, undefined, undefined, undefined, annotations);
 }

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

@@ -152,7 +152,8 @@ export const reviewAgentContract = activityContract(
     op: z.string(),
     changeSet: z.object({ digest: z.string(), entries: z.array(z.unknown()) }).passthrough().optional(),
     changeSetFile: z.string().optional(),
-    mode: z.enum(["comment", "report"]).optional(),
+    mode: z.enum(["comment", "report", "handoff"]).optional(),
+    dir: z.string().optional(),
     title: z.string().optional(),
     description: z.string().optional(),
     base: z.string().optional(),
@@ -162,13 +163,14 @@ export const reviewAgentContract = activityContract(
     timeout: z.number().positive().optional(),
   }),
   z.object({
-    mode: z.enum(["comment", "report"]),
+    mode: z.enum(["comment", "report", "handoff"]),
     risk: z.enum(["low", "medium", "high", "unknown"]),
     exitCode: z.number().nullable(),
     summary: z.string(),
     commentUrl: z.string().optional(),
     pullRequest: z.string().optional(),
     mergeRequest: z.string().optional(),
+    recordFile: z.string().optional(),
   }),
 );
 
@@ -265,6 +267,7 @@ export const workEvidenceContract = activityContract(
     title: z.string(),
     url: z.string().optional(),
     path: z.string().optional(),
+    ops: z.record(z.string(), z.unknown()).optional(),
     kind: z.string().optional(),
     cwd: z.string().optional(),
   }),

package/src/op/activities/index.ts

@@ -164,8 +164,8 @@ export type {
 // The review agent (#4299): a model reviews the change set against the pull
 // request's own text and posts one sticky note. Only the activity and its
 // marker are re-exported, since the registry collects every exported function.
-export { reviewAgent, reviewMarker } from "./review-agent";
-export type { ReviewAgentArgs, ReviewAgentResult, ReviewAgentMode, ReviewRisk } from "./review-agent";
+export { parseReviewResult, postReviewNote, readReviewRecord, REVIEW_DIR_ENV, REVIEW_MARKER_PREFIX, REVIEW_RECORD, reviewAgent, reviewMarker } from "./review-agent";
+export type { PostReviewNoteArgs, PostReviewNoteResult, ReviewAgentArgs, ReviewAgentResult, ReviewAgentMode, ReviewRecord, ReviewRisk } from "./review-agent";
 
 // The propose-only template upgrade (#2550). Loads the workspace code on first
 // call only, so importing this module loads nothing under `workspace/`.