@cassiomc1/forgeloop 1.13.0 → 1.14.0

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

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

@@ -0,0 +1,204 @@
+import {
+  E_SECURITY_REVIEW_PROVIDER_INVALID,
+  E_SECURITY_REVIEW_PROVIDER_UNAVAILABLE,
+} from "../error-codes.js";
+import { assertPortableContextSafe, deepFreeze, normalizePortableText } from "../portable-context.js";
+import {
+  SECURITY_REVIEW_CATEGORIES,
+  SECURITY_REVIEW_LIMITS,
+  SECURITY_REVIEW_SCOPES,
+  securityReviewRequestError,
+} from "./constants.js";
+
+export const SECURITY_REVIEW_PROVIDER_ID_PATTERN = /^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?$/;
+
+function providerError(message, details = null) {
+  const error = new Error(message);
+  error.code = E_SECURITY_REVIEW_PROVIDER_INVALID;
+  error.details = details;
+  return error;
+}
+
+function unavailableError(message, details = null) {
+  const error = new Error(message);
+  error.code = E_SECURITY_REVIEW_PROVIDER_UNAVAILABLE;
+  error.details = details;
+  return error;
+}
+
+function assertPlainObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
+    throw securityReviewRequestError(`${label} must be a plain object.`);
+  }
+  return value;
+}
+
+function rejectUnknown(source, allowed, label) {
+  for (const key of Reflect.ownKeys(source)) {
+    if (typeof key !== "string" || !allowed.includes(key)) {
+      throw securityReviewRequestError(`${label}.${String(key)} is not supported.`, { field: String(key) });
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(source, key);
+    if (!descriptor || descriptor.get || descriptor.set) {
+      throw securityReviewRequestError(`${label}.${key} must not be an accessor.`, { field: key });
+    }
+  }
+}
+
+function text(label, value, maxLength, { optional = false } = {}) {
+  try {
+    return normalizePortableText(value, { label, maxLength, optional });
+  } catch (error) {
+    throw securityReviewRequestError(`${label} is invalid: ${error.message}`);
+  }
+}
+
+function normalizeRelativePath(value, index) {
+  const path = text(`paths[${index}]`, value, SECURITY_REVIEW_LIMITS.maxPathChars);
+  if (path.startsWith("/") || /^[a-z]:[\\/]/i.test(path) || path.startsWith("\\\\")
+    || /^file:/i.test(path) || path.split(/[\\/]+/).includes("..")) {
+    throw securityReviewRequestError(`paths[${index}] must be a project-relative non-escaping path.`);
+  }
+  const normalized = path.replaceAll("\\", "/");
+  if (normalized === "." || normalized.endsWith("/") || normalized.includes("//")) {
+    throw securityReviewRequestError(`paths[${index}] must identify a normalized project-relative path.`);
+  }
+  return normalized;
+}
+
+function normalizeStringList(value, { label, maxItems, maxChars, allowed = null } = {}) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > maxItems) {
+    throw securityReviewRequestError(`${label} must be an array with at most ${maxItems} items.`);
+  }
+  const result = value.map((entry, index) => {
+    const normalized = text(`${label}[${index}]`, entry, maxChars);
+    if (allowed && !allowed.includes(normalized)) {
+      throw securityReviewRequestError(`${label}[${index}] is unsupported.`);
+    }
+    return normalized;
+  });
+  if (new Set(result).size !== result.length) throw securityReviewRequestError(`${label} must not contain duplicates.`);
+  return result;
+}
+
+function normalizeTimeout(value) {
+  if (value === undefined || value === null) return SECURITY_REVIEW_LIMITS.defaultTimeoutMs;
+  if (!Number.isInteger(value) || value < 1) throw securityReviewRequestError("timeoutMs must be a positive integer.");
+  return Math.min(value, SECURITY_REVIEW_LIMITS.maxTimeoutMs);
+}
+
+function normalizeRevision(value) {
+  if (value === undefined || value === null) return undefined;
+  const source = assertPlainObject(value, "revision");
+  rejectUnknown(source, ["base", "head"], "revision");
+  const base = text("revision.base", source.base, SECURITY_REVIEW_LIMITS.maxRevisionChars, { optional: true });
+  const head = text("revision.head", source.head, SECURITY_REVIEW_LIMITS.maxRevisionChars, { optional: true });
+  if (base === undefined && head === undefined) throw securityReviewRequestError("revision must contain base or head.");
+  return deepFreeze({ ...(base === undefined ? {} : { base }), ...(head === undefined ? {} : { head }) });
+}
+
+export function normalizeSecurityReviewRequest(input) {
+  const source = assertPlainObject(input, "security review request");
+  rejectUnknown(source, ["projectPath", "taskId", "reviewId", "scope", "paths", "categories", "requirements", "revision", "timeoutMs"], "security review request");
+  const projectPath = text("projectPath", source.projectPath, SECURITY_REVIEW_LIMITS.maxProjectPathChars);
+  const taskId = text("taskId", source.taskId, SECURITY_REVIEW_LIMITS.maxTaskIdChars);
+  const reviewId = text("reviewId", source.reviewId, SECURITY_REVIEW_LIMITS.maxReviewIdChars);
+  const scope = text("scope", source.scope, 32);
+  if (!SECURITY_REVIEW_SCOPES.includes(scope)) throw securityReviewRequestError("scope is unsupported.");
+  const paths = normalizeStringList(source.paths, {
+    label: "paths", maxItems: SECURITY_REVIEW_LIMITS.maxPaths, maxChars: SECURITY_REVIEW_LIMITS.maxPathChars,
+  }).map((value, index) => normalizeRelativePath(value, index));
+  if (scope === "SELECTED" && paths.length === 0) throw securityReviewRequestError("SELECTED scope requires at least one path.");
+  const categories = normalizeStringList(source.categories, {
+    label: "categories", maxItems: SECURITY_REVIEW_LIMITS.maxCategories,
+    maxChars: SECURITY_REVIEW_LIMITS.maxCategoryChars, allowed: SECURITY_REVIEW_CATEGORIES,
+  });
+  const requirements = normalizeStringList(source.requirements, {
+    label: "requirements", maxItems: SECURITY_REVIEW_LIMITS.maxRequirements,
+    maxChars: SECURITY_REVIEW_LIMITS.maxRequirementChars,
+  });
+  const normalized = {
+    projectPath, taskId, reviewId, scope,
+    paths: Object.freeze(paths),
+    categories: Object.freeze(categories),
+    requirements: Object.freeze(requirements),
+    timeoutMs: normalizeTimeout(source.timeoutMs),
+    ...(source.revision === undefined || source.revision === null ? {} : { revision: normalizeRevision(source.revision) }),
+  };
+  try {
+    assertPortableContextSafe(normalized, { label: "security review request" });
+  } catch (error) {
+    throw securityReviewRequestError(`security review request failed safety verification: ${error.message}`);
+  }
+  return deepFreeze(normalized);
+}
+
+function assertProviderDataProperties(provider, label) {
+  for (const key of ["id", "version", "review"]) {
+    const descriptor = Object.getOwnPropertyDescriptor(provider, key);
+    if (descriptor?.get || descriptor?.set) throw providerError(`${label}.${key} must not be an accessor.`);
+  }
+}
+
+export function assertSecurityReviewProvider(provider, { label = "security-review provider" } = {}) {
+  if (!provider || typeof provider !== "object" || Array.isArray(provider)) {
+    throw providerError(`${label} must be an object.`);
+  }
+  assertProviderDataProperties(provider, label);
+  if (typeof provider.id !== "string" || !SECURITY_REVIEW_PROVIDER_ID_PATTERN.test(provider.id)) {
+    throw providerError(`${label}.id is invalid.`, { id: provider.id });
+  }
+  if (typeof provider.review !== "function") throw providerError(`${label}.review must be a function.`);
+  if (provider.version !== undefined && typeof provider.version !== "string") {
+    throw providerError(`${label}.version must be a string when present.`);
+  }
+  return provider;
+}
+
+export function assertSecurityReviewProviderIdentity(providerIdentity, { label = "security-review provider identity", expectedId } = {}) {
+  if (!providerIdentity || typeof providerIdentity !== "object" || Array.isArray(providerIdentity)) {
+    throw providerError(`${label} must be an object.`);
+  }
+  if (typeof providerIdentity.id !== "string" || !SECURITY_REVIEW_PROVIDER_ID_PATTERN.test(providerIdentity.id)) {
+    throw providerError(`${label}.id is invalid.`);
+  }
+  if (expectedId !== undefined && providerIdentity.id !== expectedId) {
+    throw providerError(`${label}.id must match registry key "${expectedId}".`);
+  }
+  return deepFreeze({ id: providerIdentity.id, ...(providerIdentity.version === undefined ? {} : { version: providerIdentity.version }) });
+}
+
+export function assertSecurityReviewProviderRegistration(provider, expectedId, options = {}) {
+  const validated = assertSecurityReviewProvider(provider, options);
+  if (validated.id !== expectedId) throw providerError(`Provider id "${validated.id}" does not match registry key "${expectedId}".`);
+  return validated;
+}
+
+export function createSecurityReviewProviderRegistry(providers = {}) {
+  if (!providers || typeof providers !== "object" || Array.isArray(providers)) {
+    throw providerError("Security-review provider registry source must be an object or Map.");
+  }
+  const entries = providers instanceof Map ? [...providers.entries()] : Object.entries(providers);
+  const registry = {};
+  for (const [name, provider] of entries) {
+    if (typeof name !== "string" || !SECURITY_REVIEW_PROVIDER_ID_PATTERN.test(name)) {
+      throw providerError(`Invalid security-review provider ID: ${name}.`);
+    }
+    if (typeof provider === "function") registry[name] = provider;
+    else registry[name] = assertSecurityReviewProviderRegistration(provider, name, { label: `security-review provider "${name}"` });
+  }
+  return deepFreeze({ ...registry });
+}
+
+export async function resolveSecurityReviewProvider(providers, name, input = {}) {
+  if (typeof name !== "string" || !SECURITY_REVIEW_PROVIDER_ID_PATTERN.test(name)) {
+    throw unavailableError("Security-review provider name is invalid.", { name });
+  }
+  const registry = providers ?? {};
+  const entry = registry instanceof Map ? registry.get(name) : registry[name];
+  if (!entry) throw unavailableError(`Security-review provider "${name}" is not registered.`, { name });
+  const provider = typeof entry === "function" ? await entry(input) : entry;
+  return assertSecurityReviewProviderRegistration(provider, name, { label: `security-review provider "${name}"` });
+}

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

@@ -0,0 +1,134 @@
+import {
+  E_SECURITY_REVIEW_CANCELLED,
+  E_SECURITY_REVIEW_EXECUTION_FAILED,
+  E_SECURITY_REVIEW_OUTPUT_LIMIT,
+  E_SECURITY_REVIEW_PROVIDER_INVALID,
+  E_SECURITY_REVIEW_PROVIDER_UNAVAILABLE,
+  E_SECURITY_REVIEW_REQUEST_INVALID,
+  E_SECURITY_REVIEW_RESULT_INVALID,
+  E_SECURITY_REVIEW_TIMEOUT,
+} from "../error-codes.js";
+import { normalizeSecurityReviewRequest, resolveSecurityReviewProvider } from "./provider.js";
+import { SECURITY_REVIEW_LIMITS } from "./constants.js";
+import { normalizeSecurityReviewResult } from "./normalize.js";
+
+function error(code, message, details = null) {
+  const output = new Error(message);
+  output.code = code;
+  output.details = details;
+  return output;
+}
+
+function timeoutError(providerName, reviewId) {
+  return error(E_SECURITY_REVIEW_TIMEOUT, `Security review provider "${providerName}" timed out.`, { provider: providerName, reviewId });
+}
+
+function cancelledError(providerName, reviewId) {
+  return error(E_SECURITY_REVIEW_CANCELLED, `Security review provider "${providerName}" was cancelled.`, { provider: providerName, reviewId });
+}
+
+function safeFailure(providerName) {
+  return error(E_SECURITY_REVIEW_EXECUTION_FAILED, `Security review provider "${providerName}" failed.`, { provider: providerName });
+}
+
+async function bounded(factory, { controller, callerSignal, deadline, providerName, reviewId }) {
+  const remaining = () => Math.max(0, deadline - Date.now());
+  if (callerSignal?.aborted) {
+    controller.abort();
+    throw cancelledError(providerName, reviewId);
+  }
+  if (remaining() <= 0) {
+    controller.abort();
+    throw timeoutError(providerName, reviewId);
+  }
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => {
+      clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onAbort);
+    };
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      callback(value);
+    };
+    const onAbort = () => {
+      controller.abort();
+      finish(reject, cancelledError(providerName, reviewId));
+    };
+    const timer = setTimeout(() => {
+      controller.abort();
+      finish(reject, timeoutError(providerName, reviewId));
+    }, remaining());
+    callerSignal?.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve()
+      .then(() => factory(remaining()))
+      .then((value) => finish(resolve, value), (failure) => finish(reject, failure));
+  });
+}
+
+export async function runSecurityReview({
+  projectPath, taskId, providerName, reviewId, scope, paths, categories, requirements, revision,
+  timeoutMs, runtimeContext, signal,
+} = {}) {
+  const normalized = normalizeSecurityReviewRequest({
+    projectPath, taskId, reviewId, scope, paths, categories, requirements, revision, timeoutMs,
+  });
+  const controller = new AbortController();
+  const deadline = Date.now() + normalized.timeoutMs;
+  const providers = runtimeContext?.securityReviewProviders;
+  try {
+    const provider = await bounded(
+      (remaining) => resolveSecurityReviewProvider(providers, providerName, {
+        signal: controller.signal,
+        timeoutMs: remaining,
+        request: normalized,
+      }),
+      { controller, callerSignal: signal, deadline, providerName, reviewId: normalized.reviewId },
+    );
+    const raw = await bounded(
+      (remaining) => provider.review(Object.freeze({ ...normalized, signal: controller.signal, timeoutMs: remaining })),
+      { controller, callerSignal: signal, deadline, providerName, reviewId: normalized.reviewId },
+    );
+    if (controller.signal.aborted) {
+      if (signal?.aborted) throw cancelledError(providerName, normalized.reviewId);
+      throw timeoutError(providerName, normalized.reviewId);
+    }
+    if (Date.now() >= deadline) {
+      controller.abort();
+      throw timeoutError(providerName, normalized.reviewId);
+    }
+    const result = normalizeSecurityReviewResult(raw, {
+      provider,
+      taskId: normalized.taskId,
+      reviewId: normalized.reviewId,
+      scope: normalized.scope,
+      requestedPaths: normalized.paths,
+    });
+    if (Date.now() >= deadline) {
+      controller.abort();
+      throw timeoutError(providerName, normalized.reviewId);
+    }
+    return result;
+  } catch (failure) {
+    if ([
+      E_SECURITY_REVIEW_REQUEST_INVALID,
+      E_SECURITY_REVIEW_RESULT_INVALID,
+      E_SECURITY_REVIEW_OUTPUT_LIMIT,
+      E_SECURITY_REVIEW_TIMEOUT,
+      E_SECURITY_REVIEW_CANCELLED,
+      E_SECURITY_REVIEW_PROVIDER_INVALID,
+    ].includes(failure?.code)) {
+      if ([E_SECURITY_REVIEW_TIMEOUT, E_SECURITY_REVIEW_CANCELLED].includes(failure.code)) controller.abort();
+      throw failure;
+    }
+    if (failure?.code === E_SECURITY_REVIEW_PROVIDER_UNAVAILABLE
+      && failure.message.includes("not registered")) throw failure;
+    controller.abort();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    throw safeFailure(providerName);
+  }
+}
+
+export { SECURITY_REVIEW_LIMITS };

package/src/core/semantic-planning/constants.js

@@ -0,0 +1,19 @@
+export const FAILURE_CLASSES = Object.freeze([
+  "incorrect implementation", "stale expectation", "race condition", "state divergence",
+  "dependency incompatibility", "configuration defect", "fixture defect", "timeout",
+  "network/environment", "serialization mismatch", "ownership/protocol mismatch", "unknown",
+]);
+
+export const DIAGNOSIS_STRATEGIES = Object.freeze([
+  "inspect caller", "inspect callee", "inspect state transition", "inspect dependency behavior",
+  "inspect config", "inspect concurrency path", "inspect fixture", "inspect package boundary",
+  "run narrower experiment", "run independent checker", "inspect historical regression",
+]);
+
+export const REVIEW_FOCUSES = Object.freeze([
+  "needs_security_review", "needs_api_compatibility_review", "needs_concurrency_review",
+  "needs_package_review", "needs_docs_review", "needs_migration_review",
+  "needs_performance_review", "needs_dependency_review", "needs_full_diff_context",
+  "needs_primary_model",
+]);
+