@openlfcp/client 0.2.0-beta.1 → 0.2.0-beta.10

package/dist/connection.d.ts

@@ -1,3 +1,4 @@
+import { LfcpError } from "@openlfcp/core";
 import { type AnyMessage, type ClientConnectionState, type ClientHandshakeConfig, type ReadySession } from "@openlfcp/wire";
 /**
  * One LFCP connection over a WebSocket (LFCP-WIRE-01 §30, §31, §34-§38,
@@ -36,6 +37,14 @@ export interface WebSocketLike {
 export type WebSocketFactory = (url: string, protocols: readonly string[]) => WebSocketLike;
 /** The platform WebSocket (globalThis.WebSocket); throws if the runtime has none. */
 export declare function platformWebSocket(): WebSocketFactory;
+/**
+ * A send on a connection that is not READY: it closed while the caller was
+ * working (an ordinary network loss, not a fault of the caller's). Nothing
+ * was sent. Still an LfcpError UNSUPPORTED_VALUE, as before.
+ */
+export declare class ConnectionNotReady extends LfcpError {
+    constructor();
+}
 /** §30: the only LFCP subprotocol. */
 export declare const LFCP_SUBPROTOCOL = "lfcp-1";
 export interface ConnectionEvents {

package/dist/connection.js

@@ -7,6 +7,17 @@ export function platformWebSocket() {
         throw new LfcpError("UNSUPPORTED_VALUE", "this runtime has no global WebSocket; inject a factory");
     return (url, protocols) => new ctor(url, [...protocols]);
 }
+/**
+ * A send on a connection that is not READY: it closed while the caller was
+ * working (an ordinary network loss, not a fault of the caller's). Nothing
+ * was sent. Still an LfcpError UNSUPPORTED_VALUE, as before.
+ */
+export class ConnectionNotReady extends LfcpError {
+    constructor() {
+        super("UNSUPPORTED_VALUE", "the connection is not READY");
+        this.name = "ConnectionNotReady";
+    }
+}
 /** §30: the only LFCP subprotocol. */
 export const LFCP_SUBPROTOCOL = "lfcp-1";
 const BYTES = (data) => {
@@ -147,7 +158,7 @@ export class LfcpConnection {
     /** Sends already encoded message bytes (e.g. an OutboundMessage) on a READY session. */
     sendEncoded(bytes) {
         if (this.#state !== "READY" || this.#socket === null)
-            throw new LfcpError("UNSUPPORTED_VALUE", "the connection is not READY");
+            throw new ConnectionNotReady();
         if (bytes.length > this.#limit())
             throw new LfcpError("MESSAGE_TOO_LARGE", `${bytes.length} bytes exceed the session limit ${this.#limit()}`);
         this.#socket.send(bytes);

package/dist/data-unit.js

@@ -23,10 +23,12 @@ export async function createDataUnit(options) {
     const plaintext = options.profile.encode(options.value);
     const seq = await options.sequences.reserveNext(atHead.resourceId, actor);
     options.guard?.claim(atHead.resourceId, actor, seq);
-    if ((seq === 1n) !== (options.previousUnitId === null))
-        throw new LfcpError("INVALID_STRUCTURE", seq === 1n
-            ? "the actor's first unit (sequence 1) must have a null previous unit (§26.2)"
-            : `sequence ${seq} needs the actor's unit at sequence ${seq - 1n} as its previous unit (§26.2)`);
+    // §26.2: sequence 1 names no previous unit. A later one names the writer's
+    // latest own unit still accepted, or none: after a first unit that went
+    // stale (a Key Epoch cut it off) or was abandoned, the unit at 2 has a null
+    // previous, and a receiver that accepted nothing of the actor links it.
+    if (seq === 1n && options.previousUnitId !== null)
+        throw new LfcpError("INVALID_STRUCTURE", "the actor's first unit (sequence 1) must have a null previous unit (§26.2)");
     const sealed = sealDataUnit({
         resourceId: atHead.resourceId,
         dataEpoch: epoch,

package/dist/index.d.ts

@@ -4,18 +4,19 @@ export { type ApplyOutcome, type DataProfileHandler, DataUnitApplier, type DataU
 export { ACCEPTANCE_DURABILITY, type BatchStatus, type BatchStatusName, batchStatus, batchStatuses, } from "./batch-status.js";
 export { type CheckpointSource, ProfileCheckpointer } from "./checkpoint.js";
 export { type ClaimJournal, pendingInvitationClaims } from "./claim-journal.js";
-export { type ConnectionEvents, type ConnectionOptions, LFCP_SUBPROTOCOL, LfcpConnection, platformWebSocket, type WebSocketFactory, type WebSocketLike, } from "./connection.js";
+export { type ConnectionEvents, ConnectionNotReady, type ConnectionOptions, LFCP_SUBPROTOCOL, LfcpConnection, platformWebSocket, type WebSocketFactory, type WebSocketLike, } from "./connection.js";
 export { type CreateDataUnitOptions, type CreatedDataUnit, createDataUnit } from "./data-unit.js";
 export { EngineGuard, type EngineItem, isEngineTrap, type Suspicion, snapshotItem, unitItem, } from "./engine-guard.js";
 export { type AcceptedInvitation, type AcceptInvitationOptions, type AcceptInvitationProgress, type AcceptInvitationStage, abandonInvitationClaim, acceptInvitation, type CreatedInvitation, type CreateInvitationOptions, createInvitation, DEFAULT_INVITATION_ABILITIES, InvitationLink, type ResumeInvitationClaimOptions, resumeInvitationClaim, } from "./invite.js";
 export { type AckedItem, type AckOutcome, type AckWrites, type BlockedItem, exponentialBackoff, type NackOutcome, type OutboundMessage, OutboundQueue, type OutboundQueueOptions, type ResourceSyncState, type RetryPolicy, type RetryReason, resourceSyncState, type StaleOutboundUnit, snapshotFrontier, } from "./outbound.js";
 export { controlRecordWrites, createQueuedSnapshot, keyPackageWrites, outboundItem, queueControlRecord, queueKeyEpoch, queueKeyPackage, queueSnapshot, } from "./queue.js";
 export { intentsHash, OperationIdReusedError, type Receipt, receiptOf, receiptsOf, releaseReceipt, } from "./receipts.js";
+export { type ReproposeDropReason, type ReproposeOutcome, type ReproposeResult, reproposeControlRecords, } from "./repropose.js";
 export { type ResourcePhase, type ResourcePhaseEvent, resourcePhaseTransition, } from "./resource-state.js";
 export { planRevocation, type RemainingPath, type RevocationPlan, type RevocationRefusal, RevocationRefused, } from "./revoke.js";
 export { type CatchUp, type ReceivedFact, type ReceivedState, type ReofferReason, receivedState, type SectionState, type StatusEvent, type StatusSnapshot, } from "./section-status.js";
 export { type CreatedSnapshot, type CreateSnapshotOptions, createSnapshot } from "./snapshot.js";
-export { adoptStoredDeks, type CommitOperationOptions, commitOperation, createQueuedDataUnit, dataUnitRow, dekResolver, latestAcceptedOwnUnit, loadControlChain, StoredSeenUnits, saveControlChain, saveControlConflict, } from "./storage.js";
+export { adoptStoredDeks, type CommitOperationOptions, commitOperation, createQueuedDataUnit, dataUnitRow, dekResolver, latestAcceptedOwnUnit, loadControlChain, localControlChain, StoredSeenUnits, saveControlChain, saveControlConflict, } from "./storage.js";
 export { type CommitBinding, CommitRefusedError, defaultReconnect, type ReconnectPolicy, type ResourceBinding, type ResourceRefusal, type RevokeAccessResult, type SnapshotBinding, type StagedOperation, SyncClient, type SyncClientOptions, type SyncEvent, startSyncDriver, TERMINAL_RESOURCE_CODES, } from "./sync-client.js";
 export { type Flushed, type Submitted, TypingCoalescer, type TypingCoalescerOptions, } from "./typing.js";
 export { type AccessContext, type AccessState, accessState, type GrantPath, type IssuedInvitation, NotWritableError, type PendingControl, type ServerRefusal, UNKNOWN_ACCESS, type WriteAccess, type WriteDeniedReason, writeAccess, } from "./write-access.js";

package/dist/index.js

@@ -4,18 +4,19 @@ export { DataUnitApplier, } from "./apply.js";
 export { ACCEPTANCE_DURABILITY, batchStatus, batchStatuses, } from "./batch-status.js";
 export { ProfileCheckpointer } from "./checkpoint.js";
 export { pendingInvitationClaims } from "./claim-journal.js";
-export { LFCP_SUBPROTOCOL, LfcpConnection, platformWebSocket, } from "./connection.js";
+export { ConnectionNotReady, LFCP_SUBPROTOCOL, LfcpConnection, platformWebSocket, } from "./connection.js";
 export { createDataUnit } from "./data-unit.js";
 export { EngineGuard, isEngineTrap, snapshotItem, unitItem, } from "./engine-guard.js";
 export { abandonInvitationClaim, acceptInvitation, createInvitation, DEFAULT_INVITATION_ABILITIES, InvitationLink, resumeInvitationClaim, } from "./invite.js";
 export { exponentialBackoff, OutboundQueue, resourceSyncState, snapshotFrontier, } from "./outbound.js";
 export { controlRecordWrites, createQueuedSnapshot, keyPackageWrites, outboundItem, queueControlRecord, queueKeyEpoch, queueKeyPackage, queueSnapshot, } from "./queue.js";
 export { intentsHash, OperationIdReusedError, receiptOf, receiptsOf, releaseReceipt, } from "./receipts.js";
+export { reproposeControlRecords, } from "./repropose.js";
 export { resourcePhaseTransition, } from "./resource-state.js";
 export { planRevocation, RevocationRefused, } from "./revoke.js";
 export { receivedState, } from "./section-status.js";
 export { createSnapshot } from "./snapshot.js";
-export { adoptStoredDeks, commitOperation, createQueuedDataUnit, dataUnitRow, dekResolver, latestAcceptedOwnUnit, loadControlChain, StoredSeenUnits, saveControlChain, saveControlConflict, } from "./storage.js";
+export { adoptStoredDeks, commitOperation, createQueuedDataUnit, dataUnitRow, dekResolver, latestAcceptedOwnUnit, loadControlChain, localControlChain, StoredSeenUnits, saveControlChain, saveControlConflict, } from "./storage.js";
 export { CommitRefusedError, defaultReconnect, SyncClient, startSyncDriver, TERMINAL_RESOURCE_CODES, } from "./sync-client.js";
 export { TypingCoalescer, } from "./typing.js";
 export { accessState, NotWritableError, UNKNOWN_ACCESS, writeAccess, } from "./write-access.js";

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;

package/dist/invite.js

@@ -1,11 +1,11 @@
 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
@@ -69,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
@@ -78,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");
@@ -290,10 +316,16 @@ export async function acceptInvitation(options) {
         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))
@@ -338,7 +370,7 @@ 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);

package/dist/outbound.d.ts

@@ -239,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)
@@ -563,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/repropose.d.ts

@@ -0,0 +1,81 @@
+import { type ControlRecordId, type Hash32, type ResourceId } from "@openlfcp/core";
+import { type LfcpStorage, type SecretStore } from "@openlfcp/storage";
+import { type Signer } from "@openlfcp/wire";
+import type { OutboundQueue } from "./outbound.js";
+/**
+ * Re-proposing this client's own Control Records that the coordinator
+ * refused with CONTROL_HEAD_MISMATCH (LFCP-WIRE-01 §21, §47; the LFCP-036
+ * design). A record proposed on a head that another writer moved is blocked
+ * "repropose" by the OutboundQueue; without this it — and every object that
+ * depends on it, such as a grant's invitation Key Package — would wait
+ * forever. Here each blocked record is re-authored on the current local
+ * head, keeping its intent, re-signed with a new record ID, and its
+ * dependent Key Packages are re-sealed to the new head; a record that is no
+ * longer authorized or meaningful is dropped with a typed outcome instead.
+ *
+ * Only the GRANT and REVOKE intents are re-authored: a revocation/rotation
+ * is serialized at the author (SyncClient.revokeAccess refuses while a
+ * Control Record is pending), so a KEY_EPOCH never reaches re-proposal; one
+ * that somehow does is dropped (its epoch number, DEK commitment and final
+ * frontier are bound to the head it was built on) and surfaced, so the
+ * application re-runs the high-level operation.
+ *
+ * Re-authoring is idempotent (a grant already on the chain with the same
+ * subject and abilities is treated as superseded, not duplicated) and
+ * bounded (an item re-proposed `maxAttempts` times without landing is
+ * dropped), so a head that keeps moving cannot loop.
+ */
+export type ReproposeDropReason = 
+/** The blocked record was not authored by this client, so it cannot be re-signed. */
+"not-author"
+/** An equivalent grant is already on the chain: this one was re-proposed before. */
+ | "superseded"
+/** The intent is no longer authorized on the moved head. */
+ | "unauthorized"
+/** A revocation whose target grant is already inactive on the moved head. */
+ | "already-revoked"
+/** A dependent Key Package's DEK is not held, so it cannot be re-sealed. */
+ | "no-dek"
+/** A dependent Key Package no longer verifies on the moved head. */
+ | "key-unauthorized"
+/** A KEY_EPOCH or other intent that is not re-authored here. */
+ | "unsupported-intent"
+/** Re-proposed too many times without landing (the head kept moving). */
+ | "attempts-exhausted";
+export type ReproposeOutcome = {
+    readonly kind: "reproposed";
+    readonly oldId: ControlRecordId;
+    readonly newId: ControlRecordId;
+    /** The dependent Key Packages re-sealed to the new head, old ID → new ID. */
+    readonly keyPackages: readonly {
+        readonly oldId: Hash32;
+        readonly newId: Hash32;
+    }[];
+} | {
+    readonly kind: "dropped";
+    readonly oldId: ControlRecordId;
+    readonly reason: ReproposeDropReason;
+};
+export interface ReproposeResult {
+    readonly outcomes: readonly ReproposeOutcome[];
+}
+export interface ReproposeOptions {
+    readonly storage: Pick<LfcpStorage, "control" | "outbound" | "commit">;
+    readonly secrets: SecretStore;
+    readonly signer: Signer;
+    readonly resource: ResourceId;
+    /** For dropping in-memory tracking of the items a re-proposal replaces. */
+    readonly queue: OutboundQueue;
+    /** Re-proposal attempts per blocked record (by item ID hex), owned by the caller. */
+    readonly attempts: Map<string, number>;
+    /** The cap after which an item is dropped "attempts-exhausted" (default 8). */
+    readonly maxAttempts?: number;
+}
+/**
+ * Re-proposes every blocked "repropose" Control Record of `resource`, in
+ * record order, each on the local head left by the ones before it. Returns
+ * one outcome per blocked record. Call it under the same serial lock as the
+ * queue, so no other record is authored meanwhile.
+ */
+export declare function reproposeControlRecords(options: ReproposeOptions): Promise<ReproposeResult>;
+//# sourceMappingURL=repropose.d.ts.map

package/dist/repropose.js

@@ -0,0 +1,221 @@
+import { bytesEqual, controlRecordId, hash32, toHex, } from "@openlfcp/core";
+import { importResourceDEK } from "@openlfcp/crypto";
+import { dekSecretRef, } from "@openlfcp/storage";
+import { controlRecordSigner, decodeControlRecord, isGrantActive, parseKeyPackage, sealKeyPackage, signControlRecord, validateControlChain, verifyKeyPackage, } from "@openlfcp/wire";
+import { controlRecordWrites, keyPackageWrites } from "./queue.js";
+import { localControlChain } from "./storage.js";
+/** The descriptor of `principal` from the validated chain (its principals, owner or a grant subject). */
+function descriptorOf(state, principal) {
+    const known = state.principals.get(toHex(principal));
+    if (known !== undefined)
+        return known;
+    if (bytesEqual(state.owner.principalId, principal))
+        return state.owner;
+    return undefined;
+}
+/** An active grant on `state` with the same subject and ability set (a prior re-proposal of this grant). */
+function equivalentGrant(state, subject, abilities) {
+    const want = [...abilities].map(String).sort().join(",");
+    for (const g of state.grants.values())
+        if (bytesEqual(g.subject, subject) &&
+            isGrantActive(state, g.id) &&
+            [...g.abilities].map(String).sort().join(",") === want)
+            return true;
+    return false;
+}
+/** Re-signs a record on the local head and checks it extends the chain linearly; undefined when it does not. */
+function reauthor(local, sign) {
+    const signed = sign({
+        resourceId: local.state.resourceId,
+        controlSeq: local.state.seq + 1n,
+        prevControlId: local.state.head,
+    });
+    const next = validateControlChain([...local.records.map((r) => r.signed.bytes), signed.bytes]);
+    if (next.kind !== "linear")
+        return undefined;
+    return { bytes: signed.bytes, newId: signed.recordId, next };
+}
+/** Re-seals every queued Key Package that depended on `oldHead` to the re-proposed `newHead`/`next`. */
+async function resealDependents(options, next, oldHead, newHead) {
+    const removed = [];
+    const added = [];
+    const mapping = [];
+    for (const item of await options.storage.outbound.list(options.resource)) {
+        if (item.kind !== "key-package")
+            continue;
+        let controlHead;
+        let recipientId;
+        let epoch;
+        try {
+            const p = parseKeyPackage(item.bytes).payload;
+            controlHead = p.controlHead;
+            recipientId = p.recipient;
+            epoch = p.dataEpoch;
+        }
+        catch {
+            continue;
+        }
+        if (!bytesEqual(controlHead, oldHead))
+            continue;
+        const recipient = descriptorOf(next.state, recipientId);
+        const bytes = await options.secrets.get(dekSecretRef(options.resource, epoch));
+        if (recipient === undefined || bytes === undefined)
+            return { ok: false, reason: "no-dek" };
+        const sealed = await sealKeyPackage({
+            resourceId: options.resource,
+            epoch,
+            controlHead: newHead,
+            recipient,
+            dek: importResourceDEK(bytes),
+            signer: options.signer,
+        });
+        if (verifyKeyPackage(next, parseKeyPackage(sealed.bytes)).kind !== "authorized")
+            return { ok: false, reason: "key-unauthorized" };
+        removed.push(item.itemId);
+        added.push(sealed.bytes);
+        mapping.push({ oldId: item.itemId, newId: hash32(parseKeyPackage(sealed.bytes).signed.id) });
+    }
+    return Object.freeze({ ok: true, removed, added, mapping });
+}
+/** The queued Key Packages of `resource` whose control head is `controlHead`. */
+async function dependentKeyPackages(storage, resource, controlHead) {
+    const out = [];
+    for (const item of await storage.outbound.list(resource)) {
+        if (item.kind !== "key-package")
+            continue;
+        try {
+            if (bytesEqual(parseKeyPackage(item.bytes).payload.controlHead, controlHead))
+                out.push(item.itemId);
+        }
+        catch {
+            // not a parsable Key Package: never a dependent of this head.
+        }
+    }
+    return out;
+}
+/** Enqueues the re-authored record and its re-sealed Key Packages and dequeues the old ones, in one transaction. */
+async function swap(storage, queue, change) {
+    const writes = [
+        { op: "dequeue", itemId: change.removeControl },
+        ...change.removeKeyPackages.map((itemId) => ({ op: "dequeue", itemId })),
+        ...controlRecordWrites(change.addControl),
+        ...change.addKeyPackages.flatMap(keyPackageWrites),
+    ];
+    const r = await storage.commit(writes);
+    if (!r.ok)
+        throw new Error(`the re-proposal was not committed: ${r.reason}`);
+    queue.release([change.removeControl, ...change.removeKeyPackages]);
+}
+/** Dequeues a blocked record and its dependents and drops the queue's in-memory tracking of them. */
+async function dropItem(storage, queue, ids) {
+    const r = await storage.commit(ids.map((itemId) => ({ op: "dequeue", itemId })));
+    if (!r.ok)
+        throw new Error(`a re-proposal drop was not committed: ${r.reason}`);
+    queue.release(ids);
+}
+/**
+ * Re-proposes every blocked "repropose" Control Record of `resource`, in
+ * record order, each on the local head left by the ones before it. Returns
+ * one outcome per blocked record. Call it under the same serial lock as the
+ * queue, so no other record is authored meanwhile.
+ */
+export async function reproposeControlRecords(options) {
+    const { storage, signer, resource, queue } = options;
+    const maxAttempts = options.maxAttempts ?? 8;
+    const blocked = (await storage.outbound.list(resource))
+        .filter((i) => i.kind === "control-record" && i.blocked?.reason === "repropose")
+        .map((i) => ({ itemId: i.itemId, record: decodeControlRecord(i.bytes) }))
+        .sort((a, b) => (a.record.payload.controlSeq < b.record.payload.controlSeq ? -1 : 1));
+    const outcomes = [];
+    const mine = signer.descriptor.principalId;
+    for (const { itemId, record } of blocked) {
+        const oldId = controlRecordId(record.signed.id);
+        const drop = async (reason) => {
+            options.attempts.delete(toHex(itemId));
+            await dropItem(storage, queue, [
+                itemId,
+                ...(await dependentKeyPackages(storage, resource, oldId)),
+            ]);
+            outcomes.push(Object.freeze({ kind: "dropped", oldId, reason }));
+        };
+        if (!bytesEqual(controlRecordSigner(record), mine)) {
+            await drop("not-author");
+            continue;
+        }
+        const attempt = (options.attempts.get(toHex(itemId)) ?? 0) + 1;
+        if (attempt > maxAttempts) {
+            await drop("attempts-exhausted");
+            continue;
+        }
+        options.attempts.set(toHex(itemId), attempt);
+        const local = await localControlChain(storage, resource);
+        if (local === undefined || local.kind !== "linear") {
+            await drop("unauthorized");
+            continue;
+        }
+        const body = record.body;
+        if (body.type === "CAPABILITY_GRANT") {
+            if (equivalentGrant(local.state, body.subject.principalId, body.abilities)) {
+                await drop("superseded");
+                continue;
+            }
+            const reauthored = reauthor(local, (header) => signControlRecord(header, {
+                type: "CAPABILITY_GRANT",
+                subject: body.subject,
+                abilities: body.abilities,
+                delegable: body.delegable,
+                ...(body.claimLimit === undefined ? {} : { claimLimit: body.claimLimit }),
+            }, signer));
+            if (reauthored === undefined) {
+                await drop("unauthorized");
+                continue;
+            }
+            const resealed = await resealDependents(options, reauthored.next, oldId, reauthored.newId);
+            if (!resealed.ok) {
+                await drop(resealed.reason);
+                continue;
+            }
+            await swap(storage, queue, {
+                removeControl: itemId,
+                removeKeyPackages: resealed.removed,
+                addControl: reauthored.bytes,
+                addKeyPackages: resealed.added,
+            });
+            // Carry the attempt count onto the re-authored record, so a head that
+            // keeps moving is still bounded (the count is cleared on its ACK).
+            options.attempts.delete(toHex(itemId));
+            options.attempts.set(toHex(reauthored.newId), attempt);
+            outcomes.push(Object.freeze({
+                kind: "reproposed",
+                oldId,
+                newId: reauthored.newId,
+                keyPackages: resealed.mapping,
+            }));
+            continue;
+        }
+        if (body.type === "CAPABILITY_REVOKE") {
+            if (!isGrantActive(local.state, body.grantId)) {
+                await drop("already-revoked");
+                continue;
+            }
+            const reauthored = reauthor(local, (header) => signControlRecord(header, { type: "CAPABILITY_REVOKE", grantId: body.grantId }, signer));
+            if (reauthored === undefined) {
+                await drop("unauthorized");
+                continue;
+            }
+            await swap(storage, queue, {
+                removeControl: itemId,
+                removeKeyPackages: [],
+                addControl: reauthored.bytes,
+                addKeyPackages: [],
+            });
+            options.attempts.delete(toHex(itemId));
+            options.attempts.set(toHex(reauthored.newId), attempt);
+            outcomes.push(Object.freeze({ kind: "reproposed", oldId, newId: reauthored.newId, keyPackages: [] }));
+            continue;
+        }
+        await drop("unsupported-intent");
+    }
+    return Object.freeze({ outcomes: Object.freeze(outcomes) });
+}
+//# sourceMappingURL=repropose.js.map

package/dist/storage.d.ts

@@ -34,6 +34,23 @@ export declare class StoredSeenUnits implements SeenUnits {
  * stored head back to Genesis. Undefined when nothing is stored.
  */
 export declare function loadControlChain(storage: Pick<LfcpStorage, "control">, resource: ResourceId): Promise<ChainResult | undefined>;
+/**
+ * The client's LOCAL Control Chain: the committed chain extended by this
+ * client's own queued Control Records that are still live (not yet
+ * acknowledged, and not blocked). A writer chains a new record on this
+ * local head, not the committed head, so records authored back to back
+ * (e.g. two invitations) carry consecutive sequence numbers and a linear
+ * `previous` instead of colliding on the committed head (§47,
+ * CONTROL_HEAD_MISMATCH). Blocked items are excluded: they will not land as
+ * they are, so nothing is chained on them (the re-proposal re-authors them).
+ *
+ * Returns the committed chain unchanged when there are no live pending
+ * records, `undefined` when the Resource has no stored chain, and the
+ * committed chain when the pending records do not extend it linearly (they
+ * are then left for the re-proposal to sort out, and the caller sees the
+ * committed head).
+ */
+export declare function localControlChain(storage: Pick<LfcpStorage, "control" | "outbound">, resource: ResourceId): Promise<ChainResult | undefined>;
 /**
  * Persists a validated linear chain in one atomic batch: its exact records,
  * the head (compare-and-set against `expected`), the epoch history (keeping

package/dist/storage.js

@@ -1,7 +1,7 @@
 import { actorSequence, bytesEqual, hash32, LfcpError, toHex, } from "@openlfcp/core";
 import { dekCommitment, importResourceDEK } from "@openlfcp/crypto";
 import { dekSecretRef, } from "@openlfcp/storage";
-import { parseDataUnit, validateControlChain, } from "@openlfcp/wire";
+import { parseControlRecord, parseDataUnit, validateControlChain, } from "@openlfcp/wire";
 import { receiptIndexWrites, replaceReleasedWrites } from "./batch-status.js";
 import { createDataUnit } from "./data-unit.js";
 import { intentsHash, OperationIdReusedError, receiptOf, receiptWrite, } from "./receipts.js";
@@ -87,6 +87,38 @@ export async function loadControlChain(storage, resource) {
         throw new LfcpError("INVALID_CONTROL_CHAIN", `the stored Control Records validate to sequence ${result.state.seq}, not the stored head at ${head.controlSeq} (local corruption)`);
     return result;
 }
+/**
+ * The client's LOCAL Control Chain: the committed chain extended by this
+ * client's own queued Control Records that are still live (not yet
+ * acknowledged, and not blocked). A writer chains a new record on this
+ * local head, not the committed head, so records authored back to back
+ * (e.g. two invitations) carry consecutive sequence numbers and a linear
+ * `previous` instead of colliding on the committed head (§47,
+ * CONTROL_HEAD_MISMATCH). Blocked items are excluded: they will not land as
+ * they are, so nothing is chained on them (the re-proposal re-authors them).
+ *
+ * Returns the committed chain unchanged when there are no live pending
+ * records, `undefined` when the Resource has no stored chain, and the
+ * committed chain when the pending records do not extend it linearly (they
+ * are then left for the re-proposal to sort out, and the caller sees the
+ * committed head).
+ */
+export async function localControlChain(storage, resource) {
+    const committed = await loadControlChain(storage, resource);
+    if (committed === undefined || committed.kind !== "linear")
+        return committed;
+    const pending = (await storage.outbound.list(resource))
+        .filter((i) => i.kind === "control-record" && i.blocked === null)
+        .map((i) => parseControlRecord(i.bytes))
+        .sort((a, b) => (a.payload.controlSeq < b.payload.controlSeq ? -1 : 1));
+    if (pending.length === 0)
+        return committed;
+    const extended = validateControlChain([
+        ...committed.records.map((r) => r.signed.bytes),
+        ...pending.map((p) => p.signed.bytes),
+    ]);
+    return extended.kind === "linear" ? extended : committed;
+}
 /**
  * Persists a validated linear chain in one atomic batch: its exact records,
  * the head (compare-and-set against `expected`), the epoch history (keeping
@@ -251,9 +283,13 @@ export async function createQueuedDataUnit(storage, options, also = []) {
 }
 async function createQueuedDataUnitNow(storage, options, also, resource, actor) {
     const { onCreated, previousUnitId, ...create } = options;
-    const previous = previousUnitId !== undefined
-        ? previousUnitId
-        : await latestAcceptedOwnUnit(storage, resource, actor);
+    const latest = await latestAcceptedOwnUnit(storage, resource, actor);
+    // §26.2: a null previous only when the writer holds no own unit as
+    // accepted (before its first, or after a first that went stale); while it
+    // holds one, a receiver that accepted it would hold this unit for good.
+    if (previousUnitId === null && latest !== null)
+        throw new LfcpError("INVALID_STRUCTURE", "the writer still holds an accepted own unit: its next unit names it as previous (§26.2)");
+    const previous = previousUnitId !== undefined ? previousUnitId : latest;
     const created = await createDataUnit({
         ...create,
         previousUnitId: previous,

package/dist/sync-client.d.ts

@@ -7,6 +7,7 @@ import type { ProfileCheckpointer } from "./checkpoint.js";
 import { type WebSocketFactory } from "./connection.js";
 import type { AckOutcome, NackOutcome, OutboundQueue, StaleOutboundUnit } from "./outbound.js";
 import { type Receipt } from "./receipts.js";
+import { type ReproposeOutcome } from "./repropose.js";
 import { type ResourcePhase } from "./resource-state.js";
 import { type RemainingPath, type RevocationRefusal } from "./revoke.js";
 import { type SectionState, type StatusEvent, type StatusSnapshot } from "./section-status.js";
@@ -263,6 +264,18 @@ export type SyncEvent = {
     readonly outcome: "started" | "recovered" | "ended";
     readonly reason?: string;
 }
+/**
+ * This client's own Control Records that a moved head refused
+ * (CONTROL_HEAD_MISMATCH) were re-proposed on the current head, or dropped
+ * when no longer authorized or meaningful (repropose.ts). One outcome per
+ * record; a copied invitation link keeps working, as a re-proposed grant
+ * keeps the same Invitation Principal and claim parameters.
+ */
+ | {
+    readonly type: "repropose";
+    readonly resourceId: ResourceId;
+    readonly outcomes: readonly ReproposeOutcome[];
+}
 /**
  * The server refused the Resource for good (see ResourceRefusal): it is
  * CLOSED and is not opened again until open() is called for it.

package/dist/sync-client.js

@@ -6,11 +6,12 @@ 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 { ConnectionNotReady, LfcpConnection } from "./connection.js";
 import { EngineGuard, isEngineTrap, snapshotItem } from "./engine-guard.js";
 import { resourceSyncState, snapshotFrontier } from "./outbound.js";
 import { controlRecordWrites, createQueuedSnapshot, keyPackageWrites } from "./queue.js";
 import { intentsHash, OperationIdReusedError, receiptOf } from "./receipts.js";
+import { reproposeControlRecords } from "./repropose.js";
 import { resourcePhaseTransition, } from "./resource-state.js";
 import { planRevocation, RevocationRefused, } from "./revoke.js";
 import { receivedState, } from "./section-status.js";
@@ -102,6 +103,8 @@ export class SyncClient {
     #sentAt = new Map();
     #requestTimeoutMs;
     #listeners = new Set();
+    /** Re-proposal attempts per Control Record (item ID hex), bounded; cleared on ACK (repropose.ts). */
+    #reproposeAttempts = new Map();
     #antiEntropyMs;
     /** The crash-loop breaker for Snapshot loads (EngineGuard). */
     #snapshots;
@@ -346,6 +349,11 @@ export class SyncClient {
         this.#queue = this.#queue
             .then(() => (this.#trapped ? undefined : fn()))
             .catch((e) => {
+            // The connection closed while a handler worked: nothing was sent, and
+            // its closing (queued here) starts over at the next READY. An
+            // ordinary outcome, not an INTERNAL error.
+            if (e instanceof ConnectionNotReady)
+                return;
             if (!isEngineTrap(e)) {
                 this.#emit({
                     type: "error",
@@ -531,10 +539,19 @@ export class SyncClient {
     // -------------------------------------------------------------------------
     // plumbing
     #request(request, message) {
+        try {
+            this.#connection.send(message);
+        }
+        catch (e) {
+            // Never waiting for an answer to what was not sent (the connection's
+            // closing already failed the requests it saw).
+            if (e instanceof ConnectionNotReady && request.kind === "host")
+                request.reject(new Error("the connection closed before RESOURCE_HOSTED: not READY"));
+            throw e;
+        }
         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
@@ -1062,6 +1079,12 @@ export class SyncClient {
             }
         }
         await this.#o.outbound.controlSynced(R);
+        // §47, §21: on the fresh head, re-propose our own Control Records that a
+        // moved head refused (CONTROL_HEAD_MISMATCH) and recover any persisted
+        // "repropose" items (a restart, or an older SDK). Runs here, under the
+        // serial lock, on every control sync — so it covers both the start of an
+        // open and a sync triggered by a repropose NACK; it is idempotent.
+        await this.#reproposeControl(ctx);
         if (ctx.state === "CONTROL_SYNC") {
             this.#move(ctx, "CONTROL_COMPLETE");
             this.#requestKeys(ctx, this.#o.now());
@@ -1070,6 +1093,29 @@ export class SyncClient {
             this.#requestKeys(ctx, this.#o.now());
         }
     }
+    /**
+     * Re-proposes this client's blocked "repropose" Control Records of `ctx`'s
+     * Resource on the current local head, re-sealing their dependent Key
+     * Packages, and flushes the re-authored objects. Bounded and idempotent
+     * (repropose.ts); a dropped record (no longer authorized, or a dependent's
+     * key is not held) is surfaced so the application can act.
+     */
+    async #reproposeControl(ctx) {
+        const R = ctx.binding.resourceId;
+        const { outcomes } = await reproposeControlRecords({
+            storage: this.#o.storage,
+            secrets: this.#o.secrets,
+            signer: this.#o.signer,
+            resource: R,
+            queue: this.#o.outbound,
+            attempts: this.#reproposeAttempts,
+        });
+        if (outcomes.length === 0)
+            return;
+        this.#emit({ type: "repropose", resourceId: R, outcomes });
+        if (outcomes.some((o) => o.kind === "reproposed"))
+            await this.#flush(ctx);
+    }
     // -------------------------------------------------------------------------
     // Keys (§52, §53, §66 step 2)
     async #epochsWithoutDek(ctx) {
@@ -1770,12 +1816,16 @@ export class SyncClient {
             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)
+        if (m.body.requestType === MESSAGE_TYPE.CONTROL_PUT && outcome.acked.length > 0) {
+            // A committed record is settled: clear its bounded re-proposal count.
+            for (const id of outcome.acked)
+                this.#reproposeAttempts.delete(toHex(id));
             for (const ctx of this.#resources.values())
                 if (ctx.state === "LIVE")
                     this.#refreshControl(ctx);
                 else
                     ctx.controlStale = true;
+        }
     }
     /**
      * An ACK of our CONTROL_PUT (§47) means the server committed the record
@@ -1829,10 +1879,28 @@ export class SyncClient {
                 ctx.lossReason ??= "unknown-previous";
         }
         this.#emit({ type: "nack", outcome });
+        // MISSING_DEPENDENCY: the server lacks our Control records; a sync releases the held puts.
         if (outcome.kind === "needs-control-sync")
             for (const ctx of this.#resources.values())
                 if (ctx.state === "LIVE")
                     this.#refreshControl(ctx);
+        // CONTROL_HEAD_MISMATCH: re-author the refused record on the current head
+        // (§47, §21). When we already hold that head (e.g. the winning record was
+        // pushed to us live, §65), a CONTROL_GET would return nothing and never
+        // reach #controlComplete, so re-propose here directly; otherwise sync
+        // first and #controlComplete drives it.
+        if (outcome.kind === "repropose")
+            for (const ctx of this.#resources.values()) {
+                if (ctx.state !== "LIVE")
+                    continue;
+                const head = await this.#o.storage.control.head(ctx.binding.resourceId);
+                if (outcome.currentHead !== null &&
+                    head !== undefined &&
+                    bytesEqual(head.head, outcome.currentHead))
+                    await this.#reproposeControl(ctx);
+                else
+                    this.#refreshControl(ctx);
+            }
         // §51.1: the server lost what our unit names. Its DATA_HAVE answer
         // starts the offer (§68.1), which releases the held items.
         if (outcome.kind === "needs-offer") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/client",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.10",
   "description": "LFCP client: session, Control Plane and Data Plane synchronization.",
   "keywords": [
     "openlfcp",
@@ -42,9 +42,9 @@
     "tag": "beta"
   },
   "dependencies": {
-    "@openlfcp/core": "^0.2.0-beta.1",
-    "@openlfcp/crypto": "^0.2.0-beta.1",
-    "@openlfcp/storage": "^0.2.0-beta.1",
-    "@openlfcp/wire": "^0.2.0-beta.1"
+    "@openlfcp/core": "^0.2.0-beta.10",
+    "@openlfcp/storage": "^0.2.0-beta.10",
+    "@openlfcp/wire": "^0.2.0-beta.10",
+    "@openlfcp/crypto": "^0.2.0-beta.10"
   }
 }