@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.2

package/src/core/task-migration.js

@@ -1,16 +1,11 @@
-import { cp, mkdir, rename, rm } from "node:fs/promises";
-import path from "node:path";
-import { ensureWithin, fileExists, writeFileAtomic } from "./filesystem.js";
+import { ensureWithin, fileExists } from "./filesystem.js";
 import { getPackageRoot } from "./templates.js";
 import {
   LEGACY_TASK_ARTIFACT_PATHS,
-  TASK_STATE_ROOT,
-  taskArtifactPath,
   taskDirectory,
 } from "./task-paths.js";
 import { assertTaskId, taskStorageKey } from "./task-identity.js";
-import { createTaskDescriptor, readTaskDescriptor, writeTaskDescriptor } from "./task-descriptor.js";
-import { readJsonArtifact } from "./artifacts.js";
+import { readPortableJsonArtifact } from "./artifacts.js";
 import { validateMigrationSnapshot } from "./task-migration-validation.js";
 import {
   E_TASK_MIGRATION_IDENTITY_MISMATCH,
@@ -31,51 +26,11 @@ export async function detectLegacySingletonLayout(target) {
   };
 }
 
-async function removeLegacyArtifact(target, relativePath) {
-  const fullPath = ensureWithin(target, relativePath);
-  await rm(fullPath, { recursive: true, force: true });
-  if (await fileExists(fullPath)) {
-    const error = new Error(
-      `Legacy artifact still exists after migration cleanup: ${relativePath}`,
-    );
-    error.code = E_TASK_MIGRATION_INVALID;
-    throw error;
-  }
-}
-
-function assertMigrationSnapshotsEqual(source, destination, label) {
-  for (const [key, hash] of Object.entries(source.artifactFingerprints)) {
-    if (destination.artifactFingerprints[key] !== hash) {
-      const error = new Error(`Migration fingerprint mismatch in ${label}: ${key}`);
-      error.code = E_TASK_MIGRATION_INVALID;
-      throw error;
-    }
-  }
-
-  for (const [key, hash] of Object.entries(source.directoryFingerprints)) {
-    if (destination.directoryFingerprints[key] !== hash) {
-      const error = new Error(`Migration directory fingerprint mismatch in ${label}: ${key}`);
-      error.code = E_TASK_MIGRATION_INVALID;
-      throw error;
-    }
-  }
-
-  if (destination.eventCount !== source.eventCount) {
-    const error = new Error(`Migration event count mismatch in ${label}`);
-    error.code = E_TASK_MIGRATION_INVALID;
-    throw error;
-  }
-}
-
 export async function migrateLegacyLayout(
   target,
   {
     dryRun = false,
     packageRoot = getPackageRoot(),
-    afterCopyForTest = null,
-    afterPublishForTest = null,
-    beforeLegacyCleanupForTest = null,
-    removeLegacyArtifactForTest = null,
   } = {},
 ) {
   const detection = await detectLegacySingletonLayout(target);
@@ -90,60 +45,21 @@ export async function migrateLegacyLayout(
   let canonicalTaskId = null;
   const artifactIdentities = [];
 
-  // Determine candidate canonicalTaskId from known legacy artifacts
+  const identitySchemas = { contract: "current-contract", state: "work-state", continuity: "continuity", receipt: "execution-receipt" };
   for (const item of detection.legacyFiles) {
-    if (item.key === "contract") {
-      try {
-        const contract = await readJsonArtifact(target, item.path, "current-contract", packageRoot);
-        if (contract.value?.taskId) {
-          if (!canonicalTaskId) canonicalTaskId = contract.value.taskId;
-          artifactIdentities.push({ artifact: "contract", taskId: contract.value.taskId });
-        }
-      } catch (err) {
-        const error = new Error(`Legacy contract artifact is invalid: ${err.message}`);
-        error.code = E_TASK_MIGRATION_INVALID;
-        error.cause = err;
-        throw error;
-      }
-    } else if (item.key === "state") {
-      try {
-        const state = await readJsonArtifact(target, item.path, "work-state", packageRoot);
-        if (state.value?.taskId) {
-          if (!canonicalTaskId) canonicalTaskId = state.value.taskId;
-          artifactIdentities.push({ artifact: "state", taskId: state.value.taskId });
-        }
-      } catch (err) {
-        const error = new Error(`Legacy state artifact is invalid: ${err.message}`);
-        error.code = E_TASK_MIGRATION_INVALID;
-        error.cause = err;
-        throw error;
-      }
-    } else if (item.key === "continuity") {
-      try {
-        const continuity = await readJsonArtifact(target, item.path, "continuity", packageRoot);
-        if (continuity.value?.taskId) {
-          if (!canonicalTaskId) canonicalTaskId = continuity.value.taskId;
-          artifactIdentities.push({ artifact: "continuity", taskId: continuity.value.taskId });
-        }
-      } catch (err) {
-        const error = new Error(`Legacy continuity artifact is invalid: ${err.message}`);
-        error.code = E_TASK_MIGRATION_INVALID;
-        error.cause = err;
-        throw error;
-      }
-    } else if (item.key === "receipt") {
-      try {
-        const receipt = await readJsonArtifact(target, item.path, "execution-receipt", packageRoot);
-        if (receipt.value?.taskId) {
-          if (!canonicalTaskId) canonicalTaskId = receipt.value.taskId;
-          artifactIdentities.push({ artifact: "receipt", taskId: receipt.value.taskId });
-        }
-      } catch (err) {
-        const error = new Error(`Legacy receipt artifact is invalid: ${err.message}`);
-        error.code = E_TASK_MIGRATION_INVALID;
-        error.cause = err;
-        throw error;
+    const schema = identitySchemas[item.key];
+    if (!schema) continue;
+    try {
+      const artifact = await readPortableJsonArtifact(target, item.path, schema, packageRoot);
+      if (artifact.value?.taskId) {
+        canonicalTaskId ??= artifact.value.taskId;
+        artifactIdentities.push({ artifact: item.key, taskId: artifact.value.taskId });
       }
+    } catch (err) {
+      const error = new Error(`Legacy ${item.key} artifact is invalid: ${err.message}`);
+      error.code = E_TASK_MIGRATION_INVALID;
+      error.cause = err;
+      throw error;
     }
   }
 
@@ -167,7 +83,7 @@ export async function migrateLegacyLayout(
   }
 
   // 1. Validate complete legacy source snapshot fail-closed before creating any directories
-  const sourceSnapshot = await validateMigrationSnapshot(target, {
+  await validateMigrationSnapshot(target, {
     taskId: canonicalTaskId,
     packageRoot,
     paths: LEGACY_TASK_ARTIFACT_PATHS,
@@ -176,8 +92,6 @@ export async function migrateLegacyLayout(
   const taskKey = taskStorageKey(canonicalTaskId);
   const finalDirRel = taskDirectory(canonicalTaskId);
   const finalDirAbs = ensureWithin(target, finalDirRel);
-  const tempDirRel = `${TASK_STATE_ROOT}/.tmp-${taskKey}`;
-  const tempDirAbs = ensureWithin(target, tempDirRel);
 
   if (await fileExists(finalDirAbs)) {
     const error = new Error(`Target task directory already exists: ${finalDirRel}`);
@@ -185,8 +99,6 @@ export async function migrateLegacyLayout(
     throw error;
   }
 
-  const migratedArtifacts = [];
-
   if (dryRun) {
     return {
       migrated: false,
@@ -198,187 +110,5 @@ export async function migrateLegacyLayout(
     };
   }
 
-  let published = false;
-  let cleanupStarted = false;
-
-  // 2. Create temporary migration directory
-  await mkdir(tempDirAbs, { recursive: true });
-
-  try {
-    // 3. Create and write task.json descriptor
-    const descriptor = createTaskDescriptor({
-      taskId: canonicalTaskId,
-      writeClaims: [],
-    });
-    await writeTaskDescriptor(target, descriptor, packageRoot, {
-      relativePathOverride: `${tempDirRel}/task.json`,
-    });
-    migratedArtifacts.push("task.json");
-
-    // 4. Copy and map files into temp namespace
-    const fileMapping = [
-      [LEGACY_TASK_ARTIFACT_PATHS.contract, "contract.json"],
-      [LEGACY_TASK_ARTIFACT_PATHS.route, "routing-result.json"],
-      [LEGACY_TASK_ARTIFACT_PATHS.preflight, "preflight.json"],
-      [LEGACY_TASK_ARTIFACT_PATHS.state, "work-state.json"],
-      [LEGACY_TASK_ARTIFACT_PATHS.continuity, "continuity.json"],
-      [LEGACY_TASK_ARTIFACT_PATHS.receipt, "execution-receipt.json"],
-      [LEGACY_TASK_ARTIFACT_PATHS.events, "events.ndjson"],
-    ];
-
-    for (const [legacyRel, destName] of fileMapping) {
-      const srcAbs = ensureWithin(target, legacyRel);
-      if (await fileExists(srcAbs)) {
-        const destAbs = path.join(tempDirAbs, destName);
-        await cp(srcAbs, destAbs);
-        migratedArtifacts.push(destName);
-      }
-    }
-
-    // 5. Copy directories: gates/ and executions/
-    const dirMapping = [
-      [LEGACY_TASK_ARTIFACT_PATHS.gates, "gates"],
-      [LEGACY_TASK_ARTIFACT_PATHS.executions, "executions"],
-    ];
-
-    for (const [legacyRel, destDirName] of dirMapping) {
-      const srcAbs = ensureWithin(target, legacyRel);
-      if (await fileExists(srcAbs)) {
-        const destAbs = path.join(tempDirAbs, destDirName);
-        await cp(srcAbs, destAbs, { recursive: true });
-        migratedArtifacts.push(`${destDirName}/`);
-      }
-    }
-
-    // Test hook for corruption / failure testing
-    if (typeof afterCopyForTest === "function") {
-      await afterCopyForTest({ tempDirAbs, tempDirRel, target });
-    }
-
-    // 6. Validate temp snapshot
-    const tempPaths = {
-      contract: `${tempDirRel}/contract.json`,
-      route: `${tempDirRel}/routing-result.json`,
-      preflight: `${tempDirRel}/preflight.json`,
-      state: `${tempDirRel}/work-state.json`,
-      continuity: `${tempDirRel}/continuity.json`,
-      receipt: `${tempDirRel}/execution-receipt.json`,
-      events: `${tempDirRel}/events.ndjson`,
-      gates: `${tempDirRel}/gates`,
-      executions: `${tempDirRel}/executions`,
-    };
-
-    const tempSnapshot = await validateMigrationSnapshot(target, {
-      taskId: canonicalTaskId,
-      packageRoot,
-      paths: tempPaths,
-    });
-
-    // 7. Compare copied fingerprints
-    assertMigrationSnapshotsEqual(sourceSnapshot, tempSnapshot, "temporary namespace");
-
-    // 8. Atomically publish
-    await mkdir(ensureWithin(target, TASK_STATE_ROOT), { recursive: true });
-    await rename(tempDirAbs, finalDirAbs);
-    published = true;
-
-    // Test hook for corruption / failure testing after publication
-    if (typeof afterPublishForTest === "function") {
-      await afterPublishForTest({ finalDirAbs, finalDirRel, target });
-    }
-
-    // 9. Post-publish validation: verify final namespace snapshot and task descriptor
-    const finalPaths = {
-      contract: taskArtifactPath(canonicalTaskId, "contract"),
-      route: taskArtifactPath(canonicalTaskId, "route"),
-      preflight: taskArtifactPath(canonicalTaskId, "preflight"),
-      state: taskArtifactPath(canonicalTaskId, "state"),
-      continuity: taskArtifactPath(canonicalTaskId, "continuity"),
-      receipt: taskArtifactPath(canonicalTaskId, "receipt"),
-      events: taskArtifactPath(canonicalTaskId, "events"),
-      gates: taskArtifactPath(canonicalTaskId, "gates"),
-      executions: taskArtifactPath(canonicalTaskId, "executions"),
-    };
-
-    const finalSnapshot = await validateMigrationSnapshot(target, {
-      taskId: canonicalTaskId,
-      packageRoot,
-      paths: finalPaths,
-    });
-    assertMigrationSnapshotsEqual(sourceSnapshot, finalSnapshot, "published namespace");
-    await readTaskDescriptor(target, canonicalTaskId, packageRoot);
-
-    const migrationReceipt = {
-      schemaVersion: 1,
-      protocolVersion: 1,
-      kind: "LEGACY_TASK_MIGRATION",
-      taskId: canonicalTaskId,
-      taskKey,
-      migratedAt: new Date().toISOString(),
-      source: sourceSnapshot,
-      destination: finalSnapshot,
-      cleanupStatus: "PENDING",
-    };
-    await writeFileAtomic(
-      ensureWithin(target, `${finalDirRel}/migration-receipt.json`),
-      `${JSON.stringify(migrationReceipt, null, 2)}\n`,
-    );
-    migratedArtifacts.push("migration-receipt.json");
-
-    // Test hook for cleanup failure testing
-    if (typeof beforeLegacyCleanupForTest === "function") {
-      await beforeLegacyCleanupForTest({ finalDirAbs, finalDirRel, target });
-    }
-
-    // 10. Cleanup legacy task files (strictly after successful publish and validation)
-    cleanupStarted = true;
-    try {
-      for (const item of detection.legacyFiles) {
-        if (typeof removeLegacyArtifactForTest === "function") {
-          await removeLegacyArtifactForTest(target, item.path);
-        } else {
-          await removeLegacyArtifact(target, item.path);
-        }
-      }
-      migrationReceipt.cleanupStatus = "COMPLETED";
-      migrationReceipt.cleanedAt = new Date().toISOString();
-      await writeFileAtomic(
-        ensureWithin(target, `${finalDirRel}/migration-receipt.json`),
-        `${JSON.stringify(migrationReceipt, null, 2)}\n`,
-      );
-    } catch (cleanupErr) {
-      const error = new Error(
-        `Migration published successfully to ${finalDirRel}, but legacy cleanup failed: ${cleanupErr.message}. Manual cleanup required.`,
-      );
-      error.code = E_TASK_MIGRATION_INVALID;
-      error.cause = cleanupErr;
-      throw error;
-    }
-
-    return {
-      migrated: true,
-      taskId: canonicalTaskId,
-      taskKey,
-      targetDirectory: finalDirRel,
-      migratedArtifacts,
-    };
-  } catch (error) {
-    if (published && !cleanupStarted && (await fileExists(finalDirAbs))) {
-      try {
-        await rm(finalDirAbs, { recursive: true, force: true });
-      } catch (rollbackErr) {
-        error.rollbackError = rollbackErr;
-      }
-    }
-
-    // Cleanup temp dir on failure if it still exists
-    if (await fileExists(tempDirAbs)) {
-      try {
-        await rm(tempDirAbs, { recursive: true, force: true });
-      } catch (tempErr) {
-        error.tempCleanupError = tempErr;
-      }
-    }
-    throw error;
-  }
+  throw Object.assign(new Error("Filesystem task migration apply is retired; use explicit SQLite task migration with destination and excluded writers"), { code: "E_STORAGE_OPERATION_UNSUPPORTED" });
 }

package/src/core/task-snapshot.js

@@ -1,16 +1,21 @@
-import { readEvents, validateEventLedger } from "./events.js";
+import { taskArtifactPath } from "./task-paths.js";
+import { createHash } from "node:crypto";
+import { getOperationalStore } from "../storage/operational-context.js";
+import { needsExistingProjectScope, withExistingProjectScope } from "../storage/existing-project-scope.js";
+import { iterateEvents, validateEventLedger, withEventLedgerAudit } from "./events.js";
 import { readWorkState } from "./work-state.js";
 import { canonicalFingerprint } from "./artifacts.js";
 
-function ledgerTail(events) {
-  const last = events.at(-1) ?? null;
+async function ledgerTail(target, packageRoot, options) {
+  let last = null;
+  for await (const event of iterateEvents(target, packageRoot, options)) last = event;
   return {
     sequence: last?.seq ?? 0,
     hash: last?.hash ?? null,
   };
 }
 
-export async function buildTaskSnapshot({
+async function buildPortableTaskSnapshot({
   target,
   packageRoot,
   taskId = null,
@@ -19,19 +24,17 @@ export async function buildTaskSnapshot({
 } = {}) {
   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),
+    ...await ledgerTail(target, packageRoot, options),
   };
 
   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),
+    ...await ledgerTail(target, packageRoot, options),
   };
 
   const consistent = JSON.stringify(before) === JSON.stringify(after);
@@ -51,3 +54,43 @@ export async function buildTaskSnapshot({
     events: validation.events,
   };
 }
+
+
+function eventSummaryFingerprint(events) {
+  const digest = createHash("sha256");
+  digest.update("[");
+  let first = true;
+  for (const { seq, event, at } of events) {
+    if (!first) digest.update(",");
+    first = false;
+    // Same sorted keys/undefined omission as canonicalFingerprint({seq,event,at}).
+    digest.update(JSON.stringify({ at, event, seq }));
+  }
+  return digest.update("]").digest("hex");
+}
+
+/** Internal callback keeps event source owned until the projection finishes. */
+export async function withTaskSnapshot(options, callback) {
+  const { target, packageRoot, taskId = null, eventsPath = null, stateFile = null } = options;
+  if (await needsExistingProjectScope(target)) {
+    return withExistingProjectScope(target, () => withTaskSnapshot(options, callback), { readOnly: true });
+  }
+  if (!getOperationalStore(target) || (stateFile && (!taskId || stateFile !== taskArtifactPath(taskId, "state")))) {
+    return callback(await buildPortableTaskSnapshot(options));
+  }
+  return withEventLedgerAudit(target, packageRoot, { taskId, ...(eventsPath ? { eventsPath } : {}) }, async validation => {
+    if (Array.isArray(validation.events)) return callback(await buildPortableTaskSnapshot(options));
+    const state = await readWorkState(target, { packageRoot, taskId, ...(stateFile ? { statePath: stateFile } : {}) });
+    const tail = validation.events.at(-1);
+    return callback({ consistent: true, taskId: taskId ?? state?.taskId ?? null,
+      anchors: { stateRevision: state?.revision ?? null, sequence: tail?.seq ?? 0, hash: tail?.hash ?? null },
+      capturedAt: new Date().toISOString(),
+      integrity: { valid: validation.valid, errors: validation.errors, eventCount: validation.events.length,
+        fingerprint: eventSummaryFingerprint(validation.events) },
+      state, events: validation.events });
+  });
+}
+
+export async function buildTaskSnapshot(options = {}) {
+  return withTaskSnapshot(options, snapshot => ({ ...snapshot, events: Array.isArray(snapshot.events) ? snapshot.events : [...snapshot.events] }));
+}

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

@@ -0,0 +1,18 @@
+import { detectLegacySingletonLayout, migrateLegacyLayout } from "./task-migration.js";
+import { migrateProjectStorage } from "../storage/migration.js";
+
+/** Explicit legacy conversion now publishes canonical SQLite storage. */
+export async function migrateLegacyTaskStorage(target, { packageRoot, dryRun = false, destination, writersQuiesced = false } = {}) {
+  const detected = await detectLegacySingletonLayout(target);
+  if (!detected.hasLegacy) return migrateLegacyLayout(target, { packageRoot, dryRun });
+  if (dryRun) return { ...await migrateLegacyLayout(target, { packageRoot, dryRun }), targetDirectory: ".forgeloop/state.sqlite" };
+  if (typeof destination !== "string" || !destination || writersQuiesced !== true) throw Object.assign(new Error("Legacy task migration requires --destination and explicit --writers-quiesced for SQLite cutover"), { code: "E_CLI_INVOCATION_INVALID" });
+  const planned = await migrateLegacyLayout(target, { packageRoot, dryRun: true });
+  const storage = await migrateProjectStorage(target, { destination, writersQuiesced, packageRoot });
+  return {
+    migrated: true, taskId: planned.taskId, taskKey: planned.taskKey,
+    targetDirectory: ".forgeloop/state.sqlite", storage,
+    migrationReceipt: `${destination}/publication/publication-journal.json`,
+    migratedArtifacts: detected.legacyFiles.map(item => item.path),
+  };
+}

package/src/core/templates.js

@@ -12,8 +12,17 @@ import { GUIDE_TEMPLATE_PATHS } from "./guide-registry.js";
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
-const TEMPLATE_SOURCE_PATHS = Object.freeze({
-  ".forgeloop/.gitignore": ".forgeloop/forgeloop.gitignore",
+const INLINE_TEMPLATE_CONTENT = Object.freeze({
+  ".forgeloop/.gitignore": [
+    "# Local resumable task state is untrusted, target-specific data.",
+    "work-state.json",
+    "state.sqlite",
+    "state.sqlite-*",
+    "storage-version.json",
+    "executions/",
+    "repository-index/",
+    "",
+  ].join("\n"),
 });
 
 export const TEMPLATE_PATHS = [
@@ -36,8 +45,6 @@ export const TEMPLATE_PATHS = [
   "PROTOCOL_INTEGRATION.md",
   "AGENT_COMPATIBILITY.md",
   "THIRD_PARTY_NOTICES.md",
-  "LICENSE",
-  "LICENSE-DOCS.md",
   ...GUIDE_TEMPLATE_PATHS,
   "schemas/routing-input.schema.json",
   "schemas/routing-result.schema.json",
@@ -100,14 +107,19 @@ export function getPackageRoot() {
 export async function readTemplateEntries(packageRoot = PACKAGE_ROOT) {
   return Promise.all(
     TEMPLATE_PATHS.map(async (relativePath) => {
-      const sourcePath = TEMPLATE_SOURCE_PATHS[relativePath] ?? relativePath;
+      const sourcePath = relativePath;
+      const inlineContent = INLINE_TEMPLATE_CONTENT[relativePath];
       return {
         relativePath: targetPathForSource(relativePath),
         sourcePath,
         legacyRelativePath: legacyPathForSource(sourcePath),
-        bytes: Buffer.from(isNativeAdapterPath(relativePath)
-          ? nativeShim(relativePath)
-          : await readFile(path.join(packageRoot, sourcePath))),
+        bytes: Buffer.from(
+          inlineContent !== undefined
+            ? inlineContent
+            : isNativeAdapterPath(relativePath)
+              ? nativeShim(relativePath)
+              : await readFile(path.join(packageRoot, sourcePath)),
+        ),
       };
     }),
   );

package/src/core/test-intelligence/prune.js

@@ -1,4 +1,5 @@
 import { readTestUtility } from "./service.js";
+import { assertSafePath } from "../filesystem.js";
 import { cp, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -38,6 +39,9 @@ export async function runPruneProbe({ target, packageRoot, taskId, testId } = {}
   }
   const temporaryRoot = await mkdtemp(path.join(os.tmpdir(), "forgeloop-prune-probe-"));
   try {
+    // Persisted utility records do not grant access outside the project or
+    // through symlinks copied into the disposable workspace.
+    await assertSafePath(target, item.file);
     await cp(target, temporaryRoot, {
       recursive: true,
       dereference: false,
@@ -49,7 +53,7 @@ export async function runPruneProbe({ target, packageRoot, taskId, testId } = {}
     const dependencies = path.join(target, "node_modules");
     try { await symlink(dependencies, path.join(temporaryRoot, "node_modules"), "junction"); } catch { /* dependencies are optional for static probes */ }
     if (item.file.endsWith(".mjs") || item.file.endsWith(".js")) {
-      const candidatePath = path.join(temporaryRoot, item.file);
+      const candidatePath = await assertSafePath(temporaryRoot, item.file);
       const source = await readFile(candidatePath, "utf8");
       const escapedName = item.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
       const pattern = new RegExp(`\\b(test|it)\\s*\\(\\s*([\\"'])${escapedName}\\2`);