trellis/dist/sync/sync-engine.d.ts

Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications

/**
 * 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, SyncNackMessage, SyncDeviceRevokedMessage, SyncState, PeerId, BranchPolicy, NackReason } from './types.js';
import { type ReconcileResult } from './reconciler.js';
/**
 * Per-op rejection returned by `onOpsReceived`. Translated into one or more
 * `nack` messages on the wire, grouped by `reason`.
 */
export interface OpsReceivedRejection {
    hash: string;
    reason: NackReason;
    details?: string;
}
/**
 * Optional return value of `onOpsReceived`. When present, the engine uses it
 * to send precise `nack` messages and to compute the `ack` set (incoming
 * hashes minus rejected). When absent, all incoming ops are ack'd and no
 * nack is sent — preserving the original SyncEngine semantics.
 */
export interface OpsReceivedResult {
    rejections: OpsReceivedRejection[];
}
export declare class SyncEngine {
    private localPeerId;
    private state;
    private transport;
    private getLocalOps;
    private onOpsReceived;
    private onNackReceived?;
    private onDeviceRevoked?;
    private branchPolicy;
    constructor(opts: {
        localPeerId: string;
        transport: SyncTransport;
        getLocalOps: () => VcsOp[];
        onOpsReceived: (ops: VcsOp[]) => void | OpsReceivedResult | Promise<void | OpsReceivedResult>;
        onNackReceived?: (nack: SyncNackMessage) => void | Promise<void>;
        onDeviceRevoked?: (msg: SyncDeviceRevokedMessage) => void | Promise<void>;
        branchPolicy?: BranchPolicy;
    });
    /**
     * Initiate a sync with a specific peer.
     * Sends a 'have' message advertising our heads.
     */
    pushTo(peerId: string): Promise<void>;
    /**
     * Request ops from a peer.
     */
    pullFrom(peerId: string): Promise<void>;
    /**
     * Request the peer's complete op set and rely on hash dedupe during ingest.
     */
    pullAllFrom(peerId: string): Promise<void>;
    /**
     * Request a truncated tail snapshot from a room peer (late-joiner catch-up).
     * The room replies with a `snapshot` message handled like `ops`.
     */
    requestSnapshot(peerId: string, maxOps?: number): Promise<void>;
    /**
     * Send all our ops to a peer (full push).
     */
    sendOps(peerId: string, ops?: VcsOp[]): Promise<void>;
    /**
     * Internal: send an `ops` message and track outbound hashes in
     * `pendingAcks` until the receiver acks or nacks them. All three sites
     * that emit `ops` (sendOps, handleHave, handleWant) route through here so
     * pendingAcks reflects every outbound op uniformly.
     */
    private sendOpsMessage;
    /**
     * Reconcile our ops with a remote peer's ops.
     */
    reconcileWith(remoteOps: VcsOp[]): ReconcileResult;
    /**
     * Get current sync state.
     */
    getState(): SyncState;
    /**
     * Get branch policy.
     */
    getBranchPolicy(): BranchPolicy;
    /**
     * Set branch policy.
     */
    setBranchPolicy(policy: BranchPolicy): void;
    /**
     * List known peers.
     */
    listPeers(): PeerId[];
    private handleMessage;
    private handleDeviceRevoked;
    private handleSnapshot;
    private handleHave;
    private handleWant;
    private handleOps;
    private handleAck;
    private handleNack;
}
//# sourceMappingURL=sync-engine.d.ts.map