@git-stunts/git-warp 10.1.1

package/src/domain/types/WarpTypes.js

@@ -0,0 +1,209 @@
+/**
+ * WARP Common Types and Shared Factories
+ *
+ * Pure type definitions using JSDoc for IDE autocomplete and documentation.
+ * Contains types and factories shared across schema versions.
+ *
+ * Note: Schema-specific types are in WarpTypesV2.js (schema:2).
+ *
+ * @module WarpTypes
+ * @see WARP Spec Section 6
+ */
+
+// ============================================================================
+// Primitive Types
+// ============================================================================
+
+/**
+ * String identifier for nodes (e.g., "user:alice", UUID)
+ * @typedef {string} NodeId
+ */
+
+/**
+ * Edge identifier tuple
+ * @typedef {Object} EdgeKey
+ * @property {NodeId} from - Source node ID
+ * @property {NodeId} to - Target node ID
+ * @property {string} label - Edge label/type
+ */
+
+// ============================================================================
+// Value References
+// ============================================================================
+
+/**
+ * Inline value reference - value stored directly in the operation
+ * @typedef {Object} ValueRefInline
+ * @property {'inline'} type - Discriminator for inline values
+ * @property {*} value - The actual value (any JSON-serializable type)
+ */
+
+/**
+ * Blob value reference - value stored as a Git blob
+ * @typedef {Object} ValueRefBlob
+ * @property {'blob'} type - Discriminator for blob references
+ * @property {string} oid - Git blob OID (object identifier)
+ */
+
+/**
+ * Value reference - either inline or blob
+ * @typedef {ValueRefInline | ValueRefBlob} ValueRef
+ */
+
+// ============================================================================
+// Event Identification
+// ============================================================================
+
+/**
+ * EventId for total ordering of operations across patches
+ * Provides a globally unique identifier for each operation
+ * @typedef {Object} EventId
+ * @property {number} lamport - Lamport timestamp from the patch
+ * @property {string} writerId - Writer ID from the patch
+ * @property {string} patchSha - SHA of the patch/commit containing this operation
+ * @property {number} opIndex - Index of the operation within the patch
+ */
+
+// ============================================================================
+// Factory Functions - Value References
+// ============================================================================
+
+/**
+ * Creates an inline value reference
+ * @param {*} value - The value to store inline
+ * @returns {ValueRefInline} Inline value reference
+ */
+export function createInlineValue(value) {
+  return { type: 'inline', value };
+}
+
+/**
+ * Creates a blob value reference
+ * @param {string} oid - Git blob OID
+ * @returns {ValueRefBlob} Blob value reference
+ */
+export function createBlobValue(oid) {
+  return { type: 'blob', oid };
+}
+
+// ============================================================================
+// Operations
+// ============================================================================
+
+/**
+ * Node add operation
+ * @typedef {Object} OpNodeAdd
+ * @property {'NodeAdd'} type - Operation type discriminator
+ * @property {NodeId} node - Node ID to add
+ */
+
+/**
+ * Node tombstone operation
+ * @typedef {Object} OpNodeTombstone
+ * @property {'NodeTombstone'} type - Operation type discriminator
+ * @property {NodeId} node - Node ID to tombstone
+ */
+
+/**
+ * Edge add operation
+ * @typedef {Object} OpEdgeAdd
+ * @property {'EdgeAdd'} type - Operation type discriminator
+ * @property {NodeId} from - Source node ID
+ * @property {NodeId} to - Target node ID
+ * @property {string} label - Edge label/type
+ */
+
+/**
+ * Edge tombstone operation
+ * @typedef {Object} OpEdgeTombstone
+ * @property {'EdgeTombstone'} type - Operation type discriminator
+ * @property {NodeId} from - Source node ID
+ * @property {NodeId} to - Target node ID
+ * @property {string} label - Edge label/type
+ */
+
+/**
+ * Property set operation
+ * @typedef {Object} OpPropSet
+ * @property {'PropSet'} type - Operation type discriminator
+ * @property {NodeId} node - Node ID to set property on
+ * @property {string} key - Property key
+ * @property {ValueRef} value - Property value reference
+ */
+
+/**
+ * Any graph operation
+ * @typedef {OpNodeAdd | OpNodeTombstone | OpEdgeAdd | OpEdgeTombstone | OpPropSet} Op
+ */
+
+// ============================================================================
+// Factory Functions - Operations
+// ============================================================================
+
+/**
+ * Creates a NodeAdd operation
+ * @param {NodeId} node - Node ID to add
+ * @returns {OpNodeAdd} NodeAdd operation
+ */
+export function createNodeAdd(node) {
+  return { type: 'NodeAdd', node };
+}
+
+/**
+ * Creates a NodeTombstone operation
+ * @param {NodeId} node - Node ID to tombstone
+ * @returns {OpNodeTombstone} NodeTombstone operation
+ */
+export function createNodeTombstone(node) {
+  return { type: 'NodeTombstone', node };
+}
+
+/**
+ * Creates an EdgeAdd operation
+ * @param {NodeId} from - Source node ID
+ * @param {NodeId} to - Target node ID
+ * @param {string} label - Edge label
+ * @returns {OpEdgeAdd} EdgeAdd operation
+ */
+export function createEdgeAdd(from, to, label) {
+  return { type: 'EdgeAdd', from, to, label };
+}
+
+/**
+ * Creates an EdgeTombstone operation
+ * @param {NodeId} from - Source node ID
+ * @param {NodeId} to - Target node ID
+ * @param {string} label - Edge label
+ * @returns {OpEdgeTombstone} EdgeTombstone operation
+ */
+export function createEdgeTombstone(from, to, label) {
+  return { type: 'EdgeTombstone', from, to, label };
+}
+
+/**
+ * Creates a PropSet operation
+ * @param {NodeId} node - Node ID to set property on
+ * @param {string} key - Property key
+ * @param {ValueRef} value - Property value reference
+ * @returns {OpPropSet} PropSet operation
+ */
+export function createPropSet(node, key, value) {
+  return { type: 'PropSet', node, key, value };
+}
+
+// ============================================================================
+// Factory Functions - EventId
+// ============================================================================
+
+/**
+ * Creates an EventId
+ * @param {Object} options - EventId options
+ * @param {number} options.lamport - Lamport timestamp
+ * @param {string} options.writerId - Writer ID
+ * @param {string} options.patchSha - Patch SHA
+ * @param {number} options.opIndex - Operation index within patch
+ * @returns {EventId} EventId object
+ */
+export function createEventId({ lamport, writerId, patchSha, opIndex }) {
+  return { lamport, writerId, patchSha, opIndex };
+}

package/src/domain/types/WarpTypesV2.js

@@ -0,0 +1,200 @@
+/**
+ * WARP OpV2/PatchV2 Types and Schema
+ *
+ * Pure type definitions using JSDoc for IDE autocomplete and documentation.
+ * Factory functions for creating WARP v5 operations and patches.
+ *
+ * Key differences from V1:
+ * - Add operations carry dots (causal identifiers)
+ * - Remove operations carry observedDots (set of dots being removed)
+ * - PropSet uses EventId for identification (no dot field)
+ * - PatchV2 includes context (VersionVector) for writer's observed frontier
+ *
+ * @module WarpTypesV2
+ * @see WARP v5 Spec
+ */
+
+// ============================================================================
+// Primitive Types
+// ============================================================================
+
+/**
+ * String identifier for nodes (e.g., "user:alice", UUID)
+ * @typedef {string} NodeId
+ */
+
+/**
+ * Dot - causal identifier for an add operation
+ * @typedef {Object} Dot
+ * @property {string} writer - Writer ID that created this dot
+ * @property {number} seq - Sequence number for this writer
+ */
+
+/**
+ * VersionVector - maps writer IDs to their maximum observed sequence numbers
+ * @typedef {Object.<string, number>} VersionVector
+ */
+
+// ============================================================================
+// Operations (OpV2)
+// ============================================================================
+
+/**
+ * Node add operation - creates a new node with a dot
+ * @typedef {Object} OpV2NodeAdd
+ * @property {'NodeAdd'} type - Operation type discriminator
+ * @property {NodeId} node - Node ID to add
+ * @property {Dot} dot - Causal identifier for this add
+ */
+
+/**
+ * Node remove operation - removes a node by observed dots
+ * @typedef {Object} OpV2NodeRemove
+ * @property {'NodeRemove'} type - Operation type discriminator
+ * @property {NodeId} node - Node ID to remove
+ * @property {Dot[]} observedDots - Dots being removed (add events observed)
+ */
+
+/**
+ * Edge add operation - creates a new edge with a dot
+ * @typedef {Object} OpV2EdgeAdd
+ * @property {'EdgeAdd'} type - Operation type discriminator
+ * @property {NodeId} from - Source node ID
+ * @property {NodeId} to - Target node ID
+ * @property {string} label - Edge label/type
+ * @property {Dot} dot - Causal identifier for this add
+ */
+
+/**
+ * Edge remove operation - removes an edge by observed dots
+ * @typedef {Object} OpV2EdgeRemove
+ * @property {'EdgeRemove'} type - Operation type discriminator
+ * @property {NodeId} from - Source node ID
+ * @property {NodeId} to - Target node ID
+ * @property {string} label - Edge label/type
+ * @property {Dot[]} observedDots - Dots being removed (add events observed)
+ */
+
+/**
+ * Property set operation - sets a property value on a node
+ * Uses EventId for identification (derived from patch context)
+ * @typedef {Object} OpV2PropSet
+ * @property {'PropSet'} type - Operation type discriminator
+ * @property {NodeId} node - Node ID to set property on
+ * @property {string} key - Property key
+ * @property {*} value - Property value (any JSON-serializable type)
+ */
+
+/**
+ * Union of all v2 operation types
+ * @typedef {OpV2NodeAdd | OpV2NodeRemove | OpV2EdgeAdd | OpV2EdgeRemove | OpV2PropSet} OpV2
+ */
+
+// ============================================================================
+// Patch
+// ============================================================================
+
+/**
+ * PatchV2 - A batch of ordered operations from a single writer
+ * @typedef {Object} PatchV2
+ * @property {2|3} schema - Schema version (2 for node-only, 3 for edge properties)
+ * @property {string} writer - Writer ID (identifies the source of the patch)
+ * @property {number} lamport - Lamport timestamp for ordering
+ * @property {VersionVector} context - Writer's observed frontier (NOT global stability)
+ * @property {OpV2[]} ops - Ordered array of operations
+ * @property {string[]} [reads] - Node/edge IDs read by this patch (for provenance tracking)
+ * @property {string[]} [writes] - Node/edge IDs written by this patch (for provenance tracking)
+ */
+
+// ============================================================================
+// Factory Functions - Operations
+// ============================================================================
+
+/**
+ * Creates a NodeAdd operation with a dot
+ * @param {NodeId} node - Node ID to add
+ * @param {Dot} dot - Causal identifier for this add
+ * @returns {OpV2NodeAdd} NodeAdd operation
+ */
+export function createNodeAddV2(node, dot) {
+  return { type: 'NodeAdd', node, dot };
+}
+
+/**
+ * Creates a NodeRemove operation with observed dots
+ * @param {NodeId} node - Node ID to remove
+ * @param {Dot[]} observedDots - Dots being removed
+ * @returns {OpV2NodeRemove} NodeRemove operation
+ */
+export function createNodeRemoveV2(node, observedDots) {
+  return { type: 'NodeRemove', node, observedDots };
+}
+
+/**
+ * Creates an EdgeAdd operation with a dot
+ * @param {NodeId} from - Source node ID
+ * @param {NodeId} to - Target node ID
+ * @param {string} label - Edge label
+ * @param {Dot} dot - Causal identifier for this add
+ * @returns {OpV2EdgeAdd} EdgeAdd operation
+ */
+export function createEdgeAddV2(from, to, label, dot) {
+  return { type: 'EdgeAdd', from, to, label, dot };
+}
+
+/**
+ * Creates an EdgeRemove operation with observed dots
+ * @param {NodeId} from - Source node ID
+ * @param {NodeId} to - Target node ID
+ * @param {string} label - Edge label
+ * @param {Dot[]} observedDots - Dots being removed
+ * @returns {OpV2EdgeRemove} EdgeRemove operation
+ */
+export function createEdgeRemoveV2(from, to, label, observedDots) {
+  return { type: 'EdgeRemove', from, to, label, observedDots };
+}
+
+/**
+ * Creates a PropSet operation (no dot - uses EventId)
+ * @param {NodeId} node - Node ID to set property on
+ * @param {string} key - Property key
+ * @param {*} value - Property value (any JSON-serializable type)
+ * @returns {OpV2PropSet} PropSet operation
+ */
+export function createPropSetV2(node, key, value) {
+  return { type: 'PropSet', node, key, value };
+}
+
+// ============================================================================
+// Factory Functions - Patch
+// ============================================================================
+
+/**
+ * Creates a PatchV2
+ * @param {Object} options - Patch options
+ * @param {2|3} [options.schema=2] - Schema version (2 for node-only, 3 for edge properties)
+ * @param {string} options.writer - Writer ID
+ * @param {number} options.lamport - Lamport timestamp
+ * @param {VersionVector} options.context - Writer's observed frontier
+ * @param {OpV2[]} options.ops - Array of operations
+ * @param {string[]} [options.reads] - Node/edge IDs read by this patch (for provenance tracking)
+ * @param {string[]} [options.writes] - Node/edge IDs written by this patch (for provenance tracking)
+ * @returns {PatchV2} PatchV2 object
+ */
+export function createPatchV2({ schema = 2, writer, lamport, context, ops, reads, writes }) {
+  const patch = {
+    schema,
+    writer,
+    lamport,
+    context,
+    ops,
+  };
+  // Only include reads/writes if provided (backward compatibility)
+  if (reads && reads.length > 0) {
+    patch.reads = reads;
+  }
+  if (writes && writes.length > 0) {
+    patch.writes = writes;
+  }
+  return patch;
+}

package/src/domain/utils/CachedValue.js

@@ -0,0 +1,140 @@
+/**
+ * A TTL-based caching utility for a single value.
+ *
+ * Caches the result of an expensive operation and reuses it until
+ * the configured TTL expires. Supports manual invalidation.
+ *
+ * @class CachedValue
+ * @template T
+ *
+ * @example
+ * const cache = new CachedValue({
+ *   clock,
+ *   ttlMs: 5000,
+ *   compute: async () => await expensiveOperation(),
+ * });
+ *
+ * // First call computes the value
+ * const value1 = await cache.get();
+ *
+ * // Subsequent calls within TTL return cached value
+ * const value2 = await cache.get(); // Same as value1
+ *
+ * // Force recompute
+ * cache.invalidate();
+ * const value3 = await cache.get(); // Fresh value
+ */
+class CachedValue {
+  /**
+   * Creates a CachedValue instance.
+   *
+   * @param {Object} options
+   * @param {import('../../ports/ClockPort.js').default} options.clock - Clock port for timing
+   * @param {number} options.ttlMs - Time-to-live in milliseconds
+   * @param {() => T | Promise<T>} options.compute - Function to compute the value when cache is stale
+   * @throws {Error} If ttlMs is not a positive number
+   */
+  constructor({ clock, ttlMs, compute }) {
+    if (typeof ttlMs !== 'number' || ttlMs <= 0) {
+      throw new Error('CachedValue ttlMs must be a positive number');
+    }
+    if (typeof compute !== 'function') {
+      throw new Error('CachedValue compute must be a function');
+    }
+
+    /** @type {import('../../ports/ClockPort.js').default} */
+    this._clock = clock;
+
+    /** @type {number} */
+    this._ttlMs = ttlMs;
+
+    /** @type {() => T | Promise<T>} */
+    this._compute = compute;
+
+    /** @type {T|null} */
+    this._value = null;
+
+    /** @type {number} */
+    this._cachedAt = 0;
+
+    /** @type {string|null} */
+    this._cachedAtIso = null;
+  }
+
+  /**
+   * Gets the cached value, computing it if stale or not present.
+   *
+   * @returns {Promise<T>} The cached or freshly computed value
+   */
+  async get() {
+    if (this._isValid()) {
+      return this._value;
+    }
+
+    const value = await this._compute();
+    this._value = value;
+    this._cachedAt = this._clock.now();
+    this._cachedAtIso = this._clock.timestamp();
+
+    return value;
+  }
+
+  /**
+   * Gets the cached value with metadata about when it was cached.
+   *
+   * @returns {Promise<{value: T, cachedAt: string|null, fromCache: boolean}>}
+   */
+  async getWithMetadata() {
+    const wasValid = this._isValid();
+    const value = await this.get();
+
+    return {
+      value,
+      cachedAt: wasValid ? this._cachedAtIso : null,
+      fromCache: wasValid,
+    };
+  }
+
+  /**
+   * Invalidates the cached value, forcing recomputation on next get().
+   */
+  invalidate() {
+    this._value = null;
+    this._cachedAt = 0;
+    this._cachedAtIso = null;
+  }
+
+  /**
+   * Checks if the cached value is still valid.
+   *
+   * @returns {boolean} True if the cache is valid
+   * @private
+   */
+  _isValid() {
+    if (this._value === null) {
+      return false;
+    }
+    return this._clock.now() - this._cachedAt < this._ttlMs;
+  }
+
+  /**
+   * Gets the ISO timestamp of when the value was cached.
+   * Returns null if no value is cached.
+   *
+   * @returns {string|null}
+   */
+  get cachedAt() {
+    return this._cachedAtIso;
+  }
+
+  /**
+   * Checks if a value is currently cached (regardless of validity).
+   *
+   * @returns {boolean}
+   */
+  get hasValue() {
+    return this._value !== null;
+  }
+}
+
+export default CachedValue;

package/src/domain/utils/EventId.js

@@ -0,0 +1,89 @@
+/**
+ * EventId for total ordering of operations (WARP spec Section 7).
+ *
+ * @typedef {Object} EventId
+ * @property {number} lamport - Monotonic counter (positive integer)
+ * @property {string} writerId - Writer identifier (non-empty string)
+ * @property {string} patchSha - Patch commit SHA (hex OID, 4-64 chars)
+ * @property {number} opIndex - Operation index within patch (non-negative integer)
+ */
+
+// Regex for validating hex OID (4-64 hex characters)
+const HEX_OID_REGEX = /^[0-9a-f]{4,64}$/;
+
+/**
+ * Creates a validated EventId.
+ *
+ * @param {number} lamport - Must be positive integer (> 0)
+ * @param {string} writerId - Must be non-empty string
+ * @param {string} patchSha - Must be valid hex OID (4-64 chars)
+ * @param {number} opIndex - Must be non-negative integer (>= 0)
+ * @returns {EventId}
+ * @throws {Error} If validation fails
+ */
+export function createEventId(lamport, writerId, patchSha, opIndex) {
+  // Validate lamport is positive integer
+  if (!Number.isInteger(lamport) || lamport <= 0) {
+    throw new Error('lamport must be a positive integer');
+  }
+
+  // Validate writerId is non-empty string
+  if (typeof writerId !== 'string' || writerId.length === 0) {
+    throw new Error('writerId must be a non-empty string');
+  }
+
+  // Validate patchSha is hex string 4-64 chars
+  if (typeof patchSha !== 'string' || !HEX_OID_REGEX.test(patchSha)) {
+    throw new Error('patchSha must be a hex string of 4-64 characters');
+  }
+
+  // Validate opIndex is non-negative integer
+  if (!Number.isInteger(opIndex) || opIndex < 0) {
+    throw new Error('opIndex must be a non-negative integer');
+  }
+
+  return { lamport, writerId, patchSha, opIndex };
+}
+
+/**
+ * Compares two EventIds lexicographically.
+ * Order: lamport -> writerId -> patchSha -> opIndex
+ *
+ * @param {EventId} a
+ * @param {EventId} b
+ * @returns {number} -1 if a < b, 0 if equal, 1 if a > b
+ */
+export function compareEventIds(a, b) {
+  // 1. Compare lamport numerically
+  if (a.lamport !== b.lamport) {
+    return a.lamport < b.lamport ? -1 : 1;
+  }
+
+  // 2. Compare writerId as string
+  if (a.writerId !== b.writerId) {
+    return a.writerId < b.writerId ? -1 : 1;
+  }
+
+  // 3. Compare patchSha as string
+  if (a.patchSha !== b.patchSha) {
+    return a.patchSha < b.patchSha ? -1 : 1;
+  }
+
+  // 4. Compare opIndex numerically
+  if (a.opIndex !== b.opIndex) {
+    return a.opIndex < b.opIndex ? -1 : 1;
+  }
+
+  return 0;
+}
+
+/**
+ * Checks if EventId a is greater than EventId b.
+ *
+ * @param {EventId} a
+ * @param {EventId} b
+ * @returns {boolean}
+ */
+export function isGreater(a, b) {
+  return compareEventIds(a, b) > 0;
+}