pactium 0.2.0

package/src/storage/local-json-storage-port.js

@@ -0,0 +1,360 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { PACTIUM_PROTOCOL, PACTIUM_SCHEMA_VERSION } from "../protocol/constants.js";
+import { canonicalEncode, normalizeCanonicalValue } from "../canonical/value.js";
+import { cidForBytes, hashBytes, hexFromCid } from "../protocol/hashing.js";
+import { asArray, nowIso, safeToken } from "../shared/records.js";
+
+export function defaultPactiumDataDir() {
+  return path.join(os.homedir(), ".pactium");
+}
+
+export function resolveDataDir(dataDir = "") {
+  return path.resolve(String(dataDir || process.env.PACTIUM_DATA_DIR || defaultPactiumDataDir()));
+}
+
+export function resolveWithin(root, ...segments) {
+  const base = path.resolve(String(root || defaultPactiumDataDir()));
+  const target = path.resolve(base, ...segments.map((segment) => String(segment || "")));
+  if (target !== base && !target.startsWith(`${base}${path.sep}`)) {
+    throw new Error(`Path escapes Pactium data directory: ${target}`);
+  }
+  return target;
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return fallback;
+    throw error;
+  }
+}
+
+async function writeJsonAtomic(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  await fs.writeFile(tmpPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  await fs.rename(tmpPath, filePath);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function processIsAlive(pid) {
+  if (!pid || pid === process.pid) return Boolean(pid);
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+export function createStoragePort({ dataDir = "", userDataPath = "", inMemory = false } = {}) {
+  const resolvedDataDir = resolveDataDir(dataDir || userDataPath);
+  const memoryBlocks = new Map();
+  const memoryObjects = new Map();
+  let initialized = false;
+
+  function manifestPath() {
+    return resolveWithin(resolvedDataDir, "pactium-manifest.json");
+  }
+
+  function blockPath(cid) {
+    const hex = hexFromCid(cid);
+    return resolveWithin(resolvedDataDir, "cas", hex.slice(0, 2), `${hex}.json`);
+  }
+
+  function objectPath(scope, key) {
+    return resolveWithin(resolvedDataDir, "protocol", safeToken(scope), `${safeToken(key)}.json`);
+  }
+
+  function lockPath(name = "write") {
+    return resolveWithin(resolvedDataDir, "locks", `${safeToken(name)}.lock`);
+  }
+
+  function lockOwnerPath(lockDir) {
+    return path.join(lockDir, "owner.json");
+  }
+
+  async function ensureInitialized() {
+    if (initialized) return;
+    initialized = true;
+    if (inMemory) return;
+    await fs.mkdir(resolvedDataDir, { recursive: true });
+    const manifest = await readJson(manifestPath());
+    if (manifest) {
+      if (manifest.protocol !== PACTIUM_PROTOCOL || manifest.schema !== PACTIUM_SCHEMA_VERSION) {
+        throw new Error("Pactium latest-schema-only boundary rejected a non-current protocol data directory.");
+      }
+      return;
+    }
+    const historicalLayoutHints = [
+      resolveWithin(resolvedDataDir, "operation-ledger"),
+      resolveWithin(resolvedDataDir, "checkpoint-trees"),
+      resolveWithin(resolvedDataDir, "state-substrate")
+    ];
+    for (const historicalPath of historicalLayoutHints) {
+      if (await fileExists(historicalPath)) {
+        throw new Error("Historical Pactium data directory detected. Pactium performs no data migration.");
+      }
+    }
+    await writeJsonAtomic(manifestPath(), {
+      protocol: PACTIUM_PROTOCOL,
+      schema: PACTIUM_SCHEMA_VERSION,
+      createdAt: nowIso(),
+      latestSchemaOnly: true,
+      historicalMigration: false
+    });
+  }
+
+  async function putBlock(value, { codec = "pactium-canonical", kind = "protocol-material", refs = [] } = {}) {
+    await ensureInitialized();
+    const bytes = codec === "raw"
+      ? Buffer.from(value || "")
+      : Buffer.from(canonicalEncode(value));
+    const cid = cidForBytes(bytes);
+    const payloadHash = `sha256:${hashBytes(bytes)}`;
+    const record = {
+      protocol: PACTIUM_PROTOCOL,
+      schema: PACTIUM_SCHEMA_VERSION,
+      cid,
+      codec,
+      kind,
+      refs: [...new Set(asArray(refs).map((ref) => String(ref || "").trim()).filter(Boolean))],
+      byteLength: bytes.length,
+      payloadHash,
+      payloadBase64: bytes.toString("base64"),
+      createdAt: nowIso()
+    };
+    const existing = await getBlock(cid);
+    if (existing) {
+      if (existing.payloadHash !== payloadHash || existing.payloadBase64 !== record.payloadBase64) {
+        throw new Error(`CAS collision or replacement attempt for ${cid}`);
+      }
+      return { ...existing, deduped: true };
+    }
+    memoryBlocks.set(cid, record);
+    if (!inMemory) await writeJsonAtomic(blockPath(cid), record);
+    return { ...record, deduped: false };
+  }
+
+  async function getBlock(cid) {
+    await ensureInitialized();
+    if (memoryBlocks.has(cid)) return { ...memoryBlocks.get(cid), bytes: Buffer.from(memoryBlocks.get(cid).payloadBase64, "base64") };
+    if (inMemory) return null;
+    const record = await readJson(blockPath(cid));
+    if (!record) return null;
+    const bytes = Buffer.from(String(record.payloadBase64 || ""), "base64");
+    const payloadHash = `sha256:${hashBytes(bytes)}`;
+    if (payloadHash !== record.payloadHash || cidForBytes(bytes) !== record.cid) {
+      throw new Error(`CAS block integrity failure for ${cid}`);
+    }
+    memoryBlocks.set(cid, record);
+    return { ...record, bytes };
+  }
+
+  async function hasBlock(cid) {
+    return Boolean(await getBlock(cid));
+  }
+
+  async function walk(rootCid) {
+    const missing = [];
+    const blocks = [];
+    const seen = new Set();
+    const stack = [String(rootCid || "").trim()].filter(Boolean);
+    while (stack.length > 0) {
+      const cid = stack.pop();
+      if (!cid || seen.has(cid)) continue;
+      seen.add(cid);
+      const block = await getBlock(cid);
+      if (!block) {
+        missing.push(cid);
+        continue;
+      }
+      blocks.push(block);
+      for (const ref of [...asArray(block.refs)].reverse()) {
+        if (!seen.has(ref)) stack.push(ref);
+      }
+    }
+    return { protocol: PACTIUM_PROTOCOL, rootCid, blockCount: blocks.length, missing, blocks };
+  }
+
+  async function putProtocolObject(scope, key, value) {
+    await ensureInitialized();
+    const normalizedScope = safeToken(scope);
+    const normalizedKey = safeToken(key);
+    const storedValue = inMemory ? value : normalizeCanonicalValue(value);
+    const stored = {
+      protocol: PACTIUM_PROTOCOL,
+      schema: PACTIUM_SCHEMA_VERSION,
+      value: storedValue,
+      updatedAt: nowIso()
+    };
+    memoryObjects.set(`${normalizedScope}/${normalizedKey}`, storedValue);
+    if (!inMemory) await writeJsonAtomic(objectPath(normalizedScope, normalizedKey), stored);
+    return storedValue;
+  }
+
+  function clearCache() {
+    memoryObjects.clear();
+  }
+
+  async function readLockOwner(lockDir) {
+    const owner = await readJson(lockOwnerPath(lockDir), null);
+    const stats = await fs.stat(lockDir).catch(() => null);
+    return {
+      owner,
+      mtimeMs: Number(stats?.mtimeMs || 0)
+    };
+  }
+
+  async function removeStaleLock(lockDir, staleMs) {
+    const { owner, mtimeMs } = await readLockOwner(lockDir);
+    if (!mtimeMs) return false;
+    const pid = Number(owner?.pid || 0);
+    const ageMs = Date.now() - (Number(owner?.createdAtMs || 0) || mtimeMs);
+    if (!owner) {
+      if (ageMs < staleMs) return false;
+    } else if (ageMs < staleMs && processIsAlive(pid)) {
+      return false;
+    }
+    const latest = await readLockOwner(lockDir);
+    const sameOwner = String(latest.owner?.ownerId || "") === String(owner?.ownerId || "") &&
+      Number(latest.owner?.createdAtMs || 0) === Number(owner?.createdAtMs || 0) &&
+      Number(latest.mtimeMs || 0) === Number(mtimeMs || 0);
+    if (!sameOwner) return false;
+    await fs.rm(lockDir, { recursive: true, force: true });
+    return true;
+  }
+
+  async function withWriteLock(task, {
+    name = "write",
+    timeoutMs = 10000,
+    retryMs = 25,
+    staleMs = 30000
+  } = {}) {
+    await ensureInitialized();
+    if (inMemory) return task();
+    const locksDir = resolveWithin(resolvedDataDir, "locks");
+    await fs.mkdir(locksDir, { recursive: true });
+    const targetLockPath = lockPath(name);
+    const ownerId = crypto.randomUUID();
+    const startedAt = Date.now();
+    let acquired = false;
+    while (!acquired) {
+      try {
+        await fs.mkdir(targetLockPath);
+        acquired = true;
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+        await removeStaleLock(targetLockPath, staleMs).catch(() => false);
+        if (Date.now() - startedAt >= timeoutMs) {
+          const lockError = new Error(`Timed out acquiring Pactium data directory write lock: ${targetLockPath}`);
+          lockError.code = "PACTIUM_WRITE_LOCK_TIMEOUT";
+          lockError.details = {
+            protocol: PACTIUM_PROTOCOL,
+            lockType: "pactium.write-lock",
+            dataDir: resolvedDataDir,
+            lockPath: targetLockPath,
+            timeoutMs,
+            retryMs,
+            staleMs
+          };
+          throw lockError;
+        }
+        await sleep(retryMs);
+      }
+    }
+    await writeJsonAtomic(lockOwnerPath(targetLockPath), {
+      protocol: PACTIUM_PROTOCOL,
+      schema: PACTIUM_SCHEMA_VERSION,
+      lockType: "pactium.write-lock",
+      ownerId,
+      pid: process.pid,
+      createdAt: nowIso(),
+      createdAtMs: Date.now()
+    });
+    try {
+      return await task();
+    } finally {
+      const owner = await readJson(lockOwnerPath(targetLockPath), null).catch(() => null);
+      if (owner?.ownerId === ownerId) {
+        await fs.rm(targetLockPath, { recursive: true, force: true });
+      }
+    }
+  }
+
+  function pruneBlocks(predicate = () => false) {
+    if (!inMemory) return 0;
+    let pruned = 0;
+    for (const [cid, record] of memoryBlocks.entries()) {
+      if (predicate(record)) {
+        memoryBlocks.delete(cid);
+        pruned += 1;
+      }
+    }
+    return pruned;
+  }
+
+  function pruneProtocolObjects(predicate = () => false) {
+    if (!inMemory) return 0;
+    let pruned = 0;
+    for (const [compoundKey, value] of memoryObjects.entries()) {
+      const [scope = "", key = ""] = compoundKey.split("/");
+      if (predicate({ scope, key, value })) {
+        memoryObjects.delete(compoundKey);
+        pruned += 1;
+      }
+    }
+    return pruned;
+  }
+
+  async function getProtocolObject(scope, key, fallback = null) {
+    await ensureInitialized();
+    const normalizedScope = safeToken(scope);
+    const normalizedKey = safeToken(key);
+    const memoryKey = `${normalizedScope}/${normalizedKey}`;
+    if (memoryObjects.has(memoryKey)) return memoryObjects.get(memoryKey);
+    if (inMemory) return fallback;
+    const stored = await readJson(objectPath(normalizedScope, normalizedKey));
+    if (!stored) return fallback;
+    if (stored.protocol !== PACTIUM_PROTOCOL || stored.schema !== PACTIUM_SCHEMA_VERSION) {
+      throw new Error("Pactium latest-schema-only boundary rejected protocol material.");
+    }
+    memoryObjects.set(memoryKey, stored.value);
+    return stored.value;
+  }
+
+  return Object.freeze({
+    protocol: PACTIUM_PROTOCOL,
+    schema: PACTIUM_SCHEMA_VERSION,
+    dataDir: resolvedDataDir,
+    inMemory,
+    initialize: ensureInitialized,
+    putBlock,
+    getBlock,
+    hasBlock,
+    walk,
+    putProtocolObject,
+    getProtocolObject,
+    clearCache,
+    withWriteLock,
+    pruneBlocks,
+    pruneProtocolObjects
+  });
+}

package/src/verification/failure.js

@@ -0,0 +1,31 @@
+import { PACTIUM_PROTOCOL } from "../protocol/constants.js";
+import { asRecord, compactObject } from "../shared/records.js";
+
+export function createVerificationFailure({
+  layer = "core",
+  code = "verification_failed",
+  severity = "error",
+  message = "",
+  evidenceRef = "",
+  repairable = false,
+  details = {}
+} = {}) {
+  return compactObject({
+    protocol: PACTIUM_PROTOCOL,
+    layer,
+    code,
+    severity,
+    message,
+    evidenceRef,
+    repairable,
+    details: Object.keys(asRecord(details)).length > 0 ? asRecord(details) : undefined
+  });
+}
+
+export class PactiumLifecycleError extends Error {
+  constructor(message, failure) {
+    super(message);
+    this.name = "PactiumLifecycleError";
+    this.failure = failure;
+  }
+}