@serfab/cadre-core 1.13.0 → 1.15.0

package/dist/pending-join-runner.d.ts

@@ -1,75 +1,78 @@
 /**
  * The pending-join retry loop: carries on a join this party asked for through another party's
- * invitation (`CadreControl.PendingJoin`, one row per invitation) in the background, on every
- * owner machine of the party, until the join works, the invitation is used up or expires, or
- * the user dismisses it. The behaviour is described in `docs/strands.md` → "Joining while the
- * inviter is offline".
+ * invitation (`CadreControl.JoinRequest`, one row per invitation, with its outcome in
+ * `JoinSuccess` / `JoinFailure`) in the background, on every owner machine of the party, until
+ * the join works, the invitation is used up or expires, or the user dismisses it. The behaviour
+ * is described in `docs/strands.md` → "Joining while the inviter is offline".
  *
  * `CadreNode` owns every side effect and hands this module plain functions
- * ({@link PendingJoinRunnerDeps}): read the rows, run one attempt (its own `formStrand`), write
+ * ({@link PendingJoinRunnerDeps}): read the joins, run one attempt (its own `formStrand`), write
  * an outcome, say whether this machine is an owner, and the clock. This module owns the policy:
  * when to attempt, how to read an attempt's failure, and how to settle an outcome write that
  * another machine's write beat.
  *
- * Only owner machines run it, because every `PendingJoin` write is owner-signed. Letting a
+ * Only owner machines run it, because every pending-join write is owner-signed. Letting a
  * machine without an owner key finish a join is `blocked/decide-non-owner-machine-completes-a-pending-join`;
  * that changes {@link PendingJoinRunnerDeps.isOwner} and the write functions, not this loop.
  */
-import type { FormStrandResult, PendingJoinRow, PendingJoinStatus, StrandFormationDisclosure, StrandMembershipInvite } from './types.js';
+import type { FormStrandResult, JoinOutcome, PendingJoin, PendingJoinStatus, StrandFormationDisclosure, StrandMembershipInvite } from './types.js';
+import { type JoinRequestFields, type PendingJoinFields } from './control-database.js';
 import { type TimeoutScheduler } from './timeout-scheduler.js';
 /** How often an owner machine re-reads the party's pending joins (it also reads once right after start). */
 export declare const PENDING_JOIN_POLL_MS = 30000;
 /** Ceiling on the wait between two attempts of one join on one machine, before jitter. */
 export declare const PENDING_JOIN_MAX_BACKOFF_MS: number;
 /**
- * The longest a join is tried for. A row's `ExpiresAt` is the earlier of this and the
+ * The longest a join is tried for. A request's `ExpiresAt` is the earlier of this and the
  * invitation's own expiration, which the inviter chose.
  */
 export declare const MAX_PENDING_JOIN_MS: number;
-/** A `PendingJoin` row as written: every column but the stamp, which each write mints. */
-export type PendingJoinFields = Omit<PendingJoinRow, 'StampId'>;
+/** Which pending-join write this machine made: the request itself (an insert or a rewrite), or an outcome row for it. */
+export type PendingJoinWrite = 'request' | 'outcome';
 export interface PendingJoinRunnerDeps {
-    /** This machine's peer id; with the row id it fixes when this machine first tries a row it did not ask for. */
+    /** This machine's peer id; with the request id it fixes when this machine first tries a join it did not ask for. */
     selfId: string;
     /** `NetworkConfig.linkRoundTripMs`: the retry pace follows the formation deadlines it yields. */
     linkRoundTripMs?: number;
-    /** Whether this machine may write `PendingJoin` rows now. Asked every pass. */
+    /** Whether this machine may write pending joins now. Asked every pass. */
     isOwner(): Promise<boolean>;
-    readRows(): Promise<PendingJoinRow[]>;
-    readRow(id: string): Promise<PendingJoinRow | null>;
-    /** One formation attempt for the row's invitation and disclosure (`CadreNode.formStrand`). */
-    attempt(row: PendingJoinRow): Promise<FormStrandResult>;
-    /** `ControlDatabase.replacePendingJoin`, owner-signed: throws `PendingJoinChangedError` when the live row is not `expectedStampId`. */
-    replace(expectedStampId: string, next: PendingJoinFields): Promise<PendingJoinRow>;
+    readRows(): Promise<PendingJoin[]>;
+    readRow(id: string): Promise<PendingJoin | null>;
+    /** One formation attempt for the request's invitation and disclosure (`CadreNode.formStrand`). */
+    attempt(join: PendingJoin): Promise<FormStrandResult>;
+    /** `ControlDatabase.recordJoinOutcome`, owner-signed: throws `PendingJoinChangedError` when the live join is not `expected`. */
+    record(expected: PendingJoin, outcome: JoinOutcome): Promise<PendingJoin>;
+    /** `ControlDatabase.rewritePendingJoin`, owner-signed: throws `PendingJoinChangedError` when the live request is not `expectedStampId`. */
+    rewrite(expectedStampId: string, next: PendingJoinFields): Promise<PendingJoin>;
     /** `ControlDatabase.deletePendingJoin`, owner-signed. */
     remove(id: string): Promise<boolean>;
     /** Whether this machine has no control connection now, so a write it commits reaches no other machine. */
     isAlone(): boolean;
-    /** The sApp the row's invitation names. */
-    sAppIdOf(row: PendingJoinRow): string;
-    /** Every pass's rows, read by an owner machine; `CadreNode` stages the membership invitations they carry. */
-    observeRows(rows: readonly PendingJoinRow[]): void;
+    /** The sApp the request's invitation names. */
+    sAppIdOf(join: PendingJoin): string;
+    /** Every pass's joins, read by an owner machine; `CadreNode` stages the membership invitations they carry. */
+    observeRows(joins: readonly PendingJoin[]): void;
     emit(status: PendingJoinStatus): void;
     now?: () => number;
     random?: () => number;
     scheduler?: TimeoutScheduler;
 }
 /**
- * The pending row a `requestJoin` writes: tried until the invitation's own expiration or
+ * The request a `requestJoin` writes: tried until the invitation's own expiration or
  * {@link MAX_PENDING_JOIN_MS} from now, whichever comes first.
  */
-export declare function requestedPendingJoin(id: string, encodedInvitation: string, disclosure: StrandFormationDisclosure, invitationExpiresAt: number, now: number): PendingJoinFields;
-/** A row's stored disclosure, as the next attempt sends it. Owner-signed, so anything but an object is a bug. */
-export declare function parseStoredDisclosure(row: PendingJoinRow): StrandFormationDisclosure;
-/** A `joined` row's `MembershipInvite` column, or null when it is not the `{inviteKey, invitePrivateKey}` JSON the loop writes. */
+export declare function requestedPendingJoin(id: string, encodedInvitation: string, disclosure: StrandFormationDisclosure, invitationExpiresAt: number, now: number): JoinRequestFields;
+/** A request's stored disclosure, as the next attempt sends it. Owner-signed, so anything but an object is a bug. */
+export declare function parseStoredDisclosure(join: PendingJoin): StrandFormationDisclosure;
+/** A `JoinSuccess` row's `MembershipInvite` column, or null when it is not the `{inviteKey, invitePrivateKey}` JSON the loop writes. */
 export declare function parseStoredMembershipInvite(text: string): StrandMembershipInvite | null;
 /**
- * The membership invitations `joined` rows carry that this process has not staged yet, so a
+ * The membership invitations joined requests carry that this process has not staged yet, so a
  * closed strand joined on one owner machine can be seated by whichever machine launches it
- * first. Rows older than {@link MEMBERSHIP_INVITE_TTL_MS} are skipped: their invitation is dead.
+ * first. Joins older than {@link MEMBERSHIP_INVITE_TTL_MS} are skipped: their invitation is dead.
  * `alreadyStaged` holds invite keys; a malformed column is skipped and logged.
  */
-export declare function membershipInvitesToStage(rows: readonly PendingJoinRow[], alreadyStaged: ReadonlySet<string>, now: number): Array<{
+export declare function membershipInvitesToStage(joins: readonly PendingJoin[], alreadyStaged: ReadonlySet<string>, now: number): Array<{
     rowId: string;
     strandId: string;
     invite: StrandMembershipInvite;
@@ -77,13 +80,13 @@ export declare function membershipInvitesToStage(rows: readonly PendingJoinRow[]
 export declare class PendingJoinRunner {
     private readonly deps;
     private readonly tracked;
-    /** Rows whose latest write by this machine committed with no control connection: id → the stamp written. */
+    /** Joins whose latest write by this machine committed with no control connection: id → the request stamp written. */
     private readonly writtenAlone;
     private readonly dueQueue;
     private readonly scheduler;
     private readonly now;
     private readonly random;
-    /** First retry delay, and the window a row this machine did not ask for is first tried in. */
+    /** First retry delay, and the window a join this machine did not ask for is first tried in. */
     private readonly baseDelayMs;
     /** How long a `token-spent` answer waits before its confirming attempt: long enough for a sibling's `joined` write to replicate. */
     private readonly spentConfirmDelayMs;
@@ -99,8 +102,8 @@ export declare class PendingJoinRunner {
      * Stop scheduling. Clears every timer and starts no new attempt.
      *
      * NOTE: an attempt already in flight is not awaited, because `formStrand` takes no abort
-     * signal. An approval that lands while the node stops can lose its local records; the row then
-     * stays pending, and the next start's attempt answers `token-spent`, which fails the row after
+     * signal. An approval that lands while the node stops can lose its local records; the request
+     * then stays pending, and the next start's attempt answers `token-spent`, which fails it after
      * its confirming attempt. Honest and bounded; if it shows up in practice, give `formStrand` a
      * signal and abort it here.
      */
@@ -108,25 +111,30 @@ export declare class PendingJoinRunner {
     /** Run a pass now, for a change that may make one useful (this machine just became an owner). */
     kick(): void;
     /**
-     * Try `row` on this machine at once, outside the background slots, and report the status
-     * after the attempt. Joins an attempt already running for the row.
+     * Try `join` on this machine at once, outside the background slots, and report the status
+     * after the attempt. Joins an attempt already running for it.
      */
-    attemptNow(row: PendingJoinRow): Promise<PendingJoinStatus>;
-    /** This machine's view of `row`: the row's own state, with this machine's attempt state laid over a pending row. */
-    statusOf(row: PendingJoinRow): PendingJoinStatus;
-    /** Record a `PendingJoin` write this machine made outside the loop (a `requestJoin`), for {@link reissueWritesMadeAlone}. */
-    noteWritten(row: PendingJoinRow): void;
-    /** Stop tracking a row the user dismissed. An attempt in flight finishes; its outcome write then finds the row gone. */
+    attemptNow(join: PendingJoin): Promise<PendingJoinStatus>;
+    /** This machine's view of `join`: its own state, with this machine's attempt state laid over a pending one. */
+    statusOf(join: PendingJoin): PendingJoinStatus;
+    /**
+     * Record a pending-join write this machine made, for {@link reissueWritesMadeAlone}. A write
+     * made alone marks the join. A request write made connected clears the mark, since it
+     * carried the request; an outcome write made connected does not, since the request it names
+     * may still be unknown to the other machines.
+     */
+    noteWritten(join: PendingJoin, write: PendingJoinWrite): void;
+    /** Stop tracking a join the user dismissed. An attempt in flight finishes; its outcome write then finds the request gone. */
     forgetRow(id: string): void;
     /**
-     * Re-write, with identical content under a fresh stamp, each row this machine last wrote while
+     * Re-write, with identical content under a fresh stamp, each join this machine last wrote while
      * it had no control connection, so the other machines receive it. Called on the control
-     * connection growth edge. A row someone wrote since is left alone.
+     * connection growth edge. A join someone wrote since is left alone.
      *
-     * NOTE: in memory only, so a row written alone by a process that stopped before it reconnected
-     * reaches the party only with that row's next write. A sweep of every row this machine wrote,
+     * NOTE: in memory only, so a join written alone by a process that stopped before it reconnected
+     * reaches the party only with that join's next write. A sweep of every join this machine wrote,
      * on the first connection after start, would cover that, at the cost of one permanent
-     * `Revocation` tombstone per row per start. Revisit if other machines are seen missing such rows.
+     * `Revocation` tombstone per join per start. Revisit if other machines are seen missing such joins.
      */
     reissueWritesMadeAlone(): Promise<void>;
     private schedulePass;
@@ -136,11 +144,11 @@ export declare class PendingJoinRunner {
     private runPass;
     /** Drop every scheduled attempt; the first pass that finds this machine an owner again schedules afresh. */
     private pauseAttempts;
-    /** Bring one read row into this machine's schedule. */
+    /** Bring one read join into this machine's schedule. */
     private consider;
     /**
-     * The tracked entry for `row`, updated to it. A row asked for again (`RequestedAt` changed)
-     * starts this machine's counting over; a finished row stops its schedule.
+     * The tracked entry for `join`, updated to it. A join asked for again (`RequestedAt` changed)
+     * starts this machine's counting over; a finished join stops its schedule.
      */
     private adopt;
     private scheduleAttempt;
@@ -151,27 +159,27 @@ export declare class PendingJoinRunner {
     /** Run one attempt for `entry`, or join the one already running. Never rejects. */
     private startAttempt;
     private attemptOnce;
-    /** Read a failed attempt: retry, confirm a spent token, or fail the row. */
+    /** Read a failed attempt: retry, confirm a spent token, or fail the join. */
     private onAttemptFailed;
     /**
      * A `token-spent` answer may mean another owner machine of this party won the same
-     * invitation. Adopt its outcome if the row already shows one; otherwise confirm once, after
-     * long enough for that machine's `joined` write to arrive, before failing the row.
+     * invitation. Adopt its outcome if the join already shows one; otherwise confirm once, after
+     * long enough for that machine's `joined` write to arrive, before failing the join.
      */
     private onSpent;
     private retryLater;
     /** `min(base × 2^(n−1), max)`, moved by up to ±{@link RETRY_JITTER}. */
     private backoffMs;
     /**
-     * Write `next` over the row this machine last read. When another write got there first,
-     * re-read and settle by {@link resolveLostWrite}. A row the user dismissed meanwhile is not
-     * recreated; a join this machine made is still remembered machine-locally, as every
-     * `formStrand` is.
+     * Record `next` on the join this machine last read. When another write got there first, settle
+     * by {@link resolveLostWrite} from the live join the refusal carries. A join the user dismissed
+     * meanwhile is not recreated; a join this machine made is still remembered machine-locally, as
+     * every `formStrand` join is.
      */
     private writeOutcome;
     private settle;
     /**
-     * Remove a finished row {@link MEMBERSHIP_INVITE_TTL_MS} after its outcome: the membership
+     * Remove a finished join {@link MEMBERSHIP_INVITE_TTL_MS} after its outcome: the membership
      * invitation it carries is dead by then, and an app that was not running has seen the strand
      * through `strand:discovered`. Only while connected, like every write nothing waits on.
      *