trellis 1.0.7 → 2.0.5

package/src/sync/sync-engine.ts

@@ -0,0 +1,258 @@
+/**
+ * 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

@@ -0,0 +1,104 @@
+/**
+ * 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[];
+}

package/src/vcs/blob-store.ts

@@ -0,0 +1,124 @@
+/**
+ * Content-Addressable Blob Store
+ *
+ * Stores file content indexed by SHA-256 hash. Provides the source of truth
+ * for file reconstruction at any point in history. The EAV graph stores
+ * structural metadata; the blob store stores byte-exact content.
+ *
+ * Storage format: `.trellis/blobs/{hash}` files on disk.
+ * Future: migrate to SQLite `blobs(hash TEXT PRIMARY KEY, content BLOB)`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+export class BlobStore {
+  private blobDir: string;
+
+  constructor(trellisDir: string) {
+    this.blobDir = join(trellisDir, 'blobs');
+    if (!existsSync(this.blobDir)) {
+      mkdirSync(this.blobDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Store content and return its SHA-256 hash.
+   * Idempotent — storing the same content twice is a no-op.
+   */
+  async put(content: Buffer | Uint8Array): Promise<string> {
+    const hash = await this.hash(content);
+    const blobPath = join(this.blobDir, hash);
+    if (!existsSync(blobPath)) {
+      writeFileSync(blobPath, content);
+    }
+    return hash;
+  }
+
+  /**
+   * Synchronous put — uses Bun's sync crypto if available.
+   */
+  putSync(content: Buffer | Uint8Array): string {
+    const hash = this.hashSync(content);
+    const blobPath = join(this.blobDir, hash);
+    if (!existsSync(blobPath)) {
+      writeFileSync(blobPath, content);
+    }
+    return hash;
+  }
+
+  /**
+   * Retrieve content by hash. Returns null if not found.
+   */
+  get(hash: string): Buffer | null {
+    const blobPath = join(this.blobDir, hash);
+    if (!existsSync(blobPath)) {
+      return null;
+    }
+    return readFileSync(blobPath);
+  }
+
+  /**
+   * Check if a blob exists.
+   */
+  has(hash: string): boolean {
+    return existsSync(join(this.blobDir, hash));
+  }
+
+  /**
+   * Compute SHA-256 hash of content (async).
+   */
+  async hash(content: Buffer | Uint8Array): Promise<string> {
+    const hashBuffer = await crypto.subtle.digest(
+      'SHA-256',
+      content as unknown as ArrayBuffer,
+    );
+    return this.hexFromBuffer(hashBuffer);
+  }
+
+  /**
+   * Compute SHA-256 hash of content (sync, using Bun's CryptoHasher).
+   */
+  hashSync(content: Buffer | Uint8Array): string {
+    const hasher = new Bun.CryptoHasher('sha256');
+    hasher.update(content);
+    return hasher.digest('hex');
+  }
+
+  /**
+   * Returns the number of blobs stored.
+   */
+  count(): number {
+    try {
+      const { readdirSync } = require('fs');
+      return readdirSync(this.blobDir).length;
+    } catch {
+      return 0;
+    }
+  }
+
+  /**
+   * Returns the total size of all blobs in bytes.
+   */
+  totalSize(): number {
+    try {
+      const { readdirSync, statSync } = require('fs');
+      const files: string[] = readdirSync(this.blobDir);
+      return files.reduce((sum: number, f: string) => {
+        try {
+          return sum + statSync(join(this.blobDir, f)).size;
+        } catch {
+          return sum;
+        }
+      }, 0);
+    } catch {
+      return 0;
+    }
+  }
+
+  private hexFromBuffer(buffer: ArrayBuffer): string {
+    return Array.from(new Uint8Array(buffer))
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+}

package/src/vcs/branch.ts

@@ -0,0 +1,150 @@
+/**
+ * Branch Management Module
+ *
+ * Extracted from engine.ts per DESIGN.md §8.1.
+ * Handles create, switch, list, delete branch operations.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { createVcsOp } from './ops.js';
+import type { VcsOp } from './types.js';
+import type { EngineContext } from './engine-context.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface BranchInfo {
+  name: string;
+  isCurrent: boolean;
+  createdAt?: string;
+}
+
+export interface BranchState {
+  currentBranch: string;
+}
+
+// ---------------------------------------------------------------------------
+// Operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new branch forked from the current branch.
+ */
+export async function createBranch(
+  ctx: EngineContext,
+  name: string,
+  currentBranch: string,
+): Promise<VcsOp> {
+  const existing = ctx.store
+    .getFactsByAttribute('type')
+    .filter((f) => f.v === 'Branch' && f.e === `branch:${name}`);
+  if (existing.length > 0) {
+    throw new Error(`Branch '${name}' already exists`);
+  }
+
+  const op = await createVcsOp('vcs:branchCreate', {
+    agentId: ctx.agentId,
+    previousHash: ctx.getLastOp()?.hash,
+    vcs: {
+      branchName: name,
+      baseBranch: currentBranch,
+      targetOpHash: ctx.getLastOp()?.hash,
+    },
+  });
+  ctx.applyOp(op);
+  return op;
+}
+
+/**
+ * Switch to an existing branch.
+ */
+export function switchBranch(
+  ctx: EngineContext,
+  name: string,
+): void {
+  const branchFacts = ctx.store
+    .getFactsByEntity(`branch:${name}`)
+    .filter((f) => f.a === 'type' && f.v === 'Branch');
+  if (branchFacts.length === 0) {
+    throw new Error(`Branch '${name}' does not exist`);
+  }
+}
+
+/**
+ * List all branches.
+ */
+export function listBranches(
+  ctx: EngineContext,
+  currentBranch: string,
+): BranchInfo[] {
+  const branchFacts = ctx.store
+    .getFactsByAttribute('type')
+    .filter((f) => f.v === 'Branch');
+
+  return branchFacts.map((f) => {
+    const nameFact = ctx.store
+      .getFactsByEntity(f.e)
+      .find((ef) => ef.a === 'name');
+    const createdFact = ctx.store
+      .getFactsByEntity(f.e)
+      .find((ef) => ef.a === 'createdAt');
+    const name = (nameFact?.v as string) ?? f.e.replace('branch:', '');
+    return {
+      name,
+      isCurrent: name === currentBranch,
+      createdAt: createdFact?.v as string | undefined,
+    };
+  });
+}
+
+/**
+ * Delete a branch (cannot delete the current branch).
+ */
+export async function deleteBranch(
+  ctx: EngineContext,
+  name: string,
+  currentBranch: string,
+): Promise<VcsOp> {
+  if (name === currentBranch) {
+    throw new Error(`Cannot delete the current branch '${name}'`);
+  }
+  const branchFacts = ctx.store
+    .getFactsByEntity(`branch:${name}`)
+    .filter((f) => f.a === 'type' && f.v === 'Branch');
+  if (branchFacts.length === 0) {
+    throw new Error(`Branch '${name}' does not exist`);
+  }
+
+  const op = await createVcsOp('vcs:branchDelete', {
+    agentId: ctx.agentId,
+    previousHash: ctx.getLastOp()?.hash,
+    vcs: { branchName: name },
+  });
+  ctx.applyOp(op);
+  return op;
+}
+
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+
+export function saveBranchState(rootPath: string, state: BranchState): void {
+  const statePath = join(rootPath, '.trellis', 'state.json');
+  writeFileSync(statePath, JSON.stringify(state));
+}
+
+export function loadBranchState(rootPath: string): BranchState {
+  const statePath = join(rootPath, '.trellis', 'state.json');
+  if (existsSync(statePath)) {
+    try {
+      const raw = readFileSync(statePath, 'utf-8');
+      const state = JSON.parse(raw);
+      if (state.currentBranch) {
+        return { currentBranch: state.currentBranch };
+      }
+    } catch {}
+  }
+  return { currentBranch: 'main' };
+}

package/src/vcs/checkpoint.ts

@@ -0,0 +1,64 @@
+/**
+ * Checkpoint Module
+ *
+ * Extracted from engine.ts per DESIGN.md §8.1.
+ * Handles checkpoint creation, listing, and auto-checkpoint logic.
+ */
+
+import { createVcsOp } from './ops.js';
+import type { VcsOp } from './types.js';
+import type { EngineContext } from './engine-context.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type CheckpointTrigger = 'manual' | 'op-count' | 'interval' | 'green-build';
+
+export interface CheckpointInfo {
+  id: string;
+  createdAt?: string;
+  trigger?: string;
+  atOpHash?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a checkpoint at the current position in the causal stream.
+ */
+export async function createCheckpoint(
+  ctx: EngineContext,
+  trigger: CheckpointTrigger = 'manual',
+): Promise<VcsOp> {
+  const op = await createVcsOp('vcs:checkpointCreate', {
+    agentId: ctx.agentId,
+    previousHash: ctx.getLastOp()?.hash,
+    vcs: { trigger },
+  });
+  ctx.applyOp(op);
+  return op;
+}
+
+/**
+ * List all checkpoints from the EAV store.
+ */
+export function listCheckpoints(ctx: EngineContext): CheckpointInfo[] {
+  const cpFacts = ctx.store
+    .getFactsByAttribute('type')
+    .filter((f) => f.v === 'Checkpoint');
+
+  return cpFacts.map((f) => {
+    const facts = ctx.store.getFactsByEntity(f.e);
+    const get = (attr: string) =>
+      facts.find((ef) => ef.a === attr)?.v as string | undefined;
+    return {
+      id: f.e,
+      createdAt: get('createdAt'),
+      trigger: get('trigger'),
+      atOpHash: get('atOpHash'),
+    };
+  });
+}