@ebbjs/storage 0.0.0-stage → 0.1.1

package/dist/types/index.d.ts

@@ -0,0 +1,621 @@
+import { Action, Update, Entity } from '@ebbjs/core';
+
+/**
+ * One entry in the append-ordered action log.
+ *
+ * `position` is the log's own monotonic append cursor. It exists because
+ * the server `gsn` is not a total log cursor: an Action can arrive once
+ * per group (#473), `gsn: 0` is legal (#475 backfill), and a `gsn` cannot
+ * distinguish "already folded into the persisted replica" from
+ * "appended after it". The replica loads a persisted base at `position`
+ * and replays `readTail(position)`.
+ */
+interface LoggedAction {
+    /**
+     * The merged Action. A repeated id (#473) reports the union of every
+     * Update delivered for that id, not just this delivery's slice.
+     */
+    readonly action: Action;
+    /** The log-local append cursor for this Action. Stable across re-delivery. */
+    readonly position: number;
+    /**
+     * The Updates to fold. For `append`, only those not already logged for
+     * this id — a repeated Action id (`#473`) can carry disjoint per-group
+     * copies, and folding a whole re-delivered copy would re-apply an older
+     * `put` and revert a newer `patch`. For `readTail`, every Update of the
+     * merged Action.
+     */
+    readonly added: readonly Update[];
+}
+/**
+ * ActionLog — the append-ordered, id-keyed source of truth.
+ *
+ * The replica's durable log. `append` returns the newly-added Updates and
+ * the log-local position; `readTail` replays the entries after a
+ * watermark. `getAll` / `getForEntity` remain for the entity store that
+ * still backs the pre-replica read path.
+ *
+ * ## Methods
+ * - `append(action)` — stores or merges an Action, returns the delta + position
+ * - `appendMany(actions)` — `append` for a batch, in one durable write
+ * - `readTail(afterPosition)` — every entry with `position > afterPosition`, in order
+ * - `lastPosition()` — the log's current append cursor
+ * - `getAll()` — returns all merged Actions
+ * - `getForEntity(entityId)` — returns all Actions affecting an entity, sorted by gsn
+ * - `clear()` — removes all actions (used for reset)
+ */
+interface ActionLog {
+    append(action: Action): Promise<LoggedAction>;
+    /**
+     * Append every Action in one durable write (one IndexedDB transaction), in
+     * order, returning the same entries `append` would. A listing seed writes a
+     * page this way: the page is the unit that must land whole or not at all
+     * (#476).
+     */
+    appendMany(actions: readonly Action[]): Promise<readonly LoggedAction[]>;
+    readTail(afterPosition: number): Promise<readonly LoggedAction[]>;
+    lastPosition(): Promise<number>;
+    getAll(): Promise<readonly Action[]>;
+    getForEntity(entityId: string): Promise<readonly Action[]>;
+    clear(): Promise<void>;
+}
+
+/**
+ * DirtyTracker — tracks which entities need rematerialization.
+ *
+ * An entity is "dirty" when it has pending actions that haven't been
+ * applied to the materialized entity cache. Callers should invoke
+ * `mark(entityId, entityType)` when an action affects an entity, then
+ * materialize via `EntityStore.get()` or `EntityStore.query()`.
+ *
+ * ## Methods
+ * - `mark(entityId, entityType)` — marks an entity dirty (idempotent)
+ * - `isDirty(entityId)` — checks if an entity needs materialization
+ * - `getDirtyForType(entityType)` — returns all dirty entity IDs of a type
+ * - `clear(entityId)` — clears dirty flag after materialization
+ * - `clearAll()` — clears all dirty flags (used for reset)
+ */
+interface DirtyTracker {
+    mark(entityId: string, entityType: string): Promise<void>;
+    isDirty(entityId: string): Promise<boolean>;
+    getDirtyForType(entityType: string): Promise<readonly string[]>;
+    clear(entityId: string): Promise<void>;
+    clearAll(): Promise<void>;
+}
+
+/**
+ * Lookup key for the relationship index: the accessor name (`as`),
+ * the relationship type string, and the target entity id.
+ */
+interface RelationshipIndexQuery {
+    readonly as: string;
+    readonly type: string;
+    readonly targetId: string;
+}
+/**
+ * Lookup key for the source-keyed forward relationship index: the
+ * accessor name (`as`), the relationship type string, and the source
+ * entity id.
+ */
+interface RelationshipSourceQuery {
+    readonly as: string;
+    readonly type: string;
+    readonly sourceId: string;
+}
+/** One live relationship edge read from the source side. */
+interface RelationshipLink {
+    /** The `relationship` row id — the `subject_id` an unlink names. */
+    readonly relationshipId: string;
+    readonly targetId: string;
+}
+/** One live membership row read from the member entity side. */
+interface MembershipLink {
+    /** The `entityGroup` row id — the `subject_id` a delete names. */
+    readonly membershipId: string;
+    readonly groupId: string;
+}
+/**
+ * EntityStore — materialized entity cache supporting get-by-ID and query-by-type.
+ *
+ * Entities are materialized on-demand from the action log when they are dirty.
+ * The entity store is not responsible for marking entities dirty — that is
+ * handled by the DirtyTracker.
+ *
+ * ## Merge Semantics
+ * - **put** — full entity replacement
+ * - **patch** — field-level Last-Writer-Wins (LWW): higher HLC wins; tiebreak by lexicographic `update_id`
+ * - **delete** — soft delete (sets `deleted_hlc`); patch-on-deleted is ignored
+ *
+ * A field value is either a leaf merged by the LWW rule above, or a
+ * `{ map }` of nested field values merged key by key under the same
+ * rule. Map key sets are unioned, so a write to one key leaves its
+ * siblings untouched; a leaf `value: null` is a tombstone retained for
+ * late-apply and hidden by projection.
+ *
+ * ## Methods
+ * - `get(id)` — returns entity by ID, materializes if dirty
+ * - `set(entity)` — directly sets an entity (bypasses materialization)
+ * - `query(type)` — returns all materialized entities of a type
+ * - `queryByRelationship({ as, type, targetId })` — returns the distinct
+ *   source ids indexed under that triple in ascending order,
+ *   materializing dirty relationship rows first
+ * - `queryByRelationshipSource({ as, type, sourceId })` — returns the
+ *   live edges out of that source, ascending by target id,
+ *   materializing dirty relationship rows first
+ * - `queryByMembership(groupId)` — returns the distinct live member
+ *   entity ids whose `entityGroup` row points at the group, ascending,
+ *   materializing dirty `entityGroup` rows first
+ * - `queryByMembershipEntity(entityId)` — returns the live membership
+ *   rows of that member entity, ascending by group id, materializing
+ *   dirty `entityGroup` rows first
+ * - `reset()` — clears all cached entities
+ */
+interface EntityStore {
+    get(id: string): Promise<Entity | null>;
+    set(entity: Entity): Promise<void>;
+    query(type: string): Promise<readonly Entity[]>;
+    queryByRelationship(query: RelationshipIndexQuery): Promise<readonly string[]>;
+    queryByRelationshipSource(query: RelationshipSourceQuery): Promise<readonly RelationshipLink[]>;
+    queryByMembership(groupId: string): Promise<readonly string[]>;
+    queryByMembershipEntity(entityId: string): Promise<readonly MembershipLink[]>;
+    reset(): Promise<void>;
+}
+
+/**
+ * CursorStore — per-group sync resume state for the client.
+ *
+ * One record per group holds the cursor its view is complete as of, and,
+ * while a group listing seed is in flight, the marker that pins the seed's
+ * watermark so a crash redoes the same listing instead of a newer one
+ * (#476). Cursor and marker live in one record because they are one resume
+ * concept: the bootstrap trigger is a single read.
+ *
+ * ## Methods
+ * - `get(groupId)` — the group's cursor (GSN), or null if none
+ * - `set(groupId, cursor)` — writes the cursor, keeping any seed marker
+ * - `getRecord(groupId)` — the whole resume record (`{cursor?, seed?}`)
+ * - `setRecord(groupId, record)` — replaces the record; omitting `seed`
+ *   clears the marker, which is how the final seed page commits, and
+ *   `through` records how far the seed's base folded
+ * - `records()` — every group's record, for the handshake's cursor map
+ * - `clear()` — drops every group's resume state (a full local sync reset)
+ */
+/**
+ * A listing seed in flight: the watermark the redo must reuse and the
+ * server page token to resume from.
+ *
+ * `w` is absent while page 1's seed has not committed — the attempt then
+ * holds no rows that a newer watermark could skip past, so the redo lists
+ * from page 1 afresh (see `bootstrapGroupListing`). `token` is absent when
+ * `w` is, and otherwise names the page after the last one already seeded.
+ */
+interface SeedMarker {
+    /** The group being seeded. Guards a record against reuse across groups. */
+    readonly group_id: string;
+    /** Pinned listing watermark; absent while page 1's seed is uncommitted. */
+    readonly w?: number;
+    /** Opaque server page token for the next page to list. */
+    readonly token?: string;
+}
+/** One group's durable resume state. */
+interface CursorRecord {
+    /** Highest GSN the group's view is complete as of. Absent before any seed or catch-up. */
+    readonly cursor?: number;
+    /** Present while a listing seed is in flight. */
+    readonly seed?: SeedMarker;
+    /**
+     * Highest entity log position the group's seeded base folded. A row's
+     * `last_gsn` at or below it is the server's own state, so a re-delivered
+     * `put` / `delete` inside that window is already reflected and must not be
+     * folded again (#476). Absent until a listing seed completes; it outlives
+     * the marker because the tail re-delivers after the seed finishes.
+     */
+    readonly through?: number;
+}
+interface CursorStore {
+    get(groupId: string): Promise<number | null>;
+    set(groupId: string, cursor: number): Promise<void>;
+    getRecord(groupId: string): Promise<CursorRecord | null>;
+    setRecord(groupId: string, record: CursorRecord): Promise<void>;
+    records(): Promise<ReadonlyMap<string, CursorRecord>>;
+    clear(): Promise<void>;
+}
+
+/**
+ * The persisted form of the materialized replica — the replica at rest.
+ *
+ * `position` is the `ActionLog` append cursor the record was taken at:
+ * load is `record ⊕ readTail(record.position)`. `revision` is the
+ * replica's observable-content version at that point. `entities` is the
+ * row-shaped entity set; derived indices are rebuilt on load, never
+ * persisted, because IndexedDB cannot index nested `FieldValue` paths,
+ * express live-row filtering, or query a stored map.
+ */
+interface ReplicaRecord {
+    /** Shape version of this record. A record of an unknown format reads as absent. */
+    readonly format: number;
+    /** The log position the record was taken at. */
+    readonly position: number;
+    /** The replica's revision when the record was taken. */
+    readonly revision: number;
+    readonly entities: readonly Entity[];
+}
+/**
+ * ReplicaStore — single-slot persistence for the materialized replica.
+ *
+ * Only ever a fast path. Correctness never depends on the record
+ * existing: an absent or corrupt record reads as `null` so the caller
+ * falls back to full log replay rather than hydrating a partial base.
+ */
+interface ReplicaStore {
+    load(): Promise<ReplicaRecord | null>;
+    save(record: ReplicaRecord): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * A monotonic counter over the replica's observable content. It bumps once
+ * per entity change a reader could see — never for delivery bookkeeping like
+ * `last_gsn` — so it doubles as the invalidation token for derived state.
+ */
+type Revision = number;
+/** One observable entity change, appended to the revision journal. */
+interface ReplicaChange {
+    readonly revision: Revision;
+    readonly id: string;
+    readonly type: string;
+    readonly deleted: boolean;
+}
+/**
+ * Whether the replica retains a type's rows. The seam #500 builds on-demand
+ * residency against: a policy that holds nothing lets the engine fetch a type
+ * on first read and react to the journal it still receives.
+ */
+interface MaterializationPolicy {
+    holds(type: string): boolean;
+}
+interface ReplicaOptions {
+    readonly materialization?: MaterializationPolicy;
+    /**
+     * Reads a row from the local stores when `open` misses. Without it an
+     * on-demand id that is not resident stays a miss.
+     */
+    readonly readEntity?: (id: string) => Promise<Entity | null>;
+    /**
+     * Maximum resident on-demand rows. Defaults to 16. A non-positive or
+     * non-finite value keeps every opened row resident; opening past the
+     * window releases the least recently opened one.
+     */
+    readonly pinnedCapacity?: number;
+    /**
+     * How long a closed on-demand row stays cached before release. Defaults to
+     * 30_000 ms. A non-positive or non-finite value releases it immediately on
+     * close. An open row is never released by the TTL.
+     */
+    readonly pinnedTtlMs?: number;
+    /**
+     * Maximum retained change-journal entries after trimming. Defaults to 1024.
+     * A non-positive or non-finite value keeps the journal unbounded; a
+     * positive fraction retains at least one entry.
+     */
+    readonly journalCapacity?: number;
+}
+/** A snapshot of what the replica currently materializes and retains. */
+interface ReplicaStats {
+    /** Number of row objects currently materialized (tombstones included). */
+    readonly entities: number;
+    /** Materialized row count per entity type. */
+    readonly byType: Readonly<Record<string, number>>;
+    /** Rows retained because their type is held: the metadata footprint. */
+    readonly held: number;
+    /** Held row count per type; excludes opened on-demand rows. */
+    readonly heldByType: Readonly<Record<string, number>>;
+    /** Resident on-demand rows (open or closed and waiting out their TTL). */
+    readonly pinned: number;
+    readonly revision: Revision;
+    /** Append cursor of the last durable position folded into the base. */
+    readonly position: number;
+    /** Retained journal entries. */
+    readonly changes: number;
+    /** Oldest revision after which `changesSince` is complete. */
+    readonly changeFloor: Revision;
+}
+/**
+ * Adjacency read key for the replica's relationship index. `sourceId`
+ * reads forward — the targets out of the source; `targetId` reads
+ * reverse — the sources pointing at the target. `sourceId` wins when
+ * both are set, and neither yields no ids.
+ */
+interface RelationshipQuery {
+    readonly as: string;
+    readonly type: string;
+    readonly sourceId?: string;
+    readonly targetId?: string;
+}
+/**
+ * Adjacency read key for the replica's membership index. `groupId`
+ * reads the group's members; `entityId` reads the entity's groups.
+ * `groupId` wins when both are set, and neither yields no ids.
+ */
+interface MembershipQuery {
+    readonly groupId?: string;
+    readonly entityId?: string;
+}
+/**
+ * The materialized read path. Writes are synchronous and single-writer: the
+ * caller serializes them and folds durable updates in ascending log position.
+ * Reads return the replica's own row objects (shared, not cloned), tombstones
+ * included; callers must treat them as immutable.
+ */
+interface Replica {
+    readonly revision: Revision;
+    /**
+     * Smallest revision for which the retained journal is complete: the
+     * revision of the newest trimmed change, or the loaded record's revision.
+     * A `changesSince` below this floor yields nothing because everything may
+     * have changed.
+     */
+    readonly changeFloor: Revision;
+    get(id: string): Entity | undefined;
+    /**
+     * The durable base row for `id`, without this client's optimistic overlay
+     * writes. A reader judging "has this row already folded a later Action than
+     * the one I am delivering" must read the base: an overlay `put` composes
+     * with gsn 0, which would hide the row's folded position.
+     */
+    base(id: string): Entity | undefined;
+    iterate(type: string): readonly Entity[];
+    /** Whether the materialization policy holds `type` in full. */
+    isHeld(type: string): boolean;
+    /**
+     * Load `id` through `readEntity` when absent, pinning it and journaling the
+     * install so a derived reader sees the row arrive. Idempotent: a resident row
+     * is marked open and touched (LRU order) without another read, a concurrent
+     * open shares the in-flight read, and a held row is returned without
+     * installing or pinning. Resolves to the composed row, or `null` when the
+     * read misses.
+     */
+    open(id: string): Promise<Entity | null>;
+    /**
+     * Close a pinned row. It stays cached until `pinnedTtlMs` so a remount reads
+     * it back, then leaves; with the TTL disabled it leaves immediately. A no-op
+     * for held rows.
+     */
+    close(id: string): void;
+    /** Whether `id` is currently open (closed rows waiting out their TTL are not). */
+    isOpen(id: string): boolean;
+    /**
+     * Changes newer than `revision`, ascending. Empty when the cursor predates
+     * `changeFloor`, where the trimmed journal can no longer answer it.
+     */
+    changesSince(revision: Revision): readonly ReplicaChange[];
+    stats(): ReplicaStats;
+    /**
+     * Distinct live targets out of `(as, type, sourceId)`, or distinct
+     * live sources pointing at `(as, type, targetId)`, ascending.
+     */
+    relationships(query: RelationshipQuery): readonly string[];
+    /**
+     * Distinct live member entity ids of a group, or distinct live group
+     * ids of an entity, ascending.
+     */
+    memberships(query: MembershipQuery): readonly string[];
+    /** Live forward relationship edges out of a source, ascending by target then row id. */
+    relationshipLinks(query: RelationshipSourceQuery): readonly RelationshipLink[];
+    /** Live member-keyed membership rows of an entity, ascending by group then row id. */
+    membershipLinks(entityId: string): readonly MembershipLink[];
+    /** Fold one durable Action's `delta` at its log position. */
+    ingest(action: Action, delta: readonly Update[], position: number): Revision;
+    /** Fold an unacknowledged local Action into the overlay only. */
+    optimistic(action: Action): Revision;
+    /** Drop an overlay Action's writes, reverting the composed view. */
+    discard(actionId: string): Revision;
+    /**
+     * Replace the materialized base with `record`. The journal resets to that
+     * baseline. The revision advances to the record's revision when that is
+     * newer, and by one otherwise, so a derived reader always observes the
+     * wholesale replacement even when the record is the same revision.
+     */
+    load(record: ReplicaRecord): Revision;
+    toRecord(): ReplicaRecord;
+    /**
+     * Drop rows from the in-memory base and indices without tombstoning them:
+     * afterwards `get(id)` is undefined and `iterate(type)` omits the row. Each
+     * removed row journals one change, so derived readers see it leave. Absent
+     * ids are ignored. Returns the resulting revision.
+     */
+    evict(ids: readonly string[]): Revision;
+    /**
+     * Subscribe to post-change notifications. Fires after every mutating call
+     * (`ingest` / `optimistic` / `discard` / `load` / `evict` / `open` /
+     * `close`) that settles the composed view, so a derived reader can
+     * resynchronise from `revision` and `changesSince`. A no-op write still
+     * fires; readers cheaply ignore an unchanged revision. Re-opening a resident
+     * row only touches the LRU window, so it fires nothing. Returns an
+     * unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+}
+
+/**
+ * Lifecycle status of a buffered local Action. The store persists
+ * whatever status the writer assigns; which transitions are legal, and
+ * when they happen, is the client outbox's concern, not storage's.
+ *
+ * `conflicted` is a terminal-until-resolved hold: a catch-up pass
+ * classified the Action as a loser, so it is structurally excluded from
+ * `pending()` and never submitted. The application resolves it by
+ * retrying (back to `pending`) or discarding (removed).
+ */
+type OutboxStatus = "pending" | "acknowledged" | "error" | "conflicted";
+/**
+ * One side of a contested slot: the buffered local write, or the value
+ * the server holds once the catch-up window is applied. A leaf carries
+ * its LWW triple; a whole-field map replacement has no single leaf, so
+ * `update_id` / `hlc` are absent and `value` is the projected map. A
+ * field an inbound `put` or `delete` reverted also has no triple, and
+ * `value` is `undefined` because the server holds no value.
+ */
+interface ConflictSide {
+    /** Projected leaf or map value. `undefined` when the server holds nothing. */
+    readonly value: unknown;
+    /** `update_id` of the FieldValue; absent for a map side or a reverted field. */
+    readonly update_id?: string;
+    /** HLC carried by the FieldValue; absent for a map side or a reverted field. */
+    readonly hlc?: string;
+}
+/**
+ * One contested position on a losing Action: a field plus the map-key
+ * path from the field root to the position. `path` is empty for a plain
+ * leaf field, an entity-level touch that overlaps no position, or a
+ * field an inbound `put` / `delete` reverted. Concurrent writes to
+ * different keys are different slots and so are not conflicts.
+ */
+interface ConflictSlot {
+    /** The `subject_id` of the Update that carried the write. */
+    readonly subjectId: string;
+    /** The field name on that subject. */
+    readonly field: string;
+    /** Ordered map keys from the field root to the position; empty at the root. */
+    readonly path: readonly string[];
+    /** The buffered local value at the position. */
+    readonly local: ConflictSide;
+    /** The value the server holds at the position after the missed window. */
+    readonly remote: ConflictSide;
+}
+/**
+ * The before/after entity rows for one losing subject. `before` is the
+ * row as the client had it immediately before the catch-up window was
+ * applied: last-synced server state with its own unflushed writes
+ * optimistically applied. `after` is the materialized row at detection,
+ * once the inbound window has replaced the optimistic row with the
+ * server's view. Both are structured-clone copies, not references into
+ * the action log, so the comparison survives a reload and compaction.
+ */
+interface ConflictSubjectState {
+    readonly subjectId: string;
+    readonly subjectType: string;
+    readonly before: Entity | null;
+    readonly after: Entity | null;
+}
+/**
+ * The conflict payload detection stamps onto a losing Action's outbox
+ * row. It travels with the row rather than in a second store, so the
+ * hold and the record are the same durable write and cannot disagree.
+ */
+interface OutboxConflict {
+    /**
+     * Subjects that actually lost. A create-plus-update write names only
+     * the entity that lost, so a freshly created entity is not dragged in.
+     */
+    readonly subjects: readonly string[];
+    /**
+     * Full entity rows for each losing subject, in the same order as
+     * `subjects`. `after` is read as the materialized row at detection and
+     * is `null` only when replay yields no row.
+     */
+    readonly subjectStates: readonly ConflictSubjectState[];
+    /**
+     * Overlapping contested positions, in detection order. Empty when the
+     * entity-level scope surfaced a subject with no position overlap; an
+     * application reads that as "nothing of mine would be lost".
+     */
+    readonly slots: readonly ConflictSlot[];
+    /** The catch-up pass that produced this entry. */
+    readonly catchUpId: string;
+    /**
+     * Stamped at detection and persisted, so it survives a reload and
+     * partial resolution. Grouping is the connected set of losing
+     * subjects within one `catchUpId`.
+     */
+    readonly conflictId: string;
+    /** Client HLC stamped at detection. The conflict view's ordering key. */
+    readonly detectedAtHlc: string;
+}
+/**
+ * One locally-authored Action awaiting acknowledgement, plus the HLC at
+ * which it entered the outbox. A `conflicted` entry carries its
+ * {@link OutboxConflict} payload; the field is absent for every other
+ * status.
+ */
+interface OutboxEntry {
+    readonly action: Action;
+    readonly status: OutboxStatus;
+    /**
+     * Client HLC stamped when the Action was buffered. The ordering key
+     * for `list()` — Actions must flush in the order they were authored,
+     * independent of object-store iteration order.
+     */
+    readonly enqueuedAtHlc: string;
+    /**
+     * Highest server GSN the client had applied when the Action was
+     * authored. Catch-up detection treats an inbound Action as concurrent
+     * when its GSN is greater; `0` means "always concurrent", so a legacy
+     * or base-less entry is never silently dropped.
+     */
+    readonly basedOnGsn: number;
+    /** Present iff `status === "conflicted"`. */
+    readonly conflict?: OutboxConflict;
+}
+/**
+ * OutboxStore — durable buffer of pending local Actions.
+ *
+ * Entries are keyed by `action.id`. Re-`put`ting an id replaces the
+ * whole row, which is how a status transition — including a detection
+ * that stamps a conflict payload — is persisted; `list()` returns
+ * entries in ascending `enqueuedAtHlc` order so a rehydrating client
+ * replays them in authoring order.
+ */
+interface OutboxStore {
+    put(entry: OutboxEntry): Promise<void>;
+    /**
+     * Persist `entry` and delete `deleteId` in one durable operation. Used
+     * to resolve a conflict by retrying: the fresh re-assert must never
+     * exist without the conflicted row being gone, nor the row be gone
+     * without the re-assert persisted.
+     */
+    putAndDelete(entry: OutboxEntry, deleteId: string): Promise<void>;
+    list(): Promise<readonly OutboxEntry[]>;
+    get(actionId: string): Promise<OutboxEntry | null>;
+    delete(actionId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * StorageAdapter — unified interface composing all storage components.
+ *
+ * Use `createMemoryAdapter()` from `@ebbjs/storage` to get a full
+ * in-memory implementation.
+ *
+ * ## Composition
+ * - `actions` — ActionLog for storing and querying actions
+ * - `entities` — EntityStore for materialized entity cache
+ * - `dirtyTracker` — DirtyTracker for tracking entities needing materialization
+ * - `cursors` — CursorStore for per-group GSN tracking
+ * - `outbox` — OutboxStore for durable pending local Actions; a detected
+ *   conflict is a status + payload on its outbox row, not a sibling store
+ * - `replica` — ReplicaStore for the persisted materialized replica; single-slot
+ *   and a fast path only
+ *
+ * ## Cross-cutting Methods
+ * - `isDirty(entityId)` — delegates to dirtyTracker
+ * - `reset()` — clears the action log, dirty flags, entity cache, the
+ *   persisted replica, and every group cursor; outbox entries are durable
+ *   user data and survive a reset
+ */
+interface StorageAdapter {
+    readonly actions: ActionLog;
+    readonly entities: EntityStore;
+    readonly dirtyTracker: DirtyTracker;
+    readonly cursors: CursorStore;
+    readonly outbox: OutboxStore;
+    /**
+     * Single-slot persistence for the replica. An absent or corrupt record
+     * reads as `null`, so correctness never depends on it existing.
+     */
+    readonly replica: ReplicaStore;
+    isDirty(entityId: string): Promise<boolean>;
+    reset(): Promise<void>;
+}
+
+export type { ActionLog, ConflictSide, ConflictSlot, ConflictSubjectState, CursorRecord, CursorStore, DirtyTracker, EntityStore, LoggedAction, MaterializationPolicy, MembershipLink, MembershipQuery, OutboxConflict, OutboxEntry, OutboxStatus, OutboxStore, RelationshipIndexQuery, RelationshipLink, RelationshipQuery, RelationshipSourceQuery, Replica, ReplicaChange, ReplicaOptions, ReplicaRecord, ReplicaStats, ReplicaStore, Revision, SeedMarker, StorageAdapter };

package/dist/types/index.js

@@ -0,0 +1 @@
+