@kubun/store-graph 0.17.0 → 0.18.0

package/lib/api.d.ts

@@ -1,8 +1,53 @@
+import type { CustodyGuard, StoreAPIContext, StoreProvider } from '@kubun/db';
 import type { Adapter } from '@kubun/db-adapter';
 import { DocumentID, DocumentModelID } from '@kubun/id';
-import type { AggregateDocumentsParams, AggregateValues, DocumentModel, DocumentNode, GroupedAggregateDocumentsParams, GroupedAggregateValue } from '@kubun/protocol';
-import type { Kysely } from 'kysely';
-import type { AccessLevel, Catalog, ClusterDefinitionRow, ClusterModel, CreateDocumentParams, CreateGraphParams, GraphModel, GraphModelWithRecord, GraphTables, InsertCatalog, InsertClusterModel, InsertMutationLogEntry, ListDocumentsParams, MutationLogEntry, QueryDocumentsParams, QueryDocumentsResult, SaveDocumentParams, SearchDocumentResult, SearchDocumentsParams } from './tables.js';
+import type { AggregateDocumentsParams, AggregateValues, DocumentFieldsMeta, DocumentModel, DocumentModelSchema, DocumentNode, GroupedAggregateDocumentsParams, GroupedAggregateValue } from '@kubun/protocol';
+import type { Kysely, RawBuilder } from 'kysely';
+import { type GraphAccessDefaultRecordMethods } from './access-default-records.js';
+import type { GraphCatalogRecordMethods } from './catalog-records.js';
+import type { CatalogUse, DocumentAvailability, DocumentHold, DocumentScope, PlaceDocumentHoldParams, RouteRulesInput, ScopeCatalog, CatalogRef as ScopeCatalogRef, SweptDocument, UnavailableDocument } from './catalog-scope.js';
+import type { CatalogStateMethods } from './catalog-state.js';
+import type { AccessLevel, ClusterDefinitionRow, ClusterModel, CreateDocumentParams, CreateGraphParams, DocumentLeafPageParams, DocumentLeafRow, DocumentLeafRule, DocumentModelRow, GraphModel, GraphModelWithRecord, GraphTables, InsertClusterModel, InsertMutationLogEntry, ListDocumentsParams, MutationLogEntry, QueryDocumentsParams, QueryDocumentsResult, SaveDocumentParams, SearchDocumentResult, SearchDocumentsParams } from './tables.js';
+export declare function documentModelFromTable(row: DocumentModelRow): DocumentModel;
+export declare function documentModelToTable(adapter: Adapter, id: string, model: DocumentModel): {
+    id: string;
+    version: "1.0";
+    name: string;
+    behavior: "unique" | "default" | "interface";
+    unique_fields: string[] | null;
+    interfaces: Array<string>;
+    schema: DocumentModelSchema;
+    fields_meta: DocumentFieldsMeta;
+    provider_merge_policy: {
+        group: Array<string>;
+    } | null;
+    date_field: string | null;
+    resolved_date_field: string | null;
+};
+/**
+ * Reads a document's `field_values` cell on the given transaction and
+ * delegates the merge-policy liveness comparison to `@kubun/mutation`'s pure
+ * `winnerStateDigestOf`. Returns the winning live `$setFetch` digest, the
+ * constant deleted-state digest when the delete side wins, or `null` when the
+ * document (or its fetch-order registers) is absent.
+ *
+ * Because graph and connector tables share one DB connection (the KubunDB
+ * coordinator), a caller with its own transaction over a wider `DB` type
+ * passes it here cast to `Kysely<GraphTables>` (the same pattern
+ * `addDocumentModel` above already relies on) so the read joins that
+ * transaction rather than opening a second connection.
+ */
+export declare function readWinnerStateDigest(tx: Kysely<GraphTables>, documentID: string): Promise<string | null>;
+export type ReadWinnerStateDigestsParams = {
+    tx: Kysely<GraphTables>;
+    documentIDs: Iterable<string>;
+};
+/**
+ * Batch form of `readWinnerStateDigest`: one chunked `id in` read per model rather than one
+ * read per document. A document whose digest cannot be read (bad id, model table not deployed,
+ * no row, no digest) is left out of the map.
+ */
+export declare function readWinnerStateDigests(params: ReadWinnerStateDigestsParams): Promise<Map<string, string>>;
 /**
  * Persisted access rule shape as stored in `user_model_access_defaults`.
  */
@@ -28,7 +73,108 @@ export type StoredAccessDefaultRow = StoredAccessRule & {
      */
     hlc: string | null;
 };
-export type GraphStoreAPI = {
+export type RecomputeDocumentRefsParams = {
+    documentID: string;
+    routeRules: RouteRulesInput;
+    nowMS?: number;
+    catalog?: ScopeCatalogRef;
+    /** Custody pins to drop rather than keep, once a completed handoff is confirmed. */
+    releaseCustodyPins?: CustodyPinRelease;
+};
+export type CustodyPinRelease = {
+    refs: ReadonlyArray<string>;
+    /**
+     * Proves the handoff, called under the document's ref lock in the recomputing transaction, so
+     * no concurrent apply can change what it proved before the pins go. False keeps them.
+     */
+    confirm: () => Promise<boolean>;
+};
+export type SweepDocumentParams = {
+    documentID: string;
+    nowMS: number;
+    /** How long a document stays marked, with no change, before it may be swept. */
+    graceMS: number;
+    /**
+     * Proves the document may go (a valid receipt, or positive foreign ownership), called last,
+     * under the document's row and ref locks, with the sweeping transaction. False keeps it.
+     */
+    confirm: (stores: StoreProvider) => Promise<boolean>;
+};
+export type DocumentSweepRefusal = 'absent' | 'retained' | 'held' | 'unmarked' | 'changed' | 'grace' | 'pending' | 'unconfirmed';
+export type DocumentSweepResult = {
+    swept: true;
+} | {
+    swept: false;
+    refusal: DocumentSweepRefusal;
+};
+export type ReconcileCatalogModelRefsParams = {
+    modelID: string;
+    routeRules: RouteRulesInput;
+    nowMS: number;
+    owners?: Array<string>;
+    catalog?: ScopeCatalogRef;
+};
+export type RecordPendingMutationAttemptParams = {
+    mutationHash: string;
+    outcome: 'transient' | 'rejected' | 'applied';
+    now: number;
+    jitter: number;
+};
+export type UpdateSearchEntryParams = {
+    modelID: string;
+    documentID: string;
+    data: Record<string, unknown>;
+    fields: Array<string>;
+};
+export type RemoveUserModelAccessDefaultsParams = {
+    ownerDID: string;
+    modelID: string;
+    permissionTypes: Array<string>;
+    hlc: string;
+};
+export type GetDocumentIDsForScopeParams = {
+    scopes: Array<{
+        modelID: string;
+        ownerDID: string;
+    }>;
+    excludedDocumentIDs?: Array<string>;
+    /** Read at most this many IDs in total; a caller passes its cap plus one. */
+    limit?: number;
+    groupRead?: {
+        groupID: string;
+        circleIDs: Array<string>;
+    };
+};
+export type GCMark = {
+    documentID: string;
+    digest: string;
+    markedAt: number;
+};
+/** Whether a mark has waited out the grace: the sweep's own test, shared so a listing agrees. */
+export declare function gcMarkPastGrace(mark: Pick<GCMark, 'markedAt'>, graceMS: number, nowMS: number): boolean;
+export type DropGCMarkParams = Pick<GCMark, 'documentID' | 'digest'>;
+export type CustodyNonce = {
+    nonce: string;
+    custodian: string;
+    assignmentDigest: string;
+    expiresAt: number;
+};
+export type CustodyReceiptRecord = {
+    documentID: string;
+    custodian: string;
+    /** The custody owner's own-agents group the receipt was answered through. */
+    groupID: string;
+    custodyOwner: string;
+    catalog: ScopeCatalogRef;
+    assignmentDigest: string;
+    headDigest: string;
+    /** The digest of the accepted mutation IDs the custodian answered for. */
+    mutationDigest: string;
+    receivedAt: number;
+};
+/** Hex blake3 over mutation IDs, sorted and joined by newline: the document mutation digest. */
+export declare function mutationIDsDigest(mutationIDs: ReadonlyArray<string>): string;
+export type GraphStoreAPI = GraphAccessDefaultRecordMethods & GraphCatalogRecordMethods & CatalogStateMethods & {
     getDocument(id: DocumentID | string): Promise<DocumentNode | null>;
     /**
      * Batch fetch documents, returning a Map keyed by the document ID string. A
@@ -50,18 +196,200 @@ export type GraphStoreAPI = {
      * order from `addDocumentModel` (stable for a given graph creation).
      */
     getModelInterfaces(modelID: string): Promise<Array<string>>;
+    /**
+     * The interface IDs of every model that declares any, keyed by model, from
+     * one read. A model without interfaces is absent.
+     */
+    listModelInterfaces(): Promise<Map<string, Array<string>>>;
+    /** The deployed models among `ids`, from one read. An unknown ID is absent. */
+    getDocumentModelsByID(ids: ReadonlyArray<string>): Promise<Map<string, DocumentModel>>;
     createDocument(params: CreateDocumentParams): Promise<DocumentNode>;
     saveDocument(params: SaveDocumentParams): Promise<DocumentNode>;
+    getDocumentDates(documentID: string): Promise<{
+        createdAt: number | null;
+        updatedAt: number | null;
+        scopeDate: number | null;
+    } | null>;
+    setCatalogDefinition(ref: ScopeCatalogRef, catalog: ScopeCatalog): Promise<void>;
+    setScopeReaderDID(did: string, defaultReadLevel?: AccessLevel): Promise<void>;
+    setCatalogUse(ref: ScopeCatalogRef, use: CatalogUse): Promise<void>;
+    getCatalogUse(ref: ScopeCatalogRef): Promise<CatalogUse | null>;
+    /** The use of each catalog in `refs`, in order, from one read. */
+    getCatalogUses(refs: ReadonlyArray<ScopeCatalogRef>): Promise<Array<CatalogUse | null>>;
+    deleteCatalogUse(ref: ScopeCatalogRef): Promise<void>;
+    markDocumentLocal(documentID: string): Promise<void>;
+    /** Writes the hold row and its retain-only `hold:` ref in one transaction. */
+    placeDocumentHold(params: PlaceDocumentHoldParams): Promise<DocumentHold>;
+    /** Null when the hold is unknown or already released. */
+    releaseDocumentHold(holdID: string, nowMS: number): Promise<DocumentHold | null>;
+    getDocumentHold(holdID: string): Promise<DocumentHold | null>;
+    /** Holds on the document that are neither released nor expired at `nowMS`. */
+    listDocumentHolds(documentID: string, nowMS: number): Promise<Array<DocumentHold>>;
+    /**
+     * The earliest expiry among holds not released that scope aging has not yet passed, or null.
+     * It may already be due: aging recomputes a hold's document only once its tick passes it.
+     */
+    nextDocumentHoldExpiry(): Promise<number | null>;
+    getDocumentScope(documentID: string): Promise<DocumentScope>;
+    /**
+     * `LOCAL` for a document here (a tombstone reads null), `UNAVAILABLE` for one swept here that
+     * a retaining rule matches again, else null. Says nothing of who may read it.
+     */
+    getDocumentAvailability(documentID: string, nowMS: number): Promise<DocumentAvailability | null>;
+    /**
+     * The earliest time after `nowMS` at which a rule window starts or stops matching a swept
+     * document, or null. Ignores the read check: an extra wake costs one refresh.
+     */
+    nextSweptDocumentTransition(nowMS: number): Promise<number | null>;
+    /** What this device kept of a document it swept and has not re-acquired. */
+    getSweptDocument(documentID: string): Promise<SweptDocument | null>;
+    /** Swept documents a retaining rule matches again, ordered by ID, strictly after `after`. */
+    listUnavailableDocuments(params: {
+        nowMS: number;
+        limit: number;
+        after?: string;
+    }): Promise<Array<UnavailableDocument>>;
+    /**
+     * Evaluate swept documents (of one model, or all) against the current rules and record a scope
+     * change for each that started or stopped matching one. With `ttlMS`, drop those out of every
+     * scope for that long.
+     */
+    refreshSweptDocuments(params: {
+        nowMS: number;
+        ttlMS?: number;
+        modelID?: string;
+    }): Promise<void>;
+    /** Whether a custody pin or a `SERVE_ONLY` catalog keeps the live document's bytes here. */
+    documentNeedsBytes(documentID: string): Promise<boolean>;
+    /** Hex blake3 over the document's applied mutation hashes, sorted and joined by newline. */
+    documentMutationDigest(documentID: string): Promise<string>;
+    /** Whether every listed mutation is applied to the document. */
+    hasAppliedMutations(documentID: string, mutationIDs: ReadonlyArray<string>): Promise<boolean>;
+    /** Records a receipt nonce this device issued, dropping expired ones. */
+    putCustodyNonce(nonce: CustodyNonce): Promise<void>;
+    /** True once only: for an unexpired nonce issued to this custodian for this assignment. */
+    consumeCustodyNonce(params: Omit<CustodyNonce, 'expiresAt'> & {
+        nowMS: number;
+    }): Promise<boolean>;
+    /** One receipt per document and custodian; a later receipt replaces the earlier. */
+    putCustodyReceipts(receipts: ReadonlyArray<CustodyReceiptRecord>): Promise<void>;
+    /** Ordered by custodian. */
+    listCustodyReceipts(documentID: string): Promise<Array<CustodyReceiptRecord>>;
+    /** Documents holding this custody pin ref, ordered by ID, strictly after `after`. */
+    listCustodyPinnedDocuments(params: {
+        ref: string;
+        limit: number;
+        after?: string;
+    }): Promise<Array<string>>;
+    getGCMark(documentID: string): Promise<GCMark | null>;
+    /**
+     * Drop the document's mark only while it still carries `digest`: a mutation since remarks
+     * the document, and that mark stays. Dropping a mark only ever keeps a document.
+     */
+    dropGCMark(params: DropGCMarkParams): Promise<void>;
+    /** Marks ordered by document ID, strictly after `after`. */
+    listGCMarks(params: {
+        limit: number;
+        after?: string;
+    }): Promise<Array<GCMark>>;
+    /** Distinct documents holding any of the catalog's rule refs. */
+    countCatalogDocuments(ref: ScopeCatalogRef): Promise<number>;
+    listPendingScopeChanges(): Promise<Array<{
+        documentID: string;
+        version: number;
+    }>>;
+    ackDocumentScopeChange(documentID: string, version: number): Promise<void>;
+    recomputeDocumentRefs(params: RecomputeDocumentRefsParams): Promise<DocumentScope>;
+    /**
+     * Delete the document's graph rows, under its row and ref locks, once its refs recomputed now
+     * retain nothing, its mark is past grace with an unchanged digest, no pending mutation waits,
+     * and `confirm` agrees. Writes no tombstone; bumps the scope change so a displayed copy leaves
+     * the view. Call inside the transaction that also sweeps the other stores.
+     */
+    sweepDocument(params: SweepDocumentParams): Promise<DocumentSweepResult>;
+    /**
+     * Drop this custody pin ref from every document holding it, at once, under the exclusive ref
+     * lock; each recompute then marks or releases what nothing else keeps. Returns how many
+     * documents were recomputed. Deletes no document.
+     */
+    releaseCustodyPinRef(params: {
+        ref: string;
+        nowMS: number;
+    }): Promise<number>;
+    /** Whether a rule of the catalog, as this device stores its definition, matches the document. */
+    catalogRulesMatchDocument(params: {
+        catalog: ScopeCatalogRef;
+        documentID: string;
+        nowMS: number;
+    }): Promise<boolean>;
+    /**
+     * Lock the document's row until the transaction ends (Postgres; SQLite transactions already
+     * run one at a time) and say whether it exists. Taken first, as an apply and the sweep take
+     * it, so a writer outside the apply re-checks the document against a sweep without inverting
+     * their locks.
+     */
+    lockDocumentRow(documentID: string): Promise<boolean>;
+    /**
+     * Recompute these documents' refs in one transaction, under the all-documents ref lock.
+     * Absent documents are skipped.
+     */
+    recomputeDocuments(params: {
+        documentIDs: ReadonlyArray<string>;
+        routeRules: RouteRulesInput;
+        nowMS: number;
+    }): Promise<void>;
+    /**
+     * A catalog argument updates only that catalog's contribution, including former holders.
+     * Without one, the recompute of every document runs in batches, each in its own transaction
+     * when called outside one, and `shouldStop` is checked before each: a stopped run returns
+     * without recording the reconcile, so the next call redoes it in full.
+     */
+    reconcileCatalogRefs(nowMS: number, routeRules: RouteRulesInput, catalog?: ScopeCatalogRef, options?: {
+        shouldStop?: () => boolean;
+    }): Promise<void>;
+    /** Settle already queued scope work now, without reconciling any catalog of its own. */
+    settlePendingCatalogRefs(nowMS: number): Promise<void>;
+    /**
+     * Queue a recompute of every model's refs after the enclosing transaction
+     * commits. Route rules are read from the root provider when it runs; a
+     * failure keeps the existing refs and retries with the scheduler's backoff.
+     */
+    scheduleCatalogRefReconcile(): Promise<void>;
+    reconcileCatalogModelRefs(params: ReconcileCatalogModelRefsParams): Promise<void>;
+    /** Queue a scan that pins the guarded catalog's existing documents, restarting one queued. */
+    scheduleCustodyScan(catalog: ScopeCatalogRef): Promise<void>;
+    /** Scan one batch of the oldest queued custody scan. True while scans remain. */
+    advanceCustodyScan(params: {
+        nowMS: number;
+        batchSize: number;
+    }): Promise<boolean>;
+    /**
+     * Run queued custody scans, each batch in its own transaction, so a restart resumes after the
+     * last committed batch. Call outside a transaction. True once no scan remains.
+     */
+    runCustodyScans(options?: {
+        nowMS?: number;
+        batchSize?: number;
+        maxBatches?: number;
+    }): Promise<boolean>;
+    onScopeRecomputed(listener: () => Promise<void> | void): () => void;
+    advanceCatalogAging(nowMS: number, routeRules: RouteRulesInput): Promise<void>;
     queryDocuments(params: QueryDocumentsParams): Promise<QueryDocumentsResult>;
     aggregateDocuments(params: AggregateDocumentsParams): Promise<AggregateValues>;
     groupedAggregateDocuments(params: GroupedAggregateDocumentsParams): Promise<Array<GroupedAggregateValue>>;
     listDocuments(params: ListDocumentsParams): Promise<Array<DocumentNode>>;
     listDocumentModelIDs(): Promise<Array<string>>;
-    getDistinctOwnersForModel(modelID: string): Promise<Array<string>>;
     queryDocumentsByOwner(modelID: string, ownerDID: string): Promise<Array<DocumentNode>>;
     insertMutationLogEntry(entry: InsertMutationLogEntry): Promise<void>;
+    parkPushedMutation(entry: InsertMutationLogEntry & {
+        arrival_group_id: string;
+        sender_peer_did: string;
+    }): Promise<'parked' | 'duplicate' | 'full'>;
     hasMutationHash(hash: string): Promise<boolean>;
     updateMutationStatus(mutationHash: string, status: string): Promise<void>;
+    getDuePendingMutations(now: number): Promise<Array<MutationLogEntry>>;
+    getNextPendingAttemptAt(): Promise<number | null>;
+    recordPendingMutationAttempt(params: RecordPendingMutationAttemptParams): Promise<void>;
     getMutationLogForDocuments(documentIDs: Array<string>): Promise<Array<MutationLogEntry>>;
     getPendingMutations(documentID: string): Promise<Array<MutationLogEntry>>;
     /**
@@ -74,6 +402,8 @@ export type GraphStoreAPI = {
     getMaxMutationHLC(): Promise<string | null>;
     getFieldHLCs(documentID: string): Promise<Record<string, string> | null>;
     getFieldValues(documentID: string): Promise<Record<string, unknown> | null>;
+    /** `getFieldValues` for many documents in one read per model; absent documents are left out. */
+    getFieldValuesMany(documentIDs: ReadonlyArray<string>): Promise<Map<string, Record<string, unknown>>>;
     updateFieldHLCs(docID: DocumentID, fieldHLCs: Record<string, string>, fieldValues: Record<string, unknown>): Promise<void>;
     listGraphs(): Promise<Array<GraphModel>>;
     createGraph(params: CreateGraphParams): Promise<string>;
@@ -85,49 +415,9 @@ export type GraphStoreAPI = {
     getClusters(ids: Array<string>): Promise<Record<string, unknown>>;
     createSearchIndex(modelID: string, fields: Array<string>): Promise<void>;
     dropSearchIndex(modelID: string): Promise<void>;
-    updateSearchEntry(modelID: string, documentID: string, data: Record<string, unknown>, fields: Array<string>): Promise<void>;
+    updateSearchEntry(params: UpdateSearchEntryParams): Promise<void>;
     removeSearchEntry(modelID: string, documentID: string): Promise<void>;
     searchDocuments(params: SearchDocumentsParams): Promise<Array<SearchDocumentResult>>;
-    /** Create an own catalog: stored active (scopes sync) with null provenance. */
-    createCatalog(catalog: InsertCatalog): Promise<void>;
-    /**
-     * Insert a discovered catalog as known (not active) with first-discovery
-     * provenance. Idempotent on the id: an already-stored catalog is left
-     * untouched, so its local `active` flag and first-discovery source columns
-     * are never overwritten by a later re-discovery.
-     */
-    upsertDiscoveredCatalog(params: {
-        catalog: InsertCatalog;
-        sourceGroupID: string | null;
-        sourceCircleID: string | null;
-    }): Promise<void>;
-    /** Toggle a catalog's local sync activation. */
-    setCatalogActive(id: string, active: boolean): Promise<void>;
-    /** Flip several catalogs together — one statement, not one per id. */
-    setCatalogsActive(ids: Array<string>, active: boolean): Promise<void>;
-    /**
-     * All locally-stored catalog rows regardless of owner, optionally filtered by
-     * activation state. Backs the viewer's known-catalogs surface.
-     */
-    listStoredCatalogs(filter?: {
-        active?: boolean;
-    }): Promise<Array<Catalog>>;
-    getCatalog(id: string): Promise<Catalog | undefined>;
-    /**
-     * Batch fetch catalogs by ID. Returns a Map keyed by ID; missing IDs are
-     * absent from the map. Single SQL query with `WHERE id IN (...)`. Empty
-     * input short-circuits with an empty Map (no SQL).
-     *
-     * Caller is responsible for deduplicating IDs (e.g. via `Array.from(new Set(...))`).
-     */
-    getCatalogs(ids: Array<string>): Promise<Map<string, Catalog>>;
-    updateCatalog(id: string, update: Partial<Pick<InsertCatalog, 'name' | 'description' | 'filter_criteria' | 'hlc' | 'signed_token'>>): Promise<void>;
-    deleteCatalog(id: string): Promise<void>;
-    listCatalogs(ownerDID: string): Promise<Array<Catalog>>;
-    resolveCatalogScope(catalogID: string): Promise<{
-        models: Array<string> | undefined;
-        owners: Array<string> | undefined;
-    }>;
     registerClusterModels(clusterID: string, entries: Array<InsertClusterModel>): Promise<void>;
     /** A tombstoned (removed) rule reads as absent. */
     getUserModelAccessDefault(ownerDID: string, modelID: string, permissionType: 'read' | 'write'): Promise<StoredAccessRule | null>;
@@ -162,20 +452,89 @@ export type GraphStoreAPI = {
      * (not deleted) so a stale set arriving after the removal is rejected by HLC.
      * A type with no existing row is skipped (nothing to tombstone).
      */
-    removeUserModelAccessDefaults(ownerDID: string, modelID: string, permissionTypes: Array<string>, hlc: string): Promise<void>;
+    removeUserModelAccessDefaults(params: RemoveUserModelAccessDefaultsParams): Promise<void>;
+    hasControllerAccessDefaults(ownerDID: string, modelID?: string): Promise<boolean>;
+    invalidateAccessDefaultProjections(ownerDID?: string): Promise<void>;
     /**
      * Document IDs across every scope, one query per distinct model. Repeating a
      * (model, owner) pair yields its documents once — the result is a set, and the
      * caller builds a Merkle tree from it, where a duplicate would be a defect.
      */
-    getDocumentIDsForScope(scopes: Array<{
-        modelID: string;
-        ownerDID: string;
-    }>, excludedDocumentIDs?: Array<string>): Promise<Array<string>>;
+    /** Read at most this many IDs in total; a caller passes its cap plus one. */
+    getDocumentIDsForScope(params: GetDocumentIDsForScopeParams): Promise<Array<string>>;
     getDocumentMetadataForSync(modelID: string, documentIDs: Array<string>): Promise<Array<{
         id: string;
         model: string;
         owner: string;
     }>>;
+    /**
+     * One keyset page of stored documents matching any rule, in bytewise
+     * document-ID order, each with the sorted IDs of its applied mutations.
+     * Pending and rejected mutations are not included. One statement per model
+     * reads membership and mutation IDs together, and the per-model pages are
+     * merged; no statement binds a list of document IDs.
+     */
+    listDocumentLeafPage(params: DocumentLeafPageParams): Promise<Array<DocumentLeafRow>>;
+    /** A document's applied mutation log entries, in HLC order. */
+    getAppliedMutations(documentID: string): Promise<Array<MutationLogEntry>>;
+    /**
+     * Each document's applied mutation log entries, in HLC order, keyed by document ID. A
+     * document with none is absent.
+     */
+    getAppliedMutationsForDocuments(documentIDs: Iterable<string>): Promise<Map<string, Array<MutationLogEntry>>>;
 };
-export declare function createGraphStore(db: Kysely<GraphTables>, adapter: Adapter): GraphStoreAPI;
+/**
+ * Resolves once the root's scope scheduler has no timer armed, no recompute running and nothing
+ * queued. While recomputes keep failing it keeps retrying, so this does not resolve.
+ */
+export declare function scopeSchedulerIdle(root: StoreProvider): Promise<void>;
+/** The sticky ref a custodian pins a document with: the catalog ID part holds no `:`. */
+export declare function custodyPinRef(guard: CustodyGuard): string;
+export declare function isCustodyPinRef(ref: string): boolean;
+export declare function catalogRuleRef(catalog: ScopeCatalogRef, ruleID: string): string;
+/**
+ * Whether a ref is one of the catalog's rule refs. Catalog IDs may contain `:`, so a prefix
+ * alone would also claim the refs of a catalog whose ID extends this one.
+ */
+export declare function isCatalogRuleRef(ref: string, catalog: ScopeCatalogRef): boolean;
+/** A document holding a ref that may be one of a catalog's rule refs. */
+export type CatalogRefHolder = {
+    document_id: string;
+    ref: string;
+};
+/**
+ * The refs that start with a catalog's rule-ref prefix: a bytewise range rather
+ * than LIKE, whose wildcards and escape character catalog IDs may contain.
+ * On a Postgres adapter it compares `ref collate "C"`, which the ref index is
+ * built on. The caller keeps only the catalog's own refs with
+ * `isCatalogRuleRef`. Exported so the plan of the exact statement can be
+ * checked.
+ */
+export declare function catalogRefHoldersQuery(db: Kysely<GraphTables>, adapter: Adapter, catalog: ScopeCatalogRef): import("kysely").SelectQueryBuilder<GraphTables, "kubun_graph_document_refs", {
+    document_id: string;
+    ref: string;
+}>;
+/** One row of a document-leaf page: a document and one applied mutation of it, if any. */
+type LeafPageSQLRow = {
+    id: string;
+    owner: string;
+    authored_here: unknown;
+    mutation_hash: string | null;
+};
+/**
+ * The statement one model's keyset leaf page runs: matching documents after
+ * `after` (and up to `through`) in bytewise ID order, at most `limit`, each with
+ * whether it was created here and joined to its applied mutations. Exported so
+ * the plan of the exact statement can be checked.
+ */
+export declare function documentLeafPageStatement(params: {
+    modelID: string;
+    rules: ReadonlyArray<DocumentLeafRule>;
+    after: string | null;
+    through: string | null;
+    limit: number;
+    postgres: boolean;
+    groupReadPredicate?: RawBuilder<boolean>;
+}): RawBuilder<LeafPageSQLRow>;
+export declare function createGraphStore(db: Kysely<GraphTables>, adapter: Adapter, context?: StoreAPIContext): GraphStoreAPI;
+export {};