@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.4

package/src/storage/ledger-event-snapshot.js

@@ -0,0 +1,150 @@
+import { LedgerEventCollection } from "../core/ledger-event-collection.js";
+import { decodeIndexedEvent } from "./repository.js";
+import { runInTransaction } from "./transaction.js";
+import { withStorageSnapshot } from "./snapshot.js";
+import { withSpilledLedgerRelations, withSpilledLedgerRelationsSync } from "./ledger-relations.js";
+import { createHash } from "node:crypto";
+import { canonicalFingerprint } from "../core/artifacts.js";
+
+const typedStatements = new WeakMap();
+const activeTypedStatements = new WeakSet();
+
+function* iterateTypedRows(db, query, arity, parameters) {
+  let statements = typedStatements.get(db);
+  if (!statements) { statements = new Map(); typedStatements.set(db, statements); }
+  let statement = statements.get(arity);
+  // A nested scan cannot rebind the statement backing its still-active outer cursor.
+  if (!statement || activeTypedStatements.has(statement)) {
+    statement = db.prepare(query);
+    if (!statements.has(arity) && statements.size < 16) statements.set(arity, statement);
+  }
+  activeTypedStatements.add(statement);
+  try { yield* statement.iterate(...parameters); }
+  finally { activeTypedStatements.delete(statement); }
+}
+
+function ownCollection(db, taskId, { validate = event => event, onFullScan = null, guard = null } = {}) {
+  let active = true;
+  let indexedFieldsValidated = false;
+  const assertActive = () => {
+    if (!active) throw Object.assign(new Error("Ledger snapshot has expired"), { code: "E_STORAGE_TRANSACTION_EXPIRED" });
+  };
+  const { count, first, last } = db.prepare("SELECT COUNT(*) AS count, MIN(seq) AS first, MAX(seq) AS last FROM events WHERE task_id = ?").get(taskId);
+  // Contiguity only selects an access path. Every decoded payload still proves its indexed fields.
+  const contiguous = count === 0 || (first === 1 && last === count);
+  const at = db.prepare(contiguous
+    ? "SELECT * FROM events WHERE task_id = ? AND seq = ?"
+    : "SELECT * FROM events WHERE task_id = ? ORDER BY seq LIMIT 1 OFFSET ?");
+  const rangeSql = contiguous
+    ? "SELECT * FROM events WHERE task_id = ? AND seq > ? AND seq <= ? ORDER BY seq"
+    : "SELECT * FROM events WHERE task_id = ? ORDER BY seq LIMIT ? OFFSET ?";
+  const decode = (row, index) => {
+    const event = decodeIndexedEvent(row);
+    return indexedFieldsValidated ? event : validate(event, index);
+  };
+  const assertGuard = phase => {
+    if (typeof guard === "function") guard(events, phase);
+  };
+  const events = new LedgerEventCollection({
+    length: count,
+    readAt(index) {
+      assertActive();
+      assertGuard("start");
+      const event = decode(at.get(taskId, contiguous ? index + 1 : index), index);
+      assertGuard("end");
+      return event;
+    },
+    *iterateRange(start, end) {
+      assertActive();
+      assertGuard("start");
+      // Nested proof scans need independent statements; reusing one invalidates its outer cursor.
+      const range = end > start ? db.prepare(rangeSql) : null;
+      const rows = !range ? [] : contiguous ? range.iterate(taskId, start, end) : range.iterate(taskId, end - start, start);
+      const digest = onFullScan && !indexedFieldsValidated && start === 0 && end === count ? createHash("sha256") : null;
+      let index = start;
+      for (const row of rows) {
+        assertActive();
+        const event = decode(row, index++);
+        if (digest) digest.update(canonicalFingerprint(row));
+        assertGuard("before-yield");
+        yield event;
+        assertActive();
+        // A writer may run while the caller owns the yielded event. Recheck
+        // before fetching/decoding the next row and before completing a scan.
+        assertGuard("resume");
+      }
+      assertActive();
+      assertGuard("end");
+      if (start === 0 && end === count) {
+        if (digest) onFullScan(digest.digest("hex"));
+        assertGuard("after-full-scan");
+        indexedFieldsValidated = true;
+      }
+    },
+    *iterateTypes(start, end, types) {
+      assertActive();
+      assertGuard("start");
+      if (start === end) {
+        assertGuard("end");
+        return;
+      }
+      if (!contiguous || !indexedFieldsValidated) {
+        for (const [index, event] of events.slice(start, end).entries()) {
+          assertActive();
+          if (types.includes(event.event)) {
+            assertGuard("before-yield");
+            yield { index: start + index, event };
+            assertActive();
+            assertGuard("resume");
+          }
+          assertActive();
+        }
+        assertGuard("end");
+        return;
+      }
+      if (!types.length) {
+        assertGuard("end");
+        return;
+      }
+      const query = `SELECT * FROM events INDEXED BY events_type_idx WHERE task_id = ? AND seq > ? AND seq <= ? AND event_type IN (${types.map(() => "?").join(",")}) ORDER BY seq`;
+      for (const row of iterateTypedRows(db, query, types.length, [taskId, start, end, ...types])) {
+        assertActive();
+        const event = decode(row, row.seq - 1);
+        assertGuard("before-yield");
+        yield { index: row.seq - 1, event };
+        assertActive();
+        assertGuard("resume");
+      }
+      assertActive();
+      assertGuard("end");
+    },
+  });
+  return { events, close() { active = false; } };
+}
+
+/** Synchronous evidence reads share one SQLite snapshot, including caller transactions. */
+export function withLedgerEventSnapshot(db, taskId, callback) {
+  const read = () => {
+    const owner = ownCollection(db, taskId);
+    try {
+      const result = withSpilledLedgerRelationsSync(() => callback(owner.events));
+      if (result && typeof result.then === "function") {
+        throw Object.assign(new TypeError("Ledger snapshot callback must be synchronous"), { code: "E_STORAGE_ASYNC_TRANSACTION" });
+      }
+      return result;
+    } finally { owner.close(); }
+  };
+  if (callback.constructor?.name === "AsyncFunction") {
+    throw Object.assign(new TypeError("Ledger snapshot callback must be synchronous"), { code: "E_STORAGE_ASYNC_TRANSACTION" });
+  }
+  return db.isTransaction ? read() : runInTransaction(db, read, { immediate: false });
+}
+
+/** Async proof work uses an owned read-only backup, never a live WAL transaction. */
+export async function withDetachedLedgerSnapshot(db, taskId, callback, options = {}) {
+  return withStorageSnapshot(db, async snapshot => {
+    const owner = ownCollection(snapshot, taskId, options);
+    try { return await withSpilledLedgerRelations(() => callback(owner.events, snapshot)); }
+    finally { owner.close(); }
+  });
+}

package/src/storage/ledger-relations.js

@@ -0,0 +1,220 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { loadStorageDriver } from "./runtime.js";
+import { withLedgerRelationOwner } from "../core/ledger-relations.js";
+
+function relationError(message) {
+  return Object.assign(new Error(message), { code: "E_LEDGER_RELATION_INVALID" });
+}
+
+function keyText(key) {
+  if (typeof key !== "string" && !(typeof key === "number" && Number.isFinite(key))) {
+    throw relationError("Ledger relation keys must be strings or finite numbers");
+  }
+  return JSON.stringify(key);
+}
+
+/** Relation values are primitive metadata/source positions, never detached proof payloads. */
+function valueText(value) {
+  if (value !== undefined && value !== null && !["string", "number", "boolean"].includes(typeof value)) {
+    throw relationError("Ledger relations store primitive metadata only");
+  }
+  if (typeof value === "number" && !Number.isFinite(value)) throw relationError("Ledger relation numbers must be finite");
+  return JSON.stringify({ value });
+}
+
+class RelationMap {
+  #owner;
+  #id;
+  #resident = new Map();
+  #bytes = 0;
+  #position = 0;
+  #spilled = false;
+
+  constructor(owner, id) { this.#owner = owner; this.#id = id; }
+  get spilled() { return this.#spilled; }
+
+  #database() { this.#owner.assertActive(); return this.#owner.database(); }
+
+  #spill() {
+    for (const [key, value] of this.#resident) this.#write(key, value);
+    this.#resident.clear();
+    this.#bytes = 0;
+    this.#spilled = true;
+  }
+
+  #write(key, value) {
+    this.#database().prepare("INSERT INTO relations (relation_id, key_json, value_json, position) VALUES (?, ?, ?, ?) ON CONFLICT (relation_id, key_json) DO UPDATE SET value_json = excluded.value_json")
+      .run(this.#id, keyText(key), valueText(value), this.#position++);
+  }
+
+  get size() {
+    this.#owner.assertActive();
+    return this.#spilled ? this.#database().prepare("SELECT COUNT(*) AS count FROM relations WHERE relation_id = ?").get(this.#id).count : this.#resident.size;
+  }
+
+  has(key) {
+    this.#owner.assertActive();
+    return this.#spilled ? Boolean(this.#database().prepare("SELECT 1 FROM relations WHERE relation_id = ? AND key_json = ?").get(this.#id, keyText(key))) : this.#resident.has(key);
+  }
+
+  get(key) {
+    this.#owner.assertActive();
+    if (!this.#spilled) return this.#resident.get(key);
+    const row = this.#database().prepare("SELECT value_json FROM relations WHERE relation_id = ? AND key_json = ?").get(this.#id, keyText(key));
+    return row ? JSON.parse(row.value_json).value : undefined;
+  }
+
+  set(key, value) {
+    this.#owner.assertActive();
+    const bytes = Buffer.byteLength(keyText(key)) + Buffer.byteLength(valueText(value));
+    if (this.#spilled) { this.#write(key, value); return this; }
+    const prior = this.#resident.has(key) ? Buffer.byteLength(keyText(key)) + Buffer.byteLength(valueText(this.#resident.get(key))) : 0;
+    if (this.#resident.size >= 128 || this.#bytes - prior + bytes > 65_536) {
+      this.#spill();
+      this.#write(key, value);
+    } else {
+      this.#bytes += bytes - prior;
+      this.#resident.set(key, value);
+    }
+    return this;
+  }
+
+  delete(key) {
+    this.#owner.assertActive();
+    if (this.#spilled) return this.#database().prepare("DELETE FROM relations WHERE relation_id = ? AND key_json = ?").run(this.#id, keyText(key)).changes !== 0;
+    if (!this.#resident.has(key)) return false;
+    this.#bytes -= Buffer.byteLength(keyText(key)) + Buffer.byteLength(valueText(this.#resident.get(key)));
+    return this.#resident.delete(key);
+  }
+
+  *entries() {
+    this.#owner.assertActive();
+    if (!this.#spilled) {
+      for (const pair of this.#resident) {
+        this.#owner.assertActive();
+        yield pair;
+        this.#owner.assertActive();
+      }
+      return;
+    }
+    const rows = this.#database().prepare("SELECT key_json, value_json FROM relations WHERE relation_id = ? ORDER BY position").iterate(this.#id);
+    for (const row of rows) {
+      this.#owner.assertActive();
+      yield [JSON.parse(row.key_json), JSON.parse(row.value_json).value];
+      this.#owner.assertActive();
+    }
+    this.#owner.assertActive();
+  }
+
+  [Symbol.iterator]() { return this.entries(); }
+}
+
+class GroupedRelationSet {
+  #owner;
+  #id;
+  #resident = new Map();
+  #bytes = 0;
+  #spilled = false;
+  constructor(owner, id) { this.#owner = owner; this.#id = id; }
+  #write(group, value) {
+    this.#owner.database().prepare("INSERT OR IGNORE INTO grouped_relations (relation_id, group_json, member_json) VALUES (?, ?, ?)")
+      .run(this.#id, keyText(group), keyText(value));
+  }
+  add(group, value) {
+    this.#owner.assertActive();
+    const groupJson = keyText(group);
+    const memberJson = keyText(value);
+    const key = JSON.stringify([groupJson, memberJson]);
+    if (this.#spilled) { this.#write(group, value); return; }
+    if (this.#resident.has(key)) return;
+    const bytes = Buffer.byteLength(key);
+    if (this.#resident.size >= 128 || this.#bytes + bytes > 65_536) {
+      for (const [residentGroup, member] of this.#resident.values()) this.#write(residentGroup, member);
+      this.#resident.clear();
+      this.#bytes = 0;
+      this.#spilled = true;
+      this.#write(group, value);
+    } else {
+      this.#resident.set(key, [group, value]);
+      this.#bytes += bytes;
+    }
+  }
+  *values(group) {
+    this.#owner.assertActive();
+    const groupJson = keyText(group);
+    if (!this.#spilled) {
+      for (const [residentGroup, member] of this.#resident.values()) {
+        this.#owner.assertActive();
+        if (keyText(residentGroup) === groupJson) yield member;
+        this.#owner.assertActive();
+      }
+    } else {
+      const rows = this.#owner.database().prepare("SELECT member_json FROM grouped_relations WHERE relation_id = ? AND group_json = ? ORDER BY rowid").iterate(this.#id, groupJson);
+      for (const row of rows) {
+        this.#owner.assertActive();
+        yield JSON.parse(row.member_json);
+        this.#owner.assertActive();
+      }
+    }
+    this.#owner.assertActive();
+  }
+}
+
+class RelationSet {
+  #map;
+  constructor(map) { this.#map = map; }
+  get size() { return this.#map.size; }
+  get spilled() { return this.#map.spilled; }
+  has(value) { return this.#map.has(value); }
+  add(value) { this.#map.set(value, true); return this; }
+  delete(value) { return this.#map.delete(value); }
+  *values() { for (const [key] of this.#map) yield key; }
+  [Symbol.iterator]() { return this.values(); }
+}
+
+/** Only scratch state may remain transactional across awaits; the live operational DB is untouched. */
+function createRelationOwner() {
+  let directory;
+  let db;
+  let active = true;
+  let nextId = 0;
+  const owner = {
+    assertActive() { if (!active) throw relationError("Ledger relation owner has expired"); },
+    database() {
+      owner.assertActive();
+      if (!db) {
+        const { DatabaseSync } = loadStorageDriver();
+        directory = mkdtempSync(path.join(os.tmpdir(), "forgeloop-ledger-relations-"));
+        db = new DatabaseSync(path.join(directory, "relations.sqlite"));
+        db.exec("PRAGMA cache_size = -1024; PRAGMA temp_store = FILE; CREATE TABLE relations (relation_id INTEGER NOT NULL, key_json TEXT NOT NULL, value_json TEXT NOT NULL, position INTEGER NOT NULL, PRIMARY KEY (relation_id, key_json)); CREATE INDEX relation_order ON relations (relation_id, position); CREATE TABLE grouped_relations (relation_id INTEGER NOT NULL, group_json TEXT NOT NULL, member_json TEXT NOT NULL, UNIQUE (relation_id, group_json, member_json)); BEGIN");
+      }
+      return db;
+    },
+    map() { owner.assertActive(); return new RelationMap(owner, nextId++); },
+    set() { return new RelationSet(owner.map()); },
+    groupedSet() { owner.assertActive(); return new GroupedRelationSet(owner, nextId++); },
+  };
+  return { owner, close() {
+    active = false;
+    try { db?.close(); }
+    finally { if (directory) rmSync(directory, { recursive: true, force: true }); }
+  } };
+}
+
+export async function withSpilledLedgerRelations(callback) {
+  const scope = createRelationOwner();
+  try { return await withLedgerRelationOwner(scope.owner, () => callback(scope.owner)); }
+  finally { scope.close(); }
+}
+
+export function withSpilledLedgerRelationsSync(callback) {
+  if (callback.constructor?.name === "AsyncFunction") throw Object.assign(new TypeError("Synchronous relation owner cannot await a callback"), { code: "E_STORAGE_ASYNC_TRANSACTION" });
+  const scope = createRelationOwner();
+  try {
+    const result = withLedgerRelationOwner(scope.owner, () => callback(scope.owner));
+    if (result && typeof result.then === "function") throw Object.assign(new TypeError("Synchronous relation owner cannot await a callback"), { code: "E_STORAGE_ASYNC_TRANSACTION" });
+    return result;
+  } finally { scope.close(); }
+}

package/src/storage/legacy-maintenance-boundary.js

@@ -0,0 +1,18 @@
+import { assertSafePath } from "../core/filesystem.js";
+import { lstat, readdir } from "node:fs/promises";
+
+/** A retained legacy owner cannot be silently displaced by native admission. */
+export async function assertNoLegacyOperationLocks(target, { code = "E_STORAGE_MIGRATION_REQUIRED" } = {}) {
+  async function exists(relativePath) {
+    const filename = await assertSafePath(target, relativePath);
+    try { return { filename, info: await lstat(filename) }; }
+    catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  }
+  if (await exists(".forgeloop/.claims.lock")) {
+    throw Object.assign(new Error("Retained lock requires reconciliation: .forgeloop/.claims.lock"), { code });
+  }
+  const locks = await exists(".forgeloop/locks");
+  if (locks && (!locks.info.isDirectory() || (await readdir(locks.filename)).length)) {
+    throw Object.assign(new Error("Task locks require reconciliation before native admission"), { code });
+  }
+}

package/src/storage/legacy-signature.js

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, realpath } from "node:fs/promises";
+import { Readable } from "node:stream";
+import path from "node:path";
+import { assertSafePath } from "../core/filesystem.js";
+import { taskAttestationBundlePath, taskAttestationStatementPath, taskAttestationStatementHistoryPath } from "../core/task-paths.js";
+import { validateAttestationStatement } from "../core/attestation.js";
+import { legacyAttachmentReferenceId, signatureReferencePrefix } from "../core/signing/bundle-reference.js";
+import { publishAttachmentFile } from "./attachment-files.js";
+import { validateAttachmentReference } from "./attachment-binding.js";
+import { assertTaskDescriptorIdentity } from "../core/task-identity.js";
+import { assertJsonLimits, JSON_LIMITS } from "../core/json-safety.js";
+
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_ATTACHMENT_INVALID" }); }
+
+function assertInventoryFile(file, expectedPath) {
+  if (!file || file.path !== expectedPath || !Number.isSafeInteger(file.size) || file.size < 0 || !/^[a-f0-9]{64}$/u.test(file.sha256 ?? "")) {
+    throw invalid("Legacy signature preparation requires task-scoped recorded source bindings");
+  }
+}
+
+async function recordedStream(root, file) {
+  const filename = await assertSafePath(root, file.path);
+  const stat = await lstat(filename);
+  if (!stat.isFile() || stat.size !== file.size) throw invalid("Legacy attachment source disagrees with recorded file size/type");
+  return Readable.from((async function* () {
+    let size = 0;
+    for await (const bytes of createReadStream(filename)) {
+      size += bytes.length;
+      if (size > file.size) throw invalid("Legacy attachment source grew beyond recorded size");
+      yield bytes;
+    }
+  })());
+}
+
+async function recordedDescriptor(root, file, taskKey) {
+  assertInventoryFile(file, `.forgeloop/task-state/${taskKey}/task.json`);
+  if (file.size > JSON_LIMITS.maxBytes) throw invalid("Recorded task descriptor exceeds the JSON byte limit");
+  const chunks = [];
+  for await (const bytes of await recordedStream(root, file)) chunks.push(bytes);
+  const bytes = Buffer.concat(chunks);
+  if (bytes.length !== file.size || createHash("sha256").update(bytes).digest("hex") !== file.sha256) throw invalid("Recorded task descriptor bytes changed");
+  const text = bytes.toString("utf8");
+  if (!Buffer.from(text, "utf8").equals(bytes)) throw invalid("Recorded task descriptor is not UTF-8");
+  const descriptor = JSON.parse(text);
+  assertJsonLimits(descriptor, "Recorded task descriptor");
+  assertTaskDescriptorIdentity(descriptor, null, taskKey);
+  return descriptor;
+}
+
+/** Discover only captured signatures; no live directory scan or invented task IDs. */
+export async function prepareRecordedLegacySignatures(sourceRoot, attachmentRoot, files, { packageRoot } = {}) {
+  if (!Array.isArray(files)) throw invalid("Recorded signature discovery requires a source inventory");
+  const relevant = new Map();
+  const signatures = [];
+  for (const file of files) {
+    if (!file || typeof file.path !== "string") throw invalid("Malformed recorded source entry");
+    if (file.path.endsWith("/task.json") || file.path.endsWith("/statement.json") || file.path.endsWith("/statement.sigstore.json")) {
+      if (relevant.has(file.path)) throw invalid("Duplicate recorded signature source entry");
+      relevant.set(file.path, file);
+    }
+    if (file.path.endsWith("/statement.sigstore.json")) signatures.push(file);
+  }
+  const descriptors = new Map();
+  const references = [];
+  const mappings = [];
+  for (const signature of signatures.sort((left, right) => left.path.localeCompare(right.path))) {
+    const match = /^\.forgeloop\/task-state\/([a-f0-9]{64})\/attestations\/(?:history\/cycle-([1-9][0-9]*)\/)?statement\.sigstore\.json$/u.exec(signature.path);
+    if (!match) throw invalid("Recorded signature has no supported task namespace mapping");
+    const taskKey = match[1];
+    let descriptor = descriptors.get(taskKey);
+    if (!descriptor) {
+      descriptor = await recordedDescriptor(sourceRoot, relevant.get(`.forgeloop/task-state/${taskKey}/task.json`), taskKey);
+      descriptors.set(taskKey, descriptor);
+    }
+    const statement = relevant.get(signature.path.replace(/statement\.sigstore\.json$/u, "statement.json"));
+    const prepared = await prepareLegacySignatureAttachment(sourceRoot, attachmentRoot, {
+      taskId: descriptor.taskId, signature, statement, packageRoot,
+      verificationCycle: match[2] === undefined ? null : Number(match[2]),
+    });
+    references.push(...prepared.references);
+    mappings.push(prepared);
+  }
+  return { root: attachmentRoot, references, mappings };
+}
+
+/** Prepare external bytes separately; the caller owns atomic binding publication. */
+export async function prepareLegacySignatureAttachment(sourceRoot, attachmentRoot, { taskId, signature, statement, packageRoot, verificationCycle = null } = {}) {
+  if (verificationCycle !== null && (!Number.isSafeInteger(verificationCycle) || verificationCycle < 1)) throw invalid("Invalid historical signature cycle");
+  const statementPath = verificationCycle === null ? taskAttestationStatementPath(taskId) : taskAttestationStatementHistoryPath(taskId, verificationCycle);
+  const signaturePath = verificationCycle === null ? taskAttestationBundlePath(taskId) : statementPath.replace(/\.json$/u, ".sigstore.json");
+  assertInventoryFile(signature, signaturePath);
+  assertInventoryFile(statement, statementPath);
+  const source = await realpath(sourceRoot);
+  const destination = await realpath(attachmentRoot);
+  const inside = (parent, child) => child === parent || child.startsWith(`${parent}${path.sep}`);
+  if (inside(source, destination) || inside(destination, source)) throw invalid("Attachment preparation must not overlap the retained source tree");
+  if (statement.size > 64 * 1024 * 1024) throw invalid("Legacy attestation statement exceeds the supported byte limit");
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of await recordedStream(source, statement)) { chunks.push(chunk); size += chunk.length; }
+  const bytes = Buffer.concat(chunks, size);
+  if (bytes.length !== statement.size || createHash("sha256").update(bytes).digest("hex") !== statement.sha256) throw invalid("Legacy statement disagrees with recorded source bytes");
+  const text = bytes.toString("utf8");
+  if (!Buffer.from(text, "utf8").equals(bytes)) throw invalid("Legacy statement is not valid UTF-8");
+  const value = await validateAttestationStatement(JSON.parse(text), packageRoot);
+  if (value.predicate.task.taskId !== taskId) throw invalid("Legacy statement belongs to another task");
+  if (verificationCycle !== null && value.predicate.task.verificationCycle !== verificationCycle) throw invalid("Historical statement disagrees with its source cycle");
+  const binding = await publishAttachmentFile(destination, await recordedStream(source, signature));
+  if (binding.size !== signature.size || binding.sha256 !== signature.sha256) throw invalid("Legacy signature disagrees with recorded source bytes");
+  const alias = legacyAttachmentReferenceId(signature.path);
+  const references = [alias, `${signatureReferencePrefix(text)}${alias}`].map(referenceId => validateAttachmentReference({ taskId, referenceId, ...binding }));
+  return { sourcePath: signature.path, statementPath: statement.path, statementByteSha256: statement.sha256, binding, references };
+}

package/src/storage/maintenance-handoff.js

@@ -0,0 +1,129 @@
+import { link, mkdir, open, rename } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { assertSafePath } from "../core/filesystem.js";
+import { MAINTENANCE_OWNER_ID, readMaintenanceOwner } from "./maintenance-owner.js";
+
+const HISTORY = ".forgeloop/storage-maintenance-history";
+const busy = message => Object.assign(new Error(message), { code: "E_STORAGE_MAINTENANCE_IN_PROGRESS" });
+
+async function assertPublishableOwner(ownerData) {
+  if (process.platform !== "win32") return;
+  const { isWindowsProcessIncarnationToken, readWindowsProcessIncarnation } =
+    await import("./windows-process-incarnation.js");
+  if (ownerData.pid !== process.pid || !isWindowsProcessIncarnationToken(ownerData.processIncarnation, { pid: process.pid })) {
+    throw busy("Windows process incarnation is missing or malformed; publication refused");
+  }
+  let observation;
+  try { observation = await readWindowsProcessIncarnation(process.pid); } catch { observation = null; }
+  if (!observation || observation.status !== "ALIVE" || observation.hasExited !== false
+    || observation.startTimeTicks !== ownerData.processIncarnation.startTimeTicks) {
+    throw busy("Windows process incarnation changed or is unavailable; publication refused");
+  }
+}
+
+// Admission inspects ownership without running durable handoff writes.
+// Load the shared filesystem kernel only when a handoff actually needs it.
+async function syncDirectory(directory) {
+  const durability = await import("./file-durability.js");
+  return durability.syncDirectory(directory);
+}
+
+async function optionalClaim(target, relative) {
+  try {
+    const envelope = await readMaintenanceOwner(target, relative);
+    return { relative, ...envelope };
+  }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+async function retainedSuccessor(target, predecessor, relative) {
+  const scoped = await optionalClaim(target, relative);
+  const legacy = await optionalClaim(target, `${HISTORY}/handoffs/${predecessor}.json`);
+  if (scoped && legacy) throw busy("Maintenance continuation has conflicting path identities");
+  return scoped ?? legacy;
+}
+
+/** Each original owner has an isolated immutable dead-claimant chain. */
+export async function claimMaintenanceHandoff(target, previous, ownerData, assertDead) {
+  const sourceSha256 = createHash("sha256").update(previous.text).digest("hex");
+  const claimedOwner = { ...ownerData, handoffSourceSha256: sourceSha256 };
+  const roots = {};
+  for (const name of ["handoff-intents", "handoffs"]) {
+    roots[name] = await assertSafePath(target, `${HISTORY}/${name}`);
+    await mkdir(roots[name], { recursive: true });
+  }
+  await syncDirectory(await assertSafePath(target, HISTORY));
+  await syncDirectory(await assertSafePath(target, ".forgeloop"));
+  const intent = await assertSafePath(target, `${HISTORY}/handoff-intents/${ownerData.ownerId}.json`);
+  const handle = await open(intent, "wx", 0o600);
+  try { await handle.writeFile(`${JSON.stringify(claimedOwner)}\n`); await handle.sync(); }
+  finally { await handle.close(); }
+  await syncDirectory(roots["handoff-intents"]);
+  let predecessor = previous.value.ownerId;
+  const visited = new Set();
+  for (let depth = 0; depth < 64; depth += 1) {
+    if (visited.has(predecessor)) throw busy("Maintenance handoff history is cyclic");
+    visited.add(predecessor);
+    const relative = depth === 0
+      ? `${HISTORY}/handoffs/${predecessor}.json`
+      : `${HISTORY}/handoffs/${previous.value.ownerId}--${predecessor}.json`;
+    // Honor existing flat continuation records, including live claimants, but
+    // never create a continuation at another owner's future root pathname.
+    let claimant = depth === 0 ? null : await retainedSuccessor(target, predecessor, relative);
+    if (!claimant) {
+      const destination = await assertSafePath(target, relative);
+      try {
+        await link(intent, destination);
+        await syncDirectory(roots.handoffs);
+        return claimedOwner;
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+      }
+      const envelope = await readMaintenanceOwner(target, relative);
+      claimant = { relative, ...envelope };
+    }
+    if (!MAINTENANCE_OWNER_ID.test(claimant.value.ownerId) || claimant.value.resumedFrom !== previous.value.ownerId || claimant.value.handoffSourceSha256 !== sourceSha256) {
+      throw busy("Maintenance handoff differs from the requested owner");
+    }
+    await assertDead(claimant.value);
+    const rechecked = await readMaintenanceOwner(target, claimant.relative);
+    if (rechecked.text !== claimant.text || rechecked.value.ownerId !== claimant.value.ownerId) {
+      throw busy("Maintenance handoff claimant changed during liveness verification");
+    }
+    predecessor = rechecked.value.ownerId;
+  }
+  throw busy("Maintenance handoff history exceeds bounded recovery depth");
+}
+
+/** Link the already durable marker; an interrupted archive cannot be a partial file. */
+export async function archiveMaintenanceOwner(target, previous) {
+  const root = await assertSafePath(target, HISTORY);
+  await mkdir(root, { recursive: true });
+  await syncDirectory(await assertSafePath(target, ".forgeloop"));
+  const archived = `${HISTORY}/${previous.value.ownerId}.json`;
+  try {
+    await link(await assertSafePath(target, ".forgeloop/.storage-maintenance/owner.json"), await assertSafePath(target, archived));
+    await syncDirectory(root);
+  } catch (error) { if (error.code !== "EEXIST") throw error; }
+  if ((await readMaintenanceOwner(target, archived)).text !== previous.text) {
+    throw busy("Retained owner archive differs from the owner being resumed");
+  }
+}
+
+/** Promotion scratch stays outside the exclusion and every byte comes from the durable claim. */
+export async function publishMaintenanceOwner(target, ownerData) {
+  await assertPublishableOwner(ownerData);
+  const root = await assertSafePath(target, `${HISTORY}/handoff-promotions`);
+  await mkdir(root, { recursive: true });
+  await syncDirectory(await assertSafePath(target, HISTORY));
+  const source = await assertSafePath(target, `${HISTORY}/handoff-intents/${ownerData.ownerId}.json`);
+  const promotion = await assertSafePath(target, `${HISTORY}/handoff-promotions/${ownerData.ownerId}.json`);
+  if ((await readMaintenanceOwner(target, `${HISTORY}/handoff-intents/${ownerData.ownerId}.json`)).text !== `${JSON.stringify(ownerData)}\n`) {
+    throw busy("Maintenance promotion differs from its durable claim");
+  }
+  await link(source, promotion);
+  await syncDirectory(root);
+  await rename(promotion, await assertSafePath(target, ".forgeloop/.storage-maintenance/owner.json"));
+  await syncDirectory(root);
+  await syncDirectory(await assertSafePath(target, ".forgeloop/.storage-maintenance"));
+}