@gregiteen/ssss-cli 0.12.0 → 0.13.0

package/skills/ssss/core/scripts/maintain.mjs

@@ -0,0 +1,75 @@
+/** Portable owner helper: preserve local wrappers, deploy managed SSSS core, verify every eligible consumer. */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const value = flag => { const i=args.indexOf(flag); return i<0 ? null : args[i+1]; };
+const source = path.resolve(value('--source') || path.join(path.dirname(fileURLToPath(import.meta.url)), '../..'));
+const apply = args.includes('--apply');
+const executable = execFileSync('which',['total-recall'],{encoding:'utf8'}).trim();
+const packageRoot = path.resolve(path.dirname(fs.realpathSync(executable)), '..');
+const api = await import(pathToFileURL(path.join(packageRoot,'src/core/skills-registry.mjs')));
+const brain = path.resolve(value('--brain') || path.join(os.homedir(),'.agent/skills/total-recall'));
+const sharedRoot = path.resolve(value('--shared-root') || os.homedir());
+const registry = api.loadRegistry(brain);
+const expectedCore = api.hashSkillLayer(source,'core');
+if (!expectedCore || !fs.existsSync(path.join(source,'SKILL.md'))) throw new Error('Invalid source-owned portable SSSS package');
+const known = api.loadKnownRepoRoots(brain,{includeCwd:false});
+const targets = new Set([sharedRoot, ...known]);
+const rows = registry.installs.filter(row=>row.skill_id==='ssss');
+const obsolete = rows.filter(row=>row.repo && !fs.existsSync(row.repo)).map(row=>({path:row.path,repo:row.repo,status:'obsolete_repository',required:false}));
+const stamp = new Date().toISOString().replace(/[:.]/g,'-');
+const backup = path.join(brain,'skill-package-history','ssss',stamp);
+const results=[];
+if (apply) api.registerSkill(brain,source,{source:source,source_type:'portable-owner-package',authoritative_scope:true});
+for (const root of targets) {
+  if (!fs.existsSync(root)) { results.push({repo:root,status:'missing_repository',required:true}); continue; }
+  let destination=path.join(root,'.agent/skills/ssss');
+  let alias=null;
+  try {
+    if(fs.existsSync(destination) && fs.lstatSync(destination).isSymbolicLink()) {
+      alias=destination; destination=fs.realpathSync(destination);
+      if (api.readSkillMeta(destination).id !== 'ssss') throw new Error('Shared alias does not identify an SSSS skill');
+    }
+    if (!apply) { results.push({repo:root,path:destination,status:'would_deploy',required:true}); continue; }
+    const priorWrapper=path.join(destination,'SKILL.md');
+    const routed=fs.existsSync(priorWrapper) && /(?:core\/SKILL\.md|total-recall:managed-core-route:v1)/.test(fs.readFileSync(priorWrapper,'utf8'));
+    if(api.hashSkillLayer(destination,'core')===expectedCore && routed) {
+      results.push({repo:root,path:destination,status:'verified',required:true,expected_core:expectedCore,observed_core:expectedCore,wrapper_preserved:true,changed:false,...(alias?{alias}: {})});
+      continue;
+    }
+    // Snapshot the package only, never a vault/database or unrelated skill.
+    if(fs.existsSync(destination)) {
+      const id=Buffer.from(root).toString('base64url');
+      fs.cpSync(destination,path.join(backup,id),{recursive:true,dereference:false});
+    }
+    if (alias) {
+      api.replaceSkillDir(path.join(source,'core'),path.join(destination,'core'),{requiredFile:null,preserveExisting:false});
+      const mapped=api.loadRegistry(brain);
+      mapped.installs=mapped.installs.filter(row=>!(row.skill_id==='ssss'&&row.path===alias));
+      mapped.installs.push({skill_id:'ssss',path:alias,repo:root,layered:true,version:api.readSkillMeta(source).version,core_hash:expectedCore,repo_hash:api.hashSkillLayer(destination,'repo'),registry_hash:mapped.skills.ssss.content_hash,installed_at:new Date().toISOString()});
+      api.saveRegistry(brain,mapped);
+    } else api.deploySkill(brain,'ssss',{repo:root,routeCore:true});
+    const wrapper=path.join(destination,'SKILL.md');
+    const text=fs.readFileSync(wrapper,'utf8');
+    const marker='<!-- total-recall:managed-core-route:v1 -->';
+    if(!text.includes(marker) && !text.includes('(core/SKILL.md)')) fs.writeFileSync(wrapper,text.trimEnd()+`\n\n${marker}\nRead the [maintained portable core](core/SKILL.md) for current protocol contracts; preserve repository-specific instructions above.\n`);
+    const observed=api.hashSkillLayer(destination,'core');
+    results.push({repo:root,path:destination,status:observed===expectedCore?'verified':'hash_mismatch',required:true,expected_core:expectedCore,observed_core:observed,wrapper_preserved:true,changed:true,...(alias?{alias}: {})});
+  } catch(error) { results.push({repo:root,path:destination,status:'error',required:true,error:error.message}); }
+}
+if(apply) {
+  const updated=api.loadRegistry(brain);
+  for(const row of updated.installs.filter(row=>row.skill_id==='ssss')) {
+    row.obsolete=Boolean(row.repo && !fs.existsSync(row.repo));
+    if(row.obsolete) row.obsolete_reason='Recorded repository no longer exists; retained for history, never recreated';
+    else delete row.obsolete_reason;
+  }
+  api.saveRegistry(brain,updated);
+}
+const report={checked_at:new Date().toISOString(),apply,source,version:api.readSkillMeta(source).version,expected_core:expectedCore,backup:apply?backup:null,results,obsolete,updated:results.filter(row=>row.changed).length,failed:results.filter(row=>row.required&&!['verified','would_deploy'].includes(row.status)).length};
+console.log(JSON.stringify(report,null,2));
+if(report.failed)process.exitCode=1;

package/skills/ssss/evals/maintain.test.mjs

@@ -0,0 +1,11 @@
+import {fileURLToPath} from 'node:url'; import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path'; import {execFileSync} from 'node:child_process'; import assert from 'node:assert/strict';
+const root=fs.mkdtempSync(path.join(os.tmpdir(),'ssss-helper-')); const source=path.join(root,'source'),brain=path.join(root,'brain'),repo=path.join(root,'repo'),helper=fileURLToPath(new URL('../core/scripts/maintain.mjs', import.meta.url));
+try {
+ fs.mkdirSync(path.join(source,'core'),{recursive:true});fs.writeFileSync(path.join(source,'SKILL.md'),'---\nname: ssss\ndescription: portable\nversion: 0.12.1\n---\n# Portable\n');fs.writeFileSync(path.join(source,'core/SKILL.md'),'# Current protocol\n');
+ const wrapper=path.join(repo,'.agent/skills/ssss/SKILL.md');fs.mkdirSync(path.dirname(wrapper),{recursive:true});fs.writeFileSync(wrapper,'---\nname: ssss\n---\n# Keep authored local instructions\n');
+ const run=(apply)=>JSON.parse(execFileSync(process.execPath,[helper,'--source',source,'--brain',brain,'--shared-root',repo,...(apply?['--apply']:[])],{encoding:'utf8'}));
+ assert.equal(run(false).apply,false);assert(!fs.existsSync(path.join(path.dirname(wrapper),'core')));
+ const first=run(true);assert.equal(first.failed,0);assert.equal(first.updated,1);assert(fs.readFileSync(wrapper,'utf8').includes('Keep authored local instructions'));
+ const second=run(true);assert.equal(second.updated,0);assert.equal(second.failed,0);assert(!fs.existsSync(second.backup));
+ console.log('PASS portable helper dry-run, preserve authored wrapper, deploy managed core, independent hash verification and idempotent no-op');
+} finally {fs.rmSync(root,{recursive:true,force:true});}

package/skills/ssss/references/protocol-reference-legacy.md

@@ -0,0 +1,54 @@
+---
+type: skill
+title: SSSS Protocol Reference
+name: ssss
+description: "Use this skill when reading, writing, parsing, validating, or extending SSSS -- the Structured Semantic Syntax System: the SSSS Core Contract API, VFS-native primitives, operation/patch/event envelopes, leases, and projections. MANDATORY: You MUST read the full SKILL.md file before executing."
+timestamp: 2026-07-15T00:00:00Z
+---
+
+# SSSS — Structured Semantic Syntax System Reference
+
+You are operating in a repository that implements, extends, or relies on the **Structured Semantic Syntax System (SSSS)**. SSSS is a database-free, Markdown-first schema and mutation contract for AI-agent state.
+
+This skill provides the normative rules for interacting with an SSSS-compliant vault or host engine (like Total Recall). 
+
+## ⚠️ The VFS-First Mandate (Absolute Rule)
+
+**NEVER use raw database inserts, updates, or deletes to mutate application state in an SSSS environment!**
+
+All persistent state (memories, agents, workflows, tasks) lives in the Virtual File System (VFS) as Markdown files with YAML frontmatter. The VFS is the absolute source of truth. 
+- If you are interacting via CLI: Use `npx total-recall remember` or `npx total-recall recall`.
+- If you are building host code: You must route mutations through the SSSS **Operation Contract** engine (which handles idempotency, leasing, and semantic indexing), or use the provided API wrappers. Do not bypass the engine to write files directly.
+
+## SSSS Core Concepts
+
+### 1. Primitives (The Data Model)
+Data in SSSS is defined by standard primitives (e.g. `workflow`, `assistant`, `skill`, `memory`). Each primitive has a defined schema (in `registry/core.json` or extension registries) and belongs to a specific Portability Class:
+- `structural`: Logic and system prompts (e.g. rules, workflows). Included in export templates.
+- `tenant_private`: User data (e.g. chats, tasks). NEVER included in templates.
+- `resource_bound`: Requires external setup (e.g. Twilio numbers). Exported only as a requirement.
+
+### 2. The Operation Contract (Envelopes)
+When an SSSS engine processes a write, it receives an **Envelope**:
+- `operation`: Creates or completely replaces a document.
+- `patch`: Merges partial data into a document (e.g. updating task status).
+- `event`: Appends an immutable log entry to a document.
+- `delete`: Tombstones a replace-type document.
+
+### 3. Idempotency and Leases
+- **Idempotency**: All mutations must provide an `idempotency_key`. The engine ensures duplicate submissions do not result in duplicate state.
+- **Leases**: Background tasks and workflows use the Lease store to acquire temporary locks on documents to prevent race conditions during execution.
+
+### 4. Bundles (.ucw)
+An SSSS vault can be packaged into a `.ucw` (Universal Containerized Workspace) bundle. A bundle is a portable snapshot containing a manifest, deterministic file paths, and content hashes for cryptographic integrity.
+
+Bundle import validates the complete plan before committing. Hosts pass planned
+document lookup through the kernel context's `resolveReference` option so valid
+forward references resolve in an empty destination. Missing referenced documents
+must reject the whole import; never weaken constraints to bypass ordering.
+
+## Validation 
+
+If you are writing tests or schemas in a host repository, ensure that:
+1. `MemoryNodeSchema` validations provide all required SSSS v2 properties (`status`, `created`, `updated`, `last_accessed`, `source`, `decay`).
+2. Schema changes maintain strict compatibility with the Open Knowledge Format (OKF) standard if applicable.

package/src/bundle.mjs

@@ -471,9 +471,12 @@ export function provisionBundle(bundle, opts = {}) {
   }
 
   // Build the envelope plan. Deterministic idempotency keys make import a no-op on re-run.
+  // The key covers the content: committed keys are durable (spec §6.4), so a key
+  // derived from the path alone would make every changed re-import a conflict.
   const plan = bundle.files.map((f) => {
     const targetPath = remap(f.path);
-    const key = 'prov-' + crypto.createHash('sha256').update(workspaceId + ':' + targetPath).digest('hex').slice(0, 24);
+    const contentDigest = crypto.createHash('sha256').update(f.content).digest('hex');
+    const key = 'prov-' + crypto.createHash('sha256').update(workspaceId + ':' + targetPath + ':' + contentDigest).digest('hex').slice(0, 24);
     return { type: 'operation', idempotency_key: key, path: targetPath, workspace_id: workspaceId, content: f.content, intent: 'provision', dry_run: dryRun, actor: { role: 'system' } };
   });
 

package/src/durable-fs.mjs

@@ -0,0 +1,32 @@
+/**
+ * Flush helpers for the reference file adapters (spec §6.3 commit point).
+ *
+ * A rename is atomic but not durable: after an OS crash the new name can
+ * survive while its bytes do not, unless the file is flushed before the
+ * rename and the directory after it. Platforms that cannot open a directory
+ * for flushing (Windows) skip the directory step.
+ */
+import fs from 'node:fs';
+
+const NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+const CREATE_EXCLUSIVE = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW;
+const UNSUPPORTED_DIRECTORY_SYNC = new Set(['EISDIR', 'EINVAL', 'EPERM', 'EACCES', 'ENOTSUP', 'EBADF']);
+
+/** Create `file` exclusively, write `bytes`, and flush them before returning. */
+export function writeFileSyncDurable(file, bytes, mode = 0o600) {
+  const fd = fs.openSync(file, CREATE_EXCLUSIVE, mode);
+  try {
+    fs.writeFileSync(fd, bytes);
+    fs.fsyncSync(fd);
+  } finally { fs.closeSync(fd); }
+}
+
+/** Flush a directory's entries (a rename, create or unlink inside it). */
+export function fsyncDirectory(dir) {
+  let fd;
+  try { fd = fs.openSync(dir, fs.constants.O_RDONLY); }
+  catch (error) { if (UNSUPPORTED_DIRECTORY_SYNC.has(error.code)) return; throw error; }
+  try { fs.fsyncSync(fd); }
+  catch (error) { if (!UNSUPPORTED_DIRECTORY_SYNC.has(error.code)) throw error; }
+  finally { fs.closeSync(fd); }
+}

package/src/engine.mjs

@@ -139,6 +139,10 @@ export function createEngine(options = {}) {
       }
       return response;
     },
+    /** Resolve commit intents a crashed writer left in this vault (spec §6.3). */
+    async recover(vaultRoot, callOptions = {}) {
+      return bound(vaultRoot, callOptions.eventLogDir).recover();
+    },
     resolveContainedPath,
     _types: registrySet.types,
     _registry: registrySet,

package/src/events.mjs

@@ -2,8 +2,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { StringDecoder } from 'node:string_decoder';
 import { withFileLock } from './file-lock.mjs';
+import { fsyncDirectory } from './durable-fs.mjs';
 
 // UUIDv5 namespace for event ids derived from idempotency keys.
 const IDEMPOTENT_EVENT_NAMESPACE = Buffer.from('6f1c2d9e4b7a4e0c9f35a1d8c3b2e7f4', 'hex');
@@ -49,16 +49,26 @@ export function createCanonicalEvent(input, options = {}) {
   };
 }
 
+const keyId = (workspaceId, idempotencyKey) => JSON.stringify([workspaceId, idempotencyKey]);
+
 export class MemoryEventStore {
   #events = [];
   #ids = new Set();
+  #keys = new Map();
   async append(event) {
     if (this.#ids.has(event.event_id)) throw new Error(`Duplicate event_id '${event.event_id}'.`);
     const frozen = structuredClone(event);
     this.#events.push(frozen);
     this.#ids.add(frozen.event_id);
+    const id = keyId(frozen.workspace_id, frozen.idempotency_key);
+    if (!this.#keys.has(id)) this.#keys.set(id, frozen);
     return structuredClone(frozen);
   }
+  /** The first event committed under (workspace, key), or null (spec §6.4). */
+  async findByIdempotencyKey(workspaceId, idempotencyKey) {
+    const event = this.#keys.get(keyId(workspaceId, idempotencyKey));
+    return event ? structuredClone(event) : null;
+  }
   async *replay(options = {}) {
     for (let index = options.cursor || 0; index < this.#events.length; index++) {
       const event = this.#events[index];
@@ -84,34 +94,77 @@ function sameStat(a, b) {
   return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
 }
 
-/** Decode one line at a time, never materializing the complete log as a string. */
-function* logLines(fd, size) {
+/**
+ * Split a log into lines on raw bytes, one line at a time, never materializing
+ * the complete log. Each record carries the byte offset of its line, and
+ * `complete: false` for a final line with no newline yet (an append in flight).
+ */
+function* logRecords(fd, size) {
   const buffer = Buffer.alloc(64 * 1024);
-  const decoder = new StringDecoder('utf8');
-  let offset = 0, pending = '';
-  while (offset < size) {
-    const read = fs.readSync(fd, buffer, 0, Math.min(buffer.length, size - offset), offset);
+  let position = 0, start = 0, pending = [];
+  while (position < size) {
+    const read = fs.readSync(fd, buffer, 0, Math.min(buffer.length, size - position), position);
     if (read === 0) break;
-    offset += read;
-    const text = pending + decoder.write(buffer.subarray(0, read));
-    let start = 0, newline;
-    while ((newline = text.indexOf('\n', start)) !== -1) {
-      yield text.slice(start, newline);
-      start = newline + 1;
+    let from = 0, newline;
+    while ((newline = buffer.indexOf(0x0a, from)) !== -1 && newline < read) {
+      pending.push(buffer.subarray(from, newline));
+      yield { offset: start, text: Buffer.concat(pending).toString('utf8'), complete: true };
+      pending = [];
+      start = position + newline + 1;
+      from = newline + 1;
     }
-    pending = text.slice(start);
+    // Copy: the read buffer is reused by the next iteration.
+    if (from < read) pending.push(Buffer.from(buffer.subarray(from, read)));
+    position += read;
   }
-  pending += decoder.end();
-  if (pending) yield pending;
+  if (pending.length) yield { offset: start, text: Buffer.concat(pending).toString('utf8'), complete: false };
+}
+
+function* logLines(fd, size) {
+  for (const record of logRecords(fd, size)) yield record.text;
 }
 
-/** Read every event_id, bounded to the bytes covered by the returned stat. */
-function loadIndex(file) {
+/**
+ * Read every event_id and the first offset of every idempotency key, bounded
+ * to the bytes covered by the returned stat. A reader outside the append lock
+ * passes `partialTail` so another writer's in-flight line is skipped instead
+ * of failing to parse; the index then records that it is partial.
+ */
+function loadIndex(file, { partialTail = false } = {}) {
   const fd = openLog(file, fs.constants.O_RDONLY | NOFOLLOW);
   try {
-    const stat = fs.fstatSync(fd), ids = new Set();
-    for (const line of logLines(fd, stat.size)) if (line.trim()) ids.add(JSON.parse(line).event_id);
-    return { ids, stat };
+    const stat = fs.fstatSync(fd), ids = new Set(), keys = new Map();
+    let partial = false;
+    for (const { offset, text, complete } of logRecords(fd, stat.size)) {
+      if (!text.trim()) continue;
+      if (!complete && partialTail) { partial = true; continue; }
+      const event = JSON.parse(text);
+      ids.add(event.event_id);
+      if (typeof event.idempotency_key === 'string' && !keys.has(event.idempotency_key)) {
+        keys.set(event.idempotency_key, { file, offset });
+      }
+    }
+    return { ids, keys, stat, partial };
+  } finally { fs.closeSync(fd); }
+}
+
+/** Parse the single log line that starts at `offset`, or null if it is gone. */
+function readEventAt(file, offset) {
+  let fd;
+  try { fd = openLog(file, fs.constants.O_RDONLY | NOFOLLOW); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  try {
+    const size = fs.fstatSync(fd).size;
+    const buffer = Buffer.alloc(16 * 1024), chunks = [];
+    for (let position = offset; position < size;) {
+      const read = fs.readSync(fd, buffer, 0, Math.min(buffer.length, size - position), position);
+      if (read === 0) break;
+      const newline = buffer.indexOf(0x0a);
+      if (newline !== -1 && newline < read) { chunks.push(Buffer.from(buffer.subarray(0, newline))); break; }
+      chunks.push(Buffer.from(buffer.subarray(0, read)));
+      position += read;
+    }
+    try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { return null; }
   } finally { fs.closeSync(fd); }
 }
 
@@ -194,35 +247,60 @@ export class JsonlEventStore {
       return 0;
     }
   }
-  #index(file) {
+  // `partialTail` is for readers outside the append lock (see loadIndex). An
+  // index built that way is cached, but the append path never trusts it.
+  #index(file, { partialTail = false } = {}) {
+    const workspaceId = path.basename(file, '.jsonl');
     let stat;
     try { stat = fs.lstatSync(file); }
     catch (error) {
       if (error.code !== 'ENOENT') throw error;
       this.#indexes.delete(file);
-      return { ids: new Set(), stat: null };
+      stat = null;
     }
-    if (stat.isSymbolicLink()) throw new Error('Symlinked event logs are forbidden.');
+    if (stat?.isSymbolicLink()) throw new Error('Symlinked event logs are forbidden.');
     const cached = this.#indexes.get(file);
-    if (cached && sameStat(cached.stat, stat)) return cached;
+    if (cached && cached.stat && stat && sameStat(cached.stat, stat) && (partialTail || !cached.partial)) return cached;
     // Duplicate detection spans the live log AND every archive segment:
     // rotating a log must never let an already-recorded event_id be appended
     // again. Archives are immutable, so their ids are collected once per
     // rebuild; only the live file's stat decides when a rebuild is needed.
-    const ids = new Set();
-    const workspaceId = path.basename(file, '.jsonl');
+    // Keys keep their first occurrence, oldest segment first.
+    const ids = new Set(), keys = new Map();
+    const merge = (part) => {
+      for (const id of part.ids) ids.add(id);
+      for (const [key, entry] of part.keys) if (!keys.has(key)) keys.set(key, entry);
+    };
     for (const archive of this.#archives(workspaceId)) {
       let archiveStat;
       try { archiveStat = fs.lstatSync(archive); } catch { continue; }
       if (archiveStat.isSymbolicLink()) throw new Error('Symlinked event logs are forbidden.');
-      for (const id of loadIndex(archive).ids) ids.add(id);
+      merge(loadIndex(archive));
     }
-    const live = loadIndex(file);
-    for (const id of live.ids) ids.add(id);
-    const index = { ids, stat };
+    if (!stat) return { ids, keys, stat: null, partial: false };
+    const live = loadIndex(file, { partialTail });
+    merge(live);
+    const index = { ids, keys, stat, partial: live.partial };
     this.#indexes.set(file, index);
     return index;
   }
+  /**
+   * The first event committed under (workspace, key), or null (spec §6.4).
+   * The index holds only offsets; the event itself is read on a hit, which
+   * only a retry causes. A segment rotated between the index read and the
+   * line read is detected by the key check and retried once on a fresh index.
+   */
+  async findByIdempotencyKey(workspaceId, idempotencyKey) {
+    const file = this.#file(workspaceId);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const entry = this.#index(file, { partialTail: true }).keys.get(idempotencyKey);
+      if (!entry) return null;
+      const event = readEventAt(entry.file, entry.offset);
+      if (event?.idempotency_key === idempotencyKey && event.workspace_id === workspaceId) return event;
+      this.#indexes.delete(file);
+    }
+    return null;
+  }
   async append(event) {
     const file = this.#file(event.workspace_id);
     return withFileLock(`${file}.lock`, () => this.#appendLocked(file, event), this.lockOptions);
@@ -240,15 +318,23 @@ export class JsonlEventStore {
     let after;
     try {
       fs.writeFileSync(fd, line);
+      // The append is the commit point (spec §6.3): it is on disk before the
+      // kernel reports success, and so is a log this append created.
+      fs.fsyncSync(fd);
       after = fs.fstatSync(fd);
     } finally { fs.closeSync(fd); }
+    if (!before) fsyncDirectory(this.root);
     // Cache the index only when the log grew by exactly this line on the same
     // file. After a rotation the live file is brand new, so the previous stat
     // is meaningless and the next append rebuilds from the archives instead.
-    const expectedSize = (before?.size || 0) + Buffer.byteLength(line);
+    const offset = before?.size || 0;
+    const expectedSize = offset + Buffer.byteLength(line);
     if (!rotated && after.size === expectedSize && (!before || (before.dev === after.dev && before.ino === after.ino))) {
       index.ids.add(event.event_id);
-      this.#indexes.set(file, { ids: index.ids, stat: after });
+      if (typeof event.idempotency_key === 'string' && !index.keys.has(event.idempotency_key)) {
+        index.keys.set(event.idempotency_key, { file, offset });
+      }
+      this.#indexes.set(file, { ids: index.ids, keys: index.keys, stat: after, partial: false });
     }
     return structuredClone(event);
   }

package/src/intents.mjs

@@ -0,0 +1,217 @@
+/**
+ * Commit intent journals (spec §6.3): a rollback journal for the window
+ * between the VFS commit (stage 9) and the event append (stage 10).
+ *
+ * Before stage 9 the kernel records an intent holding the document's prior
+ * content and holds the path's commit lock until stage 10 ends. An intent
+ * still present when its lock is free belongs to a writer that died; the
+ * kernel resolves it from the event log and the vault before the next commit
+ * on that path. A live holder's intent is never touched.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { withFileLock } from './file-lock.mjs';
+import { fsyncDirectory, writeFileSyncDurable } from './durable-fs.mjs';
+
+/**
+ * Commit locks wait like other file locks, but count as stale only after five
+ * minutes, far beyond the longest in-flight commit (two 40 s lock waits), so
+ * recovery can never roll back a commit that is still running. A holder that
+ * has exited on this host is detected at once.
+ */
+export const INTENT_LOCK_DEFAULTS = Object.freeze({ timeoutMs: 40_000, staleMs: 5 * 60_000 });
+
+/** Outcomes a resolver may return. `failed` keeps the intent for a later attempt. */
+export const INTENT_OUTCOMES = Object.freeze(['committed', 'rolled_back', 'discarded', 'conflict', 'failed']);
+
+/**
+ * In-process journal: serializes commits per path. Memory state cannot outlive
+ * a crash, so the only leftovers are intents a commit kept after its own
+ * rollback failed; those are resolved before the next commit on the path.
+ */
+export class MemoryIntentJournal {
+  #tails = new Map();
+  #intents = new Map();
+  #held = new Set();
+
+  async run(vfsPath, intent, commit, { resolve }) {
+    const previous = this.#tails.get(vfsPath) || Promise.resolve();
+    let release;
+    const tail = previous.then(() => new Promise((done) => { release = done; }));
+    this.#tails.set(vfsPath, tail);
+    await previous;
+    this.#held.add(vfsPath);
+    try {
+      const leftover = this.#intents.get(vfsPath);
+      if (leftover) {
+        const settled = await resolve(structuredClone(leftover));
+        if (settled.outcome === 'failed') throw new Error(`Recovery of an earlier commit on '${vfsPath}' failed: ${settled.reason}`);
+        this.#intents.delete(vfsPath);
+      }
+      this.#intents.set(vfsPath, structuredClone(intent));
+      const result = await commit();
+      if (!result?.keepIntent) this.#intents.delete(vfsPath);
+      return result;
+    } finally {
+      this.#held.delete(vfsPath);
+      release();
+      if (this.#tails.get(vfsPath) === tail) this.#tails.delete(vfsPath);
+    }
+  }
+
+  async recover(resolve) {
+    const results = [];
+    for (const [vfsPath, intent] of [...this.#intents]) {
+      if (this.#held.has(vfsPath)) { results.push({ path: vfsPath, operation_id: intent.operation_id, outcome: 'in_flight' }); continue; }
+      const settled = await resolve(structuredClone(intent));
+      if (settled.outcome !== 'failed') this.#intents.delete(vfsPath);
+      results.push({ path: vfsPath, operation_id: intent.operation_id, ...settled });
+    }
+    return results;
+  }
+}
+
+const INTENT_FILE = /^[a-f0-9]{64}\.json$/;
+
+/**
+ * File-backed journal, one intent and one lock per path under `root`. Intents
+ * are written to a flushed temp file and renamed, so a reader sees a complete
+ * intent or none. Unresolvable intents move to `root/unresolved/`.
+ */
+export class FileIntentJournal {
+  constructor(root, options = {}) {
+    if (!root) throw new Error('FileIntentJournal requires a root directory.');
+    this.root = path.resolve(root);
+    this.lockOptions = { ...INTENT_LOCK_DEFAULTS, ...options.lock };
+  }
+
+  #checkRoot({ create }) {
+    let stat = null;
+    try { stat = fs.lstatSync(this.root); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (stat && (stat.isSymbolicLink() || !stat.isDirectory())) throw new Error('Intent journal root must be a real directory.');
+    if (!stat && create) fs.mkdirSync(this.root, { recursive: true, mode: 0o700 });
+    return !!stat || create;
+  }
+
+  #files(name) {
+    return { intent: path.join(this.root, `${name}.json`), lock: path.join(this.root, `${name}.lock`) };
+  }
+
+  #name(vfsPath) { return crypto.createHash('sha256').update(vfsPath).digest('hex'); }
+
+  #read(file) {
+    let stat;
+    try { stat = fs.lstatSync(file); }
+    catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+    if (!stat.isFile()) return { unreadable: true };
+    try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return { unreadable: true }; }
+  }
+
+  #write(file, intent) {
+    const temp = `${file}.${crypto.randomUUID()}.tmp`;
+    try {
+      writeFileSyncDurable(temp, `${JSON.stringify(intent)}\n`);
+      fs.renameSync(temp, file);
+      fsyncDirectory(this.root);
+    } finally { fs.rmSync(temp, { force: true }); }
+  }
+
+  #quarantine(file, intent) {
+    const dir = path.join(this.root, 'unresolved');
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const target = path.join(dir, `${path.basename(file, '.json')}-${intent?.operation_id || crypto.randomUUID()}.json`);
+    fs.renameSync(file, target);
+    fsyncDirectory(dir);
+    return path.relative(this.root, target).split(path.sep).join('/');
+  }
+
+  // Caller holds the path's lock. Temp files under the same name belong to a
+  // writer that held this lock and died, so they are removed here.
+  async #settle(name, resolve) {
+    const { intent: file } = this.#files(name);
+    for (const entry of fs.readdirSync(this.root)) {
+      if (entry.startsWith(`${name}.json.`) && entry.endsWith('.tmp')) fs.rmSync(path.join(this.root, entry), { force: true });
+    }
+    const leftover = this.#read(file);
+    if (!leftover) return null;
+    if (leftover.unreadable) {
+      return { path: null, operation_id: null, outcome: 'conflict', reason: 'Intent record is unreadable.', quarantined: this.#quarantine(file, null) };
+    }
+    const settled = await resolve(leftover);
+    const result = { path: leftover.path, operation_id: leftover.operation_id, ...settled };
+    if (settled.outcome === 'conflict') result.quarantined = this.#quarantine(file, leftover);
+    else if (settled.outcome !== 'failed') fs.rmSync(file, { force: true });
+    return result;
+  }
+
+  async run(vfsPath, intent, commit, { resolve }) {
+    this.#checkRoot({ create: true });
+    const name = this.#name(vfsPath);
+    const { intent: file, lock } = this.#files(name);
+    return withFileLock(lock, async () => {
+      const settled = await this.#settle(name, resolve);
+      if (settled?.outcome === 'failed') throw new Error(`Recovery of an earlier commit on '${vfsPath}' failed: ${settled.reason}`);
+      this.#write(file, intent);
+      // A throw leaves the intent in place: the commit's state is unknown, and
+      // the next recovery decides it from the log and the vault.
+      const result = await commit();
+      if (!result?.keepIntent) fs.rmSync(file, { force: true });
+      return result;
+    }, this.lockOptions);
+  }
+
+  /**
+   * Resolve every intent whose writer is gone. Intents whose lock is held by
+   * a live writer are reported as `in_flight` and left alone.
+   */
+  async recover(resolve) {
+    if (!this.#checkRoot({ create: false })) return [];
+    const results = [];
+    for (const entry of fs.readdirSync(this.root).sort()) {
+      if (!INTENT_FILE.test(entry)) continue;
+      const name = entry.slice(0, 64);
+      const { intent: file, lock } = this.#files(name);
+      try {
+        const settled = await withFileLock(lock, () => this.#settle(name, resolve), { ...this.lockOptions, timeoutMs: 0 });
+        if (settled) results.push(settled);
+      } catch (error) {
+        if (error.code !== 'SSSS_LOCK_TIMEOUT') throw error;
+        const intent = this.#read(file);
+        results.push({ path: intent?.path || null, operation_id: intent?.operation_id || null, outcome: 'in_flight' });
+      }
+    }
+    return results;
+  }
+}
+
+/** Shared contract for intent journals (spec §6.7). */
+export async function runIntentJournalContract(journal) {
+  const checks = [];
+  const record = (name, passed) => checks.push({ name, passed: !!passed });
+  const target = `contract/${crypto.randomUUID()}.md`;
+  const intent = (id) => ({ version: 1, operation_id: id, path: target });
+  const seen = [];
+  const resolve = async (leftover) => { seen.push(leftover.operation_id); return { outcome: 'rolled_back' }; };
+
+  const result = await journal.run(target, intent('one'), async () => ({ ok: true }), { resolve });
+  record('run returns the commit result', result?.ok === true);
+  record('a completed commit leaves nothing to recover', (await journal.recover(resolve)).length === 0 && seen.length === 0);
+
+  await journal.run(target, intent('kept'), async () => ({ keepIntent: true }), { resolve });
+  await journal.run(target, intent('next'), async () => ({ ok: true }), { resolve });
+  record('a kept intent is resolved before the next commit on its path', seen.join() === 'kept');
+
+  let order = '';
+  const slow = journal.run(target, intent('slow'), async () => { order += 'a'; await new Promise((done) => setTimeout(done, 20)); order += 'b'; return {}; }, { resolve });
+  const fast = journal.run(target, intent('fast'), async () => { order += 'c'; return {}; }, { resolve });
+  await Promise.all([slow, fast]);
+  record('commits on one path are serialized', order === 'abc');
+
+  await journal.run(target, intent('stuck'), async () => ({ keepIntent: true }), { resolve });
+  const recovered = await journal.recover(resolve);
+  record('recover resolves a kept intent and reports it', recovered.length === 1 && recovered[0].outcome === 'rolled_back' && recovered[0].operation_id === 'stuck');
+  record('a resolved intent is not resolved again', (await journal.recover(resolve)).length === 0);
+  return { passed: checks.every((check) => check.passed), checks };
+}