@tangentfeed/core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sreeraj T A
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @tangentfeed/core
+
+Protocol engine for tangentfeed: Hybrid Logical Clocks, the cell-level LWW operation log, replication, compaction, and operation signatures.
+
+Two dependencies, both audited and both from the same family: `@noble/curves` for Ed25519 and `@noble/hashes` for SHA-256. It was dependency-free until signing landed in v0.2; rolling our own curve arithmetic to keep that claim would have been a bad trade.
+
+Use this directly if you are supplying your own storage adapter or transport, or implementing against [PROTOCOL.md](https://github.com/sreerajta/tangentfeed/blob/main/PROTOCOL.md).
+
+Part of [tangentfeed](https://github.com/sreerajta/tangentfeed). MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,609 @@
+/**
+ * Hybrid Logical Clock — PROTOCOL.md §4
+ *
+ * State: (millis, counter, deviceId).
+ * String form: 12-hex millis + "-" + 4-hex counter + "-" + 32-hex deviceId,
+ * fixed 34 chars, lexicographic order === logical order.
+ */
+declare const MAX_COUNTER = 65535;
+declare const MAX_MILLIS: number;
+declare const MAX_DRIFT_MS = 300000;
+interface Hlc {
+    readonly millis: number;
+    readonly counter: number;
+    readonly deviceId: string;
+}
+declare class ClockDriftError extends Error {
+    readonly code = "CLOCK_DRIFT";
+    constructor(remoteMillis: number, physicalNow: number);
+}
+/** deviceId is 32 lowercase hex characters — 128 bits. §4.3 */
+declare const DEVICE_ID_HEX = 32;
+/** 12 + 1 + 4 + 1 + 32. §4.2 */
+declare const HLC_LENGTH = 50;
+declare function isValidDeviceId(s: string): boolean;
+/** Canonical string encoding. §4.2 */
+declare function encodeHlc(h: Hlc): string;
+/** Parse canonical string form; throws on malformed input. */
+declare function decodeHlc(s: string): Hlc;
+/**
+ * Total order over HLCs: millis, then counter, then deviceId.
+ * Guaranteed to agree with bytewise comparison of encodeHlc output;
+ * the property tests verify this equivalence.
+ */
+declare function compareHlc(a: Hlc, b: Hlc): number;
+/**
+ * The clock itself. Owns mutable (millis, counter) state for one device in
+ * one space. Inject `physicalClock` for tests; defaults to Date.now.
+ *
+ * Persistence: callers should persist state() after issuing ops and restore
+ * with the constructor, so a restart never reissues a timestamp.
+ */
+declare class HybridLogicalClock {
+    private millis;
+    private counter;
+    readonly deviceId: string;
+    private readonly physicalClock;
+    constructor(opts: {
+        deviceId: string;
+        physicalClock?: () => number;
+        /** restore persisted state; defaults to zero */
+        millis?: number;
+        counter?: number;
+    });
+    /** Current state, for persistence. Does not advance the clock. */
+    state(): Hlc;
+    /**
+     * Issue a timestamp for a new local op. §4.1 "send/local event".
+     * Strictly greater than every timestamp this clock has issued or observed.
+     */
+    now(): Hlc;
+    /**
+     * Observe a remote timestamp. §4.1 "receive".
+     * Throws ClockDriftError if the remote is > MAX_DRIFT_MS ahead of our
+     * physical clock (§4.5). On success the local clock becomes strictly
+     * greater than both its previous state and the remote timestamp.
+     */
+    receive(remote: Hlc): Hlc;
+    private checkBounds;
+}
+
+/**
+ * Operation format and validation — PROTOCOL.md §3, §11.
+ */
+/** JSON-representable value. */
+type Json = null | boolean | number | string | Json[] | {
+    [k: string]: Json;
+};
+declare const TOMBSTONE_COLUMN = "-";
+interface Op {
+    readonly id: string;
+    readonly table: string;
+    readonly row: string;
+    readonly column: string;
+    readonly value: Json;
+    readonly hlc: string;
+    /** Base64 Ed25519 signature over signedPayload(op). §12. */
+    readonly sig: string;
+    readonly device: string;
+}
+/** deviceId → highest HLC string seen from that device. §6 step 2. */
+type Frontier = Readonly<Record<string, string>>;
+declare class BadOpError extends Error {
+    readonly code = "BAD_OP";
+    constructor(msg: string);
+}
+declare const MAX_OP_BYTES: number;
+declare const MAX_BATCH_OPS = 1000;
+/** Validate an op's shape. Throws BadOpError. §11. */
+declare function validateOp(op: unknown): asserts op is Op;
+/** Is `op` above `frontier` (i.e., not yet seen by its holder)? */
+declare function aboveFrontier(op: Op, frontier: Frontier): boolean;
+/** Merge an op's hlc into a frontier, returning the (possibly new) frontier. */
+declare function advanceFrontier(frontier: Frontier, op: Op): Frontier;
+/**
+ * The exact bytes a signature covers: the domain, then the canonical JSON of
+ * every field except `sig` itself.
+ *
+ * `sig` is excluded because including it would require knowing the signature
+ * before computing it. Excluding it also means a verifier reconstructs the
+ * payload from the op it received, with no separate encoding to agree on.
+ */
+declare function signedPayload(op: Omit<Op, "sig"> | Op): Uint8Array;
+/** Whether `op.sig` is a valid signature by `publicKey`. §12. */
+declare function verifyOp(op: Op, publicKey: Uint8Array): boolean;
+
+/**
+ * ULID — PROTOCOL.md §4.4. 48-bit timestamp + 80-bit randomness,
+ * Crockford base32, 26 chars, canonical uppercase. No dependencies.
+ */
+declare function ulid(time?: number, randomBytes?: (n: number) => Uint8Array): string;
+
+/**
+ * Canonical JSON and operation signing — PROTOCOL.md §8.1 and §12.
+ *
+ * These live in core rather than crypto because core needs them to validate an
+ * op, and crypto already depends on core. Putting them the other way round
+ * would make the graph cyclic. Crypto re-exports both, so its public API is
+ * unchanged.
+ *
+ * Everything here is bytes in, bytes out — it knows nothing about operations,
+ * which is what lets it be tested without an engine.
+ */
+
+/**
+ * Prefixed to every signed payload so a signature can never be replayed as
+ * valid in some other context.
+ */
+declare const SIGNING_DOMAIN = "tangentfeed/v2/op";
+interface DeviceKey {
+    readonly publicKey: Uint8Array;
+    readonly privateKey: Uint8Array;
+}
+/** Canonical JSON per RFC 8785. §8.1. */
+declare function canonicalJson(value: Json): string;
+declare function generateDeviceKey(): DeviceKey;
+/**
+ * deviceId is the first 16 bytes of SHA-256(publicKey), lowercase hex.
+ *
+ * 128 bits rather than v0.1's 64: this identifier became a security boundary
+ * when it started deciding whose signature counts, and a targeted
+ * impersonation at 64 bits is within reach of a determined adversary.
+ */
+declare function deviceIdFromPublicKey(publicKey: Uint8Array): string;
+declare function signPayload(payload: Uint8Array, privateKey: Uint8Array): string;
+/**
+ * Returns false rather than throwing on malformed input. A bad signature from
+ * a peer is a routine condition on an open network, not an exceptional one.
+ */
+declare function verifyPayload(payload: Uint8Array, signature: string, publicKey: Uint8Array): boolean;
+
+/**
+ * Storage abstraction — PROTOCOL.md §8.
+ *
+ * The engine talks ONLY to this interface. Adapters are dumb byte movers with
+ * one hard obligation: applyBatch is atomic (§8.2). MemoryAdapter is the
+ * reference used by tests; IndexedDB/SQLite adapters come in M2+.
+ */
+
+interface ClockState {
+    readonly millis: number;
+    readonly counter: number;
+}
+interface BatchWrite {
+    /** ops to append to the log (already deduped by the engine) */
+    readonly ops: readonly Op[];
+    /** new winning op per affected cell, keyed by cellKey() */
+    readonly winners: ReadonlyMap<string, Op>;
+    /** frontier after this batch */
+    readonly frontier: Frontier;
+    /** clock state after this batch */
+    readonly clock: ClockState;
+}
+/** Ops and cells to physically remove during compaction (§9). */
+interface CompactionWrite {
+    /** op ids to delete from the log */
+    readonly opIds: readonly string[];
+    /** materialized cell keys to forget (tombstone GC only) */
+    readonly cellKeys: readonly string[];
+}
+interface StorageAdapter {
+    /** All winning cells of a row: column → winning op. undefined if none. */
+    getRow(table: string, row: string): Promise<ReadonlyMap<string, Op> | undefined>;
+    /** rowIds that have at least one cell op in this table (incl. tombstoned). */
+    listRows(table: string): Promise<string[]>;
+    /** Table names that have at least one op. */
+    listTables(): Promise<string[]>;
+    hasOp(id: string): Promise<boolean>;
+    /** Current winner for one cell. */
+    getWinner(table: string, row: string, column: string): Promise<Op | undefined>;
+    /** Every stored op strictly above `frontier`, sorted by hlc. §6 step 3. */
+    opsSince(frontier: Frontier): Promise<Op[]>;
+    getFrontier(): Promise<Frontier>;
+    getClock(): Promise<ClockState | undefined>;
+    /**
+     * The device's signing keypair, or undefined on a fresh store. Section 12.
+     *
+     * Stored in the clear beside the data it protects. On a device this belongs
+     * in Keychain or Keystore; recorded as follow-up rather than solved here,
+     * since the space secret already carries the same exposure.
+     */
+    getDeviceKey(): Promise<DeviceKey | undefined>;
+    setDeviceKey(key: DeviceKey): Promise<void>;
+    /** Atomic, all-or-nothing. §8.2. */
+    applyBatch(batch: BatchWrite): Promise<void>;
+    /** Total ops currently retained in the log. */
+    opCount(): Promise<number>;
+    /** Every op in the log, ascending by hlc. Used by compaction scans. */
+    allOps(): Promise<Op[]>;
+    /** Last known frontier of each peer, from since/ack exchanges (§6). */
+    getPeerFrontiers(): Promise<Record<string, Frontier>>;
+    /** Record a peer's frontier. */
+    setPeerFrontier(peer: string, frontier: Frontier): Promise<void>;
+    /** Atomically remove ops (and, for tombstone GC, cells). */
+    compact(write: CompactionWrite): Promise<void>;
+}
+declare function cellKey(table: string, row: string, column: string): string;
+declare class MemoryAdapter implements StorageAdapter {
+    private opsById;
+    /** table → row → column → winning op */
+    private tables;
+    private frontier;
+    private clock;
+    private deviceKey;
+    private peerFrontiers;
+    getRow(table: string, row: string): Promise<ReadonlyMap<string, Op> | undefined>;
+    listRows(table: string): Promise<string[]>;
+    listTables(): Promise<string[]>;
+    hasOp(id: string): Promise<boolean>;
+    getWinner(table: string, row: string, column: string): Promise<Op | undefined>;
+    opsSince(frontier: Frontier): Promise<Op[]>;
+    getFrontier(): Promise<Frontier>;
+    getDeviceKey(): Promise<DeviceKey | undefined>;
+    setDeviceKey(key: DeviceKey): Promise<void>;
+    getClock(): Promise<ClockState | undefined>;
+    opCount(): Promise<number>;
+    allOps(): Promise<Op[]>;
+    getPeerFrontiers(): Promise<Record<string, Frontier>>;
+    setPeerFrontier(peer: string, frontier: Frontier): Promise<void>;
+    compact(write: CompactionWrite): Promise<void>;
+    applyBatch(batch: BatchWrite): Promise<void>;
+}
+
+/**
+ * Compaction — PROTOCOL.md §9.
+ *
+ * The op log grows forever unless superseded ops are reclaimed. An op is
+ * droppable when BOTH hold:
+ *
+ *   (a) it is not the winning op for its cell, and
+ *   (b) every KNOWN peer's frontier has passed it.
+ *
+ * Condition (b) uses the "compaction horizon": per writer device, the MINIMUM
+ * highest-seen HLC across our own frontier and every peer frontier we have
+ * recorded from since/ack exchanges. Any op at or below the horizon has
+ * demonstrably reached everyone we know about.
+ *
+ * Why (a) alone would seem sufficient — and why it isn't:
+ * dropping a superseded cell value is harmless for LWW convergence, because a
+ * peer that never receives it will still receive the winner. The reason (b)
+ * exists is TOMBSTONES. Per §5 a row stays hidden because the tombstone is the
+ * winning op on the "-" cell, even when later cell writes carry higher HLCs.
+ * If a tombstone were forgotten while some peer still held un-synced writes
+ * for that row, those writes would arrive later, find no tombstone, and
+ * RESURRECT deleted data.
+ *
+ * Tombstone GC is therefore doubly guarded, and reclaims the row WHOLE:
+ *   - the winning "-" op must be a tombstone the horizon has passed, and
+ *   - every op belonging to that row must also be below the horizon, and
+ *   - all of the row's ops AND materialized cells are removed together.
+ * Removing the tombstone while leaving the row's other cells behind would
+ * resurrect the row locally on the very next read — the exact failure this
+ * module's tests exist to prevent.
+ *
+ * Consequence worth surfacing to users: one long-absent peer pins the horizon
+ * and blocks reclamation. `compact()` reports which peers hold it back rather
+ * than silently doing nothing. And because the horizon is only as good as the
+ * peer frontiers we have recorded, a replica that has never completed a sync
+ * treats itself as alone — correct for a genuinely single-device user, and a
+ * further reason tombstone GC requires an explicit opt-in.
+ */
+
+interface CompactionOptions {
+    /**
+     * Also reclaim tombstoned rows entirely once the horizon has passed every
+     * op of the row. Default false: §9 advises v1 implementations not to GC
+     * tombstones by default, because a peer offline beyond the horizon can no
+     * longer learn that the row was deleted.
+     */
+    includeTombstones?: boolean;
+    /** Report what would be removed without touching storage. */
+    dryRun?: boolean;
+}
+interface CompactionStats {
+    /** ops examined */
+    scanned: number;
+    /** ops removed (superseded ops, plus all ops of reclaimed rows) */
+    removed: number;
+    /** tombstoned rows reclaimed whole (0 unless includeTombstones) */
+    rowsReclaimed: number;
+    /** ops retained because they are winners */
+    retainedWinners: number;
+    /** ops retained because the horizon has not passed them */
+    retainedAboveHorizon: number;
+    /** peers whose lagging frontier pins the horizon; empty means unblocked */
+    blockedBy: string[];
+}
+/**
+ * Per-writer-device minimum of (our frontier, every known peer frontier).
+ * A missing entry means that peer has seen nothing from that device, which
+ * pins the horizon to zero for it.
+ */
+declare function compactionHorizon(own: Frontier, peerFrontiers: Record<string, Frontier>): Frontier;
+/** Peers whose frontier lags ours (and therefore hold the horizon back). */
+declare function blockingPeers(own: Frontier, peerFrontiers: Record<string, Frontier>): string[];
+/**
+ * Decide what to reclaim. Pure: takes a snapshot, returns a plan. Keeping the
+ * safety rules out of the storage layer makes them directly testable.
+ *
+ * @param winningCells cellKey → winning op (i.e. the materialized state)
+ */
+declare function planCompaction(ops: readonly Op[], winningCells: ReadonlyMap<string, Op>, horizon: Frontier, opts: CompactionOptions): {
+    opIds: string[];
+    cellKeys: string[];
+    stats: Omit<CompactionStats, "blockedBy">;
+};
+/** Snapshot of materialized state: cellKey → winning op. */
+declare function winningCells(storage: StorageAdapter): Promise<Map<string, Op>>;
+
+/**
+ * Cipher interface — PROTOCOL.md §7.
+ *
+ * Core stays dependency-free: this file defines the contract, and a concrete
+ * implementation lives in @tangentfeed/crypto. Other-language implementations are
+ * therefore free to use whatever XChaCha20-Poly1305 binding they like, as
+ * long as they match the spec'd scheme.
+ *
+ * What is encrypted: cell VALUES only. table, row, column, hlc, and device
+ * stay plaintext in v1 (§7 documents this as a known metadata leak). The
+ * tombstone column ("-") is also exempt, because §5 merge rules must be
+ * evaluable by any peer — including one that cannot decrypt — to decide
+ * whether a row is deleted. A relay therefore learns that a row was deleted,
+ * but never what it contained.
+ *
+ * AAD binds each ciphertext to its op id, so a ciphertext lifted from one op
+ * and pasted into another fails authentication rather than silently moving
+ * data between cells.
+ */
+
+interface Cipher {
+    /** Encrypt a cell value. `opId` is bound in as AAD. Returns "e1:<base64>". */
+    encrypt(value: Json, opId: string): string;
+    /**
+     * Decrypt a cell value produced by `encrypt`. Values that are not in the
+     * "e1:" envelope MUST be returned unchanged (a space may contain plaintext
+     * ops written before encryption was enabled).
+     */
+    decrypt(value: Json, opId: string): Json;
+}
+/** Prefix marking an encrypted value envelope. §3.2 */
+declare const CIPHER_PREFIX = "e1:";
+declare function isEncryptedValue(v: Json): v is string;
+declare class DecryptError extends Error {
+    readonly code = "DECRYPT_FAIL";
+    constructor(msg: string);
+}
+
+/**
+ * SyncEngine — the heart of the library.
+ *
+ * Owns: one space's replica. Local writes become ops; remote ops merge by
+ * cell-level LWW (PROTOCOL.md §5); all mutation flows through one atomic
+ * batch path. Storage and transport are injected; this file knows nothing
+ * about platforms.
+ */
+
+interface RowChange {
+    readonly table: string;
+    readonly row: string;
+}
+/** What subscribers see after every committed batch. */
+interface ChangeEvent {
+    readonly changes: readonly RowChange[];
+    readonly ops: readonly Op[];
+    /** "local" = written via insert/update/delete here; "remote" = applied via applyRemoteOps */
+    readonly origin: "local" | "remote";
+}
+type Subscriber = (event: ChangeEvent) => void;
+interface EngineOptions {
+    storage: StorageAdapter;
+    physicalClock?: () => number;
+    /**
+     * Optional end-to-end encryption (PROTOCOL.md §7). When present, local
+     * writes are encrypted before entering the op log, so ciphertext is what
+     * gets stored, replicated, and relayed. Reads decrypt transparently.
+     */
+    cipher?: Cipher;
+}
+type RowData = {
+    readonly id: string;
+} & Readonly<Record<string, Json>>;
+declare class SyncEngine {
+    readonly deviceId: string;
+    private readonly storage;
+    private readonly clock;
+    private readonly cipher;
+    private readonly subscribers;
+    private readonly deviceKey;
+    /** deviceId -> public key. Seeded with our own so we can verify our own ops. */
+    private readonly keys;
+    /** serializes all mutations; JS is single-threaded but ops are async */
+    private mutex;
+    private constructor();
+    /** This device's public key, for the `hello` message. Section 6.1. */
+    get publicKey(): Uint8Array;
+    /** Every device key known to this replica, for the `keys` message. */
+    knownKeys(): ReadonlyMap<string, Uint8Array>;
+    /**
+     * Records a peer's public key.
+     *
+     * Returns false when the key does not hash to the claimed id. That check is
+     * what makes the directory self-validating: a peer can relay keys it learned
+     * from others, but cannot invent one for somebody else.
+     */
+    learnKey(deviceId: string, publicKey: Uint8Array): boolean;
+    /**
+     * Opens a replica. Identity comes from the stored keypair, so a restart keeps
+     * the same device rather than minting a new one. Section 4.3.
+     */
+    static open(opts: EngineOptions): Promise<SyncEngine>;
+    /** Materialized row, or undefined if absent/tombstoned. §5. */
+    get(table: string, row: string): Promise<RowData | undefined>;
+    /** All visible rows of a table, sorted by rowId (ULID = insertion order). */
+    list(table: string): Promise<RowData[]>;
+    /** Full materialized state; used by tests and conformance vectors. */
+    dump(): Promise<Record<string, Record<string, Record<string, Json>>>>;
+    /** Insert a row; returns its generated rowId. */
+    insert(table: string, values: Record<string, Json>): Promise<string>;
+    /** Write one op per column. */
+    update(table: string, row: string, values: Record<string, Json>): Promise<void>;
+    /** Row tombstone. §5. */
+    delete(table: string, row: string): Promise<void>;
+    frontier(): Promise<Frontier>;
+    /** Ops the caller is missing, given their frontier. §6 step 3. */
+    opsSince(frontier: Frontier): Promise<Op[]>;
+    /**
+     * Apply a batch of remote ops. Validates, drift-checks, dedupes, merges,
+     * persists atomically, notifies. Returns number of newly applied ops.
+     * Throws BadOpError / ClockDriftError; on throw, nothing was applied.
+     */
+    applyRemoteOps(remoteOps: readonly unknown[]): Promise<number>;
+    /**
+     * Observe a peer's clock from a hello message (§6 step 1). Drift-checks and
+     * advances + persists our clock without applying any ops.
+     */
+    observeRemoteClock(hlc: string): Promise<void>;
+    /**
+     * Record a peer's frontier, learned from a since/ack exchange. This is the
+     * input that lets compaction know what has safely reached everyone.
+     */
+    recordPeerFrontier(peer: string, frontier: Frontier): Promise<void>;
+    peerFrontiers(): Promise<Record<string, Frontier>>;
+    /** Number of ops currently retained in the log. */
+    opCount(): Promise<number>;
+    /**
+     * Reclaim superseded ops (§9). Safe by construction: winners are never
+     * dropped, and nothing above the compaction horizon is touched. Tombstone
+     * GC is opt-in via `includeTombstones` — see compaction.ts for why.
+     */
+    compact(opts?: CompactionOptions): Promise<CompactionStats>;
+    subscribe(cb: Subscriber): () => void;
+    private makeLocalOp;
+    /**
+     * The single mutation path (local and remote both land here):
+     * compute LWW winners for affected cells, advance frontier, persist
+     * atomically, notify subscribers. §5, §8.2.
+     */
+    private commit;
+    /** Decrypt (if needed) and shape stored cells into a row. */
+    private materialize;
+    private clockMillisForUlid;
+    private locked;
+}
+/**
+ * Test/utility helper: one full bidirectional sync between two engines
+ * (§6 steps 2–4 without a wire), including the frontier recording that a real
+ * ack performs. That recording is not cosmetic: compaction's safety horizon
+ * (§9) is computed from known peer frontiers, so an exchange that skipped it
+ * would leave each engine believing it were a lone replica and permit
+ * unsafe tombstone reclamation. Repeat until both frontiers are equal for
+ * multi-peer quiescence.
+ */
+declare function syncOnce(a: SyncEngine, b: SyncEngine): Promise<void>;
+
+/**
+ * Replication — PROTOCOL.md §6 as reusable logic over any transport.
+ *
+ * A Transport is deliberately dumb: a lossy-ok message bus. `send` delivers to
+ * everyone reachable (bus semantics); point-to-point transports implement the
+ * same interface by fanning out and letting `to`-filtering discard the rest.
+ * The Replicator supplies everything protocol-shaped: hello, frontier
+ * exchange, batched op transfer, acks, and live tail.
+ *
+ * Robustness comes from the engine, not the transport: ops are idempotent and
+ * merge is commutative, so lost, duplicated, or reordered messages can only
+ * delay convergence, never corrupt it. Any gap heals on the next hello/since
+ * exchange.
+ */
+
+declare const WIRE_VERSION = 2;
+/** Conservative default; well under MAX_BATCH_OPS and typical message limits. */
+declare const OPS_PER_MESSAGE = 500;
+type WireMsg = {
+    t: "hello";
+    v: number;
+    space: string;
+    from: string;
+    clock: string;
+    key: string;
+} | {
+    t: "keys";
+    v: number;
+    space: string;
+    from: string;
+    to?: string;
+    keys: Record<string, string>;
+} | {
+    t: "since";
+    v: number;
+    space: string;
+    from: string;
+    to: string;
+    have: Frontier;
+} | {
+    t: "ops";
+    v: number;
+    space: string;
+    from: string;
+    to?: string;
+    ops: Op[];
+} | {
+    t: "ack";
+    v: number;
+    space: string;
+    from: string;
+    to: string;
+    frontier: Frontier;
+};
+interface Transport {
+    /** Deliver to all reachable peers. Fire-and-forget; loss is acceptable. */
+    send(msg: WireMsg): void;
+    /** Register receive callback; returns unsubscribe. */
+    onMessage(cb: (msg: WireMsg) => void): () => void;
+    /**
+     * Optional: fires when a new peer link becomes ready (e.g. a DataChannel
+     * opens). Lets the Replicator (re-)send hello to late-connecting peers.
+     * Bus transports with no link concept (BroadcastChannel) omit this.
+     */
+    onPeerConnect?(cb: (peerId?: string) => void): () => void;
+    close(): void;
+}
+interface ReplicatorEvents {
+    onPeersChange?: (peers: ReadonlySet<string>) => void;
+    /** Protocol-level problems (drift, bad ops). Replication continues with other peers. */
+    onError?: (err: unknown, context: {
+        from?: string;
+    }) => void;
+}
+declare class Replicator {
+    private readonly engine;
+    private readonly transport;
+    private readonly space;
+    private readonly events;
+    private readonly peers;
+    private unsubs;
+    private started;
+    constructor(opts: {
+        engine: SyncEngine;
+        transport: Transport;
+        space: string;
+        events?: ReplicatorEvents;
+    });
+    get peerIds(): ReadonlySet<string>;
+    start(): Promise<void>;
+    stop(): void;
+    private sendHello;
+    /**
+     * Every device key we hold, sent before any ops so a peer never receives an
+     * op it cannot verify. Section 6.1.
+     *
+     * Relaying keys we learned from others is what lets an op reach a peer that
+     * never met its author. It is safe because learnKey discards any entry that
+     * does not hash to its claimed id.
+     */
+    private sendKeys;
+    private handle;
+    private msg;
+}
+
+export { BadOpError, type BatchWrite, CIPHER_PREFIX, type ChangeEvent, type Cipher, ClockDriftError, type ClockState, type CompactionOptions, type CompactionStats, type CompactionWrite, DEVICE_ID_HEX, DecryptError, type DeviceKey, type EngineOptions, type Frontier, HLC_LENGTH, type Hlc, HybridLogicalClock, type Json, MAX_BATCH_OPS, MAX_COUNTER, MAX_DRIFT_MS, MAX_MILLIS, MAX_OP_BYTES, MemoryAdapter, OPS_PER_MESSAGE, type Op, Replicator, type ReplicatorEvents, type RowChange, type RowData, SIGNING_DOMAIN, type StorageAdapter, type Subscriber, SyncEngine, TOMBSTONE_COLUMN, type Transport, WIRE_VERSION, type WireMsg, aboveFrontier, advanceFrontier, blockingPeers, canonicalJson, cellKey, compactionHorizon, compareHlc, decodeHlc, deviceIdFromPublicKey, encodeHlc, generateDeviceKey, isEncryptedValue, isValidDeviceId, planCompaction, signPayload, signedPayload, syncOnce, ulid, validateOp, verifyOp, verifyPayload, winningCells };