@moretea-labs/forge 1.7.2 → 1.8.1

package/packages/kernel/work/domain/evaluation-promotion-receipt.ts

@@ -0,0 +1,186 @@
+import { createHash } from 'crypto';
+import type { WorkImplementationReviewEvidenceIdentity } from './implementation-review';
+
+export const EVALUATION_PROMOTION_RECEIPT_SCHEMA = 'forge-evaluation-promotion-receipt/v1' as const;
+export const EVALUATION_PROMOTION_RECEIPT_AUTHORITY = 'evaluation_evidence_only' as const;
+export const EVALUATION_CANDIDATE_IDENTITY_SCHEMA = 'forge-candidate-identity/v1' as const;
+
+export interface EvaluationPromotionCandidateIdentity {
+  schemaVersion: typeof EVALUATION_CANDIDATE_IDENTITY_SCHEMA;
+  candidateId: string;
+  versionLabel: string;
+  artifactDigest: string;
+  sourceRevision?: string;
+  executionSurface: 'public_cli' | 'public_mcp';
+}
+
+export interface EvaluationPromotionReceipt {
+  schemaVersion: typeof EVALUATION_PROMOTION_RECEIPT_SCHEMA;
+  authority: typeof EVALUATION_PROMOTION_RECEIPT_AUTHORITY;
+  receiptId: string;
+  baseline: EvaluationPromotionCandidateIdentity;
+  candidate: EvaluationPromotionCandidateIdentity;
+  evidence: {
+    paired: {
+      protocolDigest: string;
+      environmentFingerprint: string;
+      pairCount: number;
+      evidenceDigest: string;
+    };
+    shadow: {
+      protocolDigest: string;
+      pairedScenarioCount: number;
+      evidenceDigest: string;
+    };
+    certification?: {
+      manifestDigest: string;
+    };
+  };
+}
+
+export type EvaluationPromotionReceiptCore = Omit<EvaluationPromotionReceipt, 'receiptId'>;
+
+function requiredText(value: unknown, field: string): string {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  if (!normalized) throw new Error(`EVALUATION_PROMOTION_RECEIPT_${field.toUpperCase()}_REQUIRED`);
+  return normalized;
+}
+
+function nonNegativeInteger(value: unknown, field: string): number {
+  if (!Number.isInteger(value) || Number(value) < 0) {
+    throw new Error(`EVALUATION_PROMOTION_RECEIPT_${field.toUpperCase()}_INVALID`);
+  }
+  return Number(value);
+}
+
+function candidateIdentity(value: unknown, field: 'baseline' | 'candidate'): EvaluationPromotionCandidateIdentity {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`EVALUATION_PROMOTION_RECEIPT_${field.toUpperCase()}_REQUIRED`);
+  }
+  const input = value as Record<string, unknown>;
+  if (input.schemaVersion !== EVALUATION_CANDIDATE_IDENTITY_SCHEMA) {
+    throw new Error(`EVALUATION_PROMOTION_RECEIPT_${field.toUpperCase()}_SCHEMA_INVALID`);
+  }
+  if (input.executionSurface !== 'public_cli' && input.executionSurface !== 'public_mcp') {
+    throw new Error(`EVALUATION_PROMOTION_RECEIPT_${field.toUpperCase()}_SURFACE_INVALID`);
+  }
+  const sourceRevision = typeof input.sourceRevision === 'string' && input.sourceRevision.trim()
+    ? input.sourceRevision.trim()
+    : undefined;
+  return {
+    schemaVersion: EVALUATION_CANDIDATE_IDENTITY_SCHEMA,
+    candidateId: requiredText(input.candidateId, `${field}_candidate_id`),
+    versionLabel: requiredText(input.versionLabel, `${field}_version_label`),
+    artifactDigest: requiredText(input.artifactDigest, `${field}_artifact_digest`),
+    ...(sourceRevision ? { sourceRevision } : {}),
+    executionSurface: input.executionSurface,
+  };
+}
+
+function receiptCore(value: unknown): EvaluationPromotionReceiptCore {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('EVALUATION_PROMOTION_RECEIPT_INVALID');
+  }
+  const input = value as Record<string, unknown>;
+  if (input.schemaVersion !== EVALUATION_PROMOTION_RECEIPT_SCHEMA) {
+    throw new Error('EVALUATION_PROMOTION_RECEIPT_SCHEMA_INVALID');
+  }
+  if (input.authority !== EVALUATION_PROMOTION_RECEIPT_AUTHORITY) {
+    throw new Error('EVALUATION_PROMOTION_RECEIPT_AUTHORITY_INVALID');
+  }
+  if (!input.evidence || typeof input.evidence !== 'object' || Array.isArray(input.evidence)) {
+    throw new Error('EVALUATION_PROMOTION_RECEIPT_EVIDENCE_REQUIRED');
+  }
+  const evidence = input.evidence as Record<string, unknown>;
+  if (!evidence.paired || typeof evidence.paired !== 'object' || Array.isArray(evidence.paired)) {
+    throw new Error('EVALUATION_PROMOTION_RECEIPT_PAIRED_REQUIRED');
+  }
+  if (!evidence.shadow || typeof evidence.shadow !== 'object' || Array.isArray(evidence.shadow)) {
+    throw new Error('EVALUATION_PROMOTION_RECEIPT_SHADOW_REQUIRED');
+  }
+  const paired = evidence.paired as Record<string, unknown>;
+  const shadow = evidence.shadow as Record<string, unknown>;
+  let certification: EvaluationPromotionReceipt['evidence']['certification'];
+  if (evidence.certification !== undefined) {
+    if (!evidence.certification || typeof evidence.certification !== 'object' || Array.isArray(evidence.certification)) {
+      throw new Error('EVALUATION_PROMOTION_RECEIPT_CERTIFICATION_INVALID');
+    }
+    certification = {
+      manifestDigest: requiredText(
+        (evidence.certification as Record<string, unknown>).manifestDigest,
+        'certification_manifest_digest',
+      ),
+    };
+  }
+  return {
+    schemaVersion: EVALUATION_PROMOTION_RECEIPT_SCHEMA,
+    authority: EVALUATION_PROMOTION_RECEIPT_AUTHORITY,
+    baseline: candidateIdentity(input.baseline, 'baseline'),
+    candidate: candidateIdentity(input.candidate, 'candidate'),
+    evidence: {
+      paired: {
+        protocolDigest: requiredText(paired.protocolDigest, 'paired_protocol_digest'),
+        environmentFingerprint: requiredText(paired.environmentFingerprint, 'paired_environment_fingerprint'),
+        pairCount: nonNegativeInteger(paired.pairCount, 'paired_pair_count'),
+        evidenceDigest: requiredText(paired.evidenceDigest, 'paired_evidence_digest'),
+      },
+      shadow: {
+        protocolDigest: requiredText(shadow.protocolDigest, 'shadow_protocol_digest'),
+        pairedScenarioCount: nonNegativeInteger(shadow.pairedScenarioCount, 'shadow_paired_scenario_count'),
+        evidenceDigest: requiredText(shadow.evidenceDigest, 'shadow_evidence_digest'),
+      },
+      ...(certification ? { certification } : {}),
+    },
+  };
+}
+
+function receiptIdentity(core: EvaluationPromotionReceiptCore): string {
+  const digest = createHash('sha256')
+    .update(EVALUATION_PROMOTION_RECEIPT_SCHEMA)
+    .update('\0')
+    .update(JSON.stringify(core))
+    .digest('hex');
+  return `evaluation-promotion:sha256:${digest}`;
+}
+
+function deepFreeze<T>(value: T): T {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const nested of Object.values(value as Record<string, unknown>)) deepFreeze(nested);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/**
+ * Identity constructor only. Eligibility authority remains in evaluation/.
+ * Callers outside the evaluator must not treat this helper as proof that A/B,
+ * shadow, or certification gates ran.
+ */
+export function buildEvaluationPromotionReceipt(coreInput: EvaluationPromotionReceiptCore): EvaluationPromotionReceipt {
+  const core = receiptCore(coreInput);
+  return deepFreeze({ ...core, receiptId: receiptIdentity(core) });
+}
+
+export function validateEvaluationPromotionReceipt(value: unknown): EvaluationPromotionReceipt {
+  const core = receiptCore(value);
+  const receiptId = requiredText((value as Record<string, unknown>).receiptId, 'receipt_id');
+  const expected = receiptIdentity(core);
+  if (receiptId !== expected) throw new Error('EVALUATION_PROMOTION_RECEIPT_ID_INVALID');
+  return deepFreeze({ ...core, receiptId });
+}
+
+export function evaluationPromotionReceiptArchitectureEvidence(
+  value: unknown,
+  expectedSourceRevision: string,
+): WorkImplementationReviewEvidenceIdentity {
+  const receipt = validateEvaluationPromotionReceipt(value);
+  const sourceRevision = receipt.candidate.sourceRevision?.trim() ?? '';
+  const expected = expectedSourceRevision.trim();
+  if (!expected || !sourceRevision || sourceRevision !== expected) {
+    throw new Error(`EVALUATION_PROMOTION_RECEIPT_CANDIDATE_SOURCE_MISMATCH: expected=${expected || 'missing'} actual=${sourceRevision || 'missing'}`);
+  }
+  return {
+    evidenceId: receipt.receiptId,
+    digest: receipt.receiptId.slice('evaluation-promotion:'.length),
+  };
+}

package/packages/kernel/work/domain/execution-concurrency.ts

@@ -0,0 +1,247 @@
+import type { EngineeringMutationClass } from './engineering-design';
+import type { WorkContract } from './types';
+
+export type WorkExecutionLane = 'read' | 'review' | 'isolated_write' | 'integration_write' | 'external_effect';
+export type WorkExecutionIsolation = 'shared' | 'isolated';
+export type WorkExecutionResourceMode = 'read' | 'write' | 'exclusive';
+
+export interface WorkExecutionResourceIntent {
+  resourceKey: string;
+  mode: WorkExecutionResourceMode;
+}
+
+export type WorkExecutionWakeTrigger =
+  | { kind: 'work_terminal'; workId: string }
+  | { kind: 'resource_release'; resourceKeys: string[] }
+  | { kind: 'scheduler_capacity'; capacityKey: string }
+  | { kind: 'work_contract_change'; workId: string };
+
+export interface WorkExecutionConcurrencyBlocker {
+  code:
+    | 'same_semantic_scope_mutation'
+    | 'shared_mutation_lane_conflict'
+    | 'integration_target_conflict'
+    | 'external_effect_target_conflict'
+    | 'external_effect_target_unknown';
+  disposition: 'wait' | 'invalid';
+  blockingWorkId?: string;
+  semanticScopeKeys: string[];
+  resourceKeys: string[];
+  wakeTrigger: WorkExecutionWakeTrigger;
+}
+
+export interface WorkExecutionConcurrencyContract {
+  schemaVersion: 1;
+  workId: string;
+  sourceRevision?: string;
+  observedWorkUpdatedAt: string;
+  semanticScopeKeys: string[];
+  mutationClass: EngineeringMutationClass;
+  lane: WorkExecutionLane;
+  resourceIntents: WorkExecutionResourceIntent[];
+  blockers: WorkExecutionConcurrencyBlocker[];
+  isolation: WorkExecutionIsolation;
+}
+
+export interface WorkExecutionConcurrencyInput {
+  lane?: WorkExecutionLane;
+  resourceIntents?: readonly WorkExecutionResourceIntent[];
+  blockers?: readonly WorkExecutionConcurrencyBlocker[];
+}
+
+export interface WorkExecutionCompatibilityDecision {
+  compatible: boolean;
+  blockers: WorkExecutionConcurrencyBlocker[];
+}
+
+function normalizedStrings(values: readonly string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))].sort();
+}
+
+function normalizedResourceIntents(values: readonly WorkExecutionResourceIntent[]): WorkExecutionResourceIntent[] {
+  const byIdentity = new Map<string, WorkExecutionResourceIntent>();
+  for (const value of values) {
+    const resourceKey = value.resourceKey.trim();
+    if (!resourceKey) continue;
+    const identity = `${resourceKey}\u0000${value.mode}`;
+    byIdentity.set(identity, { resourceKey, mode: value.mode });
+  }
+  return [...byIdentity.values()].sort((left, right) =>
+    left.resourceKey.localeCompare(right.resourceKey) || left.mode.localeCompare(right.mode));
+}
+
+function fallbackMutationClass(work: WorkContract): EngineeringMutationClass {
+  if (work.workKind === 'read_only_review'
+    || work.workKind === 'investigation'
+    || work.workKind === 'completed_no_change'
+    || work.workKind === 'reconciliation'
+    || work.workKind === 'superseded') return 'readonly';
+  if (work.workKind === 'local_effect' || work.workKind === 'remote_effect') return 'external_effect';
+  if (work.worktreePolicy.required || work.constraints.workspaceMode === 'isolated') {
+    return 'isolated_write';
+  }
+  return 'integration_write';
+}
+
+function semanticScopeKeys(work: WorkContract): string[] {
+  const declared = normalizedStrings(work.engineeringContext?.semanticScope?.keys ?? []);
+  if (declared.length > 0) return declared;
+  if (work.planId?.trim() && work.planStepId?.trim()) return [`plan-step:${work.planId.trim()}:${work.planStepId.trim()}`];
+  return [`work:${work.workId}`];
+}
+
+function defaultLane(
+  work: WorkContract,
+  mutationClass: EngineeringMutationClass,
+  resourceIntents: readonly WorkExecutionResourceIntent[],
+  requestedLane?: WorkExecutionLane,
+): WorkExecutionLane {
+  const hasMutableResourceIntent = resourceIntents.some((intent) => intent.mode !== 'read');
+  if (hasMutableResourceIntent && (!requestedLane || !workExecutionLaneMutates(requestedLane))) {
+    if (mutationClass === 'external_effect') return 'external_effect';
+    return work.worktreePolicy.required || work.constraints.workspaceMode === 'isolated'
+      ? 'isolated_write'
+      : 'integration_write';
+  }
+  if (requestedLane) return requestedLane;
+  if (work.workKind === 'read_only_review') return 'review';
+  if (mutationClass === 'readonly') return 'read';
+  return mutationClass;
+}
+
+export function buildWorkExecutionConcurrencyContract(
+  work: WorkContract,
+  input: WorkExecutionConcurrencyInput = {},
+): WorkExecutionConcurrencyContract {
+  const mutationClass = work.engineeringContext?.semanticScope?.mutationClass ?? fallbackMutationClass(work);
+  const resourceIntents = normalizedResourceIntents(input.resourceIntents ?? []);
+  return {
+    schemaVersion: 1,
+    workId: work.workId,
+    sourceRevision: work.baseRevision ?? work.planSourceRevision,
+    observedWorkUpdatedAt: work.updatedAt,
+    semanticScopeKeys: semanticScopeKeys(work),
+    mutationClass,
+    lane: defaultLane(work, mutationClass, resourceIntents, input.lane),
+    resourceIntents,
+    blockers: [...(input.blockers ?? [])],
+    isolation: work.worktreePolicy.required || work.constraints.workspaceMode === 'isolated'
+      ? 'isolated'
+      : 'shared',
+  };
+}
+
+export function workExecutionLaneMutates(lane: WorkExecutionLane): boolean {
+  return lane === 'isolated_write' || lane === 'integration_write' || lane === 'external_effect';
+}
+
+function scopesOverlap(left: WorkExecutionConcurrencyContract, right: WorkExecutionConcurrencyContract): string[] {
+  const rightKeys = new Set(right.semanticScopeKeys);
+  return left.semanticScopeKeys.filter((key) => rightKeys.has(key));
+}
+
+function mutableResourceKeys(contract: WorkExecutionConcurrencyContract): string[] {
+  return normalizedStrings(contract.resourceIntents
+    .filter((intent) => intent.mode !== 'read')
+    .map((intent) => intent.resourceKey));
+}
+
+function sharedMutableResourceKeys(
+  left: WorkExecutionConcurrencyContract,
+  right: WorkExecutionConcurrencyContract,
+): string[] {
+  const rightKeys = new Set(mutableResourceKeys(right));
+  return mutableResourceKeys(left).filter((key) => rightKeys.has(key));
+}
+
+export function evaluateWorkExecutionCompatibility(
+  candidate: WorkExecutionConcurrencyContract,
+  active: readonly WorkExecutionConcurrencyContract[],
+): WorkExecutionCompatibilityDecision {
+  const blockers: WorkExecutionConcurrencyBlocker[] = [];
+  if (candidate.lane === 'external_effect' && mutableResourceKeys(candidate).length === 0) {
+    blockers.push({
+      code: 'external_effect_target_unknown',
+      disposition: 'invalid',
+      semanticScopeKeys: candidate.semanticScopeKeys,
+      resourceKeys: [],
+      wakeTrigger: { kind: 'work_contract_change', workId: candidate.workId },
+    });
+  }
+  if (blockers.length > 0) return { compatible: false, blockers };
+  if (!workExecutionLaneMutates(candidate.lane)) return { compatible: true, blockers: [] };
+
+  for (const current of active) {
+    if (current.workId === candidate.workId) continue;
+    if (!workExecutionLaneMutates(current.lane)) continue;
+
+    const overlap = scopesOverlap(candidate, current);
+    if (overlap.length > 0) {
+      blockers.push({
+        code: 'same_semantic_scope_mutation',
+        disposition: 'wait',
+        blockingWorkId: current.workId,
+        semanticScopeKeys: overlap,
+        resourceKeys: [],
+        wakeTrigger: { kind: 'work_terminal', workId: current.workId },
+      });
+      continue;
+    }
+
+    if (candidate.lane === 'isolated_write' && current.lane === 'isolated_write'
+      && candidate.isolation === 'isolated' && current.isolation === 'isolated') continue;
+
+    if (candidate.lane === 'external_effect' || current.lane === 'external_effect') {
+      const candidateTargets = mutableResourceKeys(candidate);
+      const currentTargets = mutableResourceKeys(current);
+      // An active Work without an executing target does not own a remote-effect
+      // resource yet. Same semantic scope was already handled above; physical
+      // target conflicts start only once the active Work has declared claims.
+      if (current.lane === 'external_effect' && currentTargets.length === 0) continue;
+      const sharedTargets = sharedMutableResourceKeys(candidate, current);
+      if (sharedTargets.length > 0) {
+        blockers.push({
+          code: 'external_effect_target_conflict',
+          disposition: 'wait',
+          blockingWorkId: current.workId,
+          semanticScopeKeys: [],
+          resourceKeys: sharedTargets,
+          wakeTrigger: { kind: 'resource_release', resourceKeys: sharedTargets },
+        });
+      }
+      continue;
+    }
+
+    if (candidate.lane === 'integration_write' || current.lane === 'integration_write') {
+      const sharedTargets = sharedMutableResourceKeys(candidate, current);
+      if (sharedTargets.length > 0) {
+        blockers.push({
+          code: 'integration_target_conflict',
+          disposition: 'wait',
+          blockingWorkId: current.workId,
+          semanticScopeKeys: [],
+          resourceKeys: sharedTargets,
+          wakeTrigger: { kind: 'resource_release', resourceKeys: sharedTargets },
+        });
+        continue;
+      }
+      // A no-target shared mutation lane is physical checkout ownership, not a
+      // repository-wide mutex. A shared canonical checkout and an isolated
+      // checkout may proceed concurrently unless semantic scope or explicit
+      // resource targets already conflicted above. Only two shared checkouts
+      // require the fallback lane serialization.
+      if (candidate.isolation === 'shared' && current.isolation === 'shared') {
+        blockers.push({
+          code: 'shared_mutation_lane_conflict',
+          disposition: 'wait',
+          blockingWorkId: current.workId,
+          semanticScopeKeys: [],
+          resourceKeys: [],
+          wakeTrigger: { kind: 'work_terminal', workId: current.workId },
+        });
+      }
+    }
+  }
+
+  return { compatible: blockers.length === 0, blockers };
+}

package/packages/kernel/work/domain/execution-snapshot.ts

@@ -0,0 +1,2 @@
+/** Immutable access-policy value captured by a Work contract. */
+export type WorkAccessMode = 'request' | 'full_access';

package/packages/kernel/work/domain/implementation-review.ts

@@ -0,0 +1,193 @@
+import { createHash } from 'crypto';
+
+export const IMPLEMENTATION_REVIEW_DECISIONS = ['approved', 'changes_required', 'blocked'] as const;
+export const MAX_IMPLEMENTATION_REVIEW_HISTORY = 256;
+export type ImplementationReviewDecision = (typeof IMPLEMENTATION_REVIEW_DECISIONS)[number];
+
+export const IMPLEMENTATION_REVIEW_FINDING_SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'] as const;
+export type ImplementationReviewFindingSeverity = (typeof IMPLEMENTATION_REVIEW_FINDING_SEVERITIES)[number];
+
+export interface WorkImplementationReviewFinding {
+  severity: ImplementationReviewFindingSeverity;
+  category: string;
+  summary: string;
+  path?: string;
+  symbol?: string;
+}
+
+export interface WorkImplementationReviewEvidenceIdentity {
+  evidenceId: string;
+  digest: string;
+}
+
+/**
+ * Historical implementation-review evidence captured before the Thin cutover.
+ * Records remain immutable/readable for audit, but never authorize or block
+ * execution, Git delivery, checks, or semantic Work completion.
+ */
+export interface WorkImplementationReviewRecord {
+  schemaVersion: 1;
+  reviewId: string;
+  workId: string;
+  reviewerPrincipalId: string;
+  reviewerControllerSessionId?: string;
+  reviewerControllerRoundId?: string;
+  decision: ImplementationReviewDecision;
+  rationale: string;
+  findings: WorkImplementationReviewFinding[];
+  sourceRevision: string;
+  workspaceFingerprint: string;
+  /** Exact verification-input workspace identity reviewed before Git representation changes. */
+  verificationWorkspaceFingerprint: string;
+  changedPaths: string[];
+  changedPathDigest: string;
+  acceptanceCriteriaSummary: string;
+  verificationEvidence: WorkImplementationReviewEvidenceIdentity[];
+  architectureEvidence: WorkImplementationReviewEvidenceIdentity[];
+  recordedAt: string;
+  /** Present only when Forge derived an approval from a proven content-equivalent commit. */
+  derivedFromReviewId?: string;
+  derivation?: 'content_equivalent_commit';
+}
+
+function normalizedStrings(values: readonly string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))]
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function sameStringSet(left: readonly string[], right: readonly string[]): boolean {
+  const a = normalizedStrings(left);
+  const b = normalizedStrings(right);
+  return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+export function normalizeImplementationReviewEvidence(
+  values: readonly WorkImplementationReviewEvidenceIdentity[],
+): WorkImplementationReviewEvidenceIdentity[] {
+  const byId = new Map<string, string>();
+  for (const value of values) {
+    const evidenceId = value.evidenceId.trim();
+    const digest = value.digest.trim();
+    if (!evidenceId || !digest) throw new Error('WORK_IMPLEMENTATION_REVIEW_EVIDENCE_IDENTITY_REQUIRED');
+    const prior = byId.get(evidenceId);
+    if (prior && prior !== digest) throw new Error(`WORK_IMPLEMENTATION_REVIEW_EVIDENCE_ID_CONFLICT: ${evidenceId}`);
+    byId.set(evidenceId, digest);
+  }
+  return [...byId.entries()].map(([evidenceId, digest]) => ({ evidenceId, digest }))
+    .sort((left, right) => left.evidenceId.localeCompare(right.evidenceId) || left.digest.localeCompare(right.digest));
+}
+
+function sameEvidenceIdentity(
+  left: readonly WorkImplementationReviewEvidenceIdentity[],
+  right: readonly WorkImplementationReviewEvidenceIdentity[],
+): boolean {
+  const a = normalizeImplementationReviewEvidence(left);
+  const b = normalizeImplementationReviewEvidence(right);
+  return a.length === b.length && a.every((entry, index) => entry.evidenceId === b[index]!.evidenceId && entry.digest === b[index]!.digest);
+}
+
+export function normalizeImplementationReviewChangedPaths(paths: readonly string[]): string[] {
+  const normalized = paths.map((path) => path.trim().replace(/\\/g, '/').replace(/^\.\//, '')).filter(Boolean);
+  for (const path of normalized) {
+    if (path.startsWith('/') || path.includes('\0') || path.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+      throw new Error(`WORK_IMPLEMENTATION_REVIEW_PATH_INVALID: ${path}`);
+    }
+  }
+  return normalizedStrings(normalized);
+}
+
+export function implementationReviewChangedPathDigest(paths: readonly string[]): string {
+  return createHash('sha256')
+    .update(JSON.stringify(normalizeImplementationReviewChangedPaths(paths)))
+    .digest('hex');
+}
+
+export function implementationReviewEvidenceDigest(values: readonly WorkImplementationReviewEvidenceIdentity[]): string {
+  return createHash('sha256').update(JSON.stringify(normalizeImplementationReviewEvidence(values))).digest('hex');
+}
+
+export function latestImplementationReview(
+  reviews: readonly WorkImplementationReviewRecord[] | undefined,
+): WorkImplementationReviewRecord | undefined {
+  if (!reviews?.length) return undefined;
+  // Durable append order is the review authority order. Wall-clock timestamps
+  // are audit metadata and must never reorder Controller decisions under clock skew.
+  return reviews[reviews.length - 1];
+}
+
+/**
+ * Candidate review gate. Low engineering-risk delivery relies on exact durable
+ * completion evidence and may skip a separate Controller review round; normal,
+ * high, and critical repository candidates retain the exact review authority.
+ * Source-free effect/investigation/reconciliation Work may also skip review only
+ * while they truly have no repository source delta.
+ */
+export function validateImplementationReviewRecord(review: WorkImplementationReviewRecord): void {
+  if (!review.reviewId.trim() || !review.workId.trim() || !review.reviewerPrincipalId.trim() || !review.recordedAt.trim()) {
+    throw new Error('WORK_IMPLEMENTATION_REVIEW_IDENTITY_REQUIRED');
+  }
+  if (!IMPLEMENTATION_REVIEW_DECISIONS.includes(review.decision)) {
+    throw new Error('WORK_IMPLEMENTATION_REVIEW_DECISION_REQUIRED');
+  }
+  if (!review.rationale.trim() || !review.acceptanceCriteriaSummary.trim()) {
+    throw new Error('WORK_IMPLEMENTATION_REVIEW_RATIONALE_REQUIRED');
+  }
+  if (!review.sourceRevision.trim() || !review.workspaceFingerprint.trim() || !review.verificationWorkspaceFingerprint.trim()) {
+    throw new Error('WORK_IMPLEMENTATION_REVIEW_SOURCE_IDENTITY_REQUIRED');
+  }
+  const changedPaths = normalizeImplementationReviewChangedPaths(review.changedPaths);
+  if (!sameStringSet(review.changedPaths, changedPaths) || review.changedPaths.length !== changedPaths.length) {
+    throw new Error('WORK_IMPLEMENTATION_REVIEW_CHANGED_PATHS_NOT_CANONICAL');
+  }
+  if (review.changedPathDigest !== implementationReviewChangedPathDigest(changedPaths)) {
+    throw new Error('WORK_IMPLEMENTATION_REVIEW_CHANGED_PATH_IDENTITY_MISMATCH');
+  }
+  if (Number.isNaN(Date.parse(review.recordedAt))) throw new Error('WORK_IMPLEMENTATION_REVIEW_RECORDED_AT_INVALID');
+  const verificationEvidence = normalizeImplementationReviewEvidence(review.verificationEvidence);
+  const architectureEvidence = normalizeImplementationReviewEvidence(review.architectureEvidence);
+  if (!sameEvidenceIdentity(review.verificationEvidence, verificationEvidence)
+    || review.verificationEvidence.length !== verificationEvidence.length
+    || !sameEvidenceIdentity(review.architectureEvidence, architectureEvidence)
+    || review.architectureEvidence.length !== architectureEvidence.length) {
+    throw new Error('WORK_IMPLEMENTATION_REVIEW_EVIDENCE_NOT_CANONICAL');
+  }
+  for (const finding of review.findings) {
+    if (!IMPLEMENTATION_REVIEW_FINDING_SEVERITIES.includes(finding.severity) || !finding.category.trim() || !finding.summary.trim()) {
+      throw new Error('WORK_IMPLEMENTATION_REVIEW_FINDING_INVALID');
+    }
+    if (finding.path) normalizeImplementationReviewChangedPaths([finding.path]);
+  }
+  if (review.decision === 'changes_required' && review.findings.length === 0) {
+    throw new Error('WORK_IMPLEMENTATION_REVIEW_FINDINGS_REQUIRED');
+  }
+  if (review.derivation && (!review.derivedFromReviewId || review.decision !== 'approved')) {
+    throw new Error('WORK_IMPLEMENTATION_REVIEW_DERIVATION_INVALID');
+  }
+  if (review.derivedFromReviewId && review.derivation !== 'content_equivalent_commit') {
+    throw new Error('WORK_IMPLEMENTATION_REVIEW_DERIVATION_INVALID');
+  }
+}
+
+export function assertImplementationReviewHistoryAppendOnly(
+  current: readonly WorkImplementationReviewRecord[] | undefined,
+  next: readonly WorkImplementationReviewRecord[] | undefined,
+): void {
+  const before = current ?? [];
+  const after = next ?? [];
+  if (after.length < before.length) throw new Error('WORK_IMPLEMENTATION_REVIEW_HISTORY_IMMUTABLE');
+  if (after.length > MAX_IMPLEMENTATION_REVIEW_HISTORY) {
+    // Never discard old review authority to enforce a storage bound. Stop and
+    // require an explicit archival/migration design instead.
+    throw new Error('WORK_IMPLEMENTATION_REVIEW_HISTORY_LIMIT');
+  }
+  const ids = new Set<string>();
+  for (let index = 0; index < after.length; index += 1) {
+    const record = after[index];
+    validateImplementationReviewRecord(record);
+    if (ids.has(record.reviewId)) throw new Error('WORK_IMPLEMENTATION_REVIEW_ID_CONFLICT');
+    ids.add(record.reviewId);
+    if (index < before.length && JSON.stringify(before[index]) !== JSON.stringify(record)) {
+      throw new Error('WORK_IMPLEMENTATION_REVIEW_HISTORY_IMMUTABLE');
+    }
+  }
+}