@warpgogol/werkstatt-shared 0.14.1 → 0.15.0

package/src/kernel/fs-atomic.ts

@@ -0,0 +1,131 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0258: atomic file-write primitive for workspace-shared kernel-command
+  outputs. Every kernel command that writes a file outside its target app
+  directory (workspace root, docs/, packages/ontology/) MUST write through
+  writeFileAtomic instead of node:fs/promises writeFile, so that a reader
+  polling the target path never observes a torn/partial file when Turborepo
+  runs multiple app builds in parallel.
+</purpose>
+<non-goals>
+  <item>Do not provide cross-process mutual exclusion (locks) — outputs are deterministic (RFC-0087), so convergent atomic writes are sufficient.</item>
+  <item>Do not fall back to a non-atomic write when retries are exhausted — fail loudly instead.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>Writes go through temp-file plus rename — readers never observe partial content.</item>
+  <item>Canonical implementation lives in @warpgogol/forge — this is a compatibility re-export.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>RFC-0258: initial implementation.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { writeFile, rename as fsRename, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, basename } from "node:path";
+import { randomBytes } from "node:crypto";
+
+export interface WriteFileAtomicOptions {
+  /** Max rename retries on transient EPERM/EBUSY. Default 10, linear 50ms backoff. */
+  retries?: number;
+}
+
+// Indirection seam so unit tests can simulate a transient EPERM/EBUSY
+// on the first rename attempt without monkey-patching the frozen node:fs/promises
+// module namespace (ESM named exports are read-only bindings). Production code
+// always goes through fsRename; only tests in this package call the setter.
+let renameImpl: typeof fsRename = fsRename;
+
+/** @internal test-only seam — do not call from production code. */
+export function __setRenameImplForTests(impl: typeof fsRename | undefined): void {
+  renameImpl = impl ?? fsRename;
+}
+
+const DEFAULT_RETRIES = 10;
+const RETRY_BACKOFF_MS = 50;
+
+const RETRYABLE_CODES = new Set(["EPERM", "EBUSY"]);
+
+function isRetryableError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const code = (error as NodeJS.ErrnoException).code;
+  return typeof code === "string" && RETRYABLE_CODES.has(code);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function makeTempPath(filePath: string): string {
+  const dir = dirname(filePath);
+  const name = basename(filePath);
+  const random = randomBytes(6).toString("hex");
+  return join(dir, `${name}.${random}.tmp`);
+}
+
+/**
+ * Write `content` to `filePath` atomically: write to a temp file in the same
+ * directory, then rename over the target. Rename within one directory is
+ * atomic on POSIX; a bounded retry loop absorbs transient EPERM/EBUSY
+ * (e.g. a reader briefly holding the file handle during overwrite).
+ *
+ * On failure (write or all rename retries exhausted), the temp file is
+ * unlinked in a finally block and the original error is rethrown — this
+ * helper never falls back to a non-atomic write.
+ */
+export async function writeFileAtomic(
+  filePath: string,
+  content: string | Uint8Array,
+  options?: WriteFileAtomicOptions,
+): Promise<void> {
+  const retries = options?.retries ?? DEFAULT_RETRIES;
+  const tempPath = makeTempPath(filePath);
+  let tempWritten = false;
+
+  try {
+    await writeFile(tempPath, content);
+    tempWritten = true;
+
+    let attempt = 0;
+    // Bounded retry loop: attempt 0 is the first try, then up to `retries` more.
+    for (;;) {
+      try {
+        await renameImpl(tempPath, filePath);
+        return;
+      } catch (error) {
+        if (attempt >= retries || !isRetryableError(error)) {
+          throw error;
+        }
+        attempt += 1;
+        // EPERM on rename-over-existing: try unlinking the target
+        // first (it may have been briefly locked by a reader that has since
+        // released it), then retry the rename on the next iteration.
+        if (existsSync(filePath)) {
+          try {
+            await unlink(filePath);
+          } catch {
+            // If unlink also fails, the retry loop will try again.
+          }
+        }
+        await sleep(RETRY_BACKOFF_MS * attempt);
+      }
+    }
+  } finally {
+    if (tempWritten) {
+      try {
+        // If rename succeeded, the temp file no longer exists — unlink is a no-op error we swallow.
+        await unlink(tempPath);
+      } catch {
+        // Expected in the success path (temp file already renamed away) — ignore.
+      }
+    }
+  }
+}

package/src/kernel/index.ts

@@ -0,0 +1,15 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>Barrel export for @warpgogol/werkstatt-shared/kernel sub-path. Re-exports the kernel contract cluster (command/pipeline types, workspace IO, atomic fs, desired state, diagnostic schemas) sunk from @warpgogol/werkstatt-engine per RFC-1104.</purpose>
+  <non-goals>Does not re-export engine runtime modules (executor, module registry, CLI).</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1104: initial barrel — kernel contract cluster sunk from werkstatt-engine.</item>
+</CHANGE_SUMMARY>
+*/
+
+export * from "./types.ts";
+export * from "./workspace-io.ts";
+export * from "./fs-atomic.ts";
+export * from "./desired-state.ts";
+export * from "./diagnostic.ts";

package/src/kernel/tests/fs-atomic.test.ts

@@ -0,0 +1,150 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>
+    RFC-0258 unit tests for writeFileAtomic, written before the workspace-shared
+    writer migration per the RFC's own rollout order.
+  </purpose>
+  <responsibilities>
+    <item>Content lands intact after a single write.</item>
+    <item>A reader polling the target during many sequential writes never observes a partial file.</item>
+    <item>The temp file is removed when the write ultimately fails.</item>
+    <item>A simulated Windows EPERM on the first rename attempt is retried and succeeds.</item>
+  </responsibilities>
+  <non-goals>
+    <item>Do not cover the workspace-write-boundary lint here — see workspace-write-boundary.test.ts in site-kernel-checks.</item>
+  </non-goals>
+</MODULE_CONTRACT>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { test, expect } from "vitest";
+import { writeFileAtomic, __setRenameImplForTests } from "../fs-atomic.ts";
+
+async function makeTmpDir(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), "fs-atomic-"));
+}
+
+test("writeFileAtomic: content lands intact", async () => {
+  const dir = await makeTmpDir();
+  try {
+    const target = path.join(dir, "out.json");
+    const content = JSON.stringify({ hello: "world", n: 42 }, null, 2);
+    await writeFileAtomic(target, content);
+    const read = await fs.readFile(target, "utf8");
+    expect(read).toBe(content);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("writeFileAtomic: no leftover temp files after a successful write", async () => {
+  const dir = await makeTmpDir();
+  try {
+    const target = path.join(dir, "out.json");
+    await writeFileAtomic(target, "content");
+    const entries = await fs.readdir(dir);
+    expect(entries).toEqual(["out.json"]);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("writeFileAtomic: a reader polling the target during 200 sequential writes never observes a partial file", async () => {
+  const dir = await makeTmpDir();
+  try {
+    const target = path.join(dir, "shared.json");
+    const totalWrites = 200;
+    let stop = false;
+    let observedPartial = false;
+    let observedCount = 0;
+
+    // Each write produces a distinct, fully-valid JSON payload of a known shape.
+    function payloadFor(i: number): string {
+      return JSON.stringify({ seq: i, marker: "X".repeat(32) }) + "\n";
+    }
+
+    const writer = (async () => {
+      for (let i = 0; i < totalWrites; i++) {
+        // A polling reader sharing the event loop can still collide with the
+        // rename often enough to exceed the production default's 5-retry
+        // budget on Windows. Widen the retry budget for this synthetic
+        // worst-case poll loop only; the production default stays 5 (RFC-0258).
+        await writeFileAtomic(target, payloadFor(i), { retries: 80 });
+      }
+      stop = true;
+    })();
+
+    const reader = (async () => {
+      while (!stop) {
+        let raw: string | undefined;
+        try {
+          raw = await fs.readFile(target, "utf8");
+        } catch {
+          // Target may not exist yet at the very start — not a partial-read failure.
+          await new Promise((resolve) => setImmediate(resolve));
+          continue;
+        }
+        observedCount += 1;
+        try {
+          const parsed = JSON.parse(raw) as { seq: number; marker: string };
+          if (parsed.marker !== "X".repeat(32)) {
+            observedPartial = true;
+          }
+        } catch {
+          observedPartial = true;
+        }
+        // Yield once per read so this is a fast, realistic poller rather than
+        // a worst-case tight spin that starves the writer's rename retries.
+        await new Promise((resolve) => setImmediate(resolve));
+      }
+    })();
+
+    await Promise.all([writer, reader]);
+
+    expect(observedPartial).toBe(false);
+    expect(observedCount > 0).toBeTruthy();
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("writeFileAtomic: temp file is removed when the write ultimately fails", async () => {
+  const dir = await makeTmpDir();
+  try {
+    // Target directory does not exist -> the temp-file write itself fails,
+    // and no temp file should remain in `dir`.
+    const target = path.join(dir, "missing-subdir", "out.json");
+    await expect(() => writeFileAtomic(target, "content")).rejects.toThrow();
+    const entries = await fs.readdir(dir);
+    expect(entries).toEqual([]);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("writeFileAtomic: simulated EPERM on first rename attempt is retried and succeeds", async () => {
+  const dir = await makeTmpDir();
+  try {
+    const target = path.join(dir, "out.json");
+    let calls = 0;
+    __setRenameImplForTests(async (...args: Parameters<typeof fs.rename>) => {
+      calls += 1;
+      if (calls === 1) {
+        const error = new Error("simulated EPERM") as NodeJS.ErrnoException;
+        error.code = "EPERM";
+        throw error;
+      }
+      return fs.rename(...args);
+    });
+
+    await writeFileAtomic(target, "content", { retries: 5 });
+    expect(calls >= 2).toBeTruthy();
+    const read = await fs.readFile(target, "utf8");
+    expect(read).toBe("content");
+  } finally {
+    __setRenameImplForTests(undefined);
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});

package/src/kernel/tests/workspace-io.test.ts

@@ -0,0 +1,187 @@
+import { test, expect } from "vitest";
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createDefaultIO,
+  createRecordingIO,
+  createReadOnlyIO,
+  KernelMetaError,
+} from "../workspace-io.ts";
+
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0267: port + adapter tests, written before wiring into the executor.
+  Recording adapter captures intents and never touches disk (fs spy via a
+  real temp directory). Read-only adapter throws KERNEL-META-01 naming the
+  command and path on any mutation. Default adapter writes atomically
+  (delegates to writeFileAtomic, rfc-0258 — proven by "no partial content"
+  and "no leftover temp file" after a successful write).
+</purpose>
+</MODULE_CONTRACT>
+*/
+
+test("createDefaultIO: writeFile creates the file with exact content, no leftover temp file", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-default-"));
+  try {
+    const { io } = createDefaultIO();
+    const target = join(root, "nested", "file.txt");
+    await io.writeFile(target, "hello world");
+
+    const content = await readFile(target, "utf8");
+    expect(content).toBe("hello world");
+
+    const entries = await import("node:fs/promises").then((fs) => fs.readdir(join(root, "nested")));
+    expect(entries).toEqual(["file.txt"]);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("createDefaultIO: exists/readFile/mkdir/rm round-trip", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-default2-"));
+  try {
+    const { io } = createDefaultIO();
+    expect(await io.exists(join(root, "missing.txt"))).toBe(false);
+
+    await io.mkdir(join(root, "dir"));
+    expect(await io.exists(join(root, "dir"))).toBe(true);
+
+    await io.writeFile(join(root, "dir", "a.txt"), "a");
+    expect(await io.readFile(join(root, "dir", "a.txt"))).toBe("a");
+
+    await io.rm(join(root, "dir"), { recursive: true });
+    expect(await io.exists(join(root, "dir"))).toBe(false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("createDefaultIO: readdir returns port-neutral DirEntry[] with isFile/isDirectory booleans", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-readdir-"));
+  try {
+    const { io } = createDefaultIO();
+    await io.writeFile(join(root, "a.md"), "content");
+    await io.mkdir(join(root, "subdir"));
+
+    const entries = (await io.readdir(root)).sort((x, y) => x.name.localeCompare(y.name));
+    expect(entries).toEqual([
+      { name: "a.md", isFile: true, isDirectory: false },
+      { name: "subdir", isFile: false, isDirectory: true },
+    ]);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("createReadOnlyIO and createRecordingIO: readdir passes through (a read, not a mutation)", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-readdir-passthrough-"));
+  try {
+    const { io: base } = createDefaultIO();
+    await base.writeFile(join(root, "x.txt"), "x");
+
+    const readOnly = createReadOnlyIO(base, "fixture.readonly.command");
+    expect((await readOnly.readdir(root))[0]?.name).toBe("x.txt");
+
+    const { io: recording } = createRecordingIO(base);
+    expect((await recording.readdir(root))[0]?.name).toBe("x.txt");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("createRecordingIO: captures write/mkdir/rm intents and never touches disk", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-recording-"));
+  try {
+    const { io: base } = createDefaultIO();
+    const { io, intents } = createRecordingIO(base);
+
+    const target = join(root, "would-write.txt");
+    await io.writeFile(target, "some content");
+    await io.mkdir(join(root, "would-mkdir"));
+    await io.rm(join(root, "would-rm"));
+
+    expect(intents.length).toBe(3);
+    expect(intents.map((i) => i.kind)).toEqual(["write", "mkdir", "rm"]);
+    expect(intents[0]?.path).toBe(target);
+    expect(intents[0]?.bytes).toBe(Buffer.byteLength("some content", "utf8"));
+
+    // Nothing was actually written.
+    await expect(() => stat(target)).rejects.toThrow();
+    const rootEntries = await import("node:fs/promises").then((fs) => fs.readdir(root));
+    expect(rootEntries).toEqual([]);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("createRecordingIO: reads pass through to the base adapter", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-recording-reads-"));
+  try {
+    const { io: base } = createDefaultIO();
+    await base.writeFile(join(root, "existing.txt"), "real content");
+
+    const { io } = createRecordingIO(base);
+    expect(await io.exists(join(root, "existing.txt"))).toBe(true);
+    expect(await io.readFile(join(root, "existing.txt"))).toBe("real content");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("createReadOnlyIO: throws KERNEL-META-01 naming the command and path on writeFile", async () => {
+  const io = createReadOnlyIO(createDefaultIO().io, "fixture.readonly.command");
+  try {
+    await io.writeFile("/tmp/should-not-write.txt", "x");
+    expect.fail("should have thrown");
+  } catch (error) {
+    expect(error).toBeInstanceOf(KernelMetaError);
+    expect((error as Error).message).toMatch(/KERNEL-META-01/);
+    expect((error as Error).message).toMatch(/fixture\.readonly\.command/);
+    expect((error as Error).message).toMatch(/should-not-write\.txt/);
+  }
+});
+
+test("createReadOnlyIO: throws on mkdir, rm, and exec too", async () => {
+  const io = createReadOnlyIO(createDefaultIO().io, "fixture.readonly.command");
+  await expect(() => io.mkdir("/tmp/nope")).rejects.toThrow(KernelMetaError);
+  await expect(() => io.rm("/tmp/nope")).rejects.toThrow(KernelMetaError);
+  await expect(() => io.exec("rm", ["-rf", "/tmp/nope"])).rejects.toThrow(KernelMetaError);
+});
+
+test("createReadOnlyIO: reads still work", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-readonly-reads-"));
+  try {
+    const { io: base } = createDefaultIO();
+    await base.writeFile(join(root, "readable.txt"), "readable content");
+
+    const io = createReadOnlyIO(base, "fixture.readonly.command");
+    expect(await io.exists(join(root, "readable.txt"))).toBe(true);
+    expect(await io.readFile(join(root, "readable.txt"))).toBe("readable content");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+// RFC-0326: createDefaultIO now returns { io, intents } — the intents array
+// captures every mutation (write/mkdir/rm) for filesModified reporting.
+test("createDefaultIO: captures write/mkdir/rm intents while writing to real disk (RFC-0326)", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-default-intents-"));
+  try {
+    const { io, intents } = createDefaultIO();
+
+    await io.writeFile(join(root, "file.txt"), "content");
+    await io.mkdir(join(root, "subdir"));
+    await io.rm(join(root, "subdir"), { recursive: true });
+
+    expect(intents.length).toBe(3);
+    expect(intents.map((i) => i.kind)).toEqual(["write", "mkdir", "rm"]);
+    expect(intents[0]?.bytes).toBe(Buffer.byteLength("content", "utf8"));
+
+    // File was actually written to disk (this is the real adapter, not recording).
+    expect(await io.readFile(join(root, "file.txt"))).toBe("content");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});