@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/core/decision/errors.js

@@ -0,0 +1,68 @@
+export const DECISION_ERROR_CODES = Object.freeze({
+  ENGINE_UNAVAILABLE: "E_DECISION_ENGINE_UNAVAILABLE",
+  AUTH_REQUIRED: "E_DECISION_ENGINE_AUTH_REQUIRED",
+  AUTH_INVALID: "E_DECISION_ENGINE_AUTH_INVALID",
+  MODEL_UNSUPPORTED: "E_DECISION_MODEL_UNSUPPORTED",
+  REQUEST_INVALID: "E_DECISION_REQUEST_INVALID",
+  RESULT_INVALID: "E_DECISION_RESULT_INVALID",
+  TIMEOUT: "E_DECISION_TIMEOUT",
+  RATE_LIMITED: "E_DECISION_RATE_LIMITED",
+  STATE_UNSAFE: "E_DECISION_STATE_UNSAFE",
+  STATE_LIMIT: "E_DECISION_STATE_LIMIT",
+  LOW_CONFIDENCE: "E_DECISION_LOW_CONFIDENCE",
+  STALE: "E_DECISION_STALE",
+  POLICY_INVALID: "E_DECISION_POLICY_INVALID",
+  CACHE_INVALID: "E_DECISION_CACHE_INVALID",
+  QUESTION_SET_UNKNOWN: "E_DECISION_QUESTION_SET_UNKNOWN",
+  QUESTION_SET_STALE: "E_DECISION_QUESTION_SET_STALE",
+  REQUIRED: "E_DECISION_REQUIRED",
+  IMMUTABLE: "E_DECISION_IMMUTABLE",
+  LEDGER_INVALID: "E_DECISION_LEDGER_INVALID",
+  BINDING_INVALID: "E_DECISION_BINDING_INVALID",
+});
+
+export class DecisionError extends Error {
+  constructor(code, message, artifacts = []) {
+    super(message);
+    this.name = "DecisionError";
+    this.code = code;
+    this.artifacts = artifacts;
+  }
+}
+
+export function decisionError(code, message, artifacts = []) {
+  return new DecisionError(code, message, artifacts);
+}
+
+const NETWORK_ERROR_CODES = new Set(["ENOTFOUND", "EAI_AGAIN", "ECONNREFUSED", "ECONNRESET", "EPIPE", "EHOSTUNREACH", "ENETUNREACH"]);
+
+export function classifyProviderFailure(error) {
+  const status = Number(error?.status);
+  const detail = error?.body?.detail;
+  const providerErrorType = typeof detail?.error_type === "string" ? detail.error_type : null;
+  const requestId = typeof error?.requestId === "string" && /^[A-Za-z0-9_-]{1,64}$/u.test(error.requestId) ? error.requestId : null;
+  let networkClass = null;
+  if (error?.name === "APITimeoutError" || error?.code === "ETIMEDOUT") networkClass = "timeout";
+  else if (error?.name === "APIConnectionError" || NETWORK_ERROR_CODES.has(error?.code)) networkClass = "connection";
+  return {
+    httpStatus: Number.isFinite(status) ? status : null,
+    providerErrorType,
+    requestId,
+    networkClass,
+  };
+}
+
+export function safeDecisionError(error, fallbackCode = DECISION_ERROR_CODES.ENGINE_UNAVAILABLE) {
+  if (error instanceof DecisionError) return error;
+  const diagnostics = classifyProviderFailure(error);
+  const build = (code, message) => {
+    const normalized = decisionError(code, message);
+    normalized.diagnostics = diagnostics;
+    return normalized;
+  };
+  if (diagnostics.httpStatus === 401 || diagnostics.httpStatus === 403) return build(DECISION_ERROR_CODES.AUTH_INVALID, "The semantic decision service rejected authentication.");
+  if (diagnostics.httpStatus === 429) return build(DECISION_ERROR_CODES.RATE_LIMITED, "The semantic decision service rate limit was reached.");
+  if (diagnostics.networkClass === "timeout") return build(DECISION_ERROR_CODES.TIMEOUT, "The semantic decision request timed out.");
+  if (error?.name === "AuthenticationError") return build(DECISION_ERROR_CODES.AUTH_INVALID, "The semantic decision service rejected authentication.");
+  return build(fallbackCode, "The semantic decision service is unavailable.");
+}

package/src/core/decision/events.js

@@ -0,0 +1,101 @@
+import { canonicalFingerprint } from "../artifacts.js";
+import { readDecisionArtifact } from "./artifact.js";
+import { DECISION_KINDS, DECISION_STATUS, SEMANTIC_DECISION_RECORDED_EVENT, SEMANTIC_DECISION_SUPERSEDED_EVENT } from "./constants.js";
+import { DECISION_ERROR_CODES } from "./errors.js";
+
+const HEX = /^[a-f0-9]{64}$/;
+
+export function assertSemanticDecisionDetails(details, eventName = SEMANTIC_DECISION_RECORDED_EVENT) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) throw Object.assign(new Error(`${eventName} requires structured details`), { code: DECISION_ERROR_CODES.RESULT_INVALID });
+  for (const key of ["decisionId", "decisionKind", "artifactFingerprint", "questionSetFingerprint", "stateFingerprint", "model"]) {
+    if (typeof details[key] !== "string" || !details[key]) throw Object.assign(new Error(`${eventName} details.${key} is required`), { code: DECISION_ERROR_CODES.RESULT_INVALID });
+  }
+  if (!DECISION_KINDS.includes(details.decisionKind) || details.model !== "jev-1.13.0" || !HEX.test(details.artifactFingerprint) || !HEX.test(details.questionSetFingerprint) || !HEX.test(details.stateFingerprint)) {
+    throw Object.assign(new Error(`${eventName} details are invalid`), { code: DECISION_ERROR_CODES.RESULT_INVALID });
+  }
+  if (eventName === SEMANTIC_DECISION_RECORDED_EVENT && details.status !== undefined && !DECISION_STATUS.includes(details.status)) {
+    throw Object.assign(new Error(`${eventName} details.status is invalid`), { code: DECISION_ERROR_CODES.RESULT_INVALID });
+  }
+  if (eventName === SEMANTIC_DECISION_SUPERSEDED_EVENT && (typeof details.supersededBy !== "string" || !details.supersededBy)) {
+    throw Object.assign(new Error(`${eventName} details.supersededBy is required`), { code: DECISION_ERROR_CODES.RESULT_INVALID });
+  }
+}
+
+export function decisionEventDetails(artifact) {
+  return {
+    decisionId: artifact.decisionId,
+    decisionKind: artifact.decisionKind,
+    artifactFingerprint: canonicalFingerprint(artifact),
+    questionSetFingerprint: artifact.questionSetFingerprint,
+    stateFingerprint: artifact.stateFingerprint,
+    model: artifact.model,
+    status: "RECORDED",
+  };
+}
+
+export function decisionSupersededEventDetails(previousArtifact, supersededBy) {
+  return {
+    ...decisionEventDetails(previousArtifact),
+    supersededBy,
+  };
+}
+
+export function validateSemanticDecisionEventBindings(events = []) {
+  const errors = [];
+  const recorded = new Map();
+  for (const event of events) {
+    if (![SEMANTIC_DECISION_RECORDED_EVENT, SEMANTIC_DECISION_SUPERSEDED_EVENT].includes(event.event)) continue;
+    try { assertSemanticDecisionDetails(event.details, event.event); } catch (error) {
+      errors.push({ code: error.code ?? DECISION_ERROR_CODES.RESULT_INVALID, message: `event ${event.seq} (${event.event}): ${error.message}` });
+      continue;
+    }
+    if (event.event === SEMANTIC_DECISION_RECORDED_EVENT) {
+      const key = `${event.taskId}:${event.details.decisionId}`;
+      if (recorded.has(key)) {
+        errors.push({ code: DECISION_ERROR_CODES.RESULT_INVALID, message: `event ${event.seq} records duplicate decision ID ${event.details.decisionId}` });
+      }
+      recorded.set(key, event);
+    }
+    if (event.event === SEMANTIC_DECISION_SUPERSEDED_EVENT) {
+      const key = `${event.taskId}:${event.details.decisionId}`;
+      if (!recorded.has(key)) errors.push({ code: DECISION_ERROR_CODES.RESULT_INVALID, message: `event ${event.seq} supersedes a decision that was not recorded` });
+      if (!recorded.has(`${event.taskId}:${event.details.supersededBy}`)) {
+        errors.push({ code: DECISION_ERROR_CODES.RESULT_INVALID, message: `event ${event.seq} points to a superseding decision that was not recorded` });
+      }
+      const next = events.find((candidate) => candidate.seq === event.seq + 1);
+      if (next?.event !== "TRANSACTION_COMMITTED" || next.taskId !== event.taskId || next.details?.operation !== "semantic-decision") {
+        errors.push({ code: DECISION_ERROR_CODES.LEDGER_INVALID, message: `event ${event.seq} supersession is not closed by a semantic-decision transaction` });
+      }
+    }
+    if (event.event === SEMANTIC_DECISION_RECORDED_EVENT) {
+      const next = events.find((candidate) => candidate.seq === event.seq + 1);
+      const closesDirectly = next?.event === "TRANSACTION_COMMITTED" && next.taskId === event.taskId && next.details?.operation === "semantic-decision";
+      const continuesWithSupersession = next?.event === SEMANTIC_DECISION_SUPERSEDED_EVENT && next.taskId === event.taskId;
+      if (!closesDirectly && !continuesWithSupersession) {
+        errors.push({ code: DECISION_ERROR_CODES.LEDGER_INVALID, message: `event ${event.seq} is not closed by the semantic-decision transaction boundary` });
+      }
+    }
+  }
+  return errors;
+}
+
+export async function validateSemanticDecisionArtifactBindings(target, packageRoot, events = []) {
+  const errors = [];
+  for (const event of events) {
+    if (event.event !== SEMANTIC_DECISION_RECORDED_EVENT) continue;
+    try {
+      const artifact = (await readDecisionArtifact(target, event.taskId, event.details.decisionId, packageRoot)).value;
+      if (artifact.taskId !== event.taskId
+        || artifact.decisionId !== event.details.decisionId
+        || canonicalFingerprint(artifact) !== event.details.artifactFingerprint
+        || artifact.questionSetFingerprint !== event.details.questionSetFingerprint
+        || artifact.stateFingerprint !== event.details.stateFingerprint
+        || artifact.model !== event.details.model) {
+        errors.push({ code: DECISION_ERROR_CODES.LEDGER_INVALID, message: `event ${event.seq} does not match its immutable semantic decision artifact` });
+      }
+    } catch (error) {
+      errors.push({ code: DECISION_ERROR_CODES.LEDGER_INVALID, message: `event ${event.seq} semantic decision artifact is unavailable or invalid` });
+    }
+  }
+  return errors;
+}

package/src/core/decision/freshness.js

@@ -0,0 +1,19 @@
+import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
+
+export function decisionFreshnessErrors(artifact, current = {}) {
+  if (!artifact || typeof artifact !== "object") return [{ code: DECISION_ERROR_CODES.CACHE_INVALID, message: "Semantic decision artifact is missing." }];
+  const bindings = [
+    "stateFingerprint", "taskStateFingerprint", "semanticStateFingerprint",
+    "repositoryFingerprint", "contractFingerprint", "routeFingerprint",
+    "verificationCycle", "questionSetFingerprint", "policyFingerprint", "model",
+    "candidateSetFingerprint",
+  ];
+  return bindings.flatMap((key) => artifact[key] !== undefined && current[key] !== undefined && JSON.stringify(artifact[key]) !== JSON.stringify(current[key])
+    ? [{ code: DECISION_ERROR_CODES.STALE, message: `Semantic decision binding is stale: ${key}` }] : []);
+}
+
+export function assertDecisionFresh(artifact, current) {
+  const errors = decisionFreshnessErrors(artifact, current);
+  if (errors.length) throw decisionError(DECISION_ERROR_CODES.STALE, errors[0].message);
+  return artifact;
+}

package/src/core/decision/normalizers/index.js

@@ -0,0 +1,115 @@
+import { DECISION_ERROR_CODES, decisionError } from "../errors.js";
+
+function answerValue(answer) {
+  if (answer && typeof answer === "object" && !Array.isArray(answer)) {
+    for (const key of ["choice", "noul", "value", "answer"]) {
+      if (Object.prototype.hasOwnProperty.call(answer, key)) return answer[key];
+    }
+  }
+  return answer;
+}
+
+function boolAnswer(value) {
+  if (value === true || value === "yes" || value === "YES") return true;
+  if (value === false || value === "no" || value === "NO") return false;
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1) return value >= 0.5;
+  return null;
+}
+
+function unique(values) {
+  return [...new Set(values.filter((value) => typeof value === "string" && value.length > 0))];
+}
+
+function normalizeQuestionSetAnswers(questionSet, answers) {
+  const normalized = {};
+  for (const [name, question] of Object.entries(questionSet.questions)) {
+    const value = answerValue(answers[name]);
+    if (question.type === "choice") {
+      if (typeof value !== "string" || !Object.prototype.hasOwnProperty.call(question.criteria, value)) {
+        throw decisionError(DECISION_ERROR_CODES.RESULT_INVALID, `Semantic answer ${name} is outside the canonical vocabulary.`);
+      }
+      normalized[name] = value;
+    } else {
+      const bool = boolAnswer(value);
+      if (bool === null) throw decisionError(DECISION_ERROR_CODES.RESULT_INVALID, `Semantic answer ${name} must be yes or no.`);
+      normalized[name] = bool;
+    }
+  }
+  return normalized;
+}
+
+function normalizeConfidence(questionSet, confidence) {
+  return Object.fromEntries(Object.keys(questionSet.questions).map((name) => {
+    const value = confidence?.[name];
+    if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1)) {
+      throw decisionError(DECISION_ERROR_CODES.RESULT_INVALID, `Semantic confidence ${name} must be finite and between 0 and 1.`);
+    }
+    return [name, value ?? null];
+  }));
+}
+
+function normalizeModelRouteDecision(answers, confidence) {
+  const reasoning = answers.reasoning_depth;
+  return {
+    tier: reasoning,
+    generationRequired: answers.generation_required,
+    confidence: confidence.reasoning_depth,
+    requiresEscalation: reasoning === "PRIMARY" || confidence.reasoning_depth === null || confidence.reasoning_depth < 0.75,
+  };
+}
+
+function normalizeExecutionProfileDecision(answers, confidence) {
+  return {
+    recommendedProfile: answers.recommended_depth,
+    confidence: confidence.recommended_depth,
+    needsBroadContext: answers.needs_broad_context,
+    needsDeepReview: answers.needs_deep_review,
+    highAmbiguity: answers.high_ambiguity,
+    crossComponentReasoning: answers.cross_component_reasoning,
+  };
+}
+
+function candidateProjection(questionSet, answers, confidence, ids, prefix) {
+  const rankedIds = [];
+  const excludedIds = [];
+  const confidenceById = {};
+  for (const [index, id] of ids.entries()) {
+    const key = `${prefix}${index}_relevant`;
+    confidenceById[id] = confidence[key];
+    if (answers[key] === true) rankedIds.push(id);
+    else if (answers[key] === false) excludedIds.push(id);
+  }
+  rankedIds.sort((a, b) => (confidence[`${prefix}${ids.indexOf(a)}_relevant`] ?? 0) - (confidence[`${prefix}${ids.indexOf(b)}_relevant`] ?? 0));
+  return { rankedIds: rankedIds.reverse(), excludedIds, confidenceById };
+}
+
+function projectDecision(questionSet, answers, confidence, input) {
+  const projections = {
+    INTAKE: () => ({ dimensions: answers }),
+    CONTRACT_APPLICABILITY: () => ({ applicable: answers.applicable }),
+    ROUTE: () => (questionSet.metadata?.candidateQuestionPrefix
+      ? candidateProjection(questionSet, answers, confidence, questionSet.candidateIds ?? [], questionSet.metadata.candidateQuestionPrefix)
+      : { relevantGuides: unique([answers.relevant_guides]) }),
+    EXECUTION_PROFILE: () => normalizeExecutionProfileDecision(answers, confidence),
+    CONTEXT_PLAN: () => (questionSet.metadata?.candidateQuestionPrefix
+      ? { needs: answers, ...candidateProjection(questionSet, answers, confidence, questionSet.candidateIds ?? [], questionSet.metadata.candidateQuestionPrefix) }
+      : { needs: answers }),
+    MODEL_ROUTE: () => normalizeModelRouteDecision(answers, confidence),
+    FAILURE_TRIAGE: () => ({ failureClass: answers.failure_class }),
+    DIAGNOSIS_PRIORITY: () => ({ priority: answers.priority }),
+    REVIEW_PLAN: () => ({ reviewFocus: answers }),
+    TASK_OVERLAP: () => ({ relationship: answers.relationship }),
+    TEST_UTILITY: () => (questionSet.metadata?.testCount
+      ? { judgments: answers, candidateIds: unique(questionSet.candidateIds ?? input.candidateIds ?? []), tests: Object.fromEntries((questionSet.candidateIds ?? []).map((id, index) => [id, Object.fromEntries((questionSet.metadata.dimensions ?? []).map((dimension) => [dimension, answers[`test_${index}_${dimension}`]]))])) }
+      : { judgments: answers, candidateIds: unique(input.candidateIds ?? []) }),
+    TEST_PRUNE: () => ({ redundancy: answers.redundancy }),
+  };
+  const project = projections[questionSet.decisionKind];
+  if (!project) throw decisionError(DECISION_ERROR_CODES.RESULT_INVALID, `No canonical normalizer exists for ${questionSet.decisionKind}.`);
+  return project();
+}
+
+export function normalizeCanonicalDecision({ questionSet, answers = {}, input = {}, confidence = {} } = {}) {
+  const normalizedAnswers = normalizeQuestionSetAnswers(questionSet, answers);
+  return projectDecision(questionSet, normalizedAnswers, normalizeConfidence(questionSet, confidence), input);
+}

package/src/core/decision/policy.js

@@ -0,0 +1,18 @@
+import { canonicalFingerprint } from "../artifacts.js";
+import { DECISION_DEFAULT_POLICY, DECISION_ENGINE_ID, PINNED_JEV_MODEL } from "./constants.js";
+import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
+
+export function normalizeDecisionPolicy(input = {}) {
+  const policy = { ...DECISION_DEFAULT_POLICY, ...input };
+  if (policy.required !== true || policy.provider !== DECISION_ENGINE_ID || policy.model !== PINNED_JEV_MODEL) {
+    throw decisionError(DECISION_ERROR_CODES.POLICY_INVALID, "ForgeLoop Jev policy must remain mandatory and pinned.");
+  }
+  if (!Number.isInteger(policy.policyVersion) || policy.policyVersion < 1 || !Number.isInteger(policy.requestTimeoutMs) || policy.requestTimeoutMs < 500 || policy.requestTimeoutMs > 60_000 || !Number.isInteger(policy.maxRetries) || policy.maxRetries < 0 || policy.maxRetries > 3 || typeof policy.cache !== "boolean") {
+    throw decisionError(DECISION_ERROR_CODES.POLICY_INVALID, "ForgeLoop Jev policy limits are invalid.");
+  }
+  return Object.freeze(policy);
+}
+
+export function decisionPolicyFingerprint(policy) {
+  return canonicalFingerprint(normalizeDecisionPolicy(policy));
+}

package/src/core/decision/projection.js

@@ -0,0 +1,16 @@
+export function projectSemanticDecisionStatus({ artifact = null, fresh = false, errorCodes = [] } = {}) {
+  return {
+    required: true,
+    engine: "typesafe-jev",
+    model: "jev-1.13.0",
+    authority: "SEMANTIC_DECISION",
+    evidenceAuthority: "NONE",
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    ownershipAuthority: false,
+    installationAuthority: false,
+    status: artifact ? (fresh ? "FRESH" : "STALE") : "ABSENT",
+    decisionId: artifact?.decisionId ?? null,
+    errorCodes: [...errorCodes],
+  };
+}

package/src/core/decision/question-registry.js

@@ -0,0 +1,201 @@
+import { canonicalFingerprint } from "../artifacts.js";
+import { DECISION_QUESTION_SETS } from "./constants.js";
+import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
+
+function freezeQuestionSet(definition) {
+  return Object.freeze({
+    ...definition,
+    questions: Object.freeze({ ...definition.questions }),
+    fingerprint: canonicalFingerprint(definition.questions),
+  });
+}
+
+const QUESTION_SET_DEFINITIONS = Object.freeze({
+  "contract-v1": Object.freeze({
+    id: "contract-v1", version: 1, decisionKind: "CONTRACT_APPLICABILITY",
+    questions: Object.freeze({ applicable: { type: "noul", criteria: { yes: "Contract applies to the requested work", no: "Contract scope is not applicable" } } }),
+  }),
+  "route-v1": Object.freeze({
+    id: "route-v1", version: 1, decisionKind: "ROUTE",
+    questions: Object.freeze({ relevant_guides: { type: "choice", criteria: { clean: "General engineering hygiene", test: "Testing context", security: "Security context", unknown: "Insufficient information" } } }),
+  }),
+  "execution-profile-v1": Object.freeze({
+    id: "execution-profile-v1", version: 1, decisionKind: "EXECUTION_PROFILE",
+    questions: Object.freeze({
+      recommended_depth: { type: "choice", criteria: { light: "Light bounded context", balanced: "Normal engineering context", full: "Deep broad context" } },
+      needs_broad_context: { type: "noul", criteria: { yes: "Broad context is needed", no: "Broad context is not needed" } },
+      needs_deep_review: { type: "noul", criteria: { yes: "Deep review is needed", no: "Deep review is not needed" } },
+      high_ambiguity: { type: "noul", criteria: { yes: "The task is highly ambiguous", no: "The task is not highly ambiguous" } },
+      cross_component_reasoning: { type: "noul", criteria: { yes: "Cross-component reasoning is needed", no: "Cross-component reasoning is not needed" } },
+    }),
+  }),
+  "intake-v1": Object.freeze({
+    id: "intake-v1", version: 1, decisionKind: "INTAKE",
+    questions: Object.freeze({
+      work_type: { type: "choice", criteria: { documentation: "Documentation or prose change", code: "Executable code change", security: "Security-sensitive change", unknown: "Insufficient information" } },
+      backend: { type: "noul", criteria: { yes: "Backend is affected", no: "Backend is not affected" } },
+      frontend: { type: "noul", criteria: { yes: "Frontend is affected", no: "Frontend is not affected" } },
+      authentication: { type: "noul", criteria: { yes: "Authentication is affected", no: "Authentication is not affected" } },
+      authorization: { type: "noul", criteria: { yes: "Authorization is affected", no: "Authorization is not affected" } },
+      security: { type: "noul", criteria: { yes: "Security is materially relevant", no: "Security is not materially relevant" } },
+      database: { type: "noul", criteria: { yes: "Database behavior is affected", no: "Database behavior is not affected" } },
+      network: { type: "noul", criteria: { yes: "Network behavior is affected", no: "Network behavior is not affected" } },
+      public_api: { type: "noul", criteria: { yes: "A public API is affected", no: "No public API is affected" } },
+      behavior_change: { type: "noul", criteria: { yes: "Behavior changes", no: "Behavior does not change" } },
+      executable_change: { type: "noul", criteria: { yes: "Executable content changes", no: "Executable content does not change" } },
+      dependency_change: { type: "noul", criteria: { yes: "Dependencies change", no: "Dependencies do not change" } },
+      migration: { type: "noul", criteria: { yes: "A migration is involved", no: "No migration is involved" } },
+      publication: { type: "noul", criteria: { yes: "Publication is involved", no: "Publication is not involved" } },
+      documentation: { type: "noul", criteria: { yes: "Documentation is materially relevant", no: "Documentation is not materially relevant" } },
+      package: { type: "noul", criteria: { yes: "Package behavior is affected", no: "Package behavior is not affected" } },
+      ci: { type: "noul", criteria: { yes: "CI behavior is affected", no: "CI behavior is not affected" } },
+      performance: { type: "noul", criteria: { yes: "Performance is materially relevant", no: "Performance is not materially relevant" } },
+      accessibility: { type: "noul", criteria: { yes: "Accessibility is materially relevant", no: "Accessibility is not materially relevant" } },
+      compatibility: { type: "noul", criteria: { yes: "Compatibility is materially relevant", no: "Compatibility is not materially relevant" } },
+      data_sensitivity: { type: "noul", criteria: { yes: "Sensitive data is involved", no: "Sensitive data is not involved" } },
+      operational_risk: { type: "noul", criteria: { yes: "Operational risk is elevated", no: "Operational risk is not elevated" } },
+    }),
+  }),
+  "context-v1": Object.freeze({
+    id: "context-v1", version: 1, decisionKind: "CONTEXT_PLAN",
+    questions: Object.freeze({
+      need_task_history: { type: "noul", criteria: { yes: "Task history is needed", no: "Task history is not needed" } },
+      need_relevant_artifacts: { type: "noul", criteria: { yes: "Relevant artifacts are needed", no: "Relevant artifacts are not needed" } },
+      need_dependency_context: { type: "noul", criteria: { yes: "Dependency context is needed", no: "Dependency context is not needed" } },
+      need_security_context: { type: "noul", criteria: { yes: "Security context is needed", no: "Security context is not needed" } },
+      need_review_context: { type: "noul", criteria: { yes: "Review context is needed", no: "Review context is not needed" } },
+      need_verification_context: { type: "noul", criteria: { yes: "Verification context is needed", no: "Verification context is not needed" } },
+      need_advisory_context: { type: "noul", criteria: { yes: "Advisory context is needed", no: "Advisory context is not needed" } },
+      need_repository_snippets: { type: "noul", criteria: { yes: "Repository snippets are needed", no: "Repository snippets are not needed" } },
+      need_external_docs: { type: "noul", criteria: { yes: "External documentation is needed", no: "External documentation is not needed" } },
+    }),
+  }),
+  "model-route-v1": Object.freeze({
+    id: "model-route-v1", version: 1, decisionKind: "MODEL_ROUTE",
+    questions: Object.freeze({ generation_required: { type: "noul", criteria: { yes: "Generation is required", no: "A deterministic or semantic-only decision is sufficient" } }, reasoning_depth: { type: "choice", criteria: { NONE: "No generation or deep reasoning", FAST: "Small bounded reasoning", STANDARD: "Cross-file reasoning", PRIMARY: "Architecture or high ambiguity reasoning" } } }),
+  }),
+  "failure-v1": Object.freeze({
+    id: "failure-v1", version: 1, decisionKind: "FAILURE_TRIAGE",
+    questions: Object.freeze({ failure_class: { type: "choice", criteria: { implementation: "Incorrect implementation", expectation: "Stale expectation", state: "State divergence", dependency: "Dependency incompatibility", environment: "Network or environment issue", unknown: "Insufficient information" } } }),
+  }),
+  "diagnosis-v1": Object.freeze({
+    id: "diagnosis-v1", version: 1, decisionKind: "DIAGNOSIS_PRIORITY",
+    questions: Object.freeze({ priority: { type: "choice", criteria: { inspect_state: "Inspect state transition", inspect_caller: "Inspect caller", inspect_dependency: "Inspect dependency behavior", narrow_experiment: "Run a narrower experiment", unknown: "Insufficient information" } } }),
+  }),
+  "review-v1": Object.freeze({
+    id: "review-v1", version: 1, decisionKind: "REVIEW_PLAN",
+    questions: Object.freeze({
+      needs_security_review: { type: "noul", criteria: { yes: "Security review is needed", no: "Security review is not needed" } },
+      needs_api_compatibility_review: { type: "noul", criteria: { yes: "API compatibility review is needed", no: "API compatibility review is not needed" } },
+      needs_concurrency_review: { type: "noul", criteria: { yes: "Concurrency review is needed", no: "Concurrency review is not needed" } },
+      needs_package_review: { type: "noul", criteria: { yes: "Package review is needed", no: "Package review is not needed" } },
+      needs_docs_review: { type: "noul", criteria: { yes: "Documentation review is needed", no: "Documentation review is not needed" } },
+      needs_migration_review: { type: "noul", criteria: { yes: "Migration review is needed", no: "Migration review is not needed" } },
+      needs_performance_review: { type: "noul", criteria: { yes: "Performance review is needed", no: "Performance review is not needed" } },
+      needs_dependency_review: { type: "noul", criteria: { yes: "Dependency review is needed", no: "Dependency review is not needed" } },
+      needs_full_diff_context: { type: "noul", criteria: { yes: "Full diff context is needed", no: "Full diff context is not needed" } },
+      needs_primary_model: { type: "noul", criteria: { yes: "Primary model reasoning is needed", no: "Primary model reasoning is not needed" } },
+    }),
+  }),
+  "test-utility-v1": Object.freeze({
+    id: "test-utility-v1", version: 1, decisionKind: "TEST_UTILITY",
+    questions: Object.freeze({
+      validates_required_behavior: { type: "noul", criteria: { yes: "Test validates required behavior", no: "Test does not validate required behavior" } },
+      guards_public_contract: { type: "noul", criteria: { yes: "Test guards a public contract", no: "Test does not guard a public contract" } },
+      guards_security_boundary: { type: "noul", criteria: { yes: "Test guards a security boundary", no: "Test does not guard a security boundary" } },
+      guards_failure_mode: { type: "noul", criteria: { yes: "Test guards a failure mode", no: "Test does not guard a failure mode" } },
+      guards_regression_prone_behavior: { type: "noul", criteria: { yes: "Test guards regression-prone behavior", no: "Test does not guard regression-prone behavior" } },
+      has_unique_semantic_intent: { type: "noul", criteria: { yes: "Test has unique semantic intent", no: "Test has overlapping semantic intent" } },
+      semantic_duplicate: { type: "noul", criteria: { yes: "Test is a semantic duplicate", no: "Test is not a semantic duplicate" } },
+      likely_obsolete: { type: "noul", criteria: { yes: "Test is likely obsolete", no: "Test is not likely obsolete" } },
+      likely_flaky_low_signal: { type: "noul", criteria: { yes: "Test is likely flaky and low signal", no: "Test is not likely flaky and low signal" } },
+      expensive_relative_to_signal: { type: "noul", criteria: { yes: "Test is expensive relative to signal", no: "Test is not expensive relative to signal" } },
+      documentation_value: { type: "noul", criteria: { yes: "Test has documentation value", no: "Test lacks documentation value" } },
+      integration_value: { type: "noul", criteria: { yes: "Test has integration value", no: "Test lacks integration value" } },
+      platform_specific_value: { type: "noul", criteria: { yes: "Test has platform-specific value", no: "Test lacks platform-specific value" } },
+      protocol_invariant: { type: "noul", criteria: { yes: "Test protects a protocol invariant", no: "Test does not protect a protocol invariant" } },
+      requires_system_two_review: { type: "noul", criteria: { yes: "Test requires System Two review", no: "Test does not require System Two review" } },
+    }),
+  }),
+  "task-overlap-v1": Object.freeze({
+    id: "task-overlap-v1", version: 1, decisionKind: "TASK_OVERLAP",
+    questions: Object.freeze({ relationship: { type: "choice", criteria: { SAME_PROBLEM: "Same problem", RELATED: "Related problem", INDEPENDENT: "Independent problem", UNKNOWN: "Insufficient information" } } }),
+  }),
+  "test-prune-v1": Object.freeze({
+    id: "test-prune-v1", version: 1, decisionKind: "TEST_PRUNE",
+    questions: Object.freeze({ redundancy: { type: "choice", criteria: { DISTINCT_BEHAVIOR: "Distinct behavior", PARTIALLY_OVERLAPPING: "Partially overlapping", SEMANTIC_DUPLICATE: "Semantic duplicate", UNKNOWN: "Insufficient information" } } }),
+  }),
+});
+
+export function getQuestionSet(id) {
+  const definition = QUESTION_SET_DEFINITIONS[id];
+  if (!definition || !DECISION_QUESTION_SETS[id]) throw decisionError(DECISION_ERROR_CODES.QUESTION_SET_UNKNOWN, `Unknown semantic decision question set: ${id}`);
+  return freezeQuestionSet(definition);
+}
+
+export function buildDynamicQuestionSet({ id, version = 1, decisionKind, questions, candidateIds = [], metadata = {} } = {}) {
+  if (typeof id !== "string" || !id || !Number.isInteger(version) || version < 1
+    || typeof decisionKind !== "string" || !questions || typeof questions !== "object"
+    || Array.isArray(questions)) {
+    throw decisionError(DECISION_ERROR_CODES.REQUEST_INVALID, "Dynamic semantic question set is invalid.");
+  }
+  const names = Object.keys(questions);
+  if (names.length === 0 || names.length > 128 || names.some((name) => !/^[a-z][a-z0-9_]{0,95}$/.test(name))) {
+    throw decisionError(DECISION_ERROR_CODES.REQUEST_INVALID, "Dynamic semantic question set has invalid bounded questions.");
+  }
+  return freezeQuestionSet({ id, version, decisionKind, questions, candidateIds: [...candidateIds].slice(0, 64), metadata });
+}
+
+export function buildContextQuestionSet(candidates = []) {
+  const bounded = candidates.slice(0, 64);
+  const questions = Object.fromEntries(bounded.map((candidate, index) => [
+    `candidate_${index}_relevant`, {
+      type: "noul",
+      criteria: { yes: `Candidate ${candidate.id} is relevant to the bounded task context`, no: `Candidate ${candidate.id} is not relevant to the bounded task context` },
+    },
+  ]));
+  return buildDynamicQuestionSet({
+    id: "context-candidates-v1", decisionKind: "CONTEXT_PLAN", questions,
+    candidateIds: bounded.map((candidate) => candidate.id),
+    metadata: { candidateQuestionPrefix: "candidate_", relevanceSuffix: "_relevant" },
+  });
+}
+
+export function buildRouteQuestionSet(guides = []) {
+  const bounded = guides.slice(0, 64);
+  const questions = Object.fromEntries(bounded.map((guide, index) => [
+    `guide_${index}_relevant`, {
+      type: "noul",
+      criteria: { yes: `Guide ${guide} is relevant to the bounded route`, no: `Guide ${guide} is not relevant to the bounded route` },
+    },
+  ]));
+  return buildDynamicQuestionSet({
+    id: "route-candidates-v1", decisionKind: "ROUTE", questions,
+    candidateIds: bounded,
+    metadata: { candidateQuestionPrefix: "guide_", relevanceSuffix: "_relevant" },
+  });
+}
+
+export function buildExecutionProfileQuestionSet() {
+  return getQuestionSet("execution-profile-v1");
+}
+
+export function buildTestUtilityQuestionSet(tests = []) {
+  const dimensions = ["unique_semantic_intent", "semantic_duplicate", "likely_obsolete", "likely_flaky_low_signal", "expensive_relative_to_signal", "documentation_value", "integration_value", "guards_regression_prone_behavior", "requires_system_two_review"];
+  const bounded = tests.slice(0, 16);
+  const questions = {};
+  for (let index = 0; index < bounded.length; index += 1) {
+    for (const dimension of dimensions) questions[`test_${index}_${dimension}`] = {
+      type: "noul", criteria: { yes: `${dimension} applies to test ${bounded[index].testId}`, no: `${dimension} does not apply to test ${bounded[index].testId}` },
+    };
+  }
+  return buildDynamicQuestionSet({
+    id: "test-utility-candidates-v1", decisionKind: "TEST_UTILITY", questions,
+    candidateIds: bounded.map((test) => test.testId),
+    metadata: { dimensions, candidateQuestionPrefix: "test_", testCount: bounded.length },
+  });
+}
+
+export function listQuestionSets() {
+  return Object.values(DECISION_QUESTION_SETS).map((entry) => getQuestionSet(entry.id));
+}

package/src/core/decision/request.js

@@ -0,0 +1,26 @@
+import { buildCombinedDecisionState } from "./state-builder.js";
+import { DECISION_KINDS, PINNED_JEV_MODEL } from "./constants.js";
+import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
+import { getQuestionSet } from "./question-registry.js";
+
+export function validateDecisionRequest(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw decisionError(DECISION_ERROR_CODES.REQUEST_INVALID, "Decision request must be an object.");
+  if (typeof input.taskId !== "string" || !input.taskId) throw decisionError(DECISION_ERROR_CODES.REQUEST_INVALID, "Decision request requires a taskId.");
+  if (!DECISION_KINDS.includes(input.decisionKind)) throw decisionError(DECISION_ERROR_CODES.REQUEST_INVALID, "Decision request has an unsupported decision kind.");
+  if (typeof input.questionSetId !== "string" && !input.questionSet) throw decisionError(DECISION_ERROR_CODES.REQUEST_INVALID, "Decision request requires a question set.");
+  const questionSet = input.questionSet ?? getQuestionSet(input.questionSetId);
+  if (typeof questionSet.id !== "string" || typeof questionSet.fingerprint !== "string") throw decisionError(DECISION_ERROR_CODES.REQUEST_INVALID, "Decision request question set is not canonical.");
+  if (questionSet.decisionKind !== input.decisionKind) throw decisionError(DECISION_ERROR_CODES.REQUEST_INVALID, "Question set does not match decision kind.");
+  if (input.model !== undefined && input.model !== PINNED_JEV_MODEL) throw decisionError(DECISION_ERROR_CODES.MODEL_UNSUPPORTED, "Only the pinned ForgeLoop Jev model is supported.");
+  const state = input.state && typeof input.state === "object"
+    && (Object.prototype.hasOwnProperty.call(input.state, "lifecycle")
+      || Object.prototype.hasOwnProperty.call(input.state, "semantic"))
+    ? buildCombinedDecisionState(input.state)
+    : buildCombinedDecisionState({ semantic: input.state ?? {} });
+  return {
+    ...input,
+    model: PINNED_JEV_MODEL,
+    questionSet,
+    state,
+  };
+}