@kubun/store-graph 0.17.0 → 0.18.0

package/lib/api.js

@@ -1,6 +1,17 @@
-import { DocumentID, DocumentModelID } from '@kubun/id';
+import { AbstractPostgresAdapter, chunked, IN_LIST_CHUNK } from '@kubun/db-adapter';
+import { CatalogID, DocumentID, DocumentModelID } from '@kubun/id';
+import { winnerStateDigestOf } from '@kubun/mutation';
+import { isDocumentDateField } from '@kubun/protocol';
+import { blake3 } from '@noble/hashes/blake3.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { sql } from 'kysely';
+import { createGraphAccessDefaultRecordMethods } from './access-default-records.js';
+import { createGraphCatalogRecordMethods } from './catalog-records.js';
+import { parseScopeDate, parseScopeDuration, scopeRuleMatches, scopeRuleMatchesFacts, validateScopeCatalog } from './catalog-scope.js';
+import { createCatalogStateMethods } from './catalog-state.js';
 import { serializeCursor } from './cursor.js';
-import { isMissingTableError, ModelNotDeployedError } from './errors.js';
+import { DocumentLockRequiresTransactionError, DocumentNotHoldableError, InvalidModelDateFieldError, isMissingTableError, MissingGraphCommitContextError, ModelNotDeployedError } from './errors.js';
+import { boundedIdentifier } from './identifiers.js';
 import { aggregateFieldName, applyAggregateSelections, applyDocumentFilter, applyDocumentOrderBy, applyGroupBySelections, applyPagination, groupKeyAlias, knownFieldColumn } from './query-builder.js';
 import { resolveSearchableFields, SearchNotEnabledError } from './search.js';
 // --- Helper functions ---
@@ -254,21 +265,23 @@ function compareGroups(a, b, orderBy) {
     }
     return 0;
 }
-function documentModelFromTable(row) {
+export function documentModelFromTable(row) {
     const model = {
         version: row.version,
         name: row.name,
         behavior: row.behavior,
         interfaces: row.interfaces,
         schema: row.schema,
-        fieldsMeta: row.fields_meta
+        fieldsMeta: row.fields_meta,
+        providerMergePolicy: row.provider_merge_policy ?? undefined,
+        dateField: row.date_field ?? undefined
     };
     if (model.behavior === 'unique') {
         model.uniqueFields = row.unique_fields;
     }
     return model;
 }
-function documentModelToTable(adapter, id, model) {
+export function documentModelToTable(adapter, id, model) {
     return {
         id,
         version: model.version,
@@ -277,7 +290,10 @@ function documentModelToTable(adapter, id, model) {
         unique_fields: model.behavior === 'unique' ? adapter.encodeJSON(model.uniqueFields) : null,
         interfaces: adapter.encodeJSON(model.interfaces),
         schema: adapter.encodeJSON(model.schema),
-        fields_meta: adapter.encodeJSON(model.fieldsMeta)
+        fields_meta: adapter.encodeJSON(model.fieldsMeta),
+        provider_merge_policy: model.providerMergePolicy ? adapter.encodeJSON(model.providerMergePolicy) : null,
+        date_field: model.dateField ?? null,
+        resolved_date_field: model.dateField ?? null
     };
 }
 function documentNodeFromTable(adapter, doc) {
@@ -286,8 +302,9 @@ function documentNodeFromTable(adapter, doc) {
         model: doc.model,
         owner: doc.owner,
         data: doc.data,
-        createdAt: adapter.decodeTimestamp(doc.created_at),
-        updatedAt: doc.updated_at ? adapter.decodeTimestamp(doc.updated_at) : null
+        createdAt: doc.mutation_created_at == null ? adapter.decodeTimestamp(doc.created_at) : new Date(Number(doc.mutation_created_at)),
+        updatedAt: doc.mutation_updated_at == null ? doc.updated_at ? adapter.decodeTimestamp(doc.updated_at) : null : new Date(Number(doc.mutation_updated_at)),
+        scopeDate: doc.scope_date == null ? undefined : Number(doc.scope_date)
     };
 }
 function toGlobalInterfaceID(modelID, interfaceID) {
@@ -307,10 +324,31 @@ function extractFieldValue(data, fieldPath) {
 async function addDocumentModel(transaction, adapter, params) {
     const { id, graphModelID, model } = params;
     const t = adapter.types;
-    await transaction.schema.createTable(`k_${id}`).ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('owner', t.text, (col)=>col.notNull()).addColumn('model', t.text, (col)=>col.notNull()).addColumn('data', t.json).addColumn('field_hlcs', t.json).addColumn('field_values', t.json).addColumn('unique', t.binary, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>{
+    const inheritedRows = model.interfaces.length === 0 ? [] : await transaction.selectFrom('kubun_graph_document_models').select('resolved_date_field').where('id', 'in', model.interfaces.map((interfaceID)=>toGlobalInterfaceID(id, interfaceID))).execute();
+    const inheritedFields = new Set(inheritedRows.map((row)=>row.resolved_date_field).filter((field)=>field != null));
+    if (model.dateField == null && inheritedFields.size > 1) {
+        throw new InvalidModelDateFieldError('Conflicting inherited date fields');
+    }
+    const resolvedDateField = model.dateField ?? inheritedFields.values().next().value ?? null;
+    if (resolvedDateField != null) {
+        if (!isDocumentDateField(model, resolvedDateField)) {
+            throw new InvalidModelDateFieldError(`Invalid model date field: ${resolvedDateField}`);
+        }
+    }
+    await transaction.schema.createTable(`k_${id}`).ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('owner', t.text, (col)=>col.notNull()).addColumn('model', t.text, (col)=>col.notNull()).addColumn('data', t.json).addColumn('field_hlcs', t.json).addColumn('field_values', t.json).addColumn('unique', t.binary, (col)=>col.notNull()).addColumn('mutation_created_at', t.bigint).addColumn('mutation_updated_at', t.bigint).addColumn('scope_date', t.bigint).addColumn('created_at', t.timestamp, (col)=>{
         return col.defaultTo(adapter.functions.now).notNull();
     }).addColumn('updated_at', t.timestamp).execute();
-    await transaction.insertInto('kubun_graph_document_models').values(documentModelToTable(adapter, id, model)).onConflict((oc)=>oc.doNothing()).execute();
+    await transaction.schema.createIndex(boundedIdentifier(`idx_scope_date_${id}`)).ifNotExists().on(`k_${id}`).column('scope_date').execute();
+    // Document-sync pages walk ids in byte order. SQLite text compares bytewise
+    // already; a Postgres database with a linguistic collation needs an index in
+    // the "C" collation for those pages to seek instead of sort.
+    if (adapter instanceof AbstractPostgresAdapter) {
+        await transaction.schema.createIndex(boundedIdentifier(`idx_id_bytes_${id}`)).ifNotExists().on(`k_${id}`).expression(sql`id collate "C"`).execute();
+    }
+    await transaction.insertInto('kubun_graph_document_models').values({
+        ...documentModelToTable(adapter, id, model),
+        resolved_date_field: resolvedDateField
+    }).onConflict((oc)=>oc.doNothing()).execute();
     for (const interfaceID of model.interfaces){
         await transaction.insertInto('kubun_graph_document_model_interfaces').values({
             interface_id: toGlobalInterfaceID(id, interfaceID),
@@ -322,27 +360,343 @@ async function addDocumentModel(transaction, adapter, params) {
         document_model_id: id
     }).onConflict((oc)=>oc.doNothing()).execute();
 }
-// --- Factory function ---
-export function createGraphStore(db, adapter) {
-    const coerce = adapter.coerceFilterValue.bind(adapter);
-    async function resolveCatalogFilter(modelIDs, catalogID) {
-        if (catalogID == null) {
-            return {
-                effectiveModelIDs: modelIDs,
-                effectiveOwners: undefined
-            };
-        }
-        const { models, owners } = await api.resolveCatalogScope(catalogID);
-        let effectiveModelIDs = modelIDs;
-        if (models != null) {
-            const catalogModelSet = new Set(models);
-            effectiveModelIDs = effectiveModelIDs.filter((id)=>catalogModelSet.has(id));
+// --- Transaction-scoped merge-policy winner read ---
+/**
+ * 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 async function readWinnerStateDigest(tx, documentID) {
+    const modelID = DocumentID.fromString(documentID).model.toString();
+    const row = await tx.selectFrom(`k_${modelID}`).select('field_values').where('id', '=', documentID).executeTakeFirst();
+    if (row?.field_values == null) {
+        return null;
+    }
+    // ParseJSONResultsPlugin may have already parsed the value.
+    const fieldValues = typeof row.field_values === 'string' ? JSON.parse(row.field_values) : row.field_values;
+    return winnerStateDigestOf(fieldValues);
+}
+/**
+ * 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 async function readWinnerStateDigests(params) {
+    const byModel = new Map();
+    for (const documentID of params.documentIDs){
+        let modelID;
+        try {
+            modelID = DocumentID.fromString(documentID).model.toString();
+        } catch  {
+            continue;
         }
-        return {
-            effectiveModelIDs,
-            effectiveOwners: owners
-        };
+        const ids = byModel.get(modelID);
+        if (ids === undefined) byModel.set(modelID, [
+            documentID
+        ]);
+        else ids.push(documentID);
+    }
+    const digests = new Map();
+    for (const [modelID, ids] of byModel){
+        try {
+            for (const chunk of chunked(ids)){
+                const rows = await params.tx.selectFrom(`k_${modelID}`).select([
+                    'id',
+                    'field_values'
+                ]).where('id', 'in', chunk).execute();
+                for (const row of rows){
+                    if (row.field_values == null) continue;
+                    // ParseJSONResultsPlugin may have already parsed the value.
+                    const fieldValues = typeof row.field_values === 'string' ? JSON.parse(row.field_values) : row.field_values;
+                    const digest = winnerStateDigestOf(fieldValues);
+                    if (digest != null) digests.set(String(row.id), digest);
+                }
+            }
+        } catch  {}
+    }
+    return digests;
+}
+/** Whether a mark has waited out the grace: the sweep's own test, shared so a listing agrees. */ export function gcMarkPastGrace(mark, graceMS, nowMS) {
+    return mark.markedAt + graceMS <= nowMS;
+}
+/** Hex blake3 over mutation IDs, sorted and joined by newline: the document mutation digest. */ export function mutationIDsDigest(mutationIDs) {
+    const sorted = [
+        ...mutationIDs
+    ].sort();
+    return bytesToHex(blake3(new TextEncoder().encode(sorted.join('\n'))));
+}
+const scopeSchedulers = new WeakMap();
+const allDocumentRefsLockKey = 'graph.document.refs:*';
+// Transactions, by their Kysely handle, that hold the all-documents ref lock exclusively.
+const exclusiveRefLockHolders = new WeakSet();
+function getScopeScheduler(context) {
+    let state = scopeSchedulers.get(context.root);
+    if (state != null) return state;
+    state = {
+        pendingScopes: new Map(),
+        timer: null,
+        running: null,
+        failed: false,
+        retryDelayMS: 100,
+        generation: 0,
+        closed: false,
+        listeners: new Set()
+    };
+    scopeSchedulers.set(context.root, state);
+    context.onClose?.(async ()=>{
+        if (state == null) return;
+        state.closed = true;
+        state.generation++;
+        if (state.timer != null) clearTimeout(state.timer);
+        state.timer = null;
+        state.pendingScopes.clear();
+        await state.running;
+        state.listeners.clear();
+    });
+    return state;
+}
+/**
+ * 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 async function scopeSchedulerIdle(root) {
+    const state = scopeSchedulers.get(root);
+    if (state == null) return;
+    while(!state.closed && (state.timer != null || state.running != null || state.pendingScopes.size > 0)){
+        if (state.running != null) await state.running;
+        else await new Promise((resolve)=>setTimeout(resolve, 1));
+    }
+}
+function requeueScopeTasks(state, tasks) {
+    for (const task of tasks){
+        const key = JSON.stringify([
+            task.modelID,
+            task.catalog?.owner,
+            task.catalog?.id
+        ]);
+        const previous = state.pendingScopes.get(key);
+        state.pendingScopes.set(key, {
+            ...task,
+            owners: previous == null ? task.owners : previous.owners == null || task.owners == null ? undefined : [
+                ...new Set([
+                    ...previous.owners,
+                    ...task.owners
+                ])
+            ]
+        });
+    }
+}
+// A scope change written outside the scheduler's recomputes, such as a sweep, still reaches
+// whoever emits scope events.
+function notifyScopeListeners(context) {
+    const state = getScopeScheduler(context);
+    if (state.closed) return;
+    for (const listener of state.listeners){
+        void Promise.resolve().then(listener).catch((error)=>console.error('catalog scope listener failed', error));
+    }
+}
+function armScopeScheduler(context, state, delayMS = 10) {
+    if (state.closed || state.timer != null || state.running || state.pendingScopes.size === 0) return;
+    const generation = state.generation;
+    state.timer = setTimeout(()=>{
+        if (generation !== state.generation) return;
+        state.timer = null;
+        const pending = Array.from(state.pendingScopes.values());
+        state.pendingScopes.clear();
+        state.running = (async ()=>{
+            try {
+                const store = await context.root.getStore('graph');
+                for(let index = 0; index < pending.length; index++){
+                    if (generation !== state.generation) break;
+                    const task = pending[index];
+                    if (task == null) continue;
+                    try {
+                        const nowMS = Date.now();
+                        const routeRules = await context.getRootCatalogRouteRules(nowMS, task.catalog);
+                        await store.reconcileCatalogModelRefs({
+                            modelID: task.modelID,
+                            routeRules,
+                            nowMS,
+                            owners: task.owners,
+                            catalog: task.catalog
+                        });
+                    } catch (error) {
+                        requeueScopeTasks(state, pending.slice(index));
+                        throw error;
+                    }
+                }
+                state.failed = false;
+                state.retryDelayMS = 100;
+                return generation === state.generation ? [
+                    ...state.listeners
+                ] : [];
+            } catch (error) {
+                if (state.pendingScopes.size === 0) requeueScopeTasks(state, pending);
+                state.failed = true;
+                console.error('catalog scope recomputation failed', error);
+                return [];
+            } finally{
+                state.running = null;
+                if (state.failed) {
+                    const delay = state.retryDelayMS;
+                    state.retryDelayMS = Math.min(delay * 2, 30_000);
+                    armScopeScheduler(context, state, delay);
+                } else armScopeScheduler(context, state);
+            }
+        })().then((listeners)=>{
+            for (const listener of listeners){
+                void Promise.resolve().then(listener).catch((error)=>console.error('catalog scope listener failed', error));
+            }
+        });
+    }, delayMS);
+}
+const catalogRulePrefix = 'rule:';
+function catalogRefPrefix(catalog) {
+    return `${catalogRulePrefix}${catalog.owner}:${catalog.id}:`;
+}
+const custodyPinRefPrefix = 'hold:custody:';
+/** The sticky ref a custodian pins a document with: the catalog ID part holds no `:`. */ export function custodyPinRef(guard) {
+    const catalogID = new CatalogID(guard.catalog.owner, guard.catalog.id).toString();
+    return `${custodyPinRefPrefix}${guard.custodyOwner}:${catalogID}`;
+}
+export function isCustodyPinRef(ref) {
+    return ref.startsWith(custodyPinRefPrefix);
+}
+export function catalogRuleRef(catalog, ruleID) {
+    return `${catalogRefPrefix(catalog)}${ruleID}`;
+}
+/**
+ * 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 function isCatalogRuleRef(ref, catalog) {
+    const prefix = catalogRefPrefix(catalog);
+    return ref.startsWith(prefix) && /^[^:]+$/.test(ref.slice(prefix.length));
+}
+const SWEPT_PAGE = 500;
+const catalogLevelBits = {
+    KNOWN: {
+        displays: 1,
+        retains: 0
+    },
+    OFFLINE: {
+        displays: 1,
+        retains: 1
+    },
+    SERVE_ONLY: {
+        displays: 0,
+        retains: 1
     }
+};
+function catalogUseFromRow(row) {
+    return {
+        level: row.level ?? null,
+        followed: Number(row.followed) === 1
+    };
+}
+function scheduleScopeTasks(context, tasks) {
+    const state = getScopeScheduler(context);
+    const pending = Array.from(tasks);
+    if (pending.length === 0) return;
+    context.provider.onCommit(()=>{
+        if (state.closed) return;
+        requeueScopeTasks(state, pending);
+        if (state.timer != null) {
+            clearTimeout(state.timer);
+            state.timer = null;
+        }
+        armScopeScheduler(context, state, state.failed ? state.retryDelayMS : undefined);
+    });
+}
+function scheduleScopeModels(context, modelIDs) {
+    scheduleScopeTasks(context, Array.from(modelIDs, (modelID)=>({
+            modelID
+        })));
+}
+/**
+ * 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 function catalogRefHoldersQuery(db, adapter, catalog) {
+    const prefix = catalogRefPrefix(catalog);
+    const ref = adapter instanceof AbstractPostgresAdapter ? sql`ref collate "C"` : sql`ref`;
+    return db.selectFrom('kubun_graph_document_refs').select([
+        'document_id',
+        'ref'
+    ]).where(ref, '>=', prefix).where(ref, '<', `${prefix}\u{10FFFF}`);
+}
+/**
+ * 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 function documentLeafPageStatement(params) {
+    const { postgres } = params;
+    // Bytewise order on every adapter: SQLite compares text with BINARY,
+    // Postgres needs the "C" collation to agree with it.
+    const key = postgres ? sql`k.id collate "C"` : sql`k.id`;
+    const matches = params.rules.map((rule)=>{
+        const conditions = [];
+        if (rule.owners != null) {
+            conditions.push(rule.owners.length === 0 ? sql`1 = 0` : sql`k.owner in (${sql.join([
+                ...rule.owners
+            ])})`);
+        }
+        if (rule.dateField != null && (rule.from != null || rule.to != null)) {
+            const bounds = [
+                sql`sd.field = ${rule.dateField}`
+            ];
+            if (rule.from != null) bounds.push(sql`sd.scope_date >= ${rule.from}`);
+            if (rule.to != null) bounds.push(sql`sd.scope_date < ${rule.to}`);
+            conditions.push(sql`exists (select 1 from kubun_graph_document_scope_dates as sd where sd.document_id = k.id and ${sql.join(bounds, sql` and `)})`);
+        } else if (rule.from != null || rule.to != null) {
+            // A model without a declared date field windows on its scope date,
+            // which is the document's creation time.
+            if (rule.from != null) conditions.push(sql`k.scope_date >= ${rule.from}`);
+            if (rule.to != null) conditions.push(sql`k.scope_date < ${rule.to}`);
+        }
+        return conditions.length === 0 ? sql`1 = 1` : sql`(${sql.join(conditions, sql` and `)})`;
+    });
+    const range = [
+        sql`(${sql.join(matches, sql` or `)})`
+    ];
+    if (params.groupReadPredicate != null) range.push(params.groupReadPredicate);
+    if (params.after != null) range.push(sql`${key} > ${params.after}`);
+    if (params.through != null) range.push(sql`${key} <= ${params.through}`);
+    const outerKey = postgres ? sql`d.id collate "C"` : sql`d.id`;
+    // SQLite would otherwise pick the status index, which holds nearly every
+    // row: the unary plus keeps the join on the document index.
+    const applied = postgres ? sql`m.status = 'applied'` : sql`+m.status = 'applied'`;
+    return sql`
+    select d.id, d.owner, d.authored_here, m.mutation_hash
+    from (
+      select k.id, k.owner, exists (
+        select 1 from kubun_graph_document_refs as r
+        where r.document_id = k.id and r.ref = 'local'
+      ) as authored_here
+      from ${sql.table(`k_${params.modelID}`)} as k
+      where ${sql.join(range, sql` and `)}
+      order by ${key}
+      limit ${params.limit}
+    ) as d
+    left join kubun_graph_mutation_log as m
+      on m.document_id = d.id and ${applied}
+    order by ${outerKey}`;
+}
+// A custody pin, or a ref a SERVE_ONLY catalog could have written: retained, not displayed.
+function mayNeedBytes(row) {
+    return isCustodyPinRef(row.ref) || row.ref.startsWith(catalogRulePrefix) && Number(row.displays) === 0 && Number(row.retains) === 1;
+}
+export function createGraphStore(db, adapter, context) {
+    if (context == null) throw new MissingGraphCommitContextError();
+    const coerce = adapter.coerceFilterValue.bind(adapter);
     // --- Write-path search index maintenance ---
     //
     // Runs inline in the caller's write transaction (`db` here IS that
@@ -368,7 +722,703 @@ export function createGraphStore(db, adapter) {
         if (fields == null) return;
         await adapter.removeSearchEntry(db, model, documentID);
     }
+    async function refreshDocumentDates(documentID) {
+        const modelID = DocumentID.fromString(documentID).model.toString();
+        const row = await db.selectFrom(`k_${modelID}`).selectAll().where('id', '=', documentID).executeTakeFirst();
+        if (row == null) return;
+        const extrema = await db.selectFrom('kubun_graph_mutation_log').select('hlc').where('document_id', '=', documentID).where('status', '=', 'applied').orderBy('hlc').execute();
+        const createdAt = extrema[0] == null ? adapter.decodeTimestamp(row.created_at).getTime() : Date.parse(extrema[0].hlc.slice(0, 24));
+        const lastMutation = extrema.at(-1);
+        const updatedAt = lastMutation == null ? null : Date.parse(lastMutation.hlc.slice(0, 24));
+        const model = await db.selectFrom('kubun_graph_document_models').select([
+            'resolved_date_field',
+            'schema'
+        ]).where('id', '=', modelID).executeTakeFirstOrThrow();
+        const data = row.data;
+        const selectedValue = model.resolved_date_field == null || data == null ? null : extractFieldValue(data, model.resolved_date_field);
+        const scopeDate = parseScopeDate(selectedValue) ?? createdAt;
+        await db.updateTable(`k_${modelID}`).set({
+            mutation_created_at: extrema[0] == null ? null : createdAt,
+            mutation_updated_at: updatedAt,
+            scope_date: scopeDate
+        }).where('id', '=', documentID).execute();
+        await db.deleteFrom('kubun_graph_document_scope_dates').where('document_id', '=', documentID).execute();
+        const dates = Object.keys(model.schema.properties).filter((field)=>isDocumentDateField(model, field)).map((field)=>({
+                document_id: documentID,
+                field,
+                scope_date: parseScopeDate(data == null ? null : extractFieldValue(data, field)) ?? createdAt
+            }));
+        if (dates.length > 0) await db.insertInto('kubun_graph_document_scope_dates').values(dates).execute();
+    }
+    // Same size as a custody scan batch: a batch is one transaction holding the connection.
+    const ReconcileBatch = 100;
+    const reconcileAll = async (nowMS, routeRules, shouldStop)=>{
+        const models = await db.selectFrom('kubun_graph_document_models').select('id').execute();
+        const documentIDs = [];
+        for (const model of models){
+            const docs = await db.selectFrom(`k_${model.id}`).select('id').execute();
+            for (const doc of docs)documentIDs.push(doc.id);
+        }
+        documentIDs.sort();
+        if (context.provider !== context.root) {
+            // The caller's transaction spans the whole pass, so there is no connection to release.
+            if (shouldStop()) return false;
+            await lockAllDocumentRefs();
+            await recomputeDocumentRefsBatch({
+                documentIDs,
+                routeRules,
+                nowMS
+            });
+            await api.refreshSweptDocuments({
+                nowMS
+            });
+            return true;
+        }
+        for(let i = 0; i < documentIDs.length; i += ReconcileBatch){
+            if (shouldStop()) return false;
+            await api.recomputeDocuments({
+                documentIDs: documentIDs.slice(i, i + ReconcileBatch),
+                routeRules,
+                nowMS
+            });
+        }
+        if (shouldStop()) return false;
+        await api.refreshSweptDocuments({
+            nowMS
+        });
+        return true;
+    };
+    async function tasksForCatalog(ref, rules) {
+        const selected = new Map();
+        let modelsQuery = db.selectFrom('kubun_graph_document_models').select('id');
+        if (!rules.some((rule)=>rule.models == null)) {
+            const modelIDs = [
+                ...new Set(rules.flatMap((rule)=>rule.models ?? []))
+            ];
+            if (modelIDs.length === 0) modelsQuery = modelsQuery.where(sql`1 = 0`);
+            else modelsQuery = modelsQuery.where((eb)=>eb.or([
+                    eb('id', 'in', modelIDs),
+                    eb('id', 'in', eb.selectFrom('kubun_graph_document_model_interfaces').select('implementation_id').where('interface_id', 'in', modelIDs))
+                ]));
+        }
+        const models = await modelsQuery.execute();
+        const interfacesOf = memoisedInterfaces();
+        for (const model of models){
+            const interfaces = await interfacesOf(model.id);
+            for (const rule of rules){
+                if (rule.models != null && !rule.models.some((id)=>id === model.id || interfaces.includes(id))) continue;
+                const previous = selected.get(model.id);
+                if (rule.owners == null || previous === null) {
+                    selected.set(model.id, null);
+                } else {
+                    const owners = previous ?? new Set();
+                    for (const owner of rule.owners)owners.add(owner);
+                    selected.set(model.id, owners);
+                }
+            }
+        }
+        for (const row of (await catalogRefHolders(ref))){
+            const modelID = DocumentID.fromString(row.document_id).model.toString();
+            if (!selected.has(modelID)) selected.set(modelID, new Set());
+        }
+        return Array.from(selected, ([modelID, owners])=>({
+                modelID,
+                owners: owners == null ? undefined : Array.from(owners),
+                catalog: ref
+            }));
+    }
+    async function catalogRefHolders(catalog) {
+        const rows = await catalogRefHoldersQuery(db, adapter, catalog).execute();
+        return rows.filter((row)=>isCatalogRuleRef(row.ref, catalog));
+    }
+    function visibleScopePredicate(modelID, refs) {
+        const refCondition = refs == null ? sql`` : sql`and scope_ref.ref in (${sql.join(refs)})`;
+        return sql`exists (
+      select 1 from kubun_graph_document_refs as scope_ref
+      where scope_ref.document_id = ${sql.ref(`k_${modelID}.id`)}
+        and scope_ref.displays = 1 ${refCondition}
+    )`;
+    }
+    /**
+   * Settle scope work queued before a synchronous mutation, skipping the catalog the mutation
+   * reconciles itself. Entries leave the queue only when the transaction commits.
+   */ const settlePendingScopes = async (nowMS, except)=>{
+        const scheduler = scopeSchedulers.get(context.root);
+        for (const [key, task] of scheduler?.pendingScopes ?? []){
+            if (except == null || task.catalog?.owner !== except.owner || task.catalog.id !== except.id) {
+                const pendingRules = await context.getCatalogRouteRules(nowMS, task.catalog);
+                await api.reconcileCatalogModelRefs({
+                    modelID: task.modelID,
+                    routeRules: pendingRules,
+                    nowMS,
+                    owners: task.owners,
+                    catalog: task.catalog
+                });
+            }
+            context.provider.onCommit(()=>{
+                if (scheduler?.pendingScopes.get(key) === task) scheduler.pendingScopes.delete(key);
+            });
+        }
+    };
+    async function visibleCatalogRefs(ref) {
+        const catalog = await db.selectFrom('kubun_graph_catalog_use').select([
+            'rules',
+            'level'
+        ]).where('owner_did', '=', ref.owner).where('catalog_id', '=', ref.id).executeTakeFirst();
+        if (catalog?.level == null || catalogLevelBits[catalog.level].displays !== 1) return [];
+        const rules = typeof catalog.rules === 'string' ? JSON.parse(catalog.rules) : catalog.rules;
+        return rules.map((rule)=>catalogRuleRef(ref, rule.id));
+    }
+    function custodyReceiptFromRow(row) {
+        return {
+            documentID: row.document_id,
+            custodian: row.custodian,
+            groupID: row.group_id,
+            custodyOwner: row.custody_owner,
+            catalog: {
+                owner: row.catalog_owner,
+                id: row.catalog_id
+            },
+            assignmentDigest: row.assignment_digest,
+            headDigest: row.head_digest,
+            mutationDigest: row.mutation_digest,
+            receivedAt: Number(row.received_at)
+        };
+    }
+    function gcMarkFromRow(row) {
+        return {
+            documentID: row.document_id,
+            digest: row.digest,
+            markedAt: Number(row.marked_at)
+        };
+    }
+    function holdFromRow(row) {
+        return {
+            id: row.hold_id,
+            documentID: row.document_id,
+            createdBy: row.created_by,
+            reason: row.reason,
+            expiresAt: row.expires_at == null ? null : Number(row.expires_at)
+        };
+    }
+    const readScopeReader = async ()=>await db.selectFrom('kubun_graph_scope_identity').select([
+            'reader_did',
+            'default_read_level'
+        ]).where('id', '=', 1).executeTakeFirst();
+    // Whether the scope reader may read a document of this owner and model with this read rule;
+    // true with no reader, or when the reader owns it.
+    const scopeReaderMayRead = async (owner, model, override)=>await readerMayRead(await readScopeReader(), owner, model, override);
+    // One pass's read checks: nothing a ref recompute or swept refresh writes changes an answer.
+    const memoisedReadCheck = ()=>{
+        let reader;
+        const answers = new Map();
+        return async (owner, model, override)=>{
+            const key = JSON.stringify([
+                owner,
+                model,
+                override
+            ]);
+            let answer = answers.get(key);
+            if (answer == null) {
+                reader ??= readScopeReader();
+                answer = reader.then((row)=>readerMayRead(row, owner, model, override));
+                answers.set(key, answer);
+            }
+            return await answer;
+        };
+    };
+    // One pass's model interfaces, from one read on first use.
+    const memoisedInterfaces = ()=>{
+        let all;
+        return async (modelID)=>{
+            all ??= api.listModelInterfaces();
+            return (await all).get(modelID) ?? [];
+        };
+    };
+    const readerMayRead = async (reader, owner, model, override)=>{
+        if (reader == null || reader.reader_did === owner) return true;
+        const grant = override == null ? await api.getUserModelAccessDefault(owner, model, 'read') : null;
+        const access = override ?? grant;
+        const membership = context.provider.hasStore('p2p') ? await context.provider.getStore('p2p') : undefined;
+        return access == null ? !await api.hasControllerAccessDefaults(owner) && reader.default_read_level === 'anyone' : access.level === 'anyone' || access.level === 'restricted' && (access.allowedDIDs?.includes(reader.reader_did) === true || membership != null && (await membership.isMemberOfAnyCircle(reader.reader_did, access.allowedCircles ?? []) || await membership.isMemberOfAnyGroup(reader.reader_did, access.allowedGroups ?? [])));
+    };
+    function sweptFromRow(row) {
+        const parse = (value)=>typeof value === 'string' ? JSON.parse(value) : value;
+        return {
+            documentID: row.document_id,
+            modelID: row.model_id,
+            owner: row.owner,
+            createdAt: Number(row.created_at),
+            scopeDate: row.scope_date == null ? null : Number(row.scope_date),
+            fieldDates: parse(row.field_dates),
+            readAccess: row.read_access == null ? null : parse(row.read_access),
+            mutationDigest: row.mutation_digest,
+            sweptAt: Number(row.swept_at)
+        };
+    }
+    // Catalogs at a retaining level, and the pull route rules, as a ref recompute reads them.
+    const retainingRules = async (nowMS)=>{
+        const uses = [];
+        for (const use of (await db.selectFrom('kubun_graph_catalog_use').selectAll().execute())){
+            if (use.level == null || catalogLevelBits[use.level].retains !== 1) continue;
+            uses.push({
+                catalog: {
+                    owner: use.owner_did,
+                    id: use.catalog_id
+                },
+                rules: typeof use.rules === 'string' ? JSON.parse(use.rules) : use.rules
+            });
+        }
+        return {
+            uses,
+            routeRules: await context.getCatalogRouteRules(nowMS)
+        };
+    };
+    // Every rule of each catalog, whatever its level, keyed by `JSON.stringify([owner, id])`.
+    const catalogRulesByRef = async (catalogs)=>{
+        const byKey = new Map();
+        for (const catalog of catalogs)byKey.set(JSON.stringify([
+            catalog.owner,
+            catalog.id
+        ]), catalog);
+        const found = new Map();
+        // Two bound parameters per catalog.
+        for (const chunk of chunked(byKey.values(), IN_LIST_CHUNK / 2)){
+            const rows = await db.selectFrom('kubun_graph_catalog_use').select([
+                'owner_did',
+                'catalog_id',
+                'rules'
+            ]).where((eb)=>eb.or(chunk.map((catalog)=>eb.and([
+                        eb('owner_did', '=', catalog.owner),
+                        eb('catalog_id', '=', catalog.id)
+                    ])))).execute();
+            for (const row of rows){
+                found.set(JSON.stringify([
+                    row.owner_did,
+                    row.catalog_id
+                ]), typeof row.rules === 'string' ? JSON.parse(row.rules) : row.rules);
+            }
+        }
+        return found;
+    };
+    /**
+   * The catalogs whose rules would retain the swept document were it here: the same catalog
+   * levels, route rules and read check a ref recompute applies, over the facts kept at sweep.
+   */ async function sweptRetainingCatalogs(params) {
+        const { entry, nowMS, retaining } = params;
+        const checks = params.checks ?? {
+            mayRead: scopeReaderMayRead,
+            interfaces: (modelID)=>api.getModelInterfaces(modelID)
+        };
+        if (!await checks.mayRead(entry.owner, entry.modelID, entry.readAccess)) return [];
+        const interfaces = await checks.interfaces(entry.modelID);
+        const facts = {
+            model: entry.modelID,
+            owner: entry.owner,
+            dateOf: (field)=>field == null ? entry.scopeDate ?? entry.createdAt : entry.fieldDates[field] ?? entry.createdAt
+        };
+        const matches = (rules)=>rules.some((rule)=>scopeRuleMatchesFacts(rule, facts, nowMS, interfaces));
+        const found = new Map();
+        for (const use of retaining.uses)if (matches(use.rules)) found.set(catalogRefPrefix(use.catalog), use.catalog);
+        for (const route of retaining.routeRules)if (matches(route.rules)) found.set(catalogRefPrefix(route.catalog), route.catalog);
+        return Array.from(found.values());
+    }
+    async function writeSweptDocument(doc, digest, nowMS) {
+        const fieldDates = {};
+        for (const row of (await db.selectFrom('kubun_graph_document_scope_dates').select([
+            'field',
+            'scope_date'
+        ]).where('document_id', '=', doc.id).execute()))fieldDates[row.field] = Number(row.scope_date);
+        const read = doc.data?.accessPermissions?.read;
+        const values = {
+            model_id: doc.model,
+            owner: doc.owner,
+            created_at: doc.createdAt.getTime(),
+            scope_date: doc.scopeDate ?? null,
+            field_dates: JSON.stringify(fieldDates),
+            read_access: read == null ? null : JSON.stringify(read),
+            mutation_digest: digest,
+            swept_at: nowMS,
+            in_scope: 0,
+            scope_left_at: nowMS
+        };
+        await db.insertInto('kubun_graph_swept_documents').values({
+            document_id: doc.id,
+            ...values
+        }).onConflict((oc)=>oc.column('document_id').doUpdateSet(values)).execute();
+    }
+    async function recordScopeChange(documentID) {
+        await recordScopeChanges([
+            documentID
+        ]);
+    }
+    // Deduplicated per statement: Postgres refuses an upsert that updates one row twice.
+    async function recordScopeChanges(documentIDs) {
+        // Two bound parameters per row.
+        for (const chunk of chunked(documentIDs, IN_LIST_CHUNK / 2)){
+            await db.insertInto('kubun_graph_scope_changes').values(chunk.map((documentID)=>({
+                    document_id: documentID,
+                    version: 1
+                }))).onConflict((oc)=>oc.column('document_id').doUpdateSet({
+                    version: sql`kubun_graph_scope_changes.version + 1`
+                })).execute();
+        }
+    }
+    // Ref writers decide from rows another transaction may be replacing, so each document's refs
+    // take one writer at a time. A single-document writer takes the all-documents key shared, then
+    // its document's key. A bulk writer takes only the all-documents key, exclusive: one lock
+    // however many documents it rewrites, where a lock per document held to commit would exhaust
+    // Postgres's shared lock table on a large graph.
+    // SQLite serializes write transactions already; outside a transaction the lock would end
+    // with its own statement.
+    function refLocksApply() {
+        return adapter instanceof AbstractPostgresAdapter && db.isTransaction;
+    }
+    async function lockAllDocumentRefs() {
+        if (!refLocksApply()) return;
+        await sql`select pg_advisory_xact_lock(hashtextextended(${allDocumentRefsLockKey}, 0))`.execute(db);
+        exclusiveRefLockHolders.add(db);
+    }
+    // Bits alone cannot tell a SERVE_ONLY ref from a pull route's, so candidates are matched
+    // against the catalogs this device serves.
+    async function refsNeedBytes(rows, servedCatalogs = readServedCatalogs) {
+        const candidates = rows.filter(mayNeedBytes);
+        if (candidates.some((row)=>isCustodyPinRef(row.ref))) return true;
+        if (candidates.length === 0) return false;
+        const served = await servedCatalogs();
+        return served.some((catalog)=>candidates.some((row)=>isCatalogRuleRef(row.ref, catalog)));
+    }
+    async function readServedCatalogs() {
+        const served = await db.selectFrom('kubun_graph_catalog_use').select([
+            'owner_did',
+            'catalog_id'
+        ]).where('level', '=', 'SERVE_ONLY').execute();
+        return served.map((use)=>({
+                owner: use.owner_did,
+                id: use.catalog_id
+            }));
+    }
+    async function readCatalogUses(catalog) {
+        let query = db.selectFrom('kubun_graph_catalog_use').selectAll();
+        if (catalog != null) query = query.where('owner_did', '=', catalog.owner).where('catalog_id', '=', catalog.id);
+        return (await query.execute()).map((use)=>({
+                catalog: {
+                    owner: use.owner_did,
+                    id: use.catalog_id
+                },
+                level: use.level,
+                rules: typeof use.rules === 'string' ? JSON.parse(use.rules) : use.rules
+            }));
+    }
+    // The reads of a single-document recompute, each as it is asked for.
+    const directRecomputeInputs = (nowMS, catalog)=>({
+            document: async (documentID)=>await api.getDocument(documentID),
+            priorRefs: async (documentID)=>await db.selectFrom('kubun_graph_document_refs').select([
+                    'ref',
+                    'displays',
+                    'retains'
+                ]).where('document_id', '=', documentID).execute(),
+            liveHoldRefs: async (documentID)=>new Set((await api.listDocumentHolds(documentID, nowMS)).map((hold)=>`hold:${hold.id}`)),
+            interfaces: async (modelID)=>await api.getModelInterfaces(modelID),
+            guardedRules: catalogRulesByRef,
+            mayRead: scopeReaderMayRead,
+            catalogs: async ()=>await readCatalogUses(catalog),
+            servedCatalogs: readServedCatalogs,
+            present: false
+        });
+    // Documents read by model, absent ones left out; an undeployed model throws as `getDocument`.
+    async function readDocumentsByID(documentIDs) {
+        const byModel = new Map();
+        for (const documentID of documentIDs){
+            const modelID = DocumentID.fromString(documentID).model.toString();
+            const ids = byModel.get(modelID);
+            if (ids == null) byModel.set(modelID, [
+                documentID
+            ]);
+            else ids.push(documentID);
+        }
+        const found = new Map();
+        for (const [modelID, ids] of byModel){
+            const rows = await db.selectFrom(`k_${modelID}`).selectAll().where('id', 'in', ids).execute().catch((err)=>{
+                if (isMissingTableError(err, `k_${modelID}`)) throw new ModelNotDeployedError(modelID, {
+                    cause: err
+                });
+                throw err;
+            });
+            for (const row of rows){
+                const node = documentNodeFromTable(adapter, row);
+                found.set(node.id, node);
+            }
+        }
+        return found;
+    }
+    /**
+   * A bulk writer's recompute: each document as `recomputeDocumentRefs` rewrites it, in the given
+   * order, under the caller's ref lock. A document's recompute writes only its own refs, mark,
+   * scope change and byte jobs, none of which another document's recompute reads, so the rest
+   * is read once per chunk of documents or once per pass.
+   */ const recomputeDocumentRefsBatch = async (params)=>{
+        const { documentIDs, routeRules, nowMS, catalog, releaseCustodyPins: release } = params;
+        if (documentIDs.length === 0) return;
+        if (context.provider === context.root) {
+            // Outside a transaction each document's recompute commits on its own.
+            for (const documentID of documentIDs)await api.recomputeDocumentRefs({
+                documentID,
+                routeRules,
+                nowMS,
+                catalog,
+                releaseCustodyPins: release
+            });
+            return;
+        }
+        await lockDocumentRefs(documentIDs);
+        const effectiveRouteRules = routeRules.length === 0 ? await context.getCatalogRouteRules(nowMS, catalog) : routeRules;
+        const interfaces = memoisedInterfaces();
+        const mayRead = memoisedReadCheck();
+        let catalogs;
+        let served;
+        const guardRules = new Map();
+        for (const chunk of chunked(documentIDs)){
+            const documents = await readDocumentsByID(chunk);
+            const prior = new Map();
+            for (const row of (await db.selectFrom('kubun_graph_document_refs').select([
+                'document_id',
+                'ref',
+                'displays',
+                'retains'
+            ]).where('document_id', 'in', chunk).execute())){
+                const rows = prior.get(row.document_id) ?? [];
+                rows.push({
+                    ref: row.ref,
+                    displays: row.displays,
+                    retains: row.retains
+                });
+                prior.set(row.document_id, rows);
+            }
+            const holds = new Map();
+            for (const row of (await db.selectFrom('kubun_graph_document_holds').select([
+                'document_id',
+                'hold_id'
+            ]).where('document_id', 'in', chunk).where('released_at', 'is', null).where((eb)=>eb.or([
+                    eb('expires_at', 'is', null),
+                    eb('expires_at', '>', nowMS)
+                ])).execute())){
+                const refs = holds.get(row.document_id) ?? new Set();
+                refs.add(`hold:${row.hold_id}`);
+                holds.set(row.document_id, refs);
+            }
+            const inputs = {
+                document: async (documentID)=>documents.get(documentID) ?? null,
+                priorRefs: async (documentID)=>prior.get(documentID) ?? [],
+                liveHoldRefs: async (documentID)=>holds.get(documentID) ?? new Set(),
+                interfaces,
+                guardedRules: async (wanted)=>{
+                    const missing = wanted.filter((catalog)=>!guardRules.has(JSON.stringify([
+                            catalog.owner,
+                            catalog.id
+                        ])));
+                    if (missing.length > 0) {
+                        const found = await catalogRulesByRef(missing);
+                        for (const catalog of missing){
+                            const key = JSON.stringify([
+                                catalog.owner,
+                                catalog.id
+                            ]);
+                            guardRules.set(key, found.get(key) ?? []);
+                        }
+                    }
+                    return guardRules;
+                },
+                mayRead,
+                catalogs: async ()=>{
+                    catalogs ??= readCatalogUses(catalog);
+                    return await catalogs;
+                },
+                servedCatalogs: async ()=>{
+                    served ??= readServedCatalogs();
+                    return await served;
+                },
+                // Nothing in the pass removes a document.
+                present: true
+            };
+            for (const documentID of chunk){
+                const released = new Set(release != null && release.refs.length > 0 && await release.confirm() ? release.refs : []);
+                await recomputeRefsWith({
+                    documentID,
+                    routeRules: effectiveRouteRules,
+                    nowMS,
+                    catalog,
+                    released
+                }, inputs);
+            }
+        }
+    };
+    // Rewrites one document's refs and mark from what `inputs` reads: false when it is absent.
+    const recomputeRefsWith = async (step, inputs)=>{
+        const { documentID, routeRules, nowMS, catalog, released } = step;
+        const doc = await inputs.document(documentID);
+        if (doc == null) return false;
+        const prior = await inputs.priorRefs(documentID);
+        const liveHoldRefs = await inputs.liveHoldRefs(documentID);
+        const refs = new Map();
+        for (const row of prior){
+            if (row.ref === 'local' || // Custody pins are sticky: scope exit, read loss and a lost assignment keep them. Null
+            // data is only ever a tombstone winning, which releases them.
+            isCustodyPinRef(row.ref) && doc.data != null && !released.has(row.ref) || // A hold with no row (never written, or released) has nothing keeping the ref alive.
+            liveHoldRefs.has(row.ref) || catalog != null && !row.ref.startsWith('hold:') && !isCatalogRuleRef(row.ref, catalog)) refs.set(row.ref, {
+                displays: Number(row.displays),
+                retains: Number(row.retains)
+            });
+        }
+        const interfaces = await inputs.interfaces(doc.model);
+        // Computed before the read check: a custodian keeps what it guards whatever it may read.
+        const guards = doc.data == null ? [] : await context.custody?.guards() ?? [];
+        const guardedRules = await inputs.guardedRules(guards.filter((guard)=>!refs.has(custodyPinRef(guard))).map((guard)=>guard.catalog));
+        for (const guard of guards){
+            const ref = custodyPinRef(guard);
+            if (refs.has(ref)) continue;
+            // Any rule of the guarded catalog, whatever level this device keeps it at.
+            const rules = guardedRules.get(JSON.stringify([
+                guard.catalog.owner,
+                guard.catalog.id
+            ])) ?? [];
+            if (!rules.some((rule)=>scopeRuleMatches(rule, doc, nowMS, interfaces))) continue;
+            if (!await context.custody?.keepsOwner(guard.custodyOwner, doc.owner)) continue;
+            refs.set(ref, {
+                displays: 0,
+                retains: 1
+            });
+        }
+        const finish = async ()=>{
+            await replaceDocumentRefs({
+                documentID,
+                prior,
+                refs,
+                catalog,
+                nowMS,
+                present: inputs.present
+            });
+            // In this transaction, so kept bytes are queued, or released ones dropped, before the
+            // document can change again. Prior refs are read without their catalog's current level:
+            // a level change commits before the recompute that drops the catalog's refs.
+            if (doc.data != null && await refsNeedBytes(Array.from(refs, ([ref, bits])=>({
+                    ref,
+                    ...bits
+                })), inputs.servedCatalogs)) await context.documentBytes.needed(documentID);
+            else if (prior.some(mayNeedBytes)) await context.documentBytes.released(documentID);
+            return true;
+        };
+        const data = doc.data;
+        if (!await inputs.mayRead(doc.owner, doc.model, data?.accessPermissions?.read ?? null)) return await finish();
+        for (const use of (await inputs.catalogs())){
+            if (use.level == null) continue;
+            const bits = catalogLevelBits[use.level];
+            for (const rule of use.rules){
+                if (!scopeRuleMatches(rule, doc, nowMS, interfaces)) continue;
+                refs.set(catalogRuleRef(use.catalog, rule.id), bits);
+            }
+        }
+        for (const route of routeRules){
+            if (catalog != null && (route.catalog.owner !== catalog.owner || route.catalog.id !== catalog.id)) continue;
+            for (const rule of route.rules){
+                if (!scopeRuleMatches(rule, doc, nowMS, interfaces)) continue;
+                const ref = catalogRuleRef(route.catalog, rule.id);
+                refs.set(ref, {
+                    displays: refs.get(ref)?.displays ?? 0,
+                    retains: 1
+                });
+            }
+        }
+        return await finish();
+    };
+    async function lockDocumentRefs(documentIDs) {
+        if (!refLocksApply()) return;
+        if (exclusiveRefLockHolders.has(db)) {
+            // Taken again rather than trusted, as a rolled-back savepoint releases its locks. A held
+            // lock is taken again without another lock table entry.
+            await lockAllDocumentRefs();
+            return;
+        }
+        await sql`select pg_advisory_xact_lock_shared(hashtextextended(${allDocumentRefsLockKey}, 0))`.execute(db);
+        for (const documentID of [
+            ...new Set(documentIDs)
+        ].sort()){
+            await sql`select pg_advisory_xact_lock(hashtextextended(${`graph.document.refs:${documentID}`}, 0))`.execute(db);
+        }
+    }
+    async function mutationDigest(documentID) {
+        const rows = await db.selectFrom('kubun_graph_mutation_log').select('mutation_hash').where('document_id', '=', documentID).where('status', '=', 'applied').execute();
+        return mutationIDsDigest(rows.map((row)=>row.mutation_hash));
+    }
+    // Runs in the ref writer's locked transaction, after its write, so a mark never disagrees with
+    // the refs a concurrent reader can see. A mark restarts only when the document's mutations
+    // changed, so grace time is kept across repeated recomputes.
+    async function syncGCMark(documentID, nowMS, present = false) {
+        const retaining = await db.selectFrom('kubun_graph_document_refs').select('ref').where('document_id', '=', documentID).where('retains', '>', 0).limit(1).executeTakeFirst();
+        if (retaining != null || !present && await api.getDocument(documentID) == null) {
+            await db.deleteFrom('kubun_graph_gc_marks').where('document_id', '=', documentID).execute();
+            return;
+        }
+        const digest = await mutationDigest(documentID);
+        await db.insertInto('kubun_graph_gc_marks').values({
+            document_id: documentID,
+            digest,
+            marked_at: nowMS
+        }).onConflict((oc)=>oc.column('document_id').doUpdateSet({
+                digest,
+                marked_at: nowMS
+            }).where('kubun_graph_gc_marks.digest', '!=', digest)).execute();
+    }
+    async function replaceDocumentRefs(params) {
+        await writeDocumentRefs(params);
+        await syncGCMark(params.documentID, params.nowMS, params.present);
+    }
+    async function writeDocumentRefs(params) {
+        const { documentID, prior, refs, catalog } = params;
+        // Hold refs are managed on every path so a stale one is removed even in a catalog-scoped pass.
+        const managed = (ref)=>catalog == null || isCatalogRuleRef(ref, catalog) || ref.startsWith('hold:');
+        const previous = prior.filter((row)=>managed(row.ref));
+        const selected = new Map([
+            ...refs
+        ].filter(([ref])=>managed(ref)));
+        if (previous.length === selected.size && previous.every((row)=>{
+            const bits = selected.get(row.ref);
+            return bits != null && bits.displays === Number(row.displays) && bits.retains === Number(row.retains);
+        })) return;
+        const removal = db.deleteFrom('kubun_graph_document_refs').where('document_id', '=', documentID);
+        if (catalog == null) await removal.execute();
+        else if (previous.length > 0) await removal.where('ref', 'in', previous.map((row)=>row.ref)).execute();
+        if (selected.size > 0) {
+            await db.insertInto('kubun_graph_document_refs').values(Array.from(selected, ([ref, bits])=>({
+                    document_id: documentID,
+                    ref,
+                    displays: bits.displays,
+                    retains: bits.retains
+                }))).execute();
+        }
+        await recordScopeChange(documentID);
+    }
+    const pendingLifetimeMS = 24 * 60 * 60 * 1000;
+    async function expirePushedMutations(now, groupID) {
+        // Guard deletion and parking must share the same lock, including an upsert racing deletion.
+        let guards = db.selectFrom('kubun_graph_pending_groups').select('group_id');
+        if (groupID != null) guards = guards.where('group_id', '=', groupID);
+        const groups = await (adapter instanceof AbstractPostgresAdapter ? guards.orderBy('group_id').forUpdate() : guards).execute();
+        let query = db.deleteFrom('kubun_graph_mutation_log').where('status', '=', 'pending').where('arrival_group_id', 'is not', null).where('parked_at', '<=', now - pendingLifetimeMS);
+        if (groupID != null) query = query.where('arrival_group_id', '=', groupID);
+        await query.execute();
+        // A parking transaction still needs its guard until it has inserted the new row.
+        if (groupID != null || groups.length === 0) return;
+        await db.deleteFrom('kubun_graph_pending_groups').where('group_id', 'in', groups.map((group)=>group.group_id)).where((eb)=>eb.not(eb.exists(eb.selectFrom('kubun_graph_mutation_log').select('mutation_hash').where('status', '=', 'pending').whereRef('arrival_group_id', '=', 'kubun_graph_pending_groups.group_id')))).execute();
+    }
     const api = {
+        ...createGraphAccessDefaultRecordMethods(db, adapter),
+        ...createGraphCatalogRecordMethods(db, adapter, {
+            onClose: context.onClose,
+            // A custody change can complete or stop a pin handoff.
+            onCustodyRecordStored: ()=>context.provider.onCommit(()=>context.custodyRecordsChanged?.())
+        }),
+        ...createCatalogStateMethods(db),
         // --- Document operations ---
         async getDocument (id) {
             const parsedID = DocumentID.from(id);
@@ -410,7 +1460,11 @@ export function createGraphStore(db, adapter) {
             // duplicate id does not depend on which query returned first.
             const rowsByModel = await Promise.all(Array.from(idsByModel, async ([modelID, documentIDs])=>{
                 try {
-                    return await db.selectFrom(`k_${modelID}`).selectAll().where('id', 'in', documentIDs).execute();
+                    const rows = [];
+                    for (const chunk of chunked(documentIDs)){
+                        rows.push(...await db.selectFrom(`k_${modelID}`).selectAll().where('id', 'in', chunk).execute());
+                    }
+                    return rows;
                 } catch (err) {
                     // A batch spans models, so one undeployed model contributes nothing
                     // rather than failing the read for every other id asked for. The
@@ -436,6 +1490,27 @@ export function createGraphStore(db, adapter) {
             const rows = await db.selectFrom('kubun_graph_document_model_interfaces').select('interface_id').where('implementation_id', '=', modelID).execute();
             return rows.map((row)=>row.interface_id);
         },
+        async listModelInterfaces () {
+            const links = await db.selectFrom('kubun_graph_document_model_interfaces').select([
+                'implementation_id',
+                'interface_id'
+            ]).execute();
+            const interfaces = new Map();
+            for (const link of links){
+                const list = interfaces.get(link.implementation_id) ?? [];
+                list.push(link.interface_id);
+                interfaces.set(link.implementation_id, list);
+            }
+            return interfaces;
+        },
+        async getDocumentModelsByID (ids) {
+            const models = new Map();
+            for (const chunk of chunked(new Set(ids))){
+                const rows = await db.selectFrom('kubun_graph_document_models').selectAll().where('id', 'in', chunk).execute();
+                for (const row of rows)models.set(row.id, documentModelFromTable(row));
+            }
+            return models;
+        },
         async createDocument (params) {
             const id = params.id.toString();
             const model = params.id.model.toString();
@@ -443,13 +1518,28 @@ export function createGraphStore(db, adapter) {
                 id,
                 owner: params.owner,
                 model,
-                data: adapter.encodeJSON(params.data),
+                // Null data (a first-seen tombstone establishing a dead row) persists
+                // as SQL null, not the JSON string "null" — mirrors `saveDocument`.
+                data: params.data ? adapter.encodeJSON(params.data) : null,
                 unique: adapter.encodeBinary(params.unique)
             }).returningAll().executeTakeFirstOrThrow(()=>new Error(`createDocument failed to return row for ${id}`));
+            // Re-acquired, by an answer or a pushed version: nothing left to restore.
+            await db.deleteFrom('kubun_graph_swept_documents').where('document_id', '=', id).execute();
             if (params.data) {
                 await reindexDocument(model, id, params.data);
             }
-            return documentNodeFromTable(adapter, doc);
+            await refreshDocumentDates(id);
+            if (params.authoredHere !== false) await api.markDocumentLocal(id);
+            await api.recomputeDocumentRefs({
+                documentID: id,
+                routeRules: []
+            });
+            // markDocumentLocal already told the listeners for an authored create.
+            if (params.authoredHere === false) await context.documentApplied({
+                documentID: id,
+                authored: false
+            });
+            return await api.getDocument(id) ?? documentNodeFromTable(adapter, doc);
         },
         async saveDocument (params) {
             const id = params.id.toString();
@@ -463,22 +1553,955 @@ export function createGraphStore(db, adapter) {
             } else {
                 await unindexDocument(model, id);
             }
-            return documentNodeFromTable(adapter, doc);
+            await refreshDocumentDates(id);
+            await api.recomputeDocumentRefs({
+                documentID: id,
+                routeRules: []
+            });
+            // Not authored: a local apply calls markDocumentLocal after this, which says so.
+            await context.documentApplied({
+                documentID: id,
+                authored: false
+            });
+            return await api.getDocument(id) ?? documentNodeFromTable(adapter, doc);
+        },
+        async getDocumentDates (documentID) {
+            const modelID = DocumentID.fromString(documentID).model.toString();
+            const row = await db.selectFrom(`k_${modelID}`).select([
+                'mutation_created_at',
+                'mutation_updated_at',
+                'scope_date'
+            ]).where('id', '=', documentID).executeTakeFirst();
+            if (row == null) return null;
+            return {
+                createdAt: row.mutation_created_at == null ? null : Number(row.mutation_created_at),
+                updatedAt: row.mutation_updated_at == null ? null : Number(row.mutation_updated_at),
+                scopeDate: row.scope_date == null ? null : Number(row.scope_date)
+            };
+        },
+        async setCatalogDefinition (ref, catalog) {
+            validateScopeCatalog(catalog);
+            const dateModelIDs = new Set();
+            for (const rule of catalog.rules){
+                if (rule.dateField == null) continue;
+                for (const modelID of rule.models ?? [])dateModelIDs.add(modelID);
+            }
+            const dateModels = new Map();
+            for (const chunk of chunked(dateModelIDs)){
+                const rows = await db.selectFrom('kubun_graph_document_models').select([
+                    'id',
+                    'schema'
+                ]).where('id', 'in', chunk).execute();
+                for (const row of rows)dateModels.set(row.id, row);
+            }
+            for (const rule of catalog.rules){
+                if (rule.dateField == null) continue;
+                for (const modelID of rule.models ?? []){
+                    const model = dateModels.get(modelID);
+                    if (model == null || !isDocumentDateField(model, rule.dateField)) {
+                        throw new InvalidModelDateFieldError(`Invalid date-field override: ${rule.dateField}`);
+                    }
+                }
+            }
+            const previous = await db.selectFrom('kubun_graph_catalog_use').select([
+                'rules',
+                'level'
+            ]).where('owner_did', '=', ref.owner).where('catalog_id', '=', ref.id).executeTakeFirst();
+            const previousRules = previous == null ? [] : typeof previous.rules === 'string' ? JSON.parse(previous.rules) : previous.rules;
+            const affectedTasks = previous?.level != null ? await tasksForCatalog(ref, [
+                ...previousRules,
+                ...catalog.rules
+            ]) : [];
+            await db.insertInto('kubun_graph_catalog_use').values({
+                owner_did: ref.owner,
+                catalog_id: ref.id,
+                name: catalog.name,
+                rules: adapter.encodeJSON(catalog.rules),
+                level: null,
+                followed: 0
+            }).onConflict((oc)=>oc.columns([
+                    'owner_did',
+                    'catalog_id'
+                ]).doUpdateSet({
+                    name: catalog.name,
+                    rules: adapter.encodeJSON(catalog.rules)
+                })).execute();
+            scheduleScopeTasks(context, affectedTasks);
+        },
+        async setScopeReaderDID (did, defaultReadLevel = 'only_owner') {
+            const current = await db.selectFrom('kubun_graph_scope_identity').select([
+                'reader_did',
+                'default_read_level'
+            ]).where('id', '=', 1).executeTakeFirst();
+            if (current?.reader_did === did && current.default_read_level === defaultReadLevel) return;
+            await db.insertInto('kubun_graph_scope_identity').values({
+                id: 1,
+                reader_did: did,
+                default_read_level: defaultReadLevel
+            }).onConflict((oc)=>oc.column('id').doUpdateSet({
+                    reader_did: did,
+                    default_read_level: defaultReadLevel
+                })).execute();
+            const models = await db.selectFrom('kubun_graph_document_models').select('id').execute();
+            scheduleScopeModels(context, models.map((model)=>model.id));
+        },
+        async setCatalogUse (ref, use) {
+            const catalog = await db.selectFrom('kubun_graph_catalog_use').select([
+                'rules',
+                'level'
+            ]).where('owner_did', '=', ref.owner).where('catalog_id', '=', ref.id).executeTakeFirst();
+            const rules = catalog == null ? [] : typeof catalog.rules === 'string' ? JSON.parse(catalog.rules) : catalog.rules;
+            const affectedTasks = catalog != null && (catalog.level ?? null) !== use.level ? await tasksForCatalog(ref, rules) : [];
+            await db.updateTable('kubun_graph_catalog_use').set({
+                level: use.level,
+                followed: Number(use.followed)
+            }).where('owner_did', '=', ref.owner).where('catalog_id', '=', ref.id).execute();
+            scheduleScopeTasks(context, affectedTasks);
+        },
+        async getCatalogUse (ref) {
+            const row = await db.selectFrom('kubun_graph_catalog_use').select([
+                'level',
+                'followed'
+            ]).where('owner_did', '=', ref.owner).where('catalog_id', '=', ref.id).executeTakeFirst();
+            return row == null ? null : catalogUseFromRow(row);
+        },
+        async getCatalogUses (refs) {
+            if (refs.length === 0) return [];
+            // The exact keys as one row-value list, as the batched record decisions read them.
+            const unique = new Map(refs.map((ref)=>[
+                    JSON.stringify([
+                        ref.owner,
+                        ref.id
+                    ]),
+                    ref
+                ]));
+            const wanted = sql.join(Array.from(unique.values(), (ref)=>sql`(${ref.owner}, ${ref.id})`));
+            const rows = await db.selectFrom('kubun_graph_catalog_use').select([
+                'owner_did',
+                'catalog_id',
+                'level',
+                'followed'
+            ]).where(sql`(${sql.ref('owner_did')}, ${sql.ref('catalog_id')}) in (values ${wanted})`).execute();
+            const uses = new Map(rows.map((row)=>[
+                    JSON.stringify([
+                        row.owner_did,
+                        row.catalog_id
+                    ]),
+                    catalogUseFromRow(row)
+                ]));
+            return refs.map((ref)=>uses.get(JSON.stringify([
+                    ref.owner,
+                    ref.id
+                ])) ?? null);
+        },
+        async deleteCatalogUse (ref) {
+            if (context.provider === context.root) {
+                await context.root.withTransaction(async (tx)=>{
+                    await (await tx.getStore('graph')).deleteCatalogUse(ref);
+                });
+                return;
+            }
+            const existing = await db.selectFrom('kubun_graph_catalog_use').select([
+                'rules',
+                'level'
+            ]).where('owner_did', '=', ref.owner).where('catalog_id', '=', ref.id).executeTakeFirst();
+            if (context.provider.hasStore('p2p')) {
+                const p2p = await context.provider.getStore('p2p');
+                await p2p.deleteCatalogRoutes(ref.owner, ref.id);
+                await p2p.removeCatalogOffersForCatalog(ref.owner, ref.id);
+            }
+            if (existing === undefined) return;
+            const rules = typeof existing.rules === 'string' ? JSON.parse(existing.rules) : existing.rules;
+            const affectedTasks = existing.level != null ? await tasksForCatalog(ref, rules) : [];
+            await db.deleteFrom('kubun_graph_catalog_use').where('owner_did', '=', ref.owner).where('catalog_id', '=', ref.id).execute();
+            scheduleScopeTasks(context, affectedTasks);
+            await api.reconcileCatalogRefs(Date.now(), [], ref);
+        },
+        async markDocumentLocal (documentID) {
+            if (context.provider === context.root) {
+                await context.root.withTransaction(async (tx)=>{
+                    await (await tx.getStore('graph')).markDocumentLocal(documentID);
+                });
+                return;
+            }
+            await lockDocumentRefs([
+                documentID
+            ]);
+            const inserted = await db.insertInto('kubun_graph_document_refs').values({
+                document_id: documentID,
+                ref: 'local',
+                displays: 1,
+                retains: 0
+            }).onConflict((oc)=>oc.doNothing()).returning('ref').execute();
+            if (inserted.length > 0) await recordScopeChange(documentID);
+            await syncGCMark(documentID, Date.now());
+            // Called once per apply authored here, after its data is final.
+            await context.documentApplied({
+                documentID,
+                authored: true
+            });
+        },
+        async placeDocumentHold (params) {
+            if (context.provider === context.root) {
+                return await context.root.withTransaction(async (tx)=>(await tx.getStore('graph')).placeDocumentHold(params));
+            }
+            const { holdID, documentID, createdBy, reason, expiresAt } = params;
+            await lockDocumentRefs([
+                documentID
+            ]);
+            // A sweep deletes the row under this lock: one committed since the caller looked leaves
+            // nothing to hold.
+            if ((await api.getDocument(documentID))?.data == null) throw new DocumentNotHoldableError();
+            await db.insertInto('kubun_graph_document_holds').values({
+                hold_id: holdID,
+                document_id: documentID,
+                created_by: createdBy,
+                reason: reason ?? null,
+                expires_at: expiresAt ?? null,
+                released_at: null
+            }).execute();
+            await db.insertInto('kubun_graph_document_refs').values({
+                document_id: documentID,
+                ref: `hold:${holdID}`,
+                displays: 0,
+                retains: 1
+            }).onConflict((oc)=>oc.doNothing()).execute();
+            await recordScopeChange(documentID);
+            await syncGCMark(documentID, Date.now());
+            return {
+                id: holdID,
+                documentID,
+                createdBy,
+                reason: reason ?? null,
+                expiresAt: expiresAt ?? null
+            };
+        },
+        async releaseDocumentHold (holdID, nowMS) {
+            if (context.provider === context.root) {
+                return await context.root.withTransaction(async (tx)=>(await tx.getStore('graph')).releaseDocumentHold(holdID, nowMS));
+            }
+            // A hold never changes document, so its document can be locked before the release decides.
+            const target = await db.selectFrom('kubun_graph_document_holds').select('document_id').where('hold_id', '=', holdID).executeTakeFirst();
+            if (target == null) return null;
+            await lockDocumentRefs([
+                target.document_id
+            ]);
+            const released = await db.updateTable('kubun_graph_document_holds').set({
+                released_at: nowMS
+            }).where('hold_id', '=', holdID).where('released_at', 'is', null).returningAll().executeTakeFirst();
+            if (released == null) return null;
+            await db.deleteFrom('kubun_graph_document_refs').where('document_id', '=', released.document_id).where('ref', '=', `hold:${holdID}`).execute();
+            await recordScopeChange(released.document_id);
+            await syncGCMark(released.document_id, nowMS);
+            return holdFromRow(released);
+        },
+        documentMutationDigest: mutationDigest,
+        async hasAppliedMutations (documentID, mutationIDs) {
+            for (const chunk of chunked(mutationIDs)){
+                const row = await db.selectFrom('kubun_graph_mutation_log').select((eb)=>eb.fn.countAll().as('count')).where('document_id', '=', documentID).where('status', '=', 'applied').where('mutation_hash', 'in', chunk).executeTakeFirst();
+                if (Number(row?.count ?? 0) !== chunk.length) return false;
+            }
+            return true;
+        },
+        async putCustodyNonce (nonce) {
+            await db.deleteFrom('kubun_graph_custody_nonces').where('expires_at', '<=', Date.now()).execute();
+            await db.insertInto('kubun_graph_custody_nonces').values({
+                nonce: nonce.nonce,
+                custodian: nonce.custodian,
+                assignment_digest: nonce.assignmentDigest,
+                expires_at: nonce.expiresAt
+            }).execute();
+        },
+        async consumeCustodyNonce (params) {
+            // One statement, so two concurrent consumers cannot both see the row.
+            const result = await db.deleteFrom('kubun_graph_custody_nonces').where('nonce', '=', params.nonce).where('custodian', '=', params.custodian).where('assignment_digest', '=', params.assignmentDigest).where('expires_at', '>', params.nowMS).executeTakeFirst();
+            return Number(result.numDeletedRows) === 1;
+        },
+        async putCustodyReceipts (receipts) {
+            for (const receipt of receipts){
+                const values = {
+                    group_id: receipt.groupID,
+                    custody_owner: receipt.custodyOwner,
+                    catalog_owner: receipt.catalog.owner,
+                    catalog_id: receipt.catalog.id,
+                    assignment_digest: receipt.assignmentDigest,
+                    head_digest: receipt.headDigest,
+                    mutation_digest: receipt.mutationDigest,
+                    received_at: receipt.receivedAt
+                };
+                await db.insertInto('kubun_graph_custody_receipts').values({
+                    document_id: receipt.documentID,
+                    custodian: receipt.custodian,
+                    ...values
+                }).onConflict((oc)=>oc.columns([
+                        'document_id',
+                        'custodian'
+                    ]).doUpdateSet(values)).execute();
+            }
+        },
+        async listCustodyPinnedDocuments (params) {
+            let query = db.selectFrom('kubun_graph_document_refs').select('document_id').where('ref', '=', params.ref);
+            if (params.after != null) query = query.where('document_id', '>', params.after);
+            const rows = await query.orderBy('document_id').limit(params.limit).execute();
+            return rows.map((row)=>row.document_id);
+        },
+        async listCustodyReceipts (documentID) {
+            const rows = await db.selectFrom('kubun_graph_custody_receipts').selectAll().where('document_id', '=', documentID).orderBy('custodian').execute();
+            return rows.map(custodyReceiptFromRow);
+        },
+        async getGCMark (documentID) {
+            const row = await db.selectFrom('kubun_graph_gc_marks').selectAll().where('document_id', '=', documentID).executeTakeFirst();
+            return row == null ? null : gcMarkFromRow(row);
+        },
+        async dropGCMark (params) {
+            await db.deleteFrom('kubun_graph_gc_marks').where('document_id', '=', params.documentID).where('digest', '=', params.digest).execute();
+        },
+        async listGCMarks (params) {
+            let query = db.selectFrom('kubun_graph_gc_marks').selectAll();
+            // Bytewise order and cursor, so paging agrees across adapters.
+            const postgres = adapter instanceof AbstractPostgresAdapter;
+            if (params.after != null) query = query.where(postgres ? sql`document_id collate "C" > ${params.after}` : sql`document_id > ${params.after}`);
+            const rows = await (postgres ? query.orderBy(sql`document_id collate "C"`) : query.orderBy('document_id')).limit(params.limit).execute();
+            return rows.map(gcMarkFromRow);
+        },
+        async getDocumentHold (holdID) {
+            const row = await db.selectFrom('kubun_graph_document_holds').selectAll().where('hold_id', '=', holdID).executeTakeFirst();
+            return row == null ? null : holdFromRow(row);
+        },
+        async listDocumentHolds (documentID, nowMS) {
+            const rows = await db.selectFrom('kubun_graph_document_holds').selectAll().where('document_id', '=', documentID).where('released_at', 'is', null).where((eb)=>eb.or([
+                    eb('expires_at', 'is', null),
+                    eb('expires_at', '>', nowMS)
+                ])).orderBy('hold_id').execute();
+            return rows.map(holdFromRow);
+        },
+        async nextDocumentHoldExpiry () {
+            const tick = await db.selectFrom('kubun_graph_catalog_scope_tick').select('last_at').where('id', '=', 1).executeTakeFirst();
+            let query = db.selectFrom('kubun_graph_document_holds').select((eb)=>eb.fn.min('expires_at').as('expires_at')).where('released_at', 'is', null).where('expires_at', 'is not', null);
+            if (tick != null) query = query.where('expires_at', '>', Number(tick.last_at));
+            const row = await query.executeTakeFirst();
+            return row?.expires_at == null ? null : Number(row.expires_at);
+        },
+        async listPendingScopeChanges () {
+            const rows = await db.selectFrom('kubun_graph_scope_changes').select([
+                'document_id',
+                'version'
+            ]).orderBy('document_id').execute();
+            return rows.map((row)=>({
+                    documentID: row.document_id,
+                    version: row.version
+                }));
+        },
+        async ackDocumentScopeChange (documentID, version) {
+            await db.deleteFrom('kubun_graph_scope_changes').where('document_id', '=', documentID).where('version', '=', version).execute();
+        },
+        async getDocumentScope (documentID) {
+            const rows = await db.selectFrom('kubun_graph_document_refs').select([
+                'ref',
+                'displays',
+                'retains'
+            ]).where('document_id', '=', documentID).orderBy('ref').execute();
+            const retained = rows.some((row)=>Number(row.retains) === 1);
+            return {
+                scope: rows.some((row)=>Number(row.displays) === 1) ? 'visible' : retained ? 'retained' : 'outOfScope',
+                retained,
+                refs: rows.map((row)=>row.ref)
+            };
+        },
+        async getDocumentAvailability (documentID, nowMS) {
+            const doc = await api.getDocument(documentID);
+            if (doc != null) return doc.data == null ? null : 'LOCAL';
+            const entry = await api.getSweptDocument(documentID);
+            if (entry == null) return null;
+            const catalogs = await sweptRetainingCatalogs({
+                entry,
+                nowMS,
+                retaining: await retainingRules(nowMS)
+            });
+            return catalogs.length > 0 ? 'UNAVAILABLE' : null;
+        },
+        async nextSweptDocumentTransition (nowMS) {
+            const rows = await db.selectFrom('kubun_graph_swept_documents').selectAll().execute();
+            if (rows.length === 0) return null;
+            const retaining = await retainingRules(nowMS);
+            const windowed = [
+                ...retaining.uses.flatMap((use)=>use.rules),
+                ...retaining.routeRules.flatMap((route)=>route.rules)
+            ].filter((rule)=>rule.maxAge != null || rule.maxAhead != null);
+            if (windowed.length === 0) return null;
+            const interfaces = new Map();
+            let next = null;
+            for (const row of rows){
+                const entry = sweptFromRow(row);
+                let modelInterfaces = interfaces.get(entry.modelID);
+                if (modelInterfaces == null) {
+                    modelInterfaces = await api.getModelInterfaces(entry.modelID);
+                    interfaces.set(entry.modelID, modelInterfaces);
+                }
+                for (const rule of windowed){
+                    // The rule without its window: only the window moves with time.
+                    const unbounded = {
+                        ...rule,
+                        maxAge: undefined,
+                        maxAhead: undefined
+                    };
+                    const facts = {
+                        model: entry.modelID,
+                        owner: entry.owner,
+                        dateOf: ()=>0
+                    };
+                    if (!scopeRuleMatchesFacts(unbounded, facts, nowMS, modelInterfaces)) continue;
+                    const date = rule.dateField == null ? entry.scopeDate ?? entry.createdAt : entry.fieldDates[rule.dateField] ?? entry.createdAt;
+                    // `date < now + maxAhead` starts holding just after `date - maxAhead`;
+                    // `date >= now - maxAge` stops holding just after `date + maxAge`.
+                    const times = [
+                        rule.maxAhead == null ? null : date - parseScopeDuration(rule.maxAhead) + 1,
+                        rule.maxAge == null ? null : date + parseScopeDuration(rule.maxAge) + 1
+                    ];
+                    for (const time of times)if (time != null && time > nowMS && (next == null || time < next)) next = time;
+                }
+            }
+            return next;
+        },
+        async getSweptDocument (documentID) {
+            const row = await db.selectFrom('kubun_graph_swept_documents').selectAll().where('document_id', '=', documentID).executeTakeFirst();
+            return row == null ? null : sweptFromRow(row);
+        },
+        async listUnavailableDocuments (params) {
+            const retaining = await retainingRules(params.nowMS);
+            const checks = {
+                mayRead: memoisedReadCheck(),
+                interfaces: memoisedInterfaces()
+            };
+            const found = [];
+            let after = params.after;
+            for(;;){
+                let query = db.selectFrom('kubun_graph_swept_documents').selectAll().orderBy('document_id').limit(SWEPT_PAGE);
+                if (after != null) query = query.where('document_id', '>', after);
+                const rows = await query.execute();
+                for (const row of rows){
+                    const entry = sweptFromRow(row);
+                    const catalogs = await sweptRetainingCatalogs({
+                        entry,
+                        nowMS: params.nowMS,
+                        retaining,
+                        checks
+                    });
+                    if (catalogs.length === 0) continue;
+                    found.push({
+                        documentID: entry.documentID,
+                        owner: entry.owner,
+                        catalogs
+                    });
+                    if (found.length >= params.limit) return found;
+                }
+                if (rows.length < SWEPT_PAGE) return found;
+                after = rows.at(-1)?.document_id;
+            }
+        },
+        async refreshSweptDocuments (params) {
+            if (context.provider === context.root) {
+                await context.root.withTransaction(async (tx)=>{
+                    const graph = await tx.getStore('graph');
+                    await graph.refreshSweptDocuments(params);
+                });
+                return;
+            }
+            const { nowMS, ttlMS } = params;
+            let query = db.selectFrom('kubun_graph_swept_documents').selectAll().orderBy('document_id');
+            if (params.modelID != null) query = query.where('model_id', '=', params.modelID);
+            const rows = await query.execute();
+            if (rows.length === 0) return;
+            const retaining = await retainingRules(nowMS);
+            const checks = {
+                mayRead: memoisedReadCheck(),
+                interfaces: memoisedInterfaces()
+            };
+            const entered = [];
+            const left = [];
+            const expired = [];
+            for (const row of rows){
+                const matching = (await sweptRetainingCatalogs({
+                    entry: sweptFromRow(row),
+                    nowMS,
+                    retaining,
+                    checks
+                })).length > 0;
+                const wasMatching = Number(row.in_scope) === 1;
+                if (matching !== wasMatching) (matching ? entered : left).push(row.document_id);
+                else if (!matching && ttlMS != null && Number(row.scope_left_at) + ttlMS <= nowMS) expired.push(row.document_id);
+            }
+            for (const chunk of chunked(entered))await db.updateTable('kubun_graph_swept_documents').set({
+                in_scope: 1
+            }).where('document_id', 'in', chunk).execute();
+            for (const chunk of chunked(left))await db.updateTable('kubun_graph_swept_documents').set({
+                in_scope: 0,
+                scope_left_at: nowMS
+            }).where('document_id', 'in', chunk).execute();
+            for (const chunk of chunked(expired))await db.deleteFrom('kubun_graph_swept_documents').where('document_id', 'in', chunk).execute();
+            // Read back as an availability change by whoever emits scope events.
+            await recordScopeChanges([
+                ...entered,
+                ...left
+            ]);
+            if (entered.length + left.length > 0) context.provider.onCommit(()=>notifyScopeListeners(context));
+        },
+        async documentNeedsBytes (documentID) {
+            const doc = await api.getDocument(documentID);
+            if (doc?.data == null) return false;
+            const rows = await db.selectFrom('kubun_graph_document_refs').select([
+                'ref',
+                'displays',
+                'retains'
+            ]).where('document_id', '=', documentID).execute();
+            return await refsNeedBytes(rows);
+        },
+        async countCatalogDocuments (ref) {
+            const holders = await catalogRefHolders(ref);
+            return new Set(holders.map((holder)=>holder.document_id)).size;
+        },
+        async recomputeDocumentRefs (params) {
+            const { documentID, routeRules, nowMS = Date.now(), catalog } = params;
+            if (context.provider === context.root) {
+                return await context.root.withTransaction(async (tx)=>(await tx.getStore('graph')).recomputeDocumentRefs({
+                        ...params,
+                        nowMS
+                    }));
+            }
+            await lockDocumentRefs([
+                documentID
+            ]);
+            const release = params.releaseCustodyPins;
+            const released = new Set(release != null && release.refs.length > 0 && await release.confirm() ? release.refs : []);
+            const effectiveRouteRules = routeRules.length === 0 ? await context.getCatalogRouteRules(nowMS, catalog) : routeRules;
+            const present = await recomputeRefsWith({
+                documentID,
+                routeRules: effectiveRouteRules,
+                nowMS,
+                catalog,
+                released
+            }, directRecomputeInputs(nowMS, catalog));
+            if (!present) return {
+                scope: 'outOfScope',
+                retained: false,
+                refs: []
+            };
+            return await api.getDocumentScope(documentID);
+        },
+        async sweepDocument (params) {
+            if (context.provider === context.root) {
+                return await context.root.withTransaction(async (tx)=>(await tx.getStore('graph')).sweepDocument(params));
+            }
+            const { documentID, nowMS } = params;
+            const modelID = DocumentID.fromString(documentID).model.toString();
+            // The row first, as an apply takes it before the ref lock.
+            if (!await api.lockDocumentRow(documentID)) return {
+                swept: false,
+                refusal: 'absent'
+            };
+            await lockDocumentRefs([
+                documentID
+            ]);
+            // Stored refs can be stale (an expired hold, a rule now matching): decide from fresh ones.
+            const scope = await api.recomputeDocumentRefs({
+                documentID,
+                routeRules: [],
+                nowMS
+            });
+            if (scope.retained) return {
+                swept: false,
+                refusal: 'retained'
+            };
+            if ((await api.listDocumentHolds(documentID, nowMS)).length > 0) return {
+                swept: false,
+                refusal: 'held'
+            };
+            const mark = await api.getGCMark(documentID);
+            if (mark == null) return {
+                swept: false,
+                refusal: 'unmarked'
+            };
+            if (mark.digest !== await mutationDigest(documentID)) return {
+                swept: false,
+                refusal: 'changed'
+            };
+            if (!gcMarkPastGrace(mark, params.graceMS, nowMS)) return {
+                swept: false,
+                refusal: 'grace'
+            };
+            // Inbound history no receipt covered.
+            const pending = await db.selectFrom('kubun_graph_mutation_log').select('mutation_hash').where('document_id', '=', documentID).where('status', '=', 'pending').limit(1).executeTakeFirst();
+            if (pending != null) return {
+                swept: false,
+                refusal: 'pending'
+            };
+            if (!await params.confirm(context.provider)) return {
+                swept: false,
+                refusal: 'unconfirmed'
+            };
+            const swept = await api.getDocument(documentID);
+            // A tombstone leaves nothing to restore.
+            if (swept?.data != null) await writeSweptDocument(swept, mark.digest, nowMS);
+            await unindexDocument(modelID, documentID);
+            await db.deleteFrom(`k_${modelID}`).where('id', '=', documentID).execute();
+            for (const table of [
+                'kubun_graph_mutation_log',
+                'kubun_graph_document_refs',
+                'kubun_graph_document_scope_dates',
+                'kubun_graph_gc_marks',
+                'kubun_graph_custody_receipts',
+                // No live hold is left: it would have retained the document.
+                'kubun_graph_document_holds'
+            ]){
+                await db.deleteFrom(table).where('document_id', '=', documentID).execute();
+            }
+            // Bumped, not removed: a copy still displayed leaves the view through the scope event.
+            await recordScopeChange(documentID);
+            context.provider.onCommit(()=>notifyScopeListeners(context));
+            return {
+                swept: true
+            };
+        },
+        async releaseCustodyPinRef (params) {
+            if (context.provider === context.root) {
+                return await context.root.withTransaction(async (tx)=>(await tx.getStore('graph')).releaseCustodyPinRef(params));
+            }
+            if (!isCustodyPinRef(params.ref)) return 0;
+            // One exclusive key, as bulk ref writers take it: no per-document lock entry per pin.
+            await lockAllDocumentRefs();
+            const documentIDs = await db.selectFrom('kubun_graph_document_refs').select('document_id').where('ref', '=', params.ref).orderBy('document_id').execute();
+            await recomputeDocumentRefsBatch({
+                documentIDs: documentIDs.map((row)=>row.document_id),
+                routeRules: [],
+                nowMS: params.nowMS,
+                releaseCustodyPins: {
+                    refs: [
+                        params.ref
+                    ],
+                    confirm: async ()=>true
+                }
+            });
+            return documentIDs.length;
+        },
+        async catalogRulesMatchDocument (params) {
+            const use = await db.selectFrom('kubun_graph_catalog_use').select('rules').where('owner_did', '=', params.catalog.owner).where('catalog_id', '=', params.catalog.id).executeTakeFirst();
+            if (use == null) return false;
+            const rules = typeof use.rules === 'string' ? JSON.parse(use.rules) : use.rules;
+            if (rules.length === 0) return false;
+            const doc = await api.getDocument(params.documentID);
+            if (doc == null) return false;
+            const interfaces = await api.getModelInterfaces(doc.model);
+            return rules.some((rule)=>scopeRuleMatches(rule, doc, params.nowMS, interfaces));
+        },
+        async lockDocumentRow (documentID) {
+            if (context.provider === context.root) throw new DocumentLockRequiresTransactionError();
+            const modelID = DocumentID.fromString(documentID).model.toString();
+            const row = db.selectFrom(`k_${modelID}`).select('id').where('id', '=', documentID);
+            const locked = await (adapter instanceof AbstractPostgresAdapter ? row.forUpdate() : row).executeTakeFirst().catch((err)=>{
+                if (isMissingTableError(err, `k_${modelID}`)) return undefined;
+                throw err;
+            });
+            return locked != null;
+        },
+        async settlePendingCatalogRefs (nowMS) {
+            if (context.provider === context.root) {
+                await context.root.withTransaction(async (tx)=>{
+                    await (await tx.getStore('graph')).settlePendingCatalogRefs(nowMS);
+                });
+                return;
+            }
+            await settlePendingScopes(nowMS);
+        },
+        async scheduleCatalogRefReconcile () {
+            scheduleScopeModels(context, await api.listDocumentModelIDs());
+        },
+        async recomputeDocuments (params) {
+            if (context.provider === context.root) {
+                await context.root.withTransaction(async (tx)=>{
+                    await (await tx.getStore('graph')).recomputeDocuments(params);
+                });
+                return;
+            }
+            if (params.documentIDs.length === 0) return;
+            await lockAllDocumentRefs();
+            await recomputeDocumentRefsBatch({
+                documentIDs: [
+                    ...params.documentIDs
+                ],
+                routeRules: params.routeRules,
+                nowMS: params.nowMS
+            });
+        },
+        async reconcileCatalogRefs (nowMS, routeRules, catalog, options = {}) {
+            if (catalog != null && context.provider === context.root) {
+                await context.root.withTransaction(async (tx)=>{
+                    await (await tx.getStore('graph')).reconcileCatalogRefs(nowMS, routeRules, catalog);
+                });
+                return;
+            }
+            const effectiveRouteRules = routeRules.length === 0 ? await context.getCatalogRouteRules(nowMS, catalog) : routeRules;
+            if (catalog != null) {
+                await settlePendingScopes(nowMS, catalog);
+                const use = await db.selectFrom('kubun_graph_catalog_use').select([
+                    'rules',
+                    'level'
+                ]).where('owner_did', '=', catalog.owner).where('catalog_id', '=', catalog.id).executeTakeFirst();
+                const localRules = use?.level == null ? [] : typeof use.rules === 'string' ? JSON.parse(use.rules) : use.rules;
+                const rules = [
+                    ...localRules,
+                    ...effectiveRouteRules.filter((entry)=>entry.catalog.owner === catalog.owner && entry.catalog.id === catalog.id).flatMap((entry)=>entry.rules)
+                ];
+                for (const task of (await tasksForCatalog(catalog, rules))){
+                    await api.reconcileCatalogModelRefs({
+                        modelID: task.modelID,
+                        routeRules: effectiveRouteRules,
+                        nowMS,
+                        owners: task.owners,
+                        catalog
+                    });
+                }
+                return;
+            }
+            const scheduler = scopeSchedulers.get(context.root);
+            if (scheduler != null) {
+                scheduler.generation++;
+                if (scheduler.timer != null) clearTimeout(scheduler.timer);
+                scheduler.timer = null;
+                scheduler.pendingScopes.clear();
+            }
+            if (!await reconcileAll(nowMS, effectiveRouteRules, options.shouldStop ?? (()=>false))) return;
+            await db.insertInto('kubun_graph_catalog_scope_tick').values({
+                id: 1,
+                last_at: nowMS
+            }).onConflict((oc)=>oc.column('id').doUpdateSet({
+                    last_at: nowMS
+                })).execute();
+            if (scheduler != null) scheduler.failed = false;
+            if (scheduler != null) scheduler.retryDelayMS = 100;
+        },
+        async reconcileCatalogModelRefs (params) {
+            const { modelID, routeRules, nowMS, owners, catalog } = params;
+            if (context.provider === context.root) {
+                await context.root.withTransaction(async (tx)=>{
+                    await (await tx.getStore('graph')).reconcileCatalogModelRefs(params);
+                });
+                return;
+            }
+            const documentIDs = new Set();
+            if (owners == null || owners.length > 0) {
+                let query = db.selectFrom(`k_${modelID}`).select('id');
+                if (owners != null) query = query.where('owner', 'in', owners);
+                const docs = await query.execute().catch((error)=>{
+                    if (isMissingTableError(error, `k_${modelID}`)) return [];
+                    throw error;
+                });
+                for (const doc of docs)documentIDs.add(doc.id);
+            }
+            if (catalog != null) {
+                for (const holder of (await catalogRefHolders(catalog))){
+                    if (DocumentID.fromString(holder.document_id).model.toString() === modelID) {
+                        documentIDs.add(holder.document_id);
+                    }
+                }
+            }
+            await lockAllDocumentRefs();
+            await recomputeDocumentRefsBatch({
+                documentIDs: [
+                    ...documentIDs
+                ].sort(),
+                routeRules,
+                nowMS,
+                catalog
+            });
+            // A swept document has no row to recompute: its kept facts are matched instead.
+            await api.refreshSweptDocuments({
+                nowMS,
+                modelID
+            });
+        },
+        async scheduleCustodyScan (catalog) {
+            await db.insertInto('kubun_graph_custody_scans').values({
+                owner_did: catalog.owner,
+                catalog_id: catalog.id,
+                after_document_id: null
+            }).onConflict((oc)=>oc.columns([
+                    'owner_did',
+                    'catalog_id'
+                ]).doUpdateSet({
+                    after_document_id: null
+                })).execute();
+            context.provider.onCommit(()=>context.custody?.scansQueued());
+        },
+        async advanceCustodyScan (params) {
+            if (context.provider === context.root) {
+                return await context.root.withTransaction(async (tx)=>(await tx.getStore('graph')).advanceCustodyScan(params));
+            }
+            const query = db.selectFrom('kubun_graph_custody_scans').selectAll().orderBy('owner_did').orderBy('catalog_id').limit(1);
+            // Two runners of one scan would each recompute the same batch.
+            const scan = await (adapter instanceof AbstractPostgresAdapter ? query.forUpdate() : query).executeTakeFirst();
+            if (scan == null) return false;
+            const ref = {
+                owner: scan.owner_did,
+                id: scan.catalog_id
+            };
+            const use = await db.selectFrom('kubun_graph_catalog_use').select('rules').where('owner_did', '=', ref.owner).where('catalog_id', '=', ref.id).executeTakeFirst();
+            const rules = use == null ? [] : typeof use.rules === 'string' ? JSON.parse(use.rules) : use.rules;
+            const postgres = adapter instanceof AbstractPostgresAdapter;
+            const candidates = [];
+            for (const task of rules.length === 0 ? [] : await tasksForCatalog(ref, rules)){
+                if (task.owners != null && task.owners.length === 0) continue;
+                let docs = db.selectFrom(`k_${task.modelID}`).select('id');
+                if (task.owners != null) docs = docs.where('owner', 'in', task.owners);
+                // Bytewise, so the cursor agrees with the JavaScript order below on both adapters.
+                if (scan.after_document_id != null) docs = docs.where(postgres ? sql`id collate "C" > ${scan.after_document_id}` : sql`id > ${scan.after_document_id}`);
+                const rows = await (postgres ? docs.orderBy(sql`id collate "C"`) : docs.orderBy('id')).limit(params.batchSize).execute().catch((error)=>{
+                    if (isMissingTableError(error, `k_${task.modelID}`)) return [];
+                    throw error;
+                });
+                for (const row of rows)candidates.push(row.id);
+            }
+            const batch = [
+                ...new Set(candidates)
+            ].sort((a, b)=>a < b ? -1 : a > b ? 1 : 0).slice(0, params.batchSize);
+            await recomputeDocumentRefsBatch({
+                documentIDs: batch,
+                routeRules: [],
+                nowMS: params.nowMS,
+                catalog: ref
+            });
+            const last = batch.at(-1);
+            const scans = db.updateTable('kubun_graph_custody_scans').where('owner_did', '=', ref.owner).where('catalog_id', '=', ref.id);
+            if (batch.length < params.batchSize || last == null) await db.deleteFrom('kubun_graph_custody_scans').where('owner_did', '=', ref.owner).where('catalog_id', '=', ref.id).execute();
+            else await scans.set({
+                after_document_id: last
+            }).execute();
+            const remaining = await db.selectFrom('kubun_graph_custody_scans').select('owner_did').limit(1).executeTakeFirst();
+            return remaining != null;
+        },
+        async runCustodyScans (options = {}) {
+            const batchSize = options.batchSize ?? 100;
+            let batches = 0;
+            while(options.maxBatches == null || batches < options.maxBatches){
+                batches++;
+                const more = await context.root.withTransaction(async (tx)=>(await tx.getStore('graph')).advanceCustodyScan({
+                        nowMS: options.nowMS ?? Date.now(),
+                        batchSize
+                    }));
+                if (!more) return true;
+            }
+            return false;
+        },
+        onScopeRecomputed (listener) {
+            const scheduler = getScopeScheduler(context);
+            scheduler.listeners.add(listener);
+            return ()=>scheduler.listeners.delete(listener);
+        },
+        async advanceCatalogAging (nowMS, routeRules) {
+            if (scopeSchedulers.get(context.root)?.failed === true) {
+                await api.reconcileCatalogRefs(nowMS, routeRules);
+                return;
+            }
+            const tick = await db.selectFrom('kubun_graph_catalog_scope_tick').select('last_at').where('id', '=', 1).executeTakeFirst();
+            if (tick == null) {
+                await api.reconcileCatalogRefs(nowMS, routeRules);
+                return;
+            }
+            const previousMS = Number(tick.last_at);
+            if (previousMS === nowMS) return;
+            const catalogs = await db.selectFrom('kubun_graph_catalog_use').select([
+                'rules'
+            ]).where('level', 'is not', null).execute();
+            const rules = catalogs.flatMap((catalog)=>typeof catalog.rules === 'string' ? JSON.parse(catalog.rules) : catalog.rules);
+            rules.push(...routeRules.flatMap((route)=>route.rules));
+            const windowedRules = rules.filter((rule)=>rule.maxAge != null || rule.maxAhead != null);
+            const modelRows = await db.selectFrom('kubun_graph_document_models').select('id').execute();
+            const interfacesOf = memoisedInterfaces();
+            const affected = new Set();
+            for (const rule of windowedRules){
+                const selectedModels = [];
+                for (const model of modelRows){
+                    const interfaces = await interfacesOf(model.id);
+                    if (rule.models == null || rule.models.some((id)=>id === model.id || interfaces.includes(id))) selectedModels.push(model.id);
+                }
+                if (selectedModels.length === 0) continue;
+                const collectRange = async (oldBound, newBound)=>{
+                    const from = Math.min(oldBound, newBound);
+                    const to = Math.max(oldBound, newBound);
+                    if (from === to) return;
+                    if (rule.dateField != null) {
+                        const rows = await db.selectFrom('kubun_graph_document_scope_dates').select('document_id').where('field', '=', rule.dateField).where('scope_date', '>=', from).where('scope_date', '<', to).execute();
+                        const selected = new Set(selectedModels);
+                        for (const row of rows){
+                            if (selected.has(DocumentID.fromString(row.document_id).model.toString())) {
+                                affected.add(row.document_id);
+                            }
+                        }
+                    } else {
+                        for (const modelID of selectedModels){
+                            const rows = await db.selectFrom(`k_${modelID}`).select('id').where('scope_date', '>=', from).where('scope_date', '<', to).execute();
+                            for (const row of rows)affected.add(row.id);
+                        }
+                    }
+                };
+                if (rule.maxAge != null) {
+                    const duration = parseScopeDuration(rule.maxAge);
+                    await collectRange(previousMS - duration, nowMS - duration);
+                }
+                if (rule.maxAhead != null) {
+                    const duration = parseScopeDuration(rule.maxAhead);
+                    await collectRange(previousMS + duration, nowMS + duration);
+                }
+            }
+            // A hold that expired keeps its ref until its document is recomputed.
+            const expiredHolds = await db.selectFrom('kubun_graph_document_holds').select('document_id').where('released_at', 'is', null).where('expires_at', '>', previousMS).where('expires_at', '<=', nowMS).execute();
+            for (const row of expiredHolds)affected.add(row.document_id);
+            const ordered = [
+                ...affected
+            ].sort();
+            if (ordered.length > 0) await lockAllDocumentRefs();
+            await recomputeDocumentRefsBatch({
+                documentIDs: ordered,
+                routeRules,
+                nowMS
+            });
+            // A swept document has no row to recompute: a window reaching it is found from its facts.
+            await api.refreshSweptDocuments({
+                nowMS
+            });
+            await db.updateTable('kubun_graph_catalog_scope_tick').set({
+                last_at: nowMS
+            }).where('id', '=', 1).execute();
         },
         async queryDocuments (params) {
-            const { catalogID, filter, modelIDs, orderBy, owner, ...pagination } = params;
+            const { catalogRef, filter, modelIDs, orderBy, owner, ...pagination } = params;
             const isReverse = params.last != null;
-            const { effectiveModelIDs, effectiveOwners } = await resolveCatalogFilter(modelIDs, catalogID);
+            const reader = await db.selectFrom('kubun_graph_scope_identity').select('id').executeTakeFirst();
+            const scopeRefs = catalogRef == null ? null : await visibleCatalogRefs(catalogRef);
+            if (catalogRef != null && scopeRefs?.length === 0) {
+                return {
+                    entries: [],
+                    hasMore: false
+                };
+            }
+            const filterScope = reader != null || catalogRef != null;
+            const effectiveModelIDs = modelIDs;
+            const effectiveOwners = undefined;
             if (effectiveModelIDs.length === 0) {
                 return {
                     entries: [],
                     hasMore: false
                 };
             }
-            const [first, ...rest] = effectiveModelIDs;
+            const first = effectiveModelIDs[0];
+            if (first == null) return {
+                entries: [],
+                hasMore: false
+            };
+            const rest = effectiveModelIDs.slice(1);
             // Tombstoned documents (data IS NULL) stay on disk for sync/CRDT but must
             // never surface in read queries.
             let query = db.selectFrom(`k_${first}`).selectAll().where('data', 'is not', null);
+            if (filterScope) query = query.where(visibleScopePredicate(first, scopeRefs));
             if (owner != null) {
                 query = query.where('owner', '=', owner);
             }
@@ -491,6 +2514,7 @@ export function createGraphStore(db, adapter) {
             for (const model of rest){
                 query = query.unionAll((eb)=>{
                     let q = eb.selectFrom(`k_${model}`).selectAll().where('data', 'is not', null);
+                    if (filterScope) q = q.where(visibleScopePredicate(model, scopeRefs));
                     if (owner != null) {
                         q = q.where('owner', '=', owner);
                     }
@@ -503,7 +2527,18 @@ export function createGraphStore(db, adapter) {
                     return q;
                 });
             }
-            const [orderedQuery, orderedFieldsPaths] = applyDocumentOrderBy(query, adapter, orderBy, isReverse);
+            // A compound SELECT only accepts result-column references in its ORDER BY (both
+            // SQLite and Postgres reject the JSON-path expressions a data-field order emits),
+            // and a WHERE added after `unionAll` binds to the first branch alone, so a keyset
+            // cursor would only filter that one table. Reading the union as a derived table
+            // lets ordering and the keyset predicate apply the single-model path's expressions
+            // to every row. This relies on every branch selecting the same column set: all
+            // model tables come from the one `createTable` in `addDocumentModel`, so the
+            // derived table has exactly the per-table columns. A field typed differently
+            // across models orders per adapter, as the JSON-extracted value: SQLite sorts
+            // numbers before text, Postgres compares the text form.
+            const source = rest.length > 0 ? db.selectFrom(query.as('k_document')).selectAll() : query;
+            const [orderedQuery, orderedFieldsPaths] = applyDocumentOrderBy(source, adapter, orderBy, isReverse);
             const [paginatedQuery, limit] = applyPagination(orderedQuery, pagination, orderBy, coerce);
             const results = await paginatedQuery.execute();
             const docs = isReverse ? results.slice(0, limit).reverse() : results.slice(0, limit);
@@ -563,12 +2598,17 @@ export function createGraphStore(db, adapter) {
             };
         },
         async aggregateDocuments (params) {
-            const { aggregates, catalogID, count, filter, modelIDs, owner, readAccess } = params;
+            const { aggregates, catalogRef, count, filter, modelIDs, owner, readAccess } = params;
             const empty = emptyAggregateValues(count, aggregates);
             // No count and no aggregate ops requested: there is nothing to select, so
             // skip the query entirely rather than build an invalid empty SELECT.
             if (!count && aggregates.length === 0) return empty;
-            const { effectiveModelIDs, effectiveOwners } = await resolveCatalogFilter(modelIDs, catalogID);
+            const scopeRefs = catalogRef == null ? null : await visibleCatalogRefs(catalogRef);
+            if (catalogRef != null && scopeRefs?.length === 0) return empty;
+            const reader = await db.selectFrom('kubun_graph_scope_identity').select('id').executeTakeFirst();
+            const filterScope = reader != null || catalogRef != null;
+            const effectiveModelIDs = modelIDs;
+            const effectiveOwners = undefined;
             if (effectiveModelIDs.length === 0) return empty;
             // Aggregate each model in its own table, then combine at the raw sum/count/min/max
             // level so interface-connection results stay correct: averages combine as Σsum /
@@ -582,6 +2622,7 @@ export function createGraphStore(db, adapter) {
                     return selections;
                 });
                 query = query.where('data', 'is not', null);
+                if (filterScope) query = query.where(visibleScopePredicate(modelID, scopeRefs));
                 if (owner != null) {
                     query = query.where('owner', '=', owner);
                 }
@@ -598,8 +2639,7 @@ export function createGraphStore(db, adapter) {
                     return await query.executeTakeFirst();
                 } catch (err) {
                     // A model whose table was never materialised contributes nothing, matching
-                    // the not-yet-materialised-table tolerance used by getDistinctOwnersForModel
-                    // and getDocumentIDsForScope in this file.
+                    // the not-yet-materialised-table tolerance used by getDocumentIDsForScope.
                     if (isMissingTableError(err, `k_${modelID}`)) return undefined;
                     throw err;
                 }
@@ -615,9 +2655,14 @@ export function createGraphStore(db, adapter) {
             return finalizeAggregateValues(count, aggregates, acc);
         },
         async groupedAggregateDocuments (params) {
-            const { aggregates, catalogID, count, filter, groupBy, having, limit, modelIDs, orderBy, owner, readAccess } = params;
-            const { effectiveModelIDs, effectiveOwners } = await resolveCatalogFilter(modelIDs, catalogID);
+            const { aggregates, catalogRef, count, filter, groupBy, having, limit, modelIDs, orderBy, owner, readAccess } = params;
+            const effectiveModelIDs = modelIDs;
+            const effectiveOwners = undefined;
             if (effectiveModelIDs.length === 0) return [];
+            const scopeRefs = catalogRef == null ? null : await visibleCatalogRefs(catalogRef);
+            if (catalogRef != null && scopeRefs?.length === 0) return [];
+            const reader = await db.selectFrom('kubun_graph_scope_identity').select('id').executeTakeFirst();
+            const filterScope = reader != null || catalogRef != null;
             // Run the same GROUP BY query per model table in parallel, tolerating tables
             // that were never materialised (they contribute nothing), mirroring the
             // multi-model fan-out in aggregateDocuments.
@@ -636,6 +2681,7 @@ export function createGraphStore(db, adapter) {
                 });
                 query = query.groupBy((eb)=>applyGroupBySelections(eb, groupBy).expressions);
                 query = query.where('data', 'is not', null);
+                if (filterScope) query = query.where(visibleScopePredicate(modelID, scopeRefs));
                 if (owner != null) {
                     query = query.where('owner', '=', owner);
                 }
@@ -715,31 +2761,169 @@ export function createGraphStore(db, adapter) {
             const models = await db.selectFrom('kubun_graph_document_models').select('id').execute();
             return models.map((m)=>m.id);
         },
-        async getDistinctOwnersForModel (modelID) {
-            try {
-                const result = await db.selectFrom(`k_${modelID}`).select('owner').distinct().execute();
-                return result.map((r)=>r.owner);
-            } catch (err) {
-                if (isMissingTableError(err, `k_${modelID}`)) return [];
-                throw err;
-            }
-        },
         async queryDocumentsByOwner (modelID, ownerDID) {
             const docs = await db.selectFrom(`k_${modelID}`).selectAll().where('owner', '=', ownerDID).execute();
             return docs.map((doc)=>documentNodeFromTable(adapter, doc));
         },
         // --- Mutation log ---
         async insertMutationLogEntry (entry) {
-            await db.insertInto('kubun_graph_mutation_log').values(entry).onConflict((oc)=>oc.doNothing()).execute();
+            if (!context.provider.isTransactionBound) {
+                await context.provider.withTransaction(async (tx)=>{
+                    const graph = await tx.getStore('graph');
+                    await graph.insertMutationLogEntry(entry);
+                });
+                return;
+            }
+            const inserted = await db.insertInto('kubun_graph_mutation_log').values(entry).onConflict((oc)=>entry.status === 'applied' ? oc.column('mutation_hash').doUpdateSet({
+                    status: 'applied',
+                    next_attempt_at: null
+                }).where((eb)=>eb(eb.ref('kubun_graph_mutation_log.status'), '!=', 'applied')) : oc.doNothing()).returning('document_id').execute();
+            if (inserted[0] != null && entry.status === 'applied') {
+                await refreshDocumentDates(inserted[0].document_id);
+                await api.recomputeDocumentRefs({
+                    documentID: inserted[0].document_id,
+                    routeRules: []
+                });
+            }
+        },
+        async parkPushedMutation (entry) {
+            if (!context.provider.isTransactionBound) {
+                return await context.provider.withTransaction(async (tx)=>{
+                    const graph = await tx.getStore('graph');
+                    return await graph.parkPushedMutation(entry);
+                });
+            }
+            await db.insertInto('kubun_graph_pending_groups').values({
+                group_id: entry.arrival_group_id
+            }).onConflict((oc)=>oc.column('group_id').doUpdateSet({
+                    group_id: entry.arrival_group_id
+                })).execute();
+            const parkedAt = Date.now();
+            await expirePushedMutations(parkedAt, entry.arrival_group_id);
+            const inserted = await db.insertInto('kubun_graph_mutation_log').columns([
+                'mutation_hash',
+                'model_id',
+                'document_id',
+                'author_did',
+                'hlc',
+                'mutation_jwt',
+                'status',
+                'arrival_group_id',
+                'sender_peer_did',
+                'parked_at'
+            ]).expression(db.selectNoFrom((eb)=>[
+                    eb.val(entry.mutation_hash).as('mutation_hash'),
+                    eb.val(entry.model_id).as('model_id'),
+                    eb.val(entry.document_id).as('document_id'),
+                    eb.val(entry.author_did).as('author_did'),
+                    eb.val(entry.hlc).as('hlc'),
+                    eb.val(entry.mutation_jwt).as('mutation_jwt'),
+                    eb.val('pending').as('status'),
+                    eb.val(entry.arrival_group_id).as('arrival_group_id'),
+                    eb.val(entry.sender_peer_did).as('sender_peer_did'),
+                    eb.val(parkedAt).as('parked_at')
+                ]).where((eb)=>eb(eb.selectFrom('kubun_graph_mutation_log').select((count)=>count.fn.countAll().as('count')).where('status', '=', 'pending').where('arrival_group_id', '=', entry.arrival_group_id), '<', 1000)).where((eb)=>eb(eb.selectFrom('kubun_graph_mutation_log').select((count)=>count.fn.countAll().as('count')).where('status', '=', 'pending').where('arrival_group_id', '=', entry.arrival_group_id).where('sender_peer_did', '=', entry.sender_peer_did), '<', 100))).onConflict((oc)=>oc.doNothing()).returning('mutation_hash').execute();
+            if (inserted.length > 0) return 'parked';
+            return await api.hasMutationHash(entry.mutation_hash) ? 'duplicate' : 'full';
         },
         async hasMutationHash (hash) {
             const row = await db.selectFrom('kubun_graph_mutation_log').select('mutation_hash').where('mutation_hash', '=', hash).executeTakeFirst();
             return row != null;
         },
         async updateMutationStatus (mutationHash, status) {
-            await db.updateTable('kubun_graph_mutation_log').set({
+            if (context.provider === context.root) {
+                await context.root.withTransaction(async (tx)=>{
+                    await (await tx.getStore('graph')).updateMutationStatus(mutationHash, status);
+                });
+                return;
+            }
+            const updated = await db.updateTable('kubun_graph_mutation_log').set({
                 status
-            }).where('mutation_hash', '=', mutationHash).execute();
+            }).where('mutation_hash', '=', mutationHash).returning('document_id').execute();
+            if (updated[0] != null) {
+                await refreshDocumentDates(updated[0].document_id);
+                await api.recomputeDocumentRefs({
+                    documentID: updated[0].document_id,
+                    routeRules: []
+                });
+            }
+        },
+        async getDuePendingMutations (now) {
+            if (!context.provider.isTransactionBound) {
+                return await context.provider.withTransaction(async (tx)=>{
+                    const graph = await tx.getStore('graph');
+                    return await graph.getDuePendingMutations(now);
+                });
+            }
+            await expirePushedMutations(now);
+            const models = await db.selectFrom('kubun_graph_document_models').select('id').execute();
+            if (models.length === 0) return [];
+            return await db.selectFrom('kubun_graph_mutation_log').selectAll().where('status', '=', 'pending').where((eb)=>eb.or([
+                    eb('next_attempt_at', 'is', null),
+                    eb('next_attempt_at', '<=', now)
+                ])).where((eb)=>eb.or(models.map(({ id })=>eb.and([
+                        eb('model_id', '=', id),
+                        eb.exists(eb.selectFrom(`k_${id} as k_`).select('id').whereRef('k_.id', '=', 'kubun_graph_mutation_log.document_id'))
+                    ])))).orderBy('hlc', 'asc').limit(100).execute();
+        },
+        async getNextPendingAttemptAt () {
+            if (!context.provider.isTransactionBound) {
+                return await context.provider.withTransaction(async (tx)=>{
+                    const graph = await tx.getStore('graph');
+                    return await graph.getNextPendingAttemptAt();
+                });
+            }
+            const now = Date.now();
+            await expirePushedMutations(now);
+            const expiry = await db.selectFrom('kubun_graph_mutation_log').select('parked_at').where('status', '=', 'pending').where('arrival_group_id', 'is not', null).where('parked_at', 'is not', null).orderBy('parked_at', 'asc').limit(1).executeTakeFirst();
+            const expiresAt = expiry?.parked_at == null ? null : Number(expiry.parked_at) + pendingLifetimeMS;
+            const models = await db.selectFrom('kubun_graph_document_models').select('id').execute();
+            if (models.length === 0) return expiresAt;
+            const row = await db.selectFrom('kubun_graph_mutation_log').select('next_attempt_at').where('status', '=', 'pending').where('next_attempt_at', 'is not', null).where((eb)=>eb.or(models.map(({ id })=>eb.and([
+                        eb('model_id', '=', id),
+                        eb.exists(eb.selectFrom(`k_${id} as k_`).select('id').whereRef('k_.id', '=', 'kubun_graph_mutation_log.document_id'))
+                    ])))).orderBy('next_attempt_at', 'asc').limit(1).executeTakeFirst();
+            const nextAttemptAt = row?.next_attempt_at == null ? null : Number(row.next_attempt_at);
+            if (nextAttemptAt == null) return expiresAt;
+            return expiresAt == null ? nextAttemptAt : Math.min(nextAttemptAt, expiresAt);
+        },
+        async recordPendingMutationAttempt (params) {
+            const { mutationHash, outcome, now, jitter } = params;
+            if (context.provider === context.root) {
+                await context.root.withTransaction(async (tx)=>{
+                    const graph = await tx.getStore('graph');
+                    await graph.recordPendingMutationAttempt(params);
+                });
+                return;
+            }
+            // Successful apply already promoted the row; stale failures may only touch pending rows.
+            const statuses = outcome === 'applied' ? [
+                'pending',
+                'applied'
+            ] : [
+                'pending'
+            ];
+            const row = await db.selectFrom('kubun_graph_mutation_log').select([
+                'attempt_count',
+                'document_id',
+                'status'
+            ]).where('mutation_hash', '=', mutationHash).where('status', 'in', statuses).executeTakeFirst();
+            if (row == null) return;
+            const count = row.attempt_count + 1;
+            const delay = Math.min(60_000, 100 * 2 ** Math.min(count - 1, 10) * (1 + 0.25 * jitter));
+            const updated = await db.updateTable('kubun_graph_mutation_log').set({
+                attempt_count: count,
+                last_attempt_at: now,
+                next_attempt_at: outcome === 'transient' ? now + Math.round(delay) : null,
+                status: outcome === 'transient' ? 'pending' : outcome
+            }).where('mutation_hash', '=', mutationHash).where('status', 'in', statuses).returning('document_id').execute();
+            if (outcome === 'applied' && row.status !== 'applied' && updated.length > 0) {
+                await refreshDocumentDates(row.document_id);
+                await api.recomputeDocumentRefs({
+                    documentID: row.document_id,
+                    routeRules: []
+                });
+            }
         },
         async getMutationLogForDocuments (documentIDs) {
             if (documentIDs.length === 0) return [];
@@ -775,6 +2959,31 @@ export function createGraphStore(db, adapter) {
             }
             return values;
         },
+        async getFieldValuesMany (documentIDs) {
+            const byModel = new Map();
+            for (const documentID of documentIDs){
+                const modelID = DocumentID.fromString(documentID).model.toString();
+                const ids = byModel.get(modelID) ?? new Set();
+                ids.add(documentID);
+                byModel.set(modelID, ids);
+            }
+            const found = new Map();
+            for (const [modelID, ids] of byModel){
+                for (const chunk of chunked(ids)){
+                    const rows = await db.selectFrom(`k_${modelID}`).select([
+                        'id',
+                        'field_values'
+                    ]).where('id', 'in', chunk).execute();
+                    for (const row of rows){
+                        if (row.field_values == null) continue;
+                        const values = row.field_values;
+                        // ParseJSONResultsPlugin may have already parsed the value
+                        found.set(row.id, typeof values === 'string' ? JSON.parse(values) : values);
+                    }
+                }
+            }
+            return found;
+        },
         async updateFieldHLCs (docID, fieldHLCs, fieldValues) {
             const modelID = docID.model.toString();
             await db.updateTable(`k_${modelID}`).set({
@@ -789,6 +2998,8 @@ export function createGraphStore(db, adapter) {
         async createGraph (params) {
             const graphModelID = params.id;
             const name = params.name ?? graphModelID;
+            const recordModelIDs = Object.keys(params.record);
+            const existingModels = recordModelIDs.length === 0 ? [] : await db.selectFrom('kubun_graph_document_models').select('id').where('id', 'in', recordModelIDs).execute();
             await db.transaction().setIsolationLevel('read committed').execute(async (trx)=>{
                 const pluginConfigValue = params.pluginConfig ? adapter.encodeJSON(params.pluginConfig) : null;
                 await trx.insertInto('kubun_graph_models').values({
@@ -909,6 +3120,7 @@ export function createGraphStore(db, adapter) {
                             }))).execute();
                 }
             });
+            scheduleScopeModels(context, existingModels.map((model)=>model.id));
             return graphModelID;
         },
         async getGraph (id) {
@@ -964,7 +3176,8 @@ export function createGraphStore(db, adapter) {
         async dropSearchIndex (modelID) {
             await adapter.dropSearchIndex(db, modelID);
         },
-        async updateSearchEntry (modelID, documentID, data, fields) {
+        async updateSearchEntry (params) {
+            const { modelID, documentID, data, fields } = params;
             const fieldValues = {};
             for (const field of fields){
                 const value = extractFieldValue(data, field);
@@ -978,6 +3191,10 @@ export function createGraphStore(db, adapter) {
             await adapter.removeSearchEntry(db, modelID, documentID);
         },
         async searchDocuments (params) {
+            const reader = await db.selectFrom('kubun_graph_scope_identity').select('id').executeTakeFirst();
+            const scopeRefs = params.catalogRef == null ? null : await visibleCatalogRefs(params.catalogRef);
+            if (params.catalogRef != null && scopeRefs?.length === 0) return [];
+            const filterScope = reader != null || params.catalogRef != null;
             // Guard against querying a model with no `kubun_graph_search_models`
             // registry row: without this, a missing `fts_<model>` table surfaces
             // as a raw adapter error (e.g. "no such table") instead of a clean,
@@ -995,17 +3212,32 @@ export function createGraphStore(db, adapter) {
             const perModelLimit = params.first != null ? offset + params.first : undefined;
             const allResults = [];
             for (const modelID of params.modelIDs){
-                const hits = await adapter.searchIndex(db, {
-                    query: params.query,
-                    modelID,
-                    limit: perModelLimit ?? 50
-                });
-                for (const hit of hits){
-                    allResults.push({
-                        documentID: hit.documentID,
+                let limit = Math.max(perModelLimit ?? 50, 50);
+                while(true){
+                    const hits = await adapter.searchIndex(db, {
+                        query: params.query,
                         modelID,
-                        rank: hit.rank
+                        limit
                     });
+                    let visibleIDs = null;
+                    if (filterScope && hits.length > 0) {
+                        let refsQuery = db.selectFrom('kubun_graph_document_refs').select('document_id').where('document_id', 'in', hits.map((hit)=>hit.documentID)).where('displays', '=', 1);
+                        if (scopeRefs != null) refsQuery = refsQuery.where('ref', 'in', scopeRefs);
+                        const rows = await refsQuery.execute();
+                        visibleIDs = new Set(rows.map((row)=>row.document_id));
+                    }
+                    const visibleHits = visibleIDs == null ? hits : hits.filter((hit)=>visibleIDs.has(hit.documentID));
+                    if (visibleHits.length >= (perModelLimit ?? 50) || hits.length < limit) {
+                        for (const hit of visibleHits){
+                            allResults.push({
+                                documentID: hit.documentID,
+                                modelID,
+                                rank: hit.rank
+                            });
+                        }
+                        break;
+                    }
+                    limit *= 2;
                 }
             }
             // Sort by absolute rank descending (SQLite bm25 returns negative, PG ts_rank positive)
@@ -1015,121 +3247,6 @@ export function createGraphStore(db, adapter) {
             }
             return allResults;
         },
-        // --- Catalog operations ---
-        async createCatalog (catalog) {
-            await db.insertInto('kubun_graph_catalogs').values({
-                id: catalog.id,
-                owner_did: catalog.owner_did,
-                name: catalog.name,
-                description: catalog.description,
-                filter_criteria: adapter.encodeJSON(catalog.filter_criteria),
-                hlc: catalog.hlc,
-                // Own catalogs scope sync immediately; no discovery provenance.
-                active: 1,
-                source_group_id: null,
-                source_circle_id: null,
-                signed_token: catalog.signed_token ?? null
-            }).execute();
-        },
-        async upsertDiscoveredCatalog ({ catalog, sourceGroupID, sourceCircleID }) {
-            await db.insertInto('kubun_graph_catalogs').values({
-                id: catalog.id,
-                owner_did: catalog.owner_did,
-                name: catalog.name,
-                description: catalog.description,
-                filter_criteria: adapter.encodeJSON(catalog.filter_criteria),
-                hlc: catalog.hlc,
-                // Discovery applies no sync — the catalog arrives known, awaiting an
-                // explicit local activation decision.
-                active: 0,
-                source_group_id: sourceGroupID,
-                source_circle_id: sourceCircleID,
-                signed_token: catalog.signed_token ?? null
-            })// First-discovery-wins: an existing row (already known or locally
-            // activated) keeps its `active` flag and source columns untouched.
-            .onConflict((oc)=>oc.column('id').doNothing()).execute();
-        },
-        async setCatalogActive (id, active) {
-            await db.updateTable('kubun_graph_catalogs').set({
-                active: active ? 1 : 0,
-                updated_at: adapter.encodeTimestamp(new Date())
-            }).where('id', '=', id).execute();
-        },
-        async setCatalogsActive (ids, active) {
-            if (ids.length === 0) {
-                return;
-            }
-            await db.updateTable('kubun_graph_catalogs').set({
-                active: active ? 1 : 0,
-                updated_at: adapter.encodeTimestamp(new Date())
-            }).where('id', 'in', ids).execute();
-        },
-        async listStoredCatalogs (filter) {
-            let query = db.selectFrom('kubun_graph_catalogs').selectAll();
-            if (filter?.active === true) {
-                query = query.where('active', '=', 1);
-            } else if (filter?.active === false) {
-                query = query.where((eb)=>eb.or([
-                        eb('active', 'is', null),
-                        eb('active', '=', 0)
-                    ]));
-            }
-            return await query.execute();
-        },
-        async getCatalog (id) {
-            return await db.selectFrom('kubun_graph_catalogs').selectAll().where('id', '=', id).executeTakeFirst();
-        },
-        async getCatalogs (ids) {
-            const result = new Map();
-            if (ids.length === 0) return result;
-            const rows = await db.selectFrom('kubun_graph_catalogs').selectAll().where('id', 'in', ids).execute();
-            for (const row of rows){
-                result.set(row.id, row);
-            }
-            return result;
-        },
-        async updateCatalog (id, update) {
-            const values = {};
-            if (update.name != null) values.name = update.name;
-            if (update.description != null) values.description = update.description;
-            if (update.filter_criteria != null) {
-                values.filter_criteria = adapter.encodeJSON(update.filter_criteria);
-            }
-            if (update.hlc != null) values.hlc = update.hlc;
-            if (update.signed_token != null) values.signed_token = update.signed_token;
-            values.updated_at = adapter.encodeTimestamp(new Date());
-            await db.updateTable('kubun_graph_catalogs').set(values).where('id', '=', id).execute();
-        },
-        async deleteCatalog (id) {
-            await db.deleteFrom('kubun_graph_catalogs').where('id', '=', id).execute();
-        },
-        async listCatalogs (ownerDID) {
-            return await db.selectFrom('kubun_graph_catalogs').selectAll().where('owner_did', '=', ownerDID).execute();
-        },
-        async resolveCatalogScope (catalogID) {
-            const catalog = await api.getCatalog(catalogID);
-            if (catalog == null) {
-                return {
-                    models: undefined,
-                    owners: undefined
-                };
-            }
-            const criteria = catalog.filter_criteria;
-            const models = criteria.models != null && criteria.models.length > 0 ? criteria.models : undefined;
-            let owners;
-            if (criteria.owners != null && criteria.owners.length > 0) {
-                owners = [
-                    ...criteria.owners
-                ];
-            }
-            // Note: circle-based owner resolution is not included here because
-            // circle tables are in a separate store. Consumers should resolve
-            // circle members externally if needed.
-            return {
-                models,
-                owners
-            };
-        },
         // --- Cluster registration ---
         async registerClusterModels (_clusterID, entries) {
             if (entries.length === 0) return;
@@ -1139,6 +3256,35 @@ export function createGraphStore(db, adapter) {
                     }))).execute();
         },
         // --- User model access defaults ---
+        async hasControllerAccessDefaults (ownerDID, modelID) {
+            let query = db.selectFrom('kubun_graph_access_default_records').select('owner').where('type', '=', 'access.default').where('owner', '=', ownerDID);
+            if (modelID != null) {
+                // Prefix ranges depend on collation ordering; type and owner narrow the primary key scan.
+                const prefix = `access.default:[${JSON.stringify(modelID)},`;
+                query = query.where(sql`substr(id, 1, ${Array.from(prefix).length}) = ${prefix}`);
+            }
+            return await query.limit(1).executeTakeFirst() != null;
+        },
+        async invalidateAccessDefaultProjections (ownerDID) {
+            if (context.provider === context.root) {
+                return context.root.withTransaction(async (tx)=>(await tx.getStore('graph')).invalidateAccessDefaultProjections(ownerDID));
+            }
+            let ownersQuery = db.selectFrom('kubun_graph_access_default_records').where('type', '=', 'access.default').select('owner').distinct();
+            if (ownerDID != null) ownersQuery = ownersQuery.where('owner', '=', ownerDID);
+            const owners = (await ownersQuery.execute()).map(({ owner })=>owner);
+            if (owners.length === 0) return;
+            await api.accessDefaultRecords().lock?.(owners.map((owner)=>({
+                    type: 'access.default',
+                    key: `!projection:${owner}`
+                })));
+            const rows = await db.selectFrom('kubun_graph_user_model_access_defaults').select([
+                'model_id',
+                'permission_type'
+            ]).where('owner_did', 'in', owners).execute();
+            // Signed slots survive invalidation so a successful repair can restore the winner.
+            await db.deleteFrom('kubun_graph_user_model_access_defaults').where('owner_did', 'in', owners).execute();
+            scheduleScopeModels(context, rows.filter((row)=>row.permission_type === 'read').map((row)=>row.model_id));
+        },
         async getUserModelAccessDefault (ownerDID, modelID, permissionType) {
             const result = await db.selectFrom('kubun_graph_user_model_access_defaults').select([
                 'access_level',
@@ -1216,8 +3362,14 @@ export function createGraphStore(db, adapter) {
                     'permission_type'
                 ]).doUpdateSet(updateValues);
             }).execute();
+            if (params.permissionType === 'read') {
+                scheduleScopeModels(context, [
+                    params.modelID
+                ]);
+            }
         },
-        async removeUserModelAccessDefaults (ownerDID, modelID, permissionTypes, hlc) {
+        async removeUserModelAccessDefaults (params) {
+            const { ownerDID, modelID, permissionTypes, hlc } = params;
             // Tombstone rather than delete: retain the row with rule fields nulled,
             // `removed` set, and `hlc` stamped so it stays the LWW anchor. Deleting
             // would erase the anchor and let a stale set revive the rule.
@@ -1259,9 +3411,15 @@ export function createGraphStore(db, adapter) {
                     removed: 1,
                     updated_at: updatedAt
                 })).execute();
+            if (permissionTypes.includes('read')) {
+                scheduleScopeModels(context, [
+                    modelID
+                ]);
+            }
         },
         // --- Document scope / metadata helpers ---
-        async getDocumentIDsForScope (scopes, excludedDocumentIDs = []) {
+        async getDocumentIDsForScope (params) {
+            const { scopes, excludedDocumentIDs = [], limit, groupRead } = params;
             // Group by model so each model's table is hit once with every owner it was
             // asked for, rather than once per (model, owner) pair.
             const ownersByModel = new Map();
@@ -1275,12 +3433,12 @@ export function createGraphStore(db, adapter) {
                     owners.add(scope.ownerDID);
                 }
             }
-            // Disjoint tables, so the reads go out together. Flattened in
-            // `ownersByModel` order rather than completion order — the returned array
-            // feeds merkle-tree construction, which must not vary run to run.
-            const idsByModel = await Promise.all(Array.from(ownersByModel, async ([modelID, owners])=>{
+            const readModel = async (modelID, owners, modelLimit)=>{
                 try {
-                    const docs = await db.selectFrom(`k_${modelID}`).select('id').where('owner', 'in', Array.from(owners)).execute();
+                    let query = db.selectFrom(`k_${modelID}`).select('id').where('owner', 'in', Array.from(owners));
+                    if (groupRead != null) query = query.where(adapter.groupReadPredicate(sql.ref('field_values'), groupRead));
+                    if (modelLimit != null) query = query.limit(modelLimit);
+                    const docs = await query.execute();
                     return docs.map((d)=>d.id);
                 } catch (err) {
                     // A model with no table contributes nothing — one missing table
@@ -1288,7 +3446,24 @@ export function createGraphStore(db, adapter) {
                     if (!isMissingTableError(err, `k_${modelID}`)) throw err;
                     return [];
                 }
-            }));
+            };
+            let idsByModel;
+            if (limit == null) {
+                // Disjoint tables, so the reads go out together. Flattened in
+                // `ownersByModel` order rather than completion order — the returned array
+                // feeds merkle-tree construction, which must not vary run to run.
+                idsByModel = await Promise.all(Array.from(ownersByModel, ([modelID, owners])=>readModel(modelID, owners)));
+            } else {
+                // A total limit: each model reads only what is left of it.
+                idsByModel = [];
+                let remaining = limit;
+                for (const [modelID, owners] of ownersByModel){
+                    if (remaining <= 0) break;
+                    const ids = await readModel(modelID, owners, remaining);
+                    idsByModel.push(ids);
+                    remaining -= ids.length;
+                }
+            }
             const docIDs = idsByModel.flat();
             if (excludedDocumentIDs.length > 0) {
                 const excluded = new Set(excludedDocumentIDs);
@@ -1296,6 +3471,70 @@ export function createGraphStore(db, adapter) {
             }
             return docIDs;
         },
+        async listDocumentLeafPage (params) {
+            if (params.limit <= 0 || params.rules.length === 0) return [];
+            const rulesByModel = new Map();
+            for (const rule of params.rules){
+                const rules = rulesByModel.get(rule.modelID);
+                if (rules == null) rulesByModel.set(rule.modelID, [
+                    rule
+                ]);
+                else rules.push(rule);
+            }
+            const postgres = adapter instanceof AbstractPostgresAdapter;
+            const leaves = [];
+            for (const [modelID, rules] of rulesByModel){
+                let rows;
+                try {
+                    rows = (await documentLeafPageStatement({
+                        modelID,
+                        rules,
+                        after: params.after,
+                        through: params.through ?? null,
+                        limit: params.limit,
+                        postgres,
+                        ...params.groupRead == null ? {} : {
+                            groupReadPredicate: adapter.groupReadPredicate(sql.ref('k.field_values'), params.groupRead)
+                        }
+                    }).execute(db)).rows;
+                } catch (err) {
+                    if (!isMissingTableError(err, `k_${modelID}`)) throw err;
+                    continue;
+                }
+                let current;
+                for (const row of rows){
+                    if (current == null || current.documentID !== row.id) {
+                        current = {
+                            documentID: row.id,
+                            owner: row.owner,
+                            authoredHere: row.authored_here === true || Number(row.authored_here) === 1,
+                            acceptedMutationIDs: []
+                        };
+                        leaves.push(current);
+                    }
+                    if (row.mutation_hash != null) current.acceptedMutationIDs.push(row.mutation_hash);
+                }
+            }
+            leaves.sort((a, b)=>a.documentID < b.documentID ? -1 : a.documentID > b.documentID ? 1 : 0);
+            const page = leaves.slice(0, params.limit);
+            for (const leaf of page)leaf.acceptedMutationIDs.sort();
+            return page;
+        },
+        async getAppliedMutationsForDocuments (documentIDs) {
+            const found = new Map();
+            for (const chunk of chunked(documentIDs)){
+                const rows = await db.selectFrom('kubun_graph_mutation_log').selectAll().where('document_id', 'in', chunk).where('status', '=', 'applied').orderBy('hlc', 'asc').execute();
+                for (const row of rows){
+                    const entries = found.get(row.document_id) ?? [];
+                    entries.push(row);
+                    found.set(row.document_id, entries);
+                }
+            }
+            return found;
+        },
+        async getAppliedMutations (documentID) {
+            return await db.selectFrom('kubun_graph_mutation_log').selectAll().where('document_id', '=', documentID).where('status', '=', 'applied').orderBy('hlc', 'asc').execute();
+        },
         async getDocumentMetadataForSync (modelID, documentIDs) {
             if (documentIDs.length === 0) return [];
             const rows = await db.selectFrom(`k_${modelID}`).select([