@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/task-recovery.js

@@ -0,0 +1,205 @@
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { LEGACY_RECOVERY_MIGRATION_EVENT } from "./task-recovery-migration.js";
+import { readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import {
+  E_TASK_RECOVERY_AUTHORITY_INVALID,
+} from "./error-codes.js";
+import { taskArtifactPath } from "./task-paths.js";
+import { getActiveTaskTransaction } from "./transaction.js";
+import { classifyRecoveryHistory } from "./recovery-history.js";
+
+export const TASK_RECOVERY_SCHEMA_VERSION = 1;
+export const TASK_RECOVERY_EVENT_TYPES = Object.freeze(new Set([
+  "TASK_RECOVERY_RECORDED",
+  "OPERATOR_RECOVERY_RECORDED",
+  LEGACY_RECOVERY_MIGRATION_EVENT,
+]));
+
+export function createTaskRecovery({
+  taskId,
+  recoveredAt,
+  recoveryId,
+  recoveryEventSeq,
+  classificationAtRecovery,
+  reasonCodes,
+  releasedClaims,
+  previousPhase,
+  previousRevision,
+  repositoryFingerprint,
+  authority,
+}) {
+  const recovery = {
+    schemaVersion: TASK_RECOVERY_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId,
+    status: "RECOVERED",
+    recoveredAt,
+    recoveryId,
+    recoveryEventSeq,
+    classificationAtRecovery,
+    reasonCodes: [...reasonCodes],
+    releasedClaims: [...releasedClaims],
+    previousPhase,
+    previousRevision,
+    repositoryFingerprint: { ...repositoryFingerprint },
+    authority: { ...authority },
+  };
+  assertTaskRecoveryAuthority(recovery);
+  return recovery;
+}
+
+export function assertTaskRecoveryAuthority(recovery) {
+  const authority = recovery?.authority;
+  const validCaller = authority?.kind === "CALLER_ACKNOWLEDGED" && authority.grantRef === undefined;
+  const validHost = authority?.kind === "HOST_ATTESTED"
+    && typeof authority.grantRef === "string"
+    && authority.grantRef.trim() !== "";
+  if (validCaller || validHost) return recovery;
+  const error = new Error(
+    "Recovery authority must be caller acknowledgement or host attestation with a trusted grant reference",
+  );
+  error.code = E_TASK_RECOVERY_AUTHORITY_INVALID;
+  throw error;
+}
+
+export async function readTaskRecovery(target, { taskId, packageRoot } = {}) {
+  try {
+    const artifact = await readJsonArtifact(target, taskArtifactPath(taskId, "recovery"), "task-recovery", packageRoot);
+    assertTaskRecoveryAuthority(artifact.value);
+    return artifact;
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") return null;
+    throw error;
+  }
+}
+
+export function writeTaskRecovery(target, recovery, packageRoot) {
+  assertTaskRecoveryAuthority(recovery);
+  return writeJsonArtifact(
+    target,
+    taskArtifactPath(recovery.taskId, "recovery"),
+    recovery,
+    "task-recovery",
+    packageRoot,
+    { taskId: recovery.taskId, operation: "write-task-recovery" },
+  );
+}
+
+export async function clearTaskRecovery(target, { taskId } = {}) {
+  const transaction = getActiveTaskTransaction();
+  if (!transaction) {
+    throw new Error("clearTaskRecovery requires an active task transaction");
+  }
+  await transaction.stageDelete(taskArtifactPath(taskId, "recovery"));
+}
+
+export function isTaskRecovered(recovery) {
+  return recovery?.status === "RECOVERED";
+}
+
+export async function assertTaskNotRecovered(target, { taskId, packageRoot } = {}) {
+  const { assertTaskMutationAllowed } = await import("./task-claim-state.js");
+  return assertTaskMutationAllowed(target, { taskId, packageRoot });
+}
+
+export function effectiveTaskClaims({
+  validatedClaimState = null,
+  historicalWriteClaims = null,
+  writeClaims = [],
+} = {}) {
+  const historical = historicalWriteClaims ?? writeClaims;
+  // Only VALIDATED canonical ownership may release claims. A bare
+  // `phase === "COMPLETE"` never proves completion ownership.
+  const validatedRelease = validatedClaimState?.valid === true
+    && ["RELEASED_BY_COMPLETION", "RELEASED_BY_RECOVERY"].includes(validatedClaimState.claimState);
+  return validatedRelease ? [] : [...historical];
+}
+
+export function taskClaimProjection({
+  validatedClaimState = null,
+  historicalWriteClaims: suppliedHistoricalClaims = null,
+  writeClaims = [],
+} = {}) {
+  const historicalWriteClaims = [...(suppliedHistoricalClaims ?? writeClaims)];
+  const effectiveWriteClaims = effectiveTaskClaims({
+    validatedClaimState,
+    historicalWriteClaims,
+  });
+  const claimState = validatedClaimState?.valid === true
+    ? validatedClaimState.claimState
+    : "ACTIVE";
+  return {
+    writeClaims: effectiveWriteClaims,
+    historicalWriteClaims,
+    effectiveWriteClaims,
+    claimState,
+    mutationAllowed: claimState === "ACTIVE",
+  };
+}
+
+function sameList(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && left.every((value, index) => value === right[index]);
+}
+
+function recoveryConsistencyError(message) {
+  return { code: "E_TASK_RECOVERY_INCONSISTENT", message };
+}
+
+export function validateTaskRecoveryConsistency({
+  taskId,
+  recovery = null,
+  events = [],
+  historicalWriteClaims = null,
+  recoveryHistory = null,
+} = {}) {
+  const history = recoveryHistory ?? classifyRecoveryHistory(events);
+  const errors = [...history.errors];
+
+  if (!recovery) {
+    if (history.valid && history.activeRecovery) {
+      errors.push(recoveryConsistencyError(
+        `Recovery event ${history.activeRecovery.recoveryId} has neither an active recovery artifact nor a resume event`,
+      ));
+    }
+    return errors;
+  }
+  if (!history.activeRecovery || history.activeRecovery.recoveryId !== recovery.recoveryId) {
+    errors.push(recoveryConsistencyError(
+      `Recovery artifact ${recovery.recoveryId ?? "unknown"} does not match the active recovery history`,
+    ));
+  }
+  if (recovery.taskId !== taskId) {
+    errors.push(recoveryConsistencyError(`Recovery artifact belongs to ${recovery.taskId}, not ${taskId}`));
+  }
+  const event = events.find((candidate) => candidate.seq === recovery.recoveryEventSeq);
+  if (!event || !TASK_RECOVERY_EVENT_TYPES.has(event.event)) {
+    errors.push(recoveryConsistencyError(
+      `Recovery artifact references missing recovery event seq ${recovery.recoveryEventSeq}`,
+    ));
+    return errors;
+  }
+
+  const comparisons = [
+    [event.taskId === recovery.taskId, "taskId"],
+    [event.at === recovery.recoveredAt, "recoveredAt"],
+    [event.details?.recoveryId === recovery.recoveryId, "recoveryId"],
+    [event.details?.classification === recovery.classificationAtRecovery, "classificationAtRecovery"],
+    [sameList(event.details?.reasonCodes, recovery.reasonCodes), "reasonCodes"],
+    [sameList(event.details?.releasedClaims, recovery.releasedClaims), "releasedClaims"],
+    [event.details?.previousPhase === recovery.previousPhase, "previousPhase"],
+    [event.details?.previousRevision === recovery.previousRevision, "previousRevision"],
+    [event.details?.currentBranch === recovery.repositoryFingerprint?.branch, "repositoryFingerprint.branch"],
+    [event.details?.currentHead === recovery.repositoryFingerprint?.head, "repositoryFingerprint.head"],
+    [event.details?.authorityKind === recovery.authority?.kind, "authority.kind"],
+  ];
+  for (const [matches, field] of comparisons) {
+    if (!matches) errors.push(recoveryConsistencyError(`Recovery artifact and ledger disagree on ${field}`));
+  }
+  if (historicalWriteClaims && !sameList(historicalWriteClaims, recovery.releasedClaims)) {
+    errors.push(recoveryConsistencyError("Recovery releasedClaims do not match the task descriptor's historical claims"));
+  }
+  return errors;
+}

package/src/core/task-scope.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import {
   E_TASK_CHANGE_OUTSIDE_SCOPE,
+  E_TASK_CLAIM_OWNERSHIP_INCONSISTENT,
   E_TASK_DESCRIPTOR_INVALID,
   E_TASK_SCOPE_CONFLICT,
   E_TASK_SCOPE_DIRTY,
@@ -93,7 +94,9 @@ export function checkScopeConflicts(newClaims, existingTasks = [], currentTaskId
     // Only non-COMPLETE tasks hold active write claims
     if (task.phase === "COMPLETE") continue;
 
-    const taskClaims = normalizeWriteClaims(task.writeClaims ?? task.descriptor?.writeClaims ?? []);
+    const taskClaims = normalizeWriteClaims(task.claimState === undefined
+      ? (task.writeClaims ?? task.descriptor?.writeClaims ?? [])
+      : (task.effectiveWriteClaims ?? []));
     for (const newClaim of normalizedNew) {
       for (const existingClaim of taskClaims) {
         if (claimsOverlap(newClaim, existingClaim)) {
@@ -112,6 +115,35 @@ export function checkScopeConflicts(newClaims, existingTasks = [], currentTaskId
 }
 
 export function assertNoScopeConflicts(newClaims, existingTasks = [], currentTaskId = null) {
+  const normalizedNew = normalizeWriteClaims(newClaims);
+  if (normalizedNew.length > 0) {
+    const ownershipBlockers = existingTasks.filter((task) => {
+      if (task.taskId === currentTaskId) return false;
+      if (task.healthy === false) return true;
+      if (task.claimState !== "INCONSISTENT" && task.ownershipValid !== false) return false;
+      const retainedClaims = normalizeWriteClaims(
+        task.effectiveWriteClaims ?? task.writeClaims ?? task.descriptor?.writeClaims ?? [],
+      );
+      return retainedClaims.length === 0
+        || normalizedNew.some((claim) => retainedClaims.some((retained) => claimsOverlap(claim, retained)));
+    });
+    if (ownershipBlockers.length > 0) {
+      const error = new Error(
+        `Cannot acquire write claims while task ownership is inconsistent: ${ownershipBlockers
+          .map((task) => task.taskId ?? task.taskKey)
+          .join(", ")}`,
+      );
+      error.code = E_TASK_CLAIM_OWNERSHIP_INCONSISTENT;
+      error.tasks = ownershipBlockers.map((task) => ({
+        taskId: task.taskId ?? null,
+        taskKey: task.taskKey ?? null,
+        claimState: task.claimState ?? "INCONSISTENT",
+        reasonCodes: task.reasonCodes ?? [task.error?.code].filter(Boolean),
+      }));
+      throw error;
+    }
+  }
+
   const conflicts = checkScopeConflicts(newClaims, existingTasks, currentTaskId);
   if (conflicts.length > 0) {
     const first = conflicts[0];

package/src/core/task-snapshot.js

@@ -0,0 +1,53 @@
+import { readEvents, validateEventLedger } from "./events.js";
+import { readWorkState } from "./work-state.js";
+import { canonicalFingerprint } from "./artifacts.js";
+
+function ledgerTail(events) {
+  const last = events.at(-1) ?? null;
+  return {
+    sequence: last?.seq ?? 0,
+    hash: last?.hash ?? null,
+  };
+}
+
+export async function buildTaskSnapshot({
+  target,
+  packageRoot,
+  taskId = null,
+  eventsPath = null,
+  stateFile = null,
+} = {}) {
+  const options = { packageRoot, taskId, ...(eventsPath ? { eventsPath } : {}) };
+  const state = await readWorkState(target, { ...options, ...(stateFile ? { statePath: stateFile } : {}) });
+  const events = await readEvents(target, packageRoot, options);
+  const before = {
+    stateRevision: state?.revision ?? null,
+    ...ledgerTail(events),
+  };
+
+  const validation = await validateEventLedger(target, packageRoot, options);
+
+  const rereadState = await readWorkState(target, { ...options, ...(stateFile ? { statePath: stateFile } : {}) });
+  const rereadEvents = await readEvents(target, packageRoot, options);
+  const after = {
+    stateRevision: rereadState?.revision ?? null,
+    ...ledgerTail(rereadEvents),
+  };
+
+  const consistent = JSON.stringify(before) === JSON.stringify(after);
+
+  return {
+    consistent,
+    taskId: taskId ?? state?.taskId ?? rereadState?.taskId ?? null,
+    anchors: before,
+    capturedAt: new Date().toISOString(),
+    integrity: {
+      valid: validation.valid,
+      errors: validation.errors,
+      eventCount: validation.events.length,
+      fingerprint: canonicalFingerprint(validation.events.map(({ seq, event, at }) => ({ seq, event, at }))),
+    },
+    state: rereadState,
+    events: validation.events,
+  };
+}

package/src/core/templates.js

@@ -66,6 +66,15 @@ export const TEMPLATE_PATHS = [
   "schemas/task-bundle.schema.json",
   "schemas/authority.schema.json",
   "schemas/task-descriptor.schema.json",
+  "schemas/task-recovery.schema.json",
+  "schemas/diagnostic-case.schema.json",
+  "schemas/intervention.schema.json",
+  "schemas/hypothesis-disposition.schema.json",
+  "schemas/action.schema.json",
+  "schemas/approval.schema.json",
+  "schemas/capability-policy.schema.json",
+  "schemas/trajectory-evaluation.schema.json",
+  "schemas/trajectory-scenario.schema.json",
 ];
 
 export function getPackageRoot() {