@openlfcp/client 0.1.5 → 0.2.0-beta.10

package/README.md

@@ -12,9 +12,9 @@ ESM only; Node.js 24 or later (browsers and Electron for every package except `@
 
 Part of the OpenLFCP TypeScript SDK, which implements the OpenLFCP MVP 0.1
 subset of [LFCP-WIRE-01](https://github.com/openlfcp/spec/blob/main/wire/LFCP-WIRE-01.md)
-at `mvp-0.1-baseline.10`, not every deferred WIRE-01 feature. It does not
+at `mvp-0.1-baseline.9`, not every deferred WIRE-01 feature. It does not
 claim full LFCP-WIRE-01 conformance. This is the MVP 0.1 release
-(`0.1.4`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
+(`0.1.3`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
 
 ## Links
 

package/dist/access-recovery.d.ts

@@ -0,0 +1,69 @@
+import { type PrincipalId } from "@openlfcp/core";
+import { type ControlRecord, type ControlState } from "@openlfcp/wire";
+/**
+ * Recovering access after a server restore (LFCP-02-106; design:
+ * `.github: docs/devel/design/member-recovery-after-restore.md`).
+ *
+ * A restored server may have lost the Control Records that grant this
+ * session's Principal `data/read`, and then refuses RESOURCE_OPEN with
+ * AUTHORIZATION_FAILED. A member whose own validated chain grants it
+ * `data/read` re-supplies the records the server lacks with CONTROL_PUT,
+ * which needs no read access (§47, §84): the server checks each record by
+ * its issuer. It learns the server's head from CONTROL_HEAD_MISMATCH,
+ * pushes the records above it oldest first, and opens again once.
+ *
+ * Security: the member uploads only records it holds, each signed by its
+ * issuer, and learns only the server's head ID (any session learns it from
+ * a mismatch). A chain that does not grant the member access sends nothing;
+ * a server head the member does not know (a revocation it has not seen, a
+ * fork) stops the recovery. Attempts are bounded.
+ *
+ * These are the pure decisions; SyncClient sends the requests.
+ */
+/** What to do next. */
+export type RecoveryStep = 
+/** CONTROL_PUT of `records[index]`, expecting `records[index - 1]`. */
+{
+    readonly kind: "push";
+    readonly index: number;
+}
+/** The server holds the whole chain now: RESOURCE_OPEN again, once. */
+ | {
+    readonly kind: "reopen";
+}
+/** No recovery: the refusal stands. */
+ | {
+    readonly kind: "final";
+    readonly reason: RecoveryEnd;
+};
+export type RecoveryEnd = 
+/** The local chain does not grant this Principal data/read: never tried. */
+"not-granted"
+/** The server holds our head: the refusal is not caused by a loss. */
+ | "server-current"
+/** The server's head is not in our chain: a record we have not seen, or a fork. */
+ | "unknown-head"
+/** The server refused a record for good, or the transient bound was reached. */
+ | "refused";
+/** Transient refusals of a recovery CONTROL_PUT, retried with backoff a bounded number of times. */
+export declare const RECOVERY_TRANSIENT_CODES: ReadonlySet<string>;
+/** How many transient refusals a recovery tolerates before it ends. */
+export declare const RECOVERY_TRANSIENT_ATTEMPTS = 3;
+/**
+ * The first step after RESOURCE_OPEN was refused with AUTHORIZATION_FAILED:
+ * push our head (the server's answer tells where its chain ends), or not
+ * at all when our chain does not grant `principal` data/read or has nothing
+ * above the Genesis to push.
+ */
+export declare function startRecovery(state: ControlState, records: readonly ControlRecord[], principal: PrincipalId): RecoveryStep;
+/** The next step after the server committed `records[index]`. */
+export declare function afterAccepted(records: readonly ControlRecord[], index: number): RecoveryStep;
+/**
+ * The next step after CONTROL_HEAD_MISMATCH naming the server's head
+ * `head`: push the record above it; open again once when the server holds
+ * our head (another holder re-supplied it meanwhile; if the refusal is not
+ * caused by a loss, the second AUTHORIZATION_FAILED is final); stop at a
+ * head we do not know.
+ */
+export declare function afterMismatch(records: readonly ControlRecord[], head: unknown): RecoveryStep;
+//# sourceMappingURL=access-recovery.d.ts.map

package/dist/access-recovery.js

@@ -0,0 +1,45 @@
+import { bytesEqual } from "@openlfcp/core";
+import { ABILITY, hasAbility } from "@openlfcp/wire";
+/** Transient refusals of a recovery CONTROL_PUT, retried with backoff a bounded number of times. */
+export const RECOVERY_TRANSIENT_CODES = new Set([
+    "RATE_LIMITED",
+    "INTERNAL_ERROR",
+]);
+/** How many transient refusals a recovery tolerates before it ends. */
+export const RECOVERY_TRANSIENT_ATTEMPTS = 3;
+/**
+ * The first step after RESOURCE_OPEN was refused with AUTHORIZATION_FAILED:
+ * push our head (the server's answer tells where its chain ends), or not
+ * at all when our chain does not grant `principal` data/read or has nothing
+ * above the Genesis to push.
+ */
+export function startRecovery(state, records, principal) {
+    if (!hasAbility(state, principal, ABILITY.DATA_READ))
+        return final("not-granted");
+    if (records.length < 2)
+        return final("server-current");
+    return { kind: "push", index: records.length - 1 };
+}
+/** The next step after the server committed `records[index]`. */
+export function afterAccepted(records, index) {
+    return index >= records.length - 1 ? { kind: "reopen" } : { kind: "push", index: index + 1 };
+}
+/**
+ * The next step after CONTROL_HEAD_MISMATCH naming the server's head
+ * `head`: push the record above it; open again once when the server holds
+ * our head (another holder re-supplied it meanwhile; if the refusal is not
+ * caused by a loss, the second AUTHORIZATION_FAILED is final); stop at a
+ * head we do not know.
+ */
+export function afterMismatch(records, head) {
+    if (!(head instanceof Uint8Array))
+        return final("refused");
+    const at = records.findIndex((r) => bytesEqual(r.signed.id, head));
+    if (at < 0)
+        return final("unknown-head");
+    if (at === records.length - 1)
+        return { kind: "reopen" };
+    return { kind: "push", index: at + 1 };
+}
+const final = (reason) => ({ kind: "final", reason });
+//# sourceMappingURL=access-recovery.js.map

package/dist/batch-status.d.ts

@@ -0,0 +1,104 @@
+import { type DataUnitId, type ResourceId } from "@openlfcp/core";
+import type { LfcpStorage, StorageWrite } from "@openlfcp/storage";
+import { type Receipt } from "./receipts.js";
+/**
+ * The status of a committed batch (SDK-SECTIONS-INTEGRATION-01 §4.1,
+ * LFCP-02-026): which of its units the server accepted, and whether it was
+ * rejected. Kept next to the batch's receipt as a local mark, and written
+ * in the same storage transaction as the evidence that changes it (the
+ * ACK's dequeue), so a restart never loses an acceptance nor invents one.
+ * An index maps each unit of a receipt to its operation. A batch whose
+ * receipt was released before it was final stays here until it is final
+ * (receipts.ts).
+ */
+/** §4.1. */
+export type BatchStatusName = "saved" | "pending" | "accepted" | "evidence-unavailable" | "rejected"
+/**
+ * LFCP-02-115: not accepted, and the server refuses the Resource in this
+ * session (e.g. AUTHORIZATION_FAILED on RESOURCE_OPEN): it cannot be
+ * accepted there now. Not a refusal of the content; the work is kept.
+ */
+ | "blocked";
+/** §4.1, §5 `batch`: a committed batch and the evidence about its units. */
+export interface BatchStatus {
+    readonly operationId: string;
+    readonly status: BatchStatusName;
+    readonly unitIds: readonly DataUnitId[];
+    /** The units a correlated durable ACK from a durability-2 server on the route set named (§4.1). */
+    readonly acceptedUnitIds: readonly DataUnitId[];
+    readonly affectedNodeIds: readonly string[];
+    /** A terminal NACK of one of its units. */
+    readonly rejection?: {
+        readonly code: string;
+        readonly unitIds: readonly DataUnitId[];
+    };
+}
+/** The durability (§37) an ACK must establish to be acceptance evidence (§4.1). */
+export declare const ACCEPTANCE_DURABILITY = 2n;
+interface Stored {
+    /** Units with acceptance evidence (hex). */
+    readonly accepted: readonly string[];
+    /** Units acknowledged without it: not durable, below durability 2, or off the route set (hex). */
+    readonly unconfirmed: readonly string[];
+    readonly rejection?: {
+        readonly code: string;
+        readonly unitIds: readonly string[];
+    };
+}
+/** The index writes of a new receipt (in the commit's transaction). */
+export declare function receiptIndexWrites(resource: ResourceId, receipt: Receipt): StorageWrite[];
+/**
+ * The writes of releasing `receipt` (with its receipt mark's removal): a
+ * final batch's status and index go; a batch not final yet is kept,
+ * reported until it is final.
+ */
+export declare function releaseWrites(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId, receipt: Receipt): Promise<StorageWrite[]>;
+/**
+ * The writes that forget a released batch still kept for its status, when
+ * a new commit takes its operation ID (the new batch replaces it).
+ */
+export declare function replaceReleasedWrites(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId, operationId: string): Promise<StorageWrite[]>;
+/** The writes that forget a released receipt's status and index. */
+export declare function releaseStatusWrites(resource: ResourceId, receipt: Receipt): StorageWrite[];
+/**
+ * §4.1: the status of a receipt's batch. `readyDurability` is the current
+ * session's READY durability, or null without a session.
+ */
+export declare function deriveStatus(receipt: Receipt, s: Stored, readyDurability: bigint | null, refused?: boolean): BatchStatus;
+/** The status of one operation's batch; undefined without a receipt. */
+export declare function batchStatus(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId, operationId: string, readyDurability: bigint | null, refused?: boolean): Promise<BatchStatus | undefined>;
+/** Every receipt's batch of a Resource, and every released batch not final yet, by operation ID. */
+export declare function batchStatuses(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId, readyDurability: bigint | null, refused?: boolean): Promise<BatchStatus[]>;
+/** What happened to units of receipts: how their batches' stored status changes. */
+export type UnitEvidence = 
+/** Acceptance evidence (§4.1). */
+{
+    readonly kind: "accepted";
+}
+/** Acknowledged without acceptance evidence. */
+ | {
+    readonly kind: "unconfirmed";
+}
+/** A terminal NACK. */
+ | {
+    readonly kind: "rejected";
+    readonly code: string;
+}
+/** Offered again after the server lost them (§4.2): no longer accepted. */
+ | {
+    readonly kind: "reoffered";
+};
+/**
+ * The writes recording `evidence` for `units` (hex), and the operations
+ * whose stored status changed with the units that changed in each. Units
+ * of no receipt are ignored. A released batch that becomes final is
+ * forgotten in the same writes; its final status is in `finals`, since it
+ * cannot be read back. Pure apart from reading the marks.
+ */
+export declare function recordEvidence(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId, units: readonly string[], evidence: UnitEvidence): Promise<{
+    readonly writes: StorageWrite[];
+    readonly changed: ReadonlyMap<string, readonly string[]>;
+    readonly finals: ReadonlyMap<string, BatchStatus>;
+}>;
+export {};
+//# sourceMappingURL=batch-status.d.ts.map

package/dist/batch-status.js

@@ -0,0 +1,171 @@
+import { dataUnitId, fromHex, toHex } from "@openlfcp/core";
+import { receiptOf, receiptsOf, releasedReceiptOf, releasedReceiptsOf, releasedWrite, } from "./receipts.js";
+/** The durability (§37) an ACK must establish to be acceptance evidence (§4.1). */
+export const ACCEPTANCE_DURABILITY = 2n;
+const EMPTY = { accepted: [], unconfirmed: [] };
+const statusKey = (resource, operationId) => `batch-status:${toHex(resource)}:${operationId}`;
+const unitKey = (resource, unit) => `receipt-unit:${toHex(resource)}:${unit}`;
+/** The index writes of a new receipt (in the commit's transaction). */
+export function receiptIndexWrites(resource, receipt) {
+    return receipt.unitIds.map((u) => ({
+        op: "put-local-mark",
+        key: unitKey(resource, toHex(u)),
+        value: receipt.operationId,
+    }));
+}
+/** Accepted or rejected: nothing more will happen to the batch (§4.1). */
+function isFinal(receipt, s) {
+    return s.rejection !== undefined || receipt.unitIds.every((u) => s.accepted.includes(toHex(u)));
+}
+/**
+ * The writes of releasing `receipt` (with its receipt mark's removal): a
+ * final batch's status and index go; a batch not final yet is kept,
+ * reported until it is final.
+ */
+export async function releaseWrites(storage, resource, receipt) {
+    const s = await stored(storage, resource, receipt.operationId);
+    return isFinal(receipt, s)
+        ? releaseStatusWrites(resource, receipt)
+        : [releasedWrite(resource, receipt.operationId, receipt)];
+}
+/**
+ * The writes that forget a released batch still kept for its status, when
+ * a new commit takes its operation ID (the new batch replaces it).
+ */
+export async function replaceReleasedWrites(storage, resource, operationId) {
+    const released = await releasedReceiptOf(storage, resource, operationId);
+    return released === undefined
+        ? []
+        : [releasedWrite(resource, operationId, null), ...releaseStatusWrites(resource, released)];
+}
+/** The writes that forget a released receipt's status and index. */
+export function releaseStatusWrites(resource, receipt) {
+    return [
+        { op: "put-local-mark", key: statusKey(resource, receipt.operationId), value: null },
+        ...receipt.unitIds.map((u) => ({
+            op: "put-local-mark",
+            key: unitKey(resource, toHex(u)),
+            value: null,
+        })),
+    ];
+}
+async function stored(storage, resource, operationId) {
+    const raw = await storage.localMarks.get(statusKey(resource, operationId));
+    return raw === undefined ? EMPTY : JSON.parse(raw);
+}
+/**
+ * §4.1: the status of a receipt's batch. `readyDurability` is the current
+ * session's READY durability, or null without a session.
+ */
+export function deriveStatus(receipt, s, readyDurability, refused = false) {
+    const units = receipt.unitIds.map((u) => toHex(u));
+    const accepted = units.filter((u) => s.accepted.includes(u));
+    const status = s.rejection !== undefined
+        ? "rejected"
+        : units.length === 0
+            ? "saved"
+            : accepted.length === units.length
+                ? "accepted"
+                : refused
+                    ? "blocked"
+                    : units.some((u) => s.unconfirmed.includes(u) && !s.accepted.includes(u)) ||
+                        (readyDurability !== null && readyDurability < ACCEPTANCE_DURABILITY)
+                        ? "evidence-unavailable"
+                        : "pending";
+    const ids = (hex) => Object.freeze(hex.map((h) => dataUnitId(fromHex(h))));
+    return Object.freeze({
+        operationId: receipt.operationId,
+        status,
+        unitIds: receipt.unitIds,
+        acceptedUnitIds: ids(accepted),
+        affectedNodeIds: receipt.affectedNodeIds,
+        ...(s.rejection === undefined
+            ? {}
+            : {
+                rejection: Object.freeze({ code: s.rejection.code, unitIds: ids(s.rejection.unitIds) }),
+            }),
+    });
+}
+/** The status of one operation's batch; undefined without a receipt. */
+export async function batchStatus(storage, resource, operationId, readyDurability, refused = false) {
+    const receipt = (await receiptOf(storage, resource, operationId)) ??
+        (await releasedReceiptOf(storage, resource, operationId));
+    if (receipt === undefined)
+        return undefined;
+    return deriveStatus(receipt, await stored(storage, resource, operationId), readyDurability, refused);
+}
+/** Every receipt's batch of a Resource, and every released batch not final yet, by operation ID. */
+export async function batchStatuses(storage, resource, readyDurability, refused = false) {
+    const out = [];
+    const held = await receiptsOf(storage, resource);
+    const ids = new Set(held.map((r) => r.operationId));
+    const released = (await releasedReceiptsOf(storage, resource)).filter((r) => !ids.has(r.operationId));
+    for (const receipt of [...held, ...released])
+        out.push(deriveStatus(receipt, await stored(storage, resource, receipt.operationId), readyDurability, refused));
+    return out.sort((a, b) => (a.operationId < b.operationId ? -1 : 1));
+}
+/**
+ * The writes recording `evidence` for `units` (hex), and the operations
+ * whose stored status changed with the units that changed in each. Units
+ * of no receipt are ignored. A released batch that becomes final is
+ * forgotten in the same writes; its final status is in `finals`, since it
+ * cannot be read back. Pure apart from reading the marks.
+ */
+export async function recordEvidence(storage, resource, units, evidence) {
+    const byOperation = new Map();
+    for (const u of new Set(units)) {
+        const op = await storage.localMarks.get(unitKey(resource, u));
+        if (op !== undefined)
+            byOperation.set(op, [...(byOperation.get(op) ?? []), u]);
+    }
+    const writes = [];
+    const changed = new Map();
+    const finals = new Map();
+    for (const [op, mine] of byOperation) {
+        const s = await stored(storage, resource, op);
+        let next = s;
+        let touched = [];
+        switch (evidence.kind) {
+            case "accepted":
+                touched = mine.filter((u) => !s.accepted.includes(u));
+                next = { ...s, accepted: [...s.accepted, ...touched] };
+                break;
+            case "unconfirmed":
+                touched = mine.filter((u) => !s.accepted.includes(u) && !s.unconfirmed.includes(u));
+                next = { ...s, unconfirmed: [...s.unconfirmed, ...touched] };
+                break;
+            case "rejected":
+                if (s.rejection !== undefined)
+                    break;
+                touched = mine;
+                next = { ...s, rejection: { code: evidence.code, unitIds: mine } };
+                break;
+            case "reoffered":
+                touched = mine.filter((u) => s.accepted.includes(u) || s.unconfirmed.includes(u));
+                next = {
+                    ...s,
+                    accepted: s.accepted.filter((u) => !mine.includes(u)),
+                    unconfirmed: s.unconfirmed.filter((u) => !mine.includes(u)),
+                };
+                break;
+        }
+        if (touched.length === 0)
+            continue;
+        changed.set(op, touched);
+        const released = (await receiptOf(storage, resource, op)) === undefined
+            ? await releasedReceiptOf(storage, resource, op)
+            : undefined;
+        if (released !== undefined && isFinal(released, next)) {
+            finals.set(op, deriveStatus(released, next, null));
+            writes.push(releasedWrite(resource, op, null), ...releaseStatusWrites(resource, released));
+            continue;
+        }
+        writes.push({
+            op: "put-local-mark",
+            key: statusKey(resource, op),
+            value: JSON.stringify(next),
+        });
+    }
+    return { writes, changed, finals };
+}
+//# sourceMappingURL=batch-status.js.map

package/dist/claim-journal.d.ts

@@ -0,0 +1,54 @@
+import { type ResourceId } from "@openlfcp/core";
+import { type ResourceDEK } from "@openlfcp/crypto";
+import { type LfcpStorage, type SecretStore } from "@openlfcp/storage";
+/**
+ * The journal of a capability claim in flight (LFCP-02-110).
+ *
+ * A one-time invitation is spent when the coordinator commits the claim
+ * (LFCP-WIRE-01 §18.1). If the CONTROL_PUT's answer is lost, the claimant
+ * cannot tell whether it was: retrying with the link fails once the
+ * invitation is used up, and the claimant would be left without the chain
+ * and the DEK. So before every claim is sent, the claimant journals it:
+ * the claim record, the head it expects, the validated chain up to that
+ * head, and the epochs whose DEKs it holds (the DEKs themselves go to the
+ * SecretStore first, LFCP-034). After a lost answer, the same record is
+ * sent again: a coordinator answers a record it has already committed with
+ * the same ACK (§47, §70), so a claim that landed completes without
+ * spending the invitation twice, and one that did not is refused or meets
+ * a moved head.
+ *
+ * The journal is a local mark (`invitation-claim:<resource hex>`). It holds
+ * no secret: the claim and the chain are signed public records.
+ */
+/** A journaled claim, as JSON in a local mark. Byte strings are hex. */
+export interface ClaimJournal {
+    readonly v: 1;
+    readonly resourceId: string;
+    /** The invitation grant the claim spends. */
+    readonly invitationGrantId: string;
+    /** The claimant's Principal ID. */
+    readonly claimant: string;
+    /** The signed CAPABILITY_CLAIM record. */
+    readonly claim: string;
+    /** The head the claim was sent against (its prev_control_id). */
+    readonly expectedHead: string;
+    /** The validated Control Records up to that head, in order. */
+    readonly chain: readonly string[];
+    /** The epochs whose DEK is in the SecretStore, as decimal strings. */
+    readonly epochs: readonly string[];
+    /** The claimed abilities, as decimal strings. */
+    readonly abilities: readonly string[];
+}
+type JournalStorage = Pick<LfcpStorage, "localMarks" | "commit">;
+/** Writes the DEKs to the SecretStore, then the journal (secret first, LFCP-034). */
+export declare function writeClaimJournal(storage: JournalStorage, secrets: SecretStore, resource: ResourceId, journal: ClaimJournal, deks: ReadonlyMap<string, ResourceDEK>, exportDek: (dek: ResourceDEK) => Uint8Array): Promise<void>;
+/** The journaled claim of `resource`, if any. */
+export declare function readClaimJournal(storage: Pick<LfcpStorage, "localMarks">, resource: ResourceId): Promise<ClaimJournal | undefined>;
+/** Removes the journal of `resource` once its claim's outcome is known. */
+export declare function clearClaimJournal(storage: JournalStorage, resource: ResourceId): Promise<void>;
+/** Every journaled claim, e.g. to resume them after a restart (resumeInvitationClaim). */
+export declare function pendingInvitationClaims(storage: Pick<LfcpStorage, "localMarks">): Promise<readonly ClaimJournal[]>;
+/** The journaled epochs' DEKs, from the SecretStore. */
+export declare function journaledDeks(secrets: SecretStore, resource: ResourceId, journal: ClaimJournal): Promise<Map<string, ResourceDEK>>;
+export {};
+//# sourceMappingURL=claim-journal.d.ts.map

package/dist/claim-journal.js

@@ -0,0 +1,52 @@
+import { dataEpoch, toHex } from "@openlfcp/core";
+import { importResourceDEK } from "@openlfcp/crypto";
+import { dekSecretRef } from "@openlfcp/storage";
+const PREFIX = "invitation-claim:";
+const key = (resource) => `${PREFIX}${toHex(resource)}`;
+/** Writes the DEKs to the SecretStore, then the journal (secret first, LFCP-034). */
+export async function writeClaimJournal(storage, secrets, resource, journal, deks, exportDek) {
+    for (const [epoch, dek] of deks) {
+        const bytes = exportDek(dek);
+        try {
+            await secrets.put(dekSecretRef(resource, dataEpoch(BigInt(epoch))), bytes);
+        }
+        finally {
+            bytes.fill(0);
+        }
+    }
+    const result = await storage.commit([
+        { op: "put-local-mark", key: key(resource), value: JSON.stringify(journal) },
+    ]);
+    if (!result.ok)
+        throw new Error(`the claim journal was not stored: ${result.reason}`);
+}
+/** The journaled claim of `resource`, if any. */
+export async function readClaimJournal(storage, resource) {
+    const value = await storage.localMarks.get(key(resource));
+    return value === undefined ? undefined : JSON.parse(value);
+}
+/** Removes the journal of `resource` once its claim's outcome is known. */
+export async function clearClaimJournal(storage, resource) {
+    await storage.commit([{ op: "put-local-mark", key: key(resource), value: null }]);
+}
+/** Every journaled claim, e.g. to resume them after a restart (resumeInvitationClaim). */
+export async function pendingInvitationClaims(storage) {
+    return (await storage.localMarks.list(PREFIX)).map((m) => JSON.parse(m.value));
+}
+/** The journaled epochs' DEKs, from the SecretStore. */
+export async function journaledDeks(secrets, resource, journal) {
+    const deks = new Map();
+    for (const epoch of journal.epochs) {
+        const bytes = await secrets.get(dekSecretRef(resource, dataEpoch(BigInt(epoch))));
+        if (bytes === undefined)
+            continue;
+        try {
+            deks.set(epoch, importResourceDEK(bytes));
+        }
+        finally {
+            bytes.fill(0);
+        }
+    }
+    return deks;
+}
+//# sourceMappingURL=claim-journal.js.map

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

@@ -1,15 +1,23 @@
 /** Name of this package. */
 export declare const PACKAGE = "@openlfcp/client";
 export { type ApplyOutcome, type DataProfileHandler, DataUnitApplier, type DataUnitApplierOptions, type EpochReconciliation, type EquivocationOutcome, type ExcludedUnit, type ProfileApplyResult, type ProfileDiagnostic, type ProfileExcludeResult, type ProfileUnit, } from "./apply.js";
+export { ACCEPTANCE_DURABILITY, type BatchStatus, type BatchStatusName, batchStatus, batchStatuses, } from "./batch-status.js";
 export { type CheckpointSource, ProfileCheckpointer } from "./checkpoint.js";
-export { type ConnectionEvents, type ConnectionOptions, LFCP_SUBPROTOCOL, LfcpConnection, platformWebSocket, type WebSocketFactory, type WebSocketLike, } from "./connection.js";
+export { type ClaimJournal, pendingInvitationClaims } from "./claim-journal.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, acceptInvitation, type CreatedInvitation, type CreateInvitationOptions, createInvitation, DEFAULT_INVITATION_ABILITIES, InvitationLink, } from "./invite.js";
-export { type AckOutcome, type BlockedItem, exponentialBackoff, type NackOutcome, type OutboundMessage, OutboundQueue, type OutboundQueueOptions, type ResourceSyncState, type RetryPolicy, type RetryReason, resourceSyncState, type StaleOutboundUnit, snapshotFrontier, } from "./outbound.js";
-export { createQueuedSnapshot, outboundItem, queueControlRecord, queueKeyEpoch, queueKeyPackage, queueSnapshot, } from "./queue.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, createQueuedDataUnit, dataUnitRow, dekResolver, latestAcceptedOwnUnit, loadControlChain, StoredSeenUnits, saveControlChain, saveControlConflict, } from "./storage.js";
-export { defaultReconnect, type ReconnectPolicy, type ResourceBinding, type ResourceRefusal, type SnapshotBinding, SyncClient, type SyncClientOptions, type SyncEvent, startSyncDriver, TERMINAL_RESOURCE_CODES, } from "./sync-client.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";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,15 +1,23 @@
 /** Name of this package. */
 export const PACKAGE = "@openlfcp/client";
 export { DataUnitApplier, } from "./apply.js";
+export { ACCEPTANCE_DURABILITY, batchStatus, batchStatuses, } from "./batch-status.js";
 export { ProfileCheckpointer } from "./checkpoint.js";
-export { LFCP_SUBPROTOCOL, LfcpConnection, platformWebSocket, } from "./connection.js";
+export { pendingInvitationClaims } from "./claim-journal.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 { acceptInvitation, createInvitation, DEFAULT_INVITATION_ABILITIES, InvitationLink, } from "./invite.js";
+export { abandonInvitationClaim, acceptInvitation, createInvitation, DEFAULT_INVITATION_ABILITIES, InvitationLink, resumeInvitationClaim, } from "./invite.js";
 export { exponentialBackoff, OutboundQueue, resourceSyncState, snapshotFrontier, } from "./outbound.js";
-export { createQueuedSnapshot, outboundItem, queueControlRecord, queueKeyEpoch, queueKeyPackage, queueSnapshot, } from "./queue.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, createQueuedDataUnit, dataUnitRow, dekResolver, latestAcceptedOwnUnit, loadControlChain, StoredSeenUnits, saveControlChain, saveControlConflict, } from "./storage.js";
-export { defaultReconnect, SyncClient, startSyncDriver, TERMINAL_RESOURCE_CODES, } from "./sync-client.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";
 //# sourceMappingURL=index.js.map