@aetheros/kernel-runtime 0.1.0 → 0.1.2

package/src/external-identity.js

@@ -0,0 +1,59 @@
+const permissions = new Set(['read', 'write', 'workflow', 'approve', 'audit', 'admin']);
+const text = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 2048;
+const live = claims => Number.isSafeInteger(claims.expiresAt) && claims.expiresAt > Date.now();
+const denied = () => new Error('External identity denied');
+
+/** Trusted host adapter, never a JWT decoder or a replacement for TokenAuthority.
+ * Every call verifies credentials and checks current revocation; nothing is cached.
+ */
+export class ExternalIdentityBoundary {
+  #issuer; #audience; #tenantId; #verify; #active; #subject; #scopes;
+  constructor({issuer, audience, tenantId, verifyCredential, isActive, mapSubject, scopeMap} = {}) {
+    if (![issuer, audience, tenantId].every(text) ||
+        ![verifyCredential, isActive, mapSubject].every(value => typeof value === 'function') ||
+        !scopeMap || Object.getPrototypeOf(scopeMap) !== Object.prototype ||
+        !Object.keys(scopeMap).length || Object.entries(scopeMap).some(([key, value]) => !text(key) || !permissions.has(value))) {
+      throw new TypeError('Explicit external identity host configuration required');
+    }
+    this.#issuer = issuer; this.#audience = audience; this.#tenantId = tenantId;
+    this.#verify = verifyCredential; this.#active = isActive; this.#subject = mapSubject;
+    this.#scopes = new Map(Object.entries(scopeMap));
+  }
+  async verify(credential) {
+    try {
+      if (typeof credential !== 'string' || !credential.trim() || credential.length > 16384) throw denied();
+      // Only the configured verifier sees the bearer credential. It must verify
+      // signature/protocol, algorithm, key trust, not-before and provider policy.
+      const claims = structuredClone(await this.#verify(credential));
+      if (!claims || claims.issuer !== this.#issuer || claims.audience !== this.#audience ||
+          claims.tenantId !== this.#tenantId || !text(claims.subject) || !text(claims.credentialId) ||
+          !live(claims) || !Array.isArray(claims.scopes) || claims.scopes.length > 128 ||
+          !claims.scopes.every(text)) throw denied();
+      const verified = {issuer: this.#issuer, audience: this.#audience, tenantId: this.#tenantId,
+        subject: claims.subject, credentialId: claims.credentialId, scopes: [...new Set(claims.scopes)], expiresAt: claims.expiresAt};
+      // Subject mapping is synchronous, explicit, issuer/tenant qualified and host
+      // owned. A tool cannot select the local actor or scope mapping.
+      const subject = this.#subject(Object.freeze({issuer: verified.issuer, tenantId: verified.tenantId, subject: verified.subject}));
+      if (!text(subject)) throw denied();
+      if (await this.#active(structuredClone(verified)) !== true || !live(verified)) throw denied();
+      const mapped = [...new Set(verified.scopes.filter(scope => this.#scopes.has(scope)).map(scope => this.#scopes.get(scope)))];
+      if (!mapped.length) throw denied();
+      return {tenantId: verified.tenantId, subject, permissions: mapped, expiresAt: verified.expiresAt};
+    } catch { throw denied(); } // Never forward provider exceptions, credentials or claims.
+  }
+  /** Compose with an existing facade's host policy, alongside Review/claim checks.
+   * A previous verify result is deliberately insufficient: verify again on every call.
+   */
+  async authorize({credential, identity, permission} = {}) {
+    try {
+      const expected = structuredClone(identity);
+      if (!expected || expected.tenantId !== this.#tenantId || !text(expected.subject) ||
+          !permissions.has(permission) || !Array.isArray(expected.permissions) || !live(expected) ||
+          (!expected.permissions.includes(permission) && !expected.permissions.includes('admin'))) throw denied();
+      const current = await this.verify(credential);
+      if (!live(expected) || current.tenantId !== expected.tenantId || current.subject !== expected.subject ||
+          (!current.permissions.includes(permission) && !current.permissions.includes('admin'))) throw denied();
+      return true;
+    } catch { throw denied(); }
+  }
+}

package/src/index.js

@@ -1,6 +1,7 @@
 import {randomBytes,scryptSync,timingSafeEqual} from 'node:crypto';
 import {readFile,writeFile,rename,mkdir,open} from 'node:fs/promises';
 import {dirname,resolve} from 'node:path';
+export {ExternalIdentityBoundary} from './external-identity.js';
 
 const scopes=new Set(['read','write','workflow','approve','audit','admin']);
 const validate=(value,name)=>{if(typeof value!=='string'||!value.trim())throw new Error(name+' required');return value;};
@@ -42,8 +43,10 @@ export class FileStateStore {
   FileStateStore.queues.set(this.path,current);
   try{return await current;}finally{if(FileStateStore.queues.get(this.path)===current)FileStateStore.queues.delete(this.path);}
  }
- constructor(path,{codec}={}){
+ constructor(path,{codec,recovery}={}){
   this.path=resolve(validate(path,'path'));
+  if(recovery!==undefined&&recovery!==false&&(recovery===null||typeof recovery!=='object'))throw new TypeError('Recovery options must be false or an object');
+  this.recovery=recovery;
   if(codec!==undefined&&(!codec||typeof codec.encode!=='function'||typeof codec.decode!=='function'))throw new TypeError('State codec requires encode and decode');
   this.codec=codec;
  }

package/src/lock-inspection.js

@@ -0,0 +1,39 @@
+import {lstat, open} from 'node:fs/promises';
+import {probeOwner} from './process-identity.js';
+
+/**
+ * Read-only look at the lock a state store leaves while a transaction runs (R5). It reports what can be seen and never
+ * changes, removes or takes over anything. Today's lock file holds only a random lease: it does not say which process
+ * holds it, so this can say how long it has been there and what it looks like, but not whether its owner is alive.
+ * Age alone is never proof that an owner is gone (see docs/architecture/abandoned-lock-recovery.md).
+ */
+const LEASE = /^[0-9a-f]{48}$/;
+
+/**
+ * @param {string} statePath  the state file's path (the lock is `<statePath>.lock`)
+ * @param {{now?: () => number}} options
+ * @returns {Promise<{path: string, lockPath: string, exists: boolean, ageMs?: number, modifiedAt?: string, bytes?: number, format?: 'record-v2'|'lease-v1'|'unreadable'|'unrecognised', owner?: object, owner_check?: {verdict: string, reason: string}, recovery?: string}>}
+ */
+export async function inspectStateLock(statePath, {now = () => Date.now(), probe = probeOwner, probeOptions = {}} = {}) {
+  if (typeof statePath !== 'string' || !statePath.trim()) throw new TypeError('State path required');
+  const lockPath = statePath + '.lock';
+  let info;
+  try { info = await lstat(lockPath); } catch (error) { if (error.code === 'ENOENT') return {path: statePath, lockPath, exists: false}; throw error; }
+  if (!info.isFile()) return {path: statePath, lockPath, exists: true, format: 'unrecognised', bytes: info.size, recovery: 'The lock path is not a regular file. Do not remove it automatically; look at it by hand.'};
+  // Only the first few bytes are read, and only to tell the format; the lease itself is never returned.
+  let head = '', whole = '';
+  try { const handle = await open(lockPath, 'r'); try { const buffer = Buffer.alloc(2048); const {bytesRead} = await handle.read(buffer, 0, 2048, 0); whole = buffer.subarray(0, bytesRead).toString('utf8'); head = whole.slice(0, 64); } finally { await handle.close(); } }
+  catch (error) { if (error.code === 'ENOENT') return {path: statePath, lockPath, exists: false}; return {path: statePath, lockPath, exists: true, format: 'unreadable', bytes: info.size, recovery: 'The lock file could not be read.'}; }
+  let record = null;
+  try { const v = JSON.parse(whole); if (v && v.v === 2 && typeof v.lease === 'string' && Number.isSafeInteger(v.pid)) record = v; } catch { /* not a record */ }
+  const format = record ? 'record-v2' : LEASE.test(head) && info.size === 48 ? 'lease-v1' : 'unrecognised';
+  const ageMs = Math.max(0, now() - info.mtimeMs);
+  // For a record, say who holds it and whether that process is provably gone (read-only; the lease is never returned).
+  const owner = record ? {pid: record.pid, startedAt: new Date(record.processStart).toISOString(), fence: record.fence} : undefined;
+  const ownerCheck = record ? await probe(record, probeOptions).catch(() => ({verdict: 'unknown', reason: 'the check failed'})) : undefined;
+  return {
+    path: statePath, lockPath, exists: true, ageMs: Math.round(ageMs), modifiedAt: new Date(info.mtimeMs).toISOString(), bytes: info.size, format,
+    ...(owner && {owner, owner_check: ownerCheck}),
+    recovery: record ? (ownerCheck.verdict === 'gone' ? `This lock names process ${record.pid}, which is provably gone (${ownerCheck.reason}). The next write recovers it by itself; nothing needs to be deleted by hand.` : ownerCheck.verdict === 'alive' ? `This lock is held by process ${record.pid}, which is running. Leave it.` : `This lock names process ${record.pid}, but it cannot be proven gone (${ownerCheck.reason}). A long age is not proof. If you are sure no AetherOS process is using this project, delete the lock file by hand; otherwise leave it.`) : 'Nothing in this lock says which process holds it, or whether that process is still running. A transaction normally lasts milliseconds, but a long age is not proof that its owner is gone. If you are sure no AetherOS process is using this project (close them all and check), delete the lock file by hand; otherwise leave it.'
+  };
+}

package/src/process-identity.js

@@ -0,0 +1,82 @@
+import {execFile} from 'node:child_process';
+import {createHash} from 'node:crypto';
+import {readFile} from 'node:fs/promises';
+import {hostname, uptime} from 'node:os';
+
+/**
+ * Who a process is, and whether a process named in an old lock is provably gone (R6; design in
+ * docs/architecture/abandoned-lock-recovery.md). A process is identified by its pid AND its start time, so a reused pid is a
+ * different process. "Gone" needs positive evidence on the same machine and the same boot; any doubt is "unknown", and an
+ * unknown owner is never recovered. Age is never evidence.
+ *
+ * Recovery is enabled where the probes have been verified on real machines (Windows). Elsewhere it stays manual unless
+ * AETHER_LOCK_RECOVERY=on is set (the Linux and macOS probes are written but have not been run on those systems here).
+ */
+export const START_TOLERANCE_MS = 5000;
+export const BOOT_TOLERANCE_MS = 120_000;
+export const VERIFIED_PLATFORMS = Object.freeze(['win32']);
+
+const run = (file, args, {timeout = 15_000} = {}) => new Promise((resolve, reject) => execFile(file, args, {timeout, windowsHide: true, encoding: 'utf8'}, (error, stdout) => error ? reject(error) : resolve(String(stdout))));
+
+const PROCESS_START = Math.round(Date.now() - process.uptime() * 1000);
+let identityPromise = null;
+
+async function machineId(platform, exec) {
+  try {
+    if (platform === 'win32') { const out = await exec('reg', ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid']); return /MachineGuid\s+REG_SZ\s+(\S+)/.exec(out)?.[1] ?? ''; }
+    if (platform === 'linux') { for (const f of ['/etc/machine-id', '/var/lib/dbus/machine-id']) { try { return (await readFile(f, 'utf8')).trim(); } catch { /* try the next */ } } return ''; }
+    if (platform === 'darwin') { const out = await exec('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice']); return /"IOPlatformUUID" = "([^"]+)"/.exec(out)?.[1] ?? ''; }
+  } catch { /* fall back to the host name alone */ }
+  return '';
+}
+
+/** This process: {pid, processStart (ms), hostId, bootStart (ms)}. Computed once. */
+export function currentIdentity({platform = process.platform, exec = run} = {}) {
+  identityPromise ??= (async () => ({
+    pid: process.pid, processStart: PROCESS_START,
+    hostId: createHash('sha256').update(hostname() + '|' + await machineId(platform, exec)).digest('hex').slice(0, 32),
+    bootStart: Math.round(Date.now() - uptime() * 1000)
+  }))();
+  return identityPromise;
+}
+
+/** The start time (ms since the epoch) of another process, or null when it cannot be read. */
+export async function processStartOf(pid, {platform = process.platform, exec = run} = {}) {
+  try {
+    if (platform === 'win32') {
+      const out = await exec('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `(Get-Process -Id ${Number(pid)} -ErrorAction Stop).StartTime.ToUniversalTime().ToString('o')`]);
+      const t = Date.parse(out.trim()); return Number.isFinite(t) ? t : null;
+    }
+    if (platform === 'linux') {
+      const stat = await readFile(`/proc/${Number(pid)}/stat`, 'utf8');
+      const ticks = Number(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19]);
+      const btime = Number(/^btime (\d+)/m.exec(await readFile('/proc/stat', 'utf8'))?.[1]);
+      const hz = Number((await exec('getconf', ['CLK_TCK'])).trim()) || 100;
+      return Number.isFinite(ticks) && Number.isFinite(btime) ? Math.round(btime * 1000 + (ticks / hz) * 1000) : null;
+    }
+    if (platform === 'darwin') { const t = Date.parse((await exec('ps', ['-o', 'lstart=', '-p', String(Number(pid))])).trim()); return Number.isFinite(t) ? t : null; }
+  } catch { /* unknown */ }
+  return null;
+}
+
+/**
+ * Is the owner named in a lock record provably gone? → {verdict: 'gone' | 'alive' | 'unknown', reason}.
+ * @param {{pid, processStart, hostId, bootStart}} record
+ * @param {{platform?: string, exec?: Function, kill?: Function, identity?: object, enabled?: boolean}} options  (injectable for tests)
+ */
+export async function probeOwner(record, {platform = process.platform, exec = run, kill = process.kill.bind(process), identity, enabled} = {}) {
+  const setting = process.env.AETHER_LOCK_RECOVERY; // 'off' turns automatic recovery off everywhere, 'on' also enables it on platforms not yet verified
+  const allowed = enabled ?? (setting === 'off' ? false : VERIFIED_PLATFORMS.includes(platform) || setting === 'on');
+  if (!allowed) return {verdict: 'unknown', reason: `automatic recovery is not enabled on ${platform}`};
+  if (!record || !Number.isSafeInteger(record.pid) || record.pid < 1 || !Number.isFinite(record.processStart) || typeof record.hostId !== 'string' || !Number.isFinite(record.bootStart)) return {verdict: 'unknown', reason: 'the lock does not say who holds it'};
+  const me = identity ?? await currentIdentity({platform, exec});
+  if (record.hostId !== me.hostId) return {verdict: 'unknown', reason: 'the lock was made on another machine'};
+  if (Math.abs(record.bootStart - me.bootStart) > BOOT_TOLERANCE_MS) return {verdict: 'unknown', reason: 'the lock was made before the last restart (this proves nothing about files on a shared disk)'};
+  let exists = true;
+  try { kill(record.pid, 0); } catch (error) { if (error?.code === 'ESRCH') exists = false; else if (error?.code !== 'EPERM') return {verdict: 'unknown', reason: 'the process could not be checked'}; }
+  if (!exists) return {verdict: 'gone', reason: `no process ${record.pid} exists`};
+  const started = await processStartOf(record.pid, {platform, exec});
+  if (started === null) return {verdict: 'unknown', reason: 'the start time of that process could not be read'};
+  if (Math.abs(started - record.processStart) > START_TOLERANCE_MS) return {verdict: 'gone', reason: `process ${record.pid} is a different process now (started at another time)`};
+  return {verdict: 'alive', reason: `process ${record.pid} is running`};
+}

package/src/retry-capability.js

@@ -0,0 +1,35 @@
+import {createHash} from 'node:crypto';
+import {canonicalJson} from './canonical-json.js';
+
+// Shared strict host contract validation; this alone never permits dispatch.
+export function snapshotRetryCapability(value, entry, input) {
+  const contract = JSON.parse(canonicalJson(value));
+  const exact = (object, keys) => object && !Array.isArray(object) &&
+    Object.keys(object).sort().join(',') === keys.split(',').sort().join(',');
+  const text = value => typeof value === 'string' && value.trim().length > 0;
+  const time = value => Number.isSafeInteger(value) && value >= 0;
+  if (!exact(contract, 'version,endpointId,policyVersion,effect,deduplication,expiresAt,evidence') || contract.version !== 1 ||
+      !text(contract.endpointId) || !text(contract.policyVersion) ||
+      !exact(contract.effect, 'tenantId,subject,connectorId,operationId,effectKey,requestDigest,binding') ||
+      !exact(contract.deduplication, 'scope,windowStart,windowEnd,guarantee,rejectsKeyReuse') ||
+      !exact(contract.deduplication.scope, 'accountId,namespace') ||
+      !text(contract.deduplication.scope.accountId) || !text(contract.deduplication.scope.namespace) ||
+      contract.deduplication.guarantee !== 'same-key-same-request' || contract.deduplication.rejectsKeyReuse !== true ||
+      !time(contract.deduplication.windowStart) || !time(contract.deduplication.windowEnd) ||
+      contract.deduplication.windowStart >= contract.deduplication.windowEnd ||
+      !time(contract.expiresAt) || contract.expiresAt > contract.deduplication.windowEnd ||
+      !contract.evidence || Array.isArray(contract.evidence) || typeof contract.evidence !== 'object' ||
+      !Object.keys(contract.evidence).length) throw new TypeError('Invalid remote retry capability');
+  const expected = Object.fromEntries(['tenantId', 'subject', 'connectorId', 'operationId', 'effectKey', 'requestDigest', 'binding'].map(key => [key, entry[key]]));
+  if (Object.values(expected).some(value => value === undefined) ||
+      canonicalJson(contract.effect) !== canonicalJson(expected) ||
+      !/^[a-f0-9]{64}$/.test(entry.requestDigest) ||
+      createHash('sha256').update(canonicalJson(input)).digest('hex') !== entry.requestDigest) throw new Error('Retry capability binding conflict');
+  assertRetryCapabilityTime(contract);
+  return contract;
+}
+export function assertRetryCapabilityTime(contract) {
+  const now = Date.now();
+  if (now < contract.deduplication.windowStart || now >= contract.deduplication.windowEnd || now >= contract.expiresAt) throw new Error('Retry capability expired or not active');
+}
+

package/src/storage-conformance.js

@@ -0,0 +1,81 @@
+import {strict as assert} from 'node:assert';
+import {StorageCorruptionError} from './storage.js';
+
+/**
+ * Conformance cases for any storage backend. `make()` returns {backend, corrupt(key)}: a fresh backend and a way to damage a stored
+ * document. `failWrite(backend)` is optional: when given, it must make the NEXT compareAndSwap fail part-way and throw; the case
+ * then checks that the old document is intact. Use: for (const c of storageConformanceCases(make)) test(c.name, c.run);
+ */
+export function storageConformanceCases(make, {failWrite} = {}) {
+  const cases = [
+    {name: 'a missing key loads as null; create needs expectedVersion null and gives version 1', run: async () => {
+      const {backend} = make();
+      assert.equal(await backend.load('a'), null);
+      assert.deepEqual(await backend.compareAndSwap('a', null, {n: 1}), {ok: true, version: 1});
+      assert.deepEqual(await backend.load('a'), {version: 1, value: {n: 1}});
+      assert.deepEqual(await backend.compareAndSwap('b', 1, {n: 1}), {ok: false, reason: 'conflict', currentVersion: null}, 'updating what does not exist is a conflict');
+    }},
+    {name: 'versions only grow, and a stale or repeated create loses', run: async () => {
+      const {backend} = make();
+      await backend.compareAndSwap('a', null, {n: 1});
+      assert.deepEqual(await backend.compareAndSwap('a', null, {n: 9}), {ok: false, reason: 'conflict', currentVersion: 1});
+      assert.deepEqual(await backend.compareAndSwap('a', 1, {n: 2}), {ok: true, version: 2});
+      assert.deepEqual(await backend.compareAndSwap('a', 1, {n: 3}), {ok: false, reason: 'conflict', currentVersion: 2}, 'the old version is stale');
+      assert.deepEqual(await backend.load('a'), {version: 2, value: {n: 2}}, 'a lost write changes nothing');
+    }},
+    {name: 'concurrent writers from the same version: exactly one wins, and nothing is lost or mixed', run: async () => {
+      const {backend} = make();
+      await backend.compareAndSwap('a', null, {n: 0});
+      const results = await Promise.all(Array.from({length: 8}, (_, i) => backend.compareAndSwap('a', 1, {n: i + 1})));
+      const wins = results.filter(r => r.ok);
+      assert.equal(wins.length, 1); assert.equal(wins[0].version, 2);
+      const now = await backend.load('a');
+      assert.equal(now.version, 2); assert.ok(now.value.n >= 1 && now.value.n <= 8);
+    }},
+    {name: 'a read-modify-write loop with retries loses no update', run: async () => {
+      const {backend} = make();
+      await backend.compareAndSwap('c', null, {n: 0});
+      const bump = async () => { for (;;) { const cur = await backend.load('c'); const r = await backend.compareAndSwap('c', cur.version, {n: cur.value.n + 1}); if (r.ok) return; await new Promise(res => setTimeout(res, 1 + Math.random() * 4)); } };
+      await Promise.all(Array.from({length: 6}, bump));
+      assert.deepEqual(await backend.load('c'), {version: 7, value: {n: 6}});
+    }},
+    {name: 'what is returned is a copy: changing it does not change the store, and neither does changing what was stored', run: async () => {
+      const {backend} = make();
+      const value = {list: [1]};
+      await backend.compareAndSwap('a', null, value); value.list.push(2);
+      const got = await backend.load('a'); got.value.list.push(3);
+      assert.deepEqual((await backend.load('a')).value, {list: [1]});
+    }},
+    {name: 'a damaged document is reported, never returned, and is not overwritten by a write that trusts it', run: async () => {
+      const {backend, corrupt} = make();
+      await backend.compareAndSwap('a', null, {n: 1}); await backend.compareAndSwap('keep', null, {n: 1});
+      await corrupt('a');
+      await assert.rejects(backend.load('a'), StorageCorruptionError);
+      await assert.rejects(backend.compareAndSwap('a', 1, {n: 2}), StorageCorruptionError);
+      assert.deepEqual((await backend.load('keep')).value, {n: 1}, 'other documents are fine');
+    }},
+    {name: 'list shows the keys; bad keys and versions are programming errors', run: async () => {
+      const {backend} = make();
+      await backend.compareAndSwap('b', null, 1); await backend.compareAndSwap('a', null, 2);
+      assert.deepEqual(await backend.list(), ['a', 'b']);
+      for (const bad of ['', '../x', 'a/b', 'a b', '..', 'x'.repeat(121)]) await assert.rejects(backend.load(bad), TypeError, JSON.stringify(bad));
+      await assert.rejects(backend.compareAndSwap('a', 0, 1), TypeError);
+      await assert.rejects(backend.compareAndSwap('a', '1', 1), TypeError);
+    }},
+    {name: 'values are plain JSON: nested data, unicode and null survive exactly', run: async () => {
+      const {backend} = make();
+      const value = {s: 'é — 日本', n: null, a: [1, {b: [true, false]}], big: 'x'.repeat(100000)};
+      await backend.compareAndSwap('a', null, value);
+      assert.deepEqual((await backend.load('a')).value, value);
+    }}
+  ];
+  if (failWrite) cases.push({name: 'a write that fails part-way leaves the old document, and the key can be written again', run: async () => {
+    const {backend} = make();
+    await backend.compareAndSwap('a', null, {n: 1});
+    await failWrite(backend);
+    await assert.rejects(backend.compareAndSwap('a', 1, {n: 2}));
+    assert.deepEqual(await backend.load('a'), {version: 1, value: {n: 1}});
+    assert.deepEqual(await backend.compareAndSwap('a', 1, {n: 3}), {ok: true, version: 2});
+  }});
+  return cases;
+}

package/src/storage.js

@@ -0,0 +1,87 @@
+import {createHash, randomBytes} from 'node:crypto';
+import {mkdir, open, readFile, rename, unlink, readdir} from 'node:fs/promises';
+import {join} from 'node:path';
+import {canonicalJson} from './canonical-json.js';
+
+/**
+ * Storage backend contract (P3): versioned documents with compare-and-swap. This is what a state store needs from the place
+ * its data lives, so the place can be a local folder, a database or an object store without the code above it changing.
+ *
+ *  - load(key) → {version, value} or null when the key does not exist. A document whose stored checksum does not match its
+ *    content is never returned: load throws StorageCorruptionError.
+ *  - compareAndSwap(key, expectedVersion, value) → {ok: true, version} or {ok: false, reason: 'conflict', currentVersion}.
+ *    expectedVersion is null to create (fails if the key exists) or the version last read. Versions only grow, per key.
+ *    The write is all-or-nothing: after a failure or a crash a reader sees the old document or the new one, never a mix.
+ *  - list() → the keys that exist.
+ * Values are plain JSON. No claim is made about network file systems: a backend states what it guarantees, and the
+ * conformance suite (storage-conformance.js) is what shows it. The file backend is for one machine's local disk.
+ */
+export class StorageCorruptionError extends Error {
+  constructor(key) { super(`Stored document "${key}" failed its integrity check`); this.name = 'StorageCorruptionError'; this.key = key; }
+}
+
+const keyOk = key => { if (typeof key !== 'string' || !/^[A-Za-z0-9._-]{1,120}$/.test(key) || key === '.' || key === '..') throw new TypeError('Storage key must be 1 to 120 letters, digits, dots, dashes or underscores'); };
+export const checksumOf = (version, value) => createHash('sha256').update(String(version)).update('\n').update(canonicalJson(value)).digest('hex');
+const envelope = (version, value) => ({v: 1, version, value, checksum: checksumOf(version, value)});
+const open_ = (key, text) => {
+  let e; try { e = JSON.parse(text); } catch { throw new StorageCorruptionError(key); }
+  if (!e || e.v !== 1 || !Number.isSafeInteger(e.version) || e.version < 1 || e.checksum !== checksumOf(e.version, e.value)) throw new StorageCorruptionError(key);
+  return {version: e.version, value: structuredClone(e.value)};
+};
+const conflict = currentVersion => ({ok: false, reason: 'conflict', currentVersion});
+const checkVersion = expected => { if (expected !== null && !(Number.isSafeInteger(expected) && expected >= 1)) throw new TypeError('expectedVersion must be null or a version number'); };
+
+/** In-memory reference backend. `corrupt(key)` damages a stored document (for tests). */
+export function createMemoryStorageBackend() {
+  const docs = new Map(); // key -> JSON text of the envelope
+  return {
+    async load(key) { keyOk(key); return docs.has(key) ? open_(key, docs.get(key)) : null; },
+    async compareAndSwap(key, expected, value) {
+      keyOk(key); checkVersion(expected);
+      const text = docs.get(key); const current = text === undefined ? null : open_(key, text).version;
+      if (expected !== current) return conflict(current);
+      const version = (current ?? 0) + 1;
+      docs.set(key, JSON.stringify(envelope(version, structuredClone(value))));
+      return {ok: true, version};
+    },
+    async list() { return [...docs.keys()].sort(); },
+    corrupt(key) { docs.set(key, docs.get(key).replace('"checksum":"', '"checksum":"0')); }
+  };
+}
+
+/**
+ * File backend for one machine's local disk. Each write goes to a temporary file, is flushed, then renamed over the document;
+ * a crash leaves the old document. Two writers are serialised by a short-lived exclusive-create guard file per key, so the
+ * version check and the write are one step. A guard left by a crash is reported as a conflict until a person removes it
+ * (`<dir>/<key>.guard`); it is never taken over on a timer.
+ */
+// On Windows a file that someone is reading at that moment cannot be replaced or opened for a split second (EPERM, EACCES, EBUSY).
+const busy = error => process.platform === 'win32' && ['EPERM', 'EACCES', 'EBUSY'].includes(error?.code);
+async function patiently(action) { for (let attempt = 0; ; attempt++) { try { return await action(); } catch (error) { if (!busy(error) || attempt >= 200) throw error; await new Promise(r => setTimeout(r, Math.min(5 + attempt * 2, 25))); } } }
+
+export function createFileStorageBackend(dir) {
+  if (typeof dir !== 'string' || !dir) throw new TypeError('Storage directory required');
+  const path = key => join(dir, key + '.doc.json');
+  const read = async key => { try { return await patiently(() => readFile(path(key), 'utf8')); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } };
+  return {
+    async load(key) { keyOk(key); const text = await read(key); return text === null ? null : open_(key, text); },
+    async compareAndSwap(key, expected, value) {
+      keyOk(key); checkVersion(expected); await mkdir(dir, {recursive: true});
+      const guard = join(dir, key + '.guard');
+      let handle;
+      try { handle = await open(guard, 'wx', 0o600); } catch (error) { if (error.code === 'EEXIST' || (process.platform === 'win32' && ['EPERM', 'EACCES', 'EBUSY'].includes(error.code))) return conflict((await this.load(key))?.version ?? null); throw error; }
+      const temp = join(dir, `${key}.${randomBytes(6).toString('hex')}.tmp`);
+      try {
+        const text = await read(key); const current = text === null ? null : open_(key, text).version;
+        if (expected !== current) return conflict(current);
+        const version = (current ?? 0) + 1;
+        const file = await open(temp, 'w', 0o600);
+        try { await file.writeFile(JSON.stringify(envelope(version, structuredClone(value))), 'utf8'); await file.sync(); } finally { await file.close(); }
+        await patiently(() => rename(temp, path(key)));
+        return {ok: true, version};
+      } finally { await handle.close().catch(() => {}); await unlink(guard).catch(() => {}); await unlink(temp).catch(() => {}); }
+    },
+    async list() { try { return (await readdir(dir)).filter(n => n.endsWith('.doc.json')).map(n => n.slice(0, -9)).sort(); } catch (error) { if (error.code === 'ENOENT') return []; throw error; } },
+    corruptForTest: async key => { const text = await read(key); const h = await open(path(key), 'w'); try { await h.writeFile(text.replace('"checksum":"', '"checksum":"0'), 'utf8'); } finally { await h.close(); } }
+  };
+}

package/src/transactions.js

@@ -1,32 +1,102 @@
 import {randomBytes} from 'node:crypto';
-import {open,mkdir,readFile,unlink} from 'node:fs/promises';
+import {open,mkdir,readFile,rename,unlink,writeFile,appendFile} from 'node:fs/promises';
 import {dirname} from 'node:path';
 import {FileStateStore} from './index.js';
+import {currentIdentity,probeOwner} from './process-identity.js';
 
 export class StateBusyError extends Error {
  constructor(){super('State store is locked by another transaction');this.name='StateBusyError';}
 }
-/** Cooperating processes, one canonical path. No stale-lock takeover or implicit retry. */
+export class StateLockLostError extends Error {
+ constructor(){super('The state lock was taken over while this write was waiting; the write was refused and nothing was changed');this.name='StateLockLostError';}
+}
+// On Windows a lock file that another process is deleting at that moment (or still holds open) cannot be created: the system answers
+// EPERM, EACCES or EBUSY instead of EEXIST. That is contention, not a permission problem, so it is reported as busy like any other lock.
+const contended=error=>process.platform==='win32'&&['EPERM','EACCES','EBUSY'].includes(error?.code);
+const parse=text=>{try{const v=JSON.parse(text);return v&&v.v===2&&typeof v.lease==='string'?v:null;}catch{return null;}};
+const readFence=async path=>{try{const n=Number((await readFile(path,'utf8')).trim());return Number.isSafeInteger(n)&&n>=0?n:0;}catch(error){if(error.code==='ENOENT')return 0;throw error;}};
+const processNonce=randomBytes(8).toString('hex');
+
+/**
+ * Cooperating processes, one canonical path. The lock file is a record (version 2): a lease, who holds it (pid and start time,
+ * host, boot) and the fence it saw. A lock left by a crashed process is recovered automatically ONLY when its owner is provably
+ * gone (same machine, same boot, no such process or a different process with that pid; see process-identity.js) and the platform
+ * is enabled for recovery; every other case stays manual (StateBusyError). Recovery takes the lock by an atomic rename, raises a
+ * fence counter (`<state>.fence`) and logs it (`<state>.recovery.log`). A writer that was merely paused and wakes up after a
+ * takeover finds its lock gone and its write is refused (StateLockLostError). No age or timeout is ever used as proof.
+ * Options: `recovery: false` turns recovery off; `recovery: {probe, platform, exec, onRecovered}` are for tests and hosts.
+ */
 export class TransactionalStateStore extends FileStateStore {
+ async #acquire(lock,record){
+  let handle;
+  try{handle=await open(lock,'wx',0o600);}catch(error){if(error.code==='EEXIST'||contended(error))throw new StateBusyError();throw error;}
+  try{await handle.writeFile(record,'utf8');await handle.sync();}finally{await handle.close();}
+ }
+ /** Take over a lock whose owner is provably gone. Returns true when the lock was cleared and acquiring can be retried. */
+ async #recover(lock,fencePath){
+  const options=this.recovery;
+  if(options===false)return false;
+  const raw=await readFile(lock,'utf8').catch(error=>{if(error.code==='ENOENT')return null;throw error;});
+  if(raw===null)return true; // it was released in the meantime
+  const record=parse(raw);
+  if(!record)return false; // a version 1 or unreadable lock: manual
+  const probe=options?.probe??(r=>probeOwner(r,options??{}));
+  const first=await probe(record);
+  if(first.verdict!=='gone')return false;
+  // Claim by rename (then the marker below picks exactly one winner); a lock that changed meanwhile is not what was judged.
+  const claimed=lock+'.recovering.'+randomBytes(8).toString('hex');
+  try{await rename(lock,claimed);}catch{return false;}
+  try{
+   const seen=await readFile(claimed,'utf8').catch(()=>null);
+   const again=seen===raw?await probe(record):{verdict:'changed'};
+   if(again.verdict!=='gone'){
+    // Not the lock that was judged (or the evidence changed): put it back if the way is free, otherwise leave it for a person.
+    try{const h=await open(lock,'wx',0o600);try{await h.writeFile(seen??raw,'utf8');await h.sync();}finally{await h.close();}await unlink(claimed);}catch{/* left as .recovering for a person */}
+    return false;
+   }
+   // On Windows two concurrent renames of the same file can both succeed, so the rename alone does not pick one winner. Exactly one
+   // recoverer per abandoned lease creates this marker (exclusive create); the other drops its copy and just tries to acquire.
+   try{const marker=await open(this.path+'.recovered-'+record.lease.slice(0,24).replace(/[^0-9a-f]/gi,'_'),'wx',0o600);await marker.close();}
+   catch{await unlink(claimed).catch(()=>{});return true;}
+   const fence=(await readFence(fencePath))+1;
+   await writeFile(fencePath,String(fence)+'\n','utf8');
+   const entry={at:new Date().toISOString(),recoveredPid:record.pid,reason:first.reason,fence,host:record.hostId};
+   await appendFile(this.path+'.recovery.log',JSON.stringify(entry)+'\n','utf8').catch(()=>{});
+   try{options?.onRecovered?.(entry);}catch{/* a host callback never blocks recovery */}
+   await unlink(claimed);
+   return true;
+  }catch{return false;}
+ }
  async transaction(update) {
   if(typeof update!=='function')throw new TypeError('Transaction callback required');
-  const lock=this.path+'.lock',lease=randomBytes(24).toString('hex');
+  const lock=this.path+'.lock',fencePath=this.path+'.fence';
   await mkdir(dirname(this.path),{recursive:true});
-  let handle;
-  try{handle=await open(lock,'wx',0o600);}catch(error){if(error.code==='EEXIST')throw new StateBusyError();throw error;}
+  const me=await currentIdentity(this.recovery&&this.recovery.platform?{platform:this.recovery.platform,exec:this.recovery.exec}:{});
+  const lease=randomBytes(24).toString('hex');
+  const recordFor=fence=>JSON.stringify({v:2,lease,owner:processNonce,pid:me.pid,processStart:me.processStart,hostId:me.hostId,bootStart:me.bootStart,fence,createdAt:new Date().toISOString()});
+  try{await this.#acquire(lock,recordFor(await readFence(fencePath)));}
+  catch(error){
+   if(!(error instanceof StateBusyError))throw error;
+   if(!(await this.#recover(lock,fencePath).catch(()=>false)))throw error;
+   await this.#acquire(lock,recordFor(await readFence(fencePath)));
+  }
+  const held=await readFile(lock,'utf8');
+  let lost=false;
   try {
-   try{await handle.writeFile(lease,'utf8');await handle.sync();}finally{await handle.close();}
    const previous=await super.load();
    const next=await update(structuredClone(previous));
    // Clone before awaiting I/O so a caller cannot change the snapshot during save.
    const snapshot=structuredClone(next);
+   // A writer that was paused while someone took the lock over must not write: its lock is no longer the one in place.
+   const still=await readFile(lock,'utf8').catch(error=>{if(error.code==='ENOENT')return null;throw error;});
+   if(still!==held){lost=true;throw new StateLockLostError();}
    await super.save(snapshot);
    return structuredClone(snapshot);
   } finally {
    // Never remove a replacement lock if an external operator changed ownership.
    const owner=await readFile(lock,'utf8').catch(error=>{if(error.code==='ENOENT')return null;throw error;});
-   if(owner===lease)await unlink(lock);
-   else throw new Error('State lock ownership changed; manual recovery required');
+   if(owner===held)await unlink(lock);
+   else if(!lost)throw new Error('State lock ownership changed; manual recovery required');
   }
  }
  async save(state){const snapshot=structuredClone(state);await this.transaction(()=>snapshot);}