@git-stunts/git-warp 11.5.1 → 12.0.0

package/src/ports/NeighborProviderPort.js

@@ -0,0 +1,59 @@
+/**
+ * Port interface for neighbor lookups on any graph.
+ *
+ * Concrete providers back this with in-memory adjacency maps, bitmap indexes,
+ * or remote APIs. All providers MUST return edges sorted by (neighborId, label)
+ * using strict codepoint comparison (never localeCompare).
+ *
+ * @abstract
+ */
+
+/** @typedef {'out' | 'in' | 'both'} Direction */
+/** @typedef {{ labels?: Set<string> }} NeighborOptions */
+/** @typedef {{ neighborId: string, label: string }} NeighborEdge */
+
+export default class NeighborProviderPort {
+  /**
+   * Returns neighbor edges for a node, sorted by (neighborId, label).
+   *
+   * For direction 'both', returns the union of out and in edges
+   * deduped by (neighborId, label). A consumer cannot tell if an
+   * edge was outgoing or incoming — this is intentionally lossy.
+   *
+   * @param {string} _nodeId - The node to look up
+   * @param {Direction} _direction - Edge direction: 'out', 'in', or 'both'
+   * @param {NeighborOptions} [_options] - Optional label filter
+   * @returns {Promise<NeighborEdge[]>} Sorted by (neighborId, label) via codepoint comparison
+   * @throws {Error} If not implemented by a concrete provider
+   */
+  async getNeighbors(_nodeId, _direction, _options) {
+    throw new Error('NeighborProviderPort.getNeighbors() not implemented');
+  }
+
+  /**
+   * Checks whether a node is alive in this view.
+   *
+   * Semantics: "alive in this view" (visible projection), NOT "ever existed."
+   *
+   * @param {string} _nodeId - The node to check
+   * @returns {Promise<boolean>} True if the node is alive
+   * @throws {Error} If not implemented by a concrete provider
+   */
+  async hasNode(_nodeId) {
+    throw new Error('NeighborProviderPort.hasNode() not implemented');
+  }
+
+  /**
+   * Returns the latency class of this provider.
+   *
+   * Used by GraphTraversal to decide whether to enable neighbor memoization.
+   * - 'sync': in-memory, no benefit from caching (e.g., AdjacencyNeighborProvider)
+   * - 'async-local': disk-backed, caching avoids repeated reads (e.g., BitmapNeighborProvider)
+   * - 'async-remote': network-backed, caching critical
+   *
+   * @returns {'sync' | 'async-local' | 'async-remote'}
+   */
+  get latencyClass() {
+    return 'async-local';
+  }
+}

package/src/ports/SeekCachePort.js

@@ -14,7 +14,7 @@ export default class SeekCachePort {
   /**
    * Retrieves a cached state buffer by key.
    * @param {string} _key - Cache key (e.g., 'v1:t42-<frontierHash>')
-   * @returns {Promise<Buffer|null>} The cached buffer, or null on miss
+   * @returns {Promise<{ buffer: Buffer|Uint8Array, indexTreeOid?: string } | null>} The cached entry, or null on miss
    * @throws {Error} If not implemented by a concrete adapter
    */
   async get(_key) {
@@ -24,11 +24,12 @@ export default class SeekCachePort {
   /**
    * Stores a state buffer under the given key.
    * @param {string} _key - Cache key
-   * @param {Buffer} _buffer - Serialized state to cache
+   * @param {Buffer|Uint8Array} _buffer - Serialized state to cache
+   * @param {{ indexTreeOid?: string }} [_options] - Optional metadata
    * @returns {Promise<void>}
    * @throws {Error} If not implemented by a concrete adapter
    */
-  async set(_key, _buffer) {
+  async set(_key, _buffer, _options) {
     throw new Error('SeekCachePort.set() not implemented');
   }