@intentius/chant 0.124.46 → 0.124.49

package/dist/lint/post-synth.d.ts

@@ -175,6 +175,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;
 }
 /**
  * A post-synthesis check that validates build output. Lexicons ship these as
@@ -196,8 +201,17 @@ 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 declare function isPostSynthCheck(value: unknown): value is PostSynthCheck;
 /**
  * Run a set of post-synthesis checks against a build result. `env` is threaded
@@ -214,4 +228,116 @@ export declare function runPostSynthChecks(checks: PostSynthCheck[], buildResult
     projectDir?: string;
     projectConfig?: Record<string, unknown>;
 }): PostSynthDiagnostic[];
+/**
+ * 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 declare function isCrossRootCheck(value: unknown): value is CrossRootCheck;
+/**
+ * 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 declare function createCrossRootContext(inputs: readonly CrossRootInput[], opts?: CrossRootOptions): CrossRootContext;
+/**
+ * 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 declare function runCrossRootChecks(checks: ReadonlyArray<CrossRootCheck | PostSynthCheck>, roots: readonly CrossRootInput[], opts?: CrossRootOptions): PostSynthDiagnostic[];
 //# sourceMappingURL=post-synth.d.ts.map

package/dist/lint/post-synth.d.ts.map

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

package/dist/lint/post-synth.js

@@ -36,13 +36,18 @@ export function getPrimaryOutput(output) {
 export function getAdditionalFiles(output) {
     return typeof output === "string" ? {} : (output.files ?? {});
 }
-/** 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) {
     return (typeof value === "object" &&
         value !== null &&
         typeof value.id === "string" &&
         typeof value.description === "string" &&
-        typeof value.check === "function");
+        typeof value.check === "function" &&
+        value.scope !== "cross-root");
 }
 /**
  * Run a set of post-synthesis checks against a build result. `env` is threaded
@@ -70,10 +75,87 @@ export function runPostSynthChecks(checks, buildResult, env, opts) {
     };
     const diagnostics = [];
     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.scope === "cross-root")
+            continue;
         diagnostics.push(...check.check(ctx));
     }
     return diagnostics;
 }
+/** Structural type guard for {@link CrossRootCheck}. */
+export function isCrossRootCheck(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.id === "string" &&
+        typeof value.description === "string" &&
+        typeof value.check === "function" &&
+        value.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, opts) {
+    const seen = new Set();
+    const roots = 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() {
+                return getDocs();
+            },
+        };
+    });
+    const byName = new Map(roots.map((r) => [r.root, r]));
+    let docs;
+    let entities;
+    return {
+        roots,
+        root: (name) => byName.get(name),
+        get docs() {
+            docs ?? (docs = roots.flatMap((r) => r.docs.map((d) => ({ ...d, root: r.root }))));
+            return docs;
+        },
+        get entities() {
+            entities ?? (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, roots, opts) {
+    const selected = checks.filter(isCrossRootCheck);
+    if (selected.length === 0)
+        return [];
+    const ctx = createCrossRootContext(roots, opts);
+    const diagnostics = [];
+    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/dist/lint/rules/op/index.d.ts

@@ -18,6 +18,7 @@ export { ops016 } from "./ops016-gate-resume.js";
 export { ops017, ops017Check, workspaceIdentityGates } from "./ops017-gate-alias.js";
 export { ops018 } from "./ops018-shell-image-digest.js";
 export { sys010, sys010Check } from "./sys010-key-over-plain-http.js";
+export { ops019Check, parseWorkspaceOpTarget, formatWorkspaceOpTarget, OPS019_ID, type WorkspaceOpTarget } from "./ops019-workspace-op-target.js";
 export interface CoreOpCheckOptions {
     /** `decide.backends` from the project's chant.config, for SYS010 (#2828). */
     decideBackends?: Record<string, Pick<DecideBackend, "url" | "key">>;

package/dist/lint/rules/op/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lint/rules/op/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AASvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEnE,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;IACpE,6GAA6G;IAC7G,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,kBAAuB,GAAG,cAAc,EAAE,CAE5E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lint/rules/op/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AASvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEnE,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAE/I,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;IACpE,6GAA6G;IAC7G,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,kBAAuB,GAAG,cAAc,EAAE,CAE5E"}

package/dist/lint/rules/op/index.js

@@ -24,6 +24,8 @@ export { ops016 } from "./ops016-gate-resume.js";
 export { ops017, ops017Check, workspaceIdentityGates } from "./ops017-gate-alias.js";
 export { ops018 } from "./ops018-shell-image-digest.js";
 export { sys010, sys010Check } from "./sys010-key-over-plain-http.js";
+// OPS019 (#2554) reads across members, so it is a cross-root check that only `chant workspace run` runs.
+export { ops019Check, parseWorkspaceOpTarget, formatWorkspaceOpTarget, OPS019_ID } from "./ops019-workspace-op-target.js";
 /**
  * Core's own post-synth checks over the Op model: OPS012, OPS013, OPS014,
  * OPS015, OPS016, OPS017 over the workspace's `identity.gates`, OPS018, and SYS010

package/dist/lint/rules/op/ops019-workspace-op-target.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 } from "../../post-synth.js";
+export declare 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 declare function parseWorkspaceOpTarget(text: string): WorkspaceOpTarget | null;
+export declare const formatWorkspaceOpTarget: (t: WorkspaceOpTarget) => string;
+/** The OPS019 check over `targets`. */
+export declare function ops019Check(targets: readonly WorkspaceOpTarget[]): CrossRootCheck;
+//# sourceMappingURL=ops019-workspace-op-target.d.ts.map

package/dist/lint/rules/op/ops019-workspace-op-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops019-workspace-op-target.d.ts","sourceRoot":"","sources":["../../../../src/lint/rules/op/ops019-workspace-op-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,kBAAkB,CAAC;AAG5E,eAAO,MAAM,SAAS,WAAW,CAAC;AAElC,kCAAkC;AAClC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAI7E;AAED,eAAO,MAAM,uBAAuB,MAAO,iBAAiB,KAAG,MAA+B,CAAC;AAO/F,uCAAuC;AACvC,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,cAAc,CA2CjF"}

package/dist/lint/rules/op/ops019-workspace-op-target.js

@@ -0,0 +1,63 @@
+import { isOpEntity } from "./support.js";
+export const OPS019_ID = "OPS019";
+/**
+ * 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) {
+    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) => `${t.member}/${t.op}`;
+function opName(entity) {
+    const props = entity?.props;
+    return typeof props?.name === "string" ? props.name : undefined;
+}
+/** The OPS019 check over `targets`. */
+export function ops019Check(targets) {
+    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 = [];
+            const opsByRoot = new Map();
+            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();
+                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();
+                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/dist/op/activities/activity-contracts.d.ts

@@ -134,7 +134,8 @@ export declare const reviewAgentContract: import("../index.js").ActivityContract
         entries: unknown[];
     } | undefined;
     changeSetFile?: string | undefined;
-    mode?: "comment" | "report" | undefined;
+    mode?: "comment" | "handoff" | "report" | undefined;
+    dir?: string | undefined;
     title?: string | undefined;
     description?: string | undefined;
     base?: string | undefined;
@@ -143,13 +144,14 @@ export declare const reviewAgentContract: import("../index.js").ActivityContract
     keyEnv?: string | undefined;
     timeout?: number | undefined;
 }, {
-    mode: "comment" | "report";
+    mode: "comment" | "handoff" | "report";
     risk: "high" | "low" | "medium" | "unknown";
     exitCode: number | null;
     summary: string;
     commentUrl?: string | undefined;
     pullRequest?: string | undefined;
     mergeRequest?: string | undefined;
+    recordFile?: string | undefined;
 }>;
 /**
  * The propose-only template upgrade (#2550, ws-032). `args` mirrors
@@ -237,6 +239,7 @@ export declare const workEvidenceContract: import("../index.js").ActivityContrac
     title: string;
     url?: string | undefined;
     path?: string | undefined;
+    ops?: Record<string, unknown> | undefined;
     kind?: string | undefined;
     cwd?: string | undefined;
 }, {
@@ -354,11 +357,11 @@ export declare const decideContract: import("../index.js").ActivityContract<{
     backends?: Record<string, {
         url: string;
         key?: {
+            env: string;
+        } | {
             capability: string;
             member?: string | undefined;
             env?: string | undefined;
-        } | {
-            env: string;
         } | undefined;
         timeoutMs?: number | undefined;
     }> | undefined;
@@ -447,11 +450,11 @@ export declare const factoryAskContract: import("../index.js").ActivityContract<
     backends?: Record<string, {
         url: string;
         key?: {
+            env: string;
+        } | {
             capability: string;
             member?: string | undefined;
             env?: string | undefined;
-        } | {
-            env: string;
         } | undefined;
         timeoutMs?: number | undefined;
     }> | undefined;

package/dist/op/activities/activity-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../../src/op/activities/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,eAAO,MAAM,yBAAyB;;SAGrC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;EAIjC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;EAmB5B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;EAgB7B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;SAGjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;EAUpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;EAuBpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;EAwB/B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;EA8B3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgClC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;EAkBhC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAIjC,CAAC;AAOF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;EAIpC,CAAC;AAEF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;EAI1C,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;EAIrC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAW/B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;EAWjC,CAAC;AAUF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6B1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;EAoBvC,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;EAWzC,CAAC;AAWF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAQ/B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;YAIhC,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAU9B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EASjC,CAAC"}
+{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../../src/op/activities/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,eAAO,MAAM,yBAAyB;;SAGrC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;EAIjC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;EAmB5B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;EAgB7B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;SAGjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;EAUpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;EAuBpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;EA0B/B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;EA8B3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgClC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;EAmBhC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAIjC,CAAC;AAOF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;EAIpC,CAAC;AAEF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;EAI1C,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;EAIrC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAW/B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;EAWjC,CAAC;AAUF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6B1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;EAoBvC,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;EAWzC,CAAC;AAWF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAQ/B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;YAIhC,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAU9B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EASjC,CAAC"}

package/dist/op/activities/activity-contracts.js

@@ -116,7 +116,8 @@ export const reviewAgentContract = activityContract("reviewAgent", z.strictObjec
     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(),
@@ -125,13 +126,14 @@ export const reviewAgentContract = activityContract("reviewAgent", z.strictObjec
     keyEnv: z.string().optional(),
     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(),
 }));
 /**
  * The propose-only template upgrade (#2550, ws-032). `args` mirrors
@@ -212,6 +214,7 @@ export const workEvidenceContract = activityContract("workEvidence", z.strictObj
     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(),
 }), z.object({

package/dist/op/activities/index.d.ts

@@ -38,8 +38,8 @@ export { lexiconUpgrade, isPinned, isRolling, severityToLabel, upgradeBranchName
 export type { LexiconUpgradeArgs, LexiconUpgradeResult, LexiconUpgradeMode, SupportedLexicon, SemverLabel, CheckPinnedFn, CheckRollingFn, GhRunner, ApplyBumpFn, } from "./lexicon-upgrade.js";
 export { predictBehaviour, behaviourFinding, behaviourFindingMarker, declaredEdgeCoverage, baseRefFrom, headRefFrom, noBaseRefMessage, noContributedRowsMessage, } from "./predict-behaviour.js";
 export type { PredictBehaviourArgs, BehaviourFindingArgs, BehaviourFindingResult, BehaviourFindingMode, BehaviourFindingDeps, BaseCheckout, } from "./predict-behaviour.js";
-export { reviewAgent, reviewMarker } from "./review-agent.js";
-export type { ReviewAgentArgs, ReviewAgentResult, ReviewAgentMode, ReviewRisk } from "./review-agent.js";
+export { parseReviewResult, postReviewNote, readReviewRecord, REVIEW_DIR_ENV, REVIEW_MARKER_PREFIX, REVIEW_RECORD, reviewAgent, reviewMarker } from "./review-agent.js";
+export type { PostReviewNoteArgs, PostReviewNoteResult, ReviewAgentArgs, ReviewAgentResult, ReviewAgentMode, ReviewRecord, ReviewRisk } from "./review-agent.js";
 export { proposeWorkspaceUpgrade } from "./propose-upgrade.js";
 export type { ProposeWorkspaceUpgradeArgs, ProposeWorkspaceUpgradeResult, ProposeUpgradeMode, CommandRunner, } from "./propose-upgrade.js";
 export { changeCoverage } from "./change-coverage.js";

package/dist/op/activities/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAQ9C,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,YAAY,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAK/C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5D,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC3J,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,YAAY,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACpJ,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC3F,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACzJ,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEjG,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAiB1F,OAAO,EACL,WAAW,EACX,aAAa,EACb,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEvH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC1E,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,WAAW,EACX,UAAU,EACV,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,WAAW,GACZ,MAAM,SAAS,CAAC;AAKjB,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE7F,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE5E,OAAO,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AACxG,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC3G,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEjH,OAAO,EACL,cAAc,EACd,QAAQ,EACR,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,cAAc,EACd,QAAQ,EACR,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,GACb,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,oBAAoB,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACrK,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAI9J,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,YAAY,EACV,2BAA2B,EAC3B,6BAA6B,EAC7B,kBAAkB,EAClB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAOlF,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGzD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC7G,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC"}

package/dist/op/activities/index.js

@@ -46,7 +46,7 @@ export { predictBehaviour, behaviourFinding, behaviourFindingMarker, declaredEdg
 // 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.js";
+export { parseReviewResult, postReviewNote, readReviewRecord, REVIEW_DIR_ENV, REVIEW_MARKER_PREFIX, REVIEW_RECORD, reviewAgent, reviewMarker } from "./review-agent.js";
 // The propose-only template upgrade (#2550). Loads the workspace code on first
 // call only, so importing this module loads nothing under `workspace/`.
 export { proposeWorkspaceUpgrade } from "./propose-upgrade.js";