@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/src/core/resumability.js

@@ -4,6 +4,12 @@ import { createWorkState, initializeWorkState, readWorkState, mutateWorkState }
 
 const DEFAULT_PENDING_STEPS = ["planning", "implementation", "verification"];
 
+const CURRENT_ROUTE_CHECKPOINT_PHASES = new Set(["ROUTED"]);
+
+export function routeCheckpointMustMatchCurrentRoute(phase) {
+  return CURRENT_ROUTE_CHECKPOINT_PHASES.has(phase);
+}
+
 /**
  * Resume phase derived from the highest lifecycle milestone already recorded in
  * a validated ledger. Recreating a checkpoint at ROUTED for a task whose ledger
@@ -16,9 +22,88 @@ const RESUME_PHASE_BY_MILESTONE = Object.freeze({
   EXECUTION_STARTED: "EXECUTING",
   VERIFICATION_STARTED: "VERIFYING",
   VERIFICATION_RECORDED: "VERIFYING",
+  REVIEW_STARTED: "REVIEWING",
+});
+
+const RESUME_STEPS_BY_PHASE = Object.freeze({
+  CONTRACT_READY: {
+    completedSteps: ["contract"],
+    pendingSteps: ["route", ...DEFAULT_PENDING_STEPS],
+  },
+  ROUTED: {
+    completedSteps: ["contract", "route"],
+    pendingSteps: [...DEFAULT_PENDING_STEPS],
+  },
+  PLANNED: {
+    completedSteps: ["contract", "route", "planning"],
+    pendingSteps: [...DEFAULT_PENDING_STEPS.filter((step) => step !== "planning")],
+  },
+  EXECUTING: {
+    completedSteps: ["contract", "route", "planning", "implementation"],
+    pendingSteps: ["verification"],
+  },
+  VERIFYING: {
+    completedSteps: ["contract", "route", "planning", "implementation"],
+    pendingSteps: ["verification"],
+  },
+  REVIEWING: {
+    completedSteps: ["contract", "route", "planning", "implementation", "verification"],
+    pendingSteps: [],
+  },
 });
 
-async function deriveResumePhaseFromLedger(target, packageRoot, taskId) {
+function cycleEvents(events) {
+  const CYCLE_EVENT_NAMES = new Set([
+    "VERIFICATION_STARTED",
+    "VERIFICATION_RECORDED",
+    "DIAGNOSIS_RECORDED",
+    "DIAGNOSTIC_CASE_RECORDED",
+  ]);
+  const cycles = events
+    .filter((event) => CYCLE_EVENT_NAMES.has(event.event))
+    .map((event) => event.details?.verificationCycle)
+    .filter((cycle) => Number.isInteger(cycle) && cycle >= 1);
+  return cycles.at(-1);
+}
+
+/**
+ * Canonical reconstruction projection: for a resumed phase derived from a
+ * validated ledger, returns the single source of truth for completedSteps and
+ * pendingSteps. Unknown phases fall back to the ROUTED projection, matching the
+ * historical default resume checkpoint.
+ */
+export function resumeStepsForPhase(phase) {
+  return RESUME_STEPS_BY_PHASE[phase] ?? RESUME_STEPS_BY_PHASE.ROUTED;
+}
+
+/**
+ * Canonical verification cycle derived from the ledger when history proves
+ * verification has started; undefined when the ledger has no cycle metadata.
+ */
+export function resumeVerificationCycleForPhase(events) {
+  return cycleEvents(events);
+}
+
+/**
+ * Canonical work-state identity fields for reconstruction from a validated
+ * ledger: resumed phase, completedSteps, pendingSteps, and verificationCycle.
+ * This is the one projection shared by ensureResumableState and
+ * contract-create reconstruction so later phases cannot be reconstructed with
+ * contradictory steps.
+ */
+export function buildResumableWorkStateFields({ events, resumedPhase }) {
+  const steps = resumeStepsForPhase(resumedPhase);
+  return {
+    phase: resumedPhase,
+    completedSteps: [...steps.completedSteps],
+    pendingSteps: [...steps.pendingSteps],
+    ...(events && events.length > 0 && cycleEvents(events) !== undefined
+      ? { verificationCycle: cycleEvents(events) }
+      : {}),
+  };
+}
+
+export async function deriveResumePhaseFromLedger(target, packageRoot, taskId) {
   let ledger;
   try {
     ledger = await validateEventLedger(target, packageRoot, { taskId });
@@ -32,71 +117,37 @@ async function deriveResumePhaseFromLedger(target, packageRoot, taskId) {
   let derived = null;
   for (const event of scoped) {
     const phase = positions[event.event];
-    if (!phase) continue;
-    if (!derived) {
-      derived = phase;
-      continue;
-    }
-    if (phase === "VERIFYING") derived = "VERIFYING";
+    if (phase) derived = phase;
   }
   return derived;
 }
 
-function deriveVerificationCycleFromLedger(events) {
-  const cycleEvents = new Set([
-    "VERIFICATION_STARTED",
-    "VERIFICATION_RECORDED",
-    "DIAGNOSIS_RECORDED",
-    "DIAGNOSTIC_CASE_RECORDED",
-  ]);
-  const cycles = events
-    .filter((event) => cycleEvents.has(event.event))
-    .map((event) => event.details?.verificationCycle)
-    .filter((cycle) => Number.isInteger(cycle) && cycle >= 1);
-  return cycles.at(-1);
-}
-
-function resumeSteps(phase) {
-  if (phase === "EXECUTING" || phase === "VERIFYING") {
-    return {
-      completedSteps: ["contract", "route", "planning", "implementation"],
-      pendingSteps: ["verification"],
-    };
-  }
-  return {
-    completedSteps: ["contract", "route"],
-    pendingSteps: [...DEFAULT_PENDING_STEPS],
-  };
-}
-
 export async function ensureResumableState({ target, packageRoot, contract, route, taskId, statePath }) {
   if (!contract || !route) return null;
   const existing = await readWorkState(target, { packageRoot, taskId, statePath });
   if (existing) return existing;
 
   const resumedPhase = await deriveResumePhaseFromLedger(target, packageRoot, taskId) ?? "ROUTED";
-  let verificationCycle;
+  let events = [];
   try {
     const ledger = await validateEventLedger(target, packageRoot, { taskId });
     if (ledger.valid) {
-      verificationCycle = deriveVerificationCycleFromLedger(
-        (ledger.events ?? []).filter((event) => !taskId || event.taskId === taskId),
-      );
+      events = (ledger.events ?? []).filter((event) => !taskId || event.taskId === taskId);
     }
   } catch {
-    verificationCycle = undefined;
+    events = [];
   }
-  const steps = resumeSteps(resumedPhase);
+  const projection = buildResumableWorkStateFields({ events, resumedPhase });
   const state = createWorkState({
     taskId: contract.value.taskId,
     contractFingerprint: contract.fingerprint,
     routeFingerprint: route.fingerprint,
     repositoryFingerprint: await currentRepositoryFingerprint(target),
-    phase: resumedPhase,
+    phase: projection.phase,
     selectedGuides: route.value.guides,
-    completedSteps: steps.completedSteps,
-    pendingSteps: steps.pendingSteps,
-    ...(verificationCycle !== undefined ? { verificationCycle } : {}),
+    completedSteps: projection.completedSteps,
+    pendingSteps: projection.pendingSteps,
+    ...(projection.verificationCycle !== undefined ? { verificationCycle: projection.verificationCycle } : {}),
     checks: [],
     failures: [],
     blockers: [],
@@ -105,6 +156,65 @@ export async function ensureResumableState({ target, packageRoot, contract, rout
   return initializeWorkState(target, state, { packageRoot, taskId, statePath });
 }
 
+function routeSyncError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function sameStringList(left, right) {
+  const a = [...(left ?? [])].sort();
+  const b = [...(right ?? [])].sort();
+  return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+/**
+ * Rebinds an existing ROUTED checkpoint to an already-persisted route.
+ *
+ * Only the route-bound identity fields are updated; contract, repository,
+ * steps, checks, evidence, and phase are preserved. Same-identity reruns are
+ * a no-op. Every other situation fails closed.
+ */
+export async function synchronizePersistedRouteState({ target, packageRoot, taskId, route, contract = null, statePath } = {}) {
+  if (!route || !route.value || typeof route.fingerprint !== "string") {
+    throw routeSyncError("E_ROUTE_STALE", "A persisted route artifact is required to synchronize checkpoint identity");
+  }
+  const state = await readWorkState(target, { packageRoot, taskId, statePath });
+  if (!state) return null;
+  if (state.phase !== "ROUTED") {
+    throw routeSyncError(
+      "E_ROUTE_PHASE_UNSUPPORTED",
+      `Route checkpoint synchronization supports phase ROUTED, found ${state.phase}`,
+    );
+  }
+  if (taskId && state.taskId !== taskId) {
+    throw routeSyncError("E_ROUTE_STALE", "Work state does not belong to the current route task");
+  }
+  if (contract && state.contractFingerprint !== contract.fingerprint) {
+    // Contract evolution with regenerated routing is a pre-existing flow whose
+    // stale checkpoint is recovered through the sanctioned clear-state and
+    // preflight recreation path. Never rebind route identity across a contract
+    // boundary here; leave the checkpoint untouched.
+    return state;
+  }
+  if (route.value.contractFingerprint !== undefined && state.contractFingerprint !== route.value.contractFingerprint) {
+    return state;
+  }
+  if (state.routeFingerprint === route.fingerprint && sameStringList(state.selectedGuides, route.value.guides)) {
+    return state;
+  }
+  return mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId,
+    statePath,
+  }, () => ({
+    ...state,
+    routeFingerprint: route.fingerprint,
+    selectedGuides: [...route.value.guides],
+  }));
+}
+
 export async function synchronizePreflightState({
   target,
   packageRoot,

package/src/core/route-artifact.js

@@ -1,9 +1,12 @@
 import { assertRouteInvariants } from "./router.js";
 import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { readContract } from "./contract.js";
-import { ensureResumableState } from "./resumability.js";
+import { ensureResumableState, synchronizePersistedRouteState } from "./resumability.js";
+import { readWorkState } from "./work-state.js";
 import { taskArtifactPath } from "./task-paths.js";
 
+
+
 export async function persistRoute(target, route, packageRoot, options = {}) {
   assertRouteInvariants(route);
   const { contractFingerprint, ...writeOptions } = options;
@@ -21,6 +24,14 @@ export async function persistRoute(target, route, packageRoot, options = {}) {
     : { ...route, contractFingerprint };
   assertRouteInvariants(value);
   const taskId = options.taskId ?? contractArtifact?.value?.taskId ?? null;
+  let existingState = null;
+  if (taskId) {
+    try {
+      existingState = await readWorkState(target, { packageRoot, taskId });
+    } catch {
+      existingState = null;
+    }
+  }
   const relPath = options.routePath ?? options.routeFile ?? options.relativePath ?? (taskId ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route);
   const artifact = await writeJsonArtifact(
     target,
@@ -33,6 +44,9 @@ export async function persistRoute(target, route, packageRoot, options = {}) {
   if (contractArtifact && contractArtifact.fingerprint === artifact.value.contractFingerprint) {
     await ensureResumableState({ target, packageRoot, contract: contractArtifact, route: artifact, taskId });
   }
+  if (existingState?.phase === "ROUTED") {
+    await synchronizePersistedRouteState({ target, packageRoot, taskId, route: artifact, contract: contractArtifact });
+  }
   return artifact;
 }
 

package/src/core/router.js

@@ -313,6 +313,64 @@ function reasonForSignal(prefix, signal) {
   return `${prefix}_${signal.toUpperCase().replaceAll("-", "_")}`;
 }
 
+const SECURITY_TRUST_BOUNDARY_RISKS = Object.freeze([
+  "untrusted-input", "personal-data", "secrets", "external-service", "publication",
+]);
+
+// Canonical deterministic safety floor. These are the route reason codes the
+// router assigns when a trust-boundary signal selects the security guide. The
+// semantic exclusion policy reads protection from this same source, so a
+// mandatory safety guide can never drift out of protection (for example the
+// previously missing external-service boundary).
+const MANDATORY_SAFETY_REASONS = Object.freeze(new Set([
+  "SURFACE_AUTH",
+  ...SECURITY_TRUST_BOUNDARY_RISKS.map((risk) => reasonForSignal("RISK", risk)),
+]));
+
+export function isMandatorySafetyReason(reason) {
+  return MANDATORY_SAFETY_REASONS.has(reason);
+}
+
+export function isMandatorySafetyGuide(guide, reasons) {
+  return guide === "security"
+    && Array.isArray(reasons)
+    && reasons.some((reason) => isMandatorySafetyReason(reason));
+}
+
+function applySemanticGuideRecommendation(selected, excluded, recommendation) {
+  const guideDecision = recommendation?.guideRelevance
+    ?? (recommendation?.rankedIds || recommendation?.excludedIds ? recommendation : null);
+  if (!guideDecision) return;
+  const excludedIds = new Set(Array.isArray(guideDecision.excludedIds) ? guideDecision.excludedIds : []);
+  const confidenceById = guideDecision.confidenceById ?? {};
+  for (const guide of [...selected.keys()]) {
+    const reasons = selected.get(guide);
+    if (isMandatorySafetyGuide(guide, reasons)) {
+      if (!reasons.includes("MANDATORY_SAFETY_GUIDE")) reasons.push("MANDATORY_SAFETY_GUIDE");
+      continue;
+    }
+    if (!excludedIds.has(guide)) {
+      if (!reasons.includes("JEV_RELEVANT")) reasons.push("JEV_RELEVANT");
+      continue;
+    }
+    if ((confidenceById[guide] ?? 0) < 0.75) {
+      if (!reasons.includes("JEV_LOW_CONFIDENCE_RETAINED")) reasons.push("JEV_LOW_CONFIDENCE_RETAINED");
+      continue;
+    }
+    selected.delete(guide);
+    excluded[guide] = ["JEV_EXCLUDED"];
+  }
+  const ranked = Array.isArray(guideDecision.rankedIds) ? guideDecision.rankedIds : [];
+  const order = new Map(ranked.map((guide, index) => [guide, index]));
+  const entries = [...selected.entries()].sort((left, right) => {
+    const leftRank = order.has(left[0]) ? order.get(left[0]) : ranked.length + [...selected.keys()].indexOf(left[0]);
+    const rightRank = order.has(right[0]) ? order.get(right[0]) : ranked.length + [...selected.keys()].indexOf(right[0]);
+    return leftRank - rightRank;
+  });
+  selected.clear();
+  for (const [guide, reasons] of entries) selected.set(guide, reasons);
+}
+
 function normalizeArray(value, name, allowed) {
   if (value === undefined) return [];
   if (!Array.isArray(value)) throw new RouteInputError(`${name} must be an array`);
@@ -440,7 +498,7 @@ export function evaluateRoute(input = {}, profileOptions = {}) {
   }
 
   for (const risk of normalized.risks) {
-    if (["untrusted-input", "personal-data", "secrets", "external-service", "publication"].includes(risk)) {
+    if (SECURITY_TRUST_BOUNDARY_RISKS.includes(risk)) {
       add("security", reasonForSignal("RISK", risk));
     }
     if (["critical-path", "performance"].includes(risk)) {
@@ -481,12 +539,19 @@ export function evaluateRoute(input = {}, profileOptions = {}) {
     excluded[guide] = [exclusionReasonForGuide(guide, projectEvidence, normalized.workType)];
   }
 
+  applySemanticGuideRecommendation(
+    selected,
+    excluded,
+    profileOptions.semanticRecommendation ?? null,
+  );
+
   const guides = [...selected.keys()];
   const result = {
     schemaVersion: ROUTING_SCHEMA_VERSION,
     protocolVersion: PROTOCOL_VERSION,
     input: normalized,
     primary: Object.prototype.hasOwnProperty.call(PRIMARY_GUIDES, normalized.workType)
+      && guides.includes(PRIMARY_GUIDES[normalized.workType])
       ? PRIMARY_GUIDES[normalized.workType]
       : guides[0] ?? null,
     guides,
@@ -499,6 +564,7 @@ export function evaluateRoute(input = {}, profileOptions = {}) {
       configuredProfile: profileOptions.configuredProfile ?? input.configuredProfile ?? "auto",
       requestedProfile: profileOptions.requestedProfile
         ?? (Object.prototype.hasOwnProperty.call(input, "executionProfile") ? input.executionProfile : null),
+      semanticRecommendation: profileOptions.semanticRecommendation ?? null,
     }),
   };
   return assertRouteInvariants(result);

package/src/core/runtime-context.js

@@ -4,8 +4,22 @@ import {
   normalizeVerificationExecutionPolicy,
 } from "./verification-execution.js";
 import { STRUCTURAL_QUALITY_PROVIDER_ID_PATTERN } from "./structural-quality/constants.js";
-import { E_ADVISORY_CONTEXT_PROVIDER_INVALID } from "./error-codes.js";
+import {
+  E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+  E_BROWSER_VERIFICATION_PROVIDER_INVALID,
+  E_SECURITY_REVIEW_PROVIDER_INVALID,
+} from "./error-codes.js";
 import { assertAdvisoryContextProviderIdentity } from "./advisory-context/provider.js";
+import {
+  BROWSER_VERIFICATION_PROVIDER_ID_PATTERN,
+  assertBrowserVerificationProvider,
+  assertBrowserVerificationProviderIdentity,
+} from "./browser-verification/provider.js";
+import {
+  SECURITY_REVIEW_PROVIDER_ID_PATTERN,
+  assertSecurityReviewProvider,
+  assertSecurityReviewProviderIdentity,
+} from "./security-review/provider.js";
 
 export const AUTHORITY_TRUST_MODES = Object.freeze(["NONE", "HOST_ATTESTED"]);
 
@@ -83,6 +97,100 @@ export function resolveAuthorityContext(options = {}) {
   return hasDirectAuthority ? createAuthorityContext({ ...source, trustMode: "NONE" }) : createAuthorityContext();
 }
 
+function isProviderObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value);
+}
+
+function providerEntries(configured, label, code) {
+  if (!configured || typeof configured !== "object" || Array.isArray(configured)) {
+    const error = new Error(`${label} must be an object or Map`);
+    error.code = code;
+    throw error;
+  }
+  return configured instanceof Map ? [...configured.entries()] : Object.entries(configured);
+}
+
+function registerProviders(configured, { label, code, idError, validateId, providerError, validateProvider }) {
+  const providers = {};
+  for (const [id, provider] of providerEntries(configured, label, code)) {
+    if (!validateId(id)) {
+      const error = new Error(idError(id));
+      error.code = code;
+      throw error;
+    }
+    if (typeof provider !== "function" && !isProviderObject(provider)) {
+      const error = new Error(providerError(id));
+      error.code = code;
+      throw error;
+    }
+    if (typeof provider !== "function") validateProvider(provider, id);
+    providers[id] = provider;
+  }
+  return Object.freeze(providers);
+}
+
+function configureUsageProvider(context, provider) {
+  if (!provider
+    || typeof provider !== "object"
+    || Array.isArray(provider)
+    || typeof provider.getTaskUsage !== "function") {
+    const error = new Error("Usage provider must expose getTaskUsage({ projectPath, taskId })");
+    error.code = "E_USAGE_INVALID";
+    throw error;
+  }
+  context.usageProvider = provider;
+}
+
+function configureStructuralQualityProviders(context, configured) {
+  context.structuralQualityProviders = registerProviders(configured, {
+    label: "structuralQualityProviders",
+    code: "E_STRUCTURAL_QUALITY_PROVIDER_INVALID",
+    idError: id => `Invalid or reserved structural-quality provider ID: ${id}`,
+    validateId: id => STRUCTURAL_QUALITY_PROVIDER_ID_PATTERN.test(id) && id !== "sentrux",
+    providerError: id => `Structural-quality provider ${id} must be an object or factory`,
+    validateProvider: (provider, id) => {},
+  });
+}
+
+function configureAdvisoryContextProviders(context, configured) {
+  context.advisoryContextProviders = registerProviders(configured, {
+    label: "advisoryContextProviders",
+    code: E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+    idError: id => `Invalid advisory-context provider ID: ${id}`,
+    validateId: id => /^[a-z0-9][a-z0-9_-]*$/.test(id),
+    providerError: id => `Advisory-context provider ${id} must be an object or factory`,
+    validateProvider: assertAdvisoryContextProviderIdentity,
+  });
+}
+
+function configureBrowserVerificationProviders(context, configured) {
+  context.browserVerificationProviders = registerProviders(configured, {
+    label: "browserVerificationProviders",
+    code: E_BROWSER_VERIFICATION_PROVIDER_INVALID,
+    idError: id => `Invalid browser-verification provider ID: ${id}`,
+    validateId: id => BROWSER_VERIFICATION_PROVIDER_ID_PATTERN.test(id),
+    providerError: id => `Browser-verification provider ${id} must be an object with verify() or a factory`,
+    validateProvider: (provider, id) => {
+      assertBrowserVerificationProviderIdentity(provider, { expectedId: id });
+      assertBrowserVerificationProvider(provider, { label: `browser-verification provider "${id}"` });
+    },
+  });
+}
+
+function configureSecurityReviewProviders(context, configured) {
+  context.securityReviewProviders = registerProviders(configured, {
+    label: "securityReviewProviders",
+    code: E_SECURITY_REVIEW_PROVIDER_INVALID,
+    idError: id => `Invalid security-review provider ID: ${id}`,
+    validateId: id => SECURITY_REVIEW_PROVIDER_ID_PATTERN.test(id),
+    providerError: id => `Security-review provider ${id} must be an object with review() or a factory`,
+    validateProvider: (provider, id) => {
+      assertSecurityReviewProviderIdentity(provider, { expectedId: id });
+      assertSecurityReviewProvider(provider, { label: `security-review provider "${id}"` });
+    },
+  });
+}
+
 export function createForgeLoopContext(options = {}) {
   const authorityContext = createAuthorityContext(options);
   const context = { authorityContext };
@@ -98,70 +206,19 @@ export function createForgeLoopContext(options = {}) {
     context.verificationExecutionPolicy = normalizeVerificationExecutionPolicy(options.verificationExecutionPolicy);
   }
   if (options?.usageProvider !== undefined) {
-    if (!options.usageProvider
-      || typeof options.usageProvider !== "object"
-      || Array.isArray(options.usageProvider)
-      || typeof options.usageProvider.getTaskUsage !== "function") {
-      const error = new Error("Usage provider must expose getTaskUsage({ projectPath, taskId })");
-      error.code = "E_USAGE_INVALID";
-      throw error;
-    }
-    context.usageProvider = options.usageProvider;
+    configureUsageProvider(context, options.usageProvider);
   }
   if (options?.structuralQualityProviders !== undefined) {
-    const configured = options.structuralQualityProviders instanceof Map
-      ? Object.fromEntries(options.structuralQualityProviders.entries())
-      : options.structuralQualityProviders;
-    if (!configured || typeof configured !== "object" || Array.isArray(configured)) {
-      const error = new Error("structuralQualityProviders must be an object or Map");
-      error.code = "E_STRUCTURAL_QUALITY_PROVIDER_INVALID";
-      throw error;
-    }
-    const providers = {};
-    for (const [id, provider] of Object.entries(configured)) {
-      if (!STRUCTURAL_QUALITY_PROVIDER_ID_PATTERN.test(id) || id === "sentrux") {
-        const error = new Error(`Invalid or reserved structural-quality provider ID: ${id}`);
-        error.code = "E_STRUCTURAL_QUALITY_PROVIDER_INVALID";
-        throw error;
-      }
-      if (typeof provider !== "function"
-        && (!provider || typeof provider !== "object" || Array.isArray(provider))) {
-        const error = new Error(`Structural-quality provider ${id} must be an object or factory`);
-        error.code = "E_STRUCTURAL_QUALITY_PROVIDER_INVALID";
-        throw error;
-      }
-      providers[id] = provider;
-    }
-    context.structuralQualityProviders = Object.freeze(providers);
+    configureStructuralQualityProviders(context, options.structuralQualityProviders);
   }
   if (options?.advisoryContextProviders !== undefined) {
-    const configured = options.advisoryContextProviders instanceof Map
-      ? Object.fromEntries(options.advisoryContextProviders.entries())
-      : options.advisoryContextProviders;
-    if (!configured || typeof configured !== "object" || Array.isArray(configured)) {
-      const error = new Error("advisoryContextProviders must be an object or Map");
-      error.code = E_ADVISORY_CONTEXT_PROVIDER_INVALID;
-      throw error;
-    }
-    const providers = {};
-    for (const [id, provider] of Object.entries(configured)) {
-      if (!/^[a-z0-9][a-z0-9_-]*$/.test(id)) {
-        const error = new Error(`Invalid advisory-context provider ID: ${id}`);
-        error.code = E_ADVISORY_CONTEXT_PROVIDER_INVALID;
-        throw error;
-      }
-      if (typeof provider !== "function"
-        && (!provider || typeof provider !== "object" || Array.isArray(provider))) {
-        const error = new Error(`Advisory-context provider ${id} must be an object or factory`);
-        error.code = E_ADVISORY_CONTEXT_PROVIDER_INVALID;
-        throw error;
-      }
-      if (typeof provider !== "function") {
-        assertAdvisoryContextProviderIdentity(provider, id);
-      }
-      providers[id] = provider;
-    }
-    context.advisoryContextProviders = Object.freeze(providers);
+    configureAdvisoryContextProviders(context, options.advisoryContextProviders);
+  }
+  if (options?.browserVerificationProviders !== undefined) {
+    configureBrowserVerificationProviders(context, options.browserVerificationProviders);
+  }
+  if (options?.securityReviewProviders !== undefined) {
+    configureSecurityReviewProviders(context, options.securityReviewProviders);
   }
   return Object.freeze(context);
 }

package/src/core/schema-validation.js

@@ -55,6 +55,9 @@ export const SHIPPED_SCHEMA_NAMES = Object.freeze([
   "execution-profile-benchmark-run",
   "execution-profile-benchmark-aggregate",
   "structural-quality",
+  "semantic-decision",
+  "context-plan",
+  "test-utility",
 ]);
 
 export class SchemaValidationError extends Error {

package/src/core/security-review/constants.js

@@ -0,0 +1,64 @@
+import { E_SECURITY_REVIEW_REQUEST_INVALID } from "../error-codes.js";
+
+export const SECURITY_REVIEW_LIMITS = Object.freeze({
+  maxProjectPathChars: 4096,
+  maxTaskIdChars: 128,
+  maxReviewIdChars: 128,
+  maxRequirementChars: 2000,
+  maxRequirements: 64,
+  maxPaths: 128,
+  maxPathChars: 512,
+  maxCategories: 32,
+  maxCategoryChars: 64,
+  maxRevisionChars: 256,
+  maxFindings: 256,
+  maxFindingIdChars: 128,
+  maxSeverityChars: 16,
+  maxTitleChars: 512,
+  maxSummaryChars: 4096,
+  maxRuleIdChars: 128,
+  maxConfidenceChars: 16,
+  maxDiagnosticChars: 4000,
+  maxDiagnostics: 64,
+  maxResultChars: 524288,
+  maxSnapshotDepth: 32,
+  maxSnapshotNodes: 4096,
+  maxSnapshotChars: 524288,
+  maxDurationMs: 86_400_000,
+  defaultTimeoutMs: 30_000,
+  maxTimeoutMs: 120_000,
+});
+
+export const SECURITY_REVIEW_SCOPES = Object.freeze(["FULL", "CHANGED", "SELECTED"]);
+export const SECURITY_REVIEW_SEVERITIES = Object.freeze(["INFO", "LOW", "MEDIUM", "HIGH", "CRITICAL"]);
+export const SECURITY_REVIEW_CONFIDENCE = Object.freeze(["LOW", "MEDIUM", "HIGH"]);
+export const SECURITY_REVIEW_CATEGORIES = Object.freeze([
+  "DEPENDENCY", "SECRETS", "INJECTION", "AUTHENTICATION", "AUTHORIZATION",
+  "CRYPTOGRAPHY", "CONFIGURATION", "NETWORK", "FILESYSTEM", "SUPPLY_CHAIN",
+  "UNSAFE_EXECUTION", "OTHER",
+]);
+
+export const SECURITY_REVIEW_TRUST = Object.freeze({
+  authority: "OBSERVATION",
+  evidenceAuthority: "NONE",
+  actionability: "NON_EXECUTABLE",
+  trustRole: "NON_EVIDENCE_SECURITY_REVIEW",
+  persisted: false,
+  lifecycleAuthority: false,
+  completionAuthority: false,
+  evidenceRequiresForgeLoopValidation: true,
+});
+
+export const SECURITY_REVIEW_BLOCKED_RESULT_FIELDS = Object.freeze([
+  "complete", "completed", "nextAction", "releaseClaims", "mutationAllowed", "taskPhase",
+  "lifecycleState", "receipt", "evidence", "evidenceStatus", "check", "gate", "satisfied",
+  "ownership", "writeClaims", "event", "events", "transaction", "installation", "command",
+  "commandArgv", "executable", "shell", "environment", "credentials", "secrets",
+]);
+
+export function securityReviewRequestError(message, details = null) {
+  const error = new Error(message);
+  error.code = E_SECURITY_REVIEW_REQUEST_INVALID;
+  error.details = details;
+  return error;
+}