snapback2 0.0.1

package/dist/store/indexeddb.d.ts

@@ -0,0 +1,23 @@
+import { type PersistedRangeState, type RangeStoreFactory } from "./range-store.js";
+interface WebLockLike {
+    readonly name?: string;
+}
+interface WebLocksLike {
+    request<T>(name: string, options: {
+        ifAvailable: true;
+    }, callback: (lock: WebLockLike | null) => Promise<T> | T): Promise<T>;
+}
+export interface IndexedDbRangeStoreOptions {
+    indexedDB?: IDBFactory;
+    locks?: WebLocksLike;
+    databasePrefix?: string;
+    /**
+     * Witness barrier: awaited with the next state before its readwrite
+     * transaction opens, so a harness can kill the profile between two swaps
+     * and prove the carrier lands whole swaps or nothing (LLP 1012 §10).
+     */
+    beforeReplace?: (state: PersistedRangeState) => void | Promise<void>;
+}
+/** The sole web carrier exported by `snapback2/react`. */
+export declare function indexedDbRangeStore(options?: IndexedDbRangeStoreOptions): RangeStoreFactory;
+export {};

package/dist/store/locks.d.ts

@@ -0,0 +1,11 @@
+export interface StoreLocks {
+    request<T>(name: string, options: {
+        ifAvailable: true;
+    }, callback: (lock: {
+        readonly name?: string;
+    } | null) => T | Promise<T>): Promise<T>;
+}
+type LockScope = string | object;
+export declare function inProcessLocks(scope?: LockScope): StoreLocks;
+export declare function acquireStoreLock(locks: StoreLocks, partition: string): Promise<() => Promise<void>>;
+export {};

package/dist/store/outbox.d.ts

@@ -0,0 +1,113 @@
+import type { OutboxEntry, OutboxGrant, OutboxState, OutboxTrace, OverlayRow, RangeStore, StoreDelivery } from "./range-store.js";
+export declare const ENGINE_ID: RegExp;
+export type OutboxRefusalCode = "E_OFFLINE_ID_BLOCK";
+/** A local custody refusal at enqueue time; the client maps it onto the offline family. */
+export declare class OutboxRefusal extends Error {
+    readonly code: OutboxRefusalCode;
+    readonly site: string;
+    readonly rewrite: string;
+    constructor(code: OutboxRefusalCode, message: string, site: string, rewrite: string);
+}
+export declare function emptyTrace(): OutboxTrace;
+/** Reads `grant` off a login, guest, or resume response; anything malformed is ignored. */
+export declare function decodeGrant(value: unknown): OutboxGrant | undefined;
+/** The engine ids `from + offset …`, spelled exactly as `Store::replay_slice_ids` spells them. */
+export declare function sliceIds(grant: Pick<OutboxGrant, "from" | "count">, offset: number, count: number): string[];
+export declare function intentName(grant: string, offset: number): string;
+export declare function settledEntry(entry: OutboxEntry, state: OutboxState, response: unknown, now: number): OutboxEntry;
+export interface EnqueueInput {
+    op: string;
+    args: unknown;
+    issuedSeq: number;
+    trace?: OutboxTrace;
+}
+/** The twin's run over held rows for the slice it was handed: the overlay and the trace land with the entry. */
+export interface EnqueuePrediction {
+    predicted: boolean;
+    overlay: OverlayRow[];
+    trace: OutboxTrace;
+    /** Maintained targets the overlay intentionally omits (LLP 1012 §7); recorded on the entry when non-empty. */
+    omitted?: string[];
+}
+export interface OutboxLedgerOptions {
+    now(): number;
+    fenceMs: number;
+}
+export declare class OutboxLedger {
+    private readonly store;
+    private readonly options;
+    private readonly listeners;
+    /** A successful resume renews trust without changing the server-minted grant's age. */
+    private resumedAt?;
+    /** Runtime lifecycle, advanced synchronously on open, seal, wipe, reset, or close. */
+    private trustGeneration;
+    /**
+     * Grant custody is one critical section: a read of the grant's cursor and the
+     * swap that advances it never interleave with another enqueue or adoption, so
+     * two overlapping writes can never mint the same slice.
+     */
+    private tail;
+    private fenceTimer?;
+    private fenceProbe;
+    constructor(store: RangeStore, options: OutboxLedgerOptions);
+    subscribe(listener: () => void): () => void;
+    notify(): void;
+    close(): void;
+    /** Readiness changes with time even when the outbox has no entries to push. */
+    private armFence;
+    entries(): Promise<OutboxEntry[]>;
+    queued(): Promise<OutboxEntry[]>;
+    grant(): Promise<OutboxGrant | undefined>;
+    grantById(id: string): Promise<OutboxGrant | undefined>;
+    /** A fresh grant replaces the consumption target; older grants stay for the intents that name them. */
+    adopt(grant: OutboxGrant): Promise<void>;
+    /**
+     * Persists the program's write bounds (each op's `maxNewIds`) beside the grants,
+     * on the same tail as enqueue, so an enqueue issued after the program loaded
+     * always sees the bound it certified. The certified program itself rides the
+     * same swap when given, so a cold start with the network cut evaluates and
+     * prices from custody, never from a fallback (LLP 1012 §7, §8).
+     */
+    recordBounds(bounds: Record<string, number>, programs?: Record<string, unknown>): Promise<void>;
+    /** Grant-only without an op; with one, probes the exact slice enqueue would need. */
+    ready(op?: string): Promise<boolean>;
+    /**
+     * Every outbox write shares this tail: enqueue, adoption, bounds, dismiss,
+     * and — through the runtime — settlements and the predictions they drop, so
+     * a settlement never interleaves with the enqueue that reads the grant.
+     */
+    write<T>(action: () => Promise<T>): Promise<T>;
+    pastFence(grant: Pick<OutboxGrant, "mintedAt">): boolean;
+    /** The server-minted grant's own lifetime; a resume renews fence trust, not the grant. */
+    expired(grant: Pick<OutboxGrant, "expiresAt">): boolean;
+    /** When time alone next changes `fence()`: the crossing, or the lapse of a resume's renewed trust. */
+    private trustEndsAt;
+    private resumedSince;
+    /** Trust belongs to this open partition and session, never to the next one. */
+    resetTrust(): void;
+    /** Capture before a resume starts; this is independent of the program generation. */
+    get generation(): number;
+    /** A newer consumption grant cannot authorize work queued under an older one. */
+    canReplay(entry: OutboxEntry): Promise<boolean>;
+    fence(): Promise<"inside" | "past">;
+    /** The owner re-authorized this partition; old intents may now replay for the server to judge. */
+    resumeSucceeded(generation: number): boolean;
+    enqueue(input: EnqueueInput, predict?: (ids: string[]) => Promise<EnqueuePrediction>): Promise<OutboxEntry>;
+    private serial;
+    settle(entry: OutboxEntry, state: OutboxState, response?: unknown): OutboxEntry;
+    /** Removes a settled entry; a queued intent is never dismissed. */
+    dismiss(intent: string): Promise<void>;
+}
+/** The replay envelope for one queued intent, byte-stable across retries. */
+export declare function replayEnvelope(entry: OutboxEntry): {
+    op: string;
+    args: unknown;
+    replay: {
+        grant: string;
+        offset: number;
+        count: number;
+        intent: string;
+        trace: OutboxTrace;
+    };
+};
+export type { OutboxEntry, OutboxGrant, OutboxState, OutboxTrace, StoreDelivery };

package/dist/store/overlay-retirement.d.ts

@@ -0,0 +1,17 @@
+import type { StoredAnswer, WatermarkRecord } from "./range-store.js";
+export interface OverlayWatermark extends Pick<WatermarkRecord, "op" | "args" | "watermark"> {
+    cursorArg: string;
+    /** Last proven progress, and positions already consumed, survive a remount/reopen. */
+    progress?: string;
+    consumed?: string[];
+}
+/** Each page keeps the name used when it was filed, including a pre-manifest c. */
+export declare function pagePosition(page: Pick<StoredAnswer, "op" | "args" | "cursorArg">, mark: OverlayWatermark): string | null | undefined;
+/**
+ * An ordered path starting at the commit snapshot, never inferred from a newer
+ * seq or a different opaque string. A cycle, ambiguity, or missing link ends
+ * the proven prefix. The caller supplies only non-empty, intact held pages.
+ */
+export declare function cursorChain(pages: StoredAnswer[], mark: OverlayWatermark, committedSeq: number): string[];
+/** A re-mark can consume progress only once and only beyond the last proven mark. */
+export declare function advanceOverlay(mark: OverlayWatermark, tail: WatermarkRecord | undefined, chain: string[]): boolean;

package/dist/store/projection.d.ts

@@ -0,0 +1,11 @@
+import { type PersistedRangeState } from "./range-store.js";
+export type StateEntry = {
+    key: string;
+    value: unknown;
+};
+export type StateProjection = Record<"rows" | "answers" | "outbox" | "meta", StateEntry[]>;
+export declare function projectState(state: PersistedRangeState): StateProjection;
+export declare function unprojectState(projected: StateProjection): PersistedRangeState | undefined;
+/** Split only the first separator: a row id may itself contain NUL. */
+export declare function encodeStateKey(key: string, tuple: boolean): string;
+export declare function decodeStateKey(key: string): string;

package/dist/store/range-store.d.ts

@@ -0,0 +1,388 @@
+import { type ByteCacheEntry, type ByteCacheStatus, type ByteDelta, type ByteSwapRequest, type ViewedRecord } from "./byte-cache.js";
+import { type OverlayWatermark } from "./overlay-retirement.js";
+export type PrincipalPartition = string;
+export type RetentionPolicy = "until-revoked" | "delivered-history";
+export interface RowRef {
+    table: string;
+    id: string;
+}
+export interface StoredRow extends RowRef {
+    row: Record<string, unknown>;
+}
+export interface ReceiptRange {
+    site: string;
+    table: string;
+    index: string;
+    prefix: unknown[];
+    order: "Asc" | "Desc";
+    take: number;
+    after: unknown;
+    before: unknown;
+    gt: unknown;
+    gte: unknown;
+    lt: unknown;
+    lte: unknown;
+    rowIds: string[];
+    stop: "Limit" | "Exhausted";
+    absence: boolean;
+    haloId?: string;
+    ruleHash: string;
+    /**
+     * Members this page was recorded with that a later swap evicted (LLP 1012 §5):
+     * the page's answer is `partial/evicted` from then on, and the twin's
+     * drained-prefix rule (§6) no longer counts the page as a link in a complete chain.
+     */
+    evictedIds?: string[];
+}
+export interface Receipt {
+    ranges: ReceiptRange[];
+    absences: Array<[table: string, index: string, key: unknown[]]>;
+    verdicts: unknown[];
+}
+export interface HeldAnswer<Result = unknown> {
+    op: string;
+    args: unknown;
+    state: "complete" | "capped" | "partial" | "denied";
+    data?: Result;
+    next?: string | null;
+    seq: number;
+    validator?: string;
+    receipt?: Receipt;
+    deliveredAt: number;
+    retained?: boolean;
+    caughtUp?: boolean;
+    watermark?: string | null;
+    reason?: string;
+    rule?: string;
+}
+export interface StoredAnswer extends Omit<HeldAnswer, "data"> {
+    data?: unknown;
+    refs: RowRef[];
+    order: number;
+    fingerprint?: string;
+    /** Cursor argument used when this page was filed, before or after manifest load. */
+    cursorArg?: string;
+    /** Seq of the delivery that recorded `next`; conditional refreshes cannot renew a link. */
+    nextSeq?: number;
+}
+export interface WatermarkRecord {
+    op: string;
+    args: unknown;
+    /** The argument the manifest types as this query's cursor; `c` before the manifest loads. */
+    cursorArg?: string;
+    watermark: string | null;
+    validator?: string;
+    generation?: string;
+    schemaHash?: string;
+    authEpoch?: number;
+    updatedAt: number;
+    /**
+     * Durable position among this partition's drained queries: assigned by the store
+     * when the query first records a watermark, kept across every later mark. The
+     * lowest order is the log a settlement and a resume name (LLP 1012 §7).
+     */
+    order?: number;
+}
+/** The generation and authority every held envelope of a partition was delivered under. */
+export interface CoverageFacts {
+    generation: string;
+    schemaHash: string;
+    authEpoch: number;
+}
+/** One certified operation as `GET /api/program` serves it: the IR the twin runs and its certificate. */
+export interface HeldOperation {
+    kind: "query" | "mutation";
+    planHash: string;
+    ir: unknown;
+    certificate: unknown;
+}
+export interface HeldProgram {
+    generation: string;
+    schemaHash: string;
+    schema: OfflineSchema & Record<string, unknown>;
+    programs: Record<string, HeldOperation>;
+}
+export interface Coverage {
+    rows: StoredRow[];
+    ranges: ReceiptRange[];
+    absences: Receipt["absences"];
+    verdicts: unknown[];
+    watermarks: WatermarkRecord[];
+    /**
+     * View-once rows already viewed on this partition: absent from `rows`, listed under
+     * `absences` as a `byId` point, and named here so a replay never renders them (LLP 1012 §9).
+     */
+    viewed?: RowRef[];
+    /** Rows a swap evicted (LLP 1012 §5): the twin reports a read of one as `evicted`, not `never-held`. */
+    evicted?: RowRef[];
+    /** The generation and auth epoch the held coverage was delivered under; absent when nothing is held. */
+    facts?: CoverageFacts;
+    /**
+     * The facts a later delivery arrived under when its generation or schema differ
+     * from `facts`: the held answers predate the program the server now runs, so the
+     * twin serves nothing from them — every read is `hydrating` — until the reset
+     * path drops this coverage and rebuilds it under the live generation (LLP 1012 §8).
+     */
+    superseded?: CoverageFacts;
+    /** The newest delivery's time: what an answer the twin computes reports as `stale.since`. */
+    deliveredAt?: number;
+}
+export type OutboxState = "queued" | "committed" | "rejected" | "expired";
+/** What the twin read when the intent was queued: the replay envelope's `trace` (LLP 1012 §7). */
+export interface OutboxTrace {
+    points: Array<{
+        table: string;
+        index: string;
+        key: unknown[];
+        digest: string | null;
+    }>;
+    verdicts: Array<{
+        ruleHash: string;
+        inputsDigest: string;
+        result: boolean;
+    }>;
+}
+export interface OutboxEntry {
+    intent: string;
+    grant: string;
+    offset: number;
+    count: number;
+    ids: string[];
+    op: string;
+    args: unknown;
+    issuedSeq: number;
+    state: OutboxState;
+    response?: unknown;
+    predicted?: boolean;
+    /** Prediction and its trace were skipped; the program will check this write on the server. */
+    reason?: "fence";
+    /** Engine-owned aggregate targets the prediction's overlay omits by design (the server writes them); absent when none. */
+    omitted?: string[];
+    trace?: OutboxTrace;
+    createdAt: number;
+    updatedAt: number;
+    /** Durable FIFO position; assigned by the store when absent. */
+    order?: number;
+}
+/** A principal-bound replay grant plus the client's own consumption cursor. */
+export interface OutboxGrant {
+    id: string;
+    from: string;
+    count: number;
+    mintedAt: number;
+    expiresAt: number;
+    used: number;
+}
+export interface OutboxStore {
+    all(): Promise<OutboxEntry[]>;
+    get(intent: string): Promise<OutboxEntry | undefined>;
+    put(entry: OutboxEntry): Promise<void>;
+    remove(intent: string): Promise<void>;
+    /** The grant new intents consume from, if one is held. */
+    grant(): Promise<OutboxGrant | undefined>;
+    /** Every held grant, including those older queued intents still name. */
+    grants(): Promise<OutboxGrant[]>;
+    /** Each op's persisted write bound (`maxNewIds`); an enqueue refuses without one. */
+    bounds(): Promise<Record<string, number>>;
+    /** The prediction overlay by intent: the rows a queued intent's local run wrote, `removed` for a delete. */
+    overlay(): Promise<Record<string, OverlayRow[]>>;
+    /** The certified programs held for this partition, keyed by generation. */
+    programs(): Promise<Record<string, HeldProgram>>;
+}
+/** A predicted row: the write's final image, or a `removed` marker for a row the intent deletes. */
+export interface OverlayRow extends StoredRow {
+    removed?: true;
+}
+export interface StoreDelivery {
+    cursorArg?: string;
+    op: string;
+    args: unknown;
+    state: HeldAnswer["state"];
+    data?: unknown;
+    next?: string | null;
+    seq: number;
+    validator?: string;
+    receipt?: Receipt;
+    rows?: StoredRow[];
+    deliveredAt?: number;
+    reason?: string;
+    rule?: string;
+}
+export interface StoreTombstone extends RowRef {
+    seq: number;
+}
+export interface StoreRefresh {
+    op: string;
+    args: unknown;
+    seq: number;
+    validator: string;
+    deliveredAt?: number;
+}
+export interface OfflineSchema {
+    tables?: Record<string, {
+        columns?: Record<string, unknown>;
+        indexes?: Record<string, {
+            columns?: string[];
+        }>;
+        retain?: RetentionPolicy;
+    }>;
+}
+export interface StoreSwap {
+    deliveries?: StoreDelivery[];
+    refreshes?: StoreRefresh[];
+    tombstones?: StoreTombstone[];
+    retention?: Record<string, RetentionPolicy>;
+    schema?: OfflineSchema;
+    watermark?: WatermarkRecord;
+    resetCoverage?: boolean;
+    /** One validated resume response, including unchanged; never a query re-delivery. */
+    resumeSeq?: number;
+    dropAnswers?: string[];
+    outbox?: {
+        put?: OutboxEntry[];
+        remove?: string[];
+    };
+    /**
+     * Byte-cache puts and read touches; they land in the same swap as the rows: one
+     * readwrite transaction on IndexedDB, an ordered payload write + state rename with
+     * a sweep on open for the Node file carrier.
+     */
+    bytes?: ByteSwapRequest;
+    /** View-once rows viewed now: excluded from every later answer, their bytes never cached. */
+    viewed?: RowRef[];
+    /** `current` names the grant new intents consume; `null` clears it. */
+    grants?: {
+        put?: OutboxGrant[];
+        current?: string | null;
+        remove?: string[];
+    };
+    /** Predicted rows keyed by intent; visible to the twin's local evaluation, never to `answer()` (LLP 1012 §7). */
+    overlay?: {
+        put?: Record<string, OverlayRow[]>;
+        remove?: string[];
+    };
+    /** The certified programs, replaced whole (one generation is held at a time); custody like the outbox. */
+    programs?: Record<string, HeldProgram>;
+    /** The facts the swap's envelopes were delivered under; cleared by `resetCoverage`. */
+    facts?: CoverageFacts;
+    /** A rotation: the facts a refused delivery arrived under; held coverage is superseded until rebuild completion clears it with `null`. */
+    superseded?: CoverageFacts | null;
+    /**
+     * The program's write bounds, replaced whole: what `/api/program` certified each op may
+     * mint. Custody like the outbox — a coverage reset never touches it (LLP 1012 §7).
+     */
+    bounds?: Record<string, number>;
+}
+export interface RangeStore {
+    open(partition: PrincipalPartition): Promise<void>;
+    unseal(): Promise<void>;
+    seal(): Promise<void>;
+    wipe(partition: PrincipalPartition): Promise<void>;
+    answer<Result = unknown>(op: string, args: unknown): Promise<HeldAnswer<Result> | undefined>;
+    commit(swap: StoreSwap): Promise<void>;
+    coverage(): Promise<Coverage>;
+    readonly outbox: OutboxStore;
+    close?(): Promise<void> | void;
+}
+export interface RangeStoreFactory {
+    (): RangeStore;
+    readonly carrier?: string;
+}
+export declare class OfflineStoreFailure extends Error {
+    readonly code: "E_OFFLINE_CARRIER" | "E_OFFLINE_LOCK";
+    readonly rewrite?: string | undefined;
+    constructor(code: "E_OFFLINE_CARRIER" | "E_OFFLINE_LOCK", message: string, rewrite?: string | undefined);
+}
+export interface PersistedRangeState {
+    version: 1;
+    sealed: boolean;
+    clock: number;
+    rows: Record<string, StoredRow>;
+    answers: Record<string, StoredAnswer>;
+    watermarks: Record<string, WatermarkRecord>;
+    outbox: Record<string, OutboxEntry>;
+    grants: Record<string, OutboxGrant>;
+    currentGrant?: string;
+    overlay: Record<string, OverlayRow[]>;
+    /** Per committed intent, successful resumes or proven tail advances without its rows. */
+    overlayMisses: Record<string, number>;
+    /** The commit-time tail snapshot; null after reset until the next drain establishes a new head. */
+    overlayWatermarks: Record<string, OverlayWatermark | null>;
+    /** Only primary absences and tombstones, scoped to each prediction's ids. */
+    overlayNegatives: Record<string, Record<string, {
+        seq: number;
+        source: "absence" | "tombstone";
+    }>>;
+    bounds: Record<string, number>;
+    programs: Record<string, HeldProgram>;
+    facts?: CoverageFacts;
+    superseded?: CoverageFacts;
+    negative: Record<string, number>;
+    rowSeq: Record<string, number>;
+    /** The byte-cache index; payloads live beside the state in the carrier, keyed by `byteKey`. */
+    assets: Record<string, ByteCacheEntry>;
+    viewed: Record<string, ViewedRecord>;
+}
+export interface RangeStoreBackend {
+    readonly carrier: string;
+    open(partition: PrincipalPartition): Promise<PersistedRangeState | undefined>;
+    /** One carrier transaction: the state, plus the byte payloads to write and the keys to drop. */
+    replace(state: PersistedRangeState, bytes: ByteDelta): Promise<void>;
+    readBytes?(key: string): Promise<Uint8Array | undefined>;
+    wipe(partition: PrincipalPartition): Promise<void>;
+    close(): Promise<void> | void;
+}
+export declare function emptyState(): PersistedRangeState;
+export declare function canonicalAnswerKey(op: string, args: unknown): string;
+export declare function rowReference(table: string, id: string): {
+    $row: RowRef;
+};
+/** One JSON form for warm state and every carrier: omit undefined fields, preserve null. */
+export declare function jsonState<T>(value: T): T;
+/**
+ * The log a settlement's tail request and a resume's `log` both name: the drained
+ * query whose watermark was recorded first in this partition — the first-mounted
+ * drain, since a drain records its watermark when it first catches up — by the
+ * store's durable `order`, so the choice survives restarts and re-marks and never
+ * follows whichever page moved last (LLP 1012 §7, §8).
+ */
+export declare function tailWatermark(watermarks: WatermarkRecord[]): WatermarkRecord | undefined;
+/** Shared swap engine; carrier subclasses only provide the atomic replace. */
+export declare class PersistentRangeStore implements RangeStore {
+    private readonly backend;
+    private state;
+    private partition?;
+    private tail;
+    readonly outbox: OutboxStore;
+    constructor(backend: RangeStoreBackend);
+    open(partition: PrincipalPartition): Promise<void>;
+    unseal(): Promise<void>;
+    seal(): Promise<void>;
+    wipe(partition: PrincipalPartition): Promise<void>;
+    answer<Result = unknown>(op: string, args: unknown): Promise<HeldAnswer<Result> | undefined>;
+    coverage(): Promise<Coverage>;
+    commit(swap: StoreSwap): Promise<void>;
+    /** The cached rendition for an asset at a width; nothing when unheld, sealed, or the payload is gone. */
+    readBytes(assetId: string, width: number | null): Promise<{
+        bytes: Uint8Array;
+        type: string;
+    } | undefined>;
+    bytes(): Promise<ByteCacheStatus>;
+    /** Held rows whose values carry this asset record: the lease under which its bytes may be cached. */
+    rowsReferencing(assetId: string): Promise<StoredRow[]>;
+    /** True while every held row carrying this asset is a viewed view-once row (per row, LLP 1012 §9). */
+    viewedAsset(assetId: string): Promise<boolean>;
+    /** The viewed view-once rows; a live frame nulls them exactly as a held answer does. */
+    viewedRows(): Promise<RowRef[]>;
+    /**
+     * LRU read stamps, coalesced per swap: a read stamps the entry in memory and the next
+     * swap's `replace` persists it, so a read never rewrites the carrier (LLP 1012 §9).
+     */
+    touchBytes(keys: string[]): Promise<void>;
+    close(): Promise<void>;
+    private applySwap;
+    private ensureOpen;
+    private ensureUnsealed;
+    private enqueue;
+    private read;
+}

package/dist/store/sqlite-driver.conformance.d.ts

@@ -0,0 +1,7 @@
+import type { SqliteDriver } from "./sqlite-driver.js";
+export interface SqliteConformanceResult {
+    journalMode: string;
+    checks: string[];
+}
+/** Portable: the witness passes two independently opened connections to the same scratch database. */
+export declare function runSqliteDriverConformance(open: () => SqliteDriver | Promise<SqliteDriver>): Promise<SqliteConformanceResult>;

package/dist/store/sqlite-driver.d.ts

@@ -0,0 +1,16 @@
+export type SqliteParams = Array<string | number | null | Uint8Array>;
+export interface SqliteExecutor {
+    run(sql: string, params?: SqliteParams): Promise<void>;
+    get<T>(sql: string, params?: SqliteParams): Promise<T | undefined>;
+    all<T>(sql: string, params?: SqliteParams): Promise<T[]>;
+}
+export interface SqliteDriver extends SqliteExecutor {
+    /** Stable identity of the database, shared by every connection/factory opening it. */
+    readonly identity: string;
+    exec(sql: string): Promise<void>;
+    /** All statements in body must use tx. Commit only after its promise resolves. */
+    transaction<T>(body: (tx: SqliteExecutor) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+/** Outer operations wait for an async transaction; its executor bypasses the queue. */
+export declare function driverQueue(): <T>(body: () => Promise<T>) => Promise<T>;

package/dist/store/sqlite-expo.d.ts

@@ -0,0 +1,3 @@
+import { type SqliteDriver } from "./sqlite-driver.js";
+/** Requires Expo SDK 54's initialized runtime (including structuredClone). */
+export declare function expoSqliteDriver(name?: string): SqliteDriver;

package/dist/store/sqlite.d.ts

@@ -0,0 +1,31 @@
+import { type PersistedRangeState, type RangeStoreBackend, type RangeStoreFactory } from "./range-store.js";
+import type { ByteDelta } from "./byte-cache.js";
+import { type StoreLocks } from "./locks.js";
+import type { SqliteDriver } from "./sqlite-driver.js";
+export type { SqliteDriver, SqliteExecutor, SqliteParams } from "./sqlite-driver.js";
+export { inProcessLocks } from "./locks.js";
+export interface SqliteRangeStoreOptions {
+    locks?: StoreLocks;
+    /** Witness barrier, after all DML and inside the transaction, before COMMIT. */
+    beforeCommit?: (state: PersistedRangeState, bytes: ByteDelta) => void | Promise<void>;
+}
+type DriverSource = SqliteDriver | (() => SqliteDriver | Promise<SqliteDriver>);
+/** Public backend seam: byte deltas share replace's transaction; wipe deletes all five tables. */
+export declare class SqliteBackend implements RangeStoreBackend {
+    private readonly source;
+    private readonly options;
+    readonly carrier = "SQLite";
+    private driver?;
+    private partition?;
+    private release?;
+    private locks?;
+    constructor(source: DriverSource, options?: SqliteRangeStoreOptions);
+    private guard;
+    open(partition: string): Promise<PersistedRangeState | undefined>;
+    replace(state: PersistedRangeState, bytes: ByteDelta): Promise<void>;
+    readBytes(key: string): Promise<Uint8Array | undefined>;
+    wipe(partition: string): Promise<void>;
+    close(): Promise<void>;
+}
+/** Pass a driver factory when this factory will construct multiple clients. */
+export declare function sqliteRangeStore(driver: DriverSource, options?: SqliteRangeStoreOptions): RangeStoreFactory;

package/dist/templates/chat/expo/App.tsx

@@ -0,0 +1,29 @@
+import React, { lazy, Suspense, useEffect, useState } from "react";
+import { createExpoClient, SnapbackProvider } from "snapback2/expo";
+import type { SnapbackClient } from "snapback2/client";
+import { Text } from "react-native";
+import { Chat } from "./src/Chat";
+import { chatOffline } from "./shared/offline.js";
+
+const url = process.env.EXPO_PUBLIC_SNAPBACK_URL ?? "http://127.0.0.1:3210";
+// Metro inlines this in app source, never at simctl launch or inside node_modules.
+const witnessUrl = process.env.EXPO_PUBLIC_SNAPBACK_WITNESS;
+
+const Witness = witnessUrl ? lazy(() => import("./src/Witness")) : undefined;
+
+export function NormalApp() {
+  const [client, setClient] = useState<SnapbackClient>();
+  const [error, setError] = useState<string>();
+  useEffect(() => {
+    const client = createExpoClient({ url, as: "alice", offline: chatOffline });
+    setClient(client);
+    void client.ready.catch((error) => setError(String(error)));
+    return () => { void client.close(); };
+  }, []);
+  if (!client || error) return <Text accessibilityLiveRegion="polite">{error ?? "Connecting…"}</Text>;
+  return <SnapbackProvider client={client}><Chat /></SnapbackProvider>;
+}
+
+export default function App() {
+  return witnessUrl && Witness ? <Suspense fallback={<Text>Loading witness…</Text>}><Witness url={url} controlUrl={witnessUrl} /></Suspense> : <NormalApp />;
+}

package/dist/templates/chat/expo/app.json

@@ -0,0 +1,11 @@
+{
+  "expo": {
+    "name": "Snapback Chat",
+    "slug": "snapback-chat",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "jsEngine": "hermes",
+    "ios": { "bundleIdentifier": "dev.snapback.chat", "supportsTablet": true },
+    "plugins": ["expo-sqlite", "expo-secure-store", "expo-video"]
+  }
+}