@openlfcp/client 0.1.2 → 0.1.3

package/dist/sync-client.js

@@ -0,0 +1,1401 @@
+import { actorSequence, dataEpoch, hash32, LfcpError, toHex, } from "@openlfcp/core";
+import { exportSecretKeyBytes, sha256 } from "@openlfcp/crypto";
+import { dekSecretRef, } from "@openlfcp/storage";
+import { addRange, addSequence, batchDataRanges, canonicalFrontierToCbor, createMessage, ERROR_CODE, hasSequence, haveDifference, localControlOf, MESSAGE_TYPE, missingFrom, normalizeLiveHaves, parseControlRecord, parseDataUnit, parseKeyPackage, planControlSync, receiveKeyPackage, receiveSnapshot, validateControlChain, } from "@openlfcp/wire";
+import { encode } from "@openlfcp/wire/cbor";
+import { LfcpConnection } from "./connection.js";
+import { EngineGuard, isEngineTrap, snapshotItem } from "./engine-guard.js";
+import { resourceSyncState, snapshotFrontier } from "./outbound.js";
+import { createQueuedSnapshot } from "./queue.js";
+import { resourcePhaseTransition, } from "./resource-state.js";
+import { adoptStoredDeks, dekResolver, loadControlChain, saveControlChain, saveControlConflict, } from "./storage.js";
+/** 1 s, doubling, at most 60 s, forever. */
+export const defaultReconnect = (attempt) => Math.min(60_000, 1000 * 2 ** (attempt - 1));
+/**
+ * §62 codes that end syncing a Resource on this server when they refuse
+ * RESOURCE_OPEN or one of its reads (CONTROL_GET, KEY_PACKAGE_GET, DATA_GET,
+ * DATA_HAVE, SNAPSHOT_GET). Repeating the same request cannot change them:
+ * the server's hosting or the Resource's Control state must change first,
+ * and the application decides when to ask again. Every other code is
+ * transient for these requests (RATE_LIMITED, INTERNAL_ERROR, QUOTA_EXCEEDED,
+ * unknown codes) and is retried with the ReconnectPolicy's backoff, except
+ * where the request has its own fallback: KEY_PACKAGE_GET → KEY_BLOCKED,
+ * SNAPSHOT_GET → replaying the units (§29.2).
+ */
+export const TERMINAL_RESOURCE_CODES = new Set([
+    "RESOURCE_NOT_HOSTED",
+    "RESOURCE_NOT_FOUND",
+    "RESOURCE_TOMBSTONED",
+    "AUTHORIZATION_FAILED",
+    "PROTOCOL_UNSUPPORTED",
+    "MALFORMED_MESSAGE",
+    "PROFILE_UNSUPPORTED",
+]);
+const NACK_NAME = new Map(Object.entries(ERROR_CODE).map(([k, v]) => [v, k]));
+/**
+ * Data Unit statuses whose units this client has accepted and may offer to
+ * a server that lacks them (§68.1): never a unit held for its `previous`
+ * link, a quarantined or equivocating one, or one that failed locally.
+ */
+const OFFERABLE = [
+    "merged",
+    "profile-pending",
+    "profile-held",
+    "profile-rejected",
+    "profile-unsupported",
+    "seen",
+];
+/** At most this many objects per offered DATA_PUT or KEY_PACKAGE_PUT. */
+const OFFER_BATCH = 64;
+/** The local mark that a route hosted (or opened) a Resource for this client (§41.1). */
+const hostedMark = (resource, url) => `hosted-route:${toHex(resource)}:${url}`;
+const SUBSCRIBE_DATA_AND_CONTROL = 3n;
+const iso = (ms) => new Date(ms).toISOString();
+const haveToLive = (vector) => vector.map((h) => ({
+    principalId: h.principalId,
+    contiguous: h.contiguous,
+    ...(h.extras.length > 0 ? { ranges: h.extras } : {}),
+}));
+export class SyncClient {
+    #o;
+    #connection;
+    #resources = new Map();
+    #requests = new Map();
+    /** When each request was sent (caller's clock), for the request timeout. */
+    #sentAt = new Map();
+    #requestTimeoutMs;
+    #listeners = new Set();
+    #antiEntropyMs;
+    /** The crash-loop breaker for Snapshot loads (EngineGuard). */
+    #snapshots;
+    #stopped = true;
+    /** The profile engine trapped: nothing more is processed (ENGINE_TRAP). */
+    #trapped = false;
+    #attempt = 0;
+    #reconnectAt = null;
+    /** READY's maximum message size, for offered batches (§31). */
+    #maxMessageBytes = 8 * 1024 * 1024;
+    /** Serializes message handling: each message is handled after the previous one finished. */
+    #queue = Promise.resolve();
+    constructor(options) {
+        this.#o = options;
+        this.#snapshots = new EngineGuard(options.storage, "snapshots");
+        this.#antiEntropyMs = options.antiEntropyMs ?? 30_000;
+        this.#requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
+        this.#connection = new LfcpConnection({
+            url: options.url,
+            signer: options.signer,
+            now: options.now,
+            ...(options.webSocket === undefined ? {} : { webSocket: options.webSocket }),
+            ...(options.credential === undefined ? {} : { credential: options.credential }),
+            ...(options.dataProfiles === undefined ? {} : { dataProfiles: options.dataProfiles }),
+        }, {
+            state: (state) => this.#emit({ type: "connection", state }),
+            ready: (ready) => this.#serial(() => this.#onReady(ready)),
+            message: (m) => this.#serial(() => this.#onMessage(m)),
+            closed: (reason) => this.#serial(() => this.#onClosed(reason)),
+        });
+    }
+    /** Subscribes to session events; returns the unsubscribe function. */
+    on(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    #emit(event) {
+        for (const l of this.#listeners)
+            l(event);
+    }
+    #serial(fn) {
+        this.#queue = this.#queue
+            .then(() => (this.#trapped ? undefined : fn()))
+            .catch((e) => {
+            if (!isEngineTrap(e)) {
+                this.#emit({
+                    type: "error",
+                    code: "INTERNAL",
+                    message: e instanceof Error ? e.message : String(e),
+                });
+                return;
+            }
+            // The profile engine trapped: in this process it is gone for good.
+            // Stop once, loudly; the crash-loop breaker takes over at the next start.
+            if (this.#trapped)
+                return;
+            this.#trapped = true;
+            this.#stopped = true;
+            this.#reconnectAt = null;
+            this.#connection.close("the profile engine trapped");
+            this.#emit({
+                type: "error",
+                code: "ENGINE_TRAP",
+                message: `the profile engine trapped (${e instanceof Error ? e.message : String(e)}); this process must restart`,
+            });
+        });
+    }
+    /** Resolves once every message received so far has been handled (tests and shutdown). */
+    idle() {
+        return this.#queue;
+    }
+    get connectionState() {
+        return this.#connection.state;
+    }
+    resourceState(resource) {
+        return this.#resources.get(toHex(resource))?.state ?? "CLOSED";
+    }
+    /** Why the server refused the Resource for good, or null (see ResourceRefusal). */
+    resourceRefusal(resource) {
+        return this.#resources.get(toHex(resource))?.refusal ?? null;
+    }
+    /** Connects, and reconnects after losses (per the ReconnectPolicy) until stop(). */
+    start() {
+        if (this.#trapped)
+            return;
+        this.#stopped = false;
+        this.#reconnectAt = null;
+        this.#connection.connect();
+    }
+    /** Closes the connection and stops reconnecting. Local state stays usable. */
+    async stop() {
+        this.#stopped = true;
+        this.#reconnectAt = null;
+        this.#connection.close("stopped by the application");
+        await this.idle();
+    }
+    /** Registers a Resource and opens it now (or when the session is READY). */
+    open(binding) {
+        const key = toHex(binding.resourceId);
+        let ctx = this.#resources.get(key);
+        if (ctx === undefined) {
+            ctx = {
+                binding,
+                state: "CLOSED",
+                wanted: true,
+                view: null,
+                fetched: [],
+                controlTarget: null,
+                remoteHave: [],
+                expected: [],
+                received: [],
+                early: [],
+                lastHave: 0,
+                lastKeyRequest: 0,
+                lastHeads: [],
+                controlStale: false,
+                missingEpochs: [],
+                offered: null,
+                snapshotPending: false,
+                covered: [],
+                unitsSinceSnapshot: 0,
+                lastRound: "",
+                refusal: null,
+                refusedAttempt: 0,
+                reopenAt: null,
+                offering: new Set(),
+                keysOffered: false,
+                rehosted: false,
+            };
+            this.#resources.set(key, ctx);
+        }
+        ctx.wanted = true;
+        // An explicit open asks the server again after a refusal.
+        ctx.refusal = null;
+        ctx.refusedAttempt = 0;
+        ctx.reopenAt = null;
+        if (this.#connection.state === "READY")
+            this.#serial(() => this.#sendOpen(ctx));
+    }
+    /** RESOURCE_CLOSE (§43): no more pushes; local state stays usable. */
+    close(resource) {
+        const ctx = this.#resources.get(toHex(resource));
+        if (ctx === undefined)
+            return;
+        ctx.wanted = false;
+        if (ctx.state !== "CLOSED" && this.#connection.state === "READY") {
+            this.#request({ kind: "close", resource: toHex(resource) }, createMessage("RESOURCE_CLOSE", { resourceId: resource }));
+        }
+        this.#move(ctx, "CLOSE");
+    }
+    /** RESOURCE_HOST (§39): asks the server to host a Resource from its exact Genesis bytes; resolves with the durability applied. */
+    host(genesis, credential) {
+        return new Promise((resolve, reject) => {
+            try {
+                this.#request({ kind: "host", genesis, resolve, reject }, createMessage("RESOURCE_HOST", {
+                    genesis,
+                    ...(credential === undefined ? {} : { credential }),
+                }));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+    }
+    /** Sends what the outbound queue has due for every Resource past KEY_SYNC (e.g. after a local write). */
+    flush() {
+        this.#serial(async () => {
+            for (const ctx of this.#resources.values())
+                await this.#flush(ctx);
+        });
+    }
+    /**
+     * The periodic work, on the caller's clock: heartbeat (§38), reconnect,
+     * anti-entropy DATA_HAVE for LIVE Resources (§69), Key Package retries,
+     * due outbound retries and debounced checkpoints.
+     */
+    tick(now) {
+        if (this.#connection.state === "DISCONNECTED") {
+            if (!this.#stopped && this.#reconnectAt !== null && now >= this.#reconnectAt) {
+                this.#reconnectAt = null;
+                this.#connection.connect();
+            }
+            return;
+        }
+        if (!this.#connection.tick(now))
+            return;
+        if (this.#connection.state === "READY")
+            this.#expireRequests(now);
+        this.#serial(async () => {
+            for (const ctx of this.#resources.values()) {
+                if (ctx.reopenAt !== null &&
+                    now >= ctx.reopenAt &&
+                    ctx.state === "CLOSED" &&
+                    ctx.wanted &&
+                    this.#connection.state === "READY")
+                    await this.#sendOpen(ctx);
+                if (ctx.state === "LIVE" && now - ctx.lastHave >= this.#antiEntropyMs)
+                    this.#sendHave(ctx, now);
+                if (ctx.state === "KEY_BLOCKED" && now - ctx.lastKeyRequest >= this.#antiEntropyMs)
+                    this.#requestKeys(ctx, now);
+                await this.#flush(ctx);
+                await ctx.binding.checkpointer?.maybeFlush(now);
+                if (ctx.state === "LIVE" &&
+                    ctx.binding.snapshot !== undefined &&
+                    this.#o.snapshotPolicy?.(ctx.binding.resourceId, ctx.unitsSinceSnapshot) === true)
+                    await this.#publish(ctx);
+            }
+        });
+    }
+    // -------------------------------------------------------------------------
+    // plumbing
+    #request(request, message) {
+        const key = toHex(message.messageId);
+        this.#requests.set(key, request);
+        this.#sentAt.set(key, this.#o.now());
+        this.#connection.send(message);
+    }
+    /**
+     * Requests unanswered for requestTimeoutMs on a live connection (§70: a
+     * lost request or reply): forgotten, and the step they belong to is
+     * issued again while its Resource is still in that phase. A late reply
+     * is harmless: units and records are idempotent.
+     */
+    #expireRequests(now) {
+        for (const key of this.#sentAt.keys())
+            if (!this.#requests.has(key))
+                this.#sentAt.delete(key);
+        const resend = new Map();
+        for (const [key, request] of this.#requests) {
+            const sent = this.#sentAt.get(key);
+            if (sent === undefined || now - sent < this.#requestTimeoutMs)
+                continue;
+            this.#requests.delete(key);
+            this.#sentAt.delete(key);
+            if (request.kind === "host") {
+                request.reject(new Error("RESOURCE_HOST got no answer within the request timeout"));
+                continue;
+            }
+            if (request.kind === "offer-data") {
+                // Offered again on the next DATA_HAVE (§68.1).
+                const ctx = this.#resources.get(request.resource);
+                for (const u of request.units)
+                    ctx?.offering.delete(u.id);
+                continue;
+            }
+            if (request.kind === "offer-control" || request.kind === "offer-keys")
+                continue;
+            if ("resource" in request)
+                resend.set(`${request.kind}:${request.resource}`, request);
+        }
+        for (const request of resend.values()) {
+            if (!("resource" in request))
+                continue;
+            const ctx = this.#resources.get(request.resource);
+            if (ctx === undefined)
+                continue;
+            if (request.kind === "open" && ctx.state === "OPENING") {
+                this.#move(ctx, "CLOSE");
+                this.#serial(() => this.#sendOpen(ctx));
+            }
+            else if (request.kind === "rehost" && ctx.state === "CLOSED") {
+                ctx.rehosted = false; // a lost answer: open again, which re-hosts again if needed
+                this.#serial(() => this.#sendOpen(ctx));
+            }
+            else if (request.kind === "control" && ctx.state === "CONTROL_SYNC") {
+                this.#serial(() => this.#controlRound(ctx, ctx.lastHeads));
+            }
+            else if (request.kind === "keys" && ctx.state === "KEY_SYNC") {
+                this.#requestKeys(ctx, now);
+            }
+            else if (request.kind === "snapshot" && ctx.snapshotPending) {
+                // A Snapshot is an optimization (§29.2): without it, replay the units.
+                this.#error("TIMEOUT", "the offered Snapshot did not arrive; replaying units instead", ctx.binding.resourceId);
+                this.#serial(() => this.#afterSnapshot(ctx));
+            }
+            else if (request.kind === "data-get" && ctx.state === "DATA_SYNC") {
+                ctx.lastRound = ""; // a lost reply is not a round without progress
+                ctx.expected = [];
+                this.#serial(() => this.#dataRound(ctx));
+            }
+        }
+    }
+    #move(ctx, event) {
+        const next = resourcePhaseTransition(ctx.state, event);
+        if (next === undefined)
+            return false;
+        ctx.state = next;
+        if (next === "LIVE") {
+            ctx.refusedAttempt = 0;
+            ctx.rehosted = false;
+        }
+        this.#emit({ type: "resource-state", resourceId: ctx.binding.resourceId, state: next });
+        if (next === "LIVE" && ctx.controlStale) {
+            ctx.controlStale = false;
+            this.#refreshControl(ctx);
+        }
+        else if (next === "CLOSED")
+            ctx.controlStale = false; // reopening syncs Control anyway
+        return true;
+    }
+    #ctx(resource) {
+        return this.#resources.get(toHex(resource));
+    }
+    #error(code, message, resourceId) {
+        this.#emit({
+            type: "error",
+            code,
+            message,
+            ...(resourceId === undefined ? {} : { resourceId }),
+        });
+    }
+    async #onReady(ready) {
+        this.#attempt = 0;
+        this.#maxMessageBytes = Number(ready.maxMessageBytes);
+        this.#o.outbound.session({
+            durability: ready.durability,
+            maxMessageBytes: ready.maxMessageBytes,
+        });
+        for (const ctx of this.#resources.values())
+            if (ctx.wanted)
+                await this.#sendOpen(ctx);
+    }
+    async #onClosed(reason) {
+        this.#emit({ type: "connection", state: "DISCONNECTED", reason });
+        for (const r of this.#requests.values())
+            if (r.kind === "host")
+                r.reject(new Error(`the connection closed before RESOURCE_HOSTED: ${reason}`));
+        this.#requests.clear();
+        this.#sentAt.clear();
+        for (const ctx of this.#resources.values()) {
+            this.#move(ctx, "CLOSE"); // §65, G-SM1: every Resource closes with the connection
+            ctx.view = null;
+            ctx.offering.clear();
+        }
+        await this.#o.outbound.connectionLost(iso(this.#o.now()));
+        if (this.#stopped)
+            return;
+        this.#attempt += 1;
+        const delay = (this.#o.reconnect ?? defaultReconnect)(this.#attempt);
+        this.#reconnectAt = delay === null ? null : this.#o.now() + delay;
+    }
+    async #sendOpen(ctx) {
+        if (ctx.state !== "CLOSED")
+            return;
+        const R = ctx.binding.resourceId;
+        const chain = await loadControlChain(this.#o.storage, R);
+        const heads = chain?.kind === "linear" ? [{ seq: chain.state.seq, recordId: chain.state.head }] : [];
+        const have = (await resourceSyncState(this.#o.storage, R)).have;
+        ctx.fetched = [];
+        ctx.controlTarget = null;
+        ctx.early = [];
+        ctx.reopenAt = null;
+        ctx.keysOffered = false;
+        this.#request({ kind: "open", resource: toHex(R) }, createMessage("RESOURCE_OPEN", {
+            resourceId: R,
+            heads,
+            haves: haveToLive(have),
+            flags: SUBSCRIBE_DATA_AND_CONTROL,
+        }));
+        this.#move(ctx, "OPEN");
+    }
+    // -------------------------------------------------------------------------
+    // inbound
+    async #onMessage(m) {
+        const request = m.correlationId === undefined ? undefined : this.#requests.get(toHex(m.correlationId));
+        switch (m.type) {
+            case "RESOURCE_HOSTED":
+                if (request?.kind === "host") {
+                    this.#requests.delete(toHex(m.correlationId));
+                    await this.#markHosted(parseControlRecord(request.genesis).payload.resourceId);
+                    request.resolve(m.body.durability);
+                }
+                else if (request?.kind === "rehost") {
+                    this.#requests.delete(toHex(m.correlationId));
+                    const ctx = this.#resources.get(request.resource);
+                    if (ctx === undefined)
+                        return;
+                    this.#emit({
+                        type: "rehost",
+                        resourceId: ctx.binding.resourceId,
+                        url: this.#o.url,
+                        outcome: "hosted",
+                    });
+                    if (ctx.wanted)
+                        await this.#sendOpen(ctx);
+                }
+                return;
+            case "RESOURCE_OPENED": {
+                const ctx = this.#ctx(m.body.resourceId);
+                if (ctx === undefined || ctx.state !== "OPENING")
+                    return;
+                this.#done(m);
+                ctx.remoteHave = normalizeLiveHaves(m.body.haves);
+                ctx.offered = m.body.snapshot ?? null;
+                await this.#markHosted(ctx.binding.resourceId);
+                this.#move(ctx, "OPENED");
+                // §68.1, §88 step 6: what the server lacks goes first, Control Records before units.
+                await this.#offerControl(ctx, m.body.heads);
+                await this.#offerData(ctx);
+                await this.#controlRound(ctx, m.body.heads);
+                return;
+            }
+            case "CONTROL_HAVE": {
+                const ctx = this.#ctx(m.body.resourceId);
+                this.#done(m);
+                if (ctx !== undefined && ctx.state === "LIVE")
+                    await this.#onControlHeads(ctx, m.body.heads);
+                return;
+            }
+            case "CONTROL_BATCH": {
+                const ctx = this.#ctx(m.body.resourceId);
+                if (ctx === undefined)
+                    return;
+                const solicited = request?.kind === "control";
+                if (!solicited && ctx.state === "LIVE")
+                    this.#move(ctx, "CONTROL_RECORD"); // a live push (§65)
+                if (ctx.state !== "CONTROL_SYNC") {
+                    // A push during key or data sync: validated in place.
+                    if (ctx.view !== null && !solicited)
+                        await this.#onControlRecords(ctx, m.body.objects, true);
+                    return;
+                }
+                await this.#onControlRecords(ctx, m.body.objects, solicited);
+                return;
+            }
+            case "KEY_PACKAGE_BATCH": {
+                const ctx = this.#ctx(m.body.resourceId);
+                this.#done(m);
+                if (ctx !== undefined)
+                    await this.#onKeyPackages(ctx, m.body.objects);
+                return;
+            }
+            case "DATA_BATCH": {
+                const ctx = this.#ctx(m.body.resourceId);
+                if (ctx !== undefined)
+                    await this.#onUnits(ctx, m.body.objects);
+                return;
+            }
+            case "SNAPSHOT": {
+                const ctx = this.#ctx(m.body.resourceId);
+                this.#done(m);
+                if (ctx?.snapshotPending)
+                    await this.#onSnapshot(ctx, m.body.snapshot);
+                return;
+            }
+            case "DATA_HAVE": {
+                const ctx = this.#ctx(m.body.resourceId);
+                this.#done(m);
+                if (ctx === undefined)
+                    return;
+                ctx.remoteHave = normalizeLiveHaves(m.body.haves);
+                await this.#offerData(ctx); // §68.1: both directions
+                if (ctx.state === "LIVE")
+                    await this.#dataRound(ctx);
+                return;
+            }
+            case "ACK":
+                if (request !== undefined) {
+                    this.#done(m);
+                    if (request.kind === "offer-data")
+                        for (const u of request.units)
+                            this.#resources.get(request.resource)?.offering.delete(u.id);
+                    return;
+                }
+                await this.#onAck(m);
+                return;
+            case "NACK":
+                if (request !== undefined) {
+                    this.#done(m);
+                    await this.#onRequestNack(request, m);
+                    return;
+                }
+                await this.#onNack(m);
+                return;
+            case "ERROR":
+                this.#error(`ERROR ${m.body.code}`, m.body.diagnostic ?? "the server reported an error");
+                return;
+            default:
+                return; // PONG and anything this client does not use
+        }
+    }
+    /** Forgets the request a reply answers (multi-batch replies keep it until the round ends). */
+    #done(m) {
+        if (m.correlationId !== undefined && m.type !== "CONTROL_BATCH" && m.type !== "DATA_BATCH")
+            this.#requests.delete(toHex(m.correlationId));
+    }
+    async #onRequestNack(request, m) {
+        // The §62 name (e.g. AUTHORIZATION_FAILED), so applications can explain it; unknown codes keep their number.
+        const code = NACK_NAME.get(m.body.code) ?? `NACK ${m.body.code}`;
+        if (request.kind === "offer-control" ||
+            request.kind === "offer-data" ||
+            request.kind === "offer-keys") {
+            this.#onOfferNack(request, code, m.body.diagnostic);
+            return;
+        }
+        if (request.kind === "open" && code === "RESOURCE_NOT_HOSTED") {
+            const ctx = this.#resources.get(request.resource);
+            if (ctx !== undefined && (await this.#rehost(ctx)))
+                return;
+        }
+        if (request.kind === "rehost") {
+            const ctx = this.#resources.get(request.resource);
+            if (ctx === undefined)
+                return;
+            this.#emit({
+                type: "rehost",
+                resourceId: ctx.binding.resourceId,
+                url: this.#o.url,
+                outcome: "refused",
+                code,
+            });
+            this.#error(code, `re-hosting refused${m.body.diagnostic ? `: ${m.body.diagnostic}` : ""}`, ctx.binding.resourceId);
+            // §41.1: stop re-hosting on this route and tell the user; never retried by itself.
+            this.#refuse(ctx, {
+                code,
+                url: this.#o.url,
+                request: "rehost",
+                ...(m.body.diagnostic === undefined ? {} : { diagnostic: m.body.diagnostic }),
+            });
+            return;
+        }
+        if (request.kind === "host") {
+            request.reject(new Error(`RESOURCE_HOST refused: NACK ${code}${m.body.diagnostic ? ` (${m.body.diagnostic})` : ""}`));
+            return;
+        }
+        const ctx = this.#resources.get(request.resource);
+        this.#error(code, `${request.kind} refused${m.body.diagnostic ? `: ${m.body.diagnostic}` : ""}`, ctx?.binding.resourceId);
+        if (ctx === undefined || request.kind === "close")
+            return;
+        if (TERMINAL_RESOURCE_CODES.has(code)) {
+            this.#refuse(ctx, {
+                code,
+                url: this.#o.url,
+                request: request.kind,
+                ...(m.body.diagnostic === undefined ? {} : { diagnostic: m.body.diagnostic }),
+            });
+            return;
+        }
+        if (request.kind === "keys")
+            this.#keyBlocked(ctx);
+        // A Snapshot is an optimization (§29.2): without it, replay the units.
+        else if (request.kind === "snapshot") {
+            if (ctx.snapshotPending)
+                this.#serial(() => this.#afterSnapshot(ctx));
+        }
+        // A transient refusal of the open or of a sync round: the Resource
+        // would otherwise sit there until the next reconnect. Start over after
+        // a backoff. A refused DATA_HAVE is simply sent again (§69).
+        else if (request.kind !== "data-have")
+            this.#retryLater(ctx);
+    }
+    /** The server refused the Resource for good: CLOSED, not reopened until open() asks again. */
+    #refuse(ctx, refusal) {
+        const subscribed = ctx.state !== "CLOSED" && ctx.state !== "OPENING";
+        ctx.wanted = false;
+        ctx.reopenAt = null;
+        ctx.refusal = Object.freeze(refusal);
+        // Stop any pushes the server may still send for it (§43).
+        if (subscribed && this.#connection.state === "READY")
+            this.#request({ kind: "close", resource: toHex(ctx.binding.resourceId) }, createMessage("RESOURCE_CLOSE", { resourceId: ctx.binding.resourceId }));
+        this.#move(ctx, "CLOSE");
+        this.#emit({ type: "resource-refused", resourceId: ctx.binding.resourceId, refusal });
+    }
+    /** CLOSED now, opened again after the ReconnectPolicy's delay for this Resource's attempt. */
+    #retryLater(ctx) {
+        if (ctx.state !== "CLOSED" && ctx.state !== "OPENING" && this.#connection.state === "READY")
+            this.#request({ kind: "close", resource: toHex(ctx.binding.resourceId) }, createMessage("RESOURCE_CLOSE", { resourceId: ctx.binding.resourceId }));
+        this.#move(ctx, "CLOSE");
+        ctx.refusedAttempt += 1;
+        const delay = (this.#o.reconnect ?? defaultReconnect)(ctx.refusedAttempt);
+        ctx.reopenAt = delay === null ? null : this.#o.now() + delay;
+    }
+    // -------------------------------------------------------------------------
+    // Control (§44-§47, §67)
+    async #onControlHeads(ctx, heads) {
+        const chain = await loadControlChain(this.#o.storage, ctx.binding.resourceId);
+        const local = chain?.kind === "linear" ? localControlOf(chain) : null;
+        const plan = planControlSync(local, heads);
+        if (plan.kind === "peer-behind")
+            await this.#offerControl(ctx, heads); // §68.1
+        if (plan.kind === "in-sync" || plan.kind === "peer-behind" || plan.kind === "peer-empty")
+            return;
+        this.#move(ctx, "CONTROL_RECORD");
+        await this.#controlRound(ctx, heads);
+    }
+    async #controlRound(ctx, heads) {
+        const R = ctx.binding.resourceId;
+        const chain = await loadControlChain(this.#o.storage, R);
+        const local = chain?.kind === "linear" ? localControlOf(chain) : null;
+        const plan = planControlSync(local, heads);
+        ctx.fetched = [];
+        ctx.lastHeads = heads;
+        if (plan.kind === "fetch" || plan.kind === "fork") {
+            const range = plan.kind === "fetch" ? plan : plan.fetch;
+            ctx.controlTarget = range.end;
+            this.#request({ kind: "control", resource: toHex(R) }, createMessage("CONTROL_GET", { resourceId: R, start: range.start, end: range.end }));
+            return;
+        }
+        if (chain?.kind !== "linear") {
+            this.#error("INVALID_CONTROL_CHAIN", "no valid local Control Chain and nothing to fetch", R);
+            return;
+        }
+        await this.#controlComplete(ctx, chain);
+    }
+    async #onControlRecords(ctx, records, solicited) {
+        const R = ctx.binding.resourceId;
+        const stored = await loadControlChain(this.#o.storage, R);
+        const storedRecords = stored?.kind === "linear" ? stored.records.map((r) => r.signed.bytes) : [];
+        const localSeq = stored?.kind === "linear" ? stored.state.seq : -1n;
+        if (!solicited) {
+            // A pushed record that does not continue our chain: fetch the gap first.
+            const seqs = records.map((r) => parseControlRecord(r).payload.controlSeq);
+            const min = seqs.reduce((a, b) => (b < a ? b : a), seqs[0] ?? 0n);
+            const max = seqs.reduce((a, b) => (b > a ? b : a), seqs[0] ?? 0n);
+            ctx.controlTarget = max;
+            if (min > localSeq + 1n) {
+                ctx.fetched = [...records];
+                this.#request({ kind: "control", resource: toHex(R) }, createMessage("CONTROL_GET", { resourceId: R, start: localSeq + 1n, end: max }));
+                return;
+            }
+        }
+        ctx.fetched.push(...records);
+        const byId = new Map();
+        for (const b of [...storedRecords, ...ctx.fetched])
+            byId.set(toHex(parseControlRecord(b).signed.id), b);
+        const ordered = [...byId.values()]
+            .map((b) => ({ b, p: parseControlRecord(b) }))
+            .sort((x, y) => x.p.payload.controlSeq < y.p.payload.controlSeq
+            ? -1
+            : x.p.payload.controlSeq > y.p.payload.controlSeq
+                ? 1
+                : toHex(x.p.signed.id) < toHex(y.p.signed.id)
+                    ? -1
+                    : 1)
+            .map((x) => x.b);
+        const result = validateControlChain(ordered);
+        if (result.kind === "conflict") {
+            await saveControlConflict(this.#o.storage, R, result);
+            if (ctx.state === "CONTROL_SYNC")
+                this.#move(ctx, "FORK");
+            this.#emit({ type: "control-conflict", resourceId: R, heads: result.competing });
+            return;
+        }
+        if (result.kind === "invalid") {
+            // Several replies may still be on their way; an incomplete chain is not yet invalid.
+            if (result.problem === "MALFORMED" ||
+                result.problem === "UNSUPPORTED_TYPE" ||
+                ctx.controlTarget === null) {
+                this.#error(result.wireCode, `the server's Control Records do not validate (${result.problem})`, R);
+            }
+            return;
+        }
+        if (ctx.controlTarget !== null && result.state.seq < ctx.controlTarget)
+            return; // more batches to come
+        const saved = await saveControlChain(this.#o.storage, result, stored?.kind === "linear" ? stored.state.head : null);
+        if (!saved.ok) {
+            this.#error("CONTROL_HEAD_MISMATCH", "the stored Control Head moved during sync", R);
+            return;
+        }
+        for (const [k, r] of this.#requests)
+            if (r.kind === "control" && r.resource === toHex(R))
+                this.#requests.delete(k);
+        ctx.fetched = [];
+        ctx.controlTarget = null;
+        await this.#controlComplete(ctx, result, stored?.kind === "linear" ? stored : null);
+    }
+    /** A newly validated Control state: reconcile epochs (G-EP7, §88 step 7), release queued puts, then keys. */
+    async #controlComplete(ctx, chain, previous = null) {
+        const R = ctx.binding.resourceId;
+        const before = previous ?? ctx.view;
+        ctx.view = chain;
+        // DEKs we already hold for epochs the saved chain now has (our own
+        // rotation, or a package that came before the row): no request needed.
+        await adoptStoredDeks(this.#o.storage, this.#o.secrets, chain);
+        const epochsChanged = before === null ||
+            [...chain.state.epochs.values()].some((e) => {
+                const old = before.state.epochs.get(String(e.epoch));
+                return old === undefined || (old.closedBy === null) !== (e.closedBy === null);
+            });
+        if (epochsChanged) {
+            const applied = await ctx.binding.applier.reconcileEpochs(chain);
+            const outbound = await this.#o.outbound.reconcileEpochs(chain);
+            if (applied.snapshotDropped)
+                ctx.covered = []; // SNAP-EP: covered units are fetched again
+            if (applied.excluded.length > 0 || outbound.length > 0 || applied.snapshotDropped) {
+                ctx.binding.checkpointer?.noteChange();
+                this.#emit({ type: "epoch-reconciled", resourceId: R, applied, outbound });
+            }
+        }
+        await this.#o.outbound.controlSynced(R);
+        if (ctx.state === "CONTROL_SYNC") {
+            this.#move(ctx, "CONTROL_COMPLETE");
+            this.#requestKeys(ctx, this.#o.now());
+        }
+        else if (ctx.state === "KEY_BLOCKED" && epochsChanged) {
+            this.#requestKeys(ctx, this.#o.now());
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Keys (§52, §53, §66 step 2)
+    async #epochsWithoutDek(ctx) {
+        if (ctx.view !== null)
+            await adoptStoredDeks(this.#o.storage, this.#o.secrets, ctx.view);
+        const rows = await this.#o.storage.control.epochs(ctx.binding.resourceId);
+        const out = [];
+        for (const e of ctx.view?.state.epochs.values() ?? []) {
+            const row = rows.find((r) => r.epoch === e.epoch);
+            if (row?.dekRef == null || (await this.#o.secrets.get(row.dekRef)) === undefined)
+                out.push(dataEpoch(e.epoch));
+        }
+        return out;
+    }
+    #requestKeys(ctx, now) {
+        this.#serial(async () => {
+            if (ctx.view === null || (ctx.state !== "KEY_SYNC" && ctx.state !== "KEY_BLOCKED"))
+                return;
+            const missing = await this.#epochsWithoutDek(ctx);
+            if (missing.length === 0) {
+                if (ctx.state === "KEY_BLOCKED")
+                    this.#move(ctx, "PACKAGE_ARRIVED");
+                this.#move(ctx, "DEK_AVAILABLE");
+                await this.#startData(ctx);
+                return;
+            }
+            ctx.missingEpochs = missing;
+            ctx.lastKeyRequest = now;
+            const R = ctx.binding.resourceId;
+            this.#request({ kind: "keys", resource: toHex(R) }, createMessage("KEY_PACKAGE_GET", {
+                resourceId: R,
+                recipient: this.#o.signer.descriptor.principalId,
+                // §52: at most 256 epochs per request, the newest first: the
+                // current epoch's DEK unblocks the Resource; older ones only let
+                // their units apply, and a later round asks for them.
+                epochs: missing.slice(-256),
+            }));
+        });
+    }
+    async #onKeyPackages(ctx, packages) {
+        const view = ctx.view;
+        if (view === null)
+            return;
+        const R = ctx.binding.resourceId;
+        const recipient = { descriptor: this.#o.signer.descriptor, agreement: this.#o.agreement };
+        for (const bytes of packages) {
+            const r = await receiveKeyPackage(view, bytes, recipient);
+            if (r.kind !== "opened") {
+                this.#error(r.kind === "rejected" ? r.wireCode : r.code, `a Key Package was not used (${r.kind})`, R);
+                continue;
+            }
+            // Secret first, then the row that references it (LFCP-034). The
+            // package itself is kept while we keep the Resource (§86), to
+            // re-supply a server that lost it (§68.1).
+            const ref = dekSecretRef(R, r.epoch);
+            await this.#o.secrets.put(ref, exportSecretKeyBytes(r.dek));
+            const parsed = parseKeyPackage(bytes);
+            const writes = [
+                {
+                    op: "put-key-package",
+                    row: {
+                        packageId: hash32(parsed.signed.id),
+                        resourceId: R,
+                        dataEpoch: parsed.payload.dataEpoch,
+                        recipient: parsed.payload.recipient,
+                        sender: parsed.payload.sender,
+                        bytes: parsed.signed.bytes,
+                    },
+                },
+            ];
+            const row = (await this.#o.storage.control.epochs(R)).find((e) => e.epoch === r.epoch);
+            if (row !== undefined) {
+                const next = { ...row, dekRef: ref };
+                writes.push({ op: "put-epoch", resourceId: R, epoch: next });
+            }
+            await this.#o.storage.commit(writes);
+        }
+        const missing = await this.#epochsWithoutDek(ctx);
+        const current = view.state.epoch.epoch;
+        if (missing.some((e) => e === current)) {
+            this.#keyBlocked(ctx);
+            return;
+        }
+        if (missing.length > 0)
+            this.#emit({ type: "key-blocked", resourceId: R, epochs: missing }); // older epochs: their units wait
+        if (ctx.state === "KEY_BLOCKED")
+            this.#move(ctx, "PACKAGE_ARRIVED");
+        if (ctx.state === "KEY_SYNC") {
+            this.#move(ctx, "DEK_AVAILABLE");
+            await this.#startData(ctx);
+        }
+    }
+    #keyBlocked(ctx) {
+        if (ctx.state === "KEY_SYNC")
+            this.#move(ctx, "KEY_UNAVAILABLE");
+        this.#emit({
+            type: "key-blocked",
+            resourceId: ctx.binding.resourceId,
+            epochs: ctx.missingEpochs,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Data (§48-§51, §68, §69)
+    async #startData(ctx) {
+        // Accepted units on disk that the profile state lacks (a crash before
+        // the checkpoint caught up) are applied again before any new unit.
+        if (ctx.view !== null) {
+            const R = ctx.binding.resourceId;
+            // Snapshots that crashed the engine twice are never loaded again.
+            for (const item of await this.#snapshots.recover(R))
+                this.#error("INVALID_AUTOMERGE_BYTES", `Snapshot ${item.slice("snapshot:".length)} crashed the profile engine twice; it is not loaded again on this device`, R);
+            const r = await ctx.binding.applier.replayStored(ctx.view);
+            if (r.replayed.length > 0 || r.skipped.length > 0 || r.crashed.length > 0) {
+                ctx.binding.checkpointer?.noteChange();
+                this.#emit({ type: "replayed", resourceId: R, ...r });
+            }
+            for (const unitId of r.crashed)
+                this.#error("INVALID_AUTOMERGE_BYTES", `Data Unit ${toHex(unitId)} crashed the profile engine twice; it is quarantined on this device`, R);
+        }
+        await this.#flush(ctx); // §88 step 6: upload locally queued valid units
+        if (await this.#snapshotUseful(ctx)) {
+            // §66 step 3: the preferred Snapshot first, then the units beyond it.
+            const R = ctx.binding.resourceId;
+            ctx.snapshotPending = true;
+            this.#request({ kind: "snapshot", resource: toHex(R) }, createMessage("SNAPSHOT_GET", {
+                resourceId: R,
+                snapshotId: ctx.offered.snapshotId,
+            }));
+            return;
+        }
+        await this.#afterSnapshot(ctx);
+    }
+    async #afterSnapshot(ctx) {
+        ctx.snapshotPending = false;
+        const early = ctx.early;
+        ctx.early = [];
+        await this.#dataRound(ctx);
+        if (early.length > 0)
+            await this.#onUnits(ctx, early);
+    }
+    /** The offered Snapshot holds units we lack, we can load it, and we did not load it before. */
+    async #snapshotUseful(ctx) {
+        const offered = ctx.offered;
+        if (offered === null || ctx.binding.snapshot === undefined)
+            return false;
+        if ((await this.#o.storage.snapshots.get(offered.snapshotId)) !== undefined)
+            return false;
+        const R = ctx.binding.resourceId;
+        await this.#snapshots.recover(R);
+        if (this.#snapshots.suspicion(R, snapshotItem(offered.snapshotId)) === 2)
+            return false;
+        const local = (await resourceSyncState(this.#o.storage, ctx.binding.resourceId)).have;
+        return missingFrom(local, normalizeLiveHaves(offered.frontier)).length > 0;
+    }
+    async #onSnapshot(ctx, bytes) {
+        const R = ctx.binding.resourceId;
+        const view = ctx.view;
+        const binding = ctx.binding.snapshot;
+        if (view !== null && binding !== undefined) {
+            // Decode and load under the crash-loop breaker; a trap in decode is
+            // rethrown, not reported as the Snapshot's local failure.
+            let trap;
+            const codec = binding.codec;
+            const guarded = {
+                dataProfile: codec.dataProfile,
+                encode: (v) => codec.encode(v),
+                decode: (plaintext) => {
+                    try {
+                        return codec.decode(plaintext);
+                    }
+                    catch (e) {
+                        if (isEngineTrap(e))
+                            trap = e;
+                        throw e;
+                    }
+                },
+            };
+            const r = await this.#snapshots.run(R, [snapshotItem(sha256(bytes))], async () => {
+                const received = await receiveSnapshot(view, bytes, {
+                    dek: dekResolver(this.#o.storage, this.#o.secrets, R),
+                    profile: guarded,
+                });
+                if (trap !== undefined)
+                    throw trap;
+                if (received.kind === "accepted")
+                    binding.load(received.value);
+                return received;
+            });
+            if (r.kind === "accepted") {
+                const frontier = encode(canonicalFrontierToCbor(r.frontier));
+                await this.#o.storage.commit([
+                    {
+                        op: "put-snapshot",
+                        row: {
+                            snapshotId: r.snapshotId,
+                            resourceId: R,
+                            dataEpoch: r.epoch,
+                            publisher: r.publisher,
+                            snapshotSeq: r.seq,
+                            frontier,
+                            bytes,
+                        },
+                    },
+                ]);
+                ctx.binding.checkpointer?.noteChange();
+                this.#emit({
+                    type: "snapshot-loaded",
+                    resourceId: R,
+                    snapshotId: r.snapshotId,
+                    frontier: r.frontier,
+                });
+            }
+            else {
+                const code = r.kind === "local-failure" ? r.reason : r.wireCode;
+                this.#error(code, `the offered Snapshot was not loaded (${r.kind}); replaying units instead`, R);
+            }
+        }
+        await this.#afterSnapshot(ctx);
+    }
+    /**
+     * Publishes a Snapshot of the Resource's current state (§29): its frontier
+     * is every merged unit and every stored Snapshot's frontier, so a client
+     * that loads it never skips content the state does not hold. Queued and
+     * sent like any object; returns its ID.
+     */
+    async publishSnapshot(resource) {
+        const ctx = this.#resources.get(toHex(resource));
+        if (ctx === undefined)
+            throw new LfcpError("UNSUPPORTED_VALUE", "the Resource is not open here");
+        let id;
+        await new Promise((resolve, reject) => this.#serial(async () => {
+            try {
+                id = await this.#publish(ctx);
+                resolve();
+            }
+            catch (e) {
+                reject(e);
+            }
+        }));
+        return id;
+    }
+    async #publish(ctx) {
+        const R = ctx.binding.resourceId;
+        const binding = ctx.binding.snapshot;
+        const view = ctx.view;
+        if (binding === undefined || view === null)
+            throw new LfcpError("UNSUPPORTED_VALUE", "no Snapshot binding, or the Control Chain is not synchronized");
+        const dek = await dekResolver(this.#o.storage, this.#o.secrets, R)(view.state.epoch.epoch);
+        if (dek === undefined)
+            throw new LfcpError("UNSUPPORTED_VALUE", "no DEK for the current epoch");
+        let frontier = await snapshotFrontier(this.#o.storage, R);
+        for (const u of await this.#o.storage.dataUnits.withStatus(R, "merged"))
+            if (u.accepted)
+                frontier = addSequence(frontier, u.actor, u.actorSeq);
+        const created = await createQueuedSnapshot(this.#o.storage, {
+            view,
+            controlHead: view.state.head,
+            publisher: this.#o.signer,
+            dek,
+            frontier: haveToLive(frontier),
+            profile: binding.codec,
+            value: binding.current(),
+        });
+        ctx.unitsSinceSnapshot = 0;
+        this.#emit({ type: "snapshot-published", resourceId: R, snapshotId: created.snapshotId });
+        await this.#flush(ctx);
+        return created.snapshotId;
+    }
+    async #dataRound(ctx) {
+        const R = ctx.binding.resourceId;
+        ctx.covered = await snapshotFrontier(this.#o.storage, R);
+        const local = (await resourceSyncState(this.#o.storage, R)).have;
+        // Beyond a loaded Snapshot's frontier (missingAfter: `local` includes it),
+        // plus each actor's last covered unit, so the next one links (§26.2).
+        const missing = [...(await this.#boundary(ctx)), ...missingFrom(local, ctx.remoteHave)];
+        if (missing.length === 0) {
+            ctx.lastRound = "";
+            if (ctx.state === "DATA_SYNC")
+                this.#move(ctx, "FRONTIER_REACHED");
+            ctx.expected = [];
+            ctx.received = [];
+            return;
+        }
+        // A round that asks again for exactly what the last one asked for made no
+        // progress (e.g. the server lacks units it announced): stop instead of
+        // looping; periodic anti-entropy tries again.
+        const key = missing.map((r) => `${toHex(r.actor)}:${r.start}-${r.end}`).join(",");
+        if (key === ctx.lastRound) {
+            ctx.lastRound = "";
+            this.#error("NO_PROGRESS", "a data round fetched nothing new; will retry on the next DATA_HAVE", R);
+            if (ctx.state === "DATA_SYNC")
+                this.#move(ctx, "FRONTIER_REACHED");
+            ctx.expected = [];
+            ctx.received = [];
+            return;
+        }
+        ctx.lastRound = key;
+        if (ctx.state === "LIVE")
+            this.#move(ctx, "MISSING_RANGES");
+        // Ranges stay intervals: the work is bounded by their number, never by
+        // their span (a Have may announce up to 2^64 - 1 sequences).
+        let expected = [];
+        for (const r of missing)
+            expected = addRange(expected, r.actor, r.start, r.end);
+        ctx.expected = expected;
+        ctx.received = [];
+        for (const batch of batchDataRanges(missing))
+            this.#request({ kind: "data-get", resource: toHex(R) }, createMessage("DATA_GET", {
+                resourceId: R,
+                ranges: batch.map((r) => ({ actor: r.actor, start: r.start, end: r.end })),
+            }));
+    }
+    /** The last unit of each actor run a stored Snapshot covers, when we do not hold it yet. */
+    async #boundary(ctx) {
+        const R = ctx.binding.resourceId;
+        const out = [];
+        for (const h of ctx.covered)
+            for (const seq of [
+                ...(h.contiguous > 0n ? [h.contiguous] : []),
+                ...h.extras.map(([, end]) => end),
+            ]) {
+                if (!hasSequence(ctx.remoteHave, h.principalId, seq))
+                    continue;
+                if ((await this.#o.storage.dataUnits.acceptedAt(R, h.principalId, actorSequence(seq))) !==
+                    undefined)
+                    continue;
+                out.push({ actor: h.principalId, start: seq, end: seq });
+            }
+        return out;
+    }
+    async #onUnits(ctx, units) {
+        const view = ctx.view;
+        if (view === null ||
+            ctx.state === "KEY_SYNC" ||
+            ctx.state === "KEY_BLOCKED" ||
+            ctx.state === "CONTROL_SYNC" ||
+            ctx.snapshotPending) {
+            ctx.early.push(...units);
+            return;
+        }
+        const R = ctx.binding.resourceId;
+        let changed = false;
+        let needControl = false;
+        // Units a loaded Snapshot covers are accepted as covered, one by one;
+        // runs of the others go to the applier together (receiveBatch), so the
+        // profile merges a catch-up at once.
+        const outcomes = [];
+        let run = [];
+        const flushRun = async () => {
+            if (run.length > 0)
+                outcomes.push(...(await ctx.binding.applier.receiveBatch(view, run)));
+            run = [];
+        };
+        for (const bytes of units) {
+            let covered = false;
+            try {
+                const p = parseDataUnit(bytes).payload;
+                ctx.received = addSequence(ctx.received, p.actor, p.actorSeq);
+                covered = hasSequence(ctx.covered, p.actor, p.actorSeq);
+            }
+            catch {
+                // malformed: the applier reports it
+            }
+            if (!covered) {
+                run.push(bytes);
+                continue;
+            }
+            await flushRun();
+            outcomes.push(await ctx.binding.applier.acceptCovered(view, bytes));
+        }
+        await flushRun();
+        for (const outcome of outcomes) {
+            if (outcome.kind === "applied" || outcome.kind === "profile-pending") {
+                changed = true;
+                ctx.unitsSinceSnapshot += 1;
+            }
+            if (outcome.kind === "rejected" && outcome.wireCode === "MISSING_DEPENDENCY")
+                needControl = true;
+            this.#emit({ type: "unit", resourceId: R, outcome });
+            // Held units this one released (§26.2): their outcomes too.
+            const released = "released" in outcome ? outcome.released : [];
+            for (const r of released) {
+                if (r.kind === "applied" || r.kind === "profile-pending")
+                    changed = true;
+                this.#emit({ type: "unit", resourceId: R, outcome: r });
+            }
+        }
+        if (changed)
+            ctx.binding.checkpointer?.noteChange();
+        if (needControl)
+            this.#refreshControl(ctx);
+        if (ctx.state === "DATA_SYNC" &&
+            ctx.expected.length > 0 &&
+            missingFrom(ctx.received, ctx.expected).length === 0) {
+            ctx.expected = [];
+            await this.#dataRound(ctx);
+        }
+    }
+    #sendHave(ctx, now) {
+        ctx.lastHave = now;
+        this.#serial(async () => {
+            const R = ctx.binding.resourceId;
+            const have = (await resourceSyncState(this.#o.storage, R)).have;
+            this.#request({ kind: "data-have", resource: toHex(R) }, createMessage("DATA_HAVE", { resourceId: R, haves: haveToLive(have) }));
+        });
+    }
+    #refreshControl(ctx) {
+        this.#serial(async () => {
+            const R = ctx.binding.resourceId;
+            const chain = await loadControlChain(this.#o.storage, R);
+            const heads = chain?.kind === "linear" ? [{ seq: chain.state.seq, recordId: chain.state.head }] : [];
+            this.#request({ kind: "control", resource: toHex(R) }, createMessage("CONTROL_HAVE", { resourceId: R, heads }));
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Outbound (§51, §54, §57, §59, §60, §88)
+    async #flush(ctx) {
+        if (this.#connection.state !== "READY")
+            return;
+        if (ctx.state !== "DATA_SYNC" && ctx.state !== "LIVE")
+            return;
+        const messages = await this.#o.outbound.next(ctx.binding.resourceId, iso(this.#o.now()));
+        for (const m of messages)
+            this.#connection.sendEncoded(m.bytes);
+    }
+    async #onAck(m) {
+        const outcome = await this.#o.outbound.onAck(m, iso(this.#o.now()));
+        this.#emit({ type: "ack", outcome });
+        // Our own Control Record was committed: catch up, since the server does not push it back to us.
+        if (m.body.requestType === MESSAGE_TYPE.CONTROL_PUT && outcome.acked.length > 0)
+            for (const ctx of this.#resources.values())
+                if (ctx.state === "LIVE")
+                    this.#refreshControl(ctx);
+                else
+                    ctx.controlStale = true;
+    }
+    async #onNack(m) {
+        const outcome = await this.#o.outbound.onNack(m, iso(this.#o.now()));
+        this.#emit({ type: "nack", outcome });
+        if (outcome.kind === "needs-control-sync")
+            for (const ctx of this.#resources.values())
+                if (ctx.state === "LIVE")
+                    this.#refreshControl(ctx);
+        // §51.1: the server lost what our unit names. Its DATA_HAVE answer
+        // starts the offer (§68.1), which releases the held items.
+        if (outcome.kind === "needs-offer") {
+            const ctx = this.#ctx(outcome.resourceId);
+            if (ctx !== undefined && (ctx.state === "LIVE" || ctx.state === "DATA_SYNC"))
+                this.#sendHave(ctx, this.#o.now());
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Offering what the server lacks (§68.1) and re-hosting (§41.1)
+    async #markHosted(resource) {
+        const key = hostedMark(resource, this.#o.url);
+        if ((await this.#o.storage.localMarks.get(key)) !== undefined)
+            return;
+        await this.#o.storage.commit([{ op: "put-local-mark", key, value: "1" }]);
+    }
+    /**
+     * §41.1: RESOURCE_NOT_HOSTED from a route in the Resource's route set that
+     * hosted or opened it for us before: host it again from the exact Genesis
+     * bytes, then open it. False when re-hosting is not allowed here.
+     */
+    async #rehost(ctx) {
+        if (ctx.rehosted || this.#connection.state !== "READY")
+            return false;
+        const R = ctx.binding.resourceId;
+        const chain = await loadControlChain(this.#o.storage, R);
+        if (chain?.kind !== "linear")
+            return false;
+        const route = chain.state.route;
+        const url = this.#o.url;
+        if (!route.endpoints.some((e) => e.url === url) && route.coordinatorUrl !== url)
+            return false;
+        if ((await this.#o.storage.localMarks.get(hostedMark(R, url))) === undefined)
+            return false;
+        const genesis = chain.records[0];
+        if (genesis === undefined || genesis.payload.controlSeq !== 0n)
+            return false;
+        ctx.rehosted = true;
+        this.#move(ctx, "CLOSE");
+        this.#request({ kind: "rehost", resource: toHex(R) }, createMessage("RESOURCE_HOST", { genesis: genesis.signed.bytes }));
+        return true;
+    }
+    /**
+     * §68.1: the server's Control Head is a record we hold below our own head:
+     * upload the records above it, one CONTROL_PUT each, in order, each
+     * expecting the record before it.
+     */
+    async #offerControl(ctx, heads) {
+        if (this.#connection.state !== "READY")
+            return;
+        const R = ctx.binding.resourceId;
+        const chain = await loadControlChain(this.#o.storage, R);
+        if (chain?.kind !== "linear")
+            return;
+        const plan = planControlSync(localControlOf(chain), heads);
+        if (plan.kind !== "peer-behind")
+            return;
+        for (const record of chain.records) {
+            if (record.payload.controlSeq <= plan.peerSeq)
+                continue;
+            const previous = record.payload.prevControlId;
+            if (previous === null)
+                continue;
+            this.#request({ kind: "offer-control", resource: toHex(R) }, createMessage("CONTROL_PUT", {
+                resourceId: R,
+                expectedHead: previous,
+                record: record.signed.bytes,
+            }));
+        }
+        await this.#offerKeys(ctx);
+    }
+    /**
+     * §68.1: the accepted units the server's Have Vector lacks, ours and
+     * other actors' (relay), per actor in ascending sequence. Units still in
+     * our outbound queue go through it instead. Then the queued items held
+     * for UNKNOWN_PREVIOUS are released behind them.
+     */
+    async #offerData(ctx) {
+        if (this.#connection.state !== "READY")
+            return;
+        const R = ctx.binding.resourceId;
+        const queued = new Set((await this.#o.storage.outbound.list(R)).map((o) => toHex(o.itemId)));
+        let local = [];
+        for (const status of OFFERABLE)
+            for (const u of await this.#o.storage.dataUnits.withStatus(R, status))
+                if (u.accepted)
+                    local = addSequence(local, u.actor, u.actorSeq);
+        const { offer } = haveDifference(local, ctx.remoteHave);
+        const offerable = new Set(OFFERABLE);
+        let sent = 0;
+        for (const range of offer) {
+            const units = (await this.#o.storage.dataUnits.range(R, range.actor, actorSequence(range.start), actorSequence(range.end))).filter((u) => u.accepted &&
+                offerable.has(u.status) &&
+                !queued.has(toHex(u.unitId)) &&
+                !ctx.offering.has(toHex(u.unitId)));
+            sent += units.length;
+            this.#offerUnits(ctx, units.map((u) => ({ id: toHex(u.unitId), bytes: u.bytes })));
+        }
+        await this.#o.outbound.offered(R);
+        if (sent > 0)
+            await this.#offerKeys(ctx);
+        await this.#flush(ctx);
+    }
+    /** DATA_PUTs of one actor's units in order, within the message size and object limits. */
+    #offerUnits(ctx, units) {
+        const R = ctx.binding.resourceId;
+        const limit = this.#maxMessageBytes - 1024;
+        let batch = [];
+        let size = 0;
+        const send = () => {
+            if (batch.length === 0)
+                return;
+            for (const u of batch)
+                ctx.offering.add(u.id);
+            this.#request({ kind: "offer-data", resource: toHex(R), units: batch }, createMessage("DATA_PUT", { resourceId: R, objects: batch.map((u) => u.bytes) }));
+            batch = [];
+            size = 0;
+        };
+        for (const u of units) {
+            if (batch.length >= OFFER_BATCH || size + u.bytes.length > limit)
+                send();
+            batch.push(u);
+            size += u.bytes.length;
+        }
+        send();
+    }
+    /**
+     * §68.1, §86: a server that lacked Control Records or units may have lost
+     * Key Packages too: the ones we sent or that are addressed to us are
+     * uploaded again, once per open. A package the server stores is answered
+     * as the first time (§70).
+     */
+    async #offerKeys(ctx) {
+        if (ctx.keysOffered || this.#connection.state !== "READY")
+            return;
+        ctx.keysOffered = true;
+        const R = ctx.binding.resourceId;
+        const me = toHex(this.#o.signer.descriptor.principalId);
+        const packages = (await this.#o.storage.keyPackages.list(R)).filter((k) => toHex(k.sender) === me || toHex(k.recipient) === me);
+        const limit = this.#maxMessageBytes - 1024;
+        for (let i = 0; i < packages.length;) {
+            const batch = [];
+            let size = 0;
+            while (i < packages.length && batch.length < OFFER_BATCH) {
+                const bytes = packages[i].bytes;
+                if (batch.length > 0 && size + bytes.length > limit)
+                    break;
+                batch.push(bytes);
+                size += bytes.length;
+                i++;
+            }
+            this.#request({ kind: "offer-keys", resource: toHex(R) }, createMessage("KEY_PACKAGE_PUT", { resourceId: R, objects: batch }));
+        }
+    }
+    /**
+     * A refused offer. A DATA_PUT is all-or-nothing (§51): each unit of a
+     * refused batch is offered again alone. ACTOR_EQUIVOCATION for a relayed
+     * unit is expected when the server holds the other unit of a pair, and
+     * UNKNOWN_PREVIOUS when it lacks an earlier unit we do not hold either:
+     * neither is an alarm. A refused Control Record (the server's head moved)
+     * is caught up by the next Control round.
+     */
+    #onOfferNack(request, code, diagnostic) {
+        const ctx = this.#resources.get(request.resource);
+        if (ctx === undefined)
+            return;
+        if (request.kind === "offer-data") {
+            for (const u of request.units)
+                ctx.offering.delete(u.id);
+            if (request.units.length > 1) {
+                for (const u of request.units)
+                    this.#offerUnits(ctx, [u]);
+                return;
+            }
+            if (code === "ACTOR_EQUIVOCATION" || code === "UNKNOWN_PREVIOUS")
+                return;
+        }
+        if (request.kind === "offer-control" && code === "CONTROL_HEAD_MISMATCH")
+            return;
+        this.#error(code, `an object offered to the server was refused (§68.1)${diagnostic ? `: ${diagnostic}` : ""}`, ctx.binding.resourceId);
+    }
+}
+/**
+ * A thin timer driver for SyncClient: calls tick(now) every `intervalMs`
+ * with the given clock and timer functions (setInterval/clearInterval in
+ * production). Returns the stop function. The core never sets timers
+ * itself; this is the one explicit place that does.
+ */
+export function startSyncDriver(client, timers, intervalMs = 1000) {
+    const handle = timers.setInterval(() => client.tick(timers.now()), intervalMs);
+    return () => timers.clearInterval(handle);
+}
+//# sourceMappingURL=sync-client.js.map