@effect-agent/pr-review 0.1.0-beta.23 → 0.1.0-beta.25

package/src/internal/fan-out.ts

@@ -11,6 +11,7 @@ import {
 } from "effect-agent";
 import { Toolkit } from "effect/unstable/ai";
 
+import type { PriorReviewContext } from "./adjudication.ts";
 import { anchorViolation } from "./anchors.ts";
 import { boundedListReason, FailedReviewPass, ReviewAssurance } from "./coverage.ts";
 import { ChangedFileStatus, ChangedPath, type ChangedFile } from "./diff.ts";
@@ -25,6 +26,7 @@ import {
   WalkthroughEntry,
 } from "./review-agent.ts";
 import {
+  MAX_REPORTED_UNASSIGNED_EVIDENCE_SHARDS,
   MAX_REVIEW_UNITS,
   MAX_UNIT_EVIDENCE_SHARDS,
   MAX_UNIT_FILES,
@@ -32,13 +34,13 @@ import {
   planReviewUnits,
   rankAndDedupeConcerns,
   rankAndDedupeFindings,
+  ReviewDiscoveryPass,
   ReviewEvidenceShardId,
   ReviewPassId,
   ReviewRiskCategory,
+  ReviewUnit,
   ReviewUnitId,
-  type ReviewDiscoveryPass,
-  type ReviewUnit,
-  type ReviewUnitPlan,
+  ReviewUnitPlan,
 } from "./review-units.ts";
 
 // ---------------------------------------------------------------------------
@@ -173,8 +175,8 @@ export const confirmedFindingForPublication = (
 /**
  * Concern candidates need explicit paths internally to bind the claim to
  * scheduled evidence. The verifier receives the complete bounded unit so it
- * can use neighboring evidence to falsify the claim. The public ReviewConcern
- * remains path-free after the host confirms and projects it.
+ * can use neighboring evidence to falsify the claim. The host copies these
+ * validated paths onto a confirmed public concern for incremental continuity.
  */
 export class DiscoveredConcern extends Schema.Class<DiscoveredConcern>(
   "@effect-agent/pr-review/DiscoveredConcern",
@@ -189,6 +191,11 @@ const UnitPaths = Schema.Array(ChangedPath)
   .check(Schema.isMinLength(1))
   .check(Schema.isMaxLength(MAX_UNIT_FILES));
 
+/** Bounded prior-review context lines injected into discovery instructions. */
+const UnitContextLines = Schema.Array(Schema.String.check(Schema.isMaxLength(1_200))).check(
+  Schema.isMaxLength(20),
+);
+
 const RiskCategories = Schema.Array(ReviewRiskCategory).check(Schema.isMaxLength(6));
 const Candidates = Schema.Array(ReviewCandidate).check(Schema.isMaxLength(MAX_UNIT_CANDIDATES));
 const EvidenceShardIds = Schema.Array(ReviewEvidenceShardId)
@@ -224,6 +231,10 @@ export class FileReviewBrief extends Schema.Class<FileReviewBrief>(
   evidence: Schema.Array(FileReviewEvidence)
     .check(Schema.isMinLength(1))
     .check(Schema.isMaxLength(MAX_UNIT_EVIDENCE_SHARDS)),
+  /** Maintainer-adjudicated identities on this unit; do not re-raise. */
+  adjudicatedContext: Schema.optionalKey(UnitContextLines),
+  /** Prior-round findings on this unit's re-reviewed paths. */
+  priorFindingContext: Schema.optionalKey(UnitContextLines),
 }) {}
 
 /** Child output; phase-inapplicable collections must be empty. */
@@ -296,11 +307,25 @@ export const makeFileReviewerInstructions =
           ? `This is a fresh specialist discovery pass. Concentrate on these host-classified risks without relying on another pass: ${brief.riskCategories.join(", ")}.`
           : "This is a fresh specialist discovery pass. The host found no keyword-classified category, so independently scrutinize authentication/authorization, security boundaries, durability, concurrency, credentials, and external side effects rather than treating classification silence as low risk."
         : "This is the general discovery pass. Review broadly for correctness, security, concurrency, resource, API, and error-handling defects.";
+    const adjudicated = brief.adjudicatedContext ?? [];
+    const priorFindings = brief.priorFindingContext ?? [];
     return [
       ...common,
       focus,
+      ...(adjudicated.length === 0
+        ? []
+        : [
+            "A maintainer has adjudicated these previously raised items on this unit (disposition, reason). Do not re-raise them unless you have materially new evidence, and if you do, say explicitly what changed since the adjudication:",
+            ...adjudicated.map((line) => `- ${line}`),
+          ]),
+      ...(priorFindings.length === 0
+        ? []
+        : [
+            "A previous review round raised these findings on this unit's paths. For each, either confirm it still holds, state that it is fixed, or withdraw it; do not demand the opposite of that prior guidance without explicitly acknowledging the reversal:",
+            ...priorFindings.map((line) => `- ${line}`),
+          ]),
       "The discovery evidence array contains every complete shard in the unit. Review every entry and every shard of a multi-shard path. A later independent verifier, not you, decides which candidates publish.",
-      "When a non-anchored concern depends on one or more unit files, list 1-3 exact evidencePaths to bind the claim to scheduled evidence.",
+      "Every non-anchored concern must list 1-3 exact evidencePaths to bind the claim to scheduled evidence. Report one root concern once; never split it into differently worded restatements.",
       `Return ONLY JSON with phase "discovery", the exact workId/unitId, up to ${MAX_CHILD_FINDINGS} findings, up to ${MAX_CHILD_CONCERNS} concerns shaped as {concern, evidencePaths}, one factual file summary per path (<= ${MAX_WALKTHROUGH_SUMMARY_CHARS} chars), and an empty assessments array. Empty candidate arrays are valid; do not invent defects.`,
       'Each finding is {"path": <a unit file path>, "startLine": <integer, an R-marked new-file line>, "endLine": <integer, >= startLine, same file, R-marked>, "severity": <"blocking" | "important" | "nit">, "category": <OPTIONAL problem-kind label>, "title": <string, <= 120 chars>, "body": <string, why it matters and what to do>, "suggestion": <string, OPTIONAL: replacement source code for exactly lines startLine..endLine, ready to commit>}.',
       'Include "suggestion" only when you are confident the replacement compiles and preserves intent; its text must contain the full replacement source for every line in the range and nothing else — never prose describing the change, which belongs in "body".',
@@ -361,6 +386,11 @@ export interface FanOutPipelineOutcome {
   readonly plan: ReviewUnitPlan;
   /** Paths of units with an unsettled pass — retryable scope for the next run. */
   readonly unreviewedPaths: ReadonlyArray<string>;
+  /** Failed stages paired with the leftover paths they still own. */
+  readonly unreviewedPasses: ReadonlyArray<{
+    readonly stage: FailedReviewPass["stage"];
+    readonly paths: ReadonlyArray<string>;
+  }>;
   /** Total settled child turns across every scheduled pass. */
   readonly turns: number;
 }
@@ -372,6 +402,22 @@ export interface FanOutPipelineInput {
   readonly maxFindings?: number | undefined;
   /** Shared run budget observed by every child pass. */
   readonly budget?: RunBudgetHook<BudgetExceeded | BudgetAdapterError> | undefined;
+  /**
+   * Unchanged leftover paths from a prior failed pass. Those units retry only
+   * the recorded stages — no second general discovery on files nobody touched.
+   */
+  readonly retry?:
+    | {
+        readonly paths: ReadonlyArray<string>;
+        readonly stages: ReadonlyArray<FailedReviewPass["stage"]>;
+      }
+    | undefined;
+  /**
+   * Adjudicated identities and prior-round findings injected as discovery
+   * context on the units whose paths they touch. Context only — they never
+   * enter candidates or publication.
+   */
+  readonly priorContext?: PriorReviewContext | undefined;
 }
 
 const candidateOrdinal = (index: number): string => String(index + 1).padStart(3, "0");
@@ -587,6 +633,10 @@ interface UnitReviewOutcome {
   readonly requiredVerificationPasses: number;
   readonly completedVerificationPasses: number;
   readonly unreviewedPaths: ReadonlyArray<string>;
+  readonly unreviewedPasses: ReadonlyArray<{
+    readonly stage: FailedReviewPass["stage"];
+    readonly paths: ReadonlyArray<string>;
+  }>;
 }
 
 const reviewUnit = <Provider, ModelProvides, ModelRequires>(
@@ -605,6 +655,19 @@ const reviewUnit = <Provider, ModelProvides, ModelRequires>(
     let turns = 0;
     let completedGeneralPasses = 0;
     let completedSpecialistPasses = 0;
+    // Discovery-only context: adjudicated identities (path-free entries apply
+    // to every unit) and prior-round findings on this unit's paths. The
+    // verifier stays unbiased — it judges only the candidate claims and the
+    // bounded evidence.
+    const unitPaths = new Set(unit.paths);
+    const adjudicatedContext = (input.priorContext?.adjudicated ?? [])
+      .filter((entry) => entry.path === undefined || unitPaths.has(entry.path))
+      .map((entry) => entry.line)
+      .slice(0, 20);
+    const priorFindingContext = (input.priorContext?.priorFindings ?? [])
+      .filter((entry) => unitPaths.has(entry.path))
+      .map((entry) => entry.line)
+      .slice(0, 20);
     for (const pass of passes) {
       const stage = pass.perspective === "risk-specialist" ? "specialist" : "discovery";
       const brief = FileReviewBrief.make({
@@ -617,6 +680,8 @@ const reviewUnit = <Provider, ModelProvides, ModelRequires>(
         riskCategories: pass.riskCategories,
         candidates: [],
         evidence,
+        ...(adjudicatedContext.length === 0 ? {} : { adjudicatedContext }),
+        ...(priorFindingContext.length === 0 ? {} : { priorFindingContext }),
       });
       const outcome = yield* runReviewPass(binding, brief, input.budget);
       if (outcome._tag === "failed") {
@@ -697,6 +762,10 @@ const reviewUnit = <Provider, ModelProvides, ModelRequires>(
       requiredVerificationPasses,
       completedVerificationPasses,
       unreviewedPaths: failedPasses.length > 0 ? unit.paths : [],
+      unreviewedPasses: failedPasses.map((pass) => ({
+        stage: pass.stage,
+        paths: unit.paths,
+      })),
     } satisfies UnitReviewOutcome;
   });
 
@@ -737,6 +806,121 @@ const composeSummary = (plan: ReviewUnitPlan, assurance: ReviewAssurance): strin
   return parts.join(" ").slice(0, 4_000);
 };
 
+const remapPlanUnitIds = (plan: ReviewUnitPlan, offset: number): ReviewUnitPlan => {
+  if (offset === 0) return plan;
+  const units = plan.units.map((unit, index) =>
+    ReviewUnit.make({
+      ...unit,
+      unitId: `unit-${String(offset + index + 1).padStart(3, "0")}`,
+    }),
+  );
+  const mappedIds = new Map<string, string>();
+  for (const [index, unit] of plan.units.entries()) {
+    const remapped = units[index];
+    if (remapped !== undefined) {
+      mappedIds.set(unit.unitId, remapped.unitId);
+    }
+  }
+  return ReviewUnitPlan.make({
+    ...plan,
+    units,
+    discoveryPasses: plan.discoveryPasses.map((pass) => {
+      const unitId = mappedIds.get(pass.unitId) ?? pass.unitId;
+      return ReviewDiscoveryPass.make({
+        ...pass,
+        unitId,
+        passId: `${unitId}${pass.passId.slice(pass.unitId.length)}`,
+      });
+    }),
+  });
+};
+
+const scheduleFanOutWork = (
+  input: FanOutPipelineInput,
+): {
+  readonly plan: ReviewUnitPlan;
+  readonly passesByUnit: Map<string, ReadonlyArray<ReviewDiscoveryPass>>;
+  readonly overflowRetryPaths: ReadonlyArray<string>;
+} => {
+  const retryPathSet = new Set(input.retry?.paths ?? []);
+  const retryStages = new Set(input.retry?.stages ?? []);
+  if (retryPathSet.size === 0) {
+    const plan = planReviewUnits(input.files, { totalChangedFiles: input.totalChangedFiles });
+    const passesByUnit = new Map<string, Array<ReviewDiscoveryPass>>();
+    for (const pass of plan.discoveryPasses) {
+      const passes = passesByUnit.get(pass.unitId) ?? [];
+      passes.push(pass);
+      passesByUnit.set(pass.unitId, passes);
+    }
+    return { plan, passesByUnit, overflowRetryPaths: [] };
+  }
+  const freshFiles = input.files.filter((file) => !retryPathSet.has(file.path));
+  const retryFiles = input.files.filter((file) => retryPathSet.has(file.path));
+  const freshPlan = planReviewUnits(freshFiles, { totalChangedFiles: input.totalChangedFiles });
+  const retryPlan = remapPlanUnitIds(
+    planReviewUnits(retryFiles, { totalChangedFiles: input.totalChangedFiles }),
+    freshPlan.units.length,
+  );
+  const acceptedFresh = freshPlan.units.slice(0, MAX_REVIEW_UNITS);
+  const acceptedRetry = retryPlan.units.slice(
+    0,
+    Math.max(0, MAX_REVIEW_UNITS - acceptedFresh.length),
+  );
+  const overflowRetryPaths = retryPlan.units
+    .slice(acceptedRetry.length)
+    .flatMap((unit) => [...unit.paths]);
+  const retryPassFilter = (pass: ReviewDiscoveryPass): boolean => {
+    const stage = pass.perspective === "risk-specialist" ? "specialist" : "discovery";
+    return retryStages.has(stage);
+  };
+  const acceptedRetryIds = new Set(acceptedRetry.map((unit) => unit.unitId));
+  let retryPasses = retryPlan.discoveryPasses.filter(
+    (pass) => acceptedRetryIds.has(pass.unitId) && retryPassFilter(pass),
+  );
+  if (
+    retryStages.has("verification") &&
+    !retryStages.has("discovery") &&
+    !retryStages.has("specialist")
+  ) {
+    retryPasses = retryPlan.discoveryPasses.filter((pass) => acceptedRetryIds.has(pass.unitId));
+  }
+  const acceptedFreshIds = new Set(acceptedFresh.map((unit) => unit.unitId));
+  const freshPasses = freshPlan.discoveryPasses.filter((pass) => acceptedFreshIds.has(pass.unitId));
+  const discoveryPasses = [...freshPasses, ...retryPasses];
+  const plan = ReviewUnitPlan.make({
+    totalFiles: input.files.length,
+    truncated: freshPlan.truncated || retryPlan.truncated,
+    units: [...acceptedFresh, ...acceptedRetry],
+    discoveryPasses,
+    undiffablePaths: [
+      ...new Set([...freshPlan.undiffablePaths, ...retryPlan.undiffablePaths]),
+    ].sort(),
+    partialEvidencePaths: [
+      ...new Set([...freshPlan.partialEvidencePaths, ...retryPlan.partialEvidencePaths]),
+    ].sort(),
+    unassignedEvidenceShardCount:
+      freshPlan.unassignedEvidenceShardCount + retryPlan.unassignedEvidenceShardCount,
+    unassignedEvidenceShardIds: [
+      ...freshPlan.unassignedEvidenceShardIds,
+      ...retryPlan.unassignedEvidenceShardIds,
+    ].slice(0, MAX_REPORTED_UNASSIGNED_EVIDENCE_SHARDS),
+    unassignedPaths: [
+      ...new Set([
+        ...freshPlan.unassignedPaths,
+        ...retryPlan.unassignedPaths,
+        ...overflowRetryPaths,
+      ]),
+    ].sort(),
+  });
+  const passesByUnit = new Map<string, Array<ReviewDiscoveryPass>>();
+  for (const pass of discoveryPasses) {
+    const passes = passesByUnit.get(pass.unitId) ?? [];
+    passes.push(pass);
+    passesByUnit.set(pass.unitId, passes);
+  }
+  return { plan, passesByUnit, overflowRetryPaths };
+};
+
 /**
  * Run the complete host-scheduled fan-out pipeline over one selected
  * changeset snapshot: plan, independent discovery, exact verification, and a
@@ -748,13 +932,7 @@ export const runFanOutReview = <Provider, ModelProvides, ModelRequires>(
   input: FanOutPipelineInput,
 ) =>
   Effect.gen(function* () {
-    const plan = planReviewUnits(input.files, { totalChangedFiles: input.totalChangedFiles });
-    const passesByUnit = new Map<string, Array<ReviewDiscoveryPass>>();
-    for (const pass of plan.discoveryPasses) {
-      const passes = passesByUnit.get(pass.unitId) ?? [];
-      passes.push(pass);
-      passesByUnit.set(pass.unitId, passes);
-    }
+    const { plan, passesByUnit, overflowRetryPaths } = scheduleFanOutWork(input);
     const outcomes = yield* Effect.forEach(
       plan.units,
       (unit) => reviewUnit(binding, unit, passesByUnit.get(unit.unitId) ?? [], input),
@@ -829,7 +1007,14 @@ export const runFanOutReview = <Provider, ModelProvides, ModelRequires>(
     );
     const concerns = rankAndDedupeConcerns(
       confirmed.flatMap(({ candidate }) =>
-        candidate._tag === "ConcernCandidate" ? [candidate.concern] : [],
+        candidate._tag === "ConcernCandidate"
+          ? [
+              ReviewConcern.make({
+                ...candidate.concern,
+                evidencePaths: [...new Set(candidate.evidencePaths)].sort(),
+              }),
+            ]
+          : [],
       ),
     );
     const walkthrough = outcomes.flatMap((outcome) => outcome.walkthrough);
@@ -865,6 +1050,15 @@ export const runFanOutReview = <Provider, ModelProvides, ModelRequires>(
           ...plan.undiffablePaths,
         ]),
       ].sort(),
+      unreviewedPasses: [
+        ...outcomes.flatMap((outcome) => outcome.unreviewedPasses),
+        ...(overflowRetryPaths.length === 0
+          ? []
+          : (input.retry?.stages.length
+              ? input.retry.stages
+              : (["discovery", "specialist", "verification"] as const)
+            ).map((stage) => ({ stage, paths: overflowRetryPaths }))),
+      ],
       turns: outcomes.reduce((total, outcome) => total + outcome.turns, 0),
     } satisfies FanOutPipelineOutcome;
   });

package/src/internal/fingerprint.ts

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { Crypto, Effect, Encoding } from "effect";
 
 import type { ChangedFile } from "./diff.ts";
 
@@ -36,14 +36,14 @@ export const extractFingerprint = (body: string): string | undefined => {
   return last;
 };
 
-/** WebCrypto SHA-256; unavailable crypto is a defect, not an expected failure. */
-const sha256Hex = (text: string): Effect.Effect<string> =>
-  Effect.promise(async () => {
-    const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
-    return Array.from(new Uint8Array(digest))
-      .map((byte) => byte.toString(16).padStart(2, "0"))
-      .join("");
-  });
+/** SHA-256 via `Crypto.Crypto`; unavailable crypto is a defect, not an expected failure. */
+const sha256Hex = Effect.fn("sha256Hex")(function* (
+  text: string,
+): Effect.fn.Return<string, never, Crypto.Crypto> {
+  const crypto = yield* Crypto.Crypto;
+  const digest = yield* crypto.digest("SHA-256", new TextEncoder().encode(text)).pipe(Effect.orDie);
+  return Encoding.encodeHex(digest);
+});
 
 const FIELD = "\u0000";
 const RECORD = "\u0001";
@@ -80,4 +80,10 @@ const canonicalChangeset = (files: ReadonlyArray<ChangedFile>): string =>
 export const computeChangesetFingerprint = (
   files: ReadonlyArray<ChangedFile>,
   signature: string,
-): Effect.Effect<string> => sha256Hex(`${canonicalChangeset(files)}${SECTION}${signature}`);
+): Effect.Effect<string, never, Crypto.Crypto> =>
+  sha256Hex(`${canonicalChangeset(files)}${SECTION}${signature}`);
+
+/** Profile fingerprints are SHA-256 over configuration-only signatures. */
+export const computeProfileFingerprint = (
+  signature: string,
+): Effect.Effect<string, never, Crypto.Crypto> => sha256Hex(signature);

package/src/internal/fixtures.ts

@@ -120,6 +120,7 @@ export const staticPriorReviews = (
   options: {
     readonly state?: Option.Option<ReviewState> | undefined;
     readonly comparison?: ReviewHeadComparison | undefined;
+    readonly treeComparison?: ReviewHeadComparison | undefined;
   } = {},
 ): PriorReviews["Service"] =>
   PriorReviews.of({
@@ -129,6 +130,10 @@ export const staticPriorReviews = (
       options.comparison === undefined
         ? Effect.fail(PriorReviewLookupFailure.make({ reason: "no fixture comparison" }))
         : Effect.succeed(options.comparison),
+    compareTrees: () =>
+      options.treeComparison === undefined
+        ? Effect.fail(PriorReviewLookupFailure.make({ reason: "no fixture tree comparison" }))
+        : Effect.succeed(options.treeComparison),
   });
 
 /** Layer form for consumers whose Effect explicitly requires `PriorReviews`. */
@@ -137,6 +142,7 @@ export const staticPriorReviewsLayer = (
   options: {
     readonly state?: Option.Option<ReviewState> | undefined;
     readonly comparison?: ReviewHeadComparison | undefined;
+    readonly treeComparison?: ReviewHeadComparison | undefined;
   } = {},
 ): Layer.Layer<PriorReviews> =>
   Layer.succeed(PriorReviews)(staticPriorReviews(fingerprint, options));

package/src/internal/github-env.ts

@@ -1,12 +1,14 @@
 import { Config, Effect, FileSystem, Layer, Option, Schema } from "effect";
 import type { HttpClient } from "effect/unstable/http";
 
+import type { ReviewAdjudicationHost } from "./adjudication.ts";
 import type { PriorReviews, ReviewPublisher } from "./github.ts";
 import {
   DEFAULT_GITHUB_REVIEW_AUTHOR_LOGIN,
   GitHubReviewTarget,
   gitHubPriorReviewsLayer,
   gitHubPullRequestSourceLayer,
+  gitHubReviewAdjudicationHostLayer,
   gitHubReviewPublisherLayer,
   gitHubReviewRetirementHostLayer,
 } from "./github.ts";
@@ -116,6 +118,7 @@ export const gitHubReviewLayers = (
   | ReviewPublisher
   | PriorReviews
   | ReviewRetirementHost
+  | ReviewAdjudicationHost
   | ReviewProgressReporter,
   Config.ConfigError,
   HttpClient.HttpClient
@@ -144,11 +147,17 @@ export const gitHubReviewLayers = (
         token,
         reviewAuthorLogin,
       });
+      const adjudicationHostLayer = gitHubReviewAdjudicationHostLayer.pipe(
+        Layer.provide(targetLayer),
+      );
       return Layer.mergeAll(
         gitHubPullRequestSourceLayer.pipe(Layer.provide(targetLayer)),
         gitHubReviewPublisherLayer.pipe(Layer.provide(targetLayer)),
         gitHubPriorReviewsLayer.pipe(Layer.provide(targetLayer)),
         gitHubReviewRetirementHostLayer.pipe(Layer.provide(targetLayer)),
+        // Adjudication is an unconditional run dependency, so the public
+        // GitHub bundle owns its target-bound live host explicitly.
+        adjudicationHostLayer,
         gitHubReviewProgressLayer.pipe(Layer.provide(targetLayer)),
       );
     }),