@viloforge/vfkb 0.5.0 → 0.6.0

package/dist/bundles/vfkb-mcp.mjs

@@ -32021,7 +32021,7 @@ function queryExplained(opts = {}) {
 }
 
 // src/version.ts
-var ENGINE_VERSION = true ? "0.5.0" : ownPackageVersion();
+var ENGINE_VERSION = true ? "0.6.0" : ownPackageVersion();
 
 // src/mcp-server.ts
 var SEARCH_DEFAULT_LIMIT = 25;

package/dist/bundles/vfkb.mjs

@@ -16091,8 +16091,8 @@ import { dirname as dirname5, join as join8 } from "node:path";
 
 // src/version.ts
 var SCHEMA_VERSION = 1;
-var ENGINE_VERSION = true ? "0.5.0" : ownPackageVersion();
-var ENGINE_COMMIT = true ? "aeaa5fa" : "dev";
+var ENGINE_VERSION = true ? "0.6.0" : ownPackageVersion();
+var ENGINE_COMMIT = true ? "9921586" : "dev";
 
 // src/manifest.ts
 function manifestPath(brainDir2) {
@@ -16850,7 +16850,8 @@ function initProject(root, opts = {}) {
       ".vfkb/.sessions/",
       ".vfkb/.signals/",
       ".vfkb/.journal/",
-      ".vfkb/.lock"
+      ".vfkb/.lock",
+      ".vfkb/.write-probe-*"
     ];
     const HEADER = [
       "# vfkb \u2014 entries.jsonl + manifest.json (the ADR-0030 engine stamp) are committed;",
@@ -16925,7 +16926,8 @@ function approvalNotice(project) {
 
 // src/doctor.ts
 import { execFileSync as execFileSync6 } from "node:child_process";
-import { existsSync as existsSync10, readFileSync as readFileSync11, writeFileSync as writeFileSync6, mkdirSync as mkdirSync8, realpathSync } from "node:fs";
+import { randomBytes as randomBytes3 } from "node:crypto";
+import { existsSync as existsSync10, readFileSync as readFileSync11, writeFileSync as writeFileSync6, mkdirSync as mkdirSync8, realpathSync, unlinkSync as unlinkSync2 } from "node:fs";
 import { join as join14, dirname as dirname6, relative as relative3, resolve as resolve4, isAbsolute as isAbsolute2 } from "node:path";
 function readJson2(path) {
   if (!existsSync10(path)) return void 0;
@@ -17193,6 +17195,29 @@ function runDoctor(opts) {
       add("engine drift", "warn", `brain last stamped by engine ${mf.engine_commit}, running ${runningCommit} \u2014 possible dual-clone drift`);
     }
   }
+  {
+    const probe = join14(brainDir2, `.write-probe-${process.pid}-${randomBytes3(4).toString("hex")}`);
+    const payload = `vfkb write-probe ${process.pid} ${Date.now()}`;
+    let failure;
+    try {
+      mkdirSync8(brainDir2, { recursive: true });
+      writeFileSync6(probe, payload);
+      if (readFileSync11(probe, "utf8") !== payload) failure = "wrote the probe file but read back different bytes";
+    } catch (e) {
+      failure = e.message;
+    } finally {
+      try {
+        if (existsSync10(probe)) unlinkSync2(probe);
+      } catch {
+      }
+    }
+    const SCOPE = " \u2014 scope: this is the CLI/engine/filesystem path only; it does NOT check the MCP server, so it cannot tell you whether kb_* capture is reaching the brain (ADR-0065 \xA70: a hung MCP server loses a write with no error at all)";
+    if (failure) {
+      add("write-health (filesystem)", "fail", `cannot write to ${brainDir2}: ${failure}${SCOPE}`);
+    } else {
+      add("write-health (filesystem)", "ok", `round-trip verified in ${brainDir2}${SCOPE}`);
+    }
+  }
   {
     const js = journalStatus(brainDir2);
     if (js.suppressedInEntries > 0) {

package/dist/doctor.js

@@ -3,7 +3,8 @@
 // or inconsistent wiring, and the dual-clone drift signal (a brain last stamped by
 // a different engine build). Deterministic; unit-tested (the inner gate per ADR-0023).
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync, unlinkSync } from 'node:fs';
 import { join, dirname, relative, resolve, isAbsolute } from 'node:path';
 import { SCHEMA_VERSION, ENGINE_VERSION, ENGINE_COMMIT } from './version.js';
 import { journalStatus } from './journal.js';
@@ -438,6 +439,65 @@ export function runDoctor(opts) {
             add('engine drift', 'warn', `brain last stamped by engine ${mf.engine_commit}, running ${runningCommit} — possible dual-clone drift`);
         }
     }
+    // 2a-bis. Write-health (ADR-0065 §2): can the engine actually write here?
+    //
+    // Round-trips a NON-entries file. `entries.jsonl` is append-only — there is no
+    // "append then remove" (the only delete is a tombstone, two permanent lines
+    // per doctor run), and a probe namespace inside it would dirty the working
+    // tree and grow the committed log on every invocation.
+    //
+    // SCOPE, and it is the whole difficulty. §0 observed that the failure which
+    // actually loses writes is a HUNG MCP server: the process is alive and mute,
+    // the call never returns, nothing errors (scenarios/probes/mcp-disconnect.md).
+    // Doctor is the CLI face and cannot see that at all. So a true "write-health
+    // ok" here is exactly the kind of statement a reader over-reads into "my
+    // capture is fine" — the 6ad98196b5a2 failure, where a diagnostic was made
+    // more CONFIDENT rather than more TRUE and an L4 went green because the claim
+    // became more quotable. The scope caveat below is therefore part of the
+    // behaviour, not decoration, and is pinned by test/doctor-write-health.test.ts.
+    {
+        // UNIQUE per run: with a fixed path, two doctors racing read each other's
+        // bytes and report "read back different bytes" — a false alarm of silent
+        // disk corruption, and report.ok=false exits 1 (reproduced: 4 processes x
+        // 200 runs, review of #228).
+        const probe = join(brainDir, `.write-probe-${process.pid}-${randomBytes(4).toString('hex')}`);
+        const payload = `vfkb write-probe ${process.pid} ${Date.now()}`;
+        let failure;
+        try {
+            mkdirSync(brainDir, { recursive: true });
+            writeFileSync(probe, payload);
+            // Read BACK: a write that silently no-ops (a full disk, an overlay that
+            // swallows writes) must not read as healthy.
+            if (readFileSync(probe, 'utf8') !== payload)
+                failure = 'wrote the probe file but read back different bytes';
+        }
+        catch (e) {
+            failure = e.message;
+        }
+        finally {
+            try {
+                if (existsSync(probe))
+                    unlinkSync(probe);
+            }
+            catch {
+                /* leaving the probe behind is not itself a write-health failure */
+            }
+        }
+        // §0 consequence #3 says a §2 design needs its own timeout or it inherits
+        // the hang. These are synchronous fs calls: on a wedged NFS/FUSE mount they
+        // block indefinitely and so does doctor. Named, not silently dropped — the
+        // bounded-round-trip requirement targets an MCP-probing design, which this
+        // deliberately is not.
+        const SCOPE = ' — scope: this is the CLI/engine/filesystem path only; it does NOT check the MCP server, ' +
+            'so it cannot tell you whether kb_* capture is reaching the brain (ADR-0065 §0: a hung MCP ' +
+            'server loses a write with no error at all)';
+        if (failure) {
+            add('write-health (filesystem)', 'fail', `cannot write to ${brainDir}: ${failure}${SCOPE}`);
+        }
+        else {
+            add('write-health (filesystem)', 'ok', `round-trip verified in ${brainDir}${SCOPE}`);
+        }
+    }
     // 2b. Durable-capture journal (ADR-0064): what would recovery do, and is a
     // redaction half-done? Read-only — recovery itself runs at session start.
     {

package/dist/init.js

@@ -213,6 +213,7 @@ export function initProject(root, opts = {}) {
             '.vfkb/.signals/',
             '.vfkb/.journal/',
             '.vfkb/.lock',
+            '.vfkb/.write-probe-*',
         ];
         // The header the stanza should carry. The OLD one claimed "only
         // .vfkb/entries.jsonl is committed", which is FALSE — manifest.json is

package/dist/init.test.js

@@ -66,7 +66,7 @@ describe('vfkb init (FR-1)', () => {
         it('ignores every derived/operational path, including the lock', () => {
             initProject(root, { project: 'demo' });
             const gi = read('.gitignore');
-            for (const p of ['.vfkb/index-meta.json', '.vfkb/.sessions/', '.vfkb/.signals/', '.vfkb/.journal/', '.vfkb/.lock']) {
+            for (const p of ['.vfkb/index-meta.json', '.vfkb/.sessions/', '.vfkb/.signals/', '.vfkb/.journal/', '.vfkb/.lock', '.vfkb/.write-probe-*']) {
                 expect(gi, `missing ignore rule ${p}`).toContain(p);
             }
         });
@@ -96,7 +96,7 @@ describe('vfkb init (FR-1)', () => {
                     return false;
                 }
             };
-            for (const p of ['.vfkb/.lock', '.vfkb/.journal/wal.jsonl', '.vfkb/index-meta.json', '.vfkb/.sessions/x', '.vfkb/.signals/y']) {
+            for (const p of ['.vfkb/.lock', '.vfkb/.journal/wal.jsonl', '.vfkb/index-meta.json', '.vfkb/.sessions/x', '.vfkb/.signals/y', '.vfkb/.write-probe-123-abc']) {
                 expect(ignored(p), `${p} should be ignored`).toBe(true);
             }
             // The brain and the ADR-0030 engine stamp MUST stay committable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viloforge/vfkb",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "ViloForge KnowledgeBase (vfkb) — per-project knowledge substrate for the ViloForge software factory. Greenfield TypeScript.",
   "type": "module",
   "main": "dist/engine.js",