knosky 0.6.3 → 0.7.0

package/core/CONTRACT.md

@@ -1,70 +1,70 @@
-# Knowledge City — Data Contract v2 (the shared spine)
-
-> Phase 1a deliverable (SAT-385 → build). The one schema both faces (City + MCP) and every source
-> (fs/github/board) depend on. Generalizes the fixed-4-district v1 → **N categories**. Pointers +
-> projections ONLY — never file bodies (D-146). Council fixes baked in: a serialization **allowlist** + a
-> best-effort **denylist scrub**. Proven to represent the current live city losslessly.
-
-## Envelope
-```jsonc
-{
-  "schema_version": "2.0",
-  "generated_at": "<ISO8601>",
-  "source": { "kind": "fs|github|board|legacy", "ref": "<path/repo>", "rev": "<commit/rev>" },
-  "categories": [ { "id": "technical", "label": "Technical", "color": "#4f8cff", "order": 0 } ],
-  "node_count": 150,
-  "nodes": [ /* Node[] */ ]
-}
-```
-`categories[]` is the **N-category manifest** that replaces the hardcoded 4 districts — the renderer derives
-its districts/colors from this, so the board scales to however many categories a source has.
-
-## Node
-```jsonc
-{
-  "id": "decision:D-146",          // stable, source-derived
-  "kind": "decision|spec|file|dir|doc|...",
-  "title": "Index, not copy",      // projection
-  "summary": "<= 200 chars",       // projection (excerpt, never full body)
-  "category": "governance",        // category id (was "district")
-  "status": "locked",              // optional
-  "fact_date": "2026-06-19",       // optional
-  "tags": [],                      // optional projection
-  "headings": [],                  // optional projection (for nav/search)
-  "links": ["decision:D-147"],     // edges to other node ids
-  "provenance": { "store": "...", "ref": "...", "source_rev": "...", "fetched_at": "..." },
-  "visibility": "internal|public",
-  "sensitive": false               // scrub/flag marker
-}
-```
-Required: `id, kind, title, category, links, provenance`. Provenance required: `store, ref`.
-
-## Serialization allowlist (council fix)
-Only these node fields may **ever** be written into the index:
-`id, kind, title, summary, category, status, fact_date, tags, headings, links, provenance, visibility, sensitive`.
-The serializer drops anything else and the validator **fails** on any non-allowlisted field — this is the
-structural guard against a file `body` ever leaking into the index.
-
-## PII scrub (best-effort — NOT a security boundary)
-Applied to every emitted text projection (title/summary/headings/tags): redact emails, `key|secret|token|password|bearer` assignments, AWS access-key IDs, private-key headers → `[REDACTED]`. The indexer also skips
-`.git`, `node_modules`, `secrets/`, `keys/`, `.env*`, `dist/` by default, **plus** the repo's `.gitignore`
-and a user `.kcignore`. Honest framing (per council): this reduces accidental leakage; it is not a guarantee,
-and the local index is readable by the user's own assistant. First-run note will say so.
-
-## Projection limits
-`summary` ≤ 200 chars. No field carries a full file body. Full content is reached only by dereferencing
-`provenance` to the live source (which is what keeps the city fresh — "a map, not a copy").
-
-## Proof (this Phase-1a increment)
-Adapting the current live city (`golden/city-data.golden.json`) through `adaptLegacy()` → contract v2:
-- nodes **150 → 150** (no loss), edges **769 → 769** (no loss)
-- categories derived: `product#0, technical#1, governance#2, design#3`
-- `validateCity()` → **VALID**; scrub positive+negative tests **pass**
-- reference instance written to `golden/city-data.v2.json`
-
-Implementation: `core/contract.mjs` (schema + allowlist + scrub + validator + legacy adapter).
-Reproduce: `node core/validate-golden.mjs`.
-
-## Open at G1 (founder call)
-None on the schema itself (it's proven). Carry-forward decision (Phase 3, not blocking): the **activation
-layer** — council unanimously recommends deferring it to the monetization tier so v1 stays fully offline.
+# Knowledge City — Data Contract v2 (the shared spine)
+
+> Phase 1a deliverable (SAT-385 → build). The one schema both faces (City + MCP) and every source
+> (fs/github/board) depend on. Generalizes the fixed-4-district v1 → **N categories**. Pointers +
+> projections ONLY — never file bodies (D-146). Council fixes baked in: a serialization **allowlist** + a
+> best-effort **denylist scrub**. Proven to represent the current live city losslessly.
+
+## Envelope
+```jsonc
+{
+  "schema_version": "2.0",
+  "generated_at": "<ISO8601>",
+  "source": { "kind": "fs|github|board|legacy", "ref": "<path/repo>", "rev": "<commit/rev>" },
+  "categories": [ { "id": "technical", "label": "Technical", "color": "#4f8cff", "order": 0 } ],
+  "node_count": 150,
+  "nodes": [ /* Node[] */ ]
+}
+```
+`categories[]` is the **N-category manifest** that replaces the hardcoded 4 districts — the renderer derives
+its districts/colors from this, so the board scales to however many categories a source has.
+
+## Node
+```jsonc
+{
+  "id": "decision:D-146",          // stable, source-derived
+  "kind": "decision|spec|file|dir|doc|...",
+  "title": "Index, not copy",      // projection
+  "summary": "<= 200 chars",       // projection (excerpt, never full body)
+  "category": "governance",        // category id (was "district")
+  "status": "locked",              // optional
+  "fact_date": "2026-06-19",       // optional
+  "tags": [],                      // optional projection
+  "headings": [],                  // optional projection (for nav/search)
+  "links": ["decision:D-147"],     // edges to other node ids
+  "provenance": { "store": "...", "ref": "...", "source_rev": "...", "fetched_at": "..." },
+  "visibility": "internal|public",
+  "sensitive": false               // scrub/flag marker
+}
+```
+Required: `id, kind, title, category, links, provenance`. Provenance required: `store, ref`.
+
+## Serialization allowlist (council fix)
+Only these node fields may **ever** be written into the index:
+`id, kind, title, summary, category, status, fact_date, tags, headings, links, provenance, visibility, sensitive`.
+The serializer drops anything else and the validator **fails** on any non-allowlisted field — this is the
+structural guard against a file `body` ever leaking into the index.
+
+## PII scrub (best-effort — NOT a security boundary)
+Applied to every emitted text projection (title/summary/headings/tags): redact emails, `key|secret|token|password|bearer` assignments, AWS access-key IDs, private-key headers → `[REDACTED]`. The indexer also skips
+`.git`, `node_modules`, `secrets/`, `keys/`, `.env*`, `dist/` by default, **plus** the repo's `.gitignore`
+and a user `.kcignore`. Honest framing (per council): this reduces accidental leakage; it is not a guarantee,
+and the local index is readable by the user's own assistant. First-run note will say so.
+
+## Projection limits
+`summary` ≤ 200 chars. No field carries a full file body. Full content is reached only by dereferencing
+`provenance` to the live source (which is what keeps the city fresh — "a map, not a copy").
+
+## Proof (this Phase-1a increment)
+Adapting the current live city (`golden/city-data.golden.json`) through `adaptLegacy()` → contract v2:
+- nodes **150 → 150** (no loss), edges **769 → 769** (no loss)
+- categories derived: `product#0, technical#1, governance#2, design#3`
+- `validateCity()` → **VALID**; scrub positive+negative tests **pass**
+- reference instance written to `golden/city-data.v2.json`
+
+Implementation: `core/contract.mjs` (schema + allowlist + scrub + validator + legacy adapter).
+Reproduce: `node core/validate-golden.mjs`.
+
+## Open at G1 (founder call)
+None on the schema itself (it's proven). Carry-forward decision (Phase 3, not blocking): the **activation
+layer** — council unanimously recommends deferring it to the monetization tier so v1 stays fully offline.

package/core/append-only-checkpoint.mjs

@@ -0,0 +1,215 @@
+// KnoSky F0.2 — Append-only checkpoint (SAT-546).
+//
+// Writes every ledger event to a secondary JSONL checkpoint file that the
+// evaluator process can only append to — it cannot delete or overwrite earlier
+// records.  This gives a second source of truth that a privileged local user
+// would need to destroy to tamper with the record.
+//
+// OS-level append-only protection (best-effort, silently skipped when the
+// operation is not available or the caller lacks privilege):
+//
+//   Linux   : chattr +a (requires CAP_LINUX_IMMUTABLE; typically needs root
+//             or sudo, but conferred when the daemon is started with elevated
+//             rights).  Only sets the attribute — never reads back to verify,
+//             so the evaluator itself never needs elevated rights after the
+//             initial chattr call.
+//   macOS   : chflags uappnd (user-owned append-only flag; can be set by the
+//             file's owner without root).
+//
+// The module NEVER attempts to *remove* the attribute — that would require
+// the same elevated rights and would defeat the purpose.
+//
+// The evaluator calls `appendCheckpointEntry(path, entry)` on every ledger
+// write via the optional `checkpointPath` parameter added to `checkAndAdvance`
+// (core/ledger.mjs) in SAT-561.  It uses
+// `O_WRONLY | O_APPEND | O_CREAT` (no truncation flag) so every open is an
+// append even without the OS attribute.  The OS attribute provides the
+// additional guarantee that a privileged process using O_WRONLY without
+// O_APPEND (or `unlink`) is also blocked.
+//
+// SEPARATION OF CONCERNS (ticket round-3 clarification; PR #62 review, round
+// 5: hardened from a directory-level convention into a PACKAGE-BOUNDARY
+// fact -- the export daemon is not just a different folder, it is a
+// completely separate package/repo this repo has zero dependency on):
+//   - This module is the ONLY checkpoint surface the evaluator touches.
+//   - Any export to a remote destination is handled by the separate
+//     knosky-export-daemon package (github.com/SathiaAI/knosky-export-daemon)
+//     -- an unsandboxed, opt-in daemon an organization must deliberately
+//     install; this repo never imports, requires, or ships any part of it,
+//     and gains no network capability in any configuration regardless of
+//     whether that package is installed elsewhere.
+//
+// Pure Node stdlib, ESM — no third-party dependencies.
+
+import {
+  openSync, appendFileSync, closeSync,
+  mkdirSync, existsSync,
+} from 'node:fs';
+import { dirname, isAbsolute } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { platform } from 'node:os';
+
+// Platform string, cached at module load.
+const PLATFORM = platform();
+
+// ---------------------------------------------------------------------------
+// setAppendOnlyAttribute — best-effort OS attribute
+// ---------------------------------------------------------------------------
+
+/**
+ * Attempt to set the OS append-only attribute on `filePath`.
+ *
+ * Returns a structured result so callers can log the outcome without the
+ * evaluator needing to catch exceptions.  The attribute is advisory — failure
+ * does NOT prevent writes via `appendCheckpointEntry`; the O_APPEND open flag
+ * already ensures append semantics at the process level.
+ *
+ * @param {string} filePath  Absolute path to the checkpoint file.
+ * @returns {{ ok: boolean, mechanism: string|null, skipped: boolean, error: string|null }}
+ */
+export function setAppendOnlyAttribute(filePath) {
+  // PR #62 round-7 fix: enforce the documented contract (filePath must be an
+  // absolute path) before this reaches a privileged child process at all --
+  // rejects relative paths, empty strings, and non-string input up front.
+  if (typeof filePath !== 'string' || filePath.length === 0 || !isAbsolute(filePath)) {
+    return {
+      ok: false,
+      mechanism: null,
+      skipped: true,
+      error: 'invalid filePath: must be a non-empty absolute path',
+    };
+  }
+
+  // PR #62 round-7 fix: distinguish signal-based termination (process was
+  // killed) from a plain non-zero exit, so operators can tell them apart
+  // instead of a single generic error message.
+  const describeFailure = (r, cmdLabel) => {
+    if (r.error) return String(r.error.message || r.error);
+    if (r.signal !== null) return `${cmdLabel} was terminated by signal ${r.signal}`;
+    return `${cmdLabel} exited with status ${r.status}`;
+  };
+
+  if (PLATFORM === 'linux') {
+    // chattr +a — requires CAP_LINUX_IMMUTABLE; best-effort
+    const r = spawnSync('chattr', ['+a', filePath], {
+      stdio: 'ignore',
+      timeout: 5000,
+    });
+    if (r.error || r.status !== 0 || r.signal !== null) {
+      return {
+        ok: false,
+        mechanism: 'chattr+a',
+        skipped: false,
+        error: describeFailure(r, 'chattr'),
+      };
+    }
+    return { ok: true, mechanism: 'chattr+a', skipped: false, error: null };
+  }
+
+  if (PLATFORM === 'darwin') {
+    // chflags uappnd — settable by the file owner, no root needed
+    const r = spawnSync('chflags', ['uappnd', filePath], {
+      stdio: 'ignore',
+      timeout: 5000,
+    });
+    if (r.error || r.status !== 0 || r.signal !== null) {
+      return {
+        ok: false,
+        mechanism: 'chflags-uappnd',
+        skipped: false,
+        error: describeFailure(r, 'chflags'),
+      };
+    }
+    return { ok: true, mechanism: 'chflags-uappnd', skipped: false, error: null };
+  }
+
+  // Unsupported platform — skip silently.
+  return { ok: false, mechanism: null, skipped: true, error: null };
+}
+
+// ---------------------------------------------------------------------------
+// openCheckpoint — create & protect the checkpoint file on first use
+// ---------------------------------------------------------------------------
+
+/**
+ * Ensure the checkpoint file at `checkpointPath` exists, applying the
+ * OS append-only attribute immediately after creation.
+ *
+ * Call this once at process startup (before calling `appendCheckpointEntry`).
+ * Safe to call on a file that already exists — the OS attribute is only
+ * (re-)applied on first creation, since chattr+a/chflags-uappnd persist on
+ * the inode and do not need re-setting on every idempotent re-open.
+ *
+ * @param {string} checkpointPath  Path to the JSONL checkpoint file.
+ * @returns {{ created: boolean, attributeResult: object }}
+ *   `created` is true if this call created the file (false if it pre-existed).
+ *   `attributeResult` is the result of {@link setAppendOnlyAttribute}.
+ */
+export function openCheckpoint(checkpointPath) {
+  const dir = dirname(checkpointPath);
+  mkdirSync(dir, { recursive: true });
+
+  const created = !existsSync(checkpointPath);
+  if (created) {
+    // O_CREAT | O_WRONLY — create the empty file without truncating anything.
+    const fd = openSync(checkpointPath, 'a');
+    closeSync(fd);
+  }
+
+  // PR #62 round-7 fix: only set the OS attribute on first creation. Both
+  // chattr +a and chflags uappnd are persistent flags on the inode -- they
+  // do not need re-applying on every idempotent re-open, and doing so spawned
+  // an unnecessary child process on every call (flagged as a resource-use
+  // concern for a function that may be called repeatedly during a process's
+  // lifetime).
+  const attributeResult = created
+    ? setAppendOnlyAttribute(checkpointPath)
+    : { ok: true, mechanism: null, skipped: true, error: null };
+  return { created, attributeResult };
+}
+
+// ---------------------------------------------------------------------------
+// appendCheckpointEntry — the hot-path writer
+// ---------------------------------------------------------------------------
+
+/**
+ * Append one checkpoint record to the JSONL file.
+ *
+ * Each record is written as a single JSON line followed by `\n`.  The open
+ * mode is always `O_WRONLY | O_APPEND | O_CREAT` (via Node's `'a'` flag) so
+ * the process cannot overwrite or truncate the file even if the OS attribute
+ * was not successfully applied.
+ *
+ * The function is intentionally synchronous — checkpoint writes must be
+ * durable before the evaluator signals success to the caller.
+ *
+ * @param {string} checkpointPath  Path to the JSONL checkpoint file.
+ * @param {object} entry           Record to append.  Must be JSON-serialisable.
+ *   Conventional fields:
+ *     `seq`          — ledger sequence number (non-negative integer).
+ *     `event`        — event type string (e.g. `'ledger_state'`, `'policy_eval'`).
+ *     `ts`           — ISO-8601 timestamp string (caller-supplied; not auto-added).
+ *     `payload_hash` — SHA-256 hex of the event payload (for F2 chain linkage).
+ * @throws {TypeError}  When `entry` cannot be serialised to JSON.
+ * @throws {Error}      On filesystem I/O errors.
+ */
+export function appendCheckpointEntry(checkpointPath, entry) {
+  const line = JSON.stringify(entry) + '\n';
+  // 'a' flag = O_WRONLY | O_APPEND | O_CREAT — never truncates.
+  appendFileSync(checkpointPath, line, { encoding: 'utf8', flag: 'a' });
+}
+
+// ---------------------------------------------------------------------------
+// Export-daemon isolation sentinel
+// ---------------------------------------------------------------------------
+
+/**
+ * Symbolic constant confirming that this module (the evaluator-side checkpoint
+ * writer) is intentionally separate from the export daemon.
+ *
+ * Any code path that imports both this module AND `core/export-daemon.mjs`
+ * within the evaluator process is a design violation — the evaluator must
+ * never gain network capability.  Tests import this constant to assert the
+ * architectural separation.
+ */
+export const EVALUATOR_NO_NETWORK_SENTINEL = 'f02_evaluator_local_only';

package/core/audit-writer.mjs

@@ -0,0 +1,317 @@
+// KnoSky Mode B audit receipt writer (DEC-106).
+// Metadata-only hash-chained local ledger. No file bodies. No network.
+// Best-effort exclusive seq.lock reduces concurrent multi-agent TOCTOU on ledger_seq.
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  openSync,
+  closeSync,
+  unlinkSync,
+} from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { readHwm } from './ledger.mjs';
+
+/**
+ * @param {string} domainRoot
+ */
+export function auditPaths(domainRoot) {
+  return {
+    root: domainRoot,
+    eventsPath: join(domainRoot, 'audit', 'events.ndjson'),
+    hwmPath: join(domainRoot, 'audit', 'hwm.json'),
+    checkpointPath: join(domainRoot, 'audit', 'checkpoint.ndjson'),
+    seqLockPath: join(domainRoot, 'audit', 'seq.lock'),
+  };
+}
+
+function hashLine(prevHash, bodyObj) {
+  const h = createHash('sha256');
+  h.update(prevHash || '');
+  h.update('\n');
+  h.update(JSON.stringify(bodyObj));
+  return h.digest('hex');
+}
+
+function lastHash(eventsPath) {
+  if (!existsSync(eventsPath)) return null;
+  const text = readFileSync(eventsPath, 'utf8').trim();
+  if (!text) return null;
+  const lines = text.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i].trim()) continue;
+    try {
+      const row = JSON.parse(lines[i]);
+      return row.event_hash || null;
+    } catch {
+      /* keep scanning */
+    }
+  }
+  return null;
+}
+
+function writeHwmSoft(hwmPath, seq) {
+  if (!Number.isInteger(seq) || seq < 0) {
+    throw new TypeError(`ledger_hwm must be a non-negative integer, got: ${JSON.stringify(seq)}`);
+  }
+  const dir = dirname(hwmPath);
+  mkdirSync(dir, { recursive: true });
+  const tmp = hwmPath + '.tmp';
+  writeFileSync(tmp, JSON.stringify({ ledger_hwm: seq }) + '\n', 'utf8');
+  renameSync(tmp, hwmPath);
+}
+
+function checkAndAdvanceSoft(seq, hwmPath) {
+  if (!Number.isInteger(seq) || seq < 0) {
+    return { ok: false, error: `bad seq ${seq}` };
+  }
+  let hwm = 0;
+  try {
+    hwm = readHwm(hwmPath);
+  } catch (err) {
+    return { ok: false, error: err.message || String(err) };
+  }
+  // Must strictly advance past HWM (assigned under lock after append prep).
+  if (seq <= hwm) {
+    return {
+      ok: false,
+      error: `ledger sequence ${seq} must be > high-water mark ${hwm}`,
+    };
+  }
+  try {
+    writeHwmSoft(hwmPath, seq);
+  } catch (err) {
+    return { ok: false, error: err.message || String(err) };
+  }
+  return { ok: true, seq, hwm };
+}
+
+/**
+ * Exclusive lock via O_EXCL create of seq.lock.
+ * @returns {{ ok:true, release:()=>void } | { ok:false, reason:string }}
+ */
+function acquireSeqLock(lockPath, { tries = 50, delayMs = 8 } = {}) {
+  mkdirSync(dirname(lockPath), { recursive: true });
+  for (let i = 0; i < tries; i++) {
+    try {
+      const fd = openSync(lockPath, 'wx');
+      return {
+        ok: true,
+        release() {
+          try {
+            closeSync(fd);
+          } catch {
+            /* ignore */
+          }
+          try {
+            unlinkSync(lockPath);
+          } catch {
+            /* ignore */
+          }
+        },
+      };
+    } catch (err) {
+      if (err && (err.code === 'EEXIST' || err.code === 'EPERM')) {
+        const end = Date.now() + delayMs;
+        while (Date.now() < end) {
+          /* brief backoff */
+        }
+        continue;
+      }
+      return { ok: false, reason: err && err.message ? err.message : String(err) };
+    }
+  }
+  return { ok: false, reason: 'seq_lock_timeout' };
+}
+
+function sanitizeMeta(meta) {
+  if (!meta || typeof meta !== 'object') return {};
+  const out = {};
+  for (const [k, v] of Object.entries(meta)) {
+    if (typeof k !== 'string' || k.length > 80) continue;
+    if (v == null) continue;
+    if (typeof v === 'string') out[k] = v.slice(0, 200);
+    else if (typeof v === 'number' || typeof v === 'boolean') out[k] = v;
+    else if (Array.isArray(v)) out[k] = v.slice(0, 20).map((x) => String(x).slice(0, 80));
+  }
+  return out;
+}
+
+/**
+ * Append a route/swarm decision event and return a receipt.
+ * Fail-closed on I/O / HWM / lock errors.
+ *
+ * @param {object} opts
+ * @returns {{ ok:true, receipt_id:string, ledger_seq:number, event_hash:string }
+ *          |{ ok:false, reason:string }}
+ */
+export function writeDecisionReceipt(opts = {}) {
+  let lock = null;
+  try {
+    const {
+      domainRoot,
+      decision_code,
+      agent_id = null,
+      principal_id = null,
+      tool = null,
+      destination = null,
+      mode = 'B',
+      meta = {},
+    } = opts;
+    if (!domainRoot || typeof domainRoot !== 'string') {
+      return { ok: false, reason: 'missing_domain_root' };
+    }
+    if (!decision_code || typeof decision_code !== 'string') {
+      return { ok: false, reason: 'missing_decision_code' };
+    }
+
+    const paths = auditPaths(domainRoot);
+    mkdirSync(dirname(paths.eventsPath), { recursive: true });
+
+    lock = acquireSeqLock(paths.seqLockPath);
+    if (!lock.ok) {
+      return { ok: false, reason: `seq_lock: ${lock.reason}` };
+    }
+
+    // Under lock: seq = max(lineCount, hwm) + 1, then append, then HWM.
+    const prev = lastHash(paths.eventsPath);
+    let lineCount = 0;
+    if (existsSync(paths.eventsPath)) {
+      const t = readFileSync(paths.eventsPath, 'utf8');
+      lineCount = t.split(/\r?\n/).filter(Boolean).length;
+    }
+    let hwm = 0;
+    try {
+      hwm = readHwm(paths.hwmPath);
+    } catch (err) {
+      return { ok: false, reason: `hwm_read: ${err.message || err}` };
+    }
+    const seq = Math.max(lineCount, hwm) + 1;
+
+    const receipt_id = `rcpt_${randomUUID().replace(/-/g, '').slice(0, 24)}`;
+    const body = {
+      v: 1,
+      receipt_id,
+      ledger_seq: seq,
+      ts: new Date().toISOString(),
+      decision_code,
+      mode,
+      agent_id,
+      principal_id,
+      tool,
+      destination: typeof destination === 'string' ? destination.slice(0, 400) : null,
+      meta: sanitizeMeta(meta),
+      prev_hash: prev,
+    };
+    const event_hash = hashLine(prev, body);
+    body.event_hash = event_hash;
+
+    // Append first so crash after HWM can't "orphan" a seq with Vorgang no event
+    // (if crash after append before HWM, next max(line,hwm)+1 still advances cleanly)
+    appendFileSync(paths.eventsPath, JSON.stringify(body) + '\n', 'utf8');
+
+    const adv = checkAndAdvanceSoft(seq, paths.hwmPath);
+    if (!adv.ok) {
+      return {
+        ok: false,
+        reason: `hwm_or_checkpoint: ${adv.error || 'refused'}`,
+      };
+    }
+
+    return { ok: true, receipt_id, ledger_seq: seq, event_hash };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: err && err.message ? err.message : String(err),
+    };
+  } finally {
+    if (lock && lock.ok && typeof lock.release === 'function') {
+      lock.release();
+    }
+  }
+}
+
+/**
+ * Verify hash chain + contiguous ledger_seq.
+ * @param {string} domainRoot
+ */
+export function verifyAuditChain(domainRoot) {
+  const { eventsPath } = auditPaths(domainRoot);
+  if (!existsSync(eventsPath)) return { ok: true, count: 0 };
+  const lines = readFileSync(eventsPath, 'utf8').split(/\r?\n/).filter(Boolean);
+  let prev = null;
+  let prevSeq = 0;
+  for (let i = 0; i < lines.length; i++) {
+    let row;
+    try {
+      row = JSON.parse(lines[i]);
+    } catch {
+      return { ok: false, at: i, reason: 'invalid_json' };
+    }
+    const { event_hash, ...rest } = row;
+    const body = { ...rest };
+    const recomputed = hashLine(body.prev_hash || null, body);
+    if (recomputed !== event_hash) {
+      return { ok: false, at: i, reason: 'hash_mismatch', receipt_id: row.receipt_id };
+    }
+    if (i > 0 && body.prev_hash !== prev) {
+      return { ok: false, at: i, reason: 'prev_hash_break', receipt_id: row.receipt_id };
+    }
+    if (Number.isInteger(row.ledger_seq)) {
+      if (i === 0) {
+        if (row.ledger_seq < 1) {
+          return { ok: false, at: i, reason: 'seq_invalid', receipt_id: row.receipt_id };
+        }
+      } else if (row.ledger_seq !== prevSeq + 1) {
+        return {
+          ok: false,
+          at: i,
+          reason: 'seq_not_contiguous',
+          receipt_id: row.receipt_id,
+          expected: prevSeq + 1,
+          got: row.ledger_seq,
+        };
+      }
+      prevSeq = row.ledger_seq;
+    }
+    prev = event_hash;
+  }
+  return { ok: true, count: lines.length };
+}
+
+/**
+ * @param {string} domainRoot
+ * @param {{ limit?: number, agent_id?: string }} [opts]
+ */
+export function queryAudit(domainRoot, opts = {}) {
+  const { eventsPath } = auditPaths(domainRoot);
+  if (!existsSync(eventsPath)) return [];
+  const limit = Math.min(Math.max(1, opts.limit || 20), 200);
+  const lines = readFileSync(eventsPath, 'utf8').split(/\r?\n/).filter(Boolean);
+  const rows = [];
+  for (let i = lines.length - 1; i >= 0 && rows.length < limit; i--) {
+    try {
+      const row = JSON.parse(lines[i]);
+      if (opts.agent_id && row.agent_id !== opts.agent_id) continue;
+      rows.push({
+        receipt_id: row.receipt_id,
+        ledger_seq: row.ledger_seq,
+        ts: row.ts,
+        decision_code: row.decision_code,
+        mode: row.mode,
+        agent_id: row.agent_id,
+        tool: row.tool,
+        destination: row.destination,
+        event_hash: row.event_hash,
+      });
+    } catch {
+      /* skip */
+    }
+  }
+  return rows;
+}