trellis 2.0.13 → 2.1.2

package/src/sync/reconciler.ts

@@ -1,237 +0,0 @@
-/**
- * CRDT Reconciler
- *
- * DESIGN.md §10.5 — Merges divergent op streams using causal ordering.
- * Each device maintains its own causal chain. The reconciler merges
- * divergent chains by:
- *   1. Finding the common ancestor (fork point)
- *   2. Collecting ops unique to each side
- *   3. Topologically sorting the combined set by causal dependencies
- *   4. Detecting conflicts using patch commutativity (§4.4)
- */
-
-import type { VcsOp } from '../vcs/types.js';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface ReconcileResult {
-  /** The merged op stream in causal order. */
-  merged: VcsOp[];
-  /** Ops that were only on side A. */
-  uniqueToA: VcsOp[];
-  /** Ops that were only on side B. */
-  uniqueToB: VcsOp[];
-  /** Common ancestor op hash (fork point). */
-  forkPoint: string | null;
-  /** Whether the merge was clean (no causal conflicts). */
-  clean: boolean;
-  /** Conflicting op pairs (both modify same file without commutativity). */
-  conflicts: ReconcileConflict[];
-}
-
-export interface ReconcileConflict {
-  opA: VcsOp;
-  opB: VcsOp;
-  filePath: string;
-  reason: string;
-}
-
-// ---------------------------------------------------------------------------
-// Core reconciliation
-// ---------------------------------------------------------------------------
-
-/**
- * Find the common ancestor (fork point) of two op streams.
- * Returns the hash of the last op that appears in both streams.
- */
-export function findForkPoint(opsA: VcsOp[], opsB: VcsOp[]): string | null {
-  const hashesB = new Set(opsB.map((o) => o.hash));
-  let forkPoint: string | null = null;
-
-  for (const op of opsA) {
-    if (hashesB.has(op.hash)) {
-      forkPoint = op.hash;
-    }
-  }
-
-  return forkPoint;
-}
-
-/**
- * Reconcile two divergent op streams into a single merged stream.
- *
- * Algorithm:
- *   1. Find the fork point (last common op)
- *   2. Split each stream into shared prefix + unique suffix
- *   3. Check for conflicts in the unique portions
- *   4. Interleave unique ops in causal (timestamp) order
- */
-export function reconcile(opsA: VcsOp[], opsB: VcsOp[]): ReconcileResult {
-  const forkPoint = findForkPoint(opsA, opsB);
-
-  // Split into shared prefix and unique suffixes
-  const hashesA = new Set(opsA.map((o) => o.hash));
-  const hashesB = new Set(opsB.map((o) => o.hash));
-
-  const shared: VcsOp[] = [];
-  const uniqueToA: VcsOp[] = [];
-  const uniqueToB: VcsOp[] = [];
-
-  for (const op of opsA) {
-    if (hashesB.has(op.hash)) {
-      shared.push(op);
-    } else {
-      uniqueToA.push(op);
-    }
-  }
-
-  for (const op of opsB) {
-    if (!hashesA.has(op.hash)) {
-      uniqueToB.push(op);
-    }
-  }
-
-  // If one side has no unique ops, it's a fast-forward
-  if (uniqueToA.length === 0) {
-    return {
-      merged: [...shared, ...uniqueToB],
-      uniqueToA: [],
-      uniqueToB,
-      forkPoint,
-      clean: true,
-      conflicts: [],
-    };
-  }
-
-  if (uniqueToB.length === 0) {
-    return {
-      merged: [...shared, ...uniqueToA],
-      uniqueToA,
-      uniqueToB: [],
-      forkPoint,
-      clean: true,
-      conflicts: [],
-    };
-  }
-
-  // Both sides diverged — detect conflicts
-  const conflicts = detectConflicts(uniqueToA, uniqueToB);
-
-  // Merge unique ops by timestamp (causal ordering)
-  const interleaved = interleaveByTimestamp(uniqueToA, uniqueToB);
-
-  return {
-    merged: [...shared, ...interleaved],
-    uniqueToA,
-    uniqueToB,
-    forkPoint,
-    clean: conflicts.length === 0,
-    conflicts,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Conflict detection
-// ---------------------------------------------------------------------------
-
-/** VcsOp kinds that represent file-level mutations. */
-const FILE_MUTATION_KINDS = new Set([
-  'vcs:fileAdd',
-  'vcs:fileModify',
-  'vcs:fileDelete',
-  'vcs:fileRename',
-]);
-
-/**
- * Detect conflicts between two sets of unique ops.
- * Two ops conflict when they both mutate the same file.
- */
-function detectConflicts(
-  uniqueA: VcsOp[],
-  uniqueB: VcsOp[],
-): ReconcileConflict[] {
-  const conflicts: ReconcileConflict[] = [];
-
-  // Index A's file mutations
-  const aMutations = new Map<string, VcsOp[]>();
-  for (const op of uniqueA) {
-    if (!FILE_MUTATION_KINDS.has(op.kind) || !op.vcs?.filePath) continue;
-    const path = op.vcs.filePath;
-    if (!aMutations.has(path)) aMutations.set(path, []);
-    aMutations.get(path)!.push(op);
-  }
-
-  // Check B's file mutations against A's
-  for (const op of uniqueB) {
-    if (!FILE_MUTATION_KINDS.has(op.kind) || !op.vcs?.filePath) continue;
-    const path = op.vcs.filePath;
-    const aOps = aMutations.get(path);
-    if (!aOps) continue;
-
-    for (const aOp of aOps) {
-      // Same file modified by both sides
-      if (aOp.kind === 'vcs:fileModify' && op.kind === 'vcs:fileModify') {
-        conflicts.push({
-          opA: aOp,
-          opB: op,
-          filePath: path,
-          reason: `Both sides modified ${path}`,
-        });
-      } else if (
-        (aOp.kind === 'vcs:fileDelete' && op.kind === 'vcs:fileModify') ||
-        (aOp.kind === 'vcs:fileModify' && op.kind === 'vcs:fileDelete')
-      ) {
-        conflicts.push({
-          opA: aOp,
-          opB: op,
-          filePath: path,
-          reason: `Delete/modify conflict on ${path}`,
-        });
-      } else if (aOp.kind === 'vcs:fileAdd' && op.kind === 'vcs:fileAdd') {
-        // Both added same file — conflict if different content
-        if (aOp.vcs?.contentHash !== op.vcs?.contentHash) {
-          conflicts.push({
-            opA: aOp,
-            opB: op,
-            filePath: path,
-            reason: `Both sides added ${path} with different content`,
-          });
-        }
-      }
-    }
-  }
-
-  return conflicts;
-}
-
-// ---------------------------------------------------------------------------
-// Interleaving
-// ---------------------------------------------------------------------------
-
-/**
- * Interleave two op arrays by timestamp, preserving causal ordering
- * within each array.
- */
-function interleaveByTimestamp(a: VcsOp[], b: VcsOp[]): VcsOp[] {
-  const result: VcsOp[] = [];
-  let ai = 0;
-  let bi = 0;
-
-  while (ai < a.length && bi < b.length) {
-    const tA = new Date(a[ai].timestamp).getTime();
-    const tB = new Date(b[bi].timestamp).getTime();
-
-    if (tA <= tB) {
-      result.push(a[ai++]);
-    } else {
-      result.push(b[bi++]);
-    }
-  }
-
-  while (ai < a.length) result.push(a[ai++]);
-  while (bi < b.length) result.push(b[bi++]);
-
-  return result;
-}

package/src/sync/sync-engine.ts

@@ -1,258 +0,0 @@
-/**
- * Sync Engine
- *
- * DESIGN.md §10.5 — Peer sync protocol.
- * Coordinates push/pull of ops between peers using a transport layer.
- * Supports both linear (fast-forward only) and CRDT (concurrent append)
- * branch modes.
- */
-
-import type { VcsOp } from '../vcs/types.js';
-import type {
-  SyncTransport,
-  SyncMessage,
-  SyncState,
-  PeerId,
-  BranchPolicy,
-} from './types.js';
-import { reconcile, findForkPoint, type ReconcileResult } from './reconciler.js';
-
-// ---------------------------------------------------------------------------
-// Sync Engine
-// ---------------------------------------------------------------------------
-
-export class SyncEngine {
-  private localPeerId: string;
-  private state: SyncState;
-  private transport: SyncTransport;
-  private getLocalOps: () => VcsOp[];
-  private onOpsReceived: (ops: VcsOp[]) => void;
-  private branchPolicy: BranchPolicy;
-
-  constructor(opts: {
-    localPeerId: string;
-    transport: SyncTransport;
-    getLocalOps: () => VcsOp[];
-    onOpsReceived: (ops: VcsOp[]) => void;
-    branchPolicy?: BranchPolicy;
-  }) {
-    this.localPeerId = opts.localPeerId;
-    this.transport = opts.transport;
-    this.getLocalOps = opts.getLocalOps;
-    this.onOpsReceived = opts.onOpsReceived;
-    this.branchPolicy = opts.branchPolicy ?? { linear: true };
-
-    this.state = {
-      localPeerId: opts.localPeerId,
-      peerHeads: new Map(),
-      pendingAcks: new Set(),
-      lastSync: new Map(),
-    };
-
-    // Register message handler
-    this.transport.onMessage((msg) => this.handleMessage(msg));
-  }
-
-  // -------------------------------------------------------------------------
-  // Public API
-  // -------------------------------------------------------------------------
-
-  /**
-   * Initiate a sync with a specific peer.
-   * Sends a 'have' message advertising our heads.
-   */
-  async pushTo(peerId: string): Promise<void> {
-    const ops = this.getLocalOps();
-    const heads: Record<string, string> = {};
-    if (ops.length > 0) {
-      heads['main'] = ops[ops.length - 1].hash;
-    }
-
-    await this.transport.send(peerId, {
-      type: 'have',
-      peerId: this.localPeerId,
-      heads,
-      opCount: ops.length,
-    });
-  }
-
-  /**
-   * Request ops from a peer.
-   */
-  async pullFrom(peerId: string): Promise<void> {
-    const ops = this.getLocalOps();
-    const lastHash = ops.length > 0 ? ops[ops.length - 1].hash : undefined;
-
-    await this.transport.send(peerId, {
-      type: 'want',
-      peerId: this.localPeerId,
-      wantHashes: [],
-      afterHash: lastHash,
-    });
-  }
-
-  /**
-   * Send all our ops to a peer (full push).
-   */
-  async sendOps(peerId: string, ops?: VcsOp[]): Promise<void> {
-    const opsToSend = ops ?? this.getLocalOps();
-    await this.transport.send(peerId, {
-      type: 'ops',
-      peerId: this.localPeerId,
-      ops: opsToSend,
-    });
-  }
-
-  /**
-   * Reconcile our ops with a remote peer's ops.
-   */
-  reconcileWith(remoteOps: VcsOp[]): ReconcileResult {
-    const localOps = this.getLocalOps();
-    return reconcile(localOps, remoteOps);
-  }
-
-  /**
-   * Get current sync state.
-   */
-  getState(): SyncState {
-    return this.state;
-  }
-
-  /**
-   * Get branch policy.
-   */
-  getBranchPolicy(): BranchPolicy {
-    return this.branchPolicy;
-  }
-
-  /**
-   * Set branch policy.
-   */
-  setBranchPolicy(policy: BranchPolicy): void {
-    this.branchPolicy = policy;
-  }
-
-  /**
-   * List known peers.
-   */
-  listPeers(): PeerId[] {
-    return this.transport.peers();
-  }
-
-  // -------------------------------------------------------------------------
-  // Message handling
-  // -------------------------------------------------------------------------
-
-  private handleMessage(msg: SyncMessage): void {
-    switch (msg.type) {
-      case 'have':
-        this.handleHave(msg);
-        break;
-      case 'want':
-        this.handleWant(msg);
-        break;
-      case 'ops':
-        this.handleOps(msg);
-        break;
-      case 'ack':
-        this.handleAck(msg);
-        break;
-    }
-  }
-
-  private handleHave(msg: Extract<SyncMessage, { type: 'have' }>): void {
-    // Store peer heads
-    this.state.peerHeads.set(msg.peerId, msg.heads);
-
-    // Compare with our state — determine what we need
-    const localOps = this.getLocalOps();
-    const localHashes = new Set(localOps.map((o) => o.hash));
-
-    // Check if peer has ops we don't
-    for (const [, hash] of Object.entries(msg.heads)) {
-      if (!localHashes.has(hash)) {
-        // Peer is ahead — request their ops
-        this.transport.send(msg.peerId, {
-          type: 'want',
-          peerId: this.localPeerId,
-          wantHashes: [],
-          afterHash: localOps.length > 0 ? localOps[localOps.length - 1].hash : undefined,
-        });
-        return;
-      }
-    }
-
-    // Check if we have ops they don't — push them
-    const peerOpCount = msg.opCount;
-    if (localOps.length > peerOpCount) {
-      // Send ops they might be missing
-      const opsToSend = localOps.slice(peerOpCount);
-      this.transport.send(msg.peerId, {
-        type: 'ops',
-        peerId: this.localPeerId,
-        ops: opsToSend,
-      });
-    }
-  }
-
-  private handleWant(msg: Extract<SyncMessage, { type: 'want' }>): void {
-    const localOps = this.getLocalOps();
-
-    let opsToSend: VcsOp[];
-    if (msg.afterHash) {
-      const idx = localOps.findIndex((o) => o.hash === msg.afterHash);
-      opsToSend = idx >= 0 ? localOps.slice(idx + 1) : localOps;
-    } else if (msg.wantHashes.length > 0) {
-      const wanted = new Set(msg.wantHashes);
-      opsToSend = localOps.filter((o) => wanted.has(o.hash));
-    } else {
-      opsToSend = localOps;
-    }
-
-    if (opsToSend.length > 0) {
-      this.transport.send(msg.peerId, {
-        type: 'ops',
-        peerId: this.localPeerId,
-        ops: opsToSend,
-      });
-    }
-  }
-
-  private handleOps(msg: Extract<SyncMessage, { type: 'ops' }>): void {
-    if (msg.ops.length === 0) return;
-
-    if (this.branchPolicy.linear) {
-      // Linear mode: only accept fast-forward appends
-      const localOps = this.getLocalOps();
-      const localHashes = new Set(localOps.map((o) => o.hash));
-
-      // Filter to only new ops
-      const newOps = msg.ops.filter((o) => !localHashes.has(o.hash));
-      if (newOps.length > 0) {
-        this.onOpsReceived(newOps);
-      }
-    } else {
-      // CRDT mode: reconcile divergent streams
-      const result = this.reconcileWith(msg.ops);
-      if (result.uniqueToB.length > 0) {
-        this.onOpsReceived(result.uniqueToB);
-      }
-    }
-
-    // Acknowledge
-    this.transport.send(msg.peerId, {
-      type: 'ack',
-      peerId: this.localPeerId,
-      integrated: msg.ops.map((o) => o.hash),
-    });
-
-    this.state.lastSync.set(msg.peerId, new Date().toISOString());
-  }
-
-  private handleAck(msg: Extract<SyncMessage, { type: 'ack' }>): void {
-    for (const hash of msg.integrated) {
-      this.state.pendingAcks.delete(hash);
-    }
-    this.state.lastSync.set(msg.peerId, new Date().toISOString());
-  }
-}

package/src/sync/types.ts

@@ -1,104 +0,0 @@
-/**
- * Peer Sync — Type Definitions
- *
- * DESIGN.md §3.5, §10.5 — Peer sync + CRDTs.
- * Types for peer identity, sync messages, causal DAG, and
- * branch concurrency modes.
- */
-
-import type { VcsOp } from '../vcs/types.js';
-
-// ---------------------------------------------------------------------------
-// Peer Identity
-// ---------------------------------------------------------------------------
-
-export interface PeerId {
-  /** Unique peer identifier (typically derived from identity DID). */
-  id: string;
-  /** Human-readable display name. */
-  name: string;
-  /** Last seen timestamp. */
-  lastSeen?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Sync Messages
-// ---------------------------------------------------------------------------
-
-export type SyncMessage =
-  | SyncHaveMessage
-  | SyncWantMessage
-  | SyncOpsMessage
-  | SyncAckMessage;
-
-/** Advertise which op hashes we have. */
-export interface SyncHaveMessage {
-  type: 'have';
-  peerId: string;
-  /** Our head op hashes (one per branch). */
-  heads: Record<string, string>;
-  /** Total op count for quick comparison. */
-  opCount: number;
-}
-
-/** Request ops we're missing. */
-export interface SyncWantMessage {
-  type: 'want';
-  peerId: string;
-  /** Op hashes we need (those the remote has but we don't). */
-  wantHashes: string[];
-  /** Alternatively: request all ops after a given hash. */
-  afterHash?: string;
-}
-
-/** Send a batch of ops. */
-export interface SyncOpsMessage {
-  type: 'ops';
-  peerId: string;
-  ops: VcsOp[];
-}
-
-/** Acknowledge receipt. */
-export interface SyncAckMessage {
-  type: 'ack';
-  peerId: string;
-  /** Hashes of ops we've integrated. */
-  integrated: string[];
-}
-
-// ---------------------------------------------------------------------------
-// Sync State
-// ---------------------------------------------------------------------------
-
-export interface SyncState {
-  /** Our peer identity. */
-  localPeerId: string;
-  /** Known peers and their head hashes. */
-  peerHeads: Map<string, Record<string, string>>;
-  /** Ops we've sent but not yet acknowledged. */
-  pendingAcks: Set<string>;
-  /** Last sync timestamp per peer. */
-  lastSync: Map<string, string>;
-}
-
-// ---------------------------------------------------------------------------
-// Branch Concurrency Policy
-// ---------------------------------------------------------------------------
-
-export interface BranchPolicy {
-  /** If true, only fast-forward appends (one writer). Default. */
-  linear: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Sync Transport (abstract interface)
-// ---------------------------------------------------------------------------
-
-export interface SyncTransport {
-  /** Send a message to a specific peer. */
-  send(peerId: string, message: SyncMessage): Promise<void>;
-  /** Register a handler for incoming messages. */
-  onMessage(handler: (message: SyncMessage) => void): void;
-  /** List connected peers. */
-  peers(): PeerId[];
-}