@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.2

package/src/core/task-lock.js

@@ -1,15 +1,21 @@
+import { needsExistingProjectScope, withExistingProjectScope } from "../storage/existing-project-scope.js";
 import { randomUUID } from "node:crypto";
-import { link, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
-import path from "node:path";
+import { readFile } from "node:fs/promises";
 import os from "node:os";
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
 import { taskLockPath } from "./task-paths.js";
-import {
-  E_PROJECT_CLAIMS_LOCK_INCONSISTENT,
-  E_TASK_LOCKED,
-} from "./error-codes.js";
+import { getOperationalStore } from "../storage/operational-context.js";
+import { assertStorageMaintenanceInactive } from "../storage/maintenance.js";
 
 export async function readLockInfo(target, taskId) {
+  if (await needsExistingProjectScope(target)) {
+    return withExistingProjectScope(target, () => readLockInfo(target, taskId), { readOnly: true });
+  }
+  const store = getOperationalStore(target);
+  if (store) {
+    const { readOperationalLease } = await import("../storage/leases.js");
+    return readOperationalLease(store, taskId);
+  }
   const relativePath = taskLockPath(taskId);
   await assertSafePath(target, relativePath);
   const fullPath = ensureWithin(target, relativePath);
@@ -50,13 +56,6 @@ export function isValidTaskLockIdentity(lock) {
     && hasLeaseIdentity(lock);
 }
 
-export function isValidProjectClaimsLockIdentity(lock) {
-  return Boolean(lock)
-    && !lock.corrupted
-    && lock.scope === "claims-reservation"
-    && hasLeaseIdentity(lock);
-}
-
 function classifyLeaseWindow(lock, now) {
   const heartbeat = Date.parse(lock.heartbeatAt ?? lock.acquiredAt);
   if (!Number.isFinite(heartbeat)) return { status: "UNKNOWN", stale: false };
@@ -81,191 +80,24 @@ export function currentProcessStartToken(now = Date.now(), uptimeSeconds = proce
   return `${process.pid}:${Math.max(0, Math.floor(now - (uptimeSeconds * 1000)))}`;
 }
 
-export const CLAIMS_LOCK_REL_PATH = ".forgeloop/.claims.lock";
-
-export async function readProjectClaimsLockInfo(target) {
-  await assertSafePath(target, CLAIMS_LOCK_REL_PATH);
-  const fullPath = ensureWithin(target, CLAIMS_LOCK_REL_PATH);
-
-  if (!(await fileExists(fullPath))) {
-    return null;
-  }
-
-  try {
-    const raw = await readFile(fullPath, "utf8");
-    return JSON.parse(raw);
-  } catch {
-    return { corrupted: true };
-  }
-}
-
-export function classifyProjectClaimsLock(lock, now = Date.now()) {
-  if (!lock) return { status: "NONE", stale: false };
-  if (lock.corrupted) return { status: "CORRUPT", stale: false };
-  if (!isValidProjectClaimsLockIdentity(lock)) return { status: "UNKNOWN", stale: false };
-  return classifyLeaseWindow(lock, now);
-}
-
-function projectClaimsLockError(classification, lockInfo, reason = null) {
-  if (classification.status === "LIVE") {
-    const error = new Error(
-      `Project write claims reservation is locked by operation "${lockInfo?.operation ?? "unknown"}" (pid: ${lockInfo?.pid ?? "unknown"}, acquired: ${lockInfo?.acquiredAt ?? "unknown"}).`,
-    );
-    error.code = E_TASK_LOCKED;
-    error.lockInfo = lockInfo;
-    error.classification = classification;
-    return error;
-  }
-  const error = new Error(
-    `Project write claims lock ownership is ${classification.status}${reason ? ` (${reason})` : ""}; refusing unsafe claim mutation`,
-  );
-  error.code = E_PROJECT_CLAIMS_LOCK_INCONSISTENT;
-  error.lockInfo = lockInfo;
-  error.classification = classification;
-  if (reason) error.reason = reason;
-  return error;
-}
-
-export async function releaseStaleProjectClaimsLockIfUnchanged(target, expectedLock, { now = Date.now() } = {}) {
-  await assertSafePath(target, CLAIMS_LOCK_REL_PATH);
-  const fullPath = ensureWithin(target, CLAIMS_LOCK_REL_PATH);
-  const expectedClassification = classifyProjectClaimsLock(expectedLock, now);
-  if (expectedClassification.status !== "STALE") {
-    return { released: false, reason: "EXPECTED_LOCK_NOT_STALE", classification: expectedClassification };
-  }
-
-  const quarantinePath = `${fullPath}.releasing-${randomUUID()}`;
-  try {
-    await rename(fullPath, quarantinePath);
-  } catch (error) {
-    if (error.code === "ENOENT") return { released: false, reason: "LOCK_MISSING" };
-    throw error;
-  }
-
-  let observed;
-  try {
-    observed = JSON.parse(await readFile(quarantinePath, "utf8"));
-  } catch {
-    await restoreQuarantinedLock(quarantinePath, fullPath);
-    return { released: false, reason: "LOCK_CORRUPT", classification: { status: "CORRUPT", stale: false } };
-  }
-
-  const observedClassification = classifyProjectClaimsLock(observed, now);
-  if (!sameObservedLock(observed, expectedLock, { identityIsValid: isValidProjectClaimsLockIdentity })
-    || observedClassification.status !== "STALE") {
-    await restoreQuarantinedLock(quarantinePath, fullPath);
-    return {
-      released: false,
-      reason: sameObservedLock(observed, expectedLock, { identityIsValid: isValidProjectClaimsLockIdentity })
-        ? "LOCK_NOT_STALE"
-        : "LOCK_CHANGED",
-      currentLock: observed,
-      classification: observedClassification,
-    };
-  }
-
-  await unlink(quarantinePath);
-  return { released: true, previousLock: observed, classification: observedClassification };
-}
-
-export async function acquireProjectClaimsLock(target, operation = "claim-reservation") {
-  await assertSafePath(target, CLAIMS_LOCK_REL_PATH);
-  const fullPath = ensureWithin(target, CLAIMS_LOCK_REL_PATH);
-
-  await mkdir(path.dirname(fullPath), { recursive: true });
-
-  const acquiredAt = new Date().toISOString();
-  const lockData = {
-    lockId: randomUUID(),
-    scope: "claims-reservation",
-    operation,
-    pid: process.pid,
-    hostname: os.hostname(),
-    processStartToken: currentProcessStartToken(),
-    ownerInstanceId: randomUUID(),
-    acquiredAt,
-    heartbeatAt: acquiredAt,
-    leaseMs: 300000,
-  };
-
-  let fileHandle = null;
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    try {
-      fileHandle = await open(fullPath, "wx");
-      break;
-    } catch (error) {
-      if (error.code !== "EEXIST") throw error;
-      const existing = await readProjectClaimsLockInfo(target);
-      const classification = classifyProjectClaimsLock(existing);
-      if (classification.status === "STALE" && attempt === 0) {
-        const released = await releaseStaleProjectClaimsLockIfUnchanged(target, existing);
-        if (released.released || released.reason === "LOCK_MISSING") continue;
-        throw projectClaimsLockError(
-          released.classification ?? { status: "UNKNOWN", stale: false },
-          released.currentLock ?? existing,
-          released.reason,
-        );
-      }
-      throw projectClaimsLockError(classification, existing);
-    }
-  }
-  if (!fileHandle) {
-    throw projectClaimsLockError({ status: "UNKNOWN", stale: false }, null, "ACQUISITION_RETRY_EXHAUSTED");
-  }
-
-  try {
-    await fileHandle.writeFile(`${JSON.stringify(lockData, null, 2)}\n`, "utf8");
-    await fileHandle.close();
-    return {
-      lockData,
-      release: async () => {
-        try {
-          const current = await readProjectClaimsLockInfo(target);
-          if (current && current.lockId === lockData.lockId) {
-            await unlink(fullPath);
-          }
-        } catch {
-          // ignore
-        }
-      },
-    };
-  } catch (error) {
-    try {
-      await fileHandle.close();
-    } catch {
-      // ignore
-    }
-    try {
-      await unlink(fullPath);
-    } catch {
-      // ignore
-    }
-    throw error;
-  }
-}
-
 export async function withProjectClaimsLock(target, operationOrCallback, callback) {
+  if (!getOperationalStore(target)) {
+    const { withProjectStorage } = await import("../storage/project-boundary.js");
+    return withProjectStorage(target, () => withProjectClaimsLock(target, operationOrCallback, callback));
+  }
   let operation = operationOrCallback;
   let fn = callback;
   if (typeof operationOrCallback === "function" && callback === undefined) {
     fn = operationOrCallback;
     operation = "claim-reservation";
   }
-  const lock = await acquireProjectClaimsLock(target, operation);
-  try {
-    return await fn(lock.lockData);
-  } finally {
-    await lock.release();
-  }
+  // The preparation scope records the authoritative claim inputs; its short
+  // BEGIN IMMEDIATE commit rechecks those inputs and reserves claims atomically.
+  return fn({ kind: "sqlite-claim-reservation", operation });
 }
 
 export async function acquireTaskLock(target, taskId, operation = "mutation") {
-  const relativePath = taskLockPath(taskId);
-  await assertSafePath(target, relativePath);
-  const fullPath = ensureWithin(target, relativePath);
-
-  await mkdir(path.dirname(fullPath), { recursive: true });
-
+  await assertStorageMaintenanceInactive(target);
   const acquiredAt = new Date().toISOString();
   const lockData = {
     lockId: randomUUID(),
@@ -279,80 +111,46 @@ export async function acquireTaskLock(target, taskId, operation = "mutation") {
     heartbeatAt: acquiredAt,
     leaseMs: 300000,
   };
-
-  let fileHandle;
-  try {
-    fileHandle = await open(fullPath, "wx");
-  } catch (error) {
-    if (error.code === "EEXIST") {
-      const existing = await readLockInfo(target, taskId);
-      const err = new Error(
-        `Task "${taskId}" is locked by operation "${existing?.operation ?? "unknown"}" (pid: ${existing?.pid ?? "unknown"}, acquired: ${existing?.acquiredAt ?? "unknown"}). Use 'forgeloop task-unlock --task ${taskId} --force' if the process died.`,
-      );
-      err.code = E_TASK_LOCKED;
-      err.lockInfo = existing;
-      err.taskId = taskId;
-      throw err;
-    }
-    throw error;
-  }
-
-  try {
-    await fileHandle.writeFile(`${JSON.stringify(lockData, null, 2)}\n`, "utf8");
-    await fileHandle.close();
-    return {
-      lockData,
-      release: async () => {
-        try {
-          const current = await readLockInfo(target, taskId);
-          if (current && current.lockId === lockData.lockId) {
-            await unlink(fullPath);
-          }
-        } catch {
-          // ignore already unlinked or overwritten
-        }
-      },
-    };
-  } catch (error) {
-    try {
-      await fileHandle.close();
-    } catch {
-      // ignore
-    }
-    try {
-      await unlink(fullPath);
-    } catch {
-      // ignore
-    }
-    throw error;
-  }
+  const store = getOperationalStore(target);
+  if (store) {
+    const { acquireOperationalLease } = await import("../storage/leases.js");
+    return acquireOperationalLease(store, taskId, lockData);
+  }
+  return acquireStandaloneOperationalLease(target, taskId, operation);
+}
+
+/** Keep only the connection scope alive; acquisition/release hold no SQL transaction. */
+async function acquireStandaloneOperationalLease(target, taskId, operation) {
+  let resolveReady;
+  let rejectReady;
+  let releaseScope;
+  const ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+  const released = new Promise(resolve => { releaseScope = resolve; });
+  const { withProjectStorage } = await import("../storage/project-boundary.js");
+  const completion = withProjectStorage(target, async () => {
+    const handle = await acquireTaskLock(target, taskId, operation);
+    resolveReady(handle.lockData);
+    await released;
+    return handle.release();
+  }, { existingOnly: true });
+  completion.catch(rejectReady);
+  const lockData = await ready;
+  return { lockData, release: () => { releaseScope(); return completion; } };
 }
 
 export async function forceUnlockTask(target, taskId, { staleOnly = false } = {}) {
-  const relativePath = taskLockPath(taskId);
-  await assertSafePath(target, relativePath);
-  const fullPath = ensureWithin(target, relativePath);
-
-  if (!(await fileExists(fullPath))) {
-    return { unlocked: false, message: "No active lock found" };
+  if (!getOperationalStore(target)) {
+    const { withProjectStorage } = await import("../storage/project-boundary.js");
+    return withProjectStorage(target, () => forceUnlockTask(target, taskId, { staleOnly }), { existingOnly: true });
   }
-
+  const store = getOperationalStore(target);
   const existing = await readLockInfo(target, taskId);
+  if (!existing) return { unlocked: false, message: "No active lock found" };
   const classification = classifyLockStaleness(existing);
-  if (staleOnly) {
-    if (!classification.stale) {
-      return { unlocked: false, previousLock: existing, classification };
-    }
-    const released = await releaseStaleTaskLockIfUnchanged(target, taskId, existing);
-    return {
-      unlocked: released.released,
-      previousLock: released.previousLock ?? existing,
-      classification: released.classification ?? classification,
-      ...(released.reason ? { reason: released.reason } : {}),
-    };
-  }
-  await unlink(fullPath);
-  return { unlocked: true, previousLock: existing, classification };
+  if (staleOnly && !classification.stale) return { unlocked: false, previousLock: existing, classification };
+  const { releaseOperationalLeaseIfUnchanged } = await import("../storage/leases.js");
+  const released = releaseOperationalLeaseIfUnchanged(store, taskId, existing, { force: !staleOnly, classify: classifyLockStaleness, sameIdentity: sameObservedTaskLock });
+  return { unlocked: released.released, previousLock: released.previousLock ?? existing, classification: released.classification ?? classification, ...(released.reason ? { reason: released.reason } : {}) };
 }
 
 function sameObservedLock(left, right, { identityIsValid = isValidTaskLockIdentity } = {}) {
@@ -369,61 +167,23 @@ function sameObservedTaskLock(left, right, taskId) {
     && right.taskId === taskId;
 }
 
-async function restoreQuarantinedLock(quarantinePath, fullPath) {
-  try {
-    await link(quarantinePath, fullPath);
-  } catch (error) {
-    if (error.code !== "EEXIST") throw error;
-  } finally {
-    try {
-      await unlink(quarantinePath);
-    } catch {
-      // ignore an already-consumed quarantine entry
-    }
-  }
-}
-
 export async function releaseStaleTaskLockIfUnchanged(target, taskId, expectedLock, { now = Date.now() } = {}) {
-  const relativePath = taskLockPath(taskId);
-  await assertSafePath(target, relativePath);
-  const fullPath = ensureWithin(target, relativePath);
-  const expectedClassification = classifyLockStaleness(expectedLock, now);
-  if (expectedClassification.status !== "STALE") {
-    return { released: false, reason: "EXPECTED_LOCK_NOT_STALE", classification: expectedClassification };
-  }
-
-  const quarantinePath = `${fullPath}.releasing-${randomUUID()}`;
-  try {
-    await rename(fullPath, quarantinePath);
-  } catch (error) {
-    if (error.code === "ENOENT") return { released: false, reason: "LOCK_MISSING" };
-    throw error;
+  if (!getOperationalStore(target)) {
+    const { withProjectStorage } = await import("../storage/project-boundary.js");
+    return withProjectStorage(target, () => releaseStaleTaskLockIfUnchanged(target, taskId, expectedLock, { now }), { existingOnly: true });
   }
-
-  let observed;
-  try {
-    observed = JSON.parse(await readFile(quarantinePath, "utf8"));
-  } catch {
-    await restoreQuarantinedLock(quarantinePath, fullPath);
-    return { released: false, reason: "LOCK_CORRUPT" };
-  }
-
-  const observedClassification = classifyLockStaleness(observed, now);
-  if (!sameObservedTaskLock(observed, expectedLock, taskId) || observedClassification.status !== "STALE") {
-    await restoreQuarantinedLock(quarantinePath, fullPath);
-    return {
-      released: false,
-      reason: sameObservedTaskLock(observed, expectedLock, taskId) ? "LOCK_NOT_STALE" : "LOCK_CHANGED",
-      currentLock: observed,
-      classification: observedClassification,
-    };
-  }
-
-  await unlink(quarantinePath);
-  return { released: true, previousLock: observed, classification: observedClassification };
+  const store = getOperationalStore(target);
+  const expectedClassification = classifyLockStaleness(expectedLock, now);
+  if (expectedClassification.status !== "STALE") return { released: false, reason: "EXPECTED_LOCK_NOT_STALE", classification: expectedClassification };
+  const { releaseOperationalLeaseIfUnchanged } = await import("../storage/leases.js");
+  return releaseOperationalLeaseIfUnchanged(store, taskId, expectedLock, { now, classify: classifyLockStaleness, sameIdentity: sameObservedTaskLock });
 }
 
 export async function withTaskLock(target, taskId, operationOrCallback, callback) {
+  if (!getOperationalStore(target)) {
+    const { withProjectStorage } = await import("../storage/project-boundary.js");
+    return withProjectStorage(target, () => withTaskLock(target, taskId, operationOrCallback, callback));
+  }
   let operation = operationOrCallback;
   let fn = callback;
   if (typeof operationOrCallback === "function" && callback === undefined) {

package/src/core/task-migration-validation.js

@@ -2,8 +2,8 @@ import { createHash } from "node:crypto";
 import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import { ensureWithin, fileExists } from "./filesystem.js";
-import { readJsonArtifact } from "./artifacts.js";
-import { validateEventLedger } from "./events.js";
+import { readPortableJsonArtifact } from "./artifacts.js";
+import { validatePortableEventLedger } from "./events.js";
 import {
   E_TASK_MIGRATION_IDENTITY_MISMATCH,
   E_TASK_MIGRATION_INVALID,
@@ -42,7 +42,7 @@ export async function validateMigrationSnapshot(target, { taskId, packageRoot, p
       const absPath = ensureWithin(target, relPath);
       if (await fileExists(absPath)) {
         try {
-          const { value } = await readJsonArtifact(target, relPath, schemaName, packageRoot);
+          const { value } = await readPortableJsonArtifact(target, relPath, schemaName, packageRoot);
           checkIdentity(value, relPath);
           artifactFingerprints[key] = await fingerprintFile(absPath);
         } catch (err) {
@@ -59,7 +59,7 @@ export async function validateMigrationSnapshot(target, { taskId, packageRoot, p
   if (paths.events) {
     const absPath = ensureWithin(target, paths.events);
     if (await fileExists(absPath)) {
-      const ledger = await validateEventLedger(target, packageRoot, { eventsPath: paths.events });
+      const ledger = await validatePortableEventLedger(target, packageRoot, { eventsPath: paths.events });
       if (!ledger.valid) {
         const error = new Error(`Event ledger validation failed for ${paths.events}: ${ledger.errors?.[0]?.message ?? "invalid ledger"}`);
         error.code = E_TASK_MIGRATION_INVALID;
@@ -103,7 +103,7 @@ export async function validateMigrationSnapshot(target, { taskId, packageRoot, p
       const fileAbsPath = path.join(absPath, entry.name);
 
       try {
-        const { value } = await readJsonArtifact(target, fileRelPath, schemaName, packageRoot);
+        const { value } = await readPortableJsonArtifact(target, fileRelPath, schemaName, packageRoot);
         checkIdentity(value, fileRelPath);
         const hash = await fingerprintFile(fileAbsPath);
         fileHashes.push({ relPath: entry.name, hash });