@actuarial-ts/agents 0.15.0 → 0.16.0

package/src/review.ts

@@ -0,0 +1,1116 @@
+/**
+ * Trusted agent boundary for a complete analytical review.
+ *
+ * The model can select only opaque identifiers from a host-owned catalog. It
+ * cannot author a plan, formula, source location, financial definition, input
+ * payload or tenant id. The host resolves those identifiers, performs the
+ * calculation, and returns a current-process VerifiedReviewSnapshot together
+ * with an exact scope receipt. This module validates that receipt before
+ * projecting review evidence back to the model.
+ *
+ * Manual priors, factor overrides, selections, waivers and adopted ranges are
+ * separate judgment gates. They reuse createJudgmentChain so every adopted
+ * decision suspends, requires a rationale, reads actor identity from trusted
+ * request context and enters the compliance ledger.
+ */
+
+import {
+  canonicalJson,
+  fnv1a64,
+  isDiagnosticToken,
+  type AnalysisReference,
+  type JsonValue,
+} from "@actuarial-ts/core";
+import { analysisReferenceSchema } from "@actuarial-ts/data";
+import {
+  assertVerifiedReviewSnapshot,
+  reviewEvidenceLinkSchema,
+  type ReviewSnapshotReadiness,
+  type VerifiedReviewSnapshot,
+} from "@actuarial-ts/compliance";
+import { z } from "zod";
+import { AgentsError } from "./errors.js";
+import {
+  createJudgmentChain,
+  type CreateJudgmentChainOptions,
+  type JudgmentApplication,
+  type JudgmentChainWorkflow,
+  type JudgmentGateContext,
+} from "./judgment.js";
+import {
+  defineActuarialTool,
+  tenantOf,
+  type DefinedActuarialTool,
+  type ToolEnvelopeFailure,
+} from "./tools.js";
+
+// ---------------------------------------------------------------------------
+// Public limits and schemas
+
+export const REVIEW_AGENT_LIMITS = Object.freeze({
+  maximumPresets: 64,
+  maximumMethods: 64,
+  maximumAssumptions: 256,
+  maximumOptions: 128,
+  maximumJudgments: 128,
+  maximumCandidatesPerJudgment: 128,
+  maximumEligibilityItems: 640,
+  maximumReasonCodes: 64,
+  maximumAffectedCoordinates: 1_000,
+  maximumRemedies: 64,
+  maximumTextCharacters: 20_000,
+});
+
+const token = z
+  .string()
+  .max(REVIEW_AGENT_LIMITS.maximumTextCharacters)
+  .refine(isDiagnosticToken);
+const tag = z.string().regex(/^fnv1a64-jcs-v1:[0-9a-f]{16}$/);
+const text = z
+  .string()
+  .max(REVIEW_AGENT_LIMITS.maximumTextCharacters)
+  .refine((value) => value.trim().length > 0, "Expected nonblank text");
+const uniqueTokens = (maximum: number, minimum = 0) =>
+  z
+    .array(token)
+    .min(minimum)
+    .max(maximum)
+    .refine((values) => new Set(values).size === values.length, {
+      message: "Identifiers must be distinct",
+    });
+
+export const reviewAgentDiscoveryInputSchema = z
+  .object({ runPresetId: token })
+  .strict();
+
+export const reviewAgentExecutionInputSchema = z
+  .object({
+    runPresetId: token,
+    planId: token,
+    inputId: token,
+    methodIds: uniqueTokens(REVIEW_AGENT_LIMITS.maximumMethods, 1),
+    assumptionIds: uniqueTokens(REVIEW_AGENT_LIMITS.maximumAssumptions),
+    optionIds: uniqueTokens(REVIEW_AGENT_LIMITS.maximumOptions),
+  })
+  .strict();
+
+export type ReviewAgentDiscoveryInput = z.output<
+  typeof reviewAgentDiscoveryInputSchema
+>;
+export type ReviewAgentExecutionInput = z.output<
+  typeof reviewAgentExecutionInputSchema
+>;
+
+export const REVIEW_AGENT_ELIGIBILITY_STATUSES = [
+  "supported",
+  "supported-with-warnings",
+  "requires-input",
+  "unsupported",
+] as const;
+export type ReviewAgentEligibilityStatus =
+  (typeof REVIEW_AGENT_ELIGIBILITY_STATUSES)[number];
+export const REVIEW_AGENT_SUBJECT_KINDS = [
+  "plan",
+  "input",
+  "method",
+  "assumption",
+  "option",
+] as const;
+export type ReviewAgentSubjectKind =
+  (typeof REVIEW_AGENT_SUBJECT_KINDS)[number];
+
+export interface ReviewAgentEligibility {
+  readonly kind: ReviewAgentSubjectKind;
+  readonly id: string;
+  readonly status: ReviewAgentEligibilityStatus;
+  readonly reasonCodes: readonly string[];
+  readonly affectedCoordinates: readonly string[];
+  readonly remedies: readonly string[];
+}
+
+export const reviewAgentEligibilitySchema: z.ZodType<ReviewAgentEligibility> = z
+  .object({
+    kind: z.enum(REVIEW_AGENT_SUBJECT_KINDS),
+    id: token,
+    status: z.enum(REVIEW_AGENT_ELIGIBILITY_STATUSES),
+    reasonCodes: uniqueTokens(REVIEW_AGENT_LIMITS.maximumReasonCodes),
+    affectedCoordinates: z
+      .array(text)
+      .max(REVIEW_AGENT_LIMITS.maximumAffectedCoordinates),
+    remedies: z.array(text).max(REVIEW_AGENT_LIMITS.maximumRemedies),
+  })
+  .strict();
+
+export const REVIEW_AGENT_JUDGMENT_KINDS = [
+  "manual-prior",
+  "factor-override",
+  "manual-selection",
+  "requirement-waiver",
+  "adopted-range",
+] as const;
+export type ReviewAgentJudgmentKind =
+  (typeof REVIEW_AGENT_JUDGMENT_KINDS)[number];
+
+export interface ReviewAgentCatalogItem {
+  readonly id: string;
+  readonly label: string;
+}
+
+export interface ReviewAgentMethod extends ReviewAgentCatalogItem {
+  /** Exact node and operation which must occur in the returned review plan. */
+  readonly nodeId: string;
+  readonly operation: string;
+}
+
+export interface ReviewAgentAssumption extends ReviewAgentCatalogItem {
+  readonly reference: AnalysisReference;
+}
+
+export interface ReviewAgentJudgmentDescriptor {
+  readonly id: string;
+  readonly kind: ReviewAgentJudgmentKind;
+  readonly targetId: string;
+  readonly candidateIds: readonly string[];
+}
+
+export interface ReviewAgentPresetInspectionInput {
+  readonly tenantId: string;
+  readonly runPresetId: string;
+  readonly presetVersion: string;
+}
+
+export interface ReviewAgentPresetExecutionInput
+  extends ReviewAgentPresetInspectionInput {
+  readonly requestIdentity: string;
+  readonly planId: string;
+  readonly inputId: string;
+  readonly methodIds: readonly string[];
+  readonly assumptionIds: readonly string[];
+  readonly optionIds: readonly string[];
+}
+
+export interface ReviewAgentExecutionScope
+  extends ReviewAgentPresetExecutionInput {}
+
+export interface ReviewAgentExecutionReceipt {
+  readonly scope: ReviewAgentExecutionScope;
+  /** Must retain its current-process authenticity brand. Copies are refused. */
+  readonly snapshot: VerifiedReviewSnapshot;
+}
+
+export interface ReviewAgentRunPreset {
+  readonly id: string;
+  readonly version: string;
+  readonly label: string;
+  readonly plan: {
+    readonly id: string;
+    readonly reference: AnalysisReference;
+  };
+  readonly input: {
+    readonly id: string;
+    /** Exact input/scope reference which must occur in the verified run. */
+    readonly reference: AnalysisReference;
+  };
+  readonly profile: { readonly id: string; readonly version: string };
+  readonly methods: readonly ReviewAgentMethod[];
+  readonly assumptions: readonly ReviewAgentAssumption[];
+  readonly options: readonly ReviewAgentCatalogItem[];
+  readonly judgments: readonly ReviewAgentJudgmentDescriptor[];
+  /** Returns one contextual eligibility item for every exposed catalog item. */
+  readonly inspect: (
+    input: ReviewAgentPresetInspectionInput,
+  ) => Promise<readonly ReviewAgentEligibility[]>;
+  readonly execute: (
+    input: ReviewAgentPresetExecutionInput,
+  ) => Promise<ReviewAgentExecutionReceipt>;
+}
+
+// ---------------------------------------------------------------------------
+// Result contracts
+
+const failureSchema = z
+  .object({
+    success: z.literal(false),
+    error: z.object({ code: z.string(), message: z.string() }).strict(),
+  })
+  .strict();
+const catalogItemSchema = z.object({ id: token, label: text }).strict();
+const methodSchema = catalogItemSchema
+  .extend({ nodeId: token, operation: token })
+  .strict();
+const judgmentDescriptorSchema = z
+  .object({
+    id: token,
+    kind: z.enum(REVIEW_AGENT_JUDGMENT_KINDS),
+    targetId: token,
+    candidateIds: uniqueTokens(
+      REVIEW_AGENT_LIMITS.maximumCandidatesPerJudgment,
+    ),
+  })
+  .strict();
+
+export const reviewAgentDiscoveryResultSchema = z.union([
+  z
+    .object({
+      success: z.literal(true),
+      data: z
+        .object({
+          runPresetId: token,
+          presetVersion: token,
+          label: text,
+          planId: token,
+          inputId: token,
+          profile: z.object({ id: token, version: token }).strict(),
+          methods: z.array(methodSchema).max(REVIEW_AGENT_LIMITS.maximumMethods),
+          assumptions: z
+            .array(catalogItemSchema)
+            .max(REVIEW_AGENT_LIMITS.maximumAssumptions),
+          options: z
+            .array(catalogItemSchema)
+            .max(REVIEW_AGENT_LIMITS.maximumOptions),
+          judgments: z
+            .array(judgmentDescriptorSchema)
+            .max(REVIEW_AGENT_LIMITS.maximumJudgments),
+          eligibility: z
+            .array(reviewAgentEligibilitySchema)
+            .max(REVIEW_AGENT_LIMITS.maximumEligibilityItems),
+        })
+        .strict(),
+    })
+    .strict(),
+  failureSchema,
+]);
+
+const readinessCheckSchema = z
+  .object({
+    id: text,
+    status: z.enum(["satisfied", "unresolved", "waived", "not-applicable"]),
+    message: text,
+    node: text.nullable(),
+    coordinates: z.array(text).max(1_000),
+    evidence: z.array(reviewEvidenceLinkSchema).max(1_024).optional(),
+    facet: z.enum(["validation", "selection", "review"]).optional(),
+  })
+  .strict();
+const readinessFacetsSchema = z
+  .object({
+    calculation: z.enum(["satisfied", "unresolved"]),
+    validation: z.enum(["satisfied", "unresolved", "not-applicable"]),
+    selection: z.enum(["satisfied", "unresolved", "not-applicable"]),
+    review: z.enum(["satisfied", "unresolved", "not-applicable"]),
+    externalRelease: z.literal("not-reported"),
+  })
+  .strict();
+const readinessSchema: z.ZodType<ReviewSnapshotReadiness> = z
+  .object({
+    status: z.enum(["requirements-satisfied", "unresolved"]),
+    checks: z.array(readinessCheckSchema),
+    assurance: z.enum([
+      "declared-minimum-requirements-only",
+      "caller-defined-versioned-profile",
+    ]),
+    stage: z
+      .enum(["exploratory", "calculated", "validated", "selected", "published"])
+      .optional(),
+    facets: readinessFacetsSchema.optional(),
+  })
+  .strict();
+
+export const reviewAgentExecutionResultSchema = z.union([
+  z
+    .object({
+      success: z.literal(true),
+      data: z
+        .object({
+          runPresetId: token,
+          presetVersion: token,
+          requestIdentity: tag,
+          planId: token,
+          inputId: token,
+          methodIds: z.array(token).max(REVIEW_AGENT_LIMITS.maximumMethods),
+          assumptionIds: z
+            .array(token)
+            .max(REVIEW_AGENT_LIMITS.maximumAssumptions),
+          optionIds: z.array(token).max(REVIEW_AGENT_LIMITS.maximumOptions),
+          snapshot: z
+            .object({
+              id: text,
+              version: text,
+              reference: analysisReferenceSchema,
+              profile: z.object({ id: text, version: text }).strict(),
+              readiness: readinessSchema,
+              limitations: z.array(
+                z
+                  .object({
+                    id: text,
+                    disposition: z.enum(["unresolved", "accepted"]),
+                  })
+                  .strict(),
+              ),
+              findingCodes: z.array(text),
+              assurance: z
+                .object({
+                  frozen: z.literal(true),
+                  review: z.literal("not-attested"),
+                  publication: z.literal("not-reported"),
+                })
+                .strict(),
+            })
+            .strict(),
+        })
+        .strict(),
+    })
+    .strict(),
+  failureSchema,
+]);
+
+export type ReviewAgentDiscoverySuccess = Extract<
+  z.output<typeof reviewAgentDiscoveryResultSchema>,
+  { success: true }
+>;
+export type ReviewAgentExecutionSuccess = Extract<
+  z.output<typeof reviewAgentExecutionResultSchema>,
+  { success: true }
+>;
+
+// ---------------------------------------------------------------------------
+// Catalog validation
+
+interface OwnedPreset {
+  readonly id: string;
+  readonly version: string;
+  readonly label: string;
+  readonly plan: { readonly id: string; readonly reference: AnalysisReference };
+  readonly input: { readonly id: string; readonly reference: AnalysisReference };
+  readonly profile: { readonly id: string; readonly version: string };
+  readonly methods: readonly ReviewAgentMethod[];
+  readonly assumptions: readonly ReviewAgentAssumption[];
+  readonly options: readonly ReviewAgentCatalogItem[];
+  readonly judgments: readonly ReviewAgentJudgmentDescriptor[];
+  readonly inspect: ReviewAgentRunPreset["inspect"];
+  readonly execute: ReviewAgentRunPreset["execute"];
+}
+
+const presetMetadataSchema = z
+  .object({
+    id: token,
+    version: token,
+    label: text,
+    plan: z.object({ id: token, reference: analysisReferenceSchema }).strict(),
+    input: z.object({ id: token, reference: analysisReferenceSchema }).strict(),
+    profile: z.object({ id: token, version: token }).strict(),
+    methods: z
+      .array(methodSchema)
+      .min(1)
+      .max(REVIEW_AGENT_LIMITS.maximumMethods),
+    assumptions: z
+      .array(catalogItemSchema.extend({ reference: analysisReferenceSchema }).strict())
+      .max(REVIEW_AGENT_LIMITS.maximumAssumptions),
+    options: z
+      .array(catalogItemSchema)
+      .max(REVIEW_AGENT_LIMITS.maximumOptions),
+    judgments: z
+      .array(judgmentDescriptorSchema)
+      .max(REVIEW_AGENT_LIMITS.maximumJudgments),
+  })
+  .strict();
+
+function distinct(values: readonly string[], message: string): void {
+  if (new Set(values).size !== values.length)
+    throw new AgentsError("BAD_REVIEW_CATALOG", message);
+}
+
+function ownPreset(value: ReviewAgentRunPreset): OwnedPreset {
+  if (typeof value?.inspect !== "function" || typeof value?.execute !== "function")
+    throw new AgentsError(
+      "BAD_REVIEW_CATALOG",
+      "Every review preset requires host inspect and execute functions",
+    );
+  const parsed = presetMetadataSchema.safeParse({
+    id: value.id,
+    version: value.version,
+    label: value.label,
+    plan: value.plan,
+    input: value.input,
+    profile: value.profile,
+    methods: value.methods,
+    assumptions: value.assumptions,
+    options: value.options,
+    judgments: value.judgments,
+  });
+  if (!parsed.success)
+    throw new AgentsError(
+      "BAD_REVIEW_CATALOG",
+      `Invalid review preset: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`,
+    );
+  const metadata = parsed.data;
+  distinct(metadata.methods.map((item) => item.id), `Preset ${metadata.id} has duplicate method IDs`);
+  distinct(metadata.methods.map((item) => item.nodeId), `Preset ${metadata.id} maps two methods to one node`);
+  distinct(metadata.assumptions.map((item) => item.id), `Preset ${metadata.id} has duplicate assumption IDs`);
+  distinct(
+    metadata.assumptions.map((item) => canonicalJson(item.reference)),
+    `Preset ${metadata.id} maps more than one assumption ID to the same reference`,
+  );
+  distinct(metadata.options.map((item) => item.id), `Preset ${metadata.id} has duplicate option IDs`);
+  distinct(metadata.judgments.map((item) => item.id), `Preset ${metadata.id} has duplicate judgment IDs`);
+  for (const assumption of metadata.assumptions)
+    if (assumption.reference.kind !== "assumption")
+      throw new AgentsError(
+        "BAD_REVIEW_CATALOG",
+        `Preset ${metadata.id} assumption ${assumption.id} must carry an assumption reference`,
+      );
+  if (metadata.plan.reference.kind !== "result")
+    throw new AgentsError(
+      "BAD_REVIEW_CATALOG",
+      `Preset ${metadata.id} plan reference must be a result reference`,
+    );
+  return Object.freeze({
+    ...metadata,
+    methods: Object.freeze(metadata.methods.map((item) => Object.freeze(item))),
+    assumptions: Object.freeze(
+      metadata.assumptions.map((item) => Object.freeze(item)),
+    ),
+    options: Object.freeze(metadata.options.map((item) => Object.freeze(item))),
+    judgments: Object.freeze(
+      metadata.judgments.map((item) => Object.freeze(item)),
+    ),
+    inspect: value.inspect,
+    execute: value.execute,
+  });
+}
+
+function catalogOf(values: readonly ReviewAgentRunPreset[]): Map<string, OwnedPreset> {
+  if (!Array.isArray(values) || values.length === 0 || values.length > REVIEW_AGENT_LIMITS.maximumPresets)
+    throw new AgentsError(
+      "BAD_REVIEW_CATALOG",
+      "Review tools require a nonempty bounded preset catalog",
+    );
+  const result = new Map<string, OwnedPreset>();
+  for (const raw of values) {
+    const preset = ownPreset(raw);
+    if (result.has(preset.id))
+      throw new AgentsError(
+        "BAD_REVIEW_CATALOG",
+        `Duplicate review preset ${preset.id}`,
+      );
+    result.set(preset.id, preset);
+  }
+  return result;
+}
+
+function subjectKey(kind: ReviewAgentSubjectKind, id: string): string {
+  return `${kind}\u0000${id}`;
+}
+
+function expectedSubjects(preset: OwnedPreset): Set<string> {
+  return new Set([
+    subjectKey("plan", preset.plan.id),
+    subjectKey("input", preset.input.id),
+    ...preset.methods.map((item) => subjectKey("method", item.id)),
+    ...preset.assumptions.map((item) => subjectKey("assumption", item.id)),
+    ...preset.options.map((item) => subjectKey("option", item.id)),
+  ]);
+}
+
+async function inspectPreset(
+  preset: OwnedPreset,
+  tenantId: string,
+): Promise<readonly ReviewAgentEligibility[]> {
+  const parsed = z
+    .array(reviewAgentEligibilitySchema)
+    .max(REVIEW_AGENT_LIMITS.maximumEligibilityItems)
+    .safeParse(
+      await preset.inspect({
+        tenantId,
+        runPresetId: preset.id,
+        presetVersion: preset.version,
+      }),
+    );
+  if (!parsed.success)
+    throw new AgentsError(
+      "REVIEW_ELIGIBILITY_MISMATCH",
+      "Review preset returned malformed contextual eligibility",
+    );
+  const expected = expectedSubjects(preset);
+  const actual = parsed.data.map((item) => subjectKey(item.kind, item.id));
+  if (
+    new Set(actual).size !== actual.length ||
+    actual.length !== expected.size ||
+    actual.some((key) => !expected.has(key))
+  )
+    throw new AgentsError(
+      "REVIEW_ELIGIBILITY_MISMATCH",
+      "Review preset must return exactly one eligibility outcome for every exposed item",
+    );
+  const kindOrder = new Map(
+    REVIEW_AGENT_SUBJECT_KINDS.map((kind, index) => [kind, index]),
+  );
+  return [...parsed.data].sort(
+    (left, right) =>
+      kindOrder.get(left.kind)! - kindOrder.get(right.kind)! ||
+      left.id.localeCompare(right.id),
+  );
+}
+
+function sorted(values: readonly string[]): string[] {
+  return [...values].sort();
+}
+
+function exactMembers(left: readonly string[], right: readonly string[]): boolean {
+  return canonicalJson(sorted(left)) === canonicalJson(sorted(right));
+}
+
+function exactReference(left: AnalysisReference, right: AnalysisReference): boolean {
+  return canonicalJson(left) === canonicalJson(right);
+}
+
+function requestIdentity(input: ReviewAgentExecutionInput): string {
+  return `fnv1a64-jcs-v1:${fnv1a64(
+    canonicalJson({
+      ...input,
+      methodIds: sorted(input.methodIds),
+      assumptionIds: sorted(input.assumptionIds),
+      optionIds: sorted(input.optionIds),
+    }),
+  )}`;
+}
+
+function selectedEligibility(
+  eligibility: readonly ReviewAgentEligibility[],
+  input: ReviewAgentExecutionInput,
+): readonly ReviewAgentEligibility[] {
+  const selected = new Set([
+    subjectKey("plan", input.planId),
+    subjectKey("input", input.inputId),
+    ...input.methodIds.map((id) => subjectKey("method", id)),
+    ...input.assumptionIds.map((id) => subjectKey("assumption", id)),
+    ...input.optionIds.map((id) => subjectKey("option", id)),
+  ]);
+  return eligibility.filter((item) => selected.has(subjectKey(item.kind, item.id)));
+}
+
+function assertAllowedRequest(
+  preset: OwnedPreset,
+  input: ReviewAgentExecutionInput,
+): void {
+  if (input.planId !== preset.plan.id || input.inputId !== preset.input.id)
+    throw new AgentsError(
+      "REVIEW_REQUEST_MISMATCH",
+      "The requested plan or input does not belong to the selected preset",
+    );
+  const allowedMethods = new Set(preset.methods.map((item) => item.id));
+  const allowedAssumptions = new Set(preset.assumptions.map((item) => item.id));
+  const allowedOptions = new Set(preset.options.map((item) => item.id));
+  if (input.methodIds.some((id) => !allowedMethods.has(id)))
+    throw new AgentsError(
+      "UNAPPROVED_REVIEW_METHOD",
+      "One or more requested methods are not approved by the selected preset",
+    );
+  if (input.assumptionIds.some((id) => !allowedAssumptions.has(id)))
+    throw new AgentsError(
+      "UNAPPROVED_REVIEW_ASSUMPTION",
+      "One or more requested assumptions are not approved by the selected preset",
+    );
+  if (input.optionIds.some((id) => !allowedOptions.has(id)))
+    throw new AgentsError(
+      "UNAPPROVED_REVIEW_OPTION",
+      "One or more requested options are not approved by the selected preset",
+    );
+}
+
+function assertReceipt(
+  preset: OwnedPreset,
+  request: ReviewAgentPresetExecutionInput,
+  receipt: ReviewAgentExecutionReceipt,
+): VerifiedReviewSnapshot {
+  if (receipt === null || typeof receipt !== "object" || Array.isArray(receipt))
+    throw new AgentsError(
+      "REVIEW_EXECUTION_MISMATCH",
+      "Review executor returned a malformed receipt",
+    );
+  const scopeField = Object.getOwnPropertyDescriptor(receipt, "scope");
+  const snapshotField = Object.getOwnPropertyDescriptor(receipt, "snapshot");
+  if (
+    ![Object.prototype, null].includes(Object.getPrototypeOf(receipt)) ||
+    Reflect.ownKeys(receipt).some(
+      (key) => typeof key !== "string" || !["scope", "snapshot"].includes(key),
+    ) ||
+    !scopeField?.enumerable ||
+    !("value" in scopeField) ||
+    !snapshotField?.enumerable ||
+    !("value" in snapshotField)
+  )
+    throw new AgentsError(
+      "REVIEW_EXECUTION_MISMATCH",
+      "Review executor receipt must contain only scope and snapshot data fields",
+    );
+  const scope = z
+    .object({
+      tenantId: token,
+      runPresetId: token,
+      presetVersion: token,
+      requestIdentity: tag,
+      planId: token,
+      inputId: token,
+      methodIds: uniqueTokens(REVIEW_AGENT_LIMITS.maximumMethods, 1),
+      assumptionIds: uniqueTokens(REVIEW_AGENT_LIMITS.maximumAssumptions),
+      optionIds: uniqueTokens(REVIEW_AGENT_LIMITS.maximumOptions),
+    })
+    .strict()
+    .safeParse(scopeField.value);
+  if (!scope.success || canonicalJson(scope.data) !== canonicalJson(request))
+    throw new AgentsError(
+      "REVIEW_EXECUTION_MISMATCH",
+      "Review executor result is bound to another tenant, request, definition or preset",
+    );
+  try {
+    assertVerifiedReviewSnapshot(snapshotField.value);
+  } catch {
+    throw new AgentsError(
+      "REVIEW_EXECUTION_MISMATCH",
+      "Review executor must return an authentic current-process verified snapshot",
+    );
+  }
+  const snapshot = snapshotField.value as VerifiedReviewSnapshot;
+  if (
+    snapshot.profile.id !== preset.profile.id ||
+    snapshot.profile.version !== preset.profile.version ||
+    !exactReference(
+      snapshot.run.document.analysisReview.run.plan.reference,
+      preset.plan.reference,
+    )
+  )
+    throw new AgentsError(
+      "REVIEW_EXECUTION_MISMATCH",
+      "Verified snapshot belongs to another review plan or profile",
+    );
+  const indexedReferences = snapshot.run.document.analysisReview.referenceIndex.definitions.map(
+    (entry) => entry.reference,
+  );
+  if (!indexedReferences.some((reference) => exactReference(reference, preset.input.reference)))
+    throw new AgentsError(
+      "REVIEW_EXECUTION_MISMATCH",
+      "Verified snapshot does not contain the exact approved input reference",
+    );
+  const methods = request.methodIds.map(
+    (id) => preset.methods.find((item) => item.id === id)!,
+  );
+  const planNodes = snapshot.run.document.analysisReview.run.plan.plan.nodes;
+  if (
+    methods.some(
+      (method) =>
+        !planNodes.some(
+          (node) =>
+            node.id === method.nodeId && node.operation === method.operation,
+        ),
+    )
+  )
+    throw new AgentsError(
+      "REVIEW_EXECUTION_MISMATCH",
+      "Verified snapshot is missing an exact approved method node",
+    );
+  const requestedAssumptions = request.assumptionIds.map(
+    (id) => preset.assumptions.find((item) => item.id === id)!.reference,
+  );
+  if (
+    !exactMembers(
+      snapshot.profile.assumptions.map((reference) => canonicalJson(reference)),
+      requestedAssumptions.map((reference) => canonicalJson(reference)),
+    )
+  )
+    throw new AgentsError(
+      "REVIEW_EXECUTION_MISMATCH",
+      "Verified snapshot assumptions do not exactly match the approved request",
+    );
+  return snapshot;
+}
+
+// ---------------------------------------------------------------------------
+// Discovery and execution tools
+
+export interface CreateReviewAgentToolsInput {
+  readonly runPresets: readonly ReviewAgentRunPreset[];
+  readonly discoveryId?: string;
+  readonly executionId?: string;
+  readonly tenantContextKey?: string;
+}
+
+export interface ReviewAgentTools {
+  readonly discover: DefinedActuarialTool<
+    z.input<typeof reviewAgentDiscoveryInputSchema>,
+    z.output<typeof reviewAgentDiscoveryResultSchema>
+  >;
+  readonly execute: DefinedActuarialTool<
+    z.input<typeof reviewAgentExecutionInputSchema>,
+    z.output<typeof reviewAgentExecutionResultSchema>
+  >;
+}
+
+/** Builds the paired read-only tools over one immutable host catalog. */
+export function createReviewAgentTools(
+  input: CreateReviewAgentToolsInput,
+): ReviewAgentTools {
+  if (input === null || typeof input !== "object" || Array.isArray(input))
+    throw new AgentsError(
+      "BAD_REVIEW_CATALOG",
+      "Review tool options must be an object",
+    );
+  for (const [name, value] of [
+    ["discoveryId", input.discoveryId],
+    ["executionId", input.executionId],
+    ["tenantContextKey", input.tenantContextKey],
+  ] as const)
+    if (value !== undefined && !isDiagnosticToken(value))
+      throw new AgentsError(
+        "BAD_REVIEW_CATALOG",
+        `Review tool ${name} must be a nonempty identifier when supplied`,
+      );
+  if (
+    input.discoveryId !== undefined &&
+    input.executionId !== undefined &&
+    input.discoveryId === input.executionId
+  )
+    throw new AgentsError(
+      "BAD_REVIEW_CATALOG",
+      "Review discovery and execution tool IDs must differ",
+    );
+  const catalog = catalogOf(input.runPresets);
+  const tenantKey = input.tenantContextKey ?? "projectId";
+
+  const discover = defineActuarialTool({
+    id: input.discoveryId ?? "discover-approved-review",
+    description:
+      "Discover one host-approved analytical review and its contextual eligibility",
+    kind: "read",
+    tenant: "required",
+    tenantKey,
+    inputSchema: reviewAgentDiscoveryInputSchema,
+    outputSchema: reviewAgentDiscoveryResultSchema,
+    execute: async (request, tenantId) => {
+      const preset = catalog.get(request.runPresetId);
+      if (!preset)
+        throw new AgentsError(
+          "UNKNOWN_REVIEW_PRESET",
+          `Unknown review preset ${request.runPresetId}`,
+        );
+      const eligibility = await inspectPreset(preset, tenantId);
+      return {
+        success: true as const,
+        data: {
+          runPresetId: preset.id,
+          presetVersion: preset.version,
+          label: preset.label,
+          planId: preset.plan.id,
+          inputId: preset.input.id,
+          profile: preset.profile,
+          methods: preset.methods.map((item) => ({ ...item })),
+          assumptions: preset.assumptions.map(({ id, label }) => ({ id, label })),
+          options: preset.options.map((item) => ({ ...item })),
+          judgments: preset.judgments.map((item) => ({
+            ...item,
+            candidateIds: [...item.candidateIds],
+          })),
+          eligibility: [...eligibility],
+        },
+      };
+    },
+  });
+
+  const execute = defineActuarialTool({
+    id: input.executionId ?? "run-approved-review",
+    description:
+      "Run a host-approved analytical review and return verified readiness evidence",
+    kind: "read",
+    tenant: "required",
+    tenantKey,
+    inputSchema: reviewAgentExecutionInputSchema,
+    outputSchema: reviewAgentExecutionResultSchema,
+    execute: async (raw, tenantId) => {
+      const preset = catalog.get(raw.runPresetId);
+      if (!preset)
+        throw new AgentsError(
+          "UNKNOWN_REVIEW_PRESET",
+          `Unknown review preset ${raw.runPresetId}`,
+        );
+      assertAllowedRequest(preset, raw);
+      const eligibility = await inspectPreset(preset, tenantId);
+      const unavailable = selectedEligibility(eligibility, raw).filter(
+        (item) => item.status === "requires-input" || item.status === "unsupported",
+      );
+      if (unavailable.length > 0)
+        throw new AgentsError(
+          "REVIEW_NOT_ELIGIBLE",
+          `Approved review cannot run because these selected items are ineligible: ${unavailable
+            .map((item) => `${item.kind}:${item.id}`)
+            .join(", ")}`,
+        );
+      const normalized: ReviewAgentExecutionInput = {
+        ...raw,
+        methodIds: sorted(raw.methodIds),
+        assumptionIds: sorted(raw.assumptionIds),
+        optionIds: sorted(raw.optionIds),
+      };
+      const executionInput: ReviewAgentPresetExecutionInput = {
+        tenantId,
+        runPresetId: preset.id,
+        presetVersion: preset.version,
+        requestIdentity: requestIdentity(normalized),
+        planId: normalized.planId,
+        inputId: normalized.inputId,
+        methodIds: normalized.methodIds,
+        assumptionIds: normalized.assumptionIds,
+        optionIds: normalized.optionIds,
+      };
+      const receipt = await preset.execute(executionInput);
+      const snapshot = assertReceipt(preset, executionInput, receipt);
+      return {
+        success: true as const,
+        data: {
+          runPresetId: preset.id,
+          presetVersion: preset.version,
+          requestIdentity: executionInput.requestIdentity,
+          planId: preset.plan.id,
+          inputId: preset.input.id,
+          methodIds: [...executionInput.methodIds],
+          assumptionIds: [...executionInput.assumptionIds],
+          optionIds: [...executionInput.optionIds],
+          snapshot: {
+            id: snapshot.id,
+            version: snapshot.version,
+            reference: snapshot.reference,
+            profile: { id: snapshot.profile.id, version: snapshot.profile.version },
+            readiness: snapshot.readiness,
+            limitations: snapshot.limitations.map(({ id, disposition }) => ({
+              id,
+              disposition,
+            })),
+            findingCodes: [...new Set(snapshot.findings.map((item) => item.code))].sort(),
+            assurance: snapshot.assurance,
+          },
+        },
+      };
+    },
+  });
+
+  return Object.freeze({ discover, execute });
+}
+
+// ---------------------------------------------------------------------------
+// Human judgment wrapper
+
+export interface ReviewAgentJudgmentDecision {
+  readonly decision: "adopt" | "decline";
+  readonly candidateId: string | null;
+  readonly rationale: string;
+  readonly actor?: "actuary" | "agent";
+}
+
+export interface ReviewAgentJudgmentContext {
+  readonly tenantId: string;
+  readonly presetId: string;
+  readonly presetVersion: string;
+  readonly gateId: string;
+  readonly kind: ReviewAgentJudgmentKind;
+  readonly targetId: string;
+  readonly decisions: JudgmentGateContext["decisions"];
+  readonly trail: JudgmentGateContext["trail"];
+}
+
+export interface ReviewAgentJudgmentGateSpec {
+  readonly id: string;
+  readonly stage: string;
+  readonly presetId: string;
+  readonly presetVersion: string;
+  readonly kind: ReviewAgentJudgmentKind;
+  readonly targetId: string;
+  readonly allowedCandidateIds: readonly string[];
+  readonly gatherEvidence: (
+    context: ReviewAgentJudgmentContext,
+  ) =>
+    | Promise<{ readonly recommendation: string; readonly evidence: unknown }>
+    | { readonly recommendation: string; readonly evidence: unknown };
+  readonly applyDecision: (
+    context: ReviewAgentJudgmentContext,
+    decision: ReviewAgentJudgmentDecision,
+  ) => Promise<JudgmentApplication>;
+}
+
+export interface CreateReviewAgentJudgmentChainInput {
+  readonly id: string;
+  readonly gates: readonly ReviewAgentJudgmentGateSpec[];
+  readonly now: () => string;
+  readonly tenantContextKey?: string;
+  readonly onComplete?: CreateJudgmentChainOptions["onComplete"];
+}
+
+const judgmentDecisionSchema = z
+  .object({
+    decision: z.enum(["adopt", "decline"]),
+    candidateId: token.nullable(),
+    rationale: z.string(),
+    actor: z.enum(["actuary", "agent"]).optional(),
+  })
+  .strict();
+
+function judgmentContext(
+  gate: ReviewAgentJudgmentGateSpec,
+  context: JudgmentGateContext,
+  tenantKey: string,
+): ReviewAgentJudgmentContext {
+  return {
+    tenantId: tenantOf({ requestContext: context.requestContext }, tenantKey),
+    presetId: gate.presetId,
+    presetVersion: gate.presetVersion,
+    gateId: gate.id,
+    kind: gate.kind,
+    targetId: gate.targetId,
+    decisions: context.decisions,
+    trail: context.trail,
+  };
+}
+
+/**
+ * Creates a resumable review-judgment workflow. The fixed schema admits only
+ * an allowlisted candidate ID and a documented adopt/decline decision. The
+ * wrapper always records the review judgment in the ledger, even when the
+ * host application has no additional assumption entries to append.
+ */
+export function createReviewAgentJudgmentChain(
+  input: CreateReviewAgentJudgmentChainInput,
+): JudgmentChainWorkflow {
+  if (input === null || typeof input !== "object" || Array.isArray(input))
+    throw new AgentsError(
+      "BAD_REVIEW_JUDGMENT_CATALOG",
+      "Review judgment options must be an object",
+    );
+  const tenantKey = input.tenantContextKey ?? "projectId";
+  if (
+    !isDiagnosticToken(input.id) ||
+    !isDiagnosticToken(tenantKey) ||
+    typeof input.now !== "function"
+  )
+    throw new AgentsError(
+      "BAD_REVIEW_JUDGMENT_CATALOG",
+      "Review judgment chain requires an ID and host clock",
+    );
+  if (!Array.isArray(input.gates) || input.gates.length === 0 || input.gates.length > REVIEW_AGENT_LIMITS.maximumJudgments)
+    throw new AgentsError(
+      "BAD_REVIEW_JUDGMENT_CATALOG",
+      "Review judgment chain requires a nonempty bounded gate list",
+    );
+  if (new Set(input.gates.map((gate) => gate?.id)).size !== input.gates.length)
+    throw new AgentsError(
+      "BAD_REVIEW_JUDGMENT_CATALOG",
+      "Review judgment gate IDs must be distinct",
+    );
+  const gates = input.gates.map((gate) => {
+    const parsed = z
+      .object({
+        id: token,
+        stage: text,
+        presetId: token,
+        presetVersion: token,
+        kind: z.enum(REVIEW_AGENT_JUDGMENT_KINDS),
+        targetId: token,
+        allowedCandidateIds: uniqueTokens(
+          REVIEW_AGENT_LIMITS.maximumCandidatesPerJudgment,
+        ),
+      })
+      .strict()
+      .safeParse({
+        id: gate.id,
+        stage: gate.stage,
+        presetId: gate.presetId,
+        presetVersion: gate.presetVersion,
+        kind: gate.kind,
+        targetId: gate.targetId,
+        allowedCandidateIds: gate.allowedCandidateIds,
+      });
+    if (
+      !parsed.success ||
+      typeof gate.gatherEvidence !== "function" ||
+      typeof gate.applyDecision !== "function"
+    )
+      throw new AgentsError(
+        "BAD_REVIEW_JUDGMENT_CATALOG",
+        "Review judgment gates require valid metadata and host callbacks",
+      );
+    const owned = parsed.data;
+    return {
+      id: owned.id,
+      stage: owned.stage,
+      resumeSchema: judgmentDecisionSchema,
+      gatherEvidence: async (context: JudgmentGateContext) =>
+        gate.gatherEvidence(judgmentContext(gate, context, tenantKey)),
+      applyDecision: async (
+        context: JudgmentGateContext,
+        decision: ReviewAgentJudgmentDecision,
+      ): Promise<JudgmentApplication> => {
+        const adopting = decision.decision === "adopt";
+        if (
+          (adopting &&
+            (decision.candidateId === null ||
+              !owned.allowedCandidateIds.includes(decision.candidateId))) ||
+          (!adopting && decision.candidateId !== null)
+        )
+          throw new AgentsError(
+            "UNAPPROVED_REVIEW_JUDGMENT",
+            "Review judgment must adopt one approved candidate or decline without a candidate",
+          );
+        const trusted = judgmentContext(gate, context, tenantKey);
+        const application = await gate.applyDecision(trusted, decision);
+        const auditValue: JsonValue = {
+          presetId: owned.presetId,
+          presetVersion: owned.presetVersion,
+          kind: owned.kind,
+          targetId: owned.targetId,
+          decision: decision.decision,
+          candidateId: decision.candidateId,
+        };
+        return {
+          summary:
+            application.summary ??
+            (adopting
+              ? `adopted ${decision.candidateId}`
+              : `declined ${owned.targetId}`),
+          ledgerEntries: [
+            {
+              field: `review.judgment.${owned.kind}.${owned.targetId}`,
+              value: auditValue,
+              source: `review-agent-gate:${owned.id}`,
+            },
+            ...(application.ledgerEntries ?? []),
+          ],
+        };
+      },
+    };
+  });
+  return createJudgmentChain({
+    id: input.id,
+    gates,
+    now: input.now,
+    onComplete: input.onComplete,
+    requestContextSchema: z.object({ [tenantKey]: z.string().min(1) }),
+  });
+}
+
+/** Ready-to-run offline eval cases for the default review tool IDs. */
+export const REVIEW_AGENT_TOOL_SELECTION_CASES = Object.freeze([
+  {
+    id: "discover-approved-review",
+    prompt:
+      "Show which approved review methods and assumptions are eligible before calculating anything.",
+    expectTools: ["discover-approved-review"],
+  },
+  {
+    id: "run-approved-review",
+    prompt:
+      "Run the approved review I selected and return its verified readiness evidence.",
+    expectTools: ["run-approved-review"],
+  },
+] as const);
+
+export type ReviewAgentToolResult =
+  | ReviewAgentDiscoverySuccess
+  | ReviewAgentExecutionSuccess
+  | ToolEnvelopeFailure;