@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/core/runtime-context.js

@@ -1,11 +1,26 @@
+import { attachStorageConnectionOwner } from "./storage-runtime-registry.js";
 import {
   E_VERIFICATION_ISOLATION_UNAVAILABLE,
   isVerificationExecutionAdapter,
   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 +98,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 +207,23 @@ 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);
+  }
+  if (options?.persistentStorage !== undefined && typeof options.persistentStorage !== "boolean") {
+    throw Object.assign(new Error("persistentStorage must be a boolean"), { code: "E_STORAGE_RUNTIME_CONFIGURATION_INVALID" });
   }
+  if (options?.persistentStorage === true) context.close = attachStorageConnectionOwner(context);
   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 {
@@ -120,7 +123,6 @@ function validate(value, schema, location, errors, rootSchema = schema) {
       return candidateErrors.length === 0;
     });
     if (matches.length !== 1) errors.push(`${location}: expected exactly one matching schema`);
-    return;
   }
 
   if (schema.type && !typeMatches(value, schema.type)) {
@@ -210,6 +212,12 @@ export async function readSchema(name, packageRoot = getPackageRoot()) {
   return schema;
 }
 
+function schemaHealthVersion(schema, name) {
+  const versions = schema?.properties?.schemaVersion?.enum ?? null;
+  const version = schema?.properties?.schemaVersion?.const ?? (name === "task-bundle" && JSON.stringify(versions) === "[1,2]" ? 2 : null);
+  return version;
+}
+
 export async function inspectSchemaHealth(packageRoot = getPackageRoot()) {
   const schemas = [];
   for (const name of SHIPPED_SCHEMA_NAMES) {
@@ -220,13 +228,13 @@ export async function inspectSchemaHealth(packageRoot = getPackageRoot()) {
       assertJsonBytes(bytes, filename);
       const schema = JSON.parse(bytes.toString("utf8"));
       assertJsonLimits(schema, filename);
-      const version = schema?.properties?.schemaVersion?.const ?? null;
+      const version = schemaHealthVersion(schema, name);
       let status = "valid";
       let error = null;
       if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
         status = "invalid";
         error = "schema root must be an object";
-      } else if (version !== 1) {
+      } else if (version !== 1 && !(name === "task-bundle" && version === 2)) {
         status = "unsupported-version";
         error = `schemaVersion ${version ?? "missing"} is not supported`;
       }

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;
+}

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

@@ -0,0 +1,245 @@
+import {
+  E_SECURITY_REVIEW_OUTPUT_LIMIT,
+  E_SECURITY_REVIEW_RESULT_INVALID,
+} from "../error-codes.js";
+import { deepFreeze, normalizePortableText } from "../portable-context.js";
+import {
+  SECURITY_REVIEW_BLOCKED_RESULT_FIELDS,
+  SECURITY_REVIEW_CATEGORIES,
+  SECURITY_REVIEW_CONFIDENCE,
+  SECURITY_REVIEW_LIMITS,
+  SECURITY_REVIEW_SCOPES,
+  SECURITY_REVIEW_SEVERITIES,
+  SECURITY_REVIEW_TRUST,
+} from "./constants.js";
+
+function resultError(message, details = null, code = E_SECURITY_REVIEW_RESULT_INVALID) {
+  const error = new Error(message);
+  error.code = code;
+  error.details = details;
+  return error;
+}
+
+function limitError(message, details = null) {
+  return resultError(message, details, E_SECURITY_REVIEW_OUTPUT_LIMIT);
+}
+
+function text(label, value, maxLength, { optional = false } = {}) {
+  try {
+    return normalizePortableText(value, { label, maxLength, optional });
+  } catch {
+    throw resultError(`${label} is invalid.`);
+  }
+}
+
+function consumeSnapshotBudget(value, label, state, depth) {
+  if (depth > SECURITY_REVIEW_LIMITS.maxSnapshotDepth) {
+    throw limitError(`${label} exceeds the maximum result nesting depth.`);
+  }
+  state.nodes += 1;
+  if (state.nodes > SECURITY_REVIEW_LIMITS.maxSnapshotNodes) {
+    throw limitError("Security review result exceeds its maximum snapshot node count.");
+  }
+  if (typeof value === "string") {
+    state.chars += value.length;
+    if (state.chars > SECURITY_REVIEW_LIMITS.maxSnapshotChars) {
+      throw limitError("Security review result exceeds its maximum snapshot character count.");
+    }
+  }
+}
+
+function strictSnapshotArray(value, label, seen, state, depth) {
+  seen.add(value);
+  try {
+    const output = [];
+    for (let index = 0; index < value.length; index += 1) {
+      if (!Object.prototype.hasOwnProperty.call(value, index)) throw resultError(`${label} contains a sparse array.`);
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (!descriptor || descriptor.get || descriptor.set) throw resultError(`${label}[${index}] is an accessor.`);
+      output.push(strictSnapshot(value[index], `${label}[${index}]`, seen, state, depth + 1));
+    }
+    return output;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+function strictSnapshotObject(value, label, seen, state, depth) {
+  const prototype = Object.getPrototypeOf(value);
+  if (value instanceof Date || value instanceof Map || value instanceof Set || value instanceof Promise
+    || (prototype !== Object.prototype && prototype !== null)) {
+    throw resultError(`${label} contains a non-plain object.`);
+  }
+  seen.add(value);
+  try {
+    const output = {};
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key !== "string") throw resultError(`${label} contains a symbol key.`);
+      if (key === "toJSON") throw resultError(`${label} contains a custom toJSON method.`);
+      state.chars += key.length;
+      if (state.chars > SECURITY_REVIEW_LIMITS.maxSnapshotChars) {
+        throw limitError("Security review result exceeds its maximum snapshot character count.");
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor || descriptor.get || descriptor.set) throw resultError(`${label}.${key} is an accessor.`);
+      output[key] = strictSnapshot(value[key], `${label}.${key}`, seen, state, depth + 1);
+    }
+    return output;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+function strictSnapshot(value, label = "security review result", seen = new Set(), state = { nodes: 0, chars: 0 }, depth = 0) {
+  consumeSnapshotBudget(value, label, state, depth);
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw resultError(`${label} contains a non-finite number.`);
+    return value;
+  }
+  if (typeof value !== "object") throw resultError(`${label} contains an unsupported value.`);
+  if (seen.has(value)) throw resultError(`${label} contains a circular reference.`);
+  return Array.isArray(value)
+    ? strictSnapshotArray(value, label, seen, state, depth)
+    : strictSnapshotObject(value, label, seen, state, depth);
+}
+
+function rejectUnknown(source, allowed, label) {
+  for (const key of Reflect.ownKeys(source)) {
+    if (typeof key !== "string" || !allowed.includes(key)) {
+      throw resultError(`${label} contains an unsupported field.`, { field: typeof key === "string" ? key : String(key) });
+    }
+  }
+}
+
+function assertSafeText(label, value, maxLength) {
+  const normalized = text(label, value, maxLength);
+  if (/(?:authorization\s*:\s*bearer|cookie\s*:|(?:token|secret|password)=|-----begin|file:\/\/(?:\/|%2f)|(?:^|\/)Users\/|(?:^|\/)home\/)/i.test(normalized)) {
+    throw resultError(`${label} contains sensitive or non-portable content.`);
+  }
+  return normalized;
+}
+
+function normalizePath(value, label) {
+  const path = assertSafeText(label, value, SECURITY_REVIEW_LIMITS.maxPathChars).replaceAll("\\", "/");
+  if (path.startsWith("/") || /^[a-z]:\//i.test(path) || path.startsWith("//") || /^file:/i.test(path)
+    || path.split("/").includes("..") || path === "." || path.endsWith("/") || path.includes("//")) {
+    throw resultError(`${label} must be a project-relative non-escaping path.`);
+  }
+  return path;
+}
+
+function assertFindingScope(path, scope, requestedPaths, index) {
+  if (scope === "FULL" || requestedPaths.length === 0) return;
+  const inScope = requestedPaths.some((root) => path === root || path.startsWith(`${root}/`));
+  if (!inScope) {
+    throw resultError(`findings[${index}].path is outside the requested ${scope.toLowerCase()} scope.`, {
+      path,
+      requestedPaths,
+    });
+  }
+}
+
+function normalizeFinding(raw, index, scope, requestedPaths) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw resultError(`findings[${index}] is invalid.`);
+  rejectUnknown(raw, ["id", "category", "severity", "title", "summary", "path", "line", "ruleId", "confidence"], `findings[${index}]`);
+  const finding = {
+    id: assertSafeText(`findings[${index}].id`, raw.id, SECURITY_REVIEW_LIMITS.maxFindingIdChars),
+    category: assertSafeText(`findings[${index}].category`, raw.category, SECURITY_REVIEW_LIMITS.maxCategoryChars),
+    severity: assertSafeText(`findings[${index}].severity`, raw.severity, SECURITY_REVIEW_LIMITS.maxSeverityChars),
+    title: assertSafeText(`findings[${index}].title`, raw.title, SECURITY_REVIEW_LIMITS.maxTitleChars),
+    summary: assertSafeText(`findings[${index}].summary`, raw.summary, SECURITY_REVIEW_LIMITS.maxSummaryChars),
+  };
+  if (!SECURITY_REVIEW_CATEGORIES.includes(finding.category)) throw resultError(`findings[${index}].category is unsupported.`);
+  if (!SECURITY_REVIEW_SEVERITIES.includes(finding.severity)) throw resultError(`findings[${index}].severity is unsupported.`);
+  if (raw.path !== undefined) {
+    finding.path = normalizePath(raw.path, `findings[${index}].path`);
+    assertFindingScope(finding.path, scope, requestedPaths, index);
+  }
+  if (raw.line !== undefined) {
+    if (!Number.isInteger(raw.line) || raw.line < 1 || raw.line > 10_000_000) throw resultError(`findings[${index}].line is invalid.`);
+    finding.line = raw.line;
+  }
+  if (raw.ruleId !== undefined) finding.ruleId = assertSafeText(`findings[${index}].ruleId`, raw.ruleId, SECURITY_REVIEW_LIMITS.maxRuleIdChars);
+  if (raw.confidence !== undefined) {
+    finding.confidence = assertSafeText(`findings[${index}].confidence`, raw.confidence, SECURITY_REVIEW_LIMITS.maxConfidenceChars);
+    if (!SECURITY_REVIEW_CONFIDENCE.includes(finding.confidence)) throw resultError(`findings[${index}].confidence is unsupported.`);
+  }
+  return deepFreeze(finding);
+}
+
+function normalizeDiagnostics(raw) {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw) || raw.length > SECURITY_REVIEW_LIMITS.maxDiagnostics) throw limitError("diagnostics exceeds its limit.");
+  return raw.map((entry, index) => assertSafeText(`diagnostics[${index}]`, entry, SECURITY_REVIEW_LIMITS.maxDiagnosticChars));
+}
+
+function deriveSummary(findings) {
+  const bySeverity = Object.fromEntries(SECURITY_REVIEW_SEVERITIES.map((severity) => [severity, 0]));
+  const byCategory = Object.fromEntries(SECURITY_REVIEW_CATEGORIES.map((category) => [category, 0]));
+  for (const finding of findings) {
+    bySeverity[finding.severity] += 1;
+    byCategory[finding.category] += 1;
+  }
+  return deepFreeze({ total: findings.length, bySeverity: deepFreeze(bySeverity), byCategory: deepFreeze(byCategory) });
+}
+
+function normalizeSummary(raw, expected) {
+  if (raw === undefined) return expected;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw resultError("summary is invalid.");
+  rejectUnknown(raw, ["total", "bySeverity", "byCategory"], "summary");
+  if (JSON.stringify(raw) !== JSON.stringify(expected)) throw resultError("summary does not match normalized findings.");
+  return expected;
+}
+
+function normalizeRequestedPaths(requestedPaths) {
+  if (!Array.isArray(requestedPaths)) throw resultError("requestedPaths must be an array.");
+  const normalized = requestedPaths.map((path, index) => normalizePath(path, `requestedPaths[${index}]`));
+  if (new Set(normalized).size !== normalized.length) throw resultError("requestedPaths must not contain duplicates.");
+  return normalized;
+}
+
+export function normalizeSecurityReviewResult(raw, {
+  provider, taskId, reviewId, scope, requestedPaths = [],
+} = {}) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw resultError("security review result must be an object.");
+  if (!SECURITY_REVIEW_SCOPES.includes(scope)) throw resultError("scope is unsupported.");
+  const normalizedRequestedPaths = normalizeRequestedPaths(requestedPaths);
+  if (scope === "SELECTED" && normalizedRequestedPaths.length === 0) {
+    throw resultError("SELECTED scope requires requestedPaths.");
+  }
+  const snapshot = strictSnapshot(raw);
+  for (const field of SECURITY_REVIEW_BLOCKED_RESULT_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(snapshot, field)) throw resultError("security review result contains a reserved authority field.", { field });
+  }
+  rejectUnknown(snapshot, ["findings", "diagnostics", "durationMs", "summary"], "security review result");
+  if (!Array.isArray(snapshot.findings)) throw resultError("findings must be an array.");
+  if (snapshot.findings.length > SECURITY_REVIEW_LIMITS.maxFindings) throw limitError("Too many findings.", { count: snapshot.findings.length });
+  const findings = snapshot.findings.map((finding, index) => normalizeFinding(finding, index, scope, normalizedRequestedPaths));
+  const ids = findings.map((finding) => finding.id);
+  if (new Set(ids).size !== ids.length) throw resultError("findings must not contain duplicate IDs.");
+  const summary = deriveSummary(findings);
+  normalizeSummary(snapshot.summary, summary);
+  let durationMs;
+  if (snapshot.durationMs !== undefined) {
+    if (!Number.isInteger(snapshot.durationMs) || snapshot.durationMs < 0 || snapshot.durationMs > SECURITY_REVIEW_LIMITS.maxDurationMs) {
+      throw resultError("durationMs is invalid.");
+    }
+    durationMs = snapshot.durationMs;
+  }
+  const result = {
+    taskId: assertSafeText("taskId", taskId, SECURITY_REVIEW_LIMITS.maxTaskIdChars),
+    reviewId: assertSafeText("reviewId", reviewId, SECURITY_REVIEW_LIMITS.maxReviewIdChars),
+    scope,
+    requestedPaths: Object.freeze(normalizedRequestedPaths),
+    provider: deepFreeze({ id: provider.id, ...(provider.version === undefined ? {} : { version: provider.version }) }),
+    findings: Object.freeze(findings),
+    summary,
+    diagnostics: Object.freeze(normalizeDiagnostics(snapshot.diagnostics)),
+    ...(durationMs === undefined ? {} : { durationMs }),
+    ...SECURITY_REVIEW_TRUST,
+  };
+  const serialized = JSON.stringify(result);
+  if (serialized.length > SECURITY_REVIEW_LIMITS.maxResultChars) throw limitError("Security review result exceeds its size limit.", { chars: serialized.length });
+  return deepFreeze(result);
+}