@gregiteen/ssss-cli 0.9.2 → 0.9.3

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-09-24
+### Fixed
+- Two processes sending an `event` envelope with the same idempotency key at the
+  same moment could both append an event, because the kernel records the result
+  only after committing and `event` envelopes have no VFS compare-and-swap. The
+  kernel now derives an `event` envelope's `event_id` from `(workspace_id,
+  idempotency_key)` (`idempotentEventId`, UUIDv5), so the event store rejects
+  the second append. Any request that loses at commit re-reads the idempotency
+  store and returns the winner's result as a replay, or an idempotency conflict
+  when its request differs. If a process dies after appending an event but
+  before recording its result, retries of that key now fail instead of
+  appending a second event.
+
+### Added
+- `idempotentEventId(workspaceId, idempotencyKey)` in `@gregiteen/ssss-cli/events`.
+- Conformance checks racing six kernel processes on one `event` idempotency key,
+  with identical and with differing content.
+
 ## [0.9.2] - 2026-09-24
 ### Fixed
 - The file adapters are now safe to share between processes. Each one checked

package/VERSION

@@ -1 +1 @@
-0.9.2
+0.9.3

package/conformance/reference-bundle.ucw.json

@@ -106,7 +106,7 @@
     "file_count": 14,
     "provenance": {
       "content_hash": "sha256:7febd673938a3dc04c068e0bf08097a9783c09e612606d2df9a4db8dcb8907f5",
-      "exporter": "@gregiteen/ssss-cli@0.9.2"
+      "exporter": "@gregiteen/ssss-cli@0.9.3"
     }
   },
   "files": [

package/docs/help/concurrency.md

@@ -13,6 +13,23 @@ most one racer wins:
 
 `.ssss-locks/` is reserved: VFS paths under it are rejected and `list()` skips it.
 
+## Same idempotency key from two processes
+
+The kernel records a request's result only after it commits, so two processes
+can both miss the stored result for one key. The commit step then decides:
+
+- `operation`, `patch`, `delete`: the VFS compare-and-swap lets one commit; the
+  other fails its precondition.
+- `event`: the event's `event_id` is derived from `(workspace_id,
+  idempotency_key)` (`idempotentEventId`, a UUIDv5), so the event store rejects
+  the second append.
+
+The loser then re-reads the idempotency store: if the winner has already
+recorded its result, the loser returns it as a replay (or an idempotency
+conflict when its request differs); otherwise it fails and a retry replays. If a
+process dies after appending an event but before recording the result, retries
+of that key fail rather than append a second event.
+
 ## Crashed holders
 
 A lock records its holder's pid and host. A waiter breaks the lock when the
@@ -31,10 +48,6 @@ Symlinked lock files are refused.
 
 - Locks are advisory: only writers using these adapters take them. Writers from
   `@gregiteen/ssss-cli` 0.9.1 and earlier do not.
-- The kernel's idempotency check for `event` envelopes is read before commit and
-  written after, so two processes sending the same idempotency key at the same
-  moment can each append an event. `operation`, `patch`, and `delete` are
-  protected by the VFS compare-and-swap.
 - Network filesystems must support exclusive create (`O_EXCL`).
 - Dead-holder detection assumes processes that share the filesystem have
   distinct hostnames (containers with the same hostname and separate pid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gregiteen/ssss-cli",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "CLI tools and the reference engine for the Structured Semantic Syntax System",
   "main": "src/engine.mjs",
   "exports": {

package/scripts/conformance-09.mjs

@@ -13,7 +13,7 @@ import {
 } from '../src/registry.mjs';
 import { createValidator } from '../src/validator.mjs';
 import { FileSystemVfs, MemoryVfs, runVfsContract } from '../src/vfs.mjs';
-import { JsonlEventStore, MemoryEventStore, createCanonicalEvent } from '../src/events.mjs';
+import { JsonlEventStore, MemoryEventStore, createCanonicalEvent, idempotentEventId } from '../src/events.mjs';
 import {
   ProjectionCoordinator,
   createSqlProjectionAdapter,
@@ -119,6 +119,33 @@ async function checkFileAdapterRaces(root, principal, check) {
   const stored = await new FileIdempotencyStore(idempotencyRoot).get('acme', 'race');
   check('filesystem idempotency store accepts one of several processes putting the same key',
     winners(puts).length === 1 && stored?.request_hash === `racer-${winners(puts)[0]?.racer}`, describe(puts));
+
+  const kernelRoot = path.join(root, 'kernel');
+  const kernelPrincipal = { ...principal, capabilities: ['*:*'] };
+  const stores = () => ({
+    vfs: new FileSystemVfs(kernelRoot),
+    eventStore: new JsonlEventStore(path.join(kernelRoot, '.events')),
+    idempotencyStore: new FileIdempotencyStore(path.join(kernelRoot, '.idempotency')),
+  });
+  const envelope = (key, content) => ({ type: 'event', workspace_id: 'acme', idempotency_key: key, path: 'events/race.md', content });
+  const kernelRace = (key, contentExpression) => raceProcesses(racers, {
+    createKernel: '../src/kernel.mjs', FileSystemVfs: '../src/vfs.mjs', JsonlEventStore: '../src/events.mjs', FileIdempotencyStore: '../src/idempotency.mjs',
+  }, [
+    `const kernel = createKernel({ vfs: new FileSystemVfs(${JSON.stringify(kernelRoot)}), eventStore: new JsonlEventStore(${JSON.stringify(path.join(kernelRoot, '.events'))}), idempotencyStore: new FileIdempotencyStore(${JSON.stringify(path.join(kernelRoot, '.idempotency'))}) })`,
+    `const result = await kernel.execute({ type: 'event', workspace_id: 'acme', idempotency_key: ${JSON.stringify(key)}, path: 'events/race.md', content: ${contentExpression} }, { principal: ${JSON.stringify(kernelPrincipal)} })`,
+    "if (!result.success) throw new Error(result.validation.errors.join('; '))",
+  ].join(';\n'));
+  const eventsFor = (key) => fs.readFileSync(path.join(kernelRoot, '.events', 'acme.jsonl'), 'utf8')
+    .split('\n').filter(Boolean).map((line) => JSON.parse(line)).filter((event) => event.idempotency_key === key);
+  const same = await kernelRace('race-same', 'JSON.stringify({ n: 1 })');
+  const retried = await createKernel(stores()).execute(envelope('race-same', JSON.stringify({ n: 1 })), { principal: kernelPrincipal });
+  check('kernel appends one event when several processes send the same event envelope',
+    eventsFor('race-same').length === 1 && winners(same).length >= 1 && retried.replay === true, describe(same));
+  const differing = await kernelRace('race-differ', 'JSON.stringify({ racer })');
+  check('kernel appends one event when several processes reuse a key with different content',
+    eventsFor('race-differ').length === 1 && winners(differing).length === 1, describe(differing));
+  check('kernel derives event envelope ids from the idempotency key',
+    eventsFor('race-same')[0]?.event_id === idempotentEventId('acme', 'race-same'));
 }
 
 async function checkFileLocks(root, principal, check) {

package/src/events.mjs

@@ -4,6 +4,22 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { withFileLock } from './file-lock.mjs';
 
+// UUIDv5 namespace for event ids derived from idempotency keys.
+const IDEMPOTENT_EVENT_NAMESPACE = Buffer.from('6f1c2d9e4b7a4e0c9f35a1d8c3b2e7f4', 'hex');
+
+/**
+ * Deterministic event_id (UUIDv5) for one (workspace_id, idempotency_key).
+ * The kernel uses it for `event` envelopes so a store's duplicate-event_id
+ * check stops two concurrent requests with the same key from both appending.
+ */
+export function idempotentEventId(workspaceId, idempotencyKey) {
+  const hash = crypto.createHash('sha1').update(IDEMPOTENT_EVENT_NAMESPACE).update(JSON.stringify([workspaceId, idempotencyKey])).digest();
+  hash[6] = (hash[6] & 0x0f) | 0x50;
+  hash[8] = (hash[8] & 0x3f) | 0x80;
+  const hex = hash.subarray(0, 16).toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
 export function createCanonicalEvent(input, options = {}) {
   const required = ['workspace_id', 'action', 'subject', 'operation_id', 'idempotency_key'];
   for (const field of required) if (typeof input?.[field] !== 'string' || !input[field]) throw new Error(`Event ${field} is required.`);

package/src/kernel.mjs

@@ -7,7 +7,7 @@ import { parseDocument, serializeDocument } from './frontmatter.mjs';
 import { createValidator } from './validator.mjs';
 import { isAppendType, resolvePrimitiveDefinition } from './registry.mjs';
 import { createCapabilityAuthorizer } from './authorization.mjs';
-import { createCanonicalEvent } from './events.mjs';
+import { createCanonicalEvent, idempotentEventId } from './events.mjs';
 import { MemoryIdempotencyStore } from './idempotency.mjs';
 
 export { MemoryIdempotencyStore } from './idempotency.mjs';
@@ -92,13 +92,17 @@ export function createKernel(options = {}) {
     }
 
     const requestHash = canonicalRequestHash(envelope, principal);
-    const replay = await idempotencyStore.get(envelope.workspace_id, envelope.idempotency_key);
-    if (replay) {
-      if (replay.request_hash !== requestHash) {
+    // A stored result for this key: replay it, or refuse a different request.
+    const settled = async () => {
+      const stored = await idempotencyStore.get(envelope.workspace_id, envelope.idempotency_key);
+      if (!stored) return null;
+      if (stored.request_hash !== requestHash) {
         return failure(envelope, operationId, ['Idempotency key was already used for a different request.'], [{ field: 'idempotency_key', issue: 'Request hash conflict.' }]);
       }
-      return { ...replay.response, replay: true };
-    }
+      return { ...stored.response, replay: true };
+    };
+    const replay = await settled();
+    if (replay) return replay;
 
     let current;
     try { current = await vfs.read(envelope.path); }
@@ -211,6 +215,9 @@ export function createKernel(options = {}) {
       }
 
       const event = createCanonicalEvent({
+        // `event` envelopes have no VFS compare-and-swap, so a key-derived id
+        // lets the event store reject a concurrent request with the same key.
+        event_id: envelope.type === 'event' ? idempotentEventId(envelope.workspace_id, envelope.idempotency_key) : undefined,
         workspace_id: envelope.workspace_id,
         primitive_id: definition.qualified_type,
         primitive_version: definition.primitive_version || 1,
@@ -252,6 +259,12 @@ export function createKernel(options = {}) {
           return failure(envelope, operationId, [`Commit failed: ${error.message}; rollback failed: ${rollbackError.message}`]);
         }
       }
+      // A concurrent request with the same key may have won the commit (VFS
+      // compare-and-swap or duplicate event_id); answer with its result.
+      try {
+        const winner = await settled();
+        if (winner) return winner;
+      } catch {}
       return failure(envelope, operationId, [`Commit failed: ${error.message}`]);
     }
   }