@cassiomc1/forgeloop 1.3.0 → 1.5.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/templates.js

@@ -66,6 +66,7 @@ export const TEMPLATE_PATHS = [
   "schemas/task-bundle.schema.json",
   "schemas/authority.schema.json",
   "schemas/task-descriptor.schema.json",
+  "schemas/task-recovery.schema.json",
 ];
 
 export function getPackageRoot() {

package/src/core/transaction.js

@@ -118,6 +118,9 @@ export async function withTaskTransaction({
       lock,
       async readText(relativePath) {
         await assertSafePath(target, relativePath);
+        if (manifest.writes.some((entry) => writePath(entry) === relativePath && entry.kind === "DELETE")) {
+          return null;
+        }
         const staged = ensureWithin(target, `${stageRoot}/${relativePath}`);
         if (await fileExists(staged)) return readFile(staged, "utf8");
         const appendStaged = ensureWithin(target, `${stageRoot}/${relativePath}.append`);
@@ -128,8 +131,9 @@ export async function withTaskTransaction({
       },
       async stageText(relativePath, text) {
         await assertSafePath(target, relativePath);
-        if (manifest.writes.some((entry) => writePath(entry) === relativePath && entry.kind === "APPEND")) {
-          throw new Error(`cannot replace append-staged path: ${relativePath}`);
+        const conflicting = manifest.writes.find((entry) => writePath(entry) === relativePath);
+        if (conflicting?.kind === "APPEND" || conflicting?.kind === "DELETE") {
+          throw new Error(`cannot replace ${conflicting.kind.toLowerCase()}-staged path: ${relativePath}`);
         }
         const staged = `${stageRoot}/${relativePath}`;
         await assertSafePath(target, staged);
@@ -162,6 +166,23 @@ export async function withTaskTransaction({
         }
         await writeManifest(target, manifestPath, manifest);
       },
+      async stageDelete(relativePath) {
+        await assertSafePath(target, relativePath);
+        if (manifest.writes.some((entry) => writePath(entry) === relativePath)) {
+          throw new Error(`cannot delete write-staged path: ${relativePath}`);
+        }
+        const destination = ensureWithin(target, relativePath);
+        if (!(await fileExists(destination))) {
+          throw new Error(`transaction delete target is missing: ${relativePath}`);
+        }
+        manifest.writes.push({
+          path: relativePath,
+          kind: "DELETE",
+          hadPrevious: false,
+          published: false,
+        });
+        await writeManifest(target, manifestPath, manifest);
+      },
     };
     try {
       const result = await transactionContext.run(tx, async () => {
@@ -221,6 +242,11 @@ export async function withTaskTransaction({
           entry.backupCreated = true;
         }
         await writeManifest(target, manifestPath, manifest);
+        if (entry.kind === "DELETE") {
+          entry.published = true;
+          await writeManifest(target, manifestPath, manifest);
+          continue;
+        }
         await rename(staged, destination);
         entry.published = true;
         await writeManifest(target, manifestPath, manifest);

package/src/integration.js

@@ -0,0 +1,47 @@
+import {
+  FORGELOOP_INTEGRATION_RUNTIME_VERSION,
+  executeForgeLoopCommand,
+} from "./core/command-runtime.js";
+import { validateForgeLoopCommandInput, defaultCommandInputValues } from "./core/command-input.js";
+import { CLI_COMMAND_DEFINITIONS } from "./core/cli-command-definitions.js";
+import {
+  INTEGRATION_RISK_CLASSES,
+  classifyForgeLoopInvocation,
+  getForgeLoopCapabilities,
+} from "./core/integration-invocation-policy.js";
+import { readForgeLoopIntegrationResource, INTEGRATION_RESOURCE_DEFINITIONS } from "./core/integration-resources.js";
+import { resolveForgeLoopProjectRoot } from "./core/project-root.js";
+import { INTEGRATION_LIMITS } from "./core/integration-limits.js";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Version of the installed @cassiomc1/forgeloop package providing this
+ * integration API (closing plan §14-16): lets external adapters report the
+ * real core version without hardcoding or deep-importing package internals.
+ */
+export function getForgeLoopPackageVersion() {
+  const packageJsonPath = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "package.json",
+  );
+  return JSON.parse(readFileSync(packageJsonPath, "utf8")).version;
+}
+
+export {
+  executeForgeLoopCommand,
+  validateForgeLoopCommandInput,
+  defaultCommandInputValues,
+  getForgeLoopCapabilities,
+  classifyForgeLoopInvocation,
+  readForgeLoopIntegrationResource,
+  resolveForgeLoopProjectRoot,
+  INTEGRATION_LIMITS,
+  INTEGRATION_RISK_CLASSES,
+  INTEGRATION_RESOURCE_DEFINITIONS,
+  CLI_COMMAND_DEFINITIONS,
+};
+
+export const FORGELOOP_INTEGRATION_API_VERSION = FORGELOOP_INTEGRATION_RUNTIME_VERSION;