@git-stunts/git-warp 10.8.0 → 11.2.1

package/src/domain/warp/provenance.methods.js

@@ -0,0 +1,284 @@
+/**
+ * Provenance methods for WarpGraph — patch lookups, slice materialization,
+ * backward causal cone computation, and causal sorting.
+ *
+ * Every function uses `this` bound to a WarpGraph instance at runtime
+ * via wireWarpMethods().
+ *
+ * @module domain/warp/provenance.methods
+ */
+
+import { QueryError } from './_internal.js';
+import { createEmptyStateV5, reduceV5 } from '../services/JoinReducer.js';
+import { ProvenancePayload } from '../services/ProvenancePayload.js';
+import { decodePatchMessage, detectMessageKind } from '../services/WarpMessageCodec.js';
+
+/**
+ * Returns all patch SHAs that affected a given node or edge.
+ *
+ * "Affected" means the patch either read from or wrote to the entity
+ * (based on the patch's I/O declarations from HG/IO/1).
+ *
+ * If `autoMaterialize` is enabled, this will automatically materialize
+ * the state if dirty. Otherwise, call `materialize()` first.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} entityId - The node ID or edge key to query
+ * @returns {Promise<string[]>} Array of patch SHAs that affected the entity, sorted alphabetically
+ * @throws {QueryError} If no cached state exists and autoMaterialize is off (code: `E_NO_STATE`)
+ */
+export async function patchesFor(entityId) {
+  await this._ensureFreshState();
+
+  if (this._provenanceDegraded) {
+    throw new QueryError('Provenance unavailable for cached seek. Re-seek with --no-persistent-cache or call materialize({ ceiling }) directly.', {
+      code: 'E_PROVENANCE_DEGRADED',
+    });
+  }
+
+  if (!this._provenanceIndex) {
+    throw new QueryError('No provenance index. Call materialize() first.', {
+      code: 'E_NO_STATE',
+    });
+  }
+  return this._provenanceIndex.patchesFor(entityId);
+}
+
+/**
+ * Materializes only the backward causal cone for a specific node.
+ *
+ * This implements the slicing theorem from Paper III (Computational Holography):
+ * Given a target node v, compute its backward causal cone D(v) - the set of
+ * all patches that contributed to v's current state - and replay only those.
+ *
+ * The algorithm:
+ * 1. Start with patches that directly wrote to the target node
+ * 2. For each patch, find entities it read from
+ * 3. Recursively gather all dependencies
+ * 4. Topologically sort by Lamport timestamp (causal order)
+ * 5. Replay the sorted patches against empty state
+ *
+ * **Requires a cached state.** Call materialize() first to build the provenance index.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} nodeId - The target node ID to materialize the cone for
+ * @param {{receipts?: boolean}} [options] - Optional configuration
+ * @returns {Promise<{state: import('../services/JoinReducer.js').WarpStateV5, patchCount: number, receipts?: import('../types/TickReceipt.js').TickReceipt[]}>}
+ *   Returns the sliced state with the patch count (for comparison with full materialization)
+ * @throws {QueryError} If no provenance index exists (code: `E_NO_STATE`)
+ * @throws {Error} If patch loading fails
+ */
+export async function materializeSlice(nodeId, options) {
+  const t0 = this._clock.now();
+  const collectReceipts = options && options.receipts;
+
+  try {
+    // Ensure fresh state before accessing provenance index
+    await this._ensureFreshState();
+
+    if (this._provenanceDegraded) {
+      throw new QueryError('Provenance unavailable for cached seek. Re-seek with --no-persistent-cache or call materialize({ ceiling }) directly.', {
+        code: 'E_PROVENANCE_DEGRADED',
+      });
+    }
+
+    if (!this._provenanceIndex) {
+      throw new QueryError('No provenance index. Call materialize() first.', {
+        code: 'E_NO_STATE',
+      });
+    }
+
+    // 1. Compute backward causal cone using BFS over the provenance index
+    // Returns Map<sha, patch> with patches already loaded (avoids double I/O)
+    const conePatchMap = await this._computeBackwardCone(nodeId);
+
+    // 2. If no patches in cone, return empty state
+    if (conePatchMap.size === 0) {
+      const emptyState = createEmptyStateV5();
+      this._logTiming('materializeSlice', t0, { metrics: '0 patches (empty cone)' });
+      return {
+        state: emptyState,
+        patchCount: 0,
+        ...(collectReceipts ? { receipts: [] } : {}),
+      };
+    }
+
+    // 3. Convert cached patches to entry format (patches already loaded by _computeBackwardCone)
+    const patchEntries = [];
+    for (const [sha, patch] of conePatchMap) {
+      patchEntries.push({ patch, sha });
+    }
+
+    // 4. Topologically sort by causal order (Lamport timestamp, then writer, then SHA)
+    const sortedPatches = this._sortPatchesCausally(patchEntries);
+
+    // 5. Replay: use reduceV5 directly when collecting receipts, otherwise use ProvenancePayload
+    this._logTiming('materializeSlice', t0, { metrics: `${sortedPatches.length} patches` });
+
+    if (collectReceipts) {
+      const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}} */ (reduceV5(sortedPatches, undefined, { receipts: true }));
+      return {
+        state: result.state,
+        patchCount: sortedPatches.length,
+        receipts: result.receipts,
+      };
+    }
+
+    const payload = new ProvenancePayload(sortedPatches);
+    return {
+      state: payload.replay(),
+      patchCount: sortedPatches.length,
+    };
+  } catch (err) {
+    this._logTiming('materializeSlice', t0, { error: /** @type {Error} */ (err) });
+    throw err;
+  }
+}
+
+/**
+ * Computes the backward causal cone for a node.
+ *
+ * Uses BFS over the provenance index:
+ * 1. Find all patches that wrote to the target node
+ * 2. For each patch, find entities it read from
+ * 3. Find all patches that wrote to those entities
+ * 4. Repeat until no new patches are found
+ *
+ * Returns a Map of SHA -> patch to avoid double-loading (the cone
+ * computation needs to read patches for their read-dependencies,
+ * so we cache them for later replay).
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} nodeId - The target node ID
+ * @returns {Promise<Map<string, Object>>} Map of patch SHA to loaded patch object
+ */
+export async function _computeBackwardCone(nodeId) {
+  if (!this._provenanceIndex) {
+    throw new QueryError('No provenance index. Call materialize() first.', {
+      code: 'E_NO_STATE',
+    });
+  }
+  const cone = new Map(); // sha -> patch (cache loaded patches)
+  const visited = new Set(); // Visited entities
+  const queue = [nodeId]; // BFS queue of entities to process
+  let qi = 0;
+
+  while (qi < queue.length) {
+    const entityId = queue[qi++];
+
+    if (visited.has(entityId)) {
+      continue;
+    }
+    visited.add(entityId);
+
+    // Get all patches that affected this entity
+    const patchShas = /** @type {import('../services/ProvenanceIndex.js').ProvenanceIndex} */ (this._provenanceIndex).patchesFor(entityId);
+
+    for (const sha of patchShas) {
+      if (cone.has(sha)) {
+        continue;
+      }
+
+      // Load the patch and cache it
+      const patch = await this._loadPatchBySha(sha);
+      cone.set(sha, patch);
+
+      // Add read dependencies to the queue
+      const patchReads = /** @type {any} */ (patch)?.reads; // TODO(ts-cleanup): type patch array
+      if (patchReads) {
+        for (const readEntity of patchReads) {
+          if (!visited.has(readEntity)) {
+            queue.push(readEntity);
+          }
+        }
+      }
+    }
+  }
+
+  return cone;
+}
+
+/**
+ * Loads a single patch by its SHA.
+ *
+ * Thin wrapper around the internal `_loadPatchBySha` helper. Exposed for
+ * CLI/debug tooling (e.g. seek tick receipts) that needs to inspect patch
+ * operations without re-materializing intermediate states.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} sha - The patch commit SHA
+ * @returns {Promise<Object>} The decoded patch object
+ * @throws {Error} If the commit is not a patch or loading fails
+ */
+export async function loadPatchBySha(sha) {
+  return await this._loadPatchBySha(sha);
+}
+
+/**
+ * Loads a single patch by its SHA.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} sha - The patch commit SHA
+ * @returns {Promise<Object>} The decoded patch object
+ * @throws {Error} If the commit is not a patch or loading fails
+ */
+export async function _loadPatchBySha(sha) {
+  const nodeInfo = await this._persistence.getNodeInfo(sha);
+  const kind = detectMessageKind(nodeInfo.message);
+
+  if (kind !== 'patch') {
+    throw new Error(`Commit ${sha} is not a patch`);
+  }
+
+  const patchMeta = decodePatchMessage(nodeInfo.message);
+  const patchBuffer = await this._persistence.readBlob(patchMeta.patchOid);
+  return /** @type {Object} */ (this._codec.decode(patchBuffer));
+}
+
+/**
+ * Loads multiple patches by their SHAs.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string[]} shas - Array of patch commit SHAs
+ * @returns {Promise<Array<{patch: Object, sha: string}>>} Array of patch entries
+ * @throws {Error} If any SHA is not a patch or loading fails
+ */
+export async function _loadPatchesBySha(shas) {
+  const entries = [];
+
+  for (const sha of shas) {
+    const patch = await this._loadPatchBySha(sha);
+    entries.push({ patch, sha });
+  }
+
+  return entries;
+}
+
+/**
+ * Sorts patches in causal order for deterministic replay.
+ *
+ * Sort order: Lamport timestamp (ascending), then writer ID, then SHA.
+ * This ensures deterministic ordering regardless of discovery order.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {Array<{patch: any, sha: string}>} patches - Unsorted patch entries
+ * @returns {Array<{patch: any, sha: string}>} Sorted patch entries
+ */
+export function _sortPatchesCausally(patches) {
+  return [...patches].sort((a, b) => {
+    // Primary: Lamport timestamp (ascending - earlier patches first)
+    const lamportDiff = (a.patch.lamport || 0) - (b.patch.lamport || 0);
+    if (lamportDiff !== 0) {
+      return lamportDiff;
+    }
+
+    // Secondary: Writer ID (lexicographic)
+    const writerCmp = (a.patch.writer || '').localeCompare(b.patch.writer || '');
+    if (writerCmp !== 0) {
+      return writerCmp;
+    }
+
+    // Tertiary: SHA (lexicographic) for total ordering
+    return a.sha.localeCompare(b.sha);
+  });
+}

package/src/domain/warp/query.methods.js

@@ -0,0 +1,279 @@
+/**
+ * Query methods for WarpGraph — pure reads on materialized state.
+ *
+ * Every function uses `this` bound to a WarpGraph instance at runtime
+ * via wireWarpMethods().
+ *
+ * @module domain/warp/query.methods
+ */
+
+import { orsetContains, orsetElements } from '../crdt/ORSet.js';
+import { decodePropKey, isEdgePropKey, decodeEdgePropKey, encodeEdgeKey, decodeEdgeKey } from '../services/KeyCodec.js';
+import { compareEventIds } from '../utils/EventId.js';
+import { cloneStateV5 } from '../services/JoinReducer.js';
+import QueryBuilder from '../services/QueryBuilder.js';
+import ObserverView from '../services/ObserverView.js';
+import { computeTranslationCost } from '../services/TranslationCost.js';
+
+/**
+ * Checks if a node exists in the materialized graph state.
+ *
+ * **Requires a cached state.** Call materialize() first if not already cached.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} nodeId - The node ID to check
+ * @returns {Promise<boolean>} True if the node exists in the materialized state
+ * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
+ * @throws {import('../errors/QueryError.js').default} If cached state is dirty (code: `E_STALE_STATE`)
+ */
+export async function hasNode(nodeId) {
+  await this._ensureFreshState();
+  const s = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState);
+  return orsetContains(s.nodeAlive, nodeId);
+}
+
+/**
+ * Gets all properties for a node from the materialized state.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} nodeId - The node ID to get properties for
+ * @returns {Promise<Map<string, *>|null>} Map of property key → value, or null if node doesn't exist
+ * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
+ */
+export async function getNodeProps(nodeId) {
+  await this._ensureFreshState();
+  const s = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState);
+
+  if (!orsetContains(s.nodeAlive, nodeId)) {
+    return null;
+  }
+
+  const props = new Map();
+  for (const [propKey, register] of s.prop) {
+    const decoded = decodePropKey(propKey);
+    if (decoded.nodeId === nodeId) {
+      props.set(decoded.propKey, register.value);
+    }
+  }
+
+  return props;
+}
+
+/**
+ * Gets all properties for an edge from the materialized state.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} from - Source node ID
+ * @param {string} to - Target node ID
+ * @param {string} label - Edge label
+ * @returns {Promise<Record<string, *>|null>} Object of property key → value, or null if edge doesn't exist
+ * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
+ */
+export async function getEdgeProps(from, to, label) {
+  await this._ensureFreshState();
+  const s = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState);
+
+  const edgeKey = encodeEdgeKey(from, to, label);
+  if (!orsetContains(s.edgeAlive, edgeKey)) {
+    return null;
+  }
+
+  if (!orsetContains(s.nodeAlive, from) ||
+      !orsetContains(s.nodeAlive, to)) {
+    return null;
+  }
+
+  const birthEvent = s.edgeBirthEvent?.get(edgeKey);
+
+  /** @type {Record<string, any>} */
+  const props = {};
+  for (const [propKey, register] of s.prop) {
+    if (!isEdgePropKey(propKey)) {
+      continue;
+    }
+    const decoded = decodeEdgePropKey(propKey);
+    if (decoded.from === from && decoded.to === to && decoded.label === label) {
+      if (birthEvent && register.eventId && compareEventIds(register.eventId, birthEvent) < 0) {
+        continue;
+      }
+      props[decoded.propKey] = register.value;
+    }
+  }
+
+  return props;
+}
+
+/**
+ * Gets neighbors of a node from the materialized state.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} nodeId - The node ID to get neighbors for
+ * @param {'outgoing' | 'incoming' | 'both'} [direction='both'] - Edge direction to follow
+ * @param {string} [edgeLabel] - Optional edge label filter
+ * @returns {Promise<Array<{nodeId: string, label: string, direction: 'outgoing' | 'incoming'}>>} Array of neighbor info
+ * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
+ */
+export async function neighbors(nodeId, direction = 'both', edgeLabel = undefined) {
+  await this._ensureFreshState();
+  const s = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState);
+
+  /** @type {Array<{nodeId: string, label: string, direction: 'outgoing' | 'incoming'}>} */
+  const result = [];
+
+  for (const edgeKey of orsetElements(s.edgeAlive)) {
+    const { from, to, label } = decodeEdgeKey(edgeKey);
+
+    if (edgeLabel !== undefined && label !== edgeLabel) {
+      continue;
+    }
+
+    if ((direction === 'outgoing' || direction === 'both') && from === nodeId) {
+      if (orsetContains(s.nodeAlive, to)) {
+        result.push({ nodeId: to, label, direction: /** @type {const} */ ('outgoing') });
+      }
+    }
+
+    if ((direction === 'incoming' || direction === 'both') && to === nodeId) {
+      if (orsetContains(s.nodeAlive, from)) {
+        result.push({ nodeId: from, label, direction: /** @type {const} */ ('incoming') });
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Returns a defensive copy of the current materialized state.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @returns {Promise<import('../services/JoinReducer.js').WarpStateV5 | null>}
+ */
+export async function getStateSnapshot() {
+  if (!this._cachedState && !this._autoMaterialize) {
+    return null;
+  }
+  await this._ensureFreshState();
+  if (!this._cachedState) {
+    return null;
+  }
+  return cloneStateV5(/** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState));
+}
+
+/**
+ * Gets all visible nodes in the materialized state.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @returns {Promise<string[]>} Array of node IDs
+ * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
+ */
+export async function getNodes() {
+  await this._ensureFreshState();
+  const s = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState);
+  return [...orsetElements(s.nodeAlive)];
+}
+
+/**
+ * Gets all visible edges in the materialized state.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @returns {Promise<Array<{from: string, to: string, label: string, props: Record<string, *>}>>} Array of edge info
+ * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
+ */
+export async function getEdges() {
+  await this._ensureFreshState();
+  const s = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState);
+
+  const edgePropsByKey = new Map();
+  for (const [propKey, register] of s.prop) {
+    if (!isEdgePropKey(propKey)) {
+      continue;
+    }
+    const decoded = decodeEdgePropKey(propKey);
+    const ek = encodeEdgeKey(decoded.from, decoded.to, decoded.label);
+
+    const birthEvent = s.edgeBirthEvent?.get(ek);
+    if (birthEvent && register.eventId && compareEventIds(register.eventId, birthEvent) < 0) {
+      continue;
+    }
+
+    let bag = edgePropsByKey.get(ek);
+    if (!bag) {
+      bag = {};
+      edgePropsByKey.set(ek, bag);
+    }
+    bag[decoded.propKey] = register.value;
+  }
+
+  const edges = [];
+  for (const edgeKey of orsetElements(s.edgeAlive)) {
+    const { from, to, label } = decodeEdgeKey(edgeKey);
+    if (orsetContains(s.nodeAlive, from) &&
+        orsetContains(s.nodeAlive, to)) {
+      const props = edgePropsByKey.get(edgeKey) || {};
+      edges.push({ from, to, label, props });
+    }
+  }
+  return edges;
+}
+
+/**
+ * Returns the number of property entries in the materialized state.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @returns {Promise<number>} Number of property entries
+ * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
+ */
+export async function getPropertyCount() {
+  await this._ensureFreshState();
+  const s = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState);
+  return s.prop.size;
+}
+
+/**
+ * Creates a fluent query builder for the logical graph.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @returns {import('../services/QueryBuilder.js').default} A fluent query builder
+ */
+export function query() {
+  return new QueryBuilder(this);
+}
+
+/**
+ * Creates a read-only observer view of the current materialized state.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} name - Observer name
+ * @param {Object} config - Observer configuration
+ * @param {string} config.match - Glob pattern for visible nodes
+ * @param {string[]} [config.expose] - Property keys to include
+ * @param {string[]} [config.redact] - Property keys to exclude
+ * @returns {Promise<import('../services/ObserverView.js').default>} A read-only observer view
+ */
+export async function observer(name, config) {
+  if (!config || typeof config.match !== 'string') {
+    throw new Error('observer config.match must be a string');
+  }
+  await this._ensureFreshState();
+  return new ObserverView({ name, config, graph: this });
+}
+
+/**
+ * Computes the directed MDL translation cost from observer A to observer B.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {Object} configA - Observer configuration for A
+ * @param {string} configA.match - Glob pattern for visible nodes
+ * @param {string[]} [configA.expose] - Property keys to include
+ * @param {string[]} [configA.redact] - Property keys to exclude
+ * @param {Object} configB - Observer configuration for B
+ * @param {string} configB.match - Glob pattern for visible nodes
+ * @param {string[]} [configB.expose] - Property keys to include
+ * @param {string[]} [configB.redact] - Property keys to exclude
+ * @returns {Promise<{cost: number, breakdown: {nodeLoss: number, edgeLoss: number, propLoss: number}}>}
+ */
+export async function translationCost(configA, configB) {
+  await this._ensureFreshState();
+  return computeTranslationCost(configA, configB, this._cachedState);
+}