@gregiteen/ssss-cli 0.8.0 → 0.9.1

package/src/events.mjs

@@ -0,0 +1,155 @@
+/** Canonical immutable SSSS event envelope and stores. */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+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.`);
+  if (!input.principal?.id || !input.principal?.kind) throw new Error('Event verified principal is required.');
+  return {
+    event_id: input.event_id || crypto.randomUUID(),
+    event_type: input.event_type || 'ssss.mutation',
+    schema_version: 1,
+    timestamp: input.timestamp || (options.clock ? options.clock() : new Date().toISOString()),
+    workspace_id: input.workspace_id,
+    primitive_id: input.primitive_id || null,
+    primitive_version: input.primitive_version || 1,
+    action: input.action,
+    subject: input.subject,
+    principal: input.principal,
+    correlation_id: input.correlation_id || input.operation_id,
+    causation_id: input.causation_id || null,
+    operation_id: input.operation_id,
+    idempotency_key: input.idempotency_key,
+    request_hash: input.request_hash || null,
+    before_hash: input.before_hash || null,
+    after_hash: input.after_hash || null,
+    changed_fields: input.changed_fields || [],
+    resource_status: input.resource_status || null,
+    payload: input.payload || null,
+  };
+}
+
+export class MemoryEventStore {
+  #events = [];
+  #ids = new Set();
+  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);
+    return structuredClone(frozen);
+  }
+  async *replay(options = {}) {
+    for (let index = options.cursor || 0; index < this.#events.length; index++) {
+      const event = this.#events[index];
+      if (options.workspaceId && event.workspace_id !== options.workspaceId) continue;
+      yield { cursor: index + 1, event: structuredClone(event) };
+    }
+  }
+  async size() { return this.#events.length; }
+}
+
+const NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+const APPEND_FLAGS = fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | NOFOLLOW;
+
+function openLog(file, flags, mode) {
+  try { return fs.openSync(file, flags, mode); }
+  catch (error) {
+    if (error.code === 'ELOOP') throw new Error('Symlinked event logs are forbidden.');
+    throw error;
+  }
+}
+
+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;
+}
+
+/** Read every event_id in a log, bounded to the bytes covered by the returned stat. */
+function loadIndex(file) {
+  const fd = openLog(file, fs.constants.O_RDONLY | NOFOLLOW);
+  try {
+    const stat = fs.fstatSync(fd);
+    const bytes = Buffer.alloc(stat.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const read = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+      if (read === 0) break;
+      offset += read;
+    }
+    const ids = new Set();
+    for (const line of bytes.subarray(0, offset).toString('utf8').split('\n')) {
+      if (line.trim()) ids.add(JSON.parse(line).event_id);
+    }
+    return { ids, stat };
+  } finally { fs.closeSync(fd); }
+}
+
+export class JsonlEventStore {
+  // Per-log index of event_ids, built on the first append to that log. Each
+  // index records the stat of the bytes it covers; any change (another store
+  // instance or process appended, or the file was replaced) rebuilds it.
+  #indexes = new Map();
+  constructor(root) {
+    fs.mkdirSync(root, { recursive: true });
+    this.root = fs.realpathSync(root);
+  }
+  #file(workspaceId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(workspaceId || '')) throw new Error('Unsafe event workspace_id.');
+    return path.join(this.root, `${workspaceId}.jsonl`);
+  }
+  #index(file) {
+    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 };
+    }
+    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;
+    const index = loadIndex(file);
+    this.#indexes.set(file, index);
+    return index;
+  }
+  async append(event) {
+    const file = this.#file(event.workspace_id);
+    const index = this.#index(file);
+    if (index.ids.has(event.event_id)) throw new Error(`Duplicate event_id '${event.event_id}'.`);
+    const line = `${JSON.stringify(event)}\n`;
+    this.#indexes.delete(file);
+    const fd = openLog(file, APPEND_FLAGS, 0o600);
+    let after;
+    try {
+      fs.writeFileSync(fd, line);
+      after = fs.fstatSync(fd);
+    } finally { fs.closeSync(fd); }
+    // Keep the index only when the log grew by exactly this line on the same
+    // file; otherwise another writer interleaved and the next append rebuilds.
+    const before = index.stat;
+    const expectedSize = (before?.size || 0) + Buffer.byteLength(line);
+    if (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 });
+    }
+    return structuredClone(event);
+  }
+  async *replay(options = {}) {
+    const files = options.workspaceId
+      ? [this.#file(options.workspaceId)]
+      : fs.readdirSync(this.root).filter((name) => name.endsWith('.jsonl')).sort().map((name) => path.join(this.root, name));
+    let cursor = 0;
+    for (const file of files) {
+      if (!fs.existsSync(file)) continue;
+      if (fs.lstatSync(file).isSymbolicLink()) throw new Error('Symlinked event logs are forbidden.');
+      for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+        if (!line.trim()) continue;
+        cursor++;
+        if (cursor <= (options.cursor || 0)) continue;
+        yield { cursor, event: JSON.parse(line) };
+      }
+    }
+  }
+}

package/src/guard.mjs

@@ -0,0 +1,32 @@
+/** Static guard for likely direct canonical writes outside approved SSSS adapters. */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const WRITE_PATTERNS = [
+  /\bfs\.(?:writeFile|writeFileSync|appendFile|appendFileSync|rm|rmSync|unlink|unlinkSync|rename|renameSync)\s*\(/,
+  /\b(?:writeFile|appendFile|unlink|rename)\s*\(/,
+  /\b(?:insert|update|delete)\s*\([^)]*\)\s*\.?(?:values|set|where)?\s*\(/,
+];
+
+export function detectDirectWrites(root, options = {}) {
+  const approved = (options.approved || []).map((entry) => entry.replaceAll('\\', '/'));
+  const include = options.include || /\.(?:[cm]?[jt]sx?)$/;
+  const findings = [];
+  const stack = [path.resolve(root)];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === 'dist' || entry.name === 'build') continue;
+      const absolute = path.join(dir, entry.name);
+      if (entry.isDirectory()) { stack.push(absolute); continue; }
+      const relative = path.relative(root, absolute).split(path.sep).join('/');
+      if (!include.test(relative) || approved.some((prefix) => relative === prefix || relative.startsWith(`${prefix}/`))) continue;
+      const lines = fs.readFileSync(absolute, 'utf8').split('\n');
+      for (const [index, line] of lines.entries()) {
+        if (line.includes('ssss-direct-write-approved')) continue;
+        if (WRITE_PATTERNS.some((pattern) => pattern.test(line))) findings.push({ file: relative, line: index + 1, source: line.trim() });
+      }
+    }
+  }
+  return findings;
+}

package/src/http.mjs

@@ -0,0 +1,26 @@
+/** Reference transport adapters. HTTP is a façade over kernel.execute, never a writer. */
+
+export function createCommandHandler({ kernel, authenticate, parseBody = async (request) => request.json() }) {
+  if (!kernel?.execute || typeof authenticate !== 'function') throw new Error('kernel and authenticate(request) are required.');
+  return async function handle(request) {
+    try {
+      const principal = await authenticate(request);
+      const envelope = await parseBody(request);
+      const response = await kernel.execute(envelope, { principal, request });
+      const status = response.success ? (response.replay ? 200 : response.dry_run ? 200 : 201) :
+        response.validation?.errors?.some((error) => error.includes('Access denied')) ? 403 :
+        response.validation?.errors?.some((error) => error.includes('Idempotency')) ? 409 : 422;
+      return { status, headers: { 'content-type': 'application/json' }, body: response };
+    } catch (error) {
+      return { status: 400, headers: { 'content-type': 'application/json' }, body: { success: false, error: { code: 'invalid_request', message: error.message } } };
+    }
+  };
+}
+
+export function createDomainCommand({ kernel, buildEnvelope }) {
+  if (!kernel?.execute || typeof buildEnvelope !== 'function') throw new Error('kernel and buildEnvelope(input) are required.');
+  return async function domainCommand(input, context) {
+    const envelope = await buildEnvelope(input, context);
+    return kernel.execute(envelope, context);
+  };
+}

package/src/idempotency.mjs

@@ -0,0 +1,55 @@
+/** Durable and in-memory idempotency store contracts. */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+function key(workspaceId, idempotencyKey) { return JSON.stringify([workspaceId, idempotencyKey]); }
+
+export class MemoryIdempotencyStore {
+  #entries = new Map();
+  async get(workspaceId, idempotencyKey) { return structuredClone(this.#entries.get(key(workspaceId, idempotencyKey)) || null); }
+  async put(workspaceId, idempotencyKey, value) {
+    const id = key(workspaceId, idempotencyKey);
+    if (this.#entries.has(id)) throw new Error('Idempotency entry already exists.');
+    this.#entries.set(id, structuredClone(value));
+  }
+}
+
+export class FileIdempotencyStore {
+  constructor(root) { fs.mkdirSync(root, { recursive: true }); this.root = fs.realpathSync(root); }
+  #file(workspaceId, idempotencyKey) {
+    const digest = crypto.createHash('sha256').update(key(workspaceId, idempotencyKey)).digest('hex');
+    return path.join(this.root, `${digest}.json`);
+  }
+  async get(workspaceId, idempotencyKey) {
+    const file = this.#file(workspaceId, idempotencyKey);
+    if (!fs.existsSync(file)) return null;
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('Idempotency state is unreadable.');
+    try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch { throw new Error('Idempotency state is unreadable.'); }
+  }
+  async put(workspaceId, idempotencyKey, value) {
+    const file = this.#file(workspaceId, idempotencyKey);
+    if (fs.existsSync(file)) throw new Error('Idempotency entry already exists.');
+    const temp = `${file}.${crypto.randomUUID()}.tmp`;
+    try {
+      fs.writeFileSync(temp, `${JSON.stringify(value)}\n`, { flag: 'wx', mode: 0o600 });
+      fs.renameSync(temp, file);
+    } finally { fs.rmSync(temp, { force: true }); }
+  }
+}
+
+export async function runIdempotencyContract(store) {
+  const workspace = `ws-${crypto.randomUUID()}`;
+  const id = `key-${crypto.randomUUID()}`;
+  const checks = [];
+  const record = (name, passed) => checks.push({ name, passed: !!passed });
+  record('missing key returns null', await store.get(workspace, id) === null);
+  await store.put(workspace, id, { request_hash: 'sha256:test', response: { success: true } });
+  record('stored result round-trips', (await store.get(workspace, id))?.request_hash === 'sha256:test');
+  let duplicate = false;
+  try { await store.put(workspace, id, { request_hash: 'different' }); } catch { duplicate = true; }
+  record('duplicate put is rejected', duplicate);
+  return { passed: checks.every((check) => check.passed), checks };
+}

package/src/kernel.mjs

@@ -0,0 +1,260 @@
+/**
+ * SSSS 0.9 shared mutation kernel.
+ * Hosts inject infrastructure adapters; this module owns ordering and semantics.
+ */
+import crypto from 'node:crypto';
+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 { MemoryIdempotencyStore } from './idempotency.mjs';
+
+export { MemoryIdempotencyStore } from './idempotency.mjs';
+
+const COMMAND_TYPES = new Set(['operation', 'patch', 'event', 'delete']);
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+  return value;
+}
+
+export function canonicalRequestHash(envelope, principal) {
+  const clean = {
+    type: envelope?.type,
+    workspace_id: envelope?.workspace_id,
+    idempotency_key: envelope?.idempotency_key,
+    path: envelope?.path,
+    primitive_type: envelope?.primitive_type,
+    content: envelope?.content,
+    patches: envelope?.patches,
+    verified_principal_id: principal?.id || null,
+  };
+  return `sha256:${crypto.createHash('sha256').update(JSON.stringify(stable(clean))).digest('hex')}`;
+}
+
+function failure(envelope, operationId, errors, fieldErrors = []) {
+  return {
+    success: false,
+    type: envelope?.type || null,
+    operation_id: operationId,
+    path: envelope?.path || '',
+    committed_at: null,
+    dry_run: !!envelope?.dry_run,
+    validation: { valid: false, type: null, errors, warnings: [] },
+    repair: { field_errors: fieldErrors.length ? fieldErrors : errors.map((issue) => ({ field: '(root)', issue })) },
+  };
+}
+
+function actionFor(envelope, exists, appendOnly) {
+  if (envelope.type === 'operation') return exists ? 'replace' : 'create';
+  if (envelope.type === 'patch') return appendOnly && envelope.patches?.__body__ !== undefined ? 'append' : 'patch';
+  return envelope.type;
+}
+
+export function createKernel(options = {}) {
+  const {
+    vfs,
+    eventStore,
+    projectionCoordinator,
+    leaseStore = null,
+    idempotencyStore = new MemoryIdempotencyStore(),
+    authorize = createCapabilityAuthorizer(),
+    resourceCoordinator = null,
+    clock = () => new Date().toISOString(),
+    idGenerator = () => crypto.randomUUID(),
+  } = options;
+  if (!vfs) throw new Error('createKernel requires a VFS adapter.');
+  if (!eventStore) throw new Error('createKernel requires an event store.');
+  const validator = options.validator || createValidator(options);
+  const registrySet = validator.registry;
+
+  async function execute(rawEnvelope, context = {}) {
+    const envelope = { ...rawEnvelope };
+    delete envelope.actor;
+    const operationId = envelope.operation_id || idGenerator();
+    const principal = context.principal;
+
+    if (!COMMAND_TYPES.has(envelope.type)) {
+      return failure(envelope, operationId, [`Invalid command type '${envelope.type}'.`], [{ field: 'type', issue: 'Use operation, patch, event, or delete.' }]);
+    }
+    for (const field of ['workspace_id', 'idempotency_key', 'path']) {
+      if (typeof envelope[field] !== 'string' || !envelope[field]) {
+        return failure(envelope, operationId, [`Missing required field '${field}'.`], [{ field, issue: 'Required.' }]);
+      }
+    }
+    if (envelope.type === 'operation' && typeof envelope.content !== 'string') {
+      return failure(envelope, operationId, ['Operation content must be a string.'], [{ field: 'content', issue: 'Required string.' }]);
+    }
+    if (envelope.type === 'patch' && (!envelope.patches || typeof envelope.patches !== 'object')) {
+      return failure(envelope, operationId, ['Patch requires a patches object.'], [{ field: 'patches', issue: 'Required object.' }]);
+    }
+
+    const requestHash = canonicalRequestHash(envelope, principal);
+    const replay = await idempotencyStore.get(envelope.workspace_id, envelope.idempotency_key);
+    if (replay) {
+      if (replay.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 };
+    }
+
+    let current;
+    try { current = await vfs.read(envelope.path); }
+    catch (error) { return failure(envelope, operationId, [error.message], [{ field: 'path', issue: error.message }]); }
+
+    let definition = null;
+    let declaredType = envelope.primitive_type || null;
+    let nextContent = null;
+    let nextData = null;
+    let currentData = null;
+
+    if (current) {
+      try { currentData = parseDocument(current.bytes.toString('utf8')).data; }
+      catch (error) { return failure(envelope, operationId, [`Existing document is invalid: ${error.message}`]); }
+      declaredType ||= currentData.type;
+    }
+    if (envelope.type === 'operation') {
+      if (envelope.path.endsWith('/index.md')) {
+        declaredType = 'index';
+        definition = { type: 'index', qualified_type: 'ssss:index', primitive_version: 1, capabilities: {} };
+        nextContent = envelope.content;
+        nextData = {};
+      } else {
+        const validation = validator.validateDocument(envelope.content, { resolveReference: context.resolveReference });
+        if (!validation.valid) return failure(envelope, operationId, validation.errors, validation.field_errors);
+        declaredType = validation.declared_type;
+        definition = resolvePrimitiveDefinition(registrySet, declaredType);
+        nextContent = envelope.content;
+        nextData = validation.data;
+      }
+      if (currentData?.type && currentData.type !== nextData.type) {
+        return failure(envelope, operationId, ['Operation may not change an existing document type.'], [{ field: 'type', issue: 'Use an explicit migration.' }]);
+      }
+    } else if (envelope.type === 'patch') {
+      if (!current) return failure(envelope, operationId, ['Patch target does not exist.'], [{ field: 'path', issue: 'Target not found.' }]);
+      definition = resolvePrimitiveDefinition(registrySet, declaredType);
+      if (!definition) return failure(envelope, operationId, [`Unknown SSSS primitive '${declaredType}'.`], [{ field: 'type', issue: 'Unknown primitive.' }]);
+      if (Object.hasOwn(envelope.patches, 'type') && envelope.patches.type !== currentData.type) {
+        return failure(envelope, operationId, ['Patch may not change document type.'], [{ field: 'type', issue: 'Use an explicit migration.' }]);
+      }
+      nextData = { ...currentData, ...Object.fromEntries(Object.entries(envelope.patches).filter(([key]) => key !== '__body__')) };
+      for (const field of definition.immutable_fields || []) {
+        if (Object.hasOwn(envelope.patches, field) && JSON.stringify(currentData[field]) !== JSON.stringify(nextData[field])) {
+          return failure(envelope, operationId, [`Patch may not change immutable field '${field}'.`], [{ field, issue: 'Use an explicit migration.' }]);
+        }
+      }
+      const parsedCurrent = parseDocument(current.bytes.toString('utf8'));
+      const appendOnly = isAppendType(definition);
+      let body = parsedCurrent.body;
+      if (envelope.patches.__body__ !== undefined) {
+        body = appendOnly ? `${body.replace(/\s+$/, '')}\n${envelope.patches.__body__}` : String(envelope.patches.__body__);
+      }
+      const validation = validator.validateData(nextData, { resolveReference: context.resolveReference });
+      if (!validation.valid) return failure(envelope, operationId, validation.errors, validation.field_errors);
+      nextContent = serializeDocument(nextData, body);
+    } else if (envelope.type === 'delete') {
+      if (!current) return failure(envelope, operationId, ['Delete target does not exist.'], [{ field: 'path', issue: 'Target not found.' }]);
+      definition = resolvePrimitiveDefinition(registrySet, declaredType);
+      if (!definition) return failure(envelope, operationId, [`Unknown SSSS primitive '${declaredType}'.`]);
+      if (isAppendType(definition)) return failure(envelope, operationId, [`Append-only primitive '${declaredType}' cannot be deleted.`]);
+    } else {
+      definition = { type: 'event', qualified_type: 'ssss:event', primitive_version: 1, capabilities: { event: ['write:event'] } };
+      try { if (typeof envelope.content === 'string') JSON.parse(envelope.content); }
+      catch { return failure(envelope, operationId, ['Event content must be valid JSON.'], [{ field: 'content', issue: 'Expected JSON string.' }]); }
+    }
+
+    const appendOnly = isAppendType(definition);
+    const action = actionFor(envelope, !!current, appendOnly);
+    const auth = await authorize({ principal, workspaceId: envelope.workspace_id, definition, action, context });
+    if (!auth.allowed) return failure(envelope, operationId, [`Access denied: ${auth.reason}`], [{ field: 'principal', issue: auth.reason }]);
+
+    if ((definition?.lease_required || context.requireLease) && leaseStore) {
+      let lease;
+      try {
+        lease = await leaseStore.verify({
+          workspace_id: envelope.workspace_id,
+          target: envelope.path,
+          principal_id: principal.id,
+          operation_id: operationId,
+          lease_id: envelope.lease_id,
+        });
+      } catch (error) {
+        return failure(envelope, operationId, [`Lease state is unreadable: ${error.message}`], [{ field: 'lease_id', issue: 'Lease state is unreadable.' }]);
+      }
+      if (!lease.valid) return failure(envelope, operationId, [lease.reason], [{ field: 'lease_id', issue: lease.reason }]);
+    }
+
+    let resourceState = null;
+    if (resourceCoordinator?.prepare) {
+      try { resourceState = await resourceCoordinator.prepare({ envelope, principal, definition, action, current, nextContent }); }
+      catch (error) { return failure(envelope, operationId, [`Resource prepare failed: ${error.message}`]); }
+    }
+
+    if (envelope.dry_run) {
+      return {
+        success: true, type: envelope.type, operation_id: operationId, path: envelope.path,
+        committed_at: null, dry_run: true,
+        validation: { valid: true, type: definition.qualified_type, errors: [], warnings: [] },
+      };
+    }
+
+    let commit = null;
+    try {
+      if (envelope.type === 'operation') {
+        commit = await vfs.writeAtomic(envelope.path, nextContent, current ? { version: current.version } : { ifAbsent: true });
+      } else if (envelope.type === 'patch') {
+        commit = await vfs.writeAtomic(envelope.path, nextContent, { version: current.version });
+      } else if (envelope.type === 'delete') {
+        commit = await vfs.remove(envelope.path, { version: current.version });
+      }
+
+      const event = createCanonicalEvent({
+        workspace_id: envelope.workspace_id,
+        primitive_id: definition.qualified_type,
+        primitive_version: definition.primitive_version || 1,
+        action,
+        subject: envelope.path,
+        principal,
+        operation_id: operationId,
+        idempotency_key: envelope.idempotency_key,
+        request_hash: requestHash,
+        before_hash: current?.hash || null,
+        after_hash: commit?.hash || null,
+        changed_fields: envelope.type === 'patch' ? Object.keys(envelope.patches).sort() : [],
+        resource_status: resourceState ? 'prepared' : null,
+        payload: envelope.type === 'event' && envelope.content ? JSON.parse(envelope.content) : null,
+      }, { clock });
+      await eventStore.append(event);
+
+      if (resourceCoordinator?.finalize) await resourceCoordinator.finalize({ resourceState, event });
+      const projectionResults = projectionCoordinator ? await projectionCoordinator.dispatch(event) : [];
+      const warnings = projectionResults.filter((item) => !item.success).map((item) => `Projection '${item.id}' failed: ${item.error}`);
+      const response = {
+        success: true, type: envelope.type, operation_id: operationId, path: envelope.path,
+        committed_at: event.timestamp, dry_run: false,
+        event_id: event.event_id,
+        validation: { valid: true, type: definition.qualified_type, errors: [], warnings },
+      };
+      await idempotencyStore.put(envelope.workspace_id, envelope.idempotency_key, { request_hash: requestHash, response });
+      return response;
+    } catch (error) {
+      if (resourceCoordinator?.reconcile) {
+        try { await resourceCoordinator.reconcile({ resourceState, error, envelope, principal }); } catch {}
+      }
+      // Roll back a VFS commit when event persistence fails. Event envelopes have no VFS commit.
+      if (commit && envelope.type !== 'event') {
+        try {
+          if (!current) await vfs.remove(envelope.path, { version: commit.version });
+          else await vfs.writeAtomic(envelope.path, current.bytes, commit.version ? { version: commit.version } : {});
+        } catch (rollbackError) {
+          return failure(envelope, operationId, [`Commit failed: ${error.message}; rollback failed: ${rollbackError.message}`]);
+        }
+      }
+      return failure(envelope, operationId, [`Commit failed: ${error.message}`]);
+    }
+  }
+
+  return { execute, registry: registrySet, validator };
+}