API index and search · Build metadata

Supporting declarations

packages/room/src/journal.ts. These declarations explain referenced types. Only package-page symbols are package exports.

Exact source

/** One journaled mutation: the wire envelope plus its recorded outcome. Replay applies
 *  the OUTCOME — a non-applied (`rejected`/`deopt`) entry consumes its mid without
 *  running the mutator. */
export interface RoomJournalEntry {
    clientID: string;
    mid: number;
    name: string;
    args: unknown;
    /** The connection's authenticated subject at push time (the lease token's `sub`,
     *  shell-stamped — managed-writes §3.3): recovery is re-invocation, so identity is
     *  an input that must survive the crash. `""` = an entry journaled before the
     *  identity plane existed (mutators see it as unauthenticated). */
    sub: string;
    /** The recorded verdict (H-iv-b): `"applied"` replays by RE-INVOKING the mutator
     *  (§3.3 — and against a moved base the re-invocation may legitimately reject or
     *  DEOPT; the journal record is never rewritten, the shell's recorded-outcome map
     *  reflects what the replaying incarnation produced); `"rejected"` (final — authz /
     *  validation / unknown mutator) and `"deopt"` (the §3.3 commit gate refused; the
     *  client was told to re-route the mutation) both replay as a consumed-mid-no-effect
     *  WITHOUT running anything — re-judging a deopt could invent effects the client
     *  already re-routed elsewhere. Absent = a legacy pre-H-iv-b entry: read through
     *  {@link journalEntryOutcome}. */
    outcome?: "applied" | "rejected" | "deopt";
    /** Legacy pre-H-iv-b flag, superseded by {@link outcome} but still WRITTEN (`true`)
     *  alongside BOTH non-applied outcomes: a legacy reader replays either kind as a
     *  consumed-mid-no-effect, which is exactly right. */
    rejected?: boolean;
}

/** The ONE reading rule for an entry's verdict across journal generations: `outcome`
 *  when present, else the legacy `rejected` flag, else applied. */
export declare function journalEntryOutcome(entry: RoomJournalEntry): "applied" | "rejected" | "deopt";

/** One journaled flush batch: the room's flush-stream position, the placement epoch it
 *  was built under, and the EXACT `/apply-row-change-txn` body string — resubmitted
 *  verbatim, never rebuilt (§5.3 step 4). */
export interface RoomFlushRecord {
    seq: number;
    epoch: number;
    body: string;
}

export interface RoomJournal {
    /** Append `entries` durably, in order. Resolving is the ack gate (§8.1): the shell
     *  advances lmid rows only after this resolves. A rejection is fatal to the
     *  incarnation — an ack that might not survive must never be sent. */
    append(entries: RoomJournalEntry[]): Promise<void>;
    /** Every entry ever appended, in append order — the boot-time replay source. */
    replay(): Promise<RoomJournalEntry[]>;
    /** Journal one built flush batch, BEFORE its first send. Same durability contract
     *  as `append`: a rejection is fatal (an unjournaled batch must never reach the
     *  wire — a retry could otherwise rebuild different bytes under the same id). */
    appendFlush(record: RoomFlushRecord): Promise<void>;
    /** The authority settled flush `seq` (committed, deduped, or dead) — drop it. */
    confirmFlush(seq: number): Promise<void>;
    /** Unconfirmed flush records in seq order, plus the highest seq ever appended
     *  (0 = none) — the boot-time resubmission source and the seq seed. */
    replayFlushes(): Promise<{
        records: RoomFlushRecord[];
        maxSeq: number;
    }>;
}

/** An in-process journal: survives incarnations within one shell process (and, handed
 *  to a second shell, a simulated process crash — the T2 harness). Not durable beyond
 *  the process, by definition. */
export declare function memoryJournal(): RoomJournal;