@openlfcp/client 0.1.5 → 0.2.0-beta.1

package/dist/sync-client.js

@@ -1,14 +1,51 @@
-import { actorSequence, dataEpoch, hash32, LfcpError, toHex, } from "@openlfcp/core";
-import { exportSecretKeyBytes, sha256 } from "@openlfcp/crypto";
+import { actorSequence, bytesEqual, controlRecordId, dataEpoch, dataUnitId, fromHex, 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 { addRange, addSequence, batchDataRanges, canonicalFrontierToCbor, createMessage, decodeControlRecord, 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 { afterAccepted, afterMismatch, RECOVERY_TRANSIENT_ATTEMPTS, RECOVERY_TRANSIENT_CODES, startRecovery, } from "./access-recovery.js";
+import { ACCEPTANCE_DURABILITY, batchStatus, batchStatuses, recordEvidence, } from "./batch-status.js";
+import { readClaimJournal } from "./claim-journal.js";
 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 { controlRecordWrites, createQueuedSnapshot, keyPackageWrites } from "./queue.js";
+import { intentsHash, OperationIdReusedError, receiptOf } from "./receipts.js";
 import { resourcePhaseTransition, } from "./resource-state.js";
-import { adoptStoredDeks, dekResolver, loadControlChain, saveControlChain, saveControlConflict, } from "./storage.js";
+import { planRevocation, RevocationRefused, } from "./revoke.js";
+import { receivedState, } from "./section-status.js";
+import { adoptStoredDeks, commitOperation, dekResolver, loadControlChain, saveControlChain, saveControlConflict, } from "./storage.js";
+import { accessState, NotWritableError, writeAccess, } from "./write-access.js";
+/** Every status of a stored unit: any of them means the Resource has content. */
+const STORED_STATUSES = [
+    "seen",
+    "merged",
+    "profile-pending",
+    "held",
+    "quarantined",
+    "equivocation",
+    "local-failure",
+    "profile-held",
+    "profile-rejected",
+    "profile-unsupported",
+];
+/**
+ * SDK-SECTIONS-INTEGRATION-01 §3.6: a batch the SDK refuses before the
+ * profile sees it, with the same codes and fields as the profile's
+ * refusals. Nothing is written.
+ */
+export class CommitRefusedError extends Error {
+    code;
+    intentIndex;
+    constructor(code, message, intentIndex) {
+        super(message);
+        this.code = code;
+        this.intentIndex = intentIndex;
+        this.name = "CommitRefusedError";
+    }
+}
+/** Access as a comparable key, to report it only when it changed (verifiedAt aside). */
+const accessKey = (a) => JSON.stringify({ ...a, verifiedAt: null }, (_, v) => typeof v === "bigint" ? `${v}` : v instanceof Uint8Array ? toHex(v) : v);
 /** 1 s, doubling, at most 60 s, forever. */
 export const defaultReconnect = (attempt) => Math.min(60_000, 1000 * 2 ** (attempt - 1));
 /**
@@ -77,6 +114,10 @@ export class SyncClient {
     #maxMessageBytes = 8 * 1024 * 1024;
     /** Serializes message handling: each message is handled after the previous one finished. */
     #queue = Promise.resolve();
+    /** READY's durability in this session; null without one (§37). */
+    #readyDurability = null;
+    /** The status stream's revision per Resource (hex), in this session (§5). */
+    #statusRevision = new Map();
     constructor(options) {
         this.#o = options;
         this.#snapshots = new EngineGuard(options.storage, "snapshots");
@@ -105,6 +146,202 @@ export class SyncClient {
         for (const l of this.#listeners)
             l(event);
     }
+    // -------------------------------------------------------------------------
+    // Status (SDK-SECTIONS-INTEGRATION-01 §4, §5; LFCP-02-026)
+    #emitStatus(resource, body) {
+        const key = toHex(resource);
+        const revision = (this.#statusRevision.get(key) ?? 0) + 1;
+        this.#statusRevision.set(key, revision);
+        this.#emit({
+            type: "status",
+            resourceId: resource,
+            event: Object.freeze({ ...body, revision }),
+        });
+    }
+    /**
+     * §5: the complete status of `resource` at the stream's current revision:
+     * every unreleased batch, the received units that wait or were refused,
+     * the section state and write access. Events at or below its revision
+     * are already in it.
+     */
+    async statusSnapshot(resource) {
+        const ctx = this.#resources.get(toHex(resource));
+        const batches = await batchStatuses(this.#o.storage, resource, this.#readyDurability, (ctx?.refusal ?? null) !== null);
+        const received = await receivedState(this.#o.storage, resource);
+        const access = await this.accessState(resource);
+        const section = ctx?.binding.commit?.section?.() ?? "unknown";
+        if (ctx !== undefined) {
+            for (const b of batches)
+                ctx.reported.batches.set(b.operationId, b.status);
+            ctx.reported.access = accessKey(access);
+            ctx.reported.section = section === "unknown" ? null : section;
+            ctx.reported.catchUp = this.#catchUp(ctx);
+        }
+        return Object.freeze({
+            revision: this.#statusRevision.get(toHex(resource)) ?? 0,
+            batches: Object.freeze(batches),
+            received,
+            section,
+            access,
+            catchUp: Object.freeze({
+                state: ctx === undefined ? "not-started" : this.#catchUp(ctx),
+                checkedAt: ctx?.liveAt ?? null,
+            }),
+        });
+    }
+    /** The batches of `operations`, reported as they are now. */
+    async #reportBatches(resource, operations, finals = new Map()) {
+        const ctx = this.#resources.get(toHex(resource));
+        for (const op of operations) {
+            // A released batch forgotten at its final status: reported with that status.
+            const b = finals.get(op) ??
+                (await batchStatus(this.#o.storage, resource, op, this.#readyDurability, (ctx?.refusal ?? null) !== null));
+            if (b === undefined)
+                continue;
+            ctx?.reported.batches.set(op, b.status);
+            this.#emitStatus(resource, { kind: "batch", ...b });
+        }
+    }
+    /** §4.3: a received unit that is held, waits for a dependency, or was refused. */
+    #reportReceived(resource, outcome) {
+        switch (outcome.kind) {
+            case "profile-held":
+                this.#emitStatus(resource, { kind: "received", fact: "held", unitIds: [outcome.unitId] });
+                return;
+            case "profile-pending":
+            case "held":
+                this.#emitStatus(resource, {
+                    kind: "received",
+                    fact: "waiting",
+                    unitIds: [outcome.unitId],
+                });
+                return;
+            case "profile-rejected":
+                this.#emitStatus(resource, {
+                    kind: "received",
+                    fact: "refused",
+                    unitIds: [outcome.unitId],
+                    diagnostic: outcome.message,
+                });
+                return;
+        }
+    }
+    /** Batches already reported whose status the session's durability changed (§4.1). */
+    async #refreshBatches() {
+        for (const ctx of this.#resources.values()) {
+            if (ctx.reported.batches.size === 0)
+                continue;
+            const R = ctx.binding.resourceId;
+            const changed = [];
+            for (const b of await batchStatuses(this.#o.storage, R, this.#readyDurability, ctx.refusal !== null)) {
+                const old = ctx.reported.batches.get(b.operationId);
+                if (old !== undefined && old !== b.status)
+                    changed.push(b.operationId);
+            }
+            await this.#reportBatches(R, changed);
+        }
+    }
+    /**
+     * LFCP-02-115: the server refuses this client the Resource in this
+     * session (AUTHORIZATION_FAILED on RESOURCE_OPEN, the recovery of 106
+     * not run or not enough). Null otherwise.
+     */
+    #serverRefusal(ctx) {
+        if (ctx?.refusal?.code !== "AUTHORIZATION_FAILED")
+            return null;
+        return Object.freeze({ code: ctx.refusal.code, recovery: ctx.recoveryEnd });
+    }
+    /**
+     * After a refusal of the Resource, or an open that clears one: reports
+     * access, catch-up, and every batch whose status that changes (blocked
+     * while refused, pending again after).
+     */
+    async #reportRefusal(ctx) {
+        const R = ctx.binding.resourceId;
+        await this.#refreshAccess(ctx);
+        this.#reportCatchUp(ctx);
+        const changed = [];
+        for (const b of await batchStatuses(this.#o.storage, R, this.#readyDurability, ctx.refusal !== null)) {
+            const old = ctx.reported.batches.get(b.operationId);
+            if (old !== b.status && (old !== undefined || b.status === "blocked"))
+                changed.push(b.operationId);
+        }
+        await this.#reportBatches(R, changed);
+    }
+    /** Reports write access when it changed (§5 `access`). */
+    async #refreshAccess(ctx) {
+        const R = ctx.binding.resourceId;
+        const access = await this.accessState(R);
+        const key = accessKey(access);
+        if (key === ctx.reported.access)
+            return;
+        ctx.reported.access = key;
+        this.#emitStatus(R, { kind: "access", access });
+    }
+    /** LFCP-02-028: the catch-up fact of a Resource from its phase. */
+    #catchUp(ctx) {
+        // Refused by the server in this session: how current we are is unknown.
+        if (ctx.refusal !== null)
+            return "unknown";
+        switch (ctx.state) {
+            case "LIVE":
+                return "current-at-checkpoint";
+            case "OPENING":
+            case "CONTROL_SYNC":
+            case "KEY_SYNC":
+            case "DATA_SYNC":
+                return "receiving";
+            case "KEY_BLOCKED":
+            case "CONTROL_CONFLICT":
+                return "unknown";
+            case "CLOSED":
+                return ctx.liveAt === null ? "not-started" : "current-at-checkpoint";
+        }
+    }
+    /** Reports the catch-up fact when it changed. */
+    #reportCatchUp(ctx) {
+        const state = this.#catchUp(ctx);
+        if (state === ctx.reported.catchUp)
+            return;
+        ctx.reported.catchUp = state;
+        this.#emitStatus(ctx.binding.resourceId, {
+            kind: "catch-up",
+            state,
+            checkedAt: ctx.liveAt,
+        });
+    }
+    /** Reports the section state when it changed (§5 `section-state`). */
+    #refreshSection(ctx) {
+        const state = ctx.binding.commit?.section?.();
+        if (state === undefined || state === ctx.reported.section)
+            return;
+        ctx.reported.section = state;
+        this.#emitStatus(ctx.binding.resourceId, { kind: "section-state", state });
+    }
+    /**
+     * §4.1: what an ACK establishes for units of `resource`: acceptance when
+     * it answers our message (correlated), says durable at a READY level of
+     * 2 or more, and comes from a route of the Resource's current route set.
+     */
+    #ackEvidence(resource, durability, correlated) {
+        const route = this.#resources.get(toHex(resource))?.view?.state.route;
+        const onRoute = route !== undefined &&
+            (route.endpoints.some((e) => e.url === this.#o.url) || route.coordinatorUrl === this.#o.url);
+        return correlated && onRoute && durability >= ACCEPTANCE_DURABILITY
+            ? { kind: "accepted" }
+            : { kind: "unconfirmed" };
+    }
+    /** Records `evidence` for units (hex) of `resource` and reports the batches it changed. */
+    async #evidence(resource, units, evidence) {
+        const { writes, changed, finals } = await recordEvidence(this.#o.storage, resource, units, evidence);
+        if (writes.length === 0)
+            return changed;
+        const r = await this.#o.storage.commit(writes);
+        if (!r.ok)
+            throw new Error(`the batch status was not stored: ${r.reason}`);
+        await this.#reportBatches(resource, changed.keys(), finals);
+        return changed;
+    }
     #serial(fn) {
         this.#queue = this.#queue
             .then(() => (this.#trapped ? undefined : fn()))
@@ -171,6 +408,11 @@ export class SyncClient {
                 state: "CLOSED",
                 wanted: true,
                 view: null,
+                verified: null,
+                serverControlSeq: null,
+                liveAt: null,
+                lossReason: null,
+                reported: { catchUp: null, access: null, section: null, batches: new Map() },
                 fetched: [],
                 controlTarget: null,
                 remoteHave: [],
@@ -193,12 +435,19 @@ export class SyncClient {
                 offering: new Set(),
                 keysOffered: false,
                 rehosted: false,
+                recoveryTried: false,
+                recoveryAttempts: 0,
+                recoveryReopened: false,
+                recoveryEnd: null,
             };
             this.#resources.set(key, ctx);
         }
         ctx.wanted = true;
         // An explicit open asks the server again after a refusal.
+        const wasRefused = ctx.refusal !== null;
         ctx.refusal = null;
+        if (wasRefused)
+            this.#serial(() => this.#reportRefusal(ctx));
         ctx.refusedAttempt = 0;
         ctx.reopenAt = null;
         if (this.#connection.state === "READY")
@@ -261,8 +510,13 @@ export class SyncClient {
                     ctx.wanted &&
                     this.#connection.state === "READY")
                     await this.#sendOpen(ctx);
-                if (ctx.state === "LIVE" && now - ctx.lastHave >= this.#antiEntropyMs)
+                // Periodic anti-entropy (§68.1), both planes: the server's answer
+                // to CONTROL_HAVE also re-offers Control Records it still lacks,
+                // e.g. after a refused or lost re-supply.
+                if (ctx.state === "LIVE" && now - ctx.lastHave >= this.#antiEntropyMs) {
                     this.#sendHave(ctx, now);
+                    this.#refreshControl(ctx);
+                }
                 if (ctx.state === "KEY_BLOCKED" && now - ctx.lastKeyRequest >= this.#antiEntropyMs)
                     this.#requestKeys(ctx, now);
                 await this.#flush(ctx);
@@ -310,7 +564,9 @@ export class SyncClient {
                     ctx?.offering.delete(u.id);
                 continue;
             }
-            if (request.kind === "offer-control" || request.kind === "offer-keys")
+            if (request.kind === "offer-control" ||
+                request.kind === "offer-keys" ||
+                request.kind === "recover-control")
                 continue;
             if ("resource" in request)
                 resend.set(`${request.kind}:${request.resource}`, request);
@@ -355,8 +611,13 @@ export class SyncClient {
         if (next === "LIVE") {
             ctx.refusedAttempt = 0;
             ctx.rehosted = false;
+            ctx.recoveryTried = false;
+            ctx.recoveryAttempts = 0;
         }
         this.#emit({ type: "resource-state", resourceId: ctx.binding.resourceId, state: next });
+        if (next === "LIVE")
+            ctx.liveAt = this.#o.now();
+        this.#reportCatchUp(ctx);
         if (next === "LIVE" && ctx.controlStale) {
             ctx.controlStale = false;
             this.#refreshControl(ctx);
@@ -383,12 +644,16 @@ export class SyncClient {
             durability: ready.durability,
             maxMessageBytes: ready.maxMessageBytes,
         });
+        this.#readyDurability = ready.durability;
+        await this.#refreshBatches();
         for (const ctx of this.#resources.values())
             if (ctx.wanted)
                 await this.#sendOpen(ctx);
     }
     async #onClosed(reason) {
         this.#emit({ type: "connection", state: "DISCONNECTED", reason });
+        this.#readyDurability = null;
+        await this.#refreshBatches();
         for (const r of this.#requests.values())
             if (r.kind === "host")
                 r.reject(new Error(`the connection closed before RESOURCE_HOSTED: ${reason}`));
@@ -398,6 +663,7 @@ export class SyncClient {
             this.#move(ctx, "CLOSE"); // §65, G-SM1: every Resource closes with the connection
             ctx.view = null;
             ctx.offering.clear();
+            ctx.recoveryTried = false; // a new session may recover again (LFCP-02-106)
         }
         await this.#o.outbound.connectionLost(iso(this.#o.now()));
         if (this.#stopped)
@@ -448,6 +714,8 @@ export class SyncClient {
                         url: this.#o.url,
                         outcome: "hosted",
                     });
+                    ctx.lossReason ??= "rehost";
+                    this.#emitStatus(ctx.binding.resourceId, { kind: "rehost", route: this.#o.url });
                     if (ctx.wanted)
                         await this.#sendOpen(ctx);
                 }
@@ -460,7 +728,12 @@ export class SyncClient {
                 ctx.remoteHave = normalizeLiveHaves(m.body.haves);
                 ctx.offered = m.body.snapshot ?? null;
                 await this.#markHosted(ctx.binding.resourceId);
+                if (ctx.recoveryReopened) {
+                    ctx.recoveryReopened = false;
+                    this.#recoveryEvent(ctx, "recovered");
+                }
                 this.#move(ctx, "OPENED");
+                await this.#noteServerHeads(ctx, m.body.heads);
                 // §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);
@@ -470,6 +743,8 @@ export class SyncClient {
             case "CONTROL_HAVE": {
                 const ctx = this.#ctx(m.body.resourceId);
                 this.#done(m);
+                if (ctx !== undefined)
+                    await this.#noteServerHeads(ctx, m.body.heads);
                 if (ctx !== undefined && ctx.state === "LIVE")
                     await this.#onControlHeads(ctx, m.body.heads);
                 return;
@@ -522,11 +797,25 @@ export class SyncClient {
                 return;
             }
             case "ACK":
+                if (request?.kind === "recover-control") {
+                    this.#done(m);
+                    await this.#recoveryAccepted(request);
+                    return;
+                }
                 if (request !== undefined) {
                     this.#done(m);
-                    if (request.kind === "offer-data")
+                    if (request.kind === "offer-data") {
+                        const ctx = this.#resources.get(request.resource);
                         for (const u of request.units)
-                            this.#resources.get(request.resource)?.offering.delete(u.id);
+                            ctx?.offering.delete(u.id);
+                        if (ctx !== undefined) {
+                            // §4.2: a re-offered unit of ours is accepted again by this ACK.
+                            const named = new Set((m.body.objectIds ?? []).map((id) => toHex(id)));
+                            const durability = m.body.durable === true ? (this.#readyDurability ?? 0n) : 0n;
+                            const R = ctx.binding.resourceId;
+                            await this.#evidence(R, request.units.map((u) => u.id).filter((id) => named.has(id)), this.#ackEvidence(R, durability, true));
+                        }
+                    }
                     return;
                 }
                 await this.#onAck(m);
@@ -565,6 +854,20 @@ export class SyncClient {
             if (ctx !== undefined && (await this.#rehost(ctx)))
                 return;
         }
+        if (request.kind === "open" && code === "AUTHORIZATION_FAILED") {
+            const ctx = this.#resources.get(request.resource);
+            if (ctx?.recoveryReopened) {
+                // The server holds our chain and still refuses: not a loss.
+                ctx.recoveryReopened = false;
+                this.#recoveryEvent(ctx, "ended", "still-refused");
+            }
+            else if (ctx !== undefined && (await this.#recoverAccess(ctx)))
+                return;
+        }
+        if (request.kind === "recover-control") {
+            await this.#recoveryRefused(request, code, m.body.details);
+            return;
+        }
         if (request.kind === "rehost") {
             const ctx = this.#resources.get(request.resource);
             if (ctx === undefined)
@@ -627,6 +930,8 @@ export class SyncClient {
             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 });
+        // LFCP-02-115: the status stream says so too.
+        this.#serial(() => this.#reportRefusal(ctx));
     }
     /** CLOSED now, opened again after the ReconnectPolicy's delay for this Resource's attempt. */
     #retryLater(ctx) {
@@ -736,9 +1041,11 @@ export class SyncClient {
         const R = ctx.binding.resourceId;
         const before = previous ?? ctx.view;
         ctx.view = chain;
+        ctx.verified = { head: chain.state.head, at: this.#o.now() };
         // 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);
+        await this.#refreshAccess(ctx);
         const epochsChanged = before === null ||
             [...chain.state.epochs.values()].some((e) => {
                 const old = before.state.epochs.get(String(e.epoch));
@@ -840,6 +1147,7 @@ export class SyncClient {
             }
             await this.#o.storage.commit(writes);
         }
+        await this.#refreshAccess(ctx);
         const missing = await this.#epochsWithoutDek(ctx);
         const current = view.state.epoch.epoch;
         if (missing.some((e) => e === current)) {
@@ -988,6 +1296,247 @@ export class SyncClient {
      * that loads it never skips content the state does not hold. Queued and
      * sent like any object; returns its ID.
      */
+    /**
+     * LFCP-02-060: removes `subject`'s access to `resource`. Every active
+     * grant naming it that this client may revoke is revoked (§17.3); when it
+     * has no read access left, the Data Epoch is rotated with a fresh DEK
+     * (§19, member revoked) and the DEK goes in Key Packages to every other
+     * remaining reader (§25), so it cannot read new data. Built on the
+     * validated head and checked before anything is queued; the records, the
+     * Key Packages and (first) the new DEK are written at once, then sent.
+     * Refused, with nothing queued, unless the Resource is live and current
+     * here and no Control Record of this client is pending.
+     */
+    revokeAccess(resource, subject, options = {}) {
+        return new Promise((resolve, reject) => this.#serial(async () => {
+            try {
+                resolve(await this.#revoke(resource, subject, options));
+            }
+            catch (e) {
+                reject(e);
+            }
+        }));
+    }
+    async #revoke(resource, subject, options) {
+        const refused = (reason, message) => Object.freeze({ kind: "refused", reason, message });
+        const ctx = this.#resources.get(toHex(resource));
+        const view = ctx?.view ?? null;
+        if (ctx === undefined || ctx.state !== "LIVE" || view === null)
+            return refused("offline", "the Resource is not live in this session");
+        if (ctx.serverControlSeq !== null && view.state.seq < ctx.serverControlSeq)
+            return refused("stale", "the validated Control Chain is behind the server's");
+        const storage = this.#o.storage;
+        if ((await storage.outbound.list(resource)).some((i) => i.kind === "control-record"))
+            return refused("control-pending", "Control Records of this client are not committed yet");
+        let plan;
+        try {
+            plan = await planRevocation({
+                view,
+                revoker: this.#o.signer,
+                subject,
+                frontier: (await resourceSyncState(storage, resource)).have,
+                ...(options.rotate === undefined ? {} : { rotate: options.rotate }),
+            });
+        }
+        catch (e) {
+            if (e instanceof RevocationRefused)
+                return refused(e.reason, e.message);
+            throw e;
+        }
+        // The new DEK first (LFCP-034), then everything that names it, at once.
+        if (plan.rotation !== null)
+            await this.#o.secrets.put(dekSecretRef(resource, plan.rotation.epoch), exportSecretKeyBytes(plan.rotation.dek));
+        const r = await storage.commit([
+            ...plan.records.flatMap((rec) => controlRecordWrites(rec.bytes)),
+            ...plan.keyPackages.flatMap(keyPackageWrites),
+        ]);
+        if (!r.ok)
+            throw new Error(`the revocation was not queued: ${r.reason}`);
+        await this.#refreshAccess(ctx);
+        await this.#flush(ctx);
+        return Object.freeze({
+            kind: "queued",
+            revoked: plan.revoked,
+            deactivated: plan.deactivated,
+            recordIds: Object.freeze(plan.records.map((rec) => rec.recordId)),
+            epoch: plan.rotation?.epoch ?? null,
+            recipients: plan.recipients,
+            remainingPaths: plan.remainingPaths,
+        });
+    }
+    /**
+     * SDK-SECTIONS-INTEGRATION-01 §3.1: commits a batch of intents on an open
+     * Resource and returns its receipt once the batch is durable: its Data
+     * Units, outbound entries, the profile checkpoint and the receipt are
+     * stored in one transaction, then the batch is sent. An operation that
+     * has a receipt returns it for the same intents and writes nothing, and
+     * throws OperationIdReusedError for different ones (§3.3). Runs between
+     * received units, never during their merge.
+     */
+    commit(resource, intents, options) {
+        const ctx = this.#resources.get(toHex(resource));
+        if (ctx === undefined)
+            return Promise.reject(new LfcpError("UNSUPPORTED_VALUE", "the Resource is not open here"));
+        const binding = ctx.binding.commit;
+        if (binding === undefined)
+            return Promise.reject(new LfcpError("UNSUPPORTED_VALUE", "the Resource has no commit binding"));
+        return new Promise((resolve, reject) => this.#serial(async () => {
+            try {
+                resolve(await this.#commit(ctx, binding, intents, options.operationId));
+            }
+            catch (e) {
+                reject(e);
+            }
+        }));
+    }
+    /**
+     * SDK-SECTIONS-INTEGRATION-01 §6: whether this client may commit to
+     * `resource`, from the validated Control state only: the chain of the
+     * last Control sync, or the stored chain validated now. `verifiedAt` is
+     * the local time of that validation (the last sync's when the stored
+     * chain is still at its head). Unknown without a validated chain.
+     */
+    async canWrite(resource) {
+        const ctx = this.#resources.get(toHex(resource));
+        const view = ctx?.view ?? (await loadControlChain(this.#o.storage, resource));
+        return this.#access(resource, view, ctx?.verified ?? null, this.#serverRefusal(ctx));
+    }
+    /**
+     * LFCP-02-027: write access with its evidence: the Control sequence it
+     * was validated at against the highest one a server reported in this
+     * session (a stale view is not current), the effective abilities and
+     * the active grant paths giving them, and apart from them the
+     * invitations we issued, our Control Records not yet committed (SI14)
+     * and an unsettled invitation claim of ours.
+     */
+    async accessState(resource) {
+        const ctx = this.#resources.get(toHex(resource));
+        const view = ctx?.view ?? (await loadControlChain(this.#o.storage, resource));
+        const refusal = this.#serverRefusal(ctx);
+        const write = await this.#access(resource, view, ctx?.verified ?? null, refusal);
+        const pendingControl = [];
+        for (const item of await this.#o.storage.outbound.list(resource)) {
+            if (item.kind !== "control-record")
+                continue;
+            const record = decodeControlRecord(item.bytes);
+            pendingControl.push(Object.freeze({ recordId: controlRecordId(record.signed.id), type: record.body.type }));
+        }
+        const dek = view?.kind === "linear" &&
+            (await this.#currentDek(resource, view.state.epoch.epoch)) !== undefined;
+        return accessState(view, this.#o.signer.descriptor.principalId, dek, write.verifiedAt ?? 0, {
+            serverControlSeq: ctx?.serverControlSeq ?? null,
+            pendingControl,
+            pendingClaim: (await readClaimJournal(this.#o.storage, resource)) !== undefined,
+            serverRefusal: refusal,
+        });
+    }
+    /** Records the highest Control sequence a server reported, and reports access if it changed. */
+    async #noteServerHeads(ctx, heads) {
+        const seq = heads.reduce((m, h) => (m === null || h.seq > m ? h.seq : m), null);
+        if (seq === null || (ctx.serverControlSeq !== null && seq <= ctx.serverControlSeq))
+            return;
+        ctx.serverControlSeq = seq;
+        await this.#refreshAccess(ctx);
+    }
+    /**
+     * The DEK of `epoch`, or undefined when it is not held or the key store
+     * cannot be read now (LFCP-02-030): an unreadable key store is
+     * key-unavailable, never a reason to write without it or to reset state.
+     */
+    async #currentDek(resource, epoch) {
+        try {
+            return await dekResolver(this.#o.storage, this.#o.secrets, resource)(epoch);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async #access(resource, view, verified, refusal = null) {
+        if (view?.kind !== "linear")
+            return writeAccess(view, this.#o.signer.descriptor.principalId, false, 0);
+        const dek = await this.#currentDek(resource, view.state.epoch.epoch);
+        const at = verified !== null && bytesEqual(verified.head, view.state.head) ? verified.at : this.#o.now();
+        const access = writeAccess(view, this.#o.signer.descriptor.principalId, dek !== undefined, at);
+        // LFCP-02-115: the server refuses us the Resource; the local chain is not the last word.
+        return refusal === null
+            ? access
+            : Object.freeze({ ...access, allowed: false, reason: "server-refused" });
+    }
+    /**
+     * SHARED-SECTIONS-PROFILE-01 §13, in depth behind the adapter's own
+     * check: an incomplete load never becomes a new, empty section. A batch
+     * that creates a section is refused (SECTION_EXISTS) when units of the
+     * Resource are stored (content exists that the model may not hold yet),
+     * or when this client is not the Resource's owner and the Resource was
+     * not live in this session (it has not caught up). The owner creates its
+     * new Resource's section offline.
+     */
+    async #guardCreate(ctx, view, intents) {
+        const index = intents.findIndex((i) => typeof i === "object" &&
+            i !== null &&
+            i.intent === "section.create");
+        if (index < 0)
+            return;
+        const R = ctx.binding.resourceId;
+        const stored = (await Promise.all(STORED_STATUSES.map((st) => this.#o.storage.dataUnits.withStatus(R, st)))).some((units) => units.length > 0);
+        if (stored)
+            throw new CommitRefusedError("SECTION_EXISTS", "units of this Resource are stored: it is not a new section (§13)", index);
+        const owner = bytesEqual(view.state.owner.principalId, this.#o.signer.descriptor.principalId);
+        if (!owner && ctx.liveAt === null)
+            throw new CommitRefusedError("SECTION_EXISTS", "the Resource has not caught up in this session: its section may exist (§13)", index);
+    }
+    async #commit(ctx, binding, intents, operationId) {
+        const R = ctx.binding.resourceId;
+        const storage = this.#o.storage;
+        // §3.3: a committed operation answers first; its intents may no longer apply.
+        const known = await receiptOf(storage, R, operationId);
+        if (known !== undefined) {
+            if (known.intentsHash !== intentsHash(intents))
+                throw new OperationIdReusedError(operationId);
+            return known;
+        }
+        const view = ctx.view ?? (await loadControlChain(storage, R));
+        // §3.6, §6: a batch submitted while writing is not allowed writes nothing.
+        const access = await this.#access(R, view, ctx.verified, this.#serverRefusal(ctx));
+        if (!access.allowed || view?.kind !== "linear")
+            throw new NotWritableError(access);
+        const dek = await this.#currentDek(R, view.state.epoch.epoch);
+        if (dek === undefined)
+            throw new NotWritableError({ ...access, allowed: false, reason: "key-unavailable" });
+        await this.#guardCreate(ctx, view, intents);
+        const staged = binding.stage(intents);
+        staged?.apply();
+        try {
+            const { receipt, committed } = await commitOperation(storage, {
+                view,
+                controlHead: view.state.head,
+                actor: this.#o.signer,
+                dek,
+                profile: binding.codec,
+                operationId,
+                intents,
+                values: staged?.values ?? [],
+                affectedNodeIds: staged?.affectedNodeIds ?? [],
+                modelRevision: staged?.modelRevision ?? "",
+            }, (units) => staged?.writes(units) ?? []);
+            if (!committed)
+                staged?.revert();
+            else
+                staged?.committed(receipt.unitIds);
+            if (committed) {
+                // Our own units grow the history a Snapshot covers, as received ones do.
+                ctx.unitsSinceSnapshot += receipt.unitIds.length;
+                await this.#reportBatches(R, [receipt.operationId]);
+                this.#refreshSection(ctx);
+            }
+            await this.#flush(ctx);
+            return receipt;
+        }
+        catch (e) {
+            staged?.revert();
+            throw e;
+        }
+    }
     async publishSnapshot(resource) {
         const ctx = this.#resources.get(toHex(resource));
         if (ctx === undefined)
@@ -1142,16 +1691,20 @@ export class SyncClient {
             if (outcome.kind === "rejected" && outcome.wireCode === "MISSING_DEPENDENCY")
                 needControl = true;
             this.#emit({ type: "unit", resourceId: R, outcome });
+            this.#reportReceived(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 });
+                this.#reportReceived(R, r);
             }
         }
-        if (changed)
+        if (changed) {
             ctx.binding.checkpointer?.noteChange();
+            this.#refreshSection(ctx);
+        }
         if (needControl)
             this.#refreshControl(ctx);
         if (ctx.state === "DATA_SYNC" &&
@@ -1189,7 +1742,32 @@ export class SyncClient {
             this.#connection.sendEncoded(m.bytes);
     }
     async #onAck(m) {
-        const outcome = await this.#o.outbound.onAck(m, iso(this.#o.now()));
+        if (m.body.requestType === MESSAGE_TYPE.CONTROL_PUT)
+            await this.#adoptAcked(m);
+        // §4.1: acceptance is recorded in the dequeue's transaction.
+        const changed = [];
+        const outcome = await this.#o.outbound.onAck(m, iso(this.#o.now()), async (items, ack) => {
+            const byResource = new Map();
+            for (const item of items) {
+                if (item.kind !== "data-unit")
+                    continue;
+                const key = toHex(item.resourceId);
+                const entry = byResource.get(key) ?? { R: item.resourceId, units: [] };
+                entry.units.push(toHex(item.itemId));
+                byResource.set(key, entry);
+            }
+            const writes = [];
+            for (const { R, units } of byResource.values()) {
+                const evidence = this.#ackEvidence(R, ack.durability, ack.correlated);
+                const r = await recordEvidence(this.#o.storage, R, units, evidence);
+                writes.push(...r.writes);
+                if (r.changed.size > 0)
+                    changed.push([R, r.changed, r.finals]);
+            }
+            return writes;
+        });
+        for (const [R, ops, finals] of changed)
+            await this.#reportBatches(R, ops.keys(), finals);
         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)
@@ -1199,8 +1777,57 @@ export class SyncClient {
                 else
                     ctx.controlStale = true;
     }
+    /**
+     * An ACK of our CONTROL_PUT (§47) means the server committed the record
+     * on the head it expected: our own previous record. The record joins the
+     * stored chain the way a fetched one does, BEFORE it leaves the queue, so
+     * it is never held by the server alone: a stop between the ACK and the
+     * catch-up fetch, then a server restored from an older copy, would
+     * otherwise lose it (LFCP-02-106). A crash before the dequeue only sends
+     * it again, and a repeated ACK is idempotent. A record that does not
+     * continue the stored chain is left to the catch-up fetch.
+     */
+    async #adoptAcked(m) {
+        for (const id of m.body.objectIds ?? []) {
+            const item = await this.#o.storage.outbound.get(id);
+            if (item?.kind !== "control-record")
+                continue;
+            const ctx = this.#ctx(item.resourceId);
+            if (ctx === undefined)
+                continue;
+            await this.#onControlRecords(ctx, [item.bytes], false);
+        }
+    }
     async #onNack(m) {
         const outcome = await this.#o.outbound.onNack(m, iso(this.#o.now()));
+        // §4.1: a terminal NACK rejects the batch of the unit.
+        if (outcome.kind === "rejected" ||
+            outcome.kind === "stale" ||
+            outcome.kind === "equivocation-alarm") {
+            const code = outcome.kind === "rejected"
+                ? outcome.code
+                : outcome.kind === "stale"
+                    ? "STALE_DATA_EPOCH"
+                    : "ACTOR_EQUIVOCATION";
+            const byResource = new Map();
+            for (const item of outcome.items) {
+                if (item.kind !== "data-unit")
+                    continue;
+                const R = (await this.#o.storage.outbound.get(item.itemId))?.resourceId;
+                if (R === undefined)
+                    continue;
+                const entry = byResource.get(toHex(R)) ?? { R, units: [] };
+                entry.units.push(toHex(item.itemId));
+                byResource.set(toHex(R), entry);
+            }
+            for (const { R, units } of byResource.values())
+                await this.#evidence(R, units, { kind: "rejected", code });
+        }
+        if (outcome.kind === "needs-offer") {
+            const ctx = this.#ctx(outcome.resourceId);
+            if (ctx !== undefined)
+                ctx.lossReason ??= "unknown-previous";
+        }
         this.#emit({ type: "nack", outcome });
         if (outcome.kind === "needs-control-sync")
             for (const ctx of this.#resources.values())
@@ -1248,6 +1875,94 @@ export class SyncClient {
         this.#request({ kind: "rehost", resource: toHex(R) }, createMessage("RESOURCE_HOST", { genesis: genesis.signed.bytes }));
         return true;
     }
+    /**
+     * LFCP-02-106: RESOURCE_OPEN was refused with AUTHORIZATION_FAILED. When
+     * our validated chain grants us data/read, the server may have lost the
+     * records that do (a restore): push our head, and follow the server's
+     * answer (see access-recovery.ts). False when no recovery runs; the
+     * refusal then stands as before.
+     */
+    async #recoverAccess(ctx) {
+        if (ctx.recoveryTried || this.#connection.state !== "READY")
+            return false;
+        const chain = await loadControlChain(this.#o.storage, ctx.binding.resourceId);
+        if (chain?.kind !== "linear")
+            return false;
+        const step = startRecovery(chain.state, chain.records, this.#o.signer.descriptor.principalId);
+        ctx.recoveryTried = true;
+        if (step.kind !== "push") {
+            this.#recoveryEvent(ctx, "ended", step.kind === "final" ? step.reason : undefined);
+            return false;
+        }
+        this.#recoveryEvent(ctx, "started");
+        this.#move(ctx, "CLOSE");
+        await this.#recoveryStep(ctx, step);
+        return true;
+    }
+    async #recoveryStep(ctx, step) {
+        const R = ctx.binding.resourceId;
+        if (step.kind === "reopen") {
+            ctx.recoveryReopened = true;
+            if (ctx.wanted)
+                await this.#sendOpen(ctx);
+            return;
+        }
+        if (step.kind === "final") {
+            this.#recoveryEvent(ctx, "ended", step.reason);
+            this.#refuse(ctx, { code: "AUTHORIZATION_FAILED", url: this.#o.url, request: "open" });
+            return;
+        }
+        if (this.#connection.state !== "READY")
+            return; // the next session opens and may recover again
+        const chain = await loadControlChain(this.#o.storage, R);
+        const record = chain?.kind === "linear" ? chain.records[step.index] : undefined;
+        const previous = record?.payload.prevControlId ?? null;
+        if (record === undefined || previous === null) {
+            await this.#recoveryStep(ctx, { kind: "final", reason: "refused" });
+            return;
+        }
+        this.#request({ kind: "recover-control", resource: toHex(R), index: step.index }, createMessage("CONTROL_PUT", {
+            resourceId: R,
+            expectedHead: previous,
+            record: record.signed.bytes,
+        }));
+    }
+    async #recoveryAccepted(request) {
+        const ctx = this.#resources.get(request.resource);
+        if (ctx === undefined)
+            return;
+        const chain = await loadControlChain(this.#o.storage, ctx.binding.resourceId);
+        if (chain?.kind !== "linear")
+            return;
+        await this.#recoveryStep(ctx, afterAccepted(chain.records, request.index));
+    }
+    async #recoveryRefused(request, code, details) {
+        const ctx = this.#resources.get(request.resource);
+        if (ctx === undefined)
+            return;
+        if (RECOVERY_TRANSIENT_CODES.has(code) && ctx.recoveryAttempts < RECOVERY_TRANSIENT_ATTEMPTS) {
+            // Open again after a backoff; the refused open recovers again.
+            ctx.recoveryAttempts += 1;
+            ctx.recoveryTried = false;
+            this.#retryLater(ctx);
+            return;
+        }
+        const chain = await loadControlChain(this.#o.storage, ctx.binding.resourceId);
+        const step = code === "CONTROL_HEAD_MISMATCH" && chain?.kind === "linear"
+            ? afterMismatch(chain.records, details)
+            : { kind: "final", reason: "refused" };
+        await this.#recoveryStep(ctx, step);
+    }
+    #recoveryEvent(ctx, outcome, reason) {
+        ctx.recoveryEnd = outcome === "ended" ? (reason ?? null) : null;
+        this.#emit({
+            type: "access-recovery",
+            resourceId: ctx.binding.resourceId,
+            url: this.#o.url,
+            outcome,
+            ...(reason === undefined ? {} : { reason }),
+        });
+    }
     /**
      * §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
@@ -1302,9 +2017,19 @@ export class SyncClient {
                 !queued.has(toHex(u.unitId)) &&
                 !ctx.offering.has(toHex(u.unitId)));
             sent += units.length;
+            // §4.2: units of our batches the server lost are pending again.
+            const lost = await this.#evidence(R, units.map((u) => toHex(u.unitId)), { kind: "reoffered" });
+            const again = [...lost.values()].flat();
+            if (again.length > 0)
+                this.#emitStatus(R, {
+                    kind: "reoffered",
+                    unitIds: Object.freeze(again.map((u) => dataUnitId(fromHex(u)))),
+                    reason: ctx.lossReason ?? "have-gap",
+                });
             this.#offerUnits(ctx, units.map((u) => ({ id: toHex(u.unitId), bytes: u.bytes })));
         }
         await this.#o.outbound.offered(R);
+        ctx.lossReason = null;
         if (sent > 0)
             await this.#offerKeys(ctx);
         await this.#flush(ctx);