@feltdb/core 0.4.17 → 0.4.20

package/dist/cli/index.js

@@ -23,7 +23,7 @@ import * as path from 'path';
 import * as readline from 'readline';
 import { getClient } from './api-client.js';
 import { loadFeltDBConfig, createDefaultConfig, validateModel, } from './config.js';
-const VERSION = '0.4.17';
+const VERSION = '0.4.20';
 function prompt(question) {
     const rl = readline.createInterface({
         input: process.stdin,

package/dist/create/package-versions.js

@@ -1,4 +1,4 @@
 // One release train keeps generated applications installable. The repository
 // validation script checks these values against every workspace manifest.
-export const FELTDB_PACKAGE_VERSION = '0.4.17';
+export const FELTDB_PACKAGE_VERSION = '0.4.20';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

package/dist/feltdb.d.ts

@@ -85,6 +85,10 @@ export interface JsDb {
         updated: boolean;
         currentVersion: number;
     }>;
+    /** Atomic idempotent operation admission: durably admit unique operations. */
+    admitOperation?(input: any): Promise<any>;
+    /** Atomic operation lifecycle transition: versioned conditional state changes. */
+    transitionOperation?(input: any): Promise<any>;
 }
 /**
  * A row stored in the database

package/dist/feltdb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feltdb.d.ts","sourceRoot":"","sources":["../src/feltdb.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,GAAG,GAAG,GAAG,CAAC;IAEhC;;OAEG;IACH,SAAS,IAAI,GAAG,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC;IAE/B;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC;IAEpC;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC;IAEvC;;OAEG;IACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,GAAG,CAAC;IAEnE;;OAEG;IACH,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC;IAEpE;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEzC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAErC;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEvD,6DAA6D;IAC7D,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAExD,qDAAqD;IACrD,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEzC,2EAA2E;IAC3E,iBAAiB,CAAC,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC5F,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/B;;OAEG;IACH,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC;IAEhD;;OAEG;IACH,WAAW,IAAI,MAAM,CAAC;IAEtB;;OAEG;IACH,YAAY,IAAI,MAAM,CAAC;IAEvB,0EAA0E;IAC1E,YAAY,CAAC,IAAI,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEpC,6DAA6D;IAC7D,iBAAiB,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/D,uBAAuB,CAAC,CAAC,UAAU,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEhE,oEAAoE;IACpE,WAAW,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAExF,kEAAkE;IAClE,GAAG,CAAC,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9H;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB"}
+{"version":3,"file":"feltdb.d.ts","sourceRoot":"","sources":["../src/feltdb.ts"],"names":[],"mappings":"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"}

package/dist/file-db.d.ts

@@ -1,4 +1,5 @@
 import type { JsDb } from './feltdb.js';
+import type { OperationAdmissionInput, OperationAdmissionResult, OperationTransitionInput, OperationTransitionResult } from './operation-admission.js';
 interface JsResult {
     success: boolean;
     data?: string;
@@ -61,6 +62,8 @@ export declare class FileJsDb implements JsDb {
         inserted: boolean;
         value: string;
     }>;
+    admitOperation(input: OperationAdmissionInput): Promise<OperationAdmissionResult>;
+    transitionOperation(input: OperationTransitionInput): Promise<OperationTransitionResult>;
     cas(params: {
         key: string;
         expectedVersion: number;

package/dist/file-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-db.d.ts","sourceRoot":"","sources":["../src/file-db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAmDxC,UAAU,QAAQ;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,aAAa;IAAG,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE;AAyBrK,qBAAa,QAAS,YAAW,IAAI;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,MAAM,CAAuB;gBAEzB,IAAI,EAAE,MAAM;IAgCxB,OAAO,CAAC,SAAS;IAiCjB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,WAAW;IAuBnB,OAAO,CAAC,gBAAgB;YAWV,gBAAgB;IA6B9B,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,SAAS;IAkCjB,OAAO,CAAC,KAAK;IAeb,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ;IAa5C,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ;IAO5C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ;IAO1B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ;IAW7B,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ;IAQnC,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ;IAIpD,UAAU,IAAI,QAAQ;IAItB,SAAS,IAAI,QAAQ;IAiBrB,QAAQ,IAAI,QAAQ;IAIpB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAKvC,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAK1C,2BAA2B,IAAI,QAAQ;IAIvC,oBAAoB,IAAI,QAAQ;IAIhC,WAAW,IAAI,MAAM;IAIrB,YAAY,IAAI,MAAM;IAItB,YAAY;IAIZ,iBAAiB,CAAC,aAAa,EAAE,MAAM;IAIvC,uBAAuB,CAAC,UAAU,EAAE,aAAa,EAAE;;;;IA0C7C,gBAAgB,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAS7E,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAwCtF,GAAG,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;IAoCjI,KAAK,IAAI,IAAI;CAId"}
+{"version":3,"file":"file-db.d.ts","sourceRoot":"","sources":["../src/file-db.ts"],"names":[],"mappings":"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"}

package/dist/file-db.js

@@ -1,3 +1,4 @@
+import { validateOperationAdmissionInput, operationsConflict, generateOperationId, validateTransitionInput, isValidTransition, isTerminalStatus, isIdempotentTerminalTransition, } from './operation-admission.js';
 import { createRequire } from 'module';
 // Create a require function for use in ESM context
 let requireFunc = null;
@@ -399,6 +400,135 @@ export class FileJsDb {
             throw new Error(`putIfAbsent failed: ${error}`);
         }
     }
+    async admitOperation(input) {
+        // Validate input
+        const validation = validateOperationAdmissionInput(input);
+        if (!validation.valid) {
+            throw new Error(`Operation admission validation failed: ${validation.error}`);
+        }
+        // Generate operation ID for this admission attempt
+        const operationId = generateOperationId();
+        // Create durable operation record
+        const durableOperation = {
+            operationId,
+            idempotencyKey: input.idempotencyKey,
+            kind: input.kind,
+            status: 'accepted',
+            version: 0,
+            createdAt: Date.now(),
+            operationFingerprint: input.operationFingerprint,
+            metadata: input.metadata,
+        };
+        // Use putIfAbsent to atomically store the operation
+        // Key format: "operation:{idempotencyKey}" for idempotency lookup
+        // Key format: "op-id:{operationId}" for direct operation lookup
+        const idempotencyKey = `operation:${input.idempotencyKey}`;
+        const operationIdKey = `op-id:${operationId}`;
+        const operationValue = JSON.stringify(durableOperation);
+        try {
+            const result = await this.putIfAbsent(idempotencyKey, operationValue);
+            // Also store by operationId for direct lookups
+            if (result.inserted) {
+                this.state.rows[operationIdKey] = durableOperation;
+                this.saveState();
+            }
+            // Parse the existing or newly inserted operation
+            const existingOperation = JSON.parse(result.value);
+            // Check for conflicts if operation already existed
+            if (!result.inserted) {
+                const conflict = operationsConflict(existingOperation, input);
+                if (conflict) {
+                    throw new Error(conflict.message);
+                }
+            }
+            return {
+                admitted: result.inserted,
+                operationId: existingOperation.operationId,
+                operation: existingOperation,
+            };
+        }
+        catch (error) {
+            throw new Error(`Operation admission failed: ${error}`);
+        }
+    }
+    async transitionOperation(input) {
+        // Validate input
+        const validation = validateTransitionInput(input);
+        if (!validation.valid) {
+            throw new Error(`Transition validation failed: ${validation.error}`);
+        }
+        try {
+            await this.acquireLockAsync();
+            try {
+                // Reload state from disk to ensure we have latest
+                this.state = this.loadState();
+                // Look up operation by its operationId
+                const operationIdKey = `op-id:${input.operationId}`;
+                // Get current operation state
+                if (!(operationIdKey in this.state.rows)) {
+                    throw new Error(`Operation ${input.operationId} not found`);
+                }
+                const currentOperation = this.state.rows[operationIdKey];
+                // Check if version matches (CAS)
+                if (currentOperation.version !== input.expectedVersion) {
+                    return {
+                        transitioned: false,
+                        reason: 'VERSION_CONFLICT',
+                        operation: currentOperation,
+                    };
+                }
+                // Check if transition is legal
+                if (!isValidTransition(currentOperation.status, input.to)) {
+                    return {
+                        transitioned: false,
+                        reason: 'INVALID_TRANSITION',
+                        operation: currentOperation,
+                    };
+                }
+                // If transitioning to terminal state, check for idempotent re-entry
+                if (isTerminalStatus(input.to) && isTerminalStatus(currentOperation.status)) {
+                    if (isIdempotentTerminalTransition(currentOperation, input.resultSnapshot, input.error)) {
+                        return {
+                            transitioned: false,
+                            reason: 'VERSION_CONFLICT', // Treat as version conflict (already transitioned)
+                            operation: currentOperation,
+                        };
+                    }
+                    // Different result data = conflict
+                    throw new Error(`Terminal state conflict: operation already in ${currentOperation.status} with different result`);
+                }
+                // Perform the transition
+                const transitionedOperation = {
+                    ...currentOperation,
+                    status: input.to,
+                    version: currentOperation.version + 1,
+                    completedAt: isTerminalStatus(input.to) ? Date.now() : currentOperation.completedAt,
+                    startedAt: input.to === 'executing' ? Date.now() : currentOperation.startedAt,
+                    resultSnapshot: input.resultSnapshot ?? currentOperation.resultSnapshot,
+                    error: input.error ?? currentOperation.error,
+                };
+                // Persist the transition atomically within lock (update both indices)
+                this.state.rows[operationIdKey] = transitionedOperation;
+                const idempotencyIndexKey = `operation:${currentOperation.idempotencyKey}`;
+                if (idempotencyIndexKey in this.state.rows) {
+                    this.state.rows[idempotencyIndexKey] = transitionedOperation;
+                }
+                const collection = operationIdKey.split(':')[0];
+                this.event(collection, operationIdKey, 'put', transitionedOperation);
+                this.saveState();
+                return {
+                    transitioned: true,
+                    operation: transitionedOperation,
+                };
+            }
+            finally {
+                this.releaseLockAsync();
+            }
+        }
+        catch (error) {
+            throw new Error(`Transition failed: ${error}`);
+        }
+    }
     async cas(params) {
         try {
             const parsed = JSON.parse(params.value);

package/dist/operation-admission.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Atomic Idempotent Operation Admission
+ *
+ * Defines the durable operation admission contract for FeltDB.
+ * Guarantees: exactly one operation identity per idempotency key,
+ * atomic durability, and convergence across concurrent callers.
+ */
+/**
+ * Input contract for admitting a durable operation
+ */
+export interface OperationAdmissionInput {
+    /** Unique idempotency key supplied by caller */
+    idempotencyKey: string;
+    /** Operation kind (e.g., "execution", "coordination", "verification") */
+    kind: string;
+    /** Optional immutable operation fingerprint for conflict detection */
+    operationFingerprint?: string;
+    /** Caller-supplied metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Operation lifecycle status
+ */
+export type OperationStatus = 'accepted' | 'executing' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Durable operation record with versioned lifecycle
+ */
+export interface DurableOperation {
+    /** FeltDB-generated operation identity (ULIDv7 or similar) */
+    operationId: string;
+    /** Caller's idempotency key */
+    idempotencyKey: string;
+    /** Operation kind (immutable) */
+    kind: string;
+    /** Current operation status in lifecycle */
+    status: OperationStatus;
+    /** Version number (increments by 1 on each successful transition) */
+    version: number;
+    /** Timestamp when operation was admitted */
+    createdAt: number;
+    /** Timestamp when execution started */
+    startedAt?: number;
+    /** Timestamp when operation terminal state reached */
+    completedAt?: number;
+    /** Operation fingerprint for conflict detection */
+    operationFingerprint?: string;
+    /** Caller metadata */
+    metadata?: Record<string, unknown>;
+    /** Result/outcome for terminal states */
+    resultSnapshot?: unknown;
+    /** Error message for failed operations */
+    error?: string;
+}
+/**
+ * Result of an operation admission attempt
+ */
+export interface OperationAdmissionResult {
+    /** True if this caller admitted the operation; false if it already existed */
+    admitted: boolean;
+    /** FeltDB-generated operation identity (same for all callers with same idempotencyKey) */
+    operationId: string;
+    /** The durable operation record */
+    operation: DurableOperation;
+}
+/**
+ * Conflict error when idempotency key is reused with different operation semantics
+ */
+export interface IdempotencyConflictError {
+    code: 'IDEMPOTENCY_CONFLICT';
+    idempotencyKey: string;
+    existingKind: string;
+    requestedKind: string;
+    existingFingerprint?: string;
+    requestedFingerprint?: string;
+    message: string;
+}
+/**
+ * Input for atomic operation lifecycle transition
+ */
+export interface OperationTransitionInput {
+    /** Operation ID to transition */
+    operationId: string;
+    /** Expected current version (for CAS) */
+    expectedVersion: number;
+    /** Target status after transition */
+    to: OperationStatus;
+    /** Result data for terminal states */
+    resultSnapshot?: unknown;
+    /** Error message for failed operations */
+    error?: string;
+    /** Metadata for the transition event */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of a transition attempt
+ */
+export interface OperationTransitionResult {
+    /** True if transition succeeded */
+    transitioned: boolean;
+    /** Reason for failure (if transitioned = false) */
+    reason?: 'VERSION_CONFLICT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+    /** Current operation state (after transition or at rejection) */
+    operation: DurableOperation;
+}
+/**
+ * Validates operation admission inputs
+ */
+export declare function validateOperationAdmissionInput(input: OperationAdmissionInput): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Checks if two operations conflict based on immutable semantics
+ */
+export declare function operationsConflict(existing: DurableOperation, requested: OperationAdmissionInput): IdempotencyConflictError | null;
+/**
+ * Generates a stable operation ID
+ * In production, use ULIDv7 for sortability and distributed uniqueness
+ */
+export declare function generateOperationId(): string;
+/**
+ * Validates that a transition is legal according to the state machine
+ */
+export declare function isValidTransition(fromStatus: OperationStatus, toStatus: OperationStatus): boolean;
+/**
+ * Checks if a status is a terminal state
+ */
+export declare function isTerminalStatus(status: OperationStatus): boolean;
+/**
+ * Validates transition input
+ */
+export declare function validateTransitionInput(input: OperationTransitionInput): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Checks if a terminal transition is idempotent
+ * (same result data means it's the same transition, not a new one)
+ */
+export declare function isIdempotentTerminalTransition(existingOp: DurableOperation, requestedResult?: unknown, requestedError?: string): boolean;
+//# sourceMappingURL=operation-admission.d.ts.map

package/dist/operation-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-admission.d.ts","sourceRoot":"","sources":["../src/operation-admission.ts"],"names":[],"mappings":"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"}

package/dist/operation-admission.js

@@ -0,0 +1,135 @@
+/**
+ * Atomic Idempotent Operation Admission
+ *
+ * Defines the durable operation admission contract for FeltDB.
+ * Guarantees: exactly one operation identity per idempotency key,
+ * atomic durability, and convergence across concurrent callers.
+ */
+/**
+ * Validates operation admission inputs
+ */
+export function validateOperationAdmissionInput(input) {
+    if (!input.idempotencyKey || typeof input.idempotencyKey !== 'string') {
+        return { valid: false, error: 'idempotencyKey must be a non-empty string' };
+    }
+    if (!input.kind || typeof input.kind !== 'string') {
+        return { valid: false, error: 'kind must be a non-empty string' };
+    }
+    if (input.idempotencyKey.length > 255) {
+        return { valid: false, error: 'idempotencyKey must be <= 255 characters' };
+    }
+    if (input.kind.length > 64) {
+        return { valid: false, error: 'kind must be <= 64 characters' };
+    }
+    if (input.operationFingerprint && input.operationFingerprint.length > 255) {
+        return { valid: false, error: 'operationFingerprint must be <= 255 characters' };
+    }
+    return { valid: true };
+}
+/**
+ * Checks if two operations conflict based on immutable semantics
+ */
+export function operationsConflict(existing, requested) {
+    // Same idempotencyKey must have same kind
+    if (existing.kind !== requested.kind) {
+        return {
+            code: 'IDEMPOTENCY_CONFLICT',
+            idempotencyKey: existing.idempotencyKey,
+            existingKind: existing.kind,
+            requestedKind: requested.kind,
+            message: `Operation kind mismatch for idempotencyKey "${existing.idempotencyKey}": existing="${existing.kind}", requested="${requested.kind}"`,
+        };
+    }
+    // If fingerprint is supplied, it must match
+    if (requested.operationFingerprint) {
+        if (existing.operationFingerprint !== requested.operationFingerprint) {
+            return {
+                code: 'IDEMPOTENCY_CONFLICT',
+                idempotencyKey: existing.idempotencyKey,
+                existingKind: existing.kind,
+                requestedKind: requested.kind,
+                existingFingerprint: existing.operationFingerprint,
+                requestedFingerprint: requested.operationFingerprint,
+                message: `Operation fingerprint mismatch for idempotencyKey "${existing.idempotencyKey}": existing="${existing.operationFingerprint}", requested="${requested.operationFingerprint}"`,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Generates a stable operation ID
+ * In production, use ULIDv7 for sortability and distributed uniqueness
+ */
+export function generateOperationId() {
+    // Format: timestamp (13 bytes) + random (12 bytes) = 25 chars
+    // For now, use a simple format; consider switching to proper ULID
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 15) +
+        Math.random().toString(36).substring(2, 15);
+    return `op-${timestamp}-${random}`;
+}
+/**
+ * Legal state transitions in the operation lifecycle
+ *
+ * Invariant: Each successful transition increments version by exactly 1.
+ * Terminal states (completed, failed, cancelled) have no outgoing transitions.
+ */
+const LEGAL_TRANSITIONS = {
+    accepted: ['executing', 'cancelled'],
+    executing: ['completed', 'failed', 'cancelled'],
+    completed: [], // Terminal: no transitions allowed
+    failed: [], // Terminal: no transitions allowed
+    cancelled: [], // Terminal: no transitions allowed
+};
+/**
+ * Validates that a transition is legal according to the state machine
+ */
+export function isValidTransition(fromStatus, toStatus) {
+    const allowedTargets = LEGAL_TRANSITIONS[fromStatus] || [];
+    return allowedTargets.includes(toStatus);
+}
+/**
+ * Checks if a status is a terminal state
+ */
+export function isTerminalStatus(status) {
+    return ['completed', 'failed', 'cancelled'].includes(status);
+}
+/**
+ * Validates transition input
+ */
+export function validateTransitionInput(input) {
+    if (!input.operationId || typeof input.operationId !== 'string') {
+        return { valid: false, error: 'operationId must be a non-empty string' };
+    }
+    if (typeof input.expectedVersion !== 'number' || input.expectedVersion < 0) {
+        return { valid: false, error: 'expectedVersion must be a non-negative number' };
+    }
+    if (!input.to || typeof input.to !== 'string') {
+        return { valid: false, error: 'to must specify a target status' };
+    }
+    const validStatuses = ['accepted', 'executing', 'completed', 'failed', 'cancelled'];
+    if (!validStatuses.includes(input.to)) {
+        return { valid: false, error: `to must be one of: ${validStatuses.join(', ')}` };
+    }
+    return { valid: true };
+}
+/**
+ * Checks if a terminal transition is idempotent
+ * (same result data means it's the same transition, not a new one)
+ */
+export function isIdempotentTerminalTransition(existingOp, requestedResult, requestedError) {
+    // If operation is already in terminal state
+    if (!isTerminalStatus(existingOp.status)) {
+        return false; // Not a terminal op
+    }
+    // For completed operations, check result
+    if (existingOp.status === 'completed') {
+        return JSON.stringify(existingOp.resultSnapshot) === JSON.stringify(requestedResult);
+    }
+    // For failed operations, check error message
+    if (existingOp.status === 'failed') {
+        return existingOp.error === requestedError;
+    }
+    // For cancelled operations, idempotent
+    return true;
+}