@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/core/decision/resolver.js

@@ -0,0 +1,138 @@
+import { readdir } from "node:fs/promises";
+
+import { canonicalFingerprint, readJsonArtifact } from "../artifacts.js";
+import { fileExists, ensureWithin } from "../filesystem.js";
+import { validateEventLedger } from "../events.js";
+import { taskDecisionDirectory } from "../task-paths.js";
+import { getQuestionSet } from "./question-registry.js";
+import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
+import { DECISION_ENGINE_ID, DECISION_POLICY_VERSION, PINNED_JEV_MODEL, SEMANTIC_DECISION_RECORDED_EVENT, SEMANTIC_DECISION_SUPERSEDED_EVENT } from "./constants.js";
+import { assertDecisionFresh } from "./freshness.js";
+import { listOperationalArtifactNames } from "../../storage/operational-context.js";
+import { withProjectReadSnapshot } from "../../storage/project-read-snapshot.js";
+
+function invalid(message, code = DECISION_ERROR_CODES.BINDING_INVALID) {
+  return decisionError(code, message);
+}
+
+function assertArtifactIdentity(artifact, { expectedDecisionKind, expectedTaskId, expectedQuestionSetId } = {}) {
+  if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) throw invalid("Semantic decision artifact is not an object.");
+  if (artifact.taskId !== expectedTaskId) throw invalid("Semantic decision task binding is invalid.");
+  if (expectedDecisionKind && artifact.decisionKind !== expectedDecisionKind) throw invalid("Semantic decision kind binding is invalid.");
+  if (expectedQuestionSetId && artifact.questionSetId !== expectedQuestionSetId) throw invalid("Semantic decision question-set binding is invalid.");
+  if (artifact.engine !== DECISION_ENGINE_ID || artifact.model !== PINNED_JEV_MODEL) throw decisionError(DECISION_ERROR_CODES.MODEL_UNSUPPORTED, "Semantic decision is not bound to the pinned Jev engine and model.");
+  if (artifact.policyVersion !== DECISION_POLICY_VERSION) throw invalid("Semantic decision policy version is invalid.");
+}
+
+function assertArtifactShape(artifact) {
+  if (artifact.schemaVersion !== 1 || artifact.protocolVersion !== 1
+    || !artifact.answers || typeof artifact.answers !== "object" || Array.isArray(artifact.answers)
+    || !artifact.confidence || typeof artifact.confidence !== "object" || Array.isArray(artifact.confidence)
+    || !artifact.decision || typeof artifact.decision !== "object" || Array.isArray(artifact.decision)
+    || !artifact.usage || typeof artifact.usage !== "object" || Array.isArray(artifact.usage)) {
+    throw invalid("Semantic decision artifact schema is invalid.");
+  }
+}
+
+function assertArtifactAuthority(artifact) {
+  if (artifact.authority !== "SEMANTIC_DECISION" || artifact.evidenceAuthority !== "NONE"
+    || artifact.lifecycleAuthority !== false || artifact.completionAuthority !== false
+    || artifact.ownershipAuthority !== false || artifact.installationAuthority !== false) {
+    throw invalid("Semantic decision authority boundary is invalid.");
+  }
+}
+
+function assertArtifactQuestionSet(artifact) {
+  const questionSet = artifact.questionSet ?? getQuestionSet(artifact.questionSetId);
+  if (questionSet.id !== artifact.questionSetId || questionSet.decisionKind === undefined) throw invalid("Semantic decision question-set identity is invalid.");
+  if (artifact.questionSetVersion !== questionSet.version || artifact.questionSetFingerprint !== questionSet.fingerprint) {
+    throw invalid("Semantic decision question-set fingerprint is stale.");
+  }
+  if (typeof artifact.decisionId !== "string" || artifact.decisionId.length === 0) {
+    throw invalid("Semantic decision ID is invalid.");
+  }
+}
+
+function assertCanonicalArtifact(artifact, options = {}) {
+  assertArtifactIdentity(artifact, options);
+  assertArtifactShape(artifact);
+  assertArtifactAuthority(artifact);
+  assertArtifactQuestionSet(artifact);
+  return artifact;
+}
+
+function decisionRecordForArtifact(events, artifact) {
+  return events.find((event) => event.event === SEMANTIC_DECISION_RECORDED_EVENT
+    && event.taskId === artifact.taskId
+    && event.details?.decisionId === artifact.decisionId) ?? null;
+}
+
+function isSuperseded(events, artifact) {
+  return events.some((event) => event.event === SEMANTIC_DECISION_SUPERSEDED_EVENT
+    && event.taskId === artifact.taskId
+    && event.details?.decisionId === artifact.decisionId);
+}
+
+export function assertRequiredFreshDecision({ artifact, currentBindings = {}, expectedDecisionKind, expectedTaskId, expectedQuestionSetId, ledger = [] } = {}) {
+  assertCanonicalArtifact(artifact, { expectedDecisionKind, expectedTaskId, expectedQuestionSetId });
+  if (!Array.isArray(ledger)) throw invalid("Semantic decision ledger is unavailable.", DECISION_ERROR_CODES.LEDGER_INVALID);
+  const record = decisionRecordForArtifact(ledger, artifact);
+  if (!record || record.details.artifactFingerprint !== canonicalFingerprint(artifact)) {
+    throw invalid("Semantic decision has no matching canonical ledger record.", DECISION_ERROR_CODES.LEDGER_INVALID);
+  }
+  if (isSuperseded(ledger, artifact)) throw decisionError(DECISION_ERROR_CODES.STALE, "Semantic decision has been superseded.");
+  assertDecisionFresh(artifact, {
+    ...currentBindings,
+    model: PINNED_JEV_MODEL,
+    policyFingerprint: currentBindings.policyFingerprint ?? artifact.policyFingerprint,
+  });
+  return artifact;
+}
+
+async function decisionArtifacts(target, taskId, packageRoot) {
+  const directory = taskDecisionDirectory(taskId);
+  let names = listOperationalArtifactNames(target, taskId, "decisions");
+  if (names === null) {
+    const absolute = ensureWithin(target, directory);
+    if (!(await fileExists(absolute))) return [];
+    names = (await readdir(absolute, { withFileTypes: true }))
+      .filter(entry => entry.isFile()).map(entry => entry.name);
+  }
+  const ids = names.filter(name => name.endsWith(".json")).map(name => name.slice(0, -5)).sort();
+  const artifacts = [];
+  for (const decisionId of ids) {
+    try {
+      artifacts.push((await readJsonArtifact(target, `${directory}/${decisionId}.json`, "semantic-decision", packageRoot)).value);
+    } catch {
+      // The canonical resolver reports a missing/invalid candidate below.
+    }
+  }
+  return artifacts;
+}
+
+export async function resolveRequiredSemanticDecision(options = {}) {
+  if (typeof options.taskId !== "string" || !options.taskId) throw decisionError(DECISION_ERROR_CODES.REQUIRED, "A task-bound semantic decision is required.");
+  return withProjectReadSnapshot(options.target, () => resolveSelectedSemanticDecision(options));
+}
+
+async function resolveSelectedSemanticDecision({ target, packageRoot, taskId, decisionKind, decisionId = null, currentBindings = {} }) {
+  const ledgerResult = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledgerResult.valid) throw decisionError(DECISION_ERROR_CODES.LEDGER_INVALID, "The task ledger is invalid for semantic decision resolution.", ledgerResult.errors);
+  const events = ledgerResult.events;
+  const candidates = decisionId
+    ? [(await readJsonArtifact(target, `${taskDecisionDirectory(taskId)}/${decisionId}.json`, "semantic-decision", packageRoot)).value]
+    : await decisionArtifacts(target, taskId, packageRoot);
+  const records = events
+    .filter((event) => event.event === SEMANTIC_DECISION_RECORDED_EVENT && event.taskId === taskId && (!decisionKind || event.details?.decisionKind === decisionKind))
+    .sort((left, right) => right.seq - left.seq);
+  for (const record of records) {
+    const artifact = candidates.find((candidate) => candidate.decisionId === record.details?.decisionId);
+    if (!artifact || isSuperseded(events, artifact)) continue;
+    try {
+      return assertRequiredFreshDecision({ artifact, currentBindings, expectedDecisionKind: decisionKind, expectedTaskId: taskId, ledger: events });
+    } catch (error) {
+      if (decisionId) throw error;
+    }
+  }
+  throw decisionError(DECISION_ERROR_CODES.REQUIRED, `No fresh canonical Jev decision is available for ${decisionKind ?? "the requested operation"}.`);
+}

package/src/core/decision/result.js

@@ -0,0 +1,58 @@
+import { PINNED_JEV_MODEL } from "./constants.js";
+import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
+import { normalizeCanonicalDecision } from "./normalizers/index.js";
+
+function finite(value) { return typeof value === "number" && Number.isFinite(value); }
+
+function normalizeAnswer(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || finite(value)) return value;
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const result = {};
+    for (const [key, child] of Object.entries(value)) result[key] = normalizeAnswer(child);
+    return result;
+  }
+  if (Array.isArray(value)) return value.slice(0, 64).map(normalizeAnswer);
+  throw decisionError(DECISION_ERROR_CODES.RESULT_INVALID, "Semantic decision answer has an unsupported shape.");
+}
+
+function normalizeAnswers(rawAnswers, questionSet) {
+  return Object.fromEntries(Object.keys(questionSet.questions).map((key) => {
+    if (!Object.prototype.hasOwnProperty.call(rawAnswers, key)) {
+      throw decisionError(DECISION_ERROR_CODES.RESULT_INVALID, `Semantic decision result is missing answer ${key}.`);
+    }
+    return [key, normalizeAnswer(rawAnswers[key])];
+  }));
+}
+
+function normalizeConfidence(confidence, questionSet) {
+  if (!confidence || typeof confidence !== "object" || Array.isArray(confidence)) {
+    throw decisionError(DECISION_ERROR_CODES.RESULT_INVALID, "Semantic decision result confidence is invalid.");
+  }
+  return Object.fromEntries(Object.keys(questionSet.questions).map((key) => [key, confidence[key] ?? null]));
+}
+
+function normalizeUsage(raw) {
+  const inputTokens = raw?.input_tokens ?? raw?.inputTokens;
+  const outputTokens = raw?.output_tokens ?? raw?.outputTokens;
+  if (!Number.isInteger(inputTokens) || inputTokens < 0 || !Number.isInteger(outputTokens) || outputTokens < 0) {
+    throw decisionError(DECISION_ERROR_CODES.RESULT_INVALID, "Semantic decision result usage is invalid.");
+  }
+  return { inputTokens, outputTokens, reportedBy: "PROVIDER" };
+}
+
+export function normalizeDecisionResult(raw, { questionSet, input = {}, model = PINNED_JEV_MODEL } = {}) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw decisionError(DECISION_ERROR_CODES.RESULT_INVALID, "Semantic decision result must be an object.");
+  if (raw.model !== model || raw.model !== PINNED_JEV_MODEL) throw decisionError(DECISION_ERROR_CODES.MODEL_UNSUPPORTED, "Semantic decision result used an unsupported model.");
+  if (!raw.answers || typeof raw.answers !== "object" || Array.isArray(raw.answers)) throw decisionError(DECISION_ERROR_CODES.RESULT_INVALID, "Semantic decision result is missing answers.");
+  const answers = normalizeAnswers(raw.answers, questionSet);
+  const confidence = normalizeConfidence(raw.confidence, questionSet);
+  const usage = normalizeUsage(raw.usage);
+  return {
+    model,
+    questionSetId: questionSet?.id ?? null,
+    answers,
+    confidence: Object.fromEntries(Object.keys(questionSet.questions).map((key) => [key, confidence[key] ?? null])),
+    decision: normalizeCanonicalDecision({ questionSet, answers, confidence, input }),
+    usage,
+  };
+}

package/src/core/decision/service.js

@@ -0,0 +1,181 @@
+import { canonicalFingerprint } from "../artifacts.js";
+import { readConfig } from "../config.js";
+import { appendProtocolEvent, iterateEvents } from "../events.js";
+import { withTaskMutation } from "../task-command.js";
+import { DECISION_DEFAULT_POLICY, PINNED_JEV_MODEL, SEMANTIC_DECISION_RECORDED_EVENT } from "./constants.js";
+import { buildDecisionArtifact, decisionArtifactFingerprint, readDecisionArtifact, writeDecisionArtifact } from "./artifact.js";
+import { decisionEventDetails, decisionSupersededEventDetails } from "./events.js";
+import { createTypesafeEngine } from "../../adapters/typesafe/engine.js";
+import { normalizeDecisionPolicy, decisionPolicyFingerprint } from "./policy.js";
+import { validateDecisionRequest } from "./request.js";
+import { normalizeDecisionResult } from "./result.js";
+import { randomUUID } from "node:crypto";
+import { readCurrentDecisionBindings } from "./task-bindings.js";
+import { resolveRequiredSemanticDecision } from "./resolver.js";
+import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
+import { getTaskTransaction } from "../transaction.js";
+import { getTestSemanticProvider } from "./test-provider.js";
+import { needsExistingProjectScope, withExistingProjectScope } from "../../storage/existing-project-scope.js";
+import { withProjectReadSnapshot } from "../../storage/project-read-snapshot.js";
+
+async function withDecisionScope(options, run) {
+  if (options.target && options.taskId && await needsExistingProjectScope(options.target)) {
+    return withExistingProjectScope(options.target, () => run(options));
+  }
+  return run(options);
+}
+
+function resolveProvider(provider) {
+  return provider ?? getTestSemanticProvider();
+}
+
+async function loadPolicy(target, packageRoot) {
+  try {
+    const config = await readConfig(target, packageRoot);
+    return normalizeDecisionPolicy(config.decisionEngine ?? DECISION_DEFAULT_POLICY);
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") return normalizeDecisionPolicy(DECISION_DEFAULT_POLICY);
+    throw error;
+  }
+}
+
+async function readCachedDecision({ target, packageRoot, taskId, decisionKind, currentBindings }) {
+  try {
+    return await resolveRequiredSemanticDecision({ target, packageRoot, taskId, decisionKind, currentBindings });
+  } catch (error) {
+    if (["E_DECISION_REQUIRED", "E_DECISION_STALE", "E_DECISION_BINDING_INVALID"].includes(error.code)) return null;
+    throw error;
+  }
+}
+
+function buildArtifact({ taskId, decisionId, policy, validated, result, request, taskBindings }) {
+  return buildDecisionArtifact({
+    taskId,
+    decisionId,
+    decisionKind: validated.decisionKind,
+    model: result.model ?? PINNED_JEV_MODEL,
+    questionSetId: validated.questionSet.id,
+    questionSetVersion: validated.questionSet.version,
+    questionSetFingerprint: validated.questionSet.fingerprint,
+    questionSet: validated.questionSet,
+    stateFingerprint: canonicalFingerprint(validated.state),
+    taskStateFingerprint: taskBindings.taskStateFingerprint ?? canonicalFingerprint(validated.state.lifecycle),
+    semanticStateFingerprint: canonicalFingerprint(validated.state.semantic),
+    policyVersion: policy.policyVersion,
+    policyFingerprint: decisionPolicyFingerprint(policy),
+    repositoryFingerprint: request.repositoryFingerprint ?? taskBindings.repositoryFingerprint,
+    contractFingerprint: request.contractFingerprint ?? taskBindings.contractFingerprint,
+    routeFingerprint: request.routeFingerprint ?? taskBindings.routeFingerprint,
+    verificationCycle: request.verificationCycle ?? taskBindings.verificationCycle,
+    candidateSetFingerprint: request.candidateSetFingerprint,
+    answers: result.answers,
+    confidence: result.confidence ?? {},
+    decision: result.decision,
+    usage: result.usage,
+    latencyMs: result.latencyMs ?? null,
+  });
+}
+
+async function readCachedSemanticDecision({ policy, decisionId, target, taskId, packageRoot, validated, taskBindings, request }) {
+  if (!policy.cache || decisionId || !target || !taskId || await getTaskTransaction(target)) return null;
+  return readCachedDecision({
+    target,
+    packageRoot,
+    taskId,
+    decisionKind: validated.decisionKind,
+    currentBindings: {
+      ...taskBindings,
+      stateFingerprint: canonicalFingerprint(validated.state),
+      taskStateFingerprint: taskBindings.taskStateFingerprint ?? canonicalFingerprint(validated.state.lifecycle),
+      semanticStateFingerprint: canonicalFingerprint(validated.state.semantic),
+      questionSetFingerprint: validated.questionSet.fingerprint,
+      policyFingerprint: decisionPolicyFingerprint(policy),
+      model: PINNED_JEV_MODEL,
+      ...(request?.candidateSetFingerprint !== undefined ? { candidateSetFingerprint: request.candidateSetFingerprint } : {}),
+      ...(request?.policyFingerprint !== undefined ? { policyFingerprint: request.policyFingerprint } : {}),
+    },
+  });
+}
+
+async function persistDecision(target, packageRoot, resolvedDecisionId, artifact, ctx) {
+  await writeDecisionArtifact(target, ctx.taskId, resolvedDecisionId, artifact, packageRoot, { taskId: ctx.taskId, operation: "semantic-decision" });
+  const priorRecords = [];
+  const supersededIds = new Set();
+  for await (const candidate of iterateEvents(target, packageRoot, { taskId: ctx.taskId })) {
+    if (candidate.event === SEMANTIC_DECISION_RECORDED_EVENT && candidate.taskId === ctx.taskId
+      && candidate.details?.decisionKind === artifact.decisionKind) priorRecords.push(candidate);
+    if (candidate.event === "SEMANTIC_DECISION_SUPERSEDED") supersededIds.add(candidate.details?.decisionId);
+  }
+  const event = await appendProtocolEvent(target, { taskId: ctx.taskId, event: SEMANTIC_DECISION_RECORDED_EVENT, details: decisionEventDetails(artifact) }, packageRoot, { taskId: ctx.taskId });
+  const previous = priorRecords.findLast(candidate => !supersededIds.has(candidate.details?.decisionId));
+  if (!previous) return { artifact, artifactFingerprint: decisionArtifactFingerprint(artifact), event, supersededEvent: null };
+  const previousArtifact = await readDecisionArtifact(target, ctx.taskId, previous.details.decisionId, packageRoot);
+  const supersededEvent = await appendProtocolEvent(target, {
+    taskId: ctx.taskId,
+    event: "SEMANTIC_DECISION_SUPERSEDED",
+    details: decisionSupersededEventDetails(previousArtifact.value, resolvedDecisionId),
+  }, packageRoot, { taskId: ctx.taskId });
+  return { artifact, artifactFingerprint: decisionArtifactFingerprint(artifact), event, supersededEvent };
+}
+
+export async function recordSemanticDecision(options = {}) {
+  return withDecisionScope(options, recordSelectedSemanticDecision);
+}
+
+async function recordSelectedSemanticDecision({ target, packageRoot, taskId, decisionId, request, provider = null }) {
+  const resolvedDecisionId = decisionId ?? `${String(request?.decisionKind ?? "decision").toLowerCase()}-${Date.now()}-${randomUUID().slice(0, 8)}`;
+  const { policy, taskBindings, validated, cached } = await withProjectReadSnapshot(target, async () => {
+    const policy = await loadPolicy(target, packageRoot);
+    const taskBindings = target && taskId ? await readCurrentDecisionBindings(target, packageRoot, taskId) : {};
+    const validated = validateDecisionRequest({
+      ...request,
+      taskId,
+      state: { lifecycle: taskBindings.state ?? {}, semantic: request?.state ?? {} },
+    });
+    const cached = await readCachedSemanticDecision({ policy, decisionId, target, taskId, packageRoot, validated, taskBindings, request });
+    return { policy, taskBindings, validated, cached };
+  });
+  if (cached) return { artifact: cached, artifactFingerprint: decisionArtifactFingerprint(cached), event: null, supersededEvent: null, cached: true, policy };
+  const engine = resolveProvider(provider) ?? createTypesafeEngine({ policy });
+  if (provider && (provider.id !== "typesafe-jev" || provider.model !== PINNED_JEV_MODEL || typeof provider.evaluate !== "function")) {
+    throw decisionError(DECISION_ERROR_CODES.MODEL_UNSUPPORTED, "Semantic decision provider must be the pinned ForgeLoop Jev engine.");
+  }
+  const result = normalizeDecisionResult(await engine.evaluate(validated), { questionSet: validated.questionSet, input: validated });
+  const artifact = buildArtifact({ taskId, decisionId: resolvedDecisionId, policy, validated, result, request, taskBindings });
+  const persisted = await withTaskMutation(target, { taskId, packageRoot }, "semantic-decision", (ctx) => persistDecision(target, packageRoot, resolvedDecisionId, artifact, ctx), { explicitRequired: true });
+  return { ...persisted, policy };
+}
+
+export async function ensureSemanticDecision(options = {}) {
+  return withDecisionScope(options, ensureSelectedSemanticDecision);
+}
+
+async function ensureSelectedSemanticDecision({ target, packageRoot, taskId, decisionId, request, provider = null, allowNetwork = true }) {
+  const { policy, validated, cached } = await withProjectReadSnapshot(target, async () => {
+    const policy = await loadPolicy(target, packageRoot);
+    const taskBindings = await readCurrentDecisionBindings(target, packageRoot, taskId);
+    const validated = validateDecisionRequest({
+      ...request,
+      taskId,
+      state: { lifecycle: taskBindings.state ?? {}, semantic: request?.state ?? {} },
+    });
+    const currentBindings = {
+      ...taskBindings,
+      stateFingerprint: canonicalFingerprint(validated.state),
+      taskStateFingerprint: taskBindings.taskStateFingerprint ?? canonicalFingerprint(validated.state.lifecycle),
+      semanticStateFingerprint: canonicalFingerprint(validated.state.semantic),
+      questionSetFingerprint: validated.questionSet.fingerprint,
+      policyFingerprint: decisionPolicyFingerprint(policy),
+      model: PINNED_JEV_MODEL,
+      ...(request?.candidateSetFingerprint !== undefined ? { candidateSetFingerprint: request.candidateSetFingerprint } : {}),
+    };
+    const cached = await getTaskTransaction(target) ? null : await readCachedDecision({
+      target, packageRoot, taskId, decisionKind: validated.decisionKind,
+      currentBindings,
+    });
+    return { policy, validated, cached };
+  });
+  if (cached) return { artifact: cached, artifactFingerprint: decisionArtifactFingerprint(cached), cached: true, policy };
+  if (!allowNetwork && !provider) throw decisionError(DECISION_ERROR_CODES.REQUIRED, `A current ${validated.decisionKind} decision is required.`);
+  return recordSemanticDecision({ target, packageRoot, taskId, decisionId, request: { ...request, questionSet: validated.questionSet }, provider });
+}

package/src/core/decision/state-builder.js

@@ -0,0 +1,65 @@
+import { Buffer } from "node:buffer";
+import { DECISION_LIMITS } from "./constants.js";
+import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
+
+const SECRET_KEY = /(^|[_-])(api[_-]?key|password|passwd|secret|token|refresh|cookie|authorization|private[_-]?key|credential|database[_-]?url|connection[_-]?string|access[_-]?key|client[_-]?secret)([_-]|$)/i;
+const SECRET_VALUE = /^(?:bearer\s+)?(?:sk-|pk-|ghp_|github_pat_|xox[baprs]-|AIza|AKIA)[A-Za-z0-9._-]{12,}$/i;
+
+function isHomePath(value) {
+  return typeof value === "string" && (/^\/Users\/[^/]+\//.test(value) || /^\/home\/[^/]+\//.test(value));
+}
+
+function sanitize(value, depth, counters) {
+  if (depth > DECISION_LIMITS.maxDepth) throw decisionError(DECISION_ERROR_CODES.STATE_LIMIT, "Decision state nesting exceeds the supported limit.");
+  if (value === null || typeof value === "boolean" || typeof value === "number") return value;
+  if (typeof value === "string") {
+    if (/[^\x09\x0A\x0D\x20-\uD7FF\uE000-\uFFFD]/u.test(value)) throw decisionError(DECISION_ERROR_CODES.STATE_UNSAFE, "Decision state contains unsafe control characters.");
+    if (SECRET_VALUE.test(value)) throw decisionError(DECISION_ERROR_CODES.STATE_UNSAFE, "Decision state contains a secret-like value.");
+    if (isHomePath(value)) return "<redacted-user-path>";
+    counters.bytes += Buffer.byteLength(value);
+    if (value.length > DECISION_LIMITS.maxStringChars) return `${value.slice(0, DECISION_LIMITS.maxStringChars)}…<truncated>`;
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > DECISION_LIMITS.maxItems) throw decisionError(DECISION_ERROR_CODES.STATE_LIMIT, "Decision state contains too many items.");
+    return value.map((item) => sanitize(item, depth + 1, counters));
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value);
+    if (entries.length > DECISION_LIMITS.maxItems) throw decisionError(DECISION_ERROR_CODES.STATE_LIMIT, "Decision state contains too many fields.");
+    const result = {};
+    for (const [key, child] of entries) {
+      if (SECRET_KEY.test(key) || key.toLowerCase() === "env" || key.toLowerCase() === "environment") continue;
+      result[key] = sanitize(child, depth + 1, counters);
+    }
+    return result;
+  }
+  throw decisionError(DECISION_ERROR_CODES.STATE_UNSAFE, "Decision state contains an unsupported value.");
+}
+
+export function buildDecisionState(value) {
+  const counters = { bytes: 0 };
+  const sanitized = sanitize(value, 0, counters);
+  const bytes = Buffer.byteLength(JSON.stringify(sanitized));
+  if (bytes > DECISION_LIMITS.maxStateBytes) throw decisionError(DECISION_ERROR_CODES.STATE_LIMIT, "Decision state exceeds the supported byte limit.");
+  return sanitized;
+}
+
+export function buildLifecycleDecisionState(value = {}) {
+  return buildDecisionState(value ?? {});
+}
+
+export function buildSemanticDecisionState(value = {}) {
+  return buildDecisionState(value ?? {});
+}
+
+export function buildCombinedDecisionState({ lifecycle = {}, semantic = {} } = {}) {
+  return {
+    lifecycle: buildLifecycleDecisionState(lifecycle),
+    semantic: buildSemanticDecisionState(semantic),
+  };
+}
+
+export function decisionStateFingerprint(value, canonicalFingerprint) {
+  return canonicalFingerprint(buildDecisionState(value));
+}

package/src/core/decision/task-bindings.js

@@ -0,0 +1,35 @@
+import { canonicalFingerprint } from "../artifacts.js";
+import { readContract } from "../contract.js";
+import { readPersistedRoute } from "../route-artifact.js";
+import { readWorkState } from "../work-state.js";
+import { withProjectReadSnapshot } from "../../storage/project-read-snapshot.js";
+
+async function readOptionalArtifact(reader) {
+  try {
+    return await reader();
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") return null;
+    throw error;
+  }
+}
+
+export async function readCurrentDecisionBindings(target, packageRoot, taskId, options = {}) {
+  return withProjectReadSnapshot(target, () => readSnapshotBindings(target, packageRoot, taskId, options));
+}
+
+async function readSnapshotBindings(target, packageRoot, taskId, { candidateSetFingerprint, policyFingerprint }) {
+  const state = await readWorkState(target, { packageRoot, taskId });
+  const contract = await readOptionalArtifact(() => readContract(target, packageRoot, { taskId }));
+  const route = await readOptionalArtifact(() => readPersistedRoute(target, packageRoot, { taskId }));
+  return {
+    state,
+    ...(state ? { stateFingerprint: canonicalFingerprint(state) } : {}),
+    ...(state ? { taskStateFingerprint: canonicalFingerprint(state) } : {}),
+    ...(state?.repositoryFingerprint ? { repositoryFingerprint: state.repositoryFingerprint } : {}),
+    ...((contract?.fingerprint ?? state?.contractFingerprint) ? { contractFingerprint: contract?.fingerprint ?? state.contractFingerprint } : {}),
+    ...((route?.fingerprint ?? state?.routeFingerprint) ? { routeFingerprint: route?.fingerprint ?? state.routeFingerprint } : {}),
+    ...(state?.verificationCycle !== undefined ? { verificationCycle: state.verificationCycle } : {}),
+    ...(candidateSetFingerprint !== undefined ? { candidateSetFingerprint } : {}),
+    ...(policyFingerprint !== undefined ? { policyFingerprint } : {}),
+  };
+}

package/src/core/decision/test-provider.js

@@ -0,0 +1,32 @@
+// This provider is deliberately reachable only through repository test injection.
+// Production commands always use the pinned TypeSafe Jev engine or fail closed.
+export const testSemanticProvider = Object.freeze({
+  id: "typesafe-jev",
+  model: "jev-1.13.0",
+  async evaluate(request) {
+    const answers = Object.fromEntries(Object.entries(request.questionSet.questions).map(([name, question]) => [
+      name,
+      question.type === "choice" ? Object.keys(question.criteria)[0] : { noul: true },
+    ]));
+    return {
+      model: "jev-1.13.0",
+      answers,
+      confidence: Object.fromEntries(Object.keys(answers).map((name) => [name, 0.95])),
+      usage: { inputTokens: 0, outputTokens: 0 },
+    };
+  },
+});
+
+let activeTestSemanticProvider = null;
+
+export function installTestSemanticProvider(provider = testSemanticProvider) {
+  activeTestSemanticProvider = provider;
+}
+
+export function clearTestSemanticProvider() {
+  activeTestSemanticProvider = null;
+}
+
+export function getTestSemanticProvider() {
+  return activeTestSemanticProvider;
+}

package/src/core/decision/thresholds.js

@@ -0,0 +1,15 @@
+export const DECISION_RISK_TIERS = Object.freeze(["LOW_RISK", "NORMAL", "HIGH_RISK", "CRITICAL"]);
+export const DECISION_THRESHOLDS = Object.freeze({
+  LOW_RISK: 0.65,
+  NORMAL: 0.75,
+  HIGH_RISK: 0.9,
+  CRITICAL: 0.97,
+});
+
+export function decisionConfidenceThreshold(risk = "NORMAL") {
+  return DECISION_THRESHOLDS[risk] ?? DECISION_THRESHOLDS.NORMAL;
+}
+
+export function requiresEscalation(confidence, risk = "NORMAL") {
+  return typeof confidence !== "number" || confidence < decisionConfidenceThreshold(risk);
+}

package/src/core/diagnosis-model.js

@@ -1,3 +1,5 @@
+import { ledgerEventsOfTypes } from "./ledger-event-collection.js";
+
 import { canonicalFingerprint } from "./artifacts.js";
 import { assertFailureClass } from "./protocol.js";
 
@@ -212,3 +214,12 @@ export function currentCycleDiagnosis(events, taskId, verificationCycle) {
   }
   return null;
 }
+
+
+export function latestDiagnosisForTask(events, taskId) {
+  let latest = null;
+  for (const event of ledgerEventsOfTypes(events ?? [], ["DIAGNOSIS_RECORDED"])) {
+    if (!taskId || event.taskId === taskId) latest = event;
+  }
+  return latest;
+}

package/src/core/diagnosis.js

@@ -1,5 +1,6 @@
 import { appendProtocolEvent, validateEventLedger } from "./events.js";
 import { readWorkState, mutateWorkState } from "./work-state.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
 import {
   DIAGNOSIS_INFORMATION_GAIN,
   assertDiagnosisDetails,
@@ -22,7 +23,15 @@ export {
   normalizeDiagnosisText,
 };
 
-export async function recordDiagnosis({
+export async function recordDiagnosis(options) {
+  if (await getTaskTransaction(options.target)) return recordDiagnosisInTransaction(options);
+  const state = await readWorkState(options.target, { packageRoot: options.packageRoot, taskId: options.taskId, statePath: options.statePath });
+  if (!state) return recordDiagnosisInTransaction(options);
+  return withTaskTransaction({ target: options.target, taskId: options.taskId ?? state.taskId,
+    packageRoot: options.packageRoot, operation: "record-diagnosis" }, () => recordDiagnosisInTransaction(options));
+}
+
+async function recordDiagnosisInTransaction({
   target,
   packageRoot,
   hypothesis,

package/src/core/diagnostic-projection.js

@@ -1,9 +1,17 @@
+import { ledgerEventsOfTypes } from "./ledger-event-collection.js";
+
 export function diagnosticEventsForTask(events, taskId) {
   return (events ?? []).filter((event) =>
     (event.event === "DIAGNOSTIC_CASE_RECORDED" || event.event === "DIAGNOSIS_RECORDED")
     && (!taskId || event.taskId === taskId));
 }
 
+export function* iterateDiagnosticEvents(events, taskId) {
+  for (const event of ledgerEventsOfTypes(events ?? [], ["DIAGNOSTIC_CASE_RECORDED", "DIAGNOSIS_RECORDED"])) {
+    if (!taskId || event.taskId === taskId) yield event;
+  }
+}
+
 function structuredProjection(event) {
   const details = event.details ?? {};
   return {
@@ -26,20 +34,29 @@ function legacyProjection(event) {
   };
 }
 
+function resolveArrayCurrentCycleDiagnostic(events, taskId, verificationCycle) {
+  const candidates = diagnosticEventsForTask(events, taskId).filter(event => {
+    const cycle = event.details?.verificationCycle;
+    return verificationCycle === null || verificationCycle === undefined || cycle === null || cycle === undefined || cycle === verificationCycle;
+  }).sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+  const structured = [...candidates].reverse().find(event => event.event === "DIAGNOSTIC_CASE_RECORDED");
+  const legacy = [...candidates].reverse().find(event => event.event === "DIAGNOSIS_RECORDED");
+  return structured ? structuredProjection(structured) : (legacy ? legacyProjection(legacy) : null);
+}
+
 export function resolveCurrentCycleDiagnostic(events, taskId, verificationCycle) {
-  const candidates = diagnosticEventsForTask(events, taskId)
-    .filter((event) => {
-      const cycle = event.details?.verificationCycle;
-      return (verificationCycle === null || verificationCycle === undefined)
-        || (cycle === null || cycle === undefined)
-        || cycle === verificationCycle;
-    })
-    .sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
-
-  const structured = [...candidates].reverse().find((event) => event.event === "DIAGNOSTIC_CASE_RECORDED");
+  if (Array.isArray(events)) return resolveArrayCurrentCycleDiagnostic(events, taskId, verificationCycle);
+  let structured = null;
+  let legacy = null;
+  for (const event of iterateDiagnosticEvents(events, taskId)) {
+    const cycle = event.details?.verificationCycle;
+    if (verificationCycle !== null && verificationCycle !== undefined
+      && cycle !== null && cycle !== undefined && cycle !== verificationCycle) continue;
+    if (event.event === "DIAGNOSTIC_CASE_RECORDED") {
+      if (!structured || (event.seq ?? 0) >= (structured.seq ?? 0)) structured = event;
+    } else if (!legacy || (event.seq ?? 0) >= (legacy.seq ?? 0)) legacy = event;
+  }
   if (structured) return structuredProjection(structured);
-
-  const legacy = [...candidates].reverse().find((event) => event.event === "DIAGNOSIS_RECORDED");
   if (legacy) return legacyProjection(legacy);
 
   return null;