@openlfcp/client 0.1.0-rc.1

package/dist/sync-client.js

@@ -0,0 +1,1032 @@
+import { actorSequence, dataEpoch, 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, localControlOf, MESSAGE_TYPE, missingFrom, normalizeLiveHaves, parseControlRecord, parseDataUnit, 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));
+const NACK_NAME = new Map(Object.entries(ERROR_CODE).map(([k, v]) => [v, k]));
+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;
+    /** 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";
+    }
+    /** 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: "",
+            };
+            this.#resources.set(key, ctx);
+        }
+        ctx.wanted = true;
+        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", 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.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 ("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 === "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;
+        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.#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;
+        }
+        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 = [];
+        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));
+                    request.resolve(m.body.durability);
+                }
+                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;
+                this.#move(ctx, "OPENED");
+                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);
+                if (ctx.state === "LIVE")
+                    await this.#dataRound(ctx);
+                return;
+            }
+            case "ACK":
+                if (request !== undefined) {
+                    this.#done(m);
+                    return;
+                }
+                await this.#onAck(m);
+                return;
+            case "NACK":
+                if (request !== undefined) {
+                    this.#done(m);
+                    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));
+    }
+    #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 === "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)
+            return;
+        if (request.kind === "open")
+            this.#move(ctx, "CLOSE");
+        if (request.kind === "keys")
+            this.#keyBlocked(ctx);
+        // A Snapshot is an optimization (§29.2): without it, replay the units.
+        if (request.kind === "snapshot" && ctx.snapshotPending)
+            this.#serial(() => this.#afterSnapshot(ctx));
+    }
+    // -------------------------------------------------------------------------
+    // 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 === "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).
+            const ref = dekSecretRef(R, r.epoch);
+            await this.#o.secrets.put(ref, exportSecretKeyBytes(r.dek));
+            const row = (await this.#o.storage.control.epochs(R)).find((e) => e.epoch === r.epoch);
+            if (row !== undefined) {
+                const next = { ...row, dekRef: ref };
+                await this.#o.storage.commit([{ op: "put-epoch", resourceId: R, epoch: next }]);
+            }
+        }
+        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);
+    }
+}
+/**
+ * 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