@git-stunts/git-warp 10.1.1

package/src/domain/services/TemporalQuery.js

@@ -0,0 +1,201 @@
+/**
+ * TemporalQuery - CTL*-style temporal operators over WARP graph history.
+ *
+ * Implements `always` and `eventually` temporal operators from Paper IV
+ * (Echo and the WARP Core). These operators evaluate predicates across
+ * the graph's history by replaying patches incrementally and checking
+ * the predicate at each tick boundary.
+ *
+ * ## Temporal Operators
+ *
+ * - **always(nodeId, predicate, { since })**: True iff the predicate holds
+ *   at every tick since `since` where the node exists.
+ * - **eventually(nodeId, predicate, { since })**: True iff the predicate holds
+ *   at some tick since `since`.
+ *
+ * ## Implementation
+ *
+ * Both operators collect all patches, sort them by causal order (same as
+ * materialization), then apply patches one at a time. After each patch
+ * application, a node snapshot is extracted and passed to the predicate.
+ *
+ * The "tick" corresponds to a patch's Lamport timestamp. The `since` option
+ * filters out patches with Lamport timestamps below the threshold.
+ *
+ * @module domain/services/TemporalQuery
+ * @see Paper IV - Echo and the WARP Core (CTL* temporal logic on histories)
+ */
+
+import { createEmptyStateV5, join as joinPatch } from './JoinReducer.js';
+import { decodePropKey } from './KeyCodec.js';
+import { orsetContains } from '../crdt/ORSet.js';
+
+/**
+ * Unwraps a property value from its CRDT envelope.
+ *
+ * InlineValue objects `{ type: 'inline', value: ... }` are unwrapped
+ * to their inner value. All other values pass through unchanged.
+ *
+ * @param {*} value - Property value (potentially InlineValue-wrapped)
+ * @returns {*} The unwrapped value
+ * @private
+ */
+function unwrapValue(value) {
+  if (value && typeof value === 'object' && value.type === 'inline') {
+    return value.value;
+  }
+  return value;
+}
+
+/**
+ * Extracts a node snapshot from the current WARP state.
+ *
+ * Returns an object with `{ id, exists, props }` where props is a
+ * plain object mapping property keys to their unwrapped values.
+ * InlineValue wrappers are stripped so predicates can compare against
+ * raw values directly (e.g., `n.props.status === 'active'`).
+ *
+ * If the node does not exist in the state, `exists` is false and
+ * `props` is an empty object.
+ *
+ * @param {import('./JoinReducer.js').WarpStateV5} state - Current state
+ * @param {string} nodeId - Node ID to extract
+ * @returns {{ id: string, exists: boolean, props: Object<string, *> }}
+ */
+function extractNodeSnapshot(state, nodeId) {
+  const exists = orsetContains(state.nodeAlive, nodeId);
+  const props = {};
+
+  if (exists) {
+    const prefix = `${nodeId}\0`;
+    for (const [propKey, register] of state.prop) {
+      if (propKey.startsWith(prefix)) {
+        const decoded = decodePropKey(propKey);
+        props[decoded.propKey] = unwrapValue(register.value);
+      }
+    }
+  }
+
+  return { id: nodeId, exists, props };
+}
+
+/**
+ * TemporalQuery provides temporal logic operators over graph history.
+ *
+ * Constructed by WarpGraph and exposed via `graph.temporal`.
+ * Both methods are async because they need to load patches from Git.
+ */
+export class TemporalQuery {
+  /**
+   * @param {Object} options
+   * @param {Function} options.loadAllPatches - Async function that returns
+   *   all patches as Array<{ patch, sha }> in causal order.
+   */
+  constructor({ loadAllPatches }) {
+    /** @type {Function} */
+    this._loadAllPatches = loadAllPatches;
+  }
+
+  /**
+   * Tests whether a predicate holds at every tick since `since`.
+   *
+   * Replays patches from `since` to current. At each tick boundary,
+   * builds the node snapshot and tests the predicate. Returns true only
+   * if the predicate returned true at every tick where the node existed.
+   *
+   * Returns false if the node never existed in the range.
+   *
+   * @param {string} nodeId - The node ID to evaluate
+   * @param {Function} predicate - Predicate receiving node snapshot
+   *   `{ id, exists, props }`. Should return boolean.
+   * @param {{ since?: number }} [options={}] - Options
+   * @param {number} [options.since=0] - Minimum Lamport tick (inclusive).
+   *   Only patches with lamport >= since are considered.
+   * @returns {Promise<boolean>} True if predicate held at every tick
+   *
+   * @example
+   * const result = await graph.temporal.always(
+   *   'user:alice',
+   *   n => n.props.status === 'active',
+   *   { since: 0 }
+   * );
+   */
+  async always(nodeId, predicate, options = {}) {
+    const since = options.since ?? 0;
+    const allPatches = await this._loadAllPatches();
+
+    const state = createEmptyStateV5();
+    let nodeEverExisted = false;
+
+    for (const { patch, sha } of allPatches) {
+      // Apply the patch to state
+      joinPatch(state, patch, sha);
+
+      // Skip patches before the `since` threshold
+      if (patch.lamport < since) {
+        continue;
+      }
+
+      // Extract node snapshot at this tick
+      const snapshot = extractNodeSnapshot(state, nodeId);
+
+      if (snapshot.exists) {
+        nodeEverExisted = true;
+        if (!predicate(snapshot)) {
+          return false;
+        }
+      }
+    }
+
+    // If the node never existed in the range, return false
+    return nodeEverExisted;
+  }
+
+  /**
+   * Tests whether a predicate holds at some tick since `since`.
+   *
+   * Replays patches from `since` to current. At each tick boundary,
+   * builds the node snapshot and tests the predicate. Returns true as
+   * soon as the predicate returns true at any tick.
+   *
+   * @param {string} nodeId - The node ID to evaluate
+   * @param {Function} predicate - Predicate receiving node snapshot
+   *   `{ id, exists, props }`. Should return boolean.
+   * @param {{ since?: number }} [options={}] - Options
+   * @param {number} [options.since=0] - Minimum Lamport tick (inclusive).
+   *   Only patches with lamport >= since are considered.
+   * @returns {Promise<boolean>} True if predicate held at any tick
+   *
+   * @example
+   * const result = await graph.temporal.eventually(
+   *   'user:alice',
+   *   n => n.props.status === 'merged',
+   *   { since: 0 }
+   * );
+   */
+  async eventually(nodeId, predicate, options = {}) {
+    const since = options.since ?? 0;
+    const allPatches = await this._loadAllPatches();
+
+    const state = createEmptyStateV5();
+
+    for (const { patch, sha } of allPatches) {
+      // Apply the patch to state
+      joinPatch(state, patch, sha);
+
+      // Skip patches before the `since` threshold
+      if (patch.lamport < since) {
+        continue;
+      }
+
+      // Extract node snapshot at this tick
+      const snapshot = extractNodeSnapshot(state, nodeId);
+
+      if (snapshot.exists && predicate(snapshot)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+}

package/src/domain/services/TranslationCost.js

@@ -0,0 +1,221 @@
+/**
+ * TranslationCost - MDL-based cost estimation between observer views.
+ *
+ * Computes the directed cost of translating observer A's view into
+ * observer B's view, measuring information loss via Minimum Description
+ * Length (MDL) of the translation function.
+ *
+ * The cost is normalized to [0, 1]:
+ *   0 = identical views (no information lost)
+ *   1 = completely disjoint views (all information lost)
+ *
+ * @module domain/services/TranslationCost
+ * @see Paper IV, Section 4 -- Directed rulial cost
+ */
+
+import { orsetElements, orsetContains } from '../crdt/ORSet.js';
+import { decodeEdgeKey, decodePropKey, isEdgePropKey } from './KeyCodec.js';
+
+/**
+ * Tests whether a string matches a glob-style pattern.
+ *
+ * @param {string} pattern - Glob pattern (e.g. 'user:*', '*:admin', '*')
+ * @param {string} str - The string to test
+ * @returns {boolean} True if the string matches the pattern
+ */
+function matchGlob(pattern, str) {
+  if (pattern === '*') {
+    return true;
+  }
+  if (!pattern.includes('*')) {
+    return pattern === str;
+  }
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  const regex = new RegExp(`^${escaped.replace(/\*/g, '.*')}$`);
+  return regex.test(str);
+}
+
+/**
+ * Computes the set of property keys visible under an observer config.
+ *
+ * @param {Map<string, *>} allNodeProps - Map of propKey -> placeholder
+ * @param {string[]|undefined} expose - Whitelist of property keys
+ * @param {string[]|undefined} redact - Blacklist of property keys
+ * @returns {Set<string>} Visible property keys
+ */
+function visiblePropKeys(allNodeProps, expose, redact) {
+  const redactSet = redact && redact.length > 0 ? new Set(redact) : null;
+  const exposeSet = expose && expose.length > 0 ? new Set(expose) : null;
+
+  const keys = new Set();
+  for (const key of allNodeProps.keys()) {
+    if (redactSet && redactSet.has(key)) {
+      continue;
+    }
+    if (exposeSet && !exposeSet.has(key)) {
+      continue;
+    }
+    keys.add(key);
+  }
+  return keys;
+}
+
+/**
+ * Collects node property keys from state for a given node.
+ *
+ * @param {*} state - WarpStateV5 materialized state
+ * @param {string} nodeId - The node ID
+ * @returns {Map<string, boolean>} Map of propKey -> true
+ */
+function collectNodePropKeys(state, nodeId) {
+  const props = new Map();
+  for (const [propKey] of state.prop) {
+    if (isEdgePropKey(propKey)) {
+      continue;
+    }
+    const decoded = decodePropKey(propKey);
+    if (decoded.nodeId === nodeId) {
+      props.set(decoded.propKey, true);
+    }
+  }
+  return props;
+}
+
+// Weights for MDL cost components
+const NODE_WEIGHT = 0.5;
+const EDGE_WEIGHT = 0.3;
+const PROP_WEIGHT = 0.2;
+
+/** @returns {{ cost: 0, breakdown: { nodeLoss: 0, edgeLoss: 0, propLoss: 0 } }} */
+function zeroCost() {
+  return { cost: 0, breakdown: { nodeLoss: 0, edgeLoss: 0, propLoss: 0 } };
+}
+
+/**
+ * Counts how many items in `source` are absent from `targetSet`.
+ *
+ * @param {Array|Set} source - Source collection
+ * @param {Set} targetSet - Target set to test against
+ * @returns {number}
+ */
+function countMissing(source, targetSet) {
+  let count = 0;
+  for (const item of source) {
+    if (!targetSet.has(item)) {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Computes edge loss between two observer node sets.
+ *
+ * @param {*} state - WarpStateV5
+ * @param {Set<string>} nodesASet - Nodes visible to A
+ * @param {Set<string>} nodesBSet - Nodes visible to B
+ * @returns {number} edgeLoss fraction
+ */
+function computeEdgeLoss(state, nodesASet, nodesBSet) {
+  const allEdges = [...orsetElements(state.edgeAlive)];
+  const edgesA = [];
+  const edgesBSet = new Set();
+
+  for (const edgeKey of allEdges) {
+    const { from, to } = decodeEdgeKey(edgeKey);
+    if (!orsetContains(state.nodeAlive, from) || !orsetContains(state.nodeAlive, to)) {
+      continue;
+    }
+    if (nodesASet.has(from) && nodesASet.has(to)) {
+      edgesA.push(edgeKey);
+    }
+    if (nodesBSet.has(from) && nodesBSet.has(to)) {
+      edgesBSet.add(edgeKey);
+    }
+  }
+
+  return countMissing(edgesA, edgesBSet) / Math.max(edgesA.length, 1);
+}
+
+/**
+ * Counts lost properties for a single node between two observer configs.
+ *
+ * @param {Map<string, boolean>} nodeProps - Property keys for the node
+ * @param {{ configA: Object, configB: Object, nodeInB: boolean }} opts
+ * @returns {{ propsInA: number, lostProps: number }}
+ */
+function countNodePropLoss(nodeProps, { configA, configB, nodeInB }) {
+  const propsA = visiblePropKeys(nodeProps, configA.expose, configA.redact);
+  if (!nodeInB) {
+    return { propsInA: propsA.size, lostProps: propsA.size };
+  }
+  const propsB = visiblePropKeys(nodeProps, configB.expose, configB.redact);
+  return { propsInA: propsA.size, lostProps: countMissing(propsA, propsB) };
+}
+
+/**
+ * Computes property loss across all A-visible nodes.
+ *
+ * @param {*} state - WarpStateV5
+ * @param {{ nodesA: string[], nodesBSet: Set<string>, configA: Object, configB: Object }} opts
+ * @returns {number} propLoss fraction
+ */
+function computePropLoss(state, { nodesA, nodesBSet, configA, configB }) {
+  let totalPropsInA = 0;
+  let totalLostProps = 0;
+
+  for (const nodeId of nodesA) {
+    const nodeProps = collectNodePropKeys(state, nodeId);
+    if (nodeProps.size === 0) {
+      continue;
+    }
+    const { propsInA, lostProps } = countNodePropLoss(
+      nodeProps, { configA, configB, nodeInB: nodesBSet.has(nodeId) }
+    );
+    totalPropsInA += propsInA;
+    totalLostProps += lostProps;
+  }
+
+  return totalLostProps / Math.max(totalPropsInA, 1);
+}
+
+/**
+ * Computes the directed MDL translation cost from observer A to observer B.
+ *
+ * The cost measures how much information is lost when translating from
+ * A's view to B's view. It is asymmetric: cost(A->B) != cost(B->A) in general.
+ *
+ * @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
+ * @param {*} state - WarpStateV5 materialized state
+ * @returns {{ cost: number, breakdown: { nodeLoss: number, edgeLoss: number, propLoss: number } }}
+ */
+export function computeTranslationCost(configA, configB, state) {
+  if (!configA || typeof configA.match !== 'string' ||
+      !configB || typeof configB.match !== 'string') {
+    throw new Error('configA.match and configB.match must be strings');
+  }
+  const allNodes = [...orsetElements(state.nodeAlive)];
+  const nodesA = allNodes.filter((id) => matchGlob(configA.match, id));
+
+  if (nodesA.length === 0) {
+    return zeroCost();
+  }
+
+  const nodesASet = new Set(nodesA);
+  const nodesBSet = new Set(allNodes.filter((id) => matchGlob(configB.match, id)));
+
+  const nodeLoss = countMissing(nodesA, nodesBSet) / Math.max(nodesA.length, 1);
+  const edgeLoss = computeEdgeLoss(state, nodesASet, nodesBSet);
+  const propLoss = computePropLoss(state, { nodesA, nodesBSet, configA, configB });
+
+  const cost = NODE_WEIGHT * nodeLoss + EDGE_WEIGHT * edgeLoss + PROP_WEIGHT * propLoss;
+
+  return { cost, breakdown: { nodeLoss, edgeLoss, propLoss } };
+}

package/src/domain/services/TraversalService.js

@@ -0,0 +1,8 @@
+/**
+ * @deprecated Use CommitDagTraversalService instead.
+ * This alias will be removed after one minor version.
+ */
+
+import CommitDagTraversalService from './CommitDagTraversalService.js';
+
+export default CommitDagTraversalService;

package/src/domain/services/WarpMessageCodec.js

@@ -0,0 +1,29 @@
+/**
+ * WARP Message Codec — facade re-exporting all message encoding, decoding,
+ * and schema utilities.
+ *
+ * This module provides backward-compatible access to the three types of
+ * WARP (Write-Ahead Reference Protocol) commit messages:
+ * - Patch: Contains graph mutations from a single writer
+ * - Checkpoint: Contains a snapshot of materialized graph state
+ * - Anchor: Marks a merge point in the WARP DAG
+ *
+ * Implementation is split across focused sub-modules:
+ * - {@link module:domain/services/PatchMessageCodec}
+ * - {@link module:domain/services/CheckpointMessageCodec}
+ * - {@link module:domain/services/AnchorMessageCodec}
+ * - {@link module:domain/services/MessageSchemaDetector}
+ *
+ * @module domain/services/WarpMessageCodec
+ */
+
+export { encodePatchMessage, decodePatchMessage } from './PatchMessageCodec.js';
+export { encodeCheckpointMessage, decodeCheckpointMessage } from './CheckpointMessageCodec.js';
+export { encodeAnchorMessage, decodeAnchorMessage } from './AnchorMessageCodec.js';
+export {
+  detectSchemaVersion,
+  detectMessageKind,
+  assertOpsCompatible,
+  SCHEMA_V2,
+  SCHEMA_V3,
+} from './MessageSchemaDetector.js';

package/src/domain/services/WarpStateIndexBuilder.js

@@ -0,0 +1,127 @@
+/**
+ * WarpStateIndexBuilder - Builds bitmap index from materialized WARP state.
+ *
+ * This builder creates adjacency indexes from WarpStateV5.edgeAlive OR-Set,
+ * NOT from Git commit DAG topology. This is the correct WARP architecture
+ * as specified in TECH-SPEC-V7.md Task 6.
+ *
+ * The index supports O(1) neighbor lookups by node ID.
+ *
+ * @module domain/services/WarpStateIndexBuilder
+ */
+
+import BitmapIndexBuilder from './BitmapIndexBuilder.js';
+import { orsetContains, orsetElements } from '../crdt/ORSet.js';
+import { decodeEdgeKey } from './KeyCodec.js';
+
+/**
+ * Builds a bitmap index from materialized WARP state.
+ *
+ * This is the V7-compliant index builder that operates on logical graph edges
+ * from the edgeAlive OR-Set, not Git commit parents.
+ *
+ * @example
+ * import WarpStateIndexBuilder from './WarpStateIndexBuilder.js';
+ *
+ * const state = await graph.materialize();
+ * const builder = new WarpStateIndexBuilder();
+ * const indexData = builder.buildFromState(state);
+ */
+export default class WarpStateIndexBuilder {
+  /**
+   * Creates a new WarpStateIndexBuilder.
+   * @param {Object} [options] - Configuration
+   * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort for shard checksums
+   */
+  constructor({ crypto } = {}) {
+    /** @type {BitmapIndexBuilder} */
+    this._builder = new BitmapIndexBuilder({ crypto });
+  }
+
+  /**
+   * Builds an index from materialized WARP state.
+   *
+   * Iterates over edgeAlive OR-Set and creates forward/reverse adjacency
+   * bitmaps for each node. Only includes edges where both endpoints are
+   * visible (exist in nodeAlive).
+   *
+   * @param {import('./JoinReducer.js').WarpStateV5} state - The materialized state
+   * @returns {{builder: BitmapIndexBuilder, stats: {nodes: number, edges: number}}} The populated builder and stats
+   * @throws {Error} If state is null or missing nodeAlive/edgeAlive fields
+   *
+   * @example
+   * const state = await graph.materialize();
+   * const { builder, stats } = new WarpStateIndexBuilder().buildFromState(state);
+   * console.log(`Indexed ${stats.nodes} nodes, ${stats.edges} edges`);
+   * const indexTree = await builder.serialize();
+   */
+  buildFromState(state) {
+    if (!state || !state.nodeAlive || !state.edgeAlive) {
+      throw new Error('Invalid state: must be a valid WarpStateV5 object');
+    }
+
+    let nodeCount = 0;
+    let edgeCount = 0;
+
+    // Register all visible nodes
+    for (const nodeId of orsetElements(state.nodeAlive)) {
+      this._builder.registerNode(nodeId);
+      nodeCount++;
+    }
+
+    // Add edges where both endpoints are visible
+    for (const edgeKey of orsetElements(state.edgeAlive)) {
+      const { from, to } = decodeEdgeKey(edgeKey);
+
+      // Only index edges where both endpoints exist in nodeAlive
+      if (orsetContains(state.nodeAlive, from) && orsetContains(state.nodeAlive, to)) {
+        this._builder.addEdge(from, to);
+        edgeCount++;
+      }
+    }
+
+    return {
+      builder: this._builder,
+      stats: { nodes: nodeCount, edges: edgeCount },
+    };
+  }
+
+  /**
+   * Serializes the index to a tree structure of buffers.
+   *
+   * @returns {Promise<Record<string, Buffer>>} Map of path → serialized content
+   */
+  async serialize() {
+    return await this._builder.serialize();
+  }
+
+  /**
+   * Gets the underlying BitmapIndexBuilder.
+   *
+   * @returns {BitmapIndexBuilder}
+   */
+  get builder() {
+    return this._builder;
+  }
+}
+
+/**
+ * Convenience function to build and serialize a WARP state index.
+ *
+ * @param {import('./JoinReducer.js').WarpStateV5} state - The materialized state
+ * @param {Object} [options] - Configuration
+ * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort for shard checksums
+ * @returns {Promise<{tree: Record<string, Buffer>, stats: {nodes: number, edges: number}}>} Serialized index and stats
+ *
+ * @example
+ * import { buildWarpStateIndex } from './WarpStateIndexBuilder.js';
+ *
+ * const state = await graph.materialize();
+ * const { tree, stats } = await buildWarpStateIndex(state);
+ */
+export async function buildWarpStateIndex(state, { crypto } = {}) {
+  const indexBuilder = new WarpStateIndexBuilder({ crypto });
+  const { stats } = indexBuilder.buildFromState(state);
+  const tree = await indexBuilder.serialize();
+  return { tree, stats };
+}