@gregiteen/ssss-cli 0.9.2 → 0.9.4

package/src/http.mjs

@@ -1,5 +1,24 @@
 /** Reference transport adapters. HTTP is a façade over kernel.execute, never a writer. */
 
+/** Canonical HTTP status for each symbolic failure code (spec §6.5). */
+export const ERROR_STATUS = Object.freeze({
+  invalid_request: 400,
+  unauthorized: 401,
+  forbidden: 403,
+  not_found: 404,
+  lease_conflict: 409,
+  version_conflict: 409,
+  idempotency_conflict: 409,
+  validation_failed: 422,
+  internal_error: 500,
+});
+
+/** Map a kernel response to its HTTP status: 201 commit, 200 replay/dry run, else by error code. */
+export function statusForResponse(response) {
+  if (response?.success) return response.replay || response.dry_run ? 200 : 201;
+  return ERROR_STATUS[response?.error?.code] || 500;
+}
+
 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) {
@@ -7,10 +26,7 @@ export function createCommandHandler({ kernel, authenticate, parseBody = async (
       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 };
+      return { status: statusForResponse(response), 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 } } };
     }

package/src/kernel.mjs

@@ -5,15 +5,26 @@
 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 { isAppendType, isSafeDocumentPath, resolvePrimitiveDefinition } from './registry.mjs';
+import { createCapabilityAuthorizer, validateVerifiedPrincipal } from './authorization.mjs';
+import { createCanonicalEvent, idempotentEventId } from './events.mjs';
 import { MemoryIdempotencyStore } from './idempotency.mjs';
 
 export { MemoryIdempotencyStore } from './idempotency.mjs';
 
 const COMMAND_TYPES = new Set(['operation', 'patch', 'event', 'delete']);
 
+/**
+ * Symbolic failure codes (spec §6.5). Every failed response carries exactly one
+ * in `error.code`; transports map codes to status without parsing messages.
+ */
+export const ERROR_CODES = Object.freeze([
+  'invalid_request', 'unauthorized', 'forbidden', 'not_found', 'lease_conflict',
+  'version_conflict', 'idempotency_conflict', 'validation_failed', 'internal_error',
+]);
+
+function isVfsError(error, name, code) { return error?.name === name || error?.code === code; }
+
 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])]));
@@ -34,9 +45,10 @@ export function canonicalRequestHash(envelope, principal) {
   return `sha256:${crypto.createHash('sha256').update(JSON.stringify(stable(clean))).digest('hex')}`;
 }
 
-function failure(envelope, operationId, errors, fieldErrors = []) {
+function failure(code, envelope, operationId, errors, fieldErrors = []) {
   return {
     success: false,
+    error: { code, message: errors[0] || code },
     type: envelope?.type || null,
     operation_id: operationId,
     path: envelope?.path || '',
@@ -70,6 +82,29 @@ export function createKernel(options = {}) {
   const validator = options.validator || createValidator(options);
   const registrySet = validator.registry;
 
+  // Registry `references` are enforced on every write (spec §9). A host may
+  // supply its own resolver; otherwise targets are read through the VFS.
+  async function referenceResolver(definition, data, context) {
+    if (context.resolveReference) return context.resolveReference;
+    const fields = Object.keys(definition?.references || {});
+    if (!fields.length || !data) return undefined;
+    const found = new Map();
+    for (const field of fields) {
+      const target = data[field];
+      if (!isSafeDocumentPath(target) || found.has(target)) continue;
+      let entry = null;
+      try {
+        const file = await vfs.read(target);
+        if (file) {
+          const content = file.bytes.toString('utf8');
+          entry = { content, data: parseDocument(content).data };
+        }
+      } catch {}
+      found.set(target, entry);
+    }
+    return (target) => found.get(target) || null;
+  }
+
   async function execute(rawEnvelope, context = {}) {
     const envelope = { ...rawEnvelope };
     delete envelope.actor;
@@ -77,32 +112,45 @@ export function createKernel(options = {}) {
     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.' }]);
+      return failure('invalid_request', 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.' }]);
+        return failure('invalid_request', 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.' }]);
+      return failure('invalid_request', 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.' }]);
+      return failure('invalid_request', envelope, operationId, ['Patch requires a patches object.'], [{ field: 'patches', issue: 'Required object.' }]);
+    }
+
+    // Authenticate before touching storage, so an anonymous caller learns
+    // nothing about the vault. The id and kind are what every event records.
+    if (!principal || typeof principal.id !== 'string' || !principal.id || typeof principal.kind !== 'string' || !principal.kind) {
+      return failure('unauthorized', envelope, operationId, ['Access denied: Verified principal is required.'], [{ field: 'principal', issue: 'Verified principal is required.' }]);
     }
 
     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.' }]);
+    // 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('idempotency_conflict', 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); }
-    catch (error) { return failure(envelope, operationId, [error.message], [{ field: 'path', issue: error.message }]); }
+    catch (error) {
+      const code = isVfsError(error, 'VfsPathError', 'SSSS_VFS_PATH') ? 'invalid_request' : 'internal_error';
+      return failure(code, envelope, operationId, [error.message], [{ field: 'path', issue: error.message }]);
+    }
 
     let definition = null;
     let declaredType = envelope.primitive_type || null;
@@ -112,7 +160,7 @@ export function createKernel(options = {}) {
 
     if (current) {
       try { currentData = parseDocument(current.bytes.toString('utf8')).data; }
-      catch (error) { return failure(envelope, operationId, [`Existing document is invalid: ${error.message}`]); }
+      catch (error) { return failure('internal_error', envelope, operationId, [`Existing document is invalid: ${error.message}`]); }
       declaredType ||= currentData.type;
     }
     if (envelope.type === 'operation') {
@@ -122,27 +170,35 @@ export function createKernel(options = {}) {
         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);
+        let draft = null;
+        try { draft = parseDocument(envelope.content).data; } catch {}
+        const draftDefinition = draft && resolvePrimitiveDefinition(registrySet, draft.type);
+        const resolveReference = await referenceResolver(draftDefinition, draft, context);
+        const validation = validator.validateDocument(envelope.content, { resolveReference });
+        if (!validation.valid) return failure('validation_failed', 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.' }]);
+        return failure('validation_failed', envelope, operationId, ['Operation may not change an existing document type.'], [{ field: 'type', issue: 'Use an explicit migration.' }]);
+      }
+      // A full replace would rewrite recorded history (spec §5.3).
+      if (current && isAppendType(definition)) {
+        return failure('validation_failed', envelope, operationId, [`Append-only primitive '${declaredType}' cannot be replaced.`], [{ field: 'content', issue: 'Append with a patch carrying __body__.' }]);
       }
     } else if (envelope.type === 'patch') {
-      if (!current) return failure(envelope, operationId, ['Patch target does not exist.'], [{ field: 'path', issue: 'Target not found.' }]);
+      if (!current) return failure('not_found', 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 (!definition) return failure('validation_failed', 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.' }]);
+        return failure('validation_failed', 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.' }]);
+          return failure('validation_failed', envelope, operationId, [`Patch may not change immutable field '${field}'.`], [{ field, issue: 'Use an explicit migration.' }]);
         }
       }
       const parsedCurrent = parseDocument(current.bytes.toString('utf8'));
@@ -151,24 +207,29 @@ export function createKernel(options = {}) {
       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);
+      const resolveReference = await referenceResolver(definition, nextData, context);
+      const validation = validator.validateData(nextData, { resolveReference });
+      if (!validation.valid) return failure('validation_failed', 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.' }]);
+      if (!current) return failure('not_found', 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.`]);
+      if (!definition) return failure('validation_failed', envelope, operationId, [`Unknown SSSS primitive '${declaredType}'.`]);
+      if (isAppendType(definition)) return failure('validation_failed', 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.' }]); }
+      catch { return failure('invalid_request', 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 (!auth.allowed) {
+      // An absent or malformed principal is an authentication failure, not a permission one.
+      const code = validateVerifiedPrincipal(principal).valid ? 'forbidden' : 'unauthorized';
+      return failure(code, envelope, operationId, [`Access denied: ${auth.reason}`], [{ field: 'principal', issue: auth.reason }]);
+    }
 
     if ((definition?.lease_required || context.requireLease) && leaseStore) {
       let lease;
@@ -181,18 +242,30 @@ export function createKernel(options = {}) {
           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.' }]);
+        return failure('internal_error', 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 }]);
+      if (!lease.valid) return failure('lease_conflict', envelope, operationId, [lease.reason], [{ field: 'lease_id', issue: lease.reason }]);
     }
 
     let resourceState = null;
+    let prepared = false;
     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}`]); }
+      try {
+        resourceState = await resourceCoordinator.prepare({ envelope, principal, definition, action, current, nextContent });
+        prepared = true;
+      }
+      catch (error) { return failure('internal_error', envelope, operationId, [`Resource prepare failed: ${error.message}`]); }
     }
 
+    // Every prepare ends in exactly one finalize or reconcile; a dry run never commits.
+    const reconcile = async (phase, error) => {
+      if (!resourceCoordinator?.reconcile) return null;
+      try { await resourceCoordinator.reconcile({ resourceState, error, envelope, principal, phase }); return null; }
+      catch (reconcileError) { return reconcileError; }
+    };
+
     if (envelope.dry_run) {
+      if (prepared) await reconcile('dry_run', null);
       return {
         success: true, type: envelope.type, operation_id: operationId, path: envelope.path,
         committed_at: null, dry_run: true,
@@ -201,6 +274,7 @@ export function createKernel(options = {}) {
     }
 
     let commit = null;
+    let event;
     try {
       if (envelope.type === 'operation') {
         commit = await vfs.writeAtomic(envelope.path, nextContent, current ? { version: current.version } : { ifAbsent: true });
@@ -210,7 +284,10 @@ export function createKernel(options = {}) {
         commit = await vfs.remove(envelope.path, { version: current.version });
       }
 
-      const event = createCanonicalEvent({
+      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,
@@ -223,37 +300,57 @@ export function createKernel(options = {}) {
         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,
+        resource_status: prepared ? '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 {}
-      }
+      if (prepared) await reconcile('commit', error);
       // 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('internal_error', envelope, operationId, [`Commit failed: ${error.message}; rollback failed: ${rollbackError.message}`]);
         }
       }
-      return failure(envelope, operationId, [`Commit failed: ${error.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 {}
+      const code = isVfsError(error, 'VfsConflictError', 'SSSS_VFS_CONFLICT') ? 'version_conflict' : 'internal_error';
+      return failure(code, envelope, operationId, [`Commit failed: ${error.message}`]);
+    }
+
+    // The appended event is the commit point (spec §6.3): nothing after it may
+    // roll the mutation back. Post-commit failures become warnings.
+    const warnings = [];
+    if (resourceCoordinator?.finalize) {
+      try { await resourceCoordinator.finalize({ resourceState, event }); }
+      catch (error) {
+        warnings.push(`Resource finalize failed: ${error.message}`);
+        const reconcileError = await reconcile('finalize', error);
+        if (reconcileError) warnings.push(`Resource reconcile failed: ${reconcileError.message}`);
+      }
+    }
+    let projectionResults = [];
+    if (projectionCoordinator) {
+      try { projectionResults = await projectionCoordinator.dispatch(event); }
+      catch (error) { warnings.push(`Projection dispatch failed: ${error.message}`); }
     }
+    warnings.push(...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 },
+    };
+    try { await idempotencyStore.put(envelope.workspace_id, envelope.idempotency_key, { request_hash: requestHash, response }); }
+    catch (error) { warnings.push(`Idempotency record failed: ${error.message}`); }
+    return response;
   }
 
   return { execute, registry: registrySet, validator };

package/types/kernel.d.ts

@@ -21,8 +21,14 @@ export interface SsssCommand {
   dry_run?: boolean;
 }
 
+export type SsssErrorCode =
+  | 'invalid_request' | 'unauthorized' | 'forbidden' | 'not_found' | 'lease_conflict'
+  | 'version_conflict' | 'idempotency_conflict' | 'validation_failed' | 'internal_error';
+
 export interface SsssResponse {
   success: boolean;
+  /** Present exactly when success is false (spec §6.5). */
+  error?: { code: SsssErrorCode; message: string };
   type: SsssCommandType | null;
   operation_id: string;
   path: string;
@@ -40,6 +46,7 @@ export interface SsssKernel {
   validator: unknown;
 }
 
+export const ERROR_CODES: readonly SsssErrorCode[];
 export function canonicalRequestHash(command: SsssCommand, principal: VerifiedPrincipal): string;
 export class MemoryIdempotencyStore {
   get(workspaceId: string, idempotencyKey: string): Promise<unknown>;