@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.2

package/src/storage/schema.js

@@ -0,0 +1,214 @@
+/**
+ * ForgeLoop SQLite storage schema.
+ *
+ * This module owns DDL and schema versioning only. It performs no I/O against a
+ * project and holds no connection state, so schema definitions can be imported
+ * from tooling that must stay independent of the live store.
+ *
+ * Design constraints (see the SQLite migration plan):
+ *   - Indexed relational fields carry identity, ordering, and lookup paths.
+ *   - Nested protocol structures stay as schema-validated canonical JSON
+ *     payloads instead of being normalized table by table.
+ *   - Extracted columns and payloads are written in one storage operation and
+ *     are never updated independently.
+ *   - Foreign keys cover only relationships that are mandatory in the actual
+ *     protocol. Audit history never cascades away from an explicit request.
+ */
+
+/** Shared verbatim so the partial index and reservation query have one predicate.
+ * This index only identifies histories requiring conservative retention proof;
+ * mutation authority still requires the complete canonical ledger validation.
+ */
+export const EVENT_RESERVATION_PROOF_PREDICATE = `CASE WHEN json_valid(event_json) = 0 THEN 1
+        ELSE json_type(event_json) <> 'object'
+          OR json_extract(event_json, '$.taskId') IS NOT task_id
+          OR json_extract(event_json, '$.seq') IS NOT seq
+          OR json_extract(event_json, '$.hash') IS NOT hash
+          OR json_extract(event_json, '$.previousHash') IS NOT previous_hash
+          OR json_extract(event_json, '$.at') IS NOT at
+          OR json_extract(event_json, '$.event') IS NOT event_type
+          OR json_extract(event_json, '$.event') IN
+            ('CONTRACT_BOOTSTRAP_REPAIR_RECORDED', 'CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_RECORDED')
+        END`;
+
+/** Bumped whenever required DDL changes incompatibly. */
+export const STORAGE_SCHEMA_VERSION = 5;
+
+/** Storage format marker recorded in `storage_meta` for cutover detection. */
+export const STORAGE_FORMAT = "sqlite";
+export const STORAGE_FORMAT_VERSION = 1;
+export const STORAGE_RELATIVE_PATH = ".forgeloop/state.sqlite";
+
+/**
+ * Declarative migration list. Each entry is applied exactly once, in order, and
+ * recorded in `storage_meta` so an existing database upgrades in place.
+ */
+export const SCHEMA_MIGRATIONS = Object.freeze([
+  Object.freeze({
+    version: 1,
+    name: "initial-operational-store",
+    statements: Object.freeze([
+      // Singleton row describing this store. `id` is pinned to 1 so a second
+      // writer cannot silently create a competing metadata row.
+      `CREATE TABLE storage_meta (
+         id INTEGER PRIMARY KEY CHECK (id = 1),
+         storage_version INTEGER NOT NULL,
+         schema_version INTEGER NOT NULL,
+         protocol_version INTEGER,
+         project_identity TEXT,
+         storage_format TEXT NOT NULL DEFAULT '${STORAGE_FORMAT}',
+         created_at TEXT NOT NULL,
+         updated_at TEXT NOT NULL,
+         import_provenance TEXT
+       )`,
+
+      // Task identity plus the two canonical snapshots that discovery reads.
+      // `descriptor_json` and `state_json` are retained verbatim so the store
+      // never becomes a lossy re-encoding of protocol state.
+      `CREATE TABLE tasks (
+         task_id TEXT PRIMARY KEY,
+         task_key TEXT NOT NULL UNIQUE,
+         phase TEXT,
+         revision INTEGER,
+         created_at TEXT,
+         updated_at TEXT,
+         descriptor_json TEXT NOT NULL,
+         state_json TEXT
+       )`,
+      `CREATE INDEX tasks_phase_updated_idx ON tasks (phase, updated_at)`,
+
+      // Normalized write claims. Directory, wildcard, and ancestor/descendant
+      // overlap cannot be expressed as exact-path uniqueness, so callers must
+      // still evaluate `claimsOverlap()` over the candidate rows returned here.
+      `CREATE TABLE claims (
+         task_id TEXT NOT NULL REFERENCES tasks (task_id) ON DELETE CASCADE,
+         claim_norm TEXT NOT NULL,
+         reservation_state TEXT NOT NULL DEFAULT 'ACTIVE',
+         created_at TEXT,
+         PRIMARY KEY (task_id, claim_norm)
+       )`,
+      `CREATE INDEX claims_norm_idx ON claims (claim_norm)`,
+
+      // Canonical ledger. `event_json` stores the original event object exactly
+      // as imported: historical events are never rehashed or rewritten.
+      `CREATE TABLE events (
+         task_id TEXT NOT NULL REFERENCES tasks (task_id) ON DELETE CASCADE,
+         seq INTEGER NOT NULL,
+         event_type TEXT NOT NULL,
+         at TEXT,
+         previous_hash TEXT,
+         hash TEXT NOT NULL,
+         event_json TEXT NOT NULL,
+         PRIMARY KEY (task_id, seq)
+       )`,
+      `CREATE INDEX events_type_idx ON events (task_id, event_type, seq)`,
+
+      // Task-local idempotency is enforced by the database rather than by a
+      // directory scan, so a duplicate key cannot create two accepted actions.
+      `CREATE TABLE actions (
+         task_id TEXT NOT NULL REFERENCES tasks (task_id) ON DELETE CASCADE,
+         action_id TEXT NOT NULL,
+         idempotency_key TEXT,
+         status TEXT,
+         revision INTEGER,
+         payload_json TEXT NOT NULL,
+         PRIMARY KEY (task_id, action_id)
+       )`,
+      `CREATE UNIQUE INDEX actions_idempotency_idx ON actions (task_id, idempotency_key) WHERE idempotency_key IS NOT NULL`,
+      `CREATE INDEX actions_status_idx ON actions (task_id, status)`,
+
+      `CREATE TABLE approvals (
+         task_id TEXT NOT NULL REFERENCES tasks (task_id) ON DELETE CASCADE,
+         approval_id TEXT NOT NULL,
+         action_id TEXT,
+         decision TEXT,
+         payload_json TEXT NOT NULL,
+         PRIMARY KEY (task_id, approval_id)
+       )`,
+      `CREATE INDEX approvals_action_idx ON approvals (task_id, action_id)`,
+
+      `CREATE TABLE executions (
+         task_id TEXT NOT NULL REFERENCES tasks (task_id) ON DELETE CASCADE,
+         execution_id TEXT NOT NULL,
+         check_id TEXT,
+         verification_cycle INTEGER,
+         payload_json TEXT NOT NULL,
+         PRIMARY KEY (task_id, execution_id)
+       )`,
+      `CREATE INDEX executions_check_idx ON executions (task_id, check_id, verification_cycle)`,
+
+      // Generic typed artifact store. Replaceable current snapshots use a
+      // fixed artifact_id; immutable history uses distinct IDs. Optional
+      // artifacts stay absent until created rather than being pre-seeded.
+      `CREATE TABLE task_artifacts (
+         task_id TEXT NOT NULL REFERENCES tasks (task_id) ON DELETE CASCADE,
+         kind TEXT NOT NULL,
+         artifact_id TEXT NOT NULL,
+         payload_json TEXT NOT NULL,
+         fingerprint TEXT NOT NULL,
+         PRIMARY KEY (task_id, kind, artifact_id)
+       )`,
+      `CREATE INDEX task_artifacts_kind_idx ON task_artifacts (kind)`,
+
+      // Session activation markers. Kept optional so a project can adopt the
+      // store before every session reader is migrated.
+      `CREATE TABLE sessions (
+         session_id TEXT PRIMARY KEY,
+         task_id TEXT REFERENCES tasks (task_id) ON DELETE SET NULL,
+         activation_json TEXT NOT NULL
+       )`,
+      `CREATE INDEX sessions_task_idx ON sessions (task_id)`,
+    ]),
+  }),
+  Object.freeze({
+    version: 2,
+    name: "artifact-byte-evidence",
+    statements: Object.freeze([
+      "ALTER TABLE task_artifacts ADD COLUMN source_json TEXT",
+      "ALTER TABLE task_artifacts ADD COLUMN byte_digest TEXT",
+    ]),
+  }),
+  Object.freeze({
+    version: 3,
+    name: "canonical-activation-selection",
+    statements: Object.freeze([
+      "ALTER TABLE storage_meta ADD COLUMN active_session_id TEXT REFERENCES sessions(session_id)",
+    ]),
+  }),
+  Object.freeze({
+    version: 4,
+    name: "execution-reference-lookup",
+    statements: Object.freeze([
+      "CREATE INDEX executions_reference_idx ON executions (execution_id, task_id)",
+    ]),
+  }),
+  Object.freeze({
+    version: 5,
+    name: "immutable-attachment-references",
+    statements: Object.freeze([
+      `CREATE TABLE attachment_references (
+        task_id TEXT NOT NULL REFERENCES tasks(task_id),
+        reference_id TEXT NOT NULL,
+        path TEXT NOT NULL,
+        size INTEGER NOT NULL CHECK(size >= 0),
+        sha256 TEXT NOT NULL CHECK(length(sha256) = 64),
+        PRIMARY KEY(task_id, reference_id)
+      )`,
+      "CREATE INDEX attachment_references_path_idx ON attachment_references(path)",
+    ]),
+  }),
+
+]);
+
+/** All DDL required to build a current store from empty, in order. */
+export const SCHEMA_STATEMENTS = Object.freeze(
+  SCHEMA_MIGRATIONS.flatMap((migration) => [...migration.statements]),
+);
+
+/** Additive performance indexes: their absence cannot change domain outcomes.
+ * Writable admission installs them without changing the marker-bound format.
+ */
+export const OPTIONAL_STORAGE_INDEXES = Object.freeze([Object.freeze({
+  name: "events_reservation_proof_idx",
+  statement: `CREATE INDEX IF NOT EXISTS events_reservation_proof_idx ON events(task_id) WHERE ${EVENT_RESERVATION_PROOF_PREDICATE}`,
+})]);

package/src/storage/singleton-import.js

@@ -0,0 +1,84 @@
+import { readFile, readdir } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { assertSafePath, fileExists } from "../core/filesystem.js";
+import { LEGACY_TASK_ARTIFACT_PATHS as paths, taskArtifactPath } from "../core/task-paths.js";
+import { assertTaskId, taskStorageKey } from "../core/task-identity.js";
+import { createTaskDescriptor } from "../core/task-descriptor.js";
+import { readPortableJsonArtifact, canonicalFingerprint } from "../core/artifacts.js";
+import { validateMigrationSnapshot } from "../core/task-migration-validation.js";
+import { readPortableEvents } from "../core/events.js";
+import { getPackageRoot } from "../core/templates.js";
+import { upsertTask, appendEvent, putArtifact, putExecution } from "./repository.js";
+
+const artifacts = Object.freeze([
+  ["contract", "current-contract"], ["route", "routing-result"],
+  ["preflight", "preflight"], ["state", "work-state"],
+  ["continuity", "continuity"], ["receipt", "execution-receipt"],
+]);
+
+/** Read-only singleton conversion input. No temporary writable namespace. */
+export async function readSingletonImportSource(target, packageRoot = getPackageRoot()) {
+  const payloads = new Map();
+  let taskId = null;
+  for (const [kind, schema] of artifacts) {
+    if (!(await fileExists(await assertSafePath(target, paths[kind])))) continue;
+    const { value } = await readPortableJsonArtifact(target, paths[kind], schema, packageRoot);
+    if (value.taskId) {
+      if (taskId !== null && taskId !== value.taskId) throw Object.assign(new Error("Singleton artifact identities disagree"), { code: "E_TASK_MIGRATION_IDENTITY_MISMATCH" });
+      taskId = value.taskId;
+    }
+    payloads.set(kind, { payload: value, sourceText: await readFile(await assertSafePath(target, paths[kind]), "utf8") });
+  }
+  assertTaskId(taskId);
+  const snapshot = await validateMigrationSnapshot(target, { taskId, packageRoot, paths });
+  for (const [kind, value] of payloads) {
+    if (createHash("sha256").update(value.sourceText).digest("hex") !== snapshot.artifactFingerprints[kind]
+      || canonicalFingerprint(JSON.parse(value.sourceText)) !== canonicalFingerprint(value.payload)) {
+      throw Object.assign(new Error("Singleton artifact changed during conversion read"), { code: "E_STORAGE_MIGRATION_SOURCE_CHANGED" });
+    }
+  }
+  const events = await readPortableEvents(target, packageRoot, { eventsPath: paths.events });
+  const directories = {};
+  for (const [kind, schema] of [["gates", "gate"], ["executions", "execution"]]) {
+    directories[kind] = [];
+    const directory = await assertSafePath(target, paths[kind]);
+    if (!(await fileExists(directory))) continue;
+    for (const filename of (await readdir(directory)).sort()) {
+      const relative = `${paths[kind]}/${filename}`;
+      const { value } = await readPortableJsonArtifact(target, relative, schema, packageRoot);
+      const id = filename.slice(0, -5);
+      if ((kind === "gates" ? value.gate : value.executionId) !== id) throw Object.assign(new Error(`Singleton directory artifact identity disagrees with filename: ${relative}`), { code: "E_STORAGE_PAYLOAD_MISMATCH" });
+      directories[kind].push({ id, payload: value, sourceText: await readFile(await assertSafePath(target, relative), "utf8") });
+    }
+  }
+  const after = await validateMigrationSnapshot(target, { taskId, packageRoot, paths });
+  if (canonicalFingerprint(snapshot) !== canonicalFingerprint(after)) throw Object.assign(new Error("Singleton source changed during conversion read"), { code: "E_STORAGE_MIGRATION_SOURCE_CHANGED" });
+  return { taskId, taskKey: taskStorageKey(taskId), payloads, events, directories, snapshot };
+}
+
+/** Caller must own an unpublished SQLite import transaction. */
+export function importSingletonSource(db, source) {
+  if (!db.isTransaction) throw Object.assign(new Error("Singleton import requires an enclosing transaction"), { code: "E_STORAGE_TRANSACTION_INVALID" });
+  const { taskId, taskKey, payloads, events, directories } = source;
+  if (db.prepare("SELECT task_id FROM tasks WHERE task_id = ? OR task_key = ?").get(taskId, taskKey)) throw Object.assign(new Error("Singleton conversion collides with an existing task namespace"), { code: "E_STORAGE_IMPORT_IDENTITY_COLLISION" });
+  const createdAt = payloads.get("state")?.payload.createdAt ?? payloads.get("contract")?.payload.createdAt ?? events[0]?.at ?? "1970-01-01T00:00:00.000Z";
+  const descriptor = createTaskDescriptor({ taskId, writeClaims: [], createdAt, updatedAt: createdAt });
+  upsertTask(db, { taskId, taskKey, descriptor, state: payloads.get("state")?.payload ?? null });
+  for (const event of events) appendEvent(db, { taskId, event });
+  for (const [kind, value] of payloads) {
+    if (kind !== "state") putArtifact(db, { taskId, kind, ...value });
+  }
+  for (const gate of directories.gates) putArtifact(db, { taskId, kind: "gate", artifactId: gate.id, payload: gate.payload, sourceText: gate.sourceText });
+  for (const execution of directories.executions) putExecution(db, { taskId, execution: execution.payload });
+  return { taskId, taskKey, events: events.length, stateFingerprint: payloads.has("state") ? canonicalFingerprint(payloads.get("state").payload) : null };
+}
+
+/** Exact source-to-portable-export mapping; unrelated roots keep their paths. */
+export function singletonExportPath(taskId, relativePath) {
+  for (const [kind, sourcePath] of Object.entries(paths)) {
+    if (kind === "session") continue;
+    if (relativePath === sourcePath) return taskArtifactPath(taskId, kind);
+    if (["gates", "executions"].includes(kind) && relativePath.startsWith(`${sourcePath}/`)) return `${taskArtifactPath(taskId, kind)}/${relativePath.slice(sourcePath.length + 1)}`;
+  }
+  return relativePath;
+}

package/src/storage/snapshot-continuity.js

@@ -0,0 +1,16 @@
+/** Preserve retained identities/history while permitting valid later mutations. */
+export function assertSnapshotContinuity(original, current, invalid) {
+  const task = current.prepare("SELECT task_key FROM tasks WHERE task_id = ?");
+  for (const row of original.prepare("SELECT task_id, task_key FROM tasks").iterate()) {
+    if (task.get(row.task_id)?.task_key !== row.task_key) throw invalid("A retained task identity was lost or substituted");
+  }
+  const event = current.prepare("SELECT event_json FROM events WHERE task_id = ? AND seq = ?");
+  for (const row of original.prepare("SELECT task_id, seq, event_json FROM events ORDER BY task_id, seq").iterate()) {
+    if (event.get(row.task_id, row.seq)?.event_json !== row.event_json) throw invalid("Retained canonical event history was lost or changed");
+  }
+  const binding = current.prepare("SELECT path, size, sha256 FROM attachment_references WHERE task_id = ? AND reference_id = ?");
+  for (const row of original.prepare("SELECT * FROM attachment_references ORDER BY task_id, reference_id").iterate()) {
+    const retained = binding.get(row.task_id, row.reference_id);
+    if (!retained || retained.path !== row.path || retained.size !== row.size || retained.sha256 !== row.sha256) throw invalid("A retained attachment binding was lost or changed");
+  }
+}

package/src/storage/snapshot.js

@@ -0,0 +1,36 @@
+import { loadStorageDriver } from "./runtime.js";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const ownedSnapshots = new WeakSet();
+/** Only copies admitted here are immutable; callers cannot register live handles. */
+export function isOwnedStorageSnapshot(db) { return ownedSnapshots.has(db); }
+// Copy a committed snapshot in one native backup step. Smaller batches restart
+// after writes from other connections and can starve readers under sustained work.
+// This is a page-step limit, not an allocation or a JavaScript buffer size.
+const SNAPSHOT_BACKUP_BATCH_PAGES = 0x7fffffff;
+
+/** Isolate portable reads from live writers without holding a reader during I/O. */
+export async function withStorageSnapshot(db, readSnapshot) {
+  const { backup, DatabaseSync } = loadStorageDriver();
+  if (db.isTransaction) {
+    const error = new Error("Export requires a committed storage snapshot");
+    error.code = "E_STORAGE_SNAPSHOT_TRANSACTION";
+    throw error;
+  }
+  // Only live read-only copies created here can be reused; callers cannot opt in.
+  if (ownedSnapshots.has(db)) return readSnapshot(db);
+  const directory = await mkdtemp(path.join(os.tmpdir(), "forgeloop-snapshot-"));
+  let snapshot;
+  try {
+    const filename = path.join(directory, "state.sqlite");
+    await backup(db, filename, { rate: SNAPSHOT_BACKUP_BATCH_PAGES });
+    snapshot = new DatabaseSync(filename, { readOnly: true, enableForeignKeyConstraints: true });
+    ownedSnapshots.add(snapshot);
+    return await readSnapshot(snapshot);
+  } finally {
+    if (snapshot) ownedSnapshots.delete(snapshot);
+    try { snapshot?.close(); } finally { await rm(directory, { recursive: true, force: true }); }
+  }
+}

package/src/storage/storage-marker.js

@@ -0,0 +1,79 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { assertSafePath, assertRegularProjectFileIdentity, isPathWithin, realpathWithTransientWindowsRetry, writeFileAtomic } from "../core/filesystem.js";
+import { assertOwnedStorageMaintenance } from "./maintenance.js";
+
+const MARKER = ".forgeloop/storage-version.json";
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_VERSION_MARKER_INVALID" }); }
+
+export function validateStorageVersionMarker(value) {
+  if (!value || value.schemaVersion !== 1 || value.storageFormat !== "sqlite" || value.storageVersion !== 1
+    || !Number.isSafeInteger(value.databaseSchemaVersion) || value.databaseSchemaVersion < 1
+    || !["CUTOVER_PENDING", "ACTIVE"].includes(value.phase)
+    || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value.operationId ?? "")
+    || !/^[a-f0-9]{64}$/.test(value.sourceInventoryFingerprint ?? "")) throw invalid("Storage marker is incomplete or unsupported");
+  return value;
+}
+
+export async function readStorageVersionMarker(target) {
+  const filename = await assertSafePath(target, MARKER);
+  const root = await realpathWithTransientWindowsRetry(target);
+  let bytes;
+  try {
+    const observed = await lstat(filename, { bigint: true });
+    if (!observed.isFile()) throw invalid("Storage marker must be a regular file");
+    if (!isPathWithin(root, await realpathWithTransientWindowsRetry(filename))) throw invalid("Storage marker resolves outside the project");
+    let file;
+    try { file = await open(filename, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)); }
+    catch (error) { if (error.code === "ELOOP") throw invalid("Storage marker must be a regular file"); throw error; }
+    try {
+      const actual = await assertRegularProjectFileIdentity(file, filename, observed, root,
+        () => invalid("Storage marker must retain its admitted file identity"));
+      if (actual.size > 65536n) throw invalid("Storage marker exceeds its byte limit");
+      const buffer = Buffer.alloc(65537);
+      let count = 0;
+      while (count < buffer.length) {
+        const { bytesRead } = await file.read(buffer, count, buffer.length - count, count);
+        if (bytesRead === 0) break;
+        count += bytesRead;
+      }
+      bytes = buffer.subarray(0, count);
+    } finally { await file.close(); }
+  } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  if (bytes.length > 65536 || !Buffer.from(bytes.toString("utf8")).equals(bytes)) throw invalid("Storage marker encoding or size is invalid");
+  let value;
+  try { value = JSON.parse(bytes.toString("utf8")); } catch { throw invalid("Storage marker is not valid JSON"); }
+  return validateStorageVersionMarker(value);
+}
+
+/** Exclusive pending marker; activation must be a separately validated step. */
+export async function writePendingStorageVersionMarker(target, marker) {
+  await assertOwnedStorageMaintenance(target);
+  const filename = await assertSafePath(target, MARKER);
+  const expected = validateStorageVersionMarker({ schemaVersion: 1, storageFormat: "sqlite", storageVersion: 1, phase: "CUTOVER_PENDING",
+    databaseSchemaVersion: marker.databaseSchemaVersion, operationId: marker.operationId, sourceInventoryFingerprint: marker.sourceInventoryFingerprint });
+  const existing = await readStorageVersionMarker(target);
+  if (existing) {
+    if (JSON.stringify(existing) !== JSON.stringify(expected)) throw invalid("Existing storage marker differs from this cutover operation");
+    return existing;
+  }
+  const file = await open(filename, "wx", 0o600);
+  try { await file.writeFile(`${JSON.stringify(expected)}\n`); await file.sync(); } finally { await file.close(); }
+  try {
+    const directory = await open(await assertSafePath(target, ".forgeloop"), "r");
+    try { await directory.sync(); } finally { await directory.close(); }
+  } catch (error) { if (!["EINVAL", "EPERM", "EISDIR", "ENOTSUP", "UNKNOWN"].includes(error.code)) throw error; }
+  return readStorageVersionMarker(target);
+}
+
+/** Called only after the cutover service validates its published database. */
+export async function activateStorageVersionMarker(target, expected) {
+  await assertOwnedStorageMaintenance(target);
+  const current = await readStorageVersionMarker(target);
+  if (!current || current.phase !== "CUTOVER_PENDING" || current.operationId !== expected.operationId
+    || current.sourceInventoryFingerprint !== expected.sourceInventoryFingerprint
+    || current.databaseSchemaVersion !== expected.databaseSchemaVersion) throw invalid("Pending marker does not belong to this validated activation");
+  const active = { ...current, phase: "ACTIVE" };
+  await writeFileAtomic(await assertSafePath(target, MARKER), `${JSON.stringify(active)}\n`);
+  return active;
+}

package/src/storage/task-guards.js

@@ -0,0 +1,107 @@
+/**
+ * Store-backed operational guards for the SQLite integration slice.
+ *
+ * Claim and reservation projections read the same operational records that
+ * native mutations use, so authority decisions are derived from one state
+ * history rather than a second compatibility adapter.
+ */
+import { buildTaskClaimEvidence, classifyTaskClaimState } from "../core/task-claim-state.js";
+import { resolveEffectiveContractBootstrapRepairAnchor } from "../core/contract-bootstrap-recovery.js";
+import { validateLedgerEvents } from "../core/events.js";
+import { listArtifacts } from "./repository.js";
+
+import { withLedgerEventSnapshot } from "./ledger-event-snapshot.js";
+import { EVENT_RESERVATION_PROOF_PREDICATE } from "./schema.js";
+
+const ERROR_CODES = Object.freeze({
+  TASK_NOT_FOUND: "E_TASK_NOT_FOUND",
+});
+
+function guardError(code, message, extra = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, extra);
+  return error;
+}
+
+function readTask(db, taskId) {
+  const row = db
+    .prepare("SELECT task_id, task_key, phase, revision, created_at, updated_at, descriptor_json, state_json FROM tasks WHERE task_id = ?")
+    .get(taskId);
+  if (!row) return null;
+  return {
+    taskId: row.task_id,
+    taskKey: row.task_key,
+    phase: row.phase,
+    revision: row.revision,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    descriptor: JSON.parse(row.descriptor_json),
+    state: row.state_json === null ? null : JSON.parse(row.state_json),
+  };
+}
+
+/**
+ * Classify operational claim state from store records.
+ *
+ * Mirrors the filesystem classification order: completion release, then active
+ * recovery release, then active. Released claims are never treated as mutation
+ * authority, and a task with no recorded claim evidence is inconsistent rather
+ * than automatically permitted.
+ */
+export function resolveStoreClaimState(db, taskId) {
+  return withLedgerEventSnapshot(db, taskId, (events) => classifyStoreClaimSnapshot(db, taskId, events));
+}
+
+function classifyStoreClaimSnapshot(db, taskId, events) {
+  const task = readTask(db, taskId);
+  if (!task) {
+    throw guardError(ERROR_CODES.TASK_NOT_FOUND, `Task "${taskId}" not found in project`, { taskId });
+  }
+
+  const ledger = validateLedgerEvents(events);
+  const recovery = listArtifacts(db, taskId, "recovery").at(-1)?.payload ?? null;
+  const repairAnchor = resolveEffectiveContractBootstrapRepairAnchor(events);
+  let repairArtifacts = null;
+  if (repairAnchor) {
+    const contract = listArtifacts(db, taskId, "contract").at(-1);
+    const route = listArtifacts(db, taskId, "route").at(-1);
+    const details = repairAnchor.details;
+    repairArtifacts = {
+      contract: contract ? { value: contract.payload, fingerprint: contract.fingerprint } : null,
+      route: route ? { value: route.payload, fingerprint: route.fingerprint } : null,
+      contractError: !contract ? "contract artifact is missing after a recorded repair"
+        : contract.fingerprint !== details.contractFingerprint ? "contract fingerprint does not match marker contract fingerprint"
+          : task.state?.contractFingerprint !== details.contractFingerprint ? "work-state contract fingerprint does not match marker contract fingerprint" : null,
+      routeError: route?.payload?.contractFingerprint !== undefined && route.payload.contractFingerprint !== details.contractFingerprint
+        ? "route artifact contract binding does not match repair anchor contract fingerprint" : null,
+    };
+  }
+  const initialErrors = [];
+  if (task.state && (task.phase !== task.state.phase || task.revision !== (task.state.revision ?? 0)
+    || task.state.taskId !== taskId) || task.descriptor.taskId !== taskId || task.descriptor.taskKey !== task.taskKey) {
+    initialErrors.push({ code: "E_TASK_CLAIM_OWNERSHIP_INCONSISTENT", causeCode: "E_STORAGE_PAYLOAD_MISMATCH", message: "Stored identity/phase/revision columns disagree with canonical task payloads" });
+  }
+  return classifyTaskClaimState(buildTaskClaimEvidence({ taskId, descriptor: task.descriptor, state: task.state, recovery, ledger, repairArtifacts, initialErrors }));
+}
+
+/** Reservation projection only: ACTIVE never grants mutation authority. */
+export function resolveStoreReservationState(db, taskId) {
+  const task = readTask(db, taskId);
+  if (!task) throw guardError(ERROR_CODES.TASK_NOT_FOUND, `Task "${taskId}" not found in project`, { taskId });
+  const recovery = db.prepare("SELECT 1 FROM task_artifacts WHERE task_id = ? AND kind = 'recovery' LIMIT 1").get(taskId);
+  if (task.state?.phase !== "COMPLETE" && !recovery) {
+    // Full classification cannot release a non-completed task without a
+    // recovery artifact. Invalid history also retains claims. Preserve the
+    // previous decoder/error path for malformed/non-object historical rows
+    // and repair histories that may inspect contract/route artifacts. Read the
+    // canonical payload, not the editable event_type index. This bounded SQL
+    // scan is not a ledger or ownership validation result.
+    const requiresFullProof = db.prepare(`SELECT 1 FROM events WHERE task_id = ?
+      AND ${EVENT_RESERVATION_PROOF_PREDICATE} LIMIT 1`).get(taskId);
+    if (!requiresFullProof) return "ACTIVE";
+  }
+  const projection = resolveStoreClaimState(db, taskId);
+  return projection.valid && projection.effectiveWriteClaims.length === 0 && projection.claimState !== "ACTIVE"
+    ? "RELEASED" : "ACTIVE";
+}

package/src/storage/topology.js

@@ -0,0 +1,42 @@
+import { statfsSync } from "node:fs";
+import path from "node:path";
+
+// Linux UAPI magic.h identifies these network/shared filesystems. This is a
+// deny-list of known unsupported topology, not certification of every other FS.
+const NETWORK_TYPES = new Map([
+  [0x6969n, "NFS"], [0x517bn, "SMB"], [0xff534d42n, "CIFS"], [0xfe534d42n, "SMB2"],
+  [0x5346414fn, "AFS"], [0x6b414653n, "AFS"], [0x73757245n, "Coda"],
+  [0x00c36400n, "Ceph"], [0x01021997n, "9P"],
+]);
+
+function unsupported(kind) {
+  return Object.assign(new Error(`SQLite WAL storage requires a supported local filesystem; ${kind} topology is unsupported`), { code: "E_STORAGE_TOPOLOGY_UNSUPPORTED" });
+}
+
+export function assertStorageTopologyName(databasePath, platform, filesystemType = null) {
+  const filename = String(databasePath).replaceAll("\\", "/");
+  if (platform === "win32" && (/^\/\/[^?./]/.test(filename) || /^\/\/[?.]\/UNC\//i.test(filename))) throw unsupported("UNC network share");
+  if (platform === "linux" && filesystemType !== null) {
+    const kind = NETWORK_TYPES.get(BigInt.asUintN(32, BigInt(filesystemType)));
+    if (kind) throw unsupported(kind);
+  }
+}
+
+/** Inspect an existing ancestor before SQLite creates a database or sidecars. */
+export function assertStorageTopology(databasePath) {
+  assertStorageTopologyName(databasePath, process.platform);
+  if (databasePath === ":memory:" || process.platform !== "linux") return;
+  let candidate = path.resolve(databasePath);
+  for (;;) {
+    try {
+      const filesystem = statfsSync(candidate, { bigint: true });
+      assertStorageTopologyName(databasePath, process.platform, filesystem.type);
+      return;
+    } catch (error) {
+      if (error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error;
+      const parent = path.dirname(candidate);
+      if (parent === candidate) throw error;
+      candidate = parent;
+    }
+  }
+}