@openlfcp/client 0.1.5 → 0.2.0-beta.10

package/dist/invite.d.ts

@@ -49,7 +49,7 @@ export declare class InvitationLink {
 /** The usual invitation grant (§18): data/read, data/write, invite/claim. */
 export declare const DEFAULT_INVITATION_ABILITIES: readonly bigint[];
 export interface CreateInvitationOptions {
-    readonly storage: Pick<LfcpStorage, "control" | "commit">;
+    readonly storage: Pick<LfcpStorage, "control" | "commit" | "outbound">;
     readonly resourceId: ResourceId;
     /** The issuer: needs the authority to grant the abilities (§17.2) and key/distribute (§25.2). */
     readonly inviter: Signer;
@@ -90,8 +90,13 @@ export interface AcceptInvitationOptions {
         readonly signer: Signer;
         readonly agreement: AgreementKeyPair;
     };
-    /** The claimant's storage and secrets: on "claimed" they hold the chain and the DEK. */
-    readonly storage: Pick<LfcpStorage, "control" | "commit">;
+    /**
+     * The claimant's storage and secrets: on "claimed" they hold the chain and
+     * the DEK. While a claim is in flight they also hold its journal
+     * (LFCP-02-110): a lost answer is then resolved by sending the same claim
+     * again, never by spending the invitation twice.
+     */
+    readonly storage: Pick<LfcpStorage, "control" | "commit" | "localMarks">;
     readonly secrets: SecretStore;
     /** Abilities to claim; default the grant's, without invite/claim unless it is delegable (§18.1 rule 4). */
     readonly abilities?: readonly bigint[];
@@ -132,6 +137,12 @@ export type AcceptedInvitation = {
     readonly epochs: readonly DataEpoch[];
     /** The CONTROL_PUT answers in order, e.g. ["ACK"] or ["CONTROL_HEAD_MISMATCH", "ACK"]. */
     readonly attempts: readonly string[];
+    /**
+     * True when an earlier attempt's claim, whose answer was lost, turned
+     * out to be committed: it was sent again from its journal (§47) and
+     * acknowledged as already committed (LFCP-02-110).
+     */
+    readonly resumed: boolean;
 } | {
     /** The coordinator refused the claim, e.g. AUTHORIZATION_FAILED: the invitation is used up. */
     readonly kind: "refused";
@@ -171,4 +182,32 @@ export type AcceptedInvitation = {
  * epoch's DEK; transport and server stops are "unavailable".
  */
 export declare function acceptInvitation(options: AcceptInvitationOptions): Promise<AcceptedInvitation>;
+export interface ResumeInvitationClaimOptions {
+    /** The Resource of a journaled claim (pendingInvitationClaims). */
+    readonly resourceId: ResourceId;
+    /** The claimant: the session authenticates as it (§84: any session may upload a record). */
+    readonly claimant: {
+        readonly signer: Signer;
+    };
+    readonly storage: Pick<LfcpStorage, "control" | "commit" | "localMarks">;
+    readonly secrets: SecretStore;
+    /** The coordinator's endpoint. */
+    readonly url: string;
+    readonly now: () => number;
+    readonly webSocket?: WebSocketFactory;
+    readonly timeout?: Promise<unknown>;
+}
+/**
+ * Settles a journaled claim without its link, e.g. after a restart
+ * (LFCP-02-110): "claimed" when the claim had landed; "not-claimed" when it
+ * had not (the journal is removed, and the link, still unused, can be
+ * accepted again); "refused" for another refusal; "unavailable" keeps the
+ * journal for a later try; "none" when no claim is journaled.
+ */
+export declare function resumeInvitationClaim(options: ResumeInvitationClaimOptions): Promise<AcceptedInvitation | {
+    readonly kind: "not-claimed" | "none";
+    readonly resourceId: ResourceId;
+}>;
+/** Gives up a journaled claim (the user declined to retry it): its journal is removed. */
+export declare function abandonInvitationClaim(storage: Pick<LfcpStorage, "commit">, resource: ResourceId): Promise<void>;
 //# sourceMappingURL=invite.d.ts.map

package/dist/invite.js

@@ -1,10 +1,11 @@
-import { bytesEqual, hash32, LfcpError, toHex, } from "@openlfcp/core";
+import { bytesEqual, fromHex, hash32, LfcpError, toHex, } from "@openlfcp/core";
 import { dekCommitment, exportSecretKeyBytes, InvitationSecret, } from "@openlfcp/crypto";
 import { dekSecretRef } from "@openlfcp/storage";
-import { ABILITY, assembleInviteUri, createMessage, ERROR_CODE, invitationPrincipal, parseControlRecord, parseInviteUri, parseKeyPackage, receiveKeyPackage, sealKeyPackage, signControlRecord, validateControlChain, verifyInvitationSecret, verifyKeyPackage, } from "@openlfcp/wire";
+import { ABILITY, assembleInviteUri, createMessage, ERROR_CODE, invitationPrincipal, isGrantActive, parseControlRecord, parseInviteUri, parseKeyPackage, receiveKeyPackage, sealKeyPackage, signControlRecord, validateControlChain, verifyInvitationSecret, verifyKeyPackage, } from "@openlfcp/wire";
+import { clearClaimJournal, journaledDeks, readClaimJournal, writeClaimJournal, } from "./claim-journal.js";
 import { LfcpConnection } from "./connection.js";
 import { queueControlRecord, queueKeyPackage } from "./queue.js";
-import { loadControlChain, saveControlChain } from "./storage.js";
+import { loadControlChain, localControlChain, saveControlChain } from "./storage.js";
 /**
  * Link invitations and the one-time capability claim (LFCP-WIRE-01 §18,
  * §18.1, §18.2, §25.2, §73; LFCP-053), built on the invitation codec of
@@ -68,6 +69,28 @@ export const DEFAULT_INVITATION_ABILITIES = Object.freeze([
 const fail = (code, why) => {
     throw new LfcpError(code, why);
 };
+/**
+ * Resolves the invitation grant the claimant will reference (§18.1, §18.2).
+ * The link names the record the inviter first queued; a re-propose on a
+ * moved head gives the grant a new record ID while keeping the same
+ * Invitation Principal and claim parameters, so the grant is looked up by
+ * its ID first and, failing that, by its subject: the single active
+ * invitation grant (invite/claim) whose subject is the secret's Invitation
+ * Principal. Returns the on-chain grant ID, the grant and the claim signer.
+ * Throws MISSING_DEPENDENCY when no such grant is on the chain.
+ */
+function resolveInvitationGrant(state, linkGrantId, secret) {
+    const principal = invitationPrincipal(secret);
+    const byId = state.grants.get(toHex(linkGrantId));
+    const grant = byId ??
+        [...state.grants.values()].find((g) => bytesEqual(g.subject, principal.principalId) &&
+            g.abilities.includes(ABILITY.INVITE_CLAIM) &&
+            isGrantActive(state, g.id)) ??
+        fail("MISSING_DEPENDENCY", "the invitation grant is not on the chain");
+    const grantId = grant.id;
+    const claimSigner = verifyInvitationSecret(state, grantId, secret);
+    return Object.freeze({ grantId, grant, claimSigner });
+}
 /**
  * The inviter's side (§18, §73). The grant must validate on the stored
  * chain and the package must pass §25.2 at the grant's head, both checked
@@ -77,7 +100,11 @@ const fail = (code, why) => {
  */
 export async function createInvitation(options) {
     const R = options.resourceId;
-    const stored = await loadControlChain(options.storage, R);
+    // §47: build the grant on the LOCAL head (the committed chain extended by
+    // this client's own still-queued records), so an invitation made before an
+    // earlier one is acknowledged chains on it instead of colliding on the
+    // committed head (CONTROL_HEAD_MISMATCH).
+    const stored = await localControlChain(options.storage, R);
     const view = stored?.kind === "linear"
         ? stored
         : fail("MISSING_DEPENDENCY", "no valid local Control Chain for the Resource");
@@ -274,15 +301,31 @@ export async function acceptInvitation(options) {
         // §73: the Invitation Principal authenticates and opens the Resource.
         progress("connecting");
         await s.connect();
+        // LFCP-02-110: a claim of this link whose answer was lost is settled first.
+        const journal = await readClaimJournal(options.storage, R);
+        if (journal !== undefined &&
+            journal.invitationGrantId === toHex(invitation.grantId) &&
+            journal.claimant === toHex(options.claimant.signer.descriptor.principalId)) {
+            progress("claiming-capability", 1);
+            const settled = await settleJournal(s, options, R, journal);
+            if (settled !== "not-committed")
+                return settled;
+        }
         progress("validating-invitation");
         const heads = await openAsInvitee(s, R, invitation.grantId);
         if (heads.length !== 1)
             throw new Unavailable("the Resource has no single Control Head: no claim is made (§42)");
         let chain = await fetchChain(s, R, [], { seq: heads[0].seq });
-        // §18.2: the secret's Principal must be the grant's subject before the secret is used further.
-        const claimSigner = verifyInvitationSecret(chain.state, invitation.grantId, secret);
-        const grant = chain.state.grants.get(toHex(invitation.grantId)) ??
-            fail("MISSING_DEPENDENCY", "the invitation grant is not on the chain");
+        // §18.2: the secret's Principal must be the grant's subject before the
+        // secret is used further. The link names the grant the inviter first
+        // queued; if that grant was re-proposed on a moved head (a new record ID,
+        // the same Invitation Principal and claim parameters), it is resolved by
+        // its subject, so a link copied before the re-propose still joins (§18.1).
+        const resolved = resolveInvitationGrant(chain.state, invitation.grantId, secret);
+        const claimSigner = resolved.claimSigner;
+        const grant = resolved.grant;
+        // The claim references the grant that is actually on the chain.
+        const grantId = resolved.grantId;
         // §27: a profile the caller cannot open is refused before the DEK and the claim.
         if (options.dataProfiles !== undefined &&
             !options.dataProfiles.includes(chain.state.dataProfile))
@@ -327,10 +370,22 @@ export async function acceptInvitation(options) {
             progress("claiming-capability", attempts.length + 1);
             const claim = signControlRecord({ resourceId: R, controlSeq: chain.state.seq + 1n, prevControlId: chain.state.head }, {
                 type: "CAPABILITY_CLAIM",
-                invitationGrantId: invitation.grantId,
+                invitationGrantId: grantId,
                 claimant: options.claimant.signer.descriptor,
                 abilities,
             }, claimSigner);
+            // The journal before the claim: a lost answer is resolved from it.
+            await writeClaimJournal(options.storage, options.secrets, R, {
+                v: 1,
+                resourceId: toHex(R),
+                invitationGrantId: toHex(invitation.grantId),
+                claimant: toHex(options.claimant.signer.descriptor.principalId),
+                claim: toHex(claim.bytes),
+                expectedHead: toHex(chain.state.head),
+                chain: chain.records.map((r) => toHex(r.signed.bytes)),
+                epochs: [...deks.keys()],
+                abilities: abilities.map(String),
+            }, deks, exportSecretKeyBytes);
             const answer = await s.request(createMessage("CONTROL_PUT", {
                 resourceId: R,
                 expectedHead: chain.state.head,
@@ -345,6 +400,7 @@ export async function acceptInvitation(options) {
                 if (claimed.kind !== "linear")
                     fail("INVALID_CONTROL_CHAIN", "the acknowledged claim does not validate locally");
                 await persist(options, claimed, deks);
+                await clearClaimJournal(options.storage, R);
                 return Object.freeze({
                     kind: "claimed",
                     resourceId: R,
@@ -352,6 +408,7 @@ export async function acceptInvitation(options) {
                     abilities: Object.freeze([...abilities]),
                     epochs: Object.freeze([...deks.keys()].map((e) => BigInt(e))),
                     attempts: Object.freeze(attempts),
+                    resumed: false,
                 });
             }
             if (answer.type !== "NACK")
@@ -360,13 +417,18 @@ export async function acceptInvitation(options) {
             attempts.push(code);
             const head = answer.body.details;
             // One refresh after a lost race (§73); the coordinator's next answer is final.
-            if (code !== "CONTROL_HEAD_MISMATCH" || attempts.length > 1 || !(head instanceof Uint8Array))
+            if (code !== "CONTROL_HEAD_MISMATCH" ||
+                attempts.length > 1 ||
+                !(head instanceof Uint8Array)) {
+                // A refused claim was not committed: nothing to resume.
+                await clearClaimJournal(options.storage, R);
                 return Object.freeze({
                     kind: "refused",
                     resourceId: R,
                     code,
                     attempts: Object.freeze(attempts),
                 });
+            }
             chain = await fetchChain(s, R, chain.records.map((r) => r.signed.bytes), { head });
         }
     }
@@ -379,6 +441,89 @@ export async function acceptInvitation(options) {
         s.close();
     }
 }
+/**
+ * LFCP-02-110: sends a journaled claim again. A coordinator answers a
+ * record it has already committed with the same ACK (§47, §70): then the
+ * claim landed before and the claimant joins from the journal. Any other
+ * answer means it was not committed: a moved head lets the caller claim
+ * anew ("not-committed"); another refusal is final. A transport stop
+ * throws Unavailable and keeps the journal.
+ */
+async function settleJournal(s, options, R, journal) {
+    const claim = fromHex(journal.claim);
+    const answer = await s.request(createMessage("CONTROL_PUT", {
+        resourceId: R,
+        expectedHead: fromHex(journal.expectedHead),
+        record: claim,
+    }), "the CONTROL_PUT answer")();
+    if (answer.type === "ACK") {
+        const claimed = validateControlChain([...journal.chain.map(fromHex), claim]);
+        if (claimed.kind !== "linear")
+            fail("INVALID_CONTROL_CHAIN", "the journaled claim does not validate locally");
+        const deks = await journaledDeks(options.secrets, R, journal);
+        await persist(options, claimed, deks);
+        await clearClaimJournal(options.storage, R);
+        return Object.freeze({
+            kind: "claimed",
+            resourceId: R,
+            grantId: claimed.state.head,
+            abilities: Object.freeze(journal.abilities.map((a) => BigInt(a))),
+            epochs: Object.freeze([...deks.keys()].map((e) => BigInt(e))),
+            attempts: Object.freeze(["ACK"]),
+            resumed: true,
+        });
+    }
+    if (answer.type !== "NACK")
+        throw new Unavailable(`CONTROL_PUT was answered with ${answer.type}`);
+    await clearClaimJournal(options.storage, R);
+    const code = codeName(answer.body.code);
+    if (code === "CONTROL_HEAD_MISMATCH")
+        return "not-committed";
+    return Object.freeze({
+        kind: "refused",
+        resourceId: R,
+        code,
+        attempts: Object.freeze([code]),
+    });
+}
+/**
+ * Settles a journaled claim without its link, e.g. after a restart
+ * (LFCP-02-110): "claimed" when the claim had landed; "not-claimed" when it
+ * had not (the journal is removed, and the link, still unused, can be
+ * accepted again); "refused" for another refusal; "unavailable" keeps the
+ * journal for a later try; "none" when no claim is journaled.
+ */
+export async function resumeInvitationClaim(options) {
+    const R = options.resourceId;
+    const journal = await readClaimJournal(options.storage, R);
+    if (journal === undefined)
+        return Object.freeze({ kind: "none", resourceId: R });
+    const s = new ClaimSession({
+        url: options.url,
+        signer: options.claimant.signer,
+        now: options.now,
+        ...(options.webSocket === undefined ? {} : { webSocket: options.webSocket }),
+    }, options.timeout ?? NEVER);
+    try {
+        await s.connect();
+        const settled = await settleJournal(s, options, R, journal);
+        return settled === "not-committed"
+            ? Object.freeze({ kind: "not-claimed", resourceId: R })
+            : settled;
+    }
+    catch (e) {
+        if (e instanceof Unavailable)
+            return Object.freeze({ kind: "unavailable", resourceId: R, reason: e.message });
+        throw e;
+    }
+    finally {
+        s.close();
+    }
+}
+/** Gives up a journaled claim (the user declined to retry it): its journal is removed. */
+export async function abandonInvitationClaim(storage, resource) {
+    await clearClaimJournal(storage, resource);
+}
 /** The claimant's storage: the chain with its grant, then each DEK before the row that names it (LFCP-034). */
 async function persist(options, chain, deks) {
     const R = chain.state.resourceId;

package/dist/outbound.d.ts

@@ -1,5 +1,5 @@
 import { type ActorSequence, type ControlRecordId, type DataEpoch, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
-import type { LfcpStorage, OutboundBlock, OutboundItem, OutboundKind } from "@openlfcp/storage";
+import type { LfcpStorage, OutboundBlock, OutboundItem, OutboundKind, StorageWrite } from "@openlfcp/storage";
 import { type ControlView, type HaveVector, type LfcpMessage, type WireErrorName } from "@openlfcp/wire";
 /**
  * The pending outbound queue and its sync state (LFCP-036): a
@@ -66,6 +66,20 @@ export interface AckOutcome {
     /** False when the ACK answers no message of this session (matched by object ID only). */
     readonly correlated: boolean;
 }
+/** An item an ACK removed from the queue, for writes that go with its removal. */
+export interface AckedItem {
+    readonly itemId: Hash32;
+    readonly resourceId: ResourceId;
+    readonly kind: OutboundKind;
+}
+/**
+ * Writes committed in the same transaction as an ACK's dequeue, from the
+ * items it removed and what the ACK established (e.g. batch acceptance).
+ */
+export type AckWrites = (acked: readonly AckedItem[], ack: {
+    readonly durability: bigint;
+    readonly correlated: boolean;
+}) => Promise<readonly StorageWrite[]>;
 /** A blocked item as surfaced to the application. */
 export interface BlockedItem {
     readonly itemId: Hash32;
@@ -186,9 +200,10 @@ export declare class OutboundQueue {
      * An ACK (§59): removes the queued items whose IDs it names (field 1),
      * and records them in the Resource's sync state. Items of the
      * acknowledged message it does not name stay queued. Idempotent: a
-     * repeated ACK, or one for items already gone, changes nothing.
+     * repeated ACK, or one for items already gone, changes nothing. `also`
+     * adds writes to the dequeue's transaction.
      */
-    onAck(message: LfcpMessage<"ACK">, now: string): Promise<AckOutcome>;
+    onAck(message: LfcpMessage<"ACK">, now: string, also?: AckWrites): Promise<AckOutcome>;
     /**
      * A NACK (§60) of one of this session's messages. Per-object codes on a
      * message of several objects resend each object alone, to learn which one
@@ -224,6 +239,13 @@ export declare class OutboundQueue {
      * are sent as the same bytes.
      */
     reconcileEpochs(view: ControlView): Promise<StaleOutboundUnit[]>;
+    /**
+     * Drops all in-memory tracking of these items, which a re-proposal has
+     * replaced with re-authored ones in storage (repropose.ts). The items are
+     * already dequeued in that same transaction; this clears any stale flight,
+     * solo or awaiting-control state so the queue never looks for them again.
+     */
+    release(ids: readonly Hash32[]): void;
     /** Removes a blocked item once the application has dealt with it (e.g. re-proposed or re-applied). */
     discard(itemId: Hash32): Promise<void>;
 }

package/dist/outbound.js

@@ -36,6 +36,8 @@ const PER_OBJECT = new Set([
 const CODE_NAMES = new Map(Object.entries(ERROR_CODE).map(([name, code]) => [code, name]));
 /** Room left in a message for the envelope and body around the objects. */
 const OVERHEAD = 1024;
+/** How many expired flights are remembered for a late answer. */
+const EXPIRED_KEPT = 1024;
 const AT_ONCE = { nextAttempt: () => null };
 /** Data Units by actor, then actor sequence; unparsable bytes last (they are blocked when sent). */
 function unitOrder(a, b) {
@@ -65,6 +67,16 @@ export class OutboundQueue {
     #maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES;
     /** message ID hex → what it carried */
     #flights = new Map();
+    /**
+     * Flights that expired unanswered (#expire), by message ID, the most
+     * recent {@link EXPIRED_KEPT}: a late answer to one is still an answer to
+     * our message, correlated for §4.1's acceptance evidence. Without them, an
+     * ACK handled after the timeout sweep (a busy event loop: the sweep's
+     * timer runs before the waiting message) dequeued the items as
+     * uncorrelated, their batch was "evidence-unavailable" for good, and no
+     * later ACK could change it (the Shared Tasks soak of 0.4.0-beta.17).
+     */
+    #expired = new Map();
     /** item ID hex → message ID hex */
     #inFlight = new Map();
     /**
@@ -99,6 +111,9 @@ export class OutboundQueue {
             if (flight.deadline > at)
                 continue;
             this.#flights.delete(key);
+            this.#expired.set(key, flight);
+            if (this.#expired.size > EXPIRED_KEPT)
+                this.#expired.delete(this.#expired.keys().next().value);
             for (const id of flight.itemIds)
                 if (this.#inFlight.get(toHex(id)) === key) {
                     this.#inFlight.delete(toHex(id));
@@ -261,8 +276,12 @@ export class OutboundQueue {
             return undefined;
         const key = toHex(messageId);
         const flight = this.#flights.get(key);
-        if (flight === undefined)
-            return undefined;
+        if (flight === undefined) {
+            // A late answer to a message whose flight expired: ours, correlated.
+            const late = this.#expired.get(key);
+            this.#expired.delete(key);
+            return late;
+        }
         this.#flights.delete(key);
         for (const id of flight.itemIds) {
             if (this.#inFlight.get(toHex(id)) === key)
@@ -294,14 +313,16 @@ export class OutboundQueue {
      * An ACK (§59): removes the queued items whose IDs it names (field 1),
      * and records them in the Resource's sync state. Items of the
      * acknowledged message it does not name stay queued. Idempotent: a
-     * repeated ACK, or one for items already gone, changes nothing.
+     * repeated ACK, or one for items already gone, changes nothing. `also`
+     * adds writes to the dequeue's transaction.
      */
-    async onAck(message, now) {
+    async onAck(message, now, also) {
         const flight = this.#land(message.correlationId);
         const named = message.body.objectIds ?? [];
         const durability = message.body.durable === true ? this.#durability : 0n;
         const requestType = message.body.requestType;
         const acked = [];
+        const ackedItems = [];
         const below = [];
         const byResource = new Map();
         for (const id of named) {
@@ -317,6 +338,7 @@ export class OutboundQueue {
                 continue;
             }
             acked.push(item.itemId);
+            ackedItems.push({ itemId: item.itemId, resourceId: item.resourceId, kind: item.kind });
             const key = toHex(item.resourceId);
             byResource.set(key, [...(byResource.get(key) ?? []), item.itemId]);
             this.#forget(item.itemId);
@@ -345,6 +367,8 @@ export class OutboundQueue {
                 },
             });
         }
+        if (also !== undefined && ackedItems.length > 0)
+            writes.push(...(await also(ackedItems, { durability, correlated: flight !== undefined })));
         await this.#commit(writes);
         const notCovered = flight?.itemIds.filter((id) => !acked.some((a) => bytesEqual(a, id)) && !below.some((b) => bytesEqual(b, id))) ?? [];
         const stillQueued = [];
@@ -558,6 +582,16 @@ export class OutboundQueue {
         await this.#commit(writes);
         return out;
     }
+    /**
+     * Drops all in-memory tracking of these items, which a re-proposal has
+     * replaced with re-authored ones in storage (repropose.ts). The items are
+     * already dequeued in that same transaction; this clears any stale flight,
+     * solo or awaiting-control state so the queue never looks for them again.
+     */
+    release(ids) {
+        for (const id of ids)
+            this.#forget(id);
+    }
     /** Removes a blocked item once the application has dealt with it (e.g. re-proposed or re-applied). */
     async discard(itemId) {
         const item = await this.#storage.outbound.get(itemId);

package/dist/queue.d.ts

@@ -19,6 +19,8 @@ export declare const outboundItem: (kind: OutboundKind, itemId: Hash32, resource
  * (adoptStoredDeks) with no network round trip.
  */
 export declare function queueKeyEpoch(storage: Pick<LfcpStorage, "commit">, secrets: SecretStore, rotation: EpochRotation, also?: readonly StorageWrite[]): Promise<Hash32>;
+/** The writes that store a sealed Key Package (§25) and queue it, for one commit with others. */
+export declare function keyPackageWrites(bytes: Uint8Array): StorageWrite[];
 /** Stores a sealed Key Package (§25) and queues it for KEY_PACKAGE_PUT. */
 export declare function queueKeyPackage(storage: Pick<LfcpStorage, "commit">, bytes: Uint8Array, also?: readonly StorageWrite[]): Promise<Hash32>;
 /** Stores a sealed Snapshot (§29) with its selection metadata and queues it for SNAPSHOT_PUT. */
@@ -35,4 +37,6 @@ export declare function createQueuedSnapshot<T>(storage: Pick<LfcpStorage, "snap
  * validated chain contains it (saveControlChain).
  */
 export declare function queueControlRecord(storage: Pick<LfcpStorage, "commit">, bytes: Uint8Array, also?: readonly StorageWrite[]): Promise<Hash32>;
+/** The write that queues a signed Control Record for CONTROL_PUT, for one commit with others. */
+export declare function controlRecordWrites(bytes: Uint8Array): StorageWrite[];
 //# sourceMappingURL=queue.d.ts.map

package/dist/queue.js

@@ -39,12 +39,12 @@ export async function queueKeyEpoch(storage, secrets, rotation, also = []) {
     await secrets.put(dekSecretRef(resource, rotation.epoch), exportSecretKeyBytes(rotation.dek));
     return queueControlRecord(storage, rotation.bytes, also);
 }
-/** Stores a sealed Key Package (§25) and queues it for KEY_PACKAGE_PUT. */
-export async function queueKeyPackage(storage, bytes, also = []) {
+/** The writes that store a sealed Key Package (§25) and queue it, for one commit with others. */
+export function keyPackageWrites(bytes) {
     const parsed = parseKeyPackage(bytes);
     const p = parsed.payload;
     const id = hash32(parsed.signed.id);
-    await commit(storage, [
+    return [
         {
             op: "put-key-package",
             row: {
@@ -57,9 +57,12 @@ export async function queueKeyPackage(storage, bytes, also = []) {
             },
         },
         { op: "enqueue", item: outboundItem("key-package", id, p.resourceId, parsed.signed.bytes) },
-        ...also,
-    ]);
-    return id;
+    ];
+}
+/** Stores a sealed Key Package (§25) and queues it for KEY_PACKAGE_PUT. */
+export async function queueKeyPackage(storage, bytes, also = []) {
+    await commit(storage, [...keyPackageWrites(bytes), ...also]);
+    return hash32(parseKeyPackage(bytes).signed.id);
 }
 /** Stores a sealed Snapshot (§29) with its selection metadata and queues it for SNAPSHOT_PUT. */
 export async function queueSnapshot(storage, bytes, also = []) {
@@ -100,17 +103,20 @@ export async function createQueuedSnapshot(storage, options, also = []) {
  * validated chain contains it (saveControlChain).
  */
 export async function queueControlRecord(storage, bytes, also = []) {
+    await commit(storage, [...controlRecordWrites(bytes), ...also]);
+    return hash32(parseControlRecord(bytes).signed.id);
+}
+/** The write that queues a signed Control Record for CONTROL_PUT, for one commit with others. */
+export function controlRecordWrites(bytes) {
     const parsed = parseControlRecord(bytes);
     if (parsed.payload.prevControlId === null)
         throw new Error("a Genesis record is hosted with RESOURCE_HOST, not CONTROL_PUT");
     const id = hash32(parsed.signed.id);
-    await commit(storage, [
+    return [
         {
             op: "enqueue",
             item: outboundItem("control-record", id, parsed.payload.resourceId, parsed.signed.bytes),
         },
-        ...also,
-    ]);
-    return id;
+    ];
 }
 //# sourceMappingURL=queue.js.map

package/dist/receipts.d.ts

@@ -0,0 +1,60 @@
+import { type DataUnitId, type ResourceId } from "@openlfcp/core";
+import type { LfcpStorage, StorageWrite } from "@openlfcp/storage";
+/**
+ * Commit receipts (SDK-SECTIONS-INTEGRATION-01 §3, LFCP-02-025): the
+ * durable record that a batch of intents was committed locally, written in
+ * the same storage transaction as its Data Units, outbound entries and
+ * profile checkpoint (commitOperation). A receipt is kept as a local mark
+ * under its Resource and operation ID until the caller releases it.
+ *
+ * Released before its batch is final (accepted or rejected, §4.1), a
+ * receipt is no longer the caller's: receiptOf and receiptsOf no longer
+ * return it. Its batch is still reported (batchStatuses, the status
+ * snapshot) until it is final, and then forgotten; for that the receipt is
+ * kept under a `released-batch:` mark.
+ */
+/** §3.2: what a committed batch produced. */
+export interface Receipt {
+    readonly operationId: string;
+    /** The Data Unit IDs of the batch, in the order of their changes. */
+    readonly unitIds: readonly DataUnitId[];
+    /** The nodes the batch writes (and the section when it writes the title). */
+    readonly affectedNodeIds: readonly string[];
+    /** The local document's heads after the commit, sorted, as one opaque string. */
+    readonly modelRevision: string;
+    /** §3.3: SHA-256 (hex) of the batch's canonical form. */
+    readonly intentsHash: string;
+    /** Always true: a receipt exists only for a durable commit. */
+    readonly durable: true;
+}
+/** §3.3: an operation ID that already has a receipt for different intents. A local SDK error. */
+export declare class OperationIdReusedError extends Error {
+    readonly operationId: string;
+    readonly code = "OPERATION_ID_REUSED";
+    constructor(operationId: string);
+}
+/**
+ * §3.3: SHA-256 (hex) of the deterministic CBOR (RFC 8949 §4.2.1) of the
+ * list of intents in order, each a map from its field names to their
+ * values, Text as given, nothing normalized.
+ */
+export declare function intentsHash(intents: readonly unknown[]): string;
+/** The local-mark write that stores `receipt` (for the commit's transaction). */
+export declare function receiptWrite(resource: ResourceId, receipt: Receipt): StorageWrite;
+/** §3.4: the receipt of an operation, definitive across restarts; undefined when nothing was committed. */
+export declare function receiptOf(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId, operationId: string): Promise<Receipt | undefined>;
+/** The receipt of a released batch that is not final yet; undefined otherwise. */
+export declare function releasedReceiptOf(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId, operationId: string): Promise<Receipt | undefined>;
+/** The receipts of a Resource's released batches that are not final yet. */
+export declare function releasedReceiptsOf(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId): Promise<Receipt[]>;
+/** Keeps a released receipt for its batch's status (or, with null, forgets it). */
+export declare function releasedWrite(resource: ResourceId, operationId: string, receipt: Receipt | null): StorageWrite;
+/** Every receipt of a Resource that is not released yet. */
+export declare function receiptsOf(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId): Promise<Receipt[]>;
+/**
+ * §3.5: forgets a receipt the caller has finished with. Its batch status
+ * goes with it when the batch is final (accepted or rejected); otherwise
+ * the batch is still reported until it is final.
+ */
+export declare function releaseReceipt(storage: Pick<LfcpStorage, "commit" | "localMarks">, resource: ResourceId, operationId: string): Promise<void>;
+//# sourceMappingURL=receipts.d.ts.map