@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/providers/capabilities.js

@@ -0,0 +1,46 @@
+export const PROVIDER_KINDS = Object.freeze([
+  "ADVISORY_CONTEXT",
+  "VERIFICATION_EXECUTION",
+  "BROWSER_VERIFICATION",
+  "SECURITY_REVIEW",
+  "PRESENTATION",
+]);
+
+export const PROVIDER_CAPABILITIES = Object.freeze({
+  ADVISORY_CONTEXT: Object.freeze({
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    executableAuthority: false,
+    evidenceAuthority: false,
+  }),
+  VERIFICATION_EXECUTION: Object.freeze({
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    canProduceExecutionObservation: true,
+    evidenceAuthority: false,
+  }),
+  BROWSER_VERIFICATION: Object.freeze({
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    evidenceRequiresForgeLoopValidation: true,
+    evidenceAuthority: false,
+  }),
+  SECURITY_REVIEW: Object.freeze({
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    evidenceRequiresForgeLoopValidation: true,
+    evidenceAuthority: false,
+  }),
+  PRESENTATION: Object.freeze({
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    executableAuthority: false,
+    evidenceAuthority: false,
+    mayMutateProtocolState: false,
+  }),
+});
+
+export function capabilityFor(kind) {
+  if (!PROVIDER_KINDS.includes(kind)) return null;
+  return PROVIDER_CAPABILITIES[kind] ?? null;
+}

package/src/providers/errors.js

@@ -0,0 +1,15 @@
+export const E_PROVIDER_INVALID = "E_PROVIDER_INVALID";
+export const E_PROVIDER_UNAVAILABLE = "E_PROVIDER_UNAVAILABLE";
+export const E_PROVIDER_TIMEOUT = "E_PROVIDER_TIMEOUT";
+export const E_PROVIDER_OUTPUT_INVALID = "E_PROVIDER_OUTPUT_INVALID";
+export const E_PROVIDER_OUTPUT_LIMIT = "E_PROVIDER_OUTPUT_LIMIT";
+export const E_PROVIDER_CAPABILITY_UNSUPPORTED = "E_PROVIDER_CAPABILITY_UNSUPPORTED";
+export const E_PROVIDER_AUTHORITY_ESCALATION = "E_PROVIDER_AUTHORITY_ESCALATION";
+export const E_PROVIDER_EXECUTION_FAILED = "E_PROVIDER_EXECUTION_FAILED";
+
+export function providerError(code, message) {
+  const error = new Error(message);
+  error.name = "ProviderError";
+  error.code = code;
+  return error;
+}

package/src/providers/index.js

@@ -0,0 +1,29 @@
+import { PROVIDER_KINDS, PROVIDER_CAPABILITIES, capabilityFor } from "./capabilities.js";
+import {
+  E_PROVIDER_INVALID,
+  E_PROVIDER_UNAVAILABLE,
+  E_PROVIDER_TIMEOUT,
+  E_PROVIDER_OUTPUT_INVALID,
+  E_PROVIDER_OUTPUT_LIMIT,
+  E_PROVIDER_CAPABILITY_UNSUPPORTED,
+  E_PROVIDER_AUTHORITY_ESCALATION,
+  E_PROVIDER_EXECUTION_FAILED,
+  providerError,
+} from "./errors.js";
+import { createProviderRegistry } from "./registry.js";
+
+export {
+  PROVIDER_KINDS,
+  PROVIDER_CAPABILITIES,
+  capabilityFor,
+  E_PROVIDER_INVALID,
+  E_PROVIDER_UNAVAILABLE,
+  E_PROVIDER_TIMEOUT,
+  E_PROVIDER_OUTPUT_INVALID,
+  E_PROVIDER_OUTPUT_LIMIT,
+  E_PROVIDER_CAPABILITY_UNSUPPORTED,
+  E_PROVIDER_AUTHORITY_ESCALATION,
+  E_PROVIDER_EXECUTION_FAILED,
+  providerError,
+  createProviderRegistry,
+};

package/src/providers/json-snapshot.js

@@ -0,0 +1,105 @@
+import { types } from "node:util";
+import { deepFreeze } from "../core/portable-context.js";
+import {
+  E_PROVIDER_AUTHORITY_ESCALATION,
+  E_PROVIDER_INVALID,
+  E_PROVIDER_OUTPUT_INVALID,
+  E_PROVIDER_OUTPUT_LIMIT,
+  providerError,
+} from "./errors.js";
+
+const AUTHORITY_KEYS = new Set([
+  "lifecycleAuthority", "completionAuthority", "evidenceAuthority",
+  "executableAuthority", "installAuthority",
+]);
+
+export function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || types.isProxy(value) || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function serializeSnapshot(value, maxBytes, invalidCode) {
+  const ancestors = new WeakSet();
+  let bytes = 0;
+  let nodes = 0;
+  const invalid = () => { throw providerError(invalidCode, "Provider payload must contain only plain JSON data without accessors"); };
+  const limit = () => { throw providerError(E_PROVIDER_OUTPUT_LIMIT, "Provider payload exceeds its byte or structural limit"); };
+  function charge(text) {
+    bytes += Buffer.byteLength(text, "utf8");
+    if (bytes > maxBytes) limit();
+    return text;
+  }
+  function string(value) {
+    if (value.length > maxBytes - bytes) limit();
+    return charge(JSON.stringify(value));
+  }
+  function visit(value, depth) {
+    nodes += 1;
+    if (depth > 64 || nodes > 100_000) limit();
+    if (value === null) return charge("null");
+    if (typeof value === "string") return string(value);
+    if (typeof value === "boolean") return charge(String(value));
+    if (typeof value === "number" && Number.isFinite(value)) return charge(JSON.stringify(value));
+    if (typeof value !== "object" || types.isProxy(value)) invalid();
+    return visitContainer(value, depth);
+  }
+  function assertContainer(value, array) {
+    const valid = array ? Object.getPrototypeOf(value) === Array.prototype : isPlainObject(value);
+    if (!valid) invalid();
+  }
+  function visitContainer(value, depth) {
+    const array = Array.isArray(value);
+    assertContainer(value, array);
+    if (ancestors.has(value)) invalid();
+    ancestors.add(value);
+    const keys = Reflect.ownKeys(value);
+    if (keys.length > 100_000 || keys.length > maxBytes) limit();
+    const parts = [];
+    charge(array ? "[]" : "{}");
+    const length = array ? Object.getOwnPropertyDescriptor(value, "length").value : 0;
+    if (array && keys.length !== length + 1) invalid();
+    let index = 0;
+    for (const key of keys) {
+      if (array && key === "length") continue;
+      if (typeof key !== "string") invalid();
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) invalid();
+      if (array && key !== String(index)) invalid();
+      if (index > 0) charge(",");
+      const prefix = array ? "" : string(key) + charge(":");
+      parts.push(prefix + visit(descriptor.value, depth + 1));
+      index += 1;
+    }
+    if (array && index !== length) invalid();
+    ancestors.delete(value);
+    return array ? `[${parts.join(",")}]` : `{${parts.join(",")}}`;
+  }
+  return visit(value, 0);
+}
+
+function assertAuthorityFree(value) {
+  if (value === null || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    if (AUTHORITY_KEYS.has(key) && child === true) {
+      throw providerError(E_PROVIDER_AUTHORITY_ESCALATION, "Provider result declares forbidden authority");
+    }
+    assertAuthorityFree(child);
+  }
+}
+
+export function normalizeProviderInput(value, maxBytes) {
+  return deepFreeze(JSON.parse(serializeSnapshot(value, maxBytes, E_PROVIDER_INVALID)));
+}
+
+export function normalizeProviderResult(value, maxBytes) {
+  if (!isPlainObject(value)) {
+    throw providerError(E_PROVIDER_OUTPUT_INVALID, "Provider result must be a plain JSON object");
+  }
+  const normalized = JSON.parse(serializeSnapshot(value, maxBytes, E_PROVIDER_OUTPUT_INVALID));
+  assertAuthorityFree(normalized);
+  if (normalized.status === "COMPLETE") {
+    throw providerError(E_PROVIDER_AUTHORITY_ESCALATION, "Provider result cannot assign lifecycle completion");
+  }
+  return deepFreeze(normalized);
+}

package/src/providers/registry.js

@@ -0,0 +1,152 @@
+import { performance } from "node:perf_hooks";
+import { types } from "node:util";
+import { capabilityFor } from "./capabilities.js";
+import { isPlainObject, normalizeProviderInput, normalizeProviderResult } from "./json-snapshot.js";
+import {
+  E_PROVIDER_EXECUTION_FAILED,
+  E_PROVIDER_INVALID,
+  E_PROVIDER_TIMEOUT,
+  E_PROVIDER_UNAVAILABLE,
+  providerError,
+} from "./errors.js";
+
+const PROVIDER_ID_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const REGISTRY_MAX_PROVIDERS = 256;
+
+function assertEntry(entry, key) {
+  if (!isPlainObject(entry)) {
+    throw providerError(E_PROVIDER_INVALID, "Provider must be a plain object");
+  }
+  for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(entry))) {
+    if (!("value" in descriptor)) throw providerError(E_PROVIDER_INVALID, "Provider accessors are not supported");
+  }
+  if (typeof entry.id !== "string" || !PROVIDER_ID_REGEX.test(entry.id) || entry.id !== key) {
+    throw providerError(E_PROVIDER_INVALID, "Provider identity does not match the registry key");
+  }
+  if (entry.version !== undefined && (typeof entry.version !== "string" || entry.version.trim() === "" || entry.version.length > 64)) {
+    throw providerError(E_PROVIDER_INVALID, "Provider version must be a non-empty string of at most 64 characters");
+  }
+  if (!capabilityFor(entry.kind)) {
+    throw providerError(E_PROVIDER_INVALID, "Provider declares an unsupported kind");
+  }
+  if (entry.capability !== undefined && entry.capability !== capabilityFor(entry.kind)) {
+    throw providerError(E_PROVIDER_INVALID, "Provider capability metadata contradicts its kind");
+  }
+  if (typeof entry.operation !== "function") {
+    throw providerError(E_PROVIDER_INVALID, "Provider must implement operation(input, context)");
+  }
+}
+
+function boundedInteger(value, fallback, maximum) {
+  const resolved = value === undefined ? fallback : value;
+  if (!Number.isInteger(resolved) || resolved <= 0 || resolved > maximum) {
+    throw providerError(E_PROVIDER_INVALID, "Provider limits must be positive bounded integers");
+  }
+  return resolved;
+}
+
+function normalizeOptions(options) {
+  if (!isPlainObject(options)) throw providerError(E_PROVIDER_INVALID, "Provider options must be a plain object");
+  const descriptors = Object.getOwnPropertyDescriptors(options);
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (!["timeoutMs", "maxInputBytes", "maxResultBytes"].includes(key) || !("value" in descriptor)) {
+      throw providerError(E_PROVIDER_INVALID, "Unsupported provider option");
+    }
+  }
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (typeof key !== "string") throw providerError(E_PROVIDER_INVALID, "Unsupported provider option");
+  }
+  return {
+    timeoutMs: boundedInteger(descriptors.timeoutMs?.value, 10_000, 300_000),
+    maxInputBytes: boundedInteger(descriptors.maxInputBytes?.value, 262_144, 4_194_304),
+    maxResultBytes: boundedInteger(descriptors.maxResultBytes?.value, 262_144, 4_194_304),
+  };
+}
+
+function callProvider(operation, normalize) {
+  let returned;
+  try {
+    returned = operation();
+  } catch {
+    throw providerError(E_PROVIDER_EXECUTION_FAILED, "Provider execution failed");
+  }
+  if (types.isPromise(returned) && !types.isProxy(returned)) {
+    return Promise.prototype.then.call(returned, normalize, () => {
+      throw providerError(E_PROVIDER_EXECUTION_FAILED, "Provider execution failed");
+    });
+  }
+  return normalize(returned);
+}
+
+async function withProviderDeadline(providerId, timeoutMs, operation) {
+  const controller = new AbortController();
+  const context = Object.freeze({ signal: controller.signal, timeoutMs, providerId });
+  const expires = performance.now() + timeoutMs;
+  const timeoutError = providerError(E_PROVIDER_TIMEOUT, "Provider invocation exceeded its deadline");
+  const checkpoint = () => {
+    if (controller.signal.aborted || performance.now() >= expires) {
+      controller.abort();
+      throw timeoutError;
+    }
+  };
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(timeoutError);
+      controller.abort();
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([
+      timeout,
+      Promise.resolve().then(() => operation(context, checkpoint)),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function createProviderRegistry({ providers = {} } = {}) {
+  if (!isPlainObject(providers)) throw providerError(E_PROVIDER_INVALID, "Provider registry requires an object map");
+  const map = new Map();
+  for (const key of Reflect.ownKeys(providers)) {
+    if (typeof key !== "string" || !PROVIDER_ID_REGEX.test(key)) {
+      throw providerError(E_PROVIDER_INVALID, "Invalid provider registry key");
+    }
+    if (map.size >= REGISTRY_MAX_PROVIDERS) throw providerError(E_PROVIDER_INVALID, "Too many providers");
+    const descriptor = Object.getOwnPropertyDescriptor(providers, key);
+    if (!("value" in descriptor) || !descriptor.enumerable) throw providerError(E_PROVIDER_INVALID, "Invalid provider registry entry");
+    const entry = descriptor.value;
+    if (typeof entry !== "function") assertEntry(entry, key);
+    map.set(key, entry);
+  }
+  return Object.freeze({
+    get(id) { return map.get(id) ?? null; },
+    has(id) { return map.has(id); },
+    list() { return [...map.keys()].sort(); },
+    async invoke(id, input = {}, options = {}) {
+      const { timeoutMs, maxInputBytes, maxResultBytes } = normalizeOptions(options);
+      if (!map.has(id)) throw providerError(E_PROVIDER_UNAVAILABLE, "Provider is not registered");
+      const payload = normalizeProviderInput(input, maxInputBytes);
+      const entry = map.get(id);
+      return withProviderDeadline(id, timeoutMs, async (context, checkpoint) => {
+        checkpoint();
+        const validate = provider => {
+          checkpoint();
+          assertEntry(provider, id);
+          return Object.freeze({ provider });
+        };
+        const { provider } = typeof entry === "function"
+          ? await callProvider(() => entry(context), validate)
+          : validate(entry);
+        checkpoint();
+        return callProvider(() => provider.operation(payload, context), result => {
+          checkpoint();
+          const normalized = normalizeProviderResult(result, maxResultBytes);
+          checkpoint();
+          return normalized;
+        });
+      });
+    },
+  });
+}

package/src/repository-index/binary-manager.js

@@ -183,9 +183,10 @@ export function validateArchiveEntry(entry) {
 
 async function listArchiveEntries(archivePath, { archive = "tar.gz", execFileImpl = nodeExecFile } = {}) {
   const listCommand = archive === "zip" && process.platform !== "win32" ? "unzip" : "tar";
-  const listArgs = listCommand === "unzip" ? ["-Z1", archivePath] : ["-tf", archivePath];
+  const archiveName = path.basename(archivePath);
+  const listArgs = listCommand === "unzip" ? ["-Z1", archiveName] : ["-tf", archiveName];
   try {
-    const listed = await execFileAsync(execFileImpl, listCommand, listArgs, { maxBuffer: 2 * 1024 * 1024 });
+    const listed = await execFileAsync(execFileImpl, listCommand, listArgs, { cwd: path.dirname(archivePath), maxBuffer: 2 * 1024 * 1024 });
     return listed.stdout.split(/\r?\n/).filter(Boolean).map(validateArchiveEntry);
   } catch (cause) {
     throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXTRACTION_FAILED, `Unable to inspect tgrep archive: ${cause.message}`, { cause });
@@ -195,11 +196,12 @@ async function listArchiveEntries(archivePath, { archive = "tar.gz", execFileImp
 async function extractArchive(archivePath, extractionDirectory, { archive = "tar.gz", execFileImpl = nodeExecFile } = {}) {
   await listArchiveEntries(archivePath, { archive, execFileImpl });
   const extractCommand = archive === "zip" && process.platform !== "win32" ? "unzip" : "tar";
+  const destination = path.relative(path.dirname(archivePath), extractionDirectory).replaceAll("\\", "/") || ".";
   const extractArgs = extractCommand === "unzip"
-    ? ["-q", archivePath, "-d", extractionDirectory]
-    : ["-xf", archivePath, "-C", extractionDirectory];
+    ? ["-q", path.basename(archivePath), "-d", destination]
+    : ["-xf", path.basename(archivePath), "-C", destination];
   try {
-    await execFileAsync(execFileImpl, extractCommand, extractArgs, { maxBuffer: 2 * 1024 * 1024 });
+    await execFileAsync(execFileImpl, extractCommand, extractArgs, { cwd: path.dirname(archivePath), maxBuffer: 2 * 1024 * 1024 });
   } catch (cause) {
     throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXTRACTION_FAILED, `Unable to extract tgrep archive: ${cause.message}`, { cause });
   }

package/src/storage/artifact-bytes.js

@@ -0,0 +1,22 @@
+import { createHash } from "node:crypto";
+import { canonicalFingerprint } from "../core/artifacts.js";
+
+/** Validate byte evidence separately from the domain payload schema. */
+export function artifactByteDigest(record) {
+  if (typeof record?.sourceText !== "string" || typeof record?.byteDigest !== "string") {
+    const error = new Error("Original artifact byte evidence is unavailable");
+    error.code = "E_STORAGE_ARTIFACT_BYTES_UNAVAILABLE";
+    throw error;
+  }
+  try {
+    const digest = createHash("sha256").update(record.sourceText).digest("hex");
+    if (digest !== record.byteDigest || canonicalFingerprint(JSON.parse(record.sourceText)) !== canonicalFingerprint(record.payload)) {
+      throw new Error("Artifact source bytes, digest and canonical payload disagree");
+    }
+    return digest;
+  } catch (cause) {
+    const error = new Error("Stored artifact byte evidence is invalid", { cause });
+    error.code = "E_STORAGE_ARTIFACT_INVALID";
+    throw error;
+  }
+}

package/src/storage/attachment-binding.js

@@ -0,0 +1,11 @@
+/** Pure canonical binding validation, independent of files and SQLite. */
+export function validateAttachmentReference(reference) {
+  if (!reference || typeof reference.taskId !== "string" || !reference.taskId
+    || typeof reference.referenceId !== "string" || !reference.referenceId || reference.referenceId.length > 256
+    || !Number.isSafeInteger(reference.size) || reference.size < 0
+    || !/^[a-f0-9]{64}$/.test(reference.sha256 ?? "")
+    || reference.path !== `.forgeloop/attachments/objects/${reference.sha256}`) {
+    throw Object.assign(new Error("Invalid canonical attachment reference"), { code: "E_STORAGE_ATTACHMENT_INVALID" });
+  }
+  return reference;
+}

package/src/storage/attachment-files.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { constants, createWriteStream } from "node:fs";
+import { link, lstat, mkdir, mkdtemp, open, rm } from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { digestFile, syncDirectory } from "./file-durability.js";
+import { assertSafePath } from "../core/filesystem.js";
+import { assertWritableContext } from "./transaction.js";
+
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_ATTACHMENT_INVALID" }); }
+
+
+/** Verify referenced immutable bytes without loading the attachment into memory. */
+async function attachmentFilename(target, reference) {
+  if (!reference || !Number.isSafeInteger(reference.size) || reference.size < 0
+    || !/^[a-f0-9]{64}$/.test(reference.sha256 ?? "")
+    || reference.path !== `.forgeloop/attachments/objects/${reference.sha256}`) throw invalid("Invalid attachment reference");
+  const filename = await assertSafePath(target, reference.path);
+  if (!(await lstat(filename)).isFile()) throw invalid("Attachment reference must name a regular file");
+  return filename;
+}
+
+export async function verifyAttachmentFile(target, reference) {
+  const filename = await attachmentFilename(target, reference);
+  const actual = await digestFile(filename, { includeSize: true });
+  if (actual.size !== reference.size || actual.sha256 !== reference.sha256) throw invalid("Attachment bytes disagree with their reference");
+  return reference;
+}
+
+/** Give consumers private verified bytes, closing the source check/use window. */
+export async function withVerifiedAttachmentFile(target, reference, callback) {
+  const source = await attachmentFilename(target, reference);
+  const directory = await mkdtemp(path.join(os.tmpdir(), "forgeloop-attachment-read-"));
+  try {
+    const filename = path.join(directory, "bytes");
+    const handle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      if (!(await handle.stat()).isFile()) throw invalid("Attachment must remain a regular file");
+      const hash = createHash("sha256");
+      let size = 0;
+      const check = new Transform({ transform(bytes, _encoding, done) {
+        size += bytes.length;
+        if (size > reference.size) { done(invalid("Attachment exceeds its reference size")); return; }
+        hash.update(bytes);
+        done(null, bytes);
+      } });
+      await pipeline(handle.createReadStream({ autoClose: false }), check, createWriteStream(filename, { flags: "wx", mode: 0o600 }));
+      if (size !== reference.size || hash.digest("hex") !== reference.sha256) throw invalid("Attachment bytes disagree with their reference");
+    } finally { await handle.close(); }
+    return await callback(filename);
+  } finally { await rm(directory, { recursive: true, force: true }); }
+}
+
+/** Publish immutable bytes before a caller commits their database reference. */
+export async function publishAttachmentFile(target, readable, { db, temporaryRoot } = {}) {
+  if (db?.isTransaction) throw invalid("Attachment publication must precede the database write transaction");
+  if (db) assertWritableContext(db);
+  const root = await assertSafePath(target, ".forgeloop/attachments/objects");
+  await mkdir(root, { recursive: true });
+  await assertSafePath(target, ".forgeloop/attachments/objects");
+  const temporaryParent = temporaryRoot ? await assertSafePath(temporaryRoot, ".") : root;
+  const temporary = await mkdtemp(path.join(temporaryParent, ".publishing-"));
+  const filename = path.join(temporary, "bytes");
+  try {
+    await pipeline(readable, createWriteStream(filename, { flags: "wx", mode: 0o600 }));
+    const binding = await digestFile(filename, { includeSize: true });
+    const file = await open(filename, "r+");
+    try { await file.sync(); } finally { await file.close(); }
+    const reference = { path: `.forgeloop/attachments/objects/${binding.sha256}`, ...binding };
+    const destination = await assertSafePath(target, reference.path);
+    try { await link(filename, destination); }
+    catch (error) { if (error.code !== "EEXIST") throw error; }
+    await verifyAttachmentFile(target, reference);
+    await syncDirectory(root);
+    await syncDirectory(path.dirname(root));
+    await syncDirectory(path.dirname(path.dirname(root)));
+    await syncDirectory(target);
+    return reference;
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}

package/src/storage/attachment-references.js

@@ -0,0 +1,36 @@
+import { publishAttachmentFile, verifyAttachmentFile } from "./attachment-files.js";
+import { assertWritableContext, runInTransaction } from "./transaction.js";
+import { validateAttachmentReference } from "./attachment-binding.js";
+export { validateAttachmentReference } from "./attachment-binding.js";
+
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_ATTACHMENT_INVALID" }); }
+
+/** Synchronous insertion is used only after the referenced bytes were verified. */
+export function insertVerifiedAttachmentReference(db, reference) {
+  assertWritableContext(db);
+  validateAttachmentReference(reference);
+  const prior = db.prepare("SELECT path, size, sha256 FROM attachment_references WHERE task_id = ? AND reference_id = ?").get(reference.taskId, reference.referenceId);
+  if (prior) {
+    if (prior.path !== reference.path || prior.size !== reference.size || prior.sha256 !== reference.sha256) throw invalid("An immutable attachment identity already names different bytes");
+    return reference;
+  }
+  db.prepare("INSERT INTO attachment_references(task_id, reference_id, path, size, sha256) VALUES (?, ?, ?, ?, ?)")
+    .run(reference.taskId, reference.referenceId, reference.path, reference.size, reference.sha256);
+  return reference;
+}
+
+/** Publish first, then commit the immutable binding in a short writer transaction. */
+export async function registerAttachment(db, target, { taskId, referenceId, readable }) {
+  if (db.isTransaction) throw invalid("Attachment registration cannot span an active write transaction");
+  assertWritableContext(db);
+  const binding = await publishAttachmentFile(target, readable, { db });
+  const reference = validateAttachmentReference({ taskId, referenceId, ...binding });
+  await verifyAttachmentFile(target, reference);
+  return runInTransaction(db, () => insertVerifiedAttachmentReference(db, reference));
+}
+
+export function* iterateAttachmentReferences(db) {
+  for (const row of db.prepare("SELECT * FROM attachment_references ORDER BY task_id, reference_id").iterate()) {
+    yield validateAttachmentReference({ taskId: row.task_id, referenceId: row.reference_id, path: row.path, size: row.size, sha256: row.sha256 });
+  }
+}

package/src/storage/backup.js

@@ -0,0 +1,53 @@
+import { loadStorageDriver } from "./runtime.js";
+import { mkdtemp, rm, link, open } from "node:fs/promises";
+import path from "node:path";
+import { assertSafePath } from "../core/filesystem.js";
+import { checkStorageIntegrity, openStorageDatabase } from "./connection.js";
+
+/** Database-only backup; attachment restore requires its own verified inventory. */
+export async function backupStorageDatabase(db, destination) {
+  const { backup, DatabaseSync } = loadStorageDriver();
+  if (db.isTransaction) throw Object.assign(new Error("Backup requires committed storage state"), { code: "E_STORAGE_SNAPSHOT_TRANSACTION" });
+  const absolute = path.resolve(destination);
+  const parent = path.dirname(absolute);
+  await assertSafePath(parent, path.basename(absolute));
+  const temporary = await mkdtemp(path.join(parent, ".forgeloop-backup-"));
+  const filename = path.join(temporary, "state.sqlite");
+  try {
+    await backup(db, filename);
+    const snapshot = new DatabaseSync(filename, { readOnly: true, enableForeignKeyConstraints: true });
+    try {
+      const integrity = checkStorageIntegrity(snapshot);
+      if (!integrity.ok) throw Object.assign(new Error("Backup snapshot failed storage integrity validation"), { code: "E_STORAGE_BACKUP_INVALID", integrity });
+    } finally { snapshot.close(); }
+    // FlushFileBuffers on Windows requires write access to this owned snapshot.
+    const file = await open(filename, "r+");
+    try { await file.sync(); } finally { await file.close(); }
+    // Same-directory hard-link publication is atomic and cannot overwrite a
+    // retained backup. The private temporary name is removed afterward.
+    await link(filename, absolute);
+    try {
+      const directory = await open(parent, "r");
+      try { await directory.sync(); } finally { await directory.close(); }
+    } catch (error) {
+      // Match the existing portable atomic-file boundary on platforms that
+      // cannot open/sync directories. Other I/O failures remain visible.
+      if (!["EINVAL", "EPERM", "EISDIR", "ENOTSUP", "UNKNOWN"].includes(error.code)) throw error;
+    }
+    return { path: absolute, kind: "DATABASE_ONLY", attachmentsIncluded: false };
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}
+
+/** Restore into a fresh database pathname; never replace an active project. */
+export async function restoreStorageDatabase(source, destination) {
+  const absolute = path.resolve(source);
+  const parent = path.dirname(absolute);
+  for (const suffix of ["", "-wal", "-shm"]) await assertSafePath(parent, `${path.basename(absolute)}${suffix}`);
+  // Read-only open rejects unsupported schema/format metadata rather than
+  // silently upgrading a retained backup during a restore drill.
+  const db = openStorageDatabase(absolute, { readOnly: true });
+  try {
+    const restored = await backupStorageDatabase(db, destination);
+    return { ...restored, source: absolute, restored: true };
+  } finally { db.close(); }
+}

package/src/storage/capabilities.js

@@ -0,0 +1,31 @@
+import { STORAGE_FORMAT, STORAGE_FORMAT_VERSION, STORAGE_RELATIVE_PATH, STORAGE_SCHEMA_VERSION } from "./schema.js";
+import { STORAGE_MINIMUM_NODE } from "./runtime.js";
+
+/** Package capabilities only; no project selection, database open or runtime probe. */
+export function getStorageCapabilities() {
+  return {
+    version: 1,
+    defaultBackend: "sqlite",
+    soleSQLiteWriter: false,
+    sqlite: {
+      format: STORAGE_FORMAT,
+      formatVersion: STORAGE_FORMAT_VERSION,
+      schemaVersion: STORAGE_SCHEMA_VERSION,
+      path: STORAGE_RELATIVE_PATH,
+      driver: "node:sqlite",
+      minimumNode: STORAGE_MINIMUM_NODE,
+      selection: "FRESH_WRITABLE_BOOTSTRAP_OR_EXISTING_DATABASE",
+    },
+    portableFormats: ["JSON", "NDJSON"],
+    migration: {
+      explicit: true,
+      requiresWritersQuiesced: true,
+      resumeRequiresRecordedInventory: true,
+      automaticDowngrade: false,
+      commands: ["storage-migrate", "storage-migration-resume", "storage-migration-status", "storage-rollback", "storage-rollback-resume"],
+      rollbackRequiresNativeWritesExcluded: true,
+      rollbackRequiresPinnedLegacyTarget: true,
+    },
+    backup: { database: true, referencedAttachments: true, command: "storage-backup" },
+  };
+}