@hilbras/omninode 2.0.0-alpha.11 → 2.0.0-alpha.12

package/README.md

@@ -18,7 +18,7 @@ existing intelligence; it does not try to become another model.
 
 ## Status
 
-**v2.0.0-alpha.11 — v2 Phase 11: Planner v2**
+**v2.0.0-alpha.12 — v2 Phase 12: Persistence Layer v2**
 (the reliability & interoperability line: architecture → execution →
 protocol → adapters → pipelines → providers → OmniHilbras → memory → reports) (the v2
 roadmap is [docs/ROADMAP_V2.md](docs/ROADMAP_V2.md); the v1 plan is complete:
@@ -31,6 +31,12 @@ for the plan and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design).
 
 ### What's new in v2 (so far)
 
+- **Phase 12 — Persistence Layer v2**: writes are now **fsynced and atomic**
+  (temp → fsync → rename → directory fsync), corrupt store files are
+  **quarantined instead of lost**, documents carry a **schema version** with
+  v1 data migrated in place (`omninode migrate [--check]`), and files from a
+  newer OmniNode are refused rather than misread. Details:
+  [PERSISTENCE.md](docs/PERSISTENCE.md).
 - **Phase 11 — Planner v2**: the planner now receives the full §15 input —
   task, project context, agent reports, **aggregated findings (consensus and
   conflicts included)**, memory and **constraints** (settable per pipeline
@@ -359,7 +365,7 @@ required for the core engine.
 - [Architecture](docs/ARCHITECTURE.md) — module map, workflow, local state
 - [Security model](docs/SECURITY.md) — secrets, process execution, env isolation, audit log
 - [API stability policy](docs/API_STABILITY.md) and [public API inventory](docs/API.md)
-- [Agent Protocol v2 spec](docs/PROTOCOL.md) · [Providers](docs/PROVIDERS.md) · [Memory](docs/MEMORY.md) · [Reports](docs/REPORTS.md) · [Deprecations](docs/DEPRECATIONS.md) · [Changelog](CHANGELOG.md) · [v2 roadmap](docs/ROADMAP_V2.md)
+- [Agent Protocol v2 spec](docs/PROTOCOL.md) · [Providers](docs/PROVIDERS.md) · [Memory](docs/MEMORY.md) · [Reports](docs/REPORTS.md) · [Persistence](docs/PERSISTENCE.md) · [Deprecations](docs/DEPRECATIONS.md) · [Changelog](CHANGELOG.md) · [v2 roadmap](docs/ROADMAP_V2.md)
 - [Example project](examples/demo/) — a runnable end-to-end demo (`./demo.sh`)
 
 Prefer a container? `docker build -t omninode .` then

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { realpathSync } from "fs";
 import { Command } from "commander";
 
 // src/version.ts
-var OMNINODE_VERSION = "2.0.0-alpha.11";
+var OMNINODE_VERSION = "2.0.0-alpha.12";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -2108,51 +2108,119 @@ function registerRoleCommands(program) {
 }
 
 // src/persistence/json-file-store.ts
-import { mkdir, readFile, rename, writeFile } from "fs/promises";
+import { open, mkdir, readFile, rename, stat } from "fs/promises";
 import { dirname } from "path";
+var SCHEMA_VERSION = 2;
+async function writeFileAtomic(target, contents) {
+  const tmp = `${target}.tmp`;
+  await mkdir(dirname(target), { recursive: true });
+  const handle = await open(tmp, "w");
+  try {
+    await handle.writeFile(contents, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await rename(tmp, target);
+  try {
+    const dir = await open(dirname(target), "r");
+    try {
+      await dir.sync();
+    } finally {
+      await dir.close();
+    }
+  } catch {
+  }
+}
+async function inspectDocument(path) {
+  let raw;
+  try {
+    await stat(path);
+  } catch {
+    return { status: "missing" };
+  }
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    return { status: "corrupt", detail: `unreadable: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (raw.trim().length === 0) return { status: "empty" };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return { status: "corrupt", detail: error instanceof Error ? error.message : "invalid JSON" };
+  }
+  if (Array.isArray(parsed)) return { status: "v1-legacy" };
+  if (parsed === null || typeof parsed !== "object") return { status: "corrupt", detail: "not an object" };
+  const doc = parsed;
+  if (!Array.isArray(doc.items)) return { status: "corrupt", detail: "missing items array" };
+  const version = typeof doc.schemaVersion === "number" ? doc.schemaVersion : 1;
+  if (version > SCHEMA_VERSION) return { status: "future", schemaVersion: version };
+  if (version < SCHEMA_VERSION) return { status: "v1-legacy" };
+  return { status: "current", schemaVersion: version, count: doc.items.length };
+}
+async function readDocument(path, onCorrupt, quarantine = true) {
+  const state = await inspectDocument(path);
+  if (state.status === "missing" || state.status === "empty") return [];
+  if (state.status === "future") {
+    const error = new Error(
+      `${path} was written by a newer OmniNode (schema v${state.schemaVersion} > v${SCHEMA_VERSION})`
+    );
+    onCorrupt?.(path, error);
+    return [];
+  }
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    onCorrupt?.(path, error);
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed;
+    return parsed.items ?? [];
+  } catch (error) {
+    if (quarantine) {
+      const quarantinePath = `${path}.corrupt-${Date.now()}`;
+      try {
+        await rename(path, quarantinePath);
+        logger.child({ component: "persistence" }).warn(
+          `Quarantined unreadable store file ${path} \u2192 ${quarantinePath}`
+        );
+      } catch {
+      }
+    }
+    onCorrupt?.(path, error);
+    return [];
+  }
+}
 var JsonFileStore = class {
   filePath;
   schemaVersion;
   onCorrupt;
+  quarantine;
   log;
   queue = Promise.resolve();
   constructor(options) {
     this.filePath = `${options.directory ?? `${process.cwd()}/.omninode`}/${options.fileName}`;
-    this.schemaVersion = options.schemaVersion ?? 1;
+    this.schemaVersion = options.schemaVersion ?? SCHEMA_VERSION;
     this.onCorrupt = options.onCorrupt;
+    this.quarantine = options.quarantine ?? true;
     this.log = logger.child({ component: "persistence", file: options.fileName });
   }
   get path() {
     return this.filePath;
   }
-  /** All items, or [] when missing/corrupt. */
+  /** All items, or [] when missing/migrated-from-v1/corrupt. */
   async readAll() {
-    let raw;
-    try {
-      raw = await readFile(this.filePath, "utf8");
-    } catch {
-      return [];
-    }
-    try {
-      const parsed = JSON.parse(raw);
-      if (Array.isArray(parsed)) return parsed;
-      if (parsed !== null && typeof parsed === "object" && Array.isArray(parsed.items)) {
-        return parsed.items;
-      }
-      throw new Error("persisted file has an unrecognized shape");
-    } catch (error) {
-      this.log.warn(`Treating ${this.filePath} as empty \u2014 it could not be parsed.`);
-      this.onCorrupt?.(this.filePath, error);
-      return [];
-    }
+    return readDocument(this.filePath, this.onCorrupt, this.quarantine);
   }
   async writeAll(items) {
     const document = { schemaVersion: this.schemaVersion, items };
-    const tmp = `${this.filePath}.tmp`;
-    await mkdir(dirname(this.filePath), { recursive: true });
-    await writeFile(tmp, `${JSON.stringify(document, null, 2)}
-`, "utf8");
-    await rename(tmp, this.filePath);
+    await writeFileAtomic(this.filePath, `${JSON.stringify(document, null, 2)}
+`);
   }
   /** Serializes an async operation against this file. */
   synchronized(operation) {
@@ -2455,7 +2523,7 @@ function sleep(ms) {
 }
 
 // src/audit/index.ts
-import { appendFile, mkdir as mkdir2 } from "fs/promises";
+import { mkdir as mkdir2, readFile as readFile2 } from "fs/promises";
 import { dirname as dirname2 } from "path";
 var FileAuditLog = class {
   filePath;
@@ -2467,8 +2535,15 @@ var FileAuditLog = class {
   async record(event) {
     try {
       await mkdir2(dirname2(this.filePath), { recursive: true });
-      await appendFile(this.filePath, `${JSON.stringify(event)}
+      const { open: open2 } = await import("fs/promises");
+      const handle = await open2(this.filePath, "a");
+      try {
+        await handle.appendFile(`${JSON.stringify(event)}
 `, "utf8");
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
     } catch (error) {
       this.log.warn(
         `Audit write failed: ${error instanceof Error ? error.message : String(error)}`
@@ -2477,7 +2552,6 @@ var FileAuditLog = class {
   }
   /** Recent events, oldest first; used by the CLI. */
   async recent(limit = 20) {
-    const { readFile: readFile2 } = await import("fs/promises");
     let raw;
     try {
       raw = await readFile2(this.filePath, "utf8");
@@ -4809,6 +4883,78 @@ function registerAuditCommand(program) {
   });
 }
 
+// src/persistence/index.ts
+var STORE_FILES = [
+  "tasks.json",
+  "pipelines.json",
+  "reports.json",
+  "plans.json",
+  "memory.json"
+];
+async function migrateProjectStores(directory = `${process.cwd()}/.omninode`, options = {}) {
+  const reports = [];
+  for (const file of STORE_FILES) {
+    const path = `${directory}/${file}`;
+    const state = await inspectDocument(path);
+    if (state.status === "missing") {
+      reports.push({ file, state: state.status, migrated: false });
+      continue;
+    }
+    if (state.status === "current") {
+      reports.push({ file, state: state.status, before: state.count, after: state.count, migrated: false });
+      continue;
+    }
+    if (state.status === "future") {
+      reports.push({
+        file,
+        state: state.status,
+        migrated: false,
+        note: `written by a newer OmniNode (schema v${state.schemaVersion}); not touched`
+      });
+      continue;
+    }
+    if (state.status === "corrupt") {
+      reports.push({ file, state: state.status, migrated: false, note: state.detail });
+      continue;
+    }
+    const items = await readDocument(path, void 0, false);
+    if (!options.checkOnly) {
+      await writeFileAtomic(path, `${JSON.stringify({ schemaVersion: SCHEMA_VERSION, items }, null, 2)}
+`);
+    }
+    const beforeCount = items.length;
+    reports.push({
+      file,
+      state: state.status,
+      before: beforeCount,
+      after: items.length,
+      migrated: !options.checkOnly,
+      ...options.checkOnly ? { note: "would migrate" } : {}
+    });
+  }
+  return reports;
+}
+
+// src/cli/commands/migrate.ts
+function registerMigrateCommand(program) {
+  program.command("migrate").description(
+    `Inspect and upgrade persisted store files to schema v${SCHEMA_VERSION} (v1 data is migrated in place).`
+  ).option("--check", "Only report what would change; do not write.").action(async (options) => {
+    const reports = await migrateProjectStores(`${process.cwd()}/.omninode`, {
+      checkOnly: options.check ?? false
+    });
+    let changed = 0;
+    for (const report of reports) {
+      if (report.migrated || report.state === "v1-legacy") changed += 1;
+      const detail = report.state === "corrupt" ? `  (corrupt: ${report.note})` : report.state === "future" ? `  (${report.note})` : report.state === "v1-legacy" ? `  ${report.migrated ? "migrated" : "would migrate"} ${report.before ?? 0} \u2192 ${report.after ?? 0} item(s)` : report.state === "current" ? `  ${report.after ?? 0} item(s)` : "";
+      console.log(`${report.file.padEnd(16)} ${report.state}${detail}`);
+    }
+    console.log(
+      changed === 0 ? `All stores are at schema v${SCHEMA_VERSION}.` : `${options.check ? "Would migrate" : "Migrated"} ${changed} store file(s) to schema v${SCHEMA_VERSION}.`
+    );
+  });
+}
+
 // src/cli/index.ts
 function createProgram() {
   const program = new Command();
@@ -4828,6 +4974,7 @@ function createProgram() {
   registerPlanCommands(program);
   registerStatusCommand(program);
   registerAuditCommand(program);
+  registerMigrateCommand(program);
   registerRunAlias(program);
   return program;
 }