@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/core/contract-presets.js

@@ -0,0 +1,82 @@
+import { createContract } from "./contract.js";
+
+const PRESET_DEFINITIONS = Object.freeze({
+  documentation: Object.freeze({
+    objective: "Complete the requested documentation change with verified project facts.",
+    constraints: ["Preserve repository-local instructions and existing public documentation contracts."],
+    risks: [],
+    verification: [{ id: "verify-documentation", text: "Relevant documentation checks pass.", type: "VERIFICATION" }],
+    successCriteria: [{ id: "complete-documentation", text: "The requested documentation change is complete and accurate.", type: "PRODUCT" }],
+    stopConditions: ["A required project fact or source cannot be confirmed."],
+  }),
+  bug: Object.freeze({
+    objective: "Diagnose and correct the requested bug without changing unrelated behavior.",
+    constraints: ["Preserve the existing public contract unless a breaking change is explicitly requested."],
+    risks: [],
+    verification: [{ id: "verify-bug-fix", text: "A focused regression check and proportional regression checks pass.", type: "VERIFICATION" }],
+    successCriteria: [{ id: "complete-bug-fix", text: "The reported behavior is corrected and the regression is covered.", type: "PRODUCT" }],
+    stopConditions: ["The failure cannot be reproduced or narrowed with available evidence."],
+  }),
+  feature: Object.freeze({
+    objective: "Implement the requested feature within the confirmed project scope.",
+    constraints: ["Preserve existing architecture and public contracts unless a change is explicitly requested."],
+    risks: [],
+    verification: [{ id: "verify-feature", text: "Focused behavior checks and proportional regression checks pass.", type: "VERIFICATION" }],
+    successCriteria: [{ id: "complete-feature", text: "The requested feature behavior is implemented and documented where applicable.", type: "PRODUCT" }],
+    stopConditions: ["Required product behavior or acceptance facts remain unresolved."],
+  }),
+  release: Object.freeze({
+    objective: "Prepare the requested release with independently verified artifact and publication evidence.",
+    constraints: [
+      "Do not publish, deploy, or mutate external release state without explicit authority.",
+      "Separate local checks, repository integration, publication, and deployment evidence.",
+    ],
+    risks: ["publication"],
+    verification: [{ id: "verify-release", text: "Release identity, package/artifact integrity, and required checks are independently verified.", type: "VERIFICATION" }],
+    successCriteria: [{
+      id: "publish-release",
+      text: "The requested release publication status is independently verified.",
+      type: "PUBLICATION",
+      requiredPublicationStatus: "published",
+    }],
+    stopConditions: ["Publication authority, target, or identity evidence is not available."],
+  }),
+});
+
+export const CONTRACT_PRESET_IDS = Object.freeze(Object.keys(PRESET_DEFINITIONS));
+
+function normalizedClaims(claims) {
+  return [...new Set((Array.isArray(claims) ? claims : [])
+    .filter((claim) => typeof claim === "string" && claim.trim() !== "")
+    .map((claim) => claim.trim()))];
+}
+
+export function createPresetContract({ taskId, preset, claims = [] } = {}) {
+  if (!Object.prototype.hasOwnProperty.call(PRESET_DEFINITIONS, preset)) {
+    const error = new Error(`Unknown contract preset: ${preset}. Expected one of ${CONTRACT_PRESET_IDS.join(", ")}`);
+    error.code = "E_CONTRACT_PRESET_UNKNOWN";
+    throw error;
+  }
+  const definition = PRESET_DEFINITIONS[preset];
+  const confirmedClaims = normalizedClaims(claims);
+  const unresolvedDecisions = confirmedClaims.length > 0
+    ? []
+    : ["Confirm the concrete deliverables and affected behavior before implementation."];
+  return createContract({
+    taskId,
+    objective: definition.objective,
+    deliverables: confirmedClaims.length > 0 ? confirmedClaims : ["Deliverables confirmed by task scope."],
+    constraints: definition.constraints,
+    risks: definition.risks,
+    verification: definition.verification,
+    successCriteria: definition.successCriteria,
+    stopConditions: definition.stopConditions,
+    unresolvedDecisions,
+    sourceRefs: [`contract-preset:${preset}`],
+  });
+}
+
+export function contractPresetDefinition(preset) {
+  if (!Object.prototype.hasOwnProperty.call(PRESET_DEFINITIONS, preset)) return null;
+  return structuredClone(PRESET_DEFINITIONS[preset]);
+}

package/src/core/contract-revision.js

@@ -0,0 +1,210 @@
+import { canonicalFingerprint } from "./artifacts.js";
+
+export const CONTRACT_REVISED_EVENT = "CONTRACT_REVISED";
+
+const FINGERPRINT = /^[a-f0-9]{64}$/;
+const REVISION_PHASES = new Set(["CONTRACT_READY", "ROUTED", "PLANNED"]);
+const REVISION_DETAIL_KEYS = Object.freeze([
+  "previousContractFingerprint",
+  "contractFingerprint",
+  "previousPhase",
+  "phase",
+  "previousStateRevision",
+  "revisedStateRevision",
+  "previousStateFingerprint",
+  "revisedStateFingerprint",
+  "previousRouteFingerprint",
+]);
+
+function invalid(message) {
+  const error = new Error(message);
+  error.code = "E_CONTRACT_REVISION_UNSAFE";
+  return error;
+}
+
+export function isFingerprint(value) {
+  return typeof value === "string" && FINGERPRINT.test(value);
+}
+
+export function assertContractRevisedDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)
+    || Object.keys(details).length !== REVISION_DETAIL_KEYS.length
+    || REVISION_DETAIL_KEYS.some((key) => !Object.prototype.hasOwnProperty.call(details, key))) {
+    throw invalid(`${CONTRACT_REVISED_EVENT} requires its exact contract-transition detail set`);
+  }
+  for (const key of ["previousContractFingerprint", "contractFingerprint", "previousStateFingerprint", "revisedStateFingerprint"]) {
+    if (!isFingerprint(details[key])) throw invalid(`${CONTRACT_REVISED_EVENT} details.${key} must be a lowercase SHA-256 fingerprint`);
+  }
+  if (details.previousContractFingerprint === details.contractFingerprint) {
+    throw invalid(`${CONTRACT_REVISED_EVENT} must change the contract fingerprint`);
+  }
+  if (!REVISION_PHASES.has(details.previousPhase) || !REVISION_PHASES.has(details.phase)) {
+    throw invalid(`${CONTRACT_REVISED_EVENT} details phase is unsupported`);
+  }
+  const expectedPhase = details.previousPhase === "PLANNED" ? "ROUTED" : details.previousPhase;
+  if (details.phase !== expectedPhase) {
+    throw invalid(`${CONTRACT_REVISED_EVENT} phase transition is invalid: ${details.previousPhase} -> ${details.phase}`);
+  }
+  for (const key of ["previousStateRevision", "revisedStateRevision"]) {
+    if (!Number.isInteger(details[key]) || details[key] < 0) {
+      throw invalid(`${CONTRACT_REVISED_EVENT} details.${key} must be a non-negative integer`);
+    }
+  }
+  if (details.revisedStateRevision !== details.previousStateRevision + 1) {
+    throw invalid(`${CONTRACT_REVISED_EVENT} state revisions must advance exactly once`);
+  }
+  if (details.previousRouteFingerprint !== null && !isFingerprint(details.previousRouteFingerprint)) {
+    throw invalid(`${CONTRACT_REVISED_EVENT} details.previousRouteFingerprint must be a fingerprint or null`);
+  }
+  if (details.previousPhase === "CONTRACT_READY" && details.previousRouteFingerprint !== null) {
+    throw invalid(`${CONTRACT_REVISED_EVENT} CONTRACT_READY revisions cannot have a route fingerprint`);
+  }
+  if (details.previousPhase !== "CONTRACT_READY" && !isFingerprint(details.previousRouteFingerprint)) {
+    throw invalid(`${CONTRACT_REVISED_EVENT} routed revisions require the previous route fingerprint`);
+  }
+  return details;
+}
+
+function eventHash(event) {
+  const { hash, ...body } = event ?? {};
+  return canonicalFingerprint(body);
+}
+
+function validRevisionCommit(revisionEvent, commitEvent) {
+  return commitEvent?.event === "TRANSACTION_COMMITTED"
+    && commitEvent.taskId === revisionEvent.taskId
+    && commitEvent.seq === revisionEvent.seq + 1
+    && commitEvent.previousHash === revisionEvent.hash
+    && revisionEvent.hash === eventHash(revisionEvent)
+    && commitEvent.hash === eventHash(commitEvent)
+    && commitEvent.details
+    && typeof commitEvent.details === "object"
+    && !Array.isArray(commitEvent.details)
+    && Object.keys(commitEvent.details).length === 2
+    && typeof commitEvent.details.transactionId === "string"
+    && commitEvent.details.transactionId.length > 0
+    && commitEvent.details.operation === "contract-revise";
+}
+
+export function resolveContractRevisionBoundary(events, revisionEvent) {
+  if (!Array.isArray(events) || !revisionEvent || revisionEvent.event !== CONTRACT_REVISED_EVENT) return null;
+  const index = events.findIndex((event) => event === revisionEvent
+    || (event?.seq === revisionEvent.seq
+      && event?.taskId === revisionEvent.taskId
+      && event?.event === CONTRACT_REVISED_EVENT));
+  if (index < 0) return null;
+  const commitEvent = events[index + 1];
+  return validRevisionCommit(revisionEvent, commitEvent)
+    ? { revisionEvent, transactionCommitEvent: commitEvent }
+    : null;
+}
+
+export function resolveCanonicalContractEvolution(events, {
+  taskId,
+  sourceSeq = 0,
+  sourceContractFingerprint,
+  targetContractFingerprint,
+} = {}) {
+  if (!Array.isArray(events)
+    || typeof taskId !== "string" || !taskId
+    || !Number.isInteger(sourceSeq) || sourceSeq < 0
+    || !isFingerprint(sourceContractFingerprint)
+    || !isFingerprint(targetContractFingerprint)) return null;
+
+  let currentFingerprint = sourceContractFingerprint;
+  const revisionEvents = [];
+  for (const event of events) {
+    if (event?.seq <= sourceSeq || event?.event !== CONTRACT_REVISED_EVENT) continue;
+    if (event.taskId !== taskId) return null;
+    try {
+      assertContractRevisedDetails(event.details);
+    } catch {
+      return null;
+    }
+    if (!resolveContractRevisionBoundary(events, event)
+      || event.details.previousContractFingerprint !== currentFingerprint) {
+      return null;
+    }
+    const executionStarted = events.some((candidate) => candidate.taskId === taskId
+      && candidate.event === "EXECUTION_STARTED"
+      && candidate.seq < event.seq);
+    if (executionStarted) return null;
+    revisionEvents.push(event);
+    currentFingerprint = event.details.contractFingerprint;
+  }
+  return currentFingerprint === targetContractFingerprint
+    ? { valid: true, contractFingerprint: currentFingerprint, revisionEvents }
+    : null;
+}
+
+export function latestContractRevision(events = []) {
+  return events.filter((event) => event.event === CONTRACT_REVISED_EVENT).at(-1) ?? null;
+}
+
+export function validateContractRevisionEventBindings(events = []) {
+  const errors = [];
+  const revisions = events.filter((event) => event.event === CONTRACT_REVISED_EVENT);
+  let currentContractFingerprint = null;
+  let currentStateRevision = null;
+  for (const event of revisions) {
+    let details;
+    try {
+      details = assertContractRevisedDetails(event.details);
+    } catch (error) {
+      errors.push({ code: error.code ?? "E_CONTRACT_REVISION_UNSAFE", message: `event ${event.seq}: ${error.message}` });
+      continue;
+    }
+    if (!resolveContractRevisionBoundary(events, event)) {
+      errors.push({ code: "E_CONTRACT_REVISION_UNSAFE", message: `event ${event.seq} must be immediately followed by its contract-revise transaction commit` });
+    }
+    if (events.some((candidate) => candidate.taskId === event.taskId
+      && candidate.event === "EXECUTION_STARTED"
+      && candidate.seq < event.seq)) {
+      errors.push({ code: "E_CONTRACT_REVISION_UNSAFE", message: `event ${event.seq} occurs after execution started` });
+    }
+    if (currentContractFingerprint === null) {
+      const initial = events.find((candidate) => candidate.taskId === event.taskId
+        && candidate.event === "CONTRACT_VALIDATED"
+        && candidate.seq < event.seq);
+      const initialFingerprint = initial?.fingerprint ?? initial?.details?.contractFingerprint;
+      if (!initial || initialFingerprint !== details.previousContractFingerprint) {
+        errors.push({ code: "E_CONTRACT_REVISION_UNSAFE", message: `event ${event.seq} does not continue the initial contract identity` });
+      }
+    } else if (details.previousContractFingerprint !== currentContractFingerprint) {
+      errors.push({ code: "E_CONTRACT_REVISION_UNSAFE", message: `event ${event.seq} is disconnected from the previous contract revision` });
+    }
+    if (currentStateRevision !== null && details.previousStateRevision < currentStateRevision) {
+      errors.push({ code: "E_CONTRACT_REVISION_UNSAFE", message: `event ${event.seq} rolls back the contract revision state` });
+    }
+    currentContractFingerprint = details.contractFingerprint;
+    currentStateRevision = details.revisedStateRevision;
+  }
+  return errors;
+}
+
+export function validateContractRevisionCurrentBinding(state, events = []) {
+  const errors = [];
+  const revisions = events.filter((event) => event.event === CONTRACT_REVISED_EVENT);
+  if (revisions.length === 0) return errors;
+  const first = revisions[0];
+  const latest = revisions.at(-1);
+  const initial = events.find((event) => event.taskId === state?.taskId && event.event === "CONTRACT_VALIDATED");
+  const evolution = resolveCanonicalContractEvolution(events, {
+    taskId: state?.taskId,
+    sourceSeq: initial?.seq ?? 0,
+    sourceContractFingerprint: initial?.fingerprint ?? first.details?.previousContractFingerprint,
+    targetContractFingerprint: state?.contractFingerprint,
+  });
+  if (!evolution) {
+    errors.push({ code: "E_CONTRACT_REVISION_UNSAFE", message: "current contract identity is not the final canonical contract revision target" });
+  }
+  if (Number.isInteger(state?.revision) && state.revision < latest.details.revisedStateRevision) {
+    errors.push({ code: "E_CONTRACT_REVISION_UNSAFE", message: `current state revision precedes contract revision event ${latest.seq}` });
+  }
+  if (state?.revision === latest.details.revisedStateRevision
+    && (state.phase !== latest.details.phase
+      || canonicalFingerprint(state) !== latest.details.revisedStateFingerprint)) {
+    errors.push({ code: "E_CONTRACT_REVISION_UNSAFE", message: `event ${latest.seq} does not bind the current revised state` });
+  }
+  return errors;
+}

package/src/core/decision/artifact.js

@@ -0,0 +1,69 @@
+import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "../artifacts.js";
+import { ensureWithin, fileExists } from "../filesystem.js";
+import { taskDecisionPath } from "../task-paths.js";
+import { assertSecretFree } from "../receipt.js";
+import { DECISION_AUTHORITY, DECISION_EVIDENCE_AUTHORITY, DECISION_POLICY_VERSION, PINNED_JEV_MODEL } from "./constants.js";
+import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
+import { getTaskTransaction, withTaskTransaction } from "../transaction.js";
+
+export function buildDecisionArtifact(input = {}) {
+  const artifact = {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    taskId: input.taskId,
+    decisionId: input.decisionId,
+    decisionKind: input.decisionKind,
+    engine: "typesafe-jev",
+    model: input.model ?? PINNED_JEV_MODEL,
+    questionSetId: input.questionSetId,
+    questionSetVersion: input.questionSetVersion ?? 1,
+    questionSetFingerprint: input.questionSetFingerprint,
+    ...(input.questionSet ? { questionSet: input.questionSet } : {}),
+    policyVersion: input.policyVersion ?? DECISION_POLICY_VERSION,
+    stateFingerprint: input.stateFingerprint,
+    taskStateFingerprint: input.taskStateFingerprint ?? null,
+    semanticStateFingerprint: input.semanticStateFingerprint ?? null,
+    policyFingerprint: input.policyFingerprint,
+    repositoryFingerprint: input.repositoryFingerprint ?? null,
+    contractFingerprint: input.contractFingerprint ?? null,
+    routeFingerprint: input.routeFingerprint ?? null,
+    verificationCycle: input.verificationCycle ?? null,
+    candidateSetFingerprint: input.candidateSetFingerprint ?? null,
+    answers: input.answers ?? {},
+    confidence: input.confidence ?? {},
+    decision: input.decision ?? {},
+    usage: input.usage ?? { inputTokens: null, outputTokens: null, reportedBy: "UNKNOWN" },
+    latencyMs: input.latencyMs ?? null,
+    authority: DECISION_AUTHORITY,
+    evidenceAuthority: DECISION_EVIDENCE_AUTHORITY,
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    ownershipAuthority: false,
+    installationAuthority: false,
+    recordedAt: input.recordedAt ?? new Date().toISOString(),
+  };
+  assertSecretFree(artifact);
+  if (artifact.model !== PINNED_JEV_MODEL || artifact.policyVersion === 0) throw decisionError(DECISION_ERROR_CODES.RESULT_INVALID, "Semantic decision artifact is not pinned.");
+  return artifact;
+}
+
+export async function readDecisionArtifact(target, taskId, decisionId, packageRoot) {
+  return readJsonArtifact(target, taskDecisionPath(taskId, decisionId), "semantic-decision", packageRoot);
+}
+
+export async function writeDecisionArtifact(target, taskId, decisionId, artifact, packageRoot, options = {}) {
+  if (!(await getTaskTransaction(target))) {
+    return withTaskTransaction({ target, taskId, packageRoot, operation: "semantic-decision" }, async () => (
+      writeDecisionArtifact(target, taskId, decisionId, artifact, packageRoot, options)
+    ));
+  }
+  const relativePath = taskDecisionPath(taskId, decisionId);
+  if (await fileExists(ensureWithin(target, relativePath))) {
+    throw decisionError(DECISION_ERROR_CODES.IMMUTABLE, `Semantic decision artifact already exists: ${decisionId}`);
+  }
+  return writeJsonArtifact(target, relativePath, artifact, "semantic-decision", packageRoot, { ...options, taskId, operation: "semantic-decision" });
+}
+
+export function decisionArtifactFingerprint(artifact) {
+  return canonicalFingerprint(artifact);
+}

package/src/core/decision/benchmarks.js

@@ -0,0 +1,103 @@
+import { canonicalFingerprint } from "../artifacts.js";
+import { projectModelRoute } from "../model-router/router.js";
+import { createTypesafeEngine } from "../../adapters/typesafe/engine.js";
+import { getQuestionSet } from "./question-registry.js";
+import { DECISION_DEFAULT_POLICY } from "./constants.js";
+
+const SCENARIOS = Object.freeze([
+  { id: "docs-only", input: { workType: "documentation" } },
+  { id: "ordinary-code", input: { workType: "code", executableChange: true } },
+  { id: "security-code", input: { workType: "code", risks: ["secrets"], executableChange: true } },
+]);
+
+export function runJevBenchmark() {
+  const scenarios = SCENARIOS.map((scenario) => {
+    const route = projectModelRoute({ input: scenario.input });
+    return {
+      id: scenario.id,
+      floor: route.floor,
+      resolved: route.resolved,
+      jevCalls: 0,
+      jevInputTokens: null,
+      jevLatencyMs: null,
+      jevCacheHits: 0,
+      jevLowConfidenceEscalations: 0,
+      mainModelCalls: null,
+      mainModelInputTokens: null,
+      mainModelOutputTokens: null,
+      candidateContextItems: null,
+      selectedContextItems: null,
+      candidateChars: null,
+      selectedChars: null,
+      guideSectionsConsidered: null,
+      guideSectionsLoaded: null,
+      filesRead: null,
+      repositorySearches: null,
+      contextRefreshes: null,
+      modelTurns: null,
+      toolCalls: null,
+      wallClockMs: null,
+      verification: "NOT_MEASURED",
+      quality: "NOT_MEASURED",
+      fallback: true,
+    };
+  });
+  const summary = {
+    schemaVersion: 1,
+    engine: "typesafe-jev",
+    model: "jev-1.13.0",
+    status: "OFFLINE_DETERMINISTIC_BASELINE",
+    scenarios,
+    metrics: {
+      scenarioCount: scenarios.length,
+      jevCalls: 0,
+      jevInputTokens: null,
+      jevLatencyMs: null,
+      jevCacheHits: 0,
+      jevLowConfidenceEscalations: 0,
+      mainModelCalls: null,
+      mainModelInputTokens: null,
+      mainModelOutputTokens: null,
+      candidateContextItems: null,
+      selectedContextItems: null,
+      candidateChars: null,
+      selectedChars: null,
+      guideSectionsConsidered: null,
+      guideSectionsLoaded: null,
+      filesRead: null,
+      repositorySearches: null,
+      contextRefreshes: null,
+      modelTurns: null,
+      toolCalls: null,
+      wallClockMs: null,
+      verification: "NOT_MEASURED",
+      quality: "NOT_MEASURED",
+      inputTokens: null,
+      outputTokens: null,
+      tokenReduction: null,
+    },
+  };
+  return { ...summary, fingerprint: canonicalFingerprint(summary) };
+}
+
+export async function runJevBenchmarkLive({ engine = null, policy = DECISION_DEFAULT_POLICY } = {}) {
+  const resolvedEngine = engine ?? createTypesafeEngine({ policy });
+  const started = Date.now();
+  const scenarios = [];
+  for (const scenario of SCENARIOS) {
+    const questionSet = getQuestionSet(scenario.id === "docs-only" ? "intake-v1" : scenario.id === "security-code" ? "route-v1" : "context-v1");
+    const result = await resolvedEngine.evaluate({
+      taskId: `benchmark-${scenario.id}`,
+      decisionKind: questionSet.decisionKind,
+      questionSetId: questionSet.id,
+      questionSet,
+      state: { benchmark: true, input: scenario.input },
+    });
+    scenarios.push({ id: scenario.id, decisionKind: questionSet.decisionKind, jevCalls: 1, usage: result.usage ?? null, latencyMs: result.latencyMs ?? null, status: "PROVIDER_REPORTED" });
+  }
+  const summary = {
+    schemaVersion: 1, engine: "typesafe-jev", model: "jev-1.13.0", status: "LIVE_PROVIDER_REPORTED", scenarios,
+    metrics: { scenarioCount: scenarios.length, jevCalls: scenarios.length, inputTokens: scenarios.reduce((sum, item) => sum + (item.usage?.inputTokens ?? 0), 0), outputTokens: scenarios.reduce((sum, item) => sum + (item.usage?.outputTokens ?? 0), 0), wallClockMs: Date.now() - started, verification: "NOT_MEASURED", quality: "NOT_MEASURED" },
+  };
+  return { ...summary, fingerprint: canonicalFingerprint(summary) };
+}

package/src/core/decision/cache.js

@@ -0,0 +1,27 @@
+import { canonicalFingerprint } from "../artifacts.js";
+import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
+
+export function decisionCacheKey(input = {}) {
+  return canonicalFingerprint({
+    engine: input.engine,
+    model: input.model,
+    questionSetFingerprint: input.questionSetFingerprint,
+    stateFingerprint: input.stateFingerprint,
+    policyFingerprint: input.policyFingerprint,
+    candidateSetFingerprint: input.candidateSetFingerprint ?? null,
+  });
+}
+
+export function createDecisionCache() {
+  const values = new Map();
+  return Object.freeze({
+    get(input) { return values.get(decisionCacheKey(input)) ?? null; },
+    set(input, value) {
+      if (!value || typeof value !== "object") throw decisionError(DECISION_ERROR_CODES.CACHE_INVALID, "Only structured semantic decisions may be cached.");
+      const key = decisionCacheKey(input);
+      values.set(key, Object.freeze({ key, value: structuredClone(value) }));
+      return key;
+    },
+    size() { return values.size; },
+  });
+}

package/src/core/decision/constants.js

@@ -0,0 +1,58 @@
+export const DECISION_ENGINE_ID = "typesafe-jev";
+export const PINNED_JEV_MODEL = "jev-1.13.0";
+export const DECISION_POLICY_VERSION = 1;
+export const DECISION_AUTHORITY = "SEMANTIC_DECISION";
+export const DECISION_EVIDENCE_AUTHORITY = "NONE";
+
+export const DECISION_KINDS = Object.freeze([
+  "INTAKE",
+  "CONTRACT_APPLICABILITY",
+  "ROUTE",
+  "EXECUTION_PROFILE",
+  "CONTEXT_PLAN",
+  "MODEL_ROUTE",
+  "FAILURE_TRIAGE",
+  "DIAGNOSIS_PRIORITY",
+  "REVIEW_PLAN",
+  "TASK_OVERLAP",
+  "TEST_UTILITY",
+  "TEST_PRUNE",
+]);
+
+export const DECISION_STATUS = Object.freeze(["RECORDED", "SUPERSEDED"]);
+
+export const DECISION_DEFAULT_POLICY = Object.freeze({
+  required: true,
+  provider: DECISION_ENGINE_ID,
+  model: PINNED_JEV_MODEL,
+  policyVersion: DECISION_POLICY_VERSION,
+  requestTimeoutMs: 8_000,
+  maxRetries: 1,
+  cache: true,
+});
+
+export const DECISION_LIMITS = Object.freeze({
+  maxStateBytes: 48_000,
+  maxStringChars: 8_000,
+  maxItems: 128,
+  maxDepth: 8,
+  maxCandidates: 64,
+});
+
+export const DECISION_QUESTION_SETS = Object.freeze({
+  "intake-v1": Object.freeze({ id: "intake-v1", version: 1, decisionKind: "INTAKE" }),
+  "contract-v1": Object.freeze({ id: "contract-v1", version: 1, decisionKind: "CONTRACT_APPLICABILITY" }),
+  "route-v1": Object.freeze({ id: "route-v1", version: 1, decisionKind: "ROUTE" }),
+  "execution-profile-v1": Object.freeze({ id: "execution-profile-v1", version: 1, decisionKind: "EXECUTION_PROFILE" }),
+  "context-v1": Object.freeze({ id: "context-v1", version: 1, decisionKind: "CONTEXT_PLAN" }),
+  "model-route-v1": Object.freeze({ id: "model-route-v1", version: 1, decisionKind: "MODEL_ROUTE" }),
+  "failure-v1": Object.freeze({ id: "failure-v1", version: 1, decisionKind: "FAILURE_TRIAGE" }),
+  "diagnosis-v1": Object.freeze({ id: "diagnosis-v1", version: 1, decisionKind: "DIAGNOSIS_PRIORITY" }),
+  "review-v1": Object.freeze({ id: "review-v1", version: 1, decisionKind: "REVIEW_PLAN" }),
+  "task-overlap-v1": Object.freeze({ id: "task-overlap-v1", version: 1, decisionKind: "TASK_OVERLAP" }),
+  "test-utility-v1": Object.freeze({ id: "test-utility-v1", version: 1, decisionKind: "TEST_UTILITY" }),
+  "test-prune-v1": Object.freeze({ id: "test-prune-v1", version: 1, decisionKind: "TEST_PRUNE" }),
+});
+
+export const SEMANTIC_DECISION_RECORDED_EVENT = "SEMANTIC_DECISION_RECORDED";
+export const SEMANTIC_DECISION_SUPERSEDED_EVENT = "SEMANTIC_DECISION_SUPERSEDED";

package/src/core/decision/cutover.js

@@ -0,0 +1,34 @@
+import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
+import { assertRequiredFreshDecision, resolveRequiredSemanticDecision } from "./resolver.js";
+
+export const DECISION_CUTOVER_MODE = "FAIL_CLOSED";
+export const OFFLINE_SAFE_OPERATIONS = Object.freeze([
+  "protocol-info", "doctor", "status", "task-show", "task-list", "history", "trace", "audit",
+  "validate-state", "validate-protocol", "inspect", "task-recover", "task-abandon", "complete",
+]);
+
+export function assertRequiredDecision({ decision = null, artifact = null, operation = "semantic-decision", currentBindings = {}, expectedDecisionKind, expectedTaskId, expectedQuestionSetId, ledger = [] } = {}) {
+  const candidate = artifact ?? decision;
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    throw decisionError(DECISION_ERROR_CODES.REQUIRED, `A fresh ForgeLoop semantic decision is required for ${operation}.`);
+  }
+  if (candidate.model !== "jev-1.13.0" || candidate.engine !== "typesafe-jev") {
+    throw decisionError(DECISION_ERROR_CODES.MODEL_UNSUPPORTED, "Semantic decision is not bound to the pinned ForgeLoop Jev model.");
+  }
+  if (!candidate.taskId || !candidate.decisionId || !candidate.questionSetId || !candidate.stateFingerprint
+    || !candidate.questionSetFingerprint || !candidate.policyFingerprint || !candidate.authority) {
+    throw decisionError(DECISION_ERROR_CODES.REQUIRED, `A canonical persisted semantic decision is required for ${operation}.`);
+  }
+  return assertRequiredFreshDecision({
+    artifact: candidate,
+    currentBindings,
+    expectedDecisionKind,
+    expectedTaskId,
+    expectedQuestionSetId,
+    ledger,
+  });
+}
+
+export { assertRequiredFreshDecision, resolveRequiredSemanticDecision };
+
+export function isOfflineSafeOperation(operation) { return OFFLINE_SAFE_OPERATIONS.includes(operation); }

package/src/core/decision/engine.js

@@ -0,0 +1,22 @@
+import { DECISION_ENGINE_ID, PINNED_JEV_MODEL } from "./constants.js";
+import { validateDecisionRequest } from "./request.js";
+import { normalizeDecisionPolicy } from "./policy.js";
+import { decisionError, DECISION_ERROR_CODES } from "./errors.js";
+
+export function assertDecisionEngine(engine) {
+  if (!engine || engine.id !== DECISION_ENGINE_ID || engine.model !== PINNED_JEV_MODEL || typeof engine.evaluate !== "function" || typeof engine.health !== "function") {
+    throw decisionError(DECISION_ERROR_CODES.ENGINE_UNAVAILABLE, "A pinned typesafe-jev decision engine is required.");
+  }
+  return engine;
+}
+
+export function createDecisionEngine({ provider, policy } = {}) {
+  const normalizedPolicy = normalizeDecisionPolicy(policy);
+  assertDecisionEngine(provider);
+  return Object.freeze({
+    id: DECISION_ENGINE_ID,
+    model: PINNED_JEV_MODEL,
+    async evaluate(input) { return provider.evaluate(validateDecisionRequest(input), normalizedPolicy); },
+    async health() { return provider.health(normalizedPolicy); },
+  });
+}