@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/src/core/events.js

@@ -9,6 +9,15 @@ import { assertSchema, readSchema } from "./schema-validation.js";
 import { assertSecretFree } from "./receipt.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { isRecoverableCompletionEvidenceCode } from "./completion-recovery.js";
+import {
+  CONTRACT_BOOTSTRAP_REPAIR_EVENT,
+  ROUTE_CHECKPOINT_BOUND_EVENT,
+  assertContractBootstrapRepairDetails,
+  assertContractBootstrapRepairMigrationDetails,
+  isLegacyContractBootstrapRepairMarkerShape,
+  validateContractBootstrapRepairMigrations,
+  repairMarkerErrors,
+} from "./contract-bootstrap-recovery.js";
 
 import { taskArtifactPath } from "./task-paths.js";
 import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
@@ -33,6 +42,32 @@ import {
   isLegacyRecoveryEventShape,
   legacyRecoveryMigrationId,
 } from "./task-recovery-migration.js";
+import {
+  CHECKPOINT_REVALIDATED_EVENT,
+  assertCheckpointRevalidatedDetails,
+  validateCheckpointRevalidationCurrentBinding,
+  validateCheckpointRevalidationEventBindings,
+} from "./checkpoint-revalidation.js";
+import {
+  CONTRACT_REVISED_EVENT,
+  assertContractRevisedDetails,
+  validateContractRevisionCurrentBinding,
+  validateContractRevisionEventBindings,
+} from "./contract-revision.js";
+import {
+  GATE_SATISFIED_EVENT,
+  GATE_REVALIDATED_EVENT,
+  assertGateSatisfiedDetails,
+  assertGateRevalidatedDetails,
+  hasCurrentGateEvidence,
+  validateGateSatisfactionBindings,
+} from "./gate-provenance.js";
+import {
+  assertSemanticDecisionDetails,
+  validateSemanticDecisionArtifactBindings,
+  validateSemanticDecisionEventBindings,
+} from "./decision/events.js";
+import { SEMANTIC_DECISION_RECORDED_EVENT, SEMANTIC_DECISION_SUPERSEDED_EVENT } from "./decision/constants.js";
 
 const EVENT_SCHEMA_VERSION = 1;
 export const LIFECYCLE_MILESTONES = Object.freeze([
@@ -60,6 +95,48 @@ const REPEATABLE_MILESTONES = new Set([
   "PREFLIGHT_READY",
 ]);
 
+export function isRevisionEpochPlanRepeat(events = [], index = 0, event = null) {
+  if (event?.event !== "PLAN_RECORDED") return false;
+  const previousPlan = events.slice(0, index).findLast((candidate) => candidate.event === "PLAN_RECORDED");
+  const revision = events.slice(0, index).findLast((candidate) => candidate.event === CONTRACT_REVISED_EVENT);
+  return Boolean(previousPlan && revision && previousPlan.seq < revision.seq);
+}
+
+function validateMilestoneChronology(events, index, event, milestoneCounts, lastMilestone, errors) {
+  const milestoneIndex = LIFECYCLE_MILESTONES.indexOf(event.event);
+  if (milestoneIndex < 0) return lastMilestone;
+  const count = (milestoneCounts.get(event.event) ?? 0) + 1;
+  milestoneCounts.set(event.event, count);
+  const revisionPlanRepeat = isRevisionEpochPlanRepeat(events, index, event);
+  if (count > 1 && !REPEATABLE_MILESTONES.has(event.event) && !revisionPlanRepeat) {
+    errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `lifecycle milestone must not repeat: ${event.event}` });
+  }
+  if (milestoneIndex > lastMilestone + 1) {
+    errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `${event.event} is missing prerequisite milestone: ${LIFECYCLE_MILESTONES[lastMilestone + 1]}` });
+  } else if (milestoneIndex < lastMilestone && event.event !== "VERIFICATION_STARTED" && event.event !== "PREFLIGHT_READY") {
+    errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `${event.event} is out of lifecycle order` });
+  } else if (milestoneIndex === lastMilestone && !REPEATABLE_MILESTONES.has(event.event) && !revisionPlanRepeat) {
+    errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `lifecycle milestone must not repeat: ${event.event}` });
+  }
+  if (milestoneIndex > lastMilestone) return milestoneIndex;
+  return lastMilestone;
+}
+
+function validateExecutionGateChronology(events, index, seen, errors) {
+  if (!seen.has("ROUTE_VALIDATED")) errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before route validation" });
+  if (!seen.has("CONTRACT_VALIDATED")) errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before contract validation" });
+  if (!seen.has("PREFLIGHT_READY")) errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before preflight readiness" });
+  const preflight = events.slice(0, index).findLast((candidate) => candidate.event === "PREFLIGHT_READY");
+  const requiredGates = preflight?.details?.requiredGates ?? [];
+  const latestContractRevisionSeq = events.slice(0, index).findLast((candidate) => candidate.event === CONTRACT_REVISED_EVENT)?.seq ?? 0;
+  const beforeExecution = events.slice(0, index);
+  for (const gate of requiredGates) {
+    if (!hasCurrentGateEvidence(beforeExecution, events[index]?.taskId, gate, latestContractRevisionSeq)) {
+      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `execution started before gate satisfaction: ${gate}` });
+    }
+  }
+}
+
 function eventIndexPath(eventsPath) {
   return `${eventsPath}.index.json`;
 }
@@ -125,6 +202,22 @@ export function validateKnownEventDetails(event) {
     case "CHECKPOINT_RECONCILED":
       assertReconcileClosureDetails(event.details);
       return;
+    case CHECKPOINT_REVALIDATED_EVENT:
+      assertCheckpointRevalidatedDetails(event.details);
+      return;
+    case CONTRACT_REVISED_EVENT:
+      assertContractRevisedDetails(event.details);
+      return;
+    case GATE_SATISFIED_EVENT:
+      assertGateSatisfiedDetails(event.details);
+      return;
+    case GATE_REVALIDATED_EVENT:
+      assertGateRevalidatedDetails(event.details);
+      return;
+    case SEMANTIC_DECISION_RECORDED_EVENT:
+    case SEMANTIC_DECISION_SUPERSEDED_EVENT:
+      assertSemanticDecisionDetails(event.details, event.event);
+      return;
     case "TASK_RECOVERY_RECORDED":
       assertRecoveryRecordedDetails(event.details);
       return;
@@ -135,18 +228,27 @@ export function validateKnownEventDetails(event) {
       if (!event.details?.recoveryId && isLegacyRecoveryDetailsShape(event.details)) return;
       assertRecoveryRecordedDetails(event.details);
       return;
+    case "TASK_ABANDONED":
+      assertTaskAbandonedDetails(event.details);
+      return;
     case "LEGACY_RECOVERY_MIGRATION_RECORDED":
       assertLegacyMigrationDetails(event.details);
       return;
+    case CONTRACT_BOOTSTRAP_REPAIR_EVENT:
+    case "CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_RECORDED":
+      validateKnownContractBootstrapEvent(event);
+      return;
+    case "ROUTE_REBOUND":
+      assertRouteReboundDetails(event.details);
+      return;
+    case ROUTE_CHECKPOINT_BOUND_EVENT:
+      assertRouteCheckpointBoundDetails(event.details);
+      return;
     case "TASK_RECOVERY_RESUMED":
       assertRecoveryResumedDetails(event.details);
       return;
     case "TRAJECTORY_EVALUATED":
-      if (!event.details || !/^eval-[A-Za-z0-9_-]+$/.test(event.details.evaluationId ?? "")
-        || typeof event.details.scenarioId !== "string" || !/^[a-f0-9]{64}$/.test(event.details.evaluationFingerprint ?? "")
-        || event.fingerprint !== event.details.evaluationFingerprint) {
-        throw protocolError("E_EVENT_INVALID", "TRAJECTORY_EVALUATED requires a bound evaluationId, scenarioId, and fingerprint");
-      }
+      assertTrajectoryEvaluatedDetails(event);
       return;
     case "WORKSPACE_BOUND":
       assertStructuredArtifactEvent(event, ["workspaceFingerprint"], "WORKSPACE_BOUND");
@@ -161,14 +263,7 @@ export function validateKnownEventDetails(event) {
       assertFingerprint(event.details.digest, "HANDOFF_CREATED details.digest");
       return;
     case "HANDOFF_ACCEPTED":
-      if (!event.details || typeof event.details !== "object" || Array.isArray(event.details)
-        || typeof event.details.handoffId !== "string" || !/^handoff-[A-Za-z0-9_-]+$/.test(event.details.handoffId)
-        || typeof event.details.handoffDigest !== "string"
-        || typeof event.details.consumerId !== "string" || !event.details.consumerId.trim()
-        || (event.details.harness !== undefined && (typeof event.details.harness !== "string" || !event.details.harness.trim()))) {
-        throw protocolError("E_EVENT_INVALID", "HANDOFF_ACCEPTED requires a valid handoffId, handoffDigest, and consumerId");
-      }
-      assertFingerprint(event.details.handoffDigest, "HANDOFF_ACCEPTED details.handoffDigest");
+      assertHandoffAcceptedDetails(event);
       return;
     case "RESPONSIBILITY_SET":
       assertStructuredArtifactEvent(event, ["responsibilityFingerprint"], "RESPONSIBILITY_SET");
@@ -207,6 +302,34 @@ export function validateKnownEventDetails(event) {
   }
 }
 
+function validateKnownContractBootstrapEvent(event) {
+  if (event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT) {
+    if (isLegacyContractBootstrapRepairMarkerShape(event)) return;
+    assertContractBootstrapRepairDetails(event.details);
+    return;
+  }
+  assertContractBootstrapRepairMigrationDetails(event.details);
+}
+
+function assertTrajectoryEvaluatedDetails(event) {
+  if (!event.details || !/^eval-[A-Za-z0-9_-]+$/.test(event.details.evaluationId ?? "")
+    || typeof event.details.scenarioId !== "string" || !/^[a-f0-9]{64}$/.test(event.details.evaluationFingerprint ?? "")
+    || event.fingerprint !== event.details.evaluationFingerprint) {
+    throw protocolError("E_EVENT_INVALID", "TRAJECTORY_EVALUATED requires a bound evaluationId, scenarioId, and fingerprint");
+  }
+}
+
+function assertHandoffAcceptedDetails(event) {
+  if (!event.details || typeof event.details !== "object" || Array.isArray(event.details)
+    || typeof event.details.handoffId !== "string" || !/^handoff-[A-Za-z0-9_-]+$/.test(event.details.handoffId)
+    || typeof event.details.handoffDigest !== "string"
+    || typeof event.details.consumerId !== "string" || !event.details.consumerId.trim()
+    || (event.details.harness !== undefined && (typeof event.details.harness !== "string" || !event.details.harness.trim()))) {
+    throw protocolError("E_EVENT_INVALID", "HANDOFF_ACCEPTED requires a valid handoffId, handoffDigest, and consumerId");
+  }
+  assertFingerprint(event.details.handoffDigest, "HANDOFF_ACCEPTED details.handoffDigest");
+}
+
 function assertStringList(value, label) {
   if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item)) {
     throw protocolError("E_EVENT_INVALID", `${label} must be an array of non-empty strings`);
@@ -234,6 +357,35 @@ function assertStructuredArtifactEvent(event, requiredDetails, label) {
   }
 }
 
+function assertRouteReboundDetails(details) {
+  const keys = ["routeFingerprint", "contractFingerprint", "previousRouteFingerprint"];
+  if (!details || typeof details !== "object" || Array.isArray(details)
+    || Object.keys(details).length !== keys.length
+    || keys.some((key) => !Object.prototype.hasOwnProperty.call(details, key))) {
+    throw protocolError("E_EVENT_INVALID", "ROUTE_REBOUND requires exactly route, contract, and previous route fingerprints");
+  }
+  assertFingerprint(details.routeFingerprint, "ROUTE_REBOUND details.routeFingerprint");
+  assertFingerprint(details.contractFingerprint, "ROUTE_REBOUND details.contractFingerprint");
+  if (details.previousRouteFingerprint !== null) {
+    assertFingerprint(details.previousRouteFingerprint, "ROUTE_REBOUND details.previousRouteFingerprint");
+  }
+}
+
+function assertRouteCheckpointBoundDetails(details) {
+  const keys = ["routeFingerprint", "contractFingerprint", "selectedGuides"];
+  if (!details || typeof details !== "object" || Array.isArray(details)
+    || Object.keys(details).length !== keys.length
+    || keys.some((key) => !Object.prototype.hasOwnProperty.call(details, key))) {
+    throw protocolError("E_EVENT_INVALID", "ROUTE_CHECKPOINT_BOUND requires exactly route, contract, and selected guide identity");
+  }
+  assertFingerprint(details.routeFingerprint, "ROUTE_CHECKPOINT_BOUND details.routeFingerprint");
+  assertFingerprint(details.contractFingerprint, "ROUTE_CHECKPOINT_BOUND details.contractFingerprint");
+  assertStringList(details.selectedGuides, "ROUTE_CHECKPOINT_BOUND details.selectedGuides");
+  if (new Set(details.selectedGuides).size !== details.selectedGuides.length) {
+    throw protocolError("E_EVENT_INVALID", "ROUTE_CHECKPOINT_BOUND details.selectedGuides must not contain duplicates");
+  }
+}
+
 function assertRecoveryRecordedDetails(details) {
   if (!details || typeof details !== "object" || Array.isArray(details)) {
     throw protocolError("E_EVENT_INVALID", "recovery event requires structured details");
@@ -256,6 +408,44 @@ function assertRecoveryRecordedDetails(details) {
   assertStringList(details.releasedClaims, "recovery event details.releasedClaims");
 }
 
+function assertTaskAbandonedDetails(details) {
+  const keys = [
+    "recoveryId", "classification", "reasonCodes", "previousPhase", "previousRevision",
+    "previousHead", "previousBranch", "currentHead", "currentBranch",
+    "releasedClaims", "authorityKind",
+  ];
+  if (!details || typeof details !== "object" || Array.isArray(details)
+    || Object.keys(details).length !== keys.length
+    || keys.some((key) => !Object.prototype.hasOwnProperty.call(details, key))) {
+    throw protocolError("E_EVENT_INVALID", "TASK_ABANDONED requires the exact abandonment boundary details");
+  }
+  if (typeof details.recoveryId !== "string" || details.recoveryId.length === 0) {
+    throw protocolError("E_EVENT_INVALID", "TASK_ABANDONED details.recoveryId must be a non-empty string");
+  }
+  if (details.classification !== "ABANDONED") {
+    throw protocolError("E_EVENT_INVALID", "TASK_ABANDONED details.classification must be ABANDONED");
+  }
+  assertStringList(details.reasonCodes, "TASK_ABANDONED details.reasonCodes");
+  if (details.reasonCodes.length !== 1 || details.reasonCodes[0] !== "CALLER_ABANDONED") {
+    throw protocolError("E_EVENT_INVALID", "TASK_ABANDONED details.reasonCodes must be [CALLER_ABANDONED]");
+  }
+  if (typeof details.previousPhase !== "string" || details.previousPhase.length === 0) {
+    throw protocolError("E_EVENT_INVALID", "TASK_ABANDONED details.previousPhase must be a non-empty string");
+  }
+  if (!Number.isInteger(details.previousRevision) || details.previousRevision < 0) {
+    throw protocolError("E_EVENT_INVALID", "TASK_ABANDONED details.previousRevision must be a non-negative integer");
+  }
+  for (const key of ["previousHead", "previousBranch", "currentHead", "currentBranch"]) {
+    if (typeof details[key] !== "string" && details[key] !== null) {
+      throw protocolError("E_EVENT_INVALID", `TASK_ABANDONED details.${key} must be a string or null`);
+    }
+  }
+  assertStringList(details.releasedClaims, "TASK_ABANDONED details.releasedClaims");
+  if (details.authorityKind !== "CALLER_ACKNOWLEDGED") {
+    throw protocolError("E_EVENT_INVALID", "TASK_ABANDONED details.authorityKind must be CALLER_ACKNOWLEDGED");
+  }
+}
+
 function assertRecoveryResumedDetails(details) {
   if (!details || typeof details !== "object" || Array.isArray(details)
     || typeof details.recoveryId !== "string" || !details.recoveryId) {
@@ -542,50 +732,10 @@ export async function validateEventLedger(target, packageRoot, options = {}) {
     } catch (err) {
       errors.push({ code: err.code ?? "E_EVENT_INVALID", message: `event ${event.seq} (${event.event}): ${err.message}` });
     }
-    const milestoneIndex = LIFECYCLE_MILESTONES.indexOf(event.event);
-    if (milestoneIndex >= 0) {
-      const count = (milestoneCounts.get(event.event) ?? 0) + 1;
-      milestoneCounts.set(event.event, count);
-      if (count > 1 && !REPEATABLE_MILESTONES.has(event.event)) {
-        errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `lifecycle milestone must not repeat: ${event.event}` });
-      }
-      if (milestoneIndex > lastMilestone + 1) {
-        errors.push({
-          code: "E_PHASE_CHRONOLOGY_INVALID",
-          message: `${event.event} is missing prerequisite milestone: ${LIFECYCLE_MILESTONES[lastMilestone + 1]}`,
-        });
-      } else if (milestoneIndex < lastMilestone && event.event !== "VERIFICATION_STARTED"
-        && event.event !== "PREFLIGHT_READY") {
-        // VERIFICATION_STARTED re-enters per verification cycle; PREFLIGHT_READY
-        // may be refreshed mid-lifecycle (policy/contract evolution) after its
-        // prerequisites were already satisfied by the earlier occurrence.
-        errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `${event.event} is out of lifecycle order` });
-      } else if (milestoneIndex === lastMilestone && !REPEATABLE_MILESTONES.has(event.event)) {
-        errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `lifecycle milestone must not repeat: ${event.event}` });
-      }
-      if (milestoneIndex > lastMilestone) lastMilestone = milestoneIndex;
-    }
+    lastMilestone = validateMilestoneChronology(events, index, event, milestoneCounts, lastMilestone, errors);
     seen.add(event.event);
-    if (event.event === "EXECUTION_STARTED" && !seen.has("ROUTE_VALIDATED")) {
-      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before route validation" });
-    }
-    if (event.event === "EXECUTION_STARTED" && !seen.has("CONTRACT_VALIDATED")) {
-      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before contract validation" });
-    }
-    if (event.event === "EXECUTION_STARTED" && !seen.has("PREFLIGHT_READY")) {
-      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before preflight readiness" });
-    }
     if (event.event === "EXECUTION_STARTED") {
-      const preflight = events.slice(0, index).findLast((candidate) => candidate.event === "PREFLIGHT_READY");
-      const requiredGates = preflight?.details?.requiredGates ?? [];
-      const satisfiedGates = new Set(events.slice(0, index)
-        .filter((candidate) => candidate.event === "GATE_SATISFIED")
-        .map((candidate) => candidate.details?.gate));
-      for (const gate of requiredGates) {
-        if (!satisfiedGates.has(gate)) {
-          errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `execution started before gate satisfaction: ${gate}` });
-        }
-      }
+      validateExecutionGateChronology(events, index, seen, errors);
     }
     if (event.event === "VERIFICATION_RECORDED" && !seen.has("VERIFICATION_STARTED")) {
       errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "verification evidence recorded before verification started" });
@@ -620,11 +770,30 @@ export async function validateEventLedger(target, packageRoot, options = {}) {
   validateLegacyRecoveryMigrations(events, errors, {
     allowUnmigratedLegacyRecoveryEvents: options?.allowUnmigratedLegacyRecoveryEvents === true,
   });
-  return { valid: errors.length === 0, events, errors };
+  errors.push(...validateCheckpointRevalidationEventBindings(events));
+  errors.push(...validateContractRevisionEventBindings(events));
+  errors.push(...validateGateSatisfactionBindings(events));
+  errors.push(...validateSemanticDecisionEventBindings(events));
+  errors.push(...await validateSemanticDecisionArtifactBindings(target, packageRoot, events));
+  const repairedErrors = validateContractBootstrapRepairLedger(events, errors, options);
+  return { valid: repairedErrors.length === 0, events, errors: repairedErrors };
+}
+
+function validateContractBootstrapRepairLedger(events, errors, options) {
+  const allowUnmigrated = options?.allowUnmigratedLegacyContractBootstrapRepairMarkers === true;
+  validateContractBootstrapRepairMigrations(events, errors, {
+    allowUnmigratedLegacyContractBootstrapRepairMarkers: allowUnmigrated,
+  });
+  return repairMarkerErrors(events, errors, {
+    allowUnmigratedLegacyContractBootstrapRepairMarkers: allowUnmigrated,
+  });
 }
 
 export function validateStateLedgerCoherence(state, events) {
-  const errors = [];
+  const errors = [
+    ...validateCheckpointRevalidationCurrentBinding(state, events),
+    ...validateContractRevisionCurrentBinding(state, events),
+  ];
   if (!Number.isInteger(state.verificationCycle)) return errors;
   const taskEvents = events.filter((event) => event.taskId === state.taskId);
   const observed = new Set(taskEvents.map((event) => event.event));

package/src/core/evidence-readiness.js

@@ -164,6 +164,15 @@ export function terminalRequirements(requirements = []) {
   return normalizeRequirements(requirements).filter((requirement) => requirement.terminalOwned);
 }
 
+export function terminalRequirementsForContract(contractValue = {}, { additionalEvidence = [] } = {}) {
+  const pool = [
+    ...(contractValue.verification ?? []),
+    ...(contractValue.successCriteria ?? []),
+    ...additionalEvidence,
+  ];
+  return terminalRequirements(pool);
+}
+
 export function lifecycleRequirements(requirements = []) {
   return normalizeRequirements(requirements).filter((requirement) => requirement.type === "LIFECYCLE");
 }

package/src/core/execution-prerequisites.js

@@ -6,6 +6,7 @@ import { readPersistedRoute } from "./route-artifact.js";
 import { stateIdentityErrors } from "./completion-relationships.js";
 import { classifyLoadedWorkState } from "./work-state.js";
 import { taskArtifactPath } from "./task-paths.js";
+import { hasCurrentGateEvidence } from "./gate-provenance.js";
 
 const START_EXECUTION_EVENTS = Object.freeze([
   "CONTRACT_VALIDATED",
@@ -129,6 +130,19 @@ function prerequisiteLedgerErrors(ledger, taskId, preflight, route) {
       [ARTIFACT_PATHS.events, ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.route],
     ));
   }
+  const latestContractRevisionSeq = currentEvents.findLast((event) => event.event === "CONTRACT_REVISED")?.seq ?? 0;
+  const currentEpochSatisfiedGates = new Set(preflight.requiredGates.filter((gate) => (
+    hasCurrentGateEvidence(currentEvents, taskId, gate, latestContractRevisionSeq)
+  )));
+  for (const gate of preflight.requiredGates) {
+    if (!currentEpochSatisfiedGates.has(gate)) {
+      errors.push(issue(
+        "E_PHASE_CHRONOLOGY_INVALID",
+        `execution started before current-contract gate satisfaction: ${gate}`,
+        [ARTIFACT_PATHS.events, ARTIFACT_PATHS.preflight],
+      ));
+    }
+  }
   return errors;
 }
 

package/src/core/execution-profile.js

@@ -162,12 +162,63 @@ export function projectExecutionProfile(route) {
   return route.executionProfile?.resolved ?? LEGACY_EXECUTION_PROFILE;
 }
 
+function routeProfileSignals(normalizedRoute) {
+  const fullReasons = [];
+  const balancedReasons = [];
+  if (FULL_WORK_TYPES.has(normalizedRoute.workType)) fullReasons.push(`WORK_${normalizedRoute.workType.toUpperCase().replaceAll("-", "_")}`);
+  if (BALANCED_WORK_TYPES.has(normalizedRoute.workType)) balancedReasons.push(`WORK_${normalizedRoute.workType.toUpperCase().replaceAll("-", "_")}`);
+  for (const surface of normalizedRoute.surfaces) {
+    if (FULL_SURFACES.has(surface)) fullReasons.push(`SURFACE_${surface.toUpperCase().replaceAll("-", "_")}`);
+    else if (BALANCED_SURFACES.has(surface)) balancedReasons.push(`SURFACE_${surface.toUpperCase().replaceAll("-", "_")}`);
+  }
+  for (const risk of normalizedRoute.risks) {
+    if (FULL_RISKS.has(risk)) fullReasons.push(`RISK_${risk.toUpperCase().replaceAll("-", "_")}`);
+    else if (BALANCED_RISKS.has(risk)) balancedReasons.push(`RISK_${risk.toUpperCase().replaceAll("-", "_")}`);
+  }
+  if (normalizedRoute.behaviorChange) balancedReasons.push("WORK_BEHAVIOR_CHANGE");
+  if (normalizedRoute.executableChange) balancedReasons.push("WORK_EXECUTABLE_CHANGE");
+  return { fullReasons, balancedReasons };
+}
+
+function contractProfileSignals(textSignals, normalizedRoute) {
+  const fullReasons = [];
+  if (textSignals.secrets) fullReasons.push("RISK_SECRETS");
+  if (textSignals.personalData) fullReasons.push("RISK_PERSONAL_DATA");
+  if (textSignals.publication) fullReasons.push("RISK_PUBLICATION");
+  if (textSignals.destructive) fullReasons.push("RISK_DESTRUCTIVE");
+  if (textSignals.migration && normalizedRoute.surfaces.includes("database")) fullReasons.push("RISK_MIGRATION");
+  if (textSignals.payment) fullReasons.push("RISK_PAYMENT");
+  if (textSignals.externalMutation) fullReasons.push("RISK_EXTERNAL_MUTATION");
+  if (textSignals.authoritySensitiveExternalMutation) fullReasons.push("RISK_AUTHORITY_SENSITIVE_EXTERNAL_MUTATION");
+  if (textSignals.broadProductionValidation) fullReasons.push("RISK_PRODUCTION_VALIDATION");
+  return fullReasons;
+}
+
+function scopeProfileSignals(scope) {
+  const balancedReasons = [];
+  if (scope.multiDeliverable) balancedReasons.push("SCOPE_MULTI_DELIVERABLE");
+  if (scope.multiClaim) balancedReasons.push("SCOPE_MULTI_CLAIM");
+  if (scope.broad || scope.multiSurfaceExecutableChange) balancedReasons.push("SCOPE_BROAD");
+  return balancedReasons;
+}
+
+function profileSignals({ normalizedRoute, contract, taskDescriptor }) {
+  const route = routeProfileSignals(normalizedRoute);
+  const scope = scopeSignals({ routeInput: normalizedRoute, contract, taskDescriptor });
+  return {
+    fullReasons: [...route.fullReasons, ...contractProfileSignals(contractSignals(contract), normalizedRoute)],
+    balancedReasons: [...route.balancedReasons, ...scopeProfileSignals(scope)],
+    scope,
+  };
+}
+
 export function resolveExecutionProfile({
   routeInput = {},
   contract = null,
   taskDescriptor = null,
   configuredProfile = "auto",
   requestedProfile = null,
+  semanticRecommendation = null,
 } = {}) {
   const normalizedRoute = normalizedRouteInput(routeInput);
   const configured = normalizeRequestedProfile(configuredProfile, "configuredProfile");
@@ -181,43 +232,7 @@ export function resolveExecutionProfile({
   else reasons.push("PROFILE_DEFAULT_AUTO");
 
   let floor = "light";
-  const fullReasons = [];
-  const balancedReasons = [];
-  const addFull = (reason) => fullReasons.push(reason);
-  const addBalanced = (reason) => balancedReasons.push(reason);
-
-  if (FULL_WORK_TYPES.has(normalizedRoute.workType)) {
-    addFull(`WORK_${normalizedRoute.workType.toUpperCase().replaceAll("-", "_")}`);
-  }
-  if (BALANCED_WORK_TYPES.has(normalizedRoute.workType)) {
-    addBalanced(`WORK_${normalizedRoute.workType.toUpperCase().replaceAll("-", "_")}`);
-  }
-  for (const surface of normalizedRoute.surfaces) {
-    if (FULL_SURFACES.has(surface)) addFull(`SURFACE_${surface.toUpperCase().replaceAll("-", "_")}`);
-    else if (BALANCED_SURFACES.has(surface)) addBalanced(`SURFACE_${surface.toUpperCase().replaceAll("-", "_")}`);
-  }
-  for (const risk of normalizedRoute.risks) {
-    if (FULL_RISKS.has(risk)) addFull(`RISK_${risk.toUpperCase().replaceAll("-", "_")}`);
-    else if (BALANCED_RISKS.has(risk)) addBalanced(`RISK_${risk.toUpperCase().replaceAll("-", "_")}`);
-  }
-  if (normalizedRoute.behaviorChange) addBalanced("WORK_BEHAVIOR_CHANGE");
-  if (normalizedRoute.executableChange) addBalanced("WORK_EXECUTABLE_CHANGE");
-
-  const textSignals = contractSignals(contract);
-  if (textSignals.secrets) addFull("RISK_SECRETS");
-  if (textSignals.personalData) addFull("RISK_PERSONAL_DATA");
-  if (textSignals.publication) addFull("RISK_PUBLICATION");
-  if (textSignals.destructive) addFull("RISK_DESTRUCTIVE");
-  if (textSignals.migration && normalizedRoute.surfaces.includes("database")) addFull("RISK_MIGRATION");
-  if (textSignals.payment) addFull("RISK_PAYMENT");
-  if (textSignals.externalMutation) addFull("RISK_EXTERNAL_MUTATION");
-  if (textSignals.authoritySensitiveExternalMutation) addFull("RISK_AUTHORITY_SENSITIVE_EXTERNAL_MUTATION");
-  if (textSignals.broadProductionValidation) addFull("RISK_PRODUCTION_VALIDATION");
-
-  const scope = scopeSignals({ routeInput: normalizedRoute, contract, taskDescriptor });
-  if (scope.multiDeliverable) addBalanced("SCOPE_MULTI_DELIVERABLE");
-  if (scope.multiClaim) addBalanced("SCOPE_MULTI_CLAIM");
-  if (scope.broad || scope.multiSurfaceExecutableChange) addBalanced("SCOPE_BROAD");
+  const { fullReasons, balancedReasons, scope } = profileSignals({ normalizedRoute, contract, taskDescriptor });
 
   if (fullReasons.length > 0) {
     floor = "full";
@@ -247,7 +262,17 @@ export function resolveExecutionProfile({
   }
 
   const requestedRank = requested === "auto" ? PROFILE_RANK[floor] : PROFILE_RANK[requested];
-  const resolved = EXECUTION_PROFILES.find((profile) => PROFILE_RANK[profile] === Math.max(requestedRank, PROFILE_RANK[floor]));
+  let resolved = EXECUTION_PROFILES.find((profile) => PROFILE_RANK[profile] === Math.max(requestedRank, PROFILE_RANK[floor]));
+  const semanticProfile = typeof semanticRecommendation === "string"
+    ? semanticRecommendation
+    : semanticRecommendation?.executionProfile?.recommendedProfile
+      ?? semanticRecommendation?.recommendedProfile
+      ?? null;
+  if (["light", "balanced", "full"].includes(semanticProfile)
+    && PROFILE_RANK[semanticProfile] > PROFILE_RANK[resolved]) {
+    resolved = semanticProfile;
+    reasons.push("PROFILE_ESCALATED_BY_JEV");
+  }
   const escalated = requested !== "auto" && PROFILE_RANK[requested] < PROFILE_RANK[floor];
   if (escalated) reasons.push("PROFILE_ESCALATED_BY_SAFETY");
 

package/src/core/gate-provenance.js

@@ -0,0 +1,124 @@
+import { canonicalFingerprint } from "./artifacts.js";
+
+export const GATE_SATISFIED_EVENT = "GATE_SATISFIED";
+export const GATE_REVALIDATED_EVENT = "GATE_REVALIDATED";
+const CONTRACT_REVISED_EVENT = "CONTRACT_REVISED";
+const TRANSACTION_COMMITTED_EVENT = "TRANSACTION_COMMITTED";
+
+function eventHash(event) {
+  const { hash, ...body } = event ?? {};
+  return canonicalFingerprint(body);
+}
+
+export function assertGateSatisfiedDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)
+    || Object.keys(details).length !== 1
+    || typeof details.gate !== "string"
+    || details.gate.trim().length === 0) {
+    const error = new Error("GATE_SATISFIED requires exactly one non-empty gate detail");
+    error.code = "E_EVENT_INVALID";
+    throw error;
+  }
+  return details;
+}
+
+export function assertGateRevalidatedDetails(details) {
+  const keys = ["gate", "previousGateFingerprint", "gateFingerprint", "stalePaths"];
+  if (!details || typeof details !== "object" || Array.isArray(details)
+    || Object.keys(details).length !== keys.length
+    || keys.some((key) => !Object.prototype.hasOwnProperty.call(details, key))
+    || typeof details.gate !== "string"
+    || details.gate.trim().length === 0
+    || !/^[a-z0-9][a-z0-9-]*$/.test(details.gate)
+    || !/^[a-f0-9]{64}$/.test(details.previousGateFingerprint)
+    || !/^[a-f0-9]{64}$/.test(details.gateFingerprint)
+    || !Array.isArray(details.stalePaths)
+    || details.stalePaths.length === 0
+    || details.stalePaths.some((value) => typeof value !== "string" || value.trim().length === 0)
+    || [...details.stalePaths].sort().join("\0") !== details.stalePaths.join("\0")
+    || new Set(details.stalePaths).size !== details.stalePaths.length) {
+    const error = new Error("GATE_REVALIDATED requires a gate, two fingerprints, and sorted stale paths");
+    error.code = "E_GATE_REVALIDATION_INVALID";
+    throw error;
+  }
+  return details;
+}
+
+function gateIndex(events, gateEvent, eventName) {
+  return events.findIndex((event) => event === gateEvent
+    || (event?.seq === gateEvent?.seq
+      && event?.taskId === gateEvent?.taskId
+      && event?.event === eventName));
+}
+
+function isValidGateCommit(gateEvent, commitEvent, operation) {
+  return commitEvent?.event === TRANSACTION_COMMITTED_EVENT
+    && commitEvent.taskId === gateEvent.taskId
+    && commitEvent.seq === gateEvent.seq + 1
+    && commitEvent.previousHash === gateEvent.hash
+    && gateEvent.hash === eventHash(gateEvent)
+    && 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 === operation;
+}
+
+export function resolveGateRecordBoundary(events, gateEvent) {
+  if (!Array.isArray(events) || !gateEvent || gateEvent.event !== GATE_SATISFIED_EVENT) return null;
+  const index = gateIndex(events, gateEvent, GATE_SATISFIED_EVENT);
+  if (index < 0) return null;
+  const commitEvent = events[index + 1];
+  return isValidGateCommit(gateEvent, commitEvent, "gate-record")
+    ? { gateEvent, transactionCommitEvent: commitEvent }
+    : null;
+}
+
+export function resolveGateRevalidationBoundary(events, gateEvent) {
+  if (!Array.isArray(events) || !gateEvent || gateEvent.event !== GATE_REVALIDATED_EVENT) return null;
+  const index = gateIndex(events, gateEvent, GATE_REVALIDATED_EVENT);
+  if (index < 0) return null;
+  const commitEvent = events[index + 1];
+  return isValidGateCommit(gateEvent, commitEvent, "gate-revalidate")
+    ? { gateEvent, transactionCommitEvent: commitEvent }
+    : null;
+}
+
+export function hasCurrentGateEvidence(events, taskId, gate, latestContractRevisionSeq = 0) {
+  return events.some((event) => [GATE_SATISFIED_EVENT, GATE_REVALIDATED_EVENT].includes(event.event)
+    && event.taskId === taskId
+    && event.details?.gate === gate
+    && event.seq > latestContractRevisionSeq);
+}
+
+export function validateGateSatisfactionBindings(events = []) {
+  const errors = [];
+  for (const [index, event] of events.entries()) {
+    if (![GATE_SATISFIED_EVENT, GATE_REVALIDATED_EVENT].includes(event.event)) continue;
+    const revalidated = event.event === GATE_REVALIDATED_EVENT;
+    try {
+      if (revalidated) assertGateRevalidatedDetails(event.details);
+      else assertGateSatisfiedDetails(event.details);
+    } catch (error) {
+      errors.push({ code: error.code ?? "E_EVENT_INVALID", message: `event ${event.seq} (${event.event}): ${error.message}` });
+      continue;
+    }
+    const revisedBeforeGate = events.slice(0, index).findLast((candidate) => candidate.taskId === event.taskId
+      && candidate.event === CONTRACT_REVISED_EVENT);
+    const boundary = revalidated
+      ? resolveGateRevalidationBoundary(events, event)
+      : resolveGateRecordBoundary(events, event);
+    if ((revalidated || revisedBeforeGate) && !boundary) {
+      errors.push({
+        code: revalidated ? "E_GATE_REVALIDATION_INVALID" : "E_EVENT_INVALID",
+        message: revalidated
+          ? `event ${event.seq} must be immediately followed by its gate-revalidate transaction commit`
+          : `event ${event.seq} must be immediately followed by its gate-record transaction commit after contract revision`,
+      });
+    }
+  }
+  return errors;
+}