@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.4

package/src/core/actions.js

@@ -1,8 +1,5 @@
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-
 import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
-import { appendProtocolEvent, readEvents } from "./events.js";
+import { appendProtocolEvent, iterateEvents } from "./events.js";
 import {
   canonicalActionFingerprint,
   actionRequiresIdempotency,
@@ -22,8 +19,7 @@ import {
   E_ACTION_STATE_MISMATCH,
   E_ACTION_VERIFICATION_REQUIRED,
 } from "./error-codes.js";
-import { assertSafePath, ensureWithin } from "./filesystem.js";
-import { taskActionPath, taskDirectory, TASK_ARTIFACT_FILES } from "./task-paths.js";
+import { requireNativeStore, withNativeReadScope } from "./native-storage.js";
 
 const STATE_EVENT_NAMES = Object.freeze({
   AUTHORIZED: "ACTION_AUTHORIZED",
@@ -41,61 +37,26 @@ function actionError(code, message) {
   return error;
 }
 
-async function readActionFile(target, packageRoot, taskId, actionId) {
-  const relPath = taskActionPath(taskId, actionId);
-  await assertSafePath(target, relPath);
-  const absolute = ensureWithin(target, relPath);
-  let text;
-  try {
-    text = await readFile(absolute, "utf8");
-  } catch (error) {
-    if (error?.code === "ENOENT") return null;
-    throw error;
-  }
-  try {
-    return JSON.parse(text);
-  } catch (error) {
-    throw actionError(E_ACTION_INVALID, `durable action artifact is not valid JSON: ${relPath}`);
-  }
-}
-
-async function writeActionFile(target, packageRoot, taskId, action) {
-  const relPath = taskActionPath(taskId, action.actionId);
-  await assertSafePath(target, relPath);
-  const serialized = `${JSON.stringify(action, null, 2)}\n`;
-  const activeTransaction = (await getTaskTransaction(target));
-  if (activeTransaction) {
-    await activeTransaction.stageText(relPath, serialized);
-  } else {
-    const absolute = ensureWithin(target, relPath);
-    await mkdir(path.dirname(absolute), { recursive: true });
-    await writeFile(absolute, serialized, "utf8");
-  }
+async function readActionFile(target, taskId, actionId) {
+  return withNativeReadScope(target, () => requireNativeStore(
+    target,
+    actionError,
+    "Actions require canonical SQLite storage; migrate legacy operational state explicitly",
+  ).readAction(taskId, actionId));
 }
 
-function taskActionsDirectory(taskId) {
-  return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.actions}`;
+async function writeActionFile(target, action) {
+  const transaction = await getTaskTransaction(target);
+  if (!transaction) throw actionError("E_STORAGE_TRANSACTION_INVALID", "Action persistence requires an active task transaction");
+  return transaction.stageAction(action);
 }
 
-async function listActionFiles(target, packageRoot, taskId) {
-  const relDir = taskActionsDirectory(taskId);
-  await assertSafePath(target, relDir);
-  const absoluteDir = ensureWithin(target, relDir);
-  let entries;
-  try {
-    entries = await readdir(absoluteDir);
-  } catch (error) {
-    if (error?.code === "ENOENT") return [];
-    throw error;
-  }
-  const actions = [];
-  for (const entry of entries) {
-    if (!entry.endsWith(".json")) continue;
-    const parsed = await readActionFile(target, packageRoot, taskId, entry.replace(/\.json$/, ""));
-    if (parsed) actions.push(parsed);
-  }
-  actions.sort((left, right) => String(left.createdAt).localeCompare(String(right.createdAt)));
-  return actions;
+async function listActionFiles(target, taskId) {
+  return withNativeReadScope(target, () => requireNativeStore(
+    target,
+    actionError,
+    "Action listing requires canonical SQLite storage; migrate legacy operational state explicitly",
+  ).listActions(taskId).sort((left, right) => String(left.createdAt).localeCompare(String(right.createdAt))));
 }
 
 function assertProposeInput(input) {
@@ -152,7 +113,7 @@ export async function proposeAction(target, { packageRoot, taskId, input }) {
         );
       }
 
-      const existingById = await readActionFile(target, packageRoot, taskId, input.actionId);
+      const existingById = await readActionFile(target, taskId, input.actionId);
       if (existingById) {
         if (existingById.actionFingerprint === identityFingerprint) {
           validateActionArtifact(existingById);
@@ -185,7 +146,7 @@ export async function proposeAction(target, { packageRoot, taskId, input }) {
       };
       validateActionArtifact(action);
 
-      await writeActionFile(target, packageRoot, taskId, action);
+      await writeActionFile(target, action);
       await appendProtocolEvent(target, {
         taskId,
         event: "ACTION_PROPOSED",
@@ -207,25 +168,28 @@ export async function proposeAction(target, { packageRoot, taskId, input }) {
   );
 }
 
-export async function readAction(target, { packageRoot, taskId, actionId }) {
-  const action = await readActionFile(target, packageRoot, taskId, actionId);
+export async function readAction(target, { taskId, actionId }) {
+  const action = await readActionFile(target, taskId, actionId);
   if (!action) {
     throw actionError(E_ACTION_NOT_FOUND, `durable action ${actionId} does not exist for task ${taskId}`);
   }
   return validateActionArtifact(action);
 }
 
-export async function listActions(target, { packageRoot, taskId }) {
-  const actions = await listActionFiles(target, packageRoot, taskId);
+export async function listActions(target, { taskId }) {
+  const actions = await listActionFiles(target, taskId);
   return actions.map((action) => validateActionArtifact(action));
 }
 
-export async function findActionByIdempotencyKey(target, { packageRoot, taskId, idempotencyKey }) {
+export async function findActionByIdempotencyKey(target, { taskId, idempotencyKey }) {
   if (typeof idempotencyKey !== "string" || !idempotencyKey) {
     throw actionError(E_ACTION_INVALID, "idempotencyKey must be a non-empty string");
   }
-  const actions = await listActionFiles(target, packageRoot, taskId);
-  const found = actions.find((action) => action.idempotencyKey === idempotencyKey);
+  const found = await withNativeReadScope(target, () => requireNativeStore(
+    target,
+    actionError,
+    "Action listing requires canonical SQLite storage; migrate legacy operational state explicitly",
+  ).findActionByIdempotencyKey(taskId, idempotencyKey));
   return found ? validateActionArtifact(found) : null;
 }
 
@@ -289,7 +253,7 @@ async function applyTransition(target, {
         next.commitResultCode = details.commitResultCode;
       }
       validateActionArtifact(next);
-      await writeActionFile(target, packageRoot, taskId, next);
+      await writeActionFile(target, next);
 
       const baseDetails = {
         actionId: next.actionId,
@@ -413,13 +377,12 @@ export async function transitionVerifiedAction(target, {
 }
 
 export async function detectOrphanActions(target, { packageRoot, taskId }) {
-  const actions = await listActionFiles(target, packageRoot, taskId);
-  const events = await readEvents(target, packageRoot, { taskId });
-  const proposedFingerprints = new Set(
-    events
-      .filter((event) => event.event === "ACTION_PROPOSED")
-      .map((event) => event.details?.actionFingerprint),
-  );
+  const actions = await listActionFiles(target, taskId);
+  const candidates = new Set(actions.map(action => action.actionFingerprint));
+  const proposedFingerprints = new Set();
+  for await (const event of iterateEvents(target, packageRoot, { taskId })) {
+    if (event.event === "ACTION_PROPOSED" && candidates.has(event.details?.actionFingerprint)) proposedFingerprints.add(event.details?.actionFingerprint);
+  }
   return actions
     .filter((action) => !proposedFingerprints.has(action.actionFingerprint))
     .map((action) => action.actionId);
@@ -431,7 +394,7 @@ export async function detectOrphanActions(target, { packageRoot, taskId }) {
  * authorization, reconciliation, verification) and compared to its artifact.
  */
 export async function validateActionLedgerConsistency(target, { packageRoot, taskId }) {
-  const actions = await listActionFiles(target, packageRoot, taskId);
+  const actions = await listActionFiles(target, taskId);
   const { projectActionLedger } = await import("./action-ledger-projection.js");
   const issues = [];
   for (const action of actions) {

package/src/core/activation.js

@@ -3,8 +3,14 @@ import { randomUUID } from "node:crypto";
 import { ARTIFACT_PATHS, writeJsonArtifact } from "./artifacts.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { sessionArtifactPath } from "./task-paths.js";
+import { getOperationalStore } from "../storage/operational-context.js";
+import { withTaskTransaction } from "./transaction.js";
 
 export async function activateSession(target, packageRoot, options = {}) {
+  if (!getOperationalStore(target)) {
+    const { withProjectStorage } = await import("../storage/project-boundary.js");
+    return withProjectStorage(target, () => activateSession(target, packageRoot, options));
+  }
   const sessionId = options.sessionId ?? randomUUID();
   const value = {
     schemaVersion: 1,
@@ -14,7 +20,9 @@ export async function activateSession(target, packageRoot, options = {}) {
     createdAt: options.createdAt ?? new Date().toISOString(),
   };
   const relativePath = sessionArtifactPath(sessionId);
-  const written = await writeJsonArtifact(target, relativePath, value, "activation", packageRoot, options);
-  await writeJsonArtifact(target, ARTIFACT_PATHS.session, value, "activation", packageRoot, options).catch(() => {});
-  return { ...written.value, path: relativePath };
+  return withTaskTransaction({ target, taskId: sessionId, operation: "activate-session", packageRoot }, async () => {
+    const written = await writeJsonArtifact(target, relativePath, value, "activation", packageRoot);
+    await writeJsonArtifact(target, ARTIFACT_PATHS.session, value, "activation", packageRoot);
+    return { ...written.value, path: relativePath };
+  });
 }

package/src/core/approvals.js

@@ -1,6 +1,3 @@
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-
 import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
 import { appendProtocolEvent } from "./events.js";
 import { canonicalFingerprint } from "./artifacts.js";
@@ -16,11 +13,10 @@ import {
   E_APPROVAL_INVALID,
   E_APPROVAL_STALE,
 } from "./error-codes.js";
-import { assertSafePath, ensureWithin } from "./filesystem.js";
 import { isTrustedHostAuthorityContext } from "./capability-policy.js";
-import { taskApprovalPath, taskDirectory, TASK_ARTIFACT_FILES } from "./task-paths.js";
 import { readAction } from "./actions.js";
 import { readWorkState } from "./work-state.js";
+import { requireNativeStore, withNativeReadScope } from "./native-storage.js";
 
 function approvalError(code, message) {
   const error = new Error(message);
@@ -29,55 +25,25 @@ function approvalError(code, message) {
 }
 
 async function readApprovalFile(target, taskId, approvalId) {
-  const relPath = taskApprovalPath(taskId, approvalId);
-  await assertSafePath(target, relPath);
-  let text;
-  try {
-    text = await readFile(ensureWithin(target, relPath), "utf8");
-  } catch (error) {
-    if (error?.code === "ENOENT") return null;
-    throw error;
-  }
-  try {
-    return JSON.parse(text);
-  } catch {
-    throw approvalError(E_APPROVAL_INVALID, `approval artifact is not valid JSON: ${relPath}`);
-  }
+  return withNativeReadScope(target, () => requireNativeStore(
+    target,
+    approvalError,
+    "Approvals require canonical SQLite storage; migrate legacy operational state explicitly",
+  ).readApproval(taskId, approvalId));
 }
 
-async function writeApprovalFile(target, taskId, approval) {
-  const relPath = taskApprovalPath(taskId, approval.approvalId);
-  await assertSafePath(target, relPath);
-  const serialized = `${JSON.stringify(approval, null, 2)}\n`;
-  const activeTransaction = (await getTaskTransaction(target));
-  if (activeTransaction) {
-    await activeTransaction.stageText(relPath, serialized);
-  } else {
-    const absolute = ensureWithin(target, relPath);
-    await mkdir(path.dirname(absolute), { recursive: true });
-    await writeFile(absolute, serialized, "utf8");
-  }
+async function writeApprovalFile(target, approval) {
+  const transaction = await getTaskTransaction(target);
+  if (!transaction) throw approvalError("E_STORAGE_TRANSACTION_INVALID", "Approval persistence requires an active task transaction");
+  return transaction.stageApproval(approval);
 }
 
 async function listApprovalFiles(target, taskId) {
-  const relDir = `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.approvals}`;
-  await assertSafePath(target, relDir);
-  const absoluteDir = ensureWithin(target, relDir);
-  let entries;
-  try {
-    entries = await readdir(absoluteDir);
-  } catch (error) {
-    if (error?.code === "ENOENT") return [];
-    throw error;
-  }
-  const approvals = [];
-  for (const entry of entries) {
-    if (!entry.endsWith(".json")) continue;
-    const parsed = await readApprovalFile(target, taskId, entry.replace(/\.json$/, ""));
-    if (parsed) approvals.push(parsed);
-  }
-  approvals.sort((left, right) => String(left.requestedAt).localeCompare(String(right.requestedAt)));
-  return approvals;
+  return withNativeReadScope(target, () => requireNativeStore(
+    target,
+    approvalError,
+    "Approval listing requires canonical SQLite storage; migrate legacy operational state explicitly",
+  ).listApprovals(taskId).sort((left, right) => String(left.requestedAt).localeCompare(String(right.requestedAt))));
 }
 
 function approvalBindingFields(approval) {
@@ -207,7 +173,7 @@ export async function requestApproval(target, { packageRoot, taskId, input }) {
       };
       validateApprovalArtifact(approval);
 
-      await writeApprovalFile(target, taskId, approval);
+      await writeApprovalFile(target, approval);
       await appendProtocolEvent(target, {
         taskId,
         event: "APPROVAL_REQUESTED",
@@ -295,7 +261,7 @@ export async function resolveApproval(target, {
         reason: reason ?? current.reason ?? null,
       };
       validateApprovalArtifact(resolved);
-      await writeApprovalFile(target, taskId, resolved);
+      await writeApprovalFile(target, resolved);
 
       const details = {
         approvalId: resolved.approvalId,

package/src/core/artifact-registry.js

@@ -1,12 +1,12 @@
 import { TASK_STATE_ROOT, TASK_ARTIFACT_FILES, PROJECT_ARTIFACT_PATHS, SESSIONS_ROOT } from "./task-paths.js";
 
 /**
- * Canonical registry of ForgeLoop artifacts, defining filesystem paths,
+ * Canonical registry of ForgeLoop artifacts, defining logical identities,
  * schema bindings, ownership, mutability, trust classifications, and scopes.
  *
  * Schema field shapes remain strictly owned by JSON schemas in `schemas/`.
  */
-export const ARTIFACT_REGISTRY = Object.freeze({
+const ARTIFACT_DEFINITIONS = Object.freeze({
   descriptor: Object.freeze({
     key: "descriptor",
     scope: "TASK",
@@ -416,3 +416,60 @@ export const ARTIFACT_REGISTRY = Object.freeze({
     description: "Deterministic test inventory and bounded utility analysis; never completion evidence or deletion authority.",
   }),
 });
+
+const DATABASE_PATH = ".forgeloop/state.sqlite";
+const RECORD_TABLES = Object.freeze({ descriptor: "tasks", state: "tasks", events: "events", actions: "actions", approvals: "approvals", executions: "executions", session: "sessions" });
+const ARTIFACT_KINDS = Object.freeze({ gates: "gate", evaluations: "evaluation", handoffs: "handoff", semanticDecisions: "decision", codeManifest: "attestation", attestationStatement: "attestation" });
+
+function canonicalStorage(artifact) {
+  if (artifact.scope === "PROJECT") return Object.freeze({ backend: "FILE", path: artifact.path });
+  if (artifact.key === "attestationBundle") {
+    return Object.freeze({ backend: "SQLITE_REFERENCED_FILE", path: DATABASE_PATH, table: "attachment_references", attachmentPath: ".forgeloop/attachments/objects/<sha256>" });
+  }
+  const table = RECORD_TABLES[artifact.key] ?? "task_artifacts";
+  return Object.freeze({ backend: "SQLITE", path: DATABASE_PATH, table,
+    ...(table === "task_artifacts" ? { kind: ARTIFACT_KINDS[artifact.key] ?? artifact.key } : {}),
+    ...(artifact.key === "descriptor" ? { column: "descriptor_json" } : {}),
+    ...(artifact.key === "state" ? { column: "state_json" } : {}),
+  });
+}
+
+/** `path` stays a historical logical alias; it is never a live-file guarantee. */
+export const ARTIFACT_REGISTRY = Object.freeze(Object.fromEntries(
+  Object.entries(ARTIFACT_DEFINITIONS).map(([key, artifact]) => [key, Object.freeze({
+    ...artifact,
+    logicalPath: artifact.path,
+    canonicalStorage: canonicalStorage(artifact),
+    // Configuration and policy inputs are copied separately from database export.
+    exportPath: artifact.scope === "PROJECT" ? null : artifact.key === "attestationBundle" ? ".forgeloop/attachments/objects/<sha256>" : artifact.path,
+    ...(artifact.key === "attestationBundle" ? { exportBindingPath: "export-index.json#attachments" } : {}),
+  })]),
+));
+
+function portableSingletonMapping(key) {
+  return Object.freeze({
+    key, kind: ARTIFACT_REGISTRY[key].canonicalStorage.kind, filename: TASK_ARTIFACT_FILES[key],
+  });
+}
+
+function portableCollectionMapping([key, registryKey]) {
+  return Object.freeze({
+    kind: ARTIFACT_REGISTRY[registryKey].canonicalStorage.kind, directory: TASK_ARTIFACT_FILES[key],
+  });
+}
+
+/** Ordered interchange mappings; bundle-specific filenames remain in bundles.js. */
+export const PORTABLE_ARTIFACT_MAPPINGS = Object.freeze({
+  singletons: Object.freeze([
+    "contract", "route", "preflight", "continuity", "receipt", "policySnapshot",
+    "recovery", "workspaceBinding", "responsibility", "verificationScope", "usage", "testUtility",
+  ].map(portableSingletonMapping)),
+  collections: Object.freeze([
+    ["gates", "gates"],
+    ["handoffs", "handoffs"],
+    ["decisions", "semanticDecisions"],
+    ["attestations", "codeManifest"],
+    ["evaluations", "evaluations"],
+    ["structuralQuality", "structuralQuality"],
+  ].map(portableCollectionMapping)),
+});

package/src/core/artifacts.js

@@ -1,3 +1,5 @@
+import { ARTIFACT_REGISTRY } from "./artifact-registry.js";
+import { needsExistingProjectScope, withExistingProjectScope, assertNativeWritePath, isOperationalArtifactPath } from "../storage/existing-project-scope.js";
 import { createHash } from "node:crypto";
 
 import { assertSafePath, ensureWithin, fileExists, readBytes, writeFileAtomic } from "./filesystem.js";
@@ -6,6 +8,12 @@ import { assertJsonBytes, assertJsonLimits } from "./json-safety.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
 import { getPackageRoot } from "./templates.js";
 import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
+import { getOperationalStore, readOperationalText } from "../storage/operational-context.js";
+import { withNativeReadScope } from "./native-storage.js";
+
+const OPERATIONAL_SCHEMAS = new Set(Object.values(ARTIFACT_REGISTRY)
+  .filter(artifact => artifact.scope !== "PROJECT" && artifact.schema)
+  .map(artifact => artifact.schema));
 
 export const ARTIFACT_PATHS = Object.freeze({
   contract: ".forgeloop/current-contract.json",
@@ -63,12 +71,43 @@ function artifactError(code, relativePath, error) {
   );
 }
 
+/** Validate already captured canonical bytes after their native read scope closes. */
+export async function parseCapturedJsonArtifact(text, relativePath, schemaName, packageRoot = getPackageRoot()) {
+  if (text === null) throw new ArtifactError("ARTIFACT_MISSING", `Artifact is missing: ${relativePath}`, [relativePath]);
+  try {
+    assertJsonBytes(text, relativePath);
+    const value = JSON.parse(text);
+    assertJsonLimits(value, relativePath);
+    assertSchema(value, await readSchema(schemaName, packageRoot), relativePath);
+    return { value, path: relativePath, fingerprint: canonicalFingerprint(value) };
+  } catch (error) { throw artifactError(error.code === "JSON_LIMIT_EXCEEDED" ? error.code : "ARTIFACT_INVALID", relativePath, error); }
+}
+
 export async function readJsonArtifact(
   target,
   relativePath,
   schemaName,
   packageRoot = getPackageRoot(),
 ) {
+  return withNativeReadScope(target, async () => {
+    const operational = readOperationalText(target, relativePath);
+    if (operational.selected) {
+      return parseCapturedJsonArtifact(operational.text, relativePath, schemaName, packageRoot);
+    }
+    if (isOperationalArtifactPath(relativePath)) {
+      try { await assertSafePath(target, relativePath); }
+      catch (error) { throw artifactError("ARTIFACT_PATH_INVALID", relativePath, error); }
+      if (!(await fileExists(ensureWithin(target, relativePath)))) {
+        throw new ArtifactError("ARTIFACT_MISSING", `Artifact is missing: ${relativePath}`, [relativePath]);
+      }
+      throw new ArtifactError("E_STORAGE_MIGRATION_REQUIRED", "Operational JSON reads require canonical SQLite storage; migrate legacy state explicitly", [relativePath]);
+    }
+    return readPortableJsonArtifact(target, relativePath, schemaName, packageRoot);
+  });
+}
+
+/** Explicit file inspection for migration inputs, portable exports and configuration. */
+export async function readPortableJsonArtifact(target, relativePath, schemaName, packageRoot = getPackageRoot()) {
   try {
     await assertSafePath(target, relativePath);
   } catch (error) {
@@ -76,9 +115,7 @@ export async function readJsonArtifact(
   }
 
   const artifactPath = ensureWithin(target, relativePath);
-  const transaction = (await getTaskTransaction(target));
-  const stagedText = transaction ? await transaction.readText(relativePath) : null;
-  if (stagedText === null && !(await fileExists(artifactPath))) {
+  if (!(await fileExists(artifactPath))) {
     throw new ArtifactError(
       "ARTIFACT_MISSING",
       `Artifact is missing: ${relativePath}`,
@@ -86,14 +123,9 @@ export async function readJsonArtifact(
     );
   }
 
-  let value;
   try {
-    const bytes = stagedText === null ? await readBytes(artifactPath) : Buffer.from(stagedText, "utf8");
-    assertJsonBytes(bytes, relativePath);
-    value = JSON.parse(bytes.toString("utf8"));
-    assertJsonLimits(value, relativePath);
-    const schema = await readSchema(schemaName, packageRoot);
-    assertSchema(value, schema, relativePath);
+    const bytes = await readBytes(artifactPath);
+    return await parseCapturedJsonArtifact(bytes, relativePath, schemaName, packageRoot);
   } catch (error) {
     throw artifactError(
       ["JSON_LIMIT_EXCEEDED", "ARTIFACT_PATH_INVALID"].includes(error.code)
@@ -103,12 +135,6 @@ export async function readJsonArtifact(
       error,
     );
   }
-
-  return {
-    value,
-    path: relativePath,
-    fingerprint: canonicalFingerprint(value),
-  };
 }
 
 export async function writeJsonArtifact(
@@ -119,17 +145,49 @@ export async function writeJsonArtifact(
   packageRoot = getPackageRoot(),
   { dryRun = false, taskId = null, operation = "write-artifact" } = {},
 ) {
+  if (OPERATIONAL_SCHEMAS.has(schemaName) && !isOperationalArtifactPath(relativePath)) {
+    throw new ArtifactError("E_STORAGE_OPERATION_UNSUPPORTED", "Operational artifacts require canonical SQLite identities; use explicit portable export", [relativePath]);
+  }
+  if (!getOperationalStore(target) && isOperationalArtifactPath(relativePath)) {
+    await assertSafePath(target, relativePath);
+    assertSecretFree(value);
+    assertSchema(value, await readSchema(schemaName, packageRoot), relativePath);
+    assertJsonLimits(value, relativePath);
+    assertJsonBytes(`${JSON.stringify(value, null, 2)}\n`, relativePath);
+    const { withProjectStorage } = await import("../storage/project-boundary.js");
+    return withProjectStorage(target, () => writeJsonArtifact(target, relativePath, value, schemaName, packageRoot, { dryRun, taskId, operation }), { readOnly: dryRun });
+  }
+  if (await needsExistingProjectScope(target)) {
+    return withExistingProjectScope(target, () => writeJsonArtifact(target, relativePath, value, schemaName, packageRoot, { dryRun, taskId, operation }), { readOnly: dryRun });
+  }
+  assertNativeWritePath(target, relativePath);
+  const store = getOperationalStore(target);
+  if (store?.recognizes(relativePath)) {
+    assertSecretFree(value);
+    assertSchema(value, await readSchema(schemaName, packageRoot), relativePath);
+    assertJsonLimits(value, relativePath);
+    const text = `${JSON.stringify(value, null, 2)}\n`;
+    assertJsonBytes(text, relativePath);
+    if (!dryRun) {
+      const scopedTaskId = taskId ?? value.taskId ?? store.transaction?.taskId;
+      if (!scopedTaskId) throw new ArtifactError("E_TASK_REQUIRED", "Operational artifact requires a task identity", [relativePath]);
+      await withTaskTransaction({ target, taskId: scopedTaskId, operation, packageRoot }, tx => tx.stageJsonRecord(relativePath, text, schemaName));
+    }
+    return { path: relativePath, fingerprint: canonicalFingerprint(value), value };
+  }
+  return writePortableJsonArtifact(target, relativePath, value, schemaName, packageRoot, { dryRun });
+}
+
+/** Explicit interchange/configuration output; never canonical operational persistence. */
+export async function writePortableJsonArtifact(target, relativePath, value, schemaName, packageRoot = getPackageRoot(), { dryRun = false } = {}) {
+  if (isOperationalArtifactPath(relativePath)) throw new ArtifactError("E_STORAGE_OPERATION_UNSUPPORTED", "Portable output cannot replace a canonical operational namespace", [relativePath]);
+  assertNativeWritePath(target, relativePath);
+  if (!dryRun && await getTaskTransaction(target)) throw new ArtifactError("E_STORAGE_TRANSACTION_INVALID", "Portable output requires no active operational transaction", [relativePath]);
   try {
     await assertSafePath(target, relativePath);
   } catch (error) {
     throw artifactError("ARTIFACT_PATH_INVALID", relativePath, error);
   }
-  const activeTransaction = (await getTaskTransaction(target));
-  if (!activeTransaction && taskId && !dryRun) {
-    return withTaskTransaction({ target, taskId, operation, packageRoot }, async () => (
-      writeJsonArtifact(target, relativePath, value, schemaName, packageRoot, { dryRun, taskId, operation })
-    ));
-  }
   try {
     const artifactPath = ensureWithin(target, relativePath);
     assertSecretFree(value);
@@ -138,11 +196,7 @@ export async function writeJsonArtifact(
     assertJsonLimits(value, relativePath);
     const serialized = `${JSON.stringify(value, null, 2)}\n`;
     assertJsonBytes(serialized, relativePath);
-    if (activeTransaction && !dryRun) {
-      await activeTransaction.stageText(relativePath, serialized);
-    } else {
-      await writeFileAtomic(artifactPath, serialized, { dryRun });
-    }
+    await writeFileAtomic(artifactPath, serialized, { dryRun });
     return { path: relativePath, fingerprint: canonicalFingerprint(value), value };
   } catch (error) {
     throw artifactError(

package/src/core/attachment-paths.js

@@ -0,0 +1,45 @@
+import { getOperationalStore, readOperationalText } from "../storage/operational-context.js";
+import { validateAttachmentReference } from "../storage/attachment-binding.js";
+import { taskStorageKey } from "./task-identity.js";
+import { taskAttestationBundlePath, taskAttestationStatementPath } from "./task-paths.js";
+import { legacyAttachmentReferenceId, signatureReferencePrefix } from "./signing/bundle-reference.js";
+
+function resolveCanonicalSignature(target, taskId, store) {
+  const source = readOperationalText(target, taskAttestationStatementPath(taskId));
+  if (source.text === null) return null;
+  const prefix = signatureReferencePrefix(source.text);
+  // At most two distinct objects are enough to detect ambiguity. Repeated
+  // bindings to identical bytes do not make selection ambiguous.
+  const rows = store.observe(`signature:${taskId}:${prefix}`, () => store.db.prepare(
+    "SELECT MIN(reference_id) AS reference_id, path, size, sha256 FROM attachment_references WHERE task_id = ? AND reference_id >= ? AND reference_id < ? GROUP BY path, size, sha256 ORDER BY path LIMIT 2",
+  ).all(taskId, prefix, `${prefix}~`));
+  const paths = new Set(rows.map(row => validateAttachmentReference({ taskId, referenceId: row.reference_id, path: row.path, size: row.size, sha256: row.sha256 }).path));
+  for (const reference of store.attachments.values()) {
+    if (reference.taskId === taskId && reference.referenceId.startsWith(prefix)) paths.add(validateAttachmentReference(reference).path);
+  }
+  if (paths.size > 1) {
+    throw Object.assign(new Error("Multiple signature bundles bind this statement; supply an explicit bundle path"), { code: "E_ATTESTATION_SIGNATURE_INVALID" });
+  }
+  return paths.values().next().value ?? null;
+}
+
+/** Preserve legacy logical references while locating external SQLite assets. */
+export function resolveAttestationBundlePath(target, taskId, suppliedPath = null) {
+  const legacy = taskAttestationBundlePath(taskId);
+  const store = getOperationalStore(target);
+  if (store && suppliedPath) {
+    const referenceId = legacyAttachmentReferenceId(suppliedPath);
+    const row = store.observe(`attachment-alias:${JSON.stringify([taskId, referenceId])}`, () => store.db.prepare(
+      "SELECT * FROM attachment_references WHERE task_id = ? AND reference_id = ?",
+    ).get(taskId, referenceId) ?? null);
+    const staged = store.attachments.get(JSON.stringify([taskId, referenceId]));
+    const reference = staged ?? (row ? { taskId: row.task_id, referenceId: row.reference_id, path: row.path, size: row.size, sha256: row.sha256 } : null);
+    if (reference) return validateAttachmentReference(reference).path;
+  }
+  if (store && (!suppliedPath || suppliedPath === legacy)) {
+    const canonical = resolveCanonicalSignature(target, taskId, store);
+    if (canonical) return canonical;
+    return `.forgeloop/attachments/${taskStorageKey(taskId)}/attestations/statement.sigstore.json`;
+  }
+  return suppliedPath ?? legacy;
+}

package/src/core/attestation-coverage.js

@@ -6,6 +6,7 @@ import { resolveRevisionProvider } from "./revision/provider.js";
 import { REVISION_PROVIDERS } from "./revision/registry.js";
 import { assertAttestationStatementBindings, verifyCodeManifestContent } from "./attestation-verifier.js";
 import { taskAttestationBundlePath } from "./task-paths.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 
 function pathMatchesExclusion(pathValue, exclusions) {
   return exclusions.some((pattern) => {
@@ -24,7 +25,11 @@ function isProtocolMetadataPath(value) {
   return normalized === ".forgeloop" || normalized.startsWith(".forgeloop/");
 }
 
-export async function evaluateAttestationCoverage({
+export async function evaluateAttestationCoverage(options = {}) {
+  return withProjectReadSnapshot(options.target, () => evaluateSelectedAttestationCoverage(options));
+}
+
+async function evaluateSelectedAttestationCoverage({
   target,
   packageRoot = getPackageRoot(),
   revisionProvider = "git",