@openlfcp/client 0.2.0-beta.5 → 0.2.0-beta.6

package/dist/index.d.ts

@@ -11,11 +11,12 @@ export { type AcceptedInvitation, type AcceptInvitationOptions, type AcceptInvit
 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

@@ -11,11 +11,12 @@ export { abandonInvitationClaim, acceptInvitation, createInvitation, DEFAULT_INV
 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

@@ -563,6 +563,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

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

@@ -11,6 +11,7 @@ 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;
@@ -1062,6 +1065,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 +1079,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 +1802,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 +1865,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.5",
+  "version": "0.2.0-beta.6",
   "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.5",
-    "@openlfcp/crypto": "^0.2.0-beta.5",
-    "@openlfcp/wire": "^0.2.0-beta.5",
-    "@openlfcp/storage": "^0.2.0-beta.5"
+    "@openlfcp/core": "^0.2.0-beta.6",
+    "@openlfcp/crypto": "^0.2.0-beta.6",
+    "@openlfcp/storage": "^0.2.0-beta.6",
+    "@openlfcp/wire": "^0.2.0-beta.6"
   }
 }