@kubun/store-graph 0.11.0 → 0.13.0

package/lib/api.d.ts

@@ -12,8 +12,36 @@ export type StoredAccessRule = {
     allowedCircles: Array<string> | null;
     allowedGroups: Array<string> | null;
 };
+/**
+ * A single stored access-default row, tagged with the model and permission
+ * type it belongs to. Returned by `listUserModelAccessDefaults`, which -
+ * unlike `getUserModelAccessDefault` - is not scoped to one (model,
+ * permissionType) pair.
+ */
+export type StoredAccessDefaultRow = StoredAccessRule & {
+    modelID: string;
+    permissionType: 'read' | 'write';
+    /**
+     * The row's LWW anchor, or null when written without a stamp. Carried here so
+     * a caller needing rule + anchor for several models reads one list rather than
+     * a `getUserModelAccessDefault` / `getUserModelAccessDefaultHLC` pair each.
+     */
+    hlc: string | null;
+};
 export type GraphStoreAPI = {
     getDocument(id: DocumentID | string): Promise<DocumentNode | null>;
+    /**
+     * Batch fetch documents, returning a Map keyed by the document ID string. A
+     * missing id is absent from the map, exactly as `getDocument` returning `null`.
+     *
+     * Documents live in a per-model table, so the reads are grouped by model and
+     * cost one query per DISTINCT model rather than one per id. A model with no
+     * table contributes nothing, matching `getDocument`'s behaviour for an id whose
+     * model was never deployed. Empty input short-circuits with no SQL.
+     *
+     * Caller is responsible for deduplicating ids.
+     */
+    getDocuments(ids: Array<DocumentID | string>): Promise<Map<string, DocumentNode>>;
     getDocumentModel(id: DocumentModelID | string): Promise<DocumentModel>;
     /**
      * Return the interface model IDs declared by `modelID` from the
@@ -61,7 +89,30 @@ export type GraphStoreAPI = {
     updateSearchEntry(modelID: string, documentID: string, data: Record<string, unknown>, fields: Array<string>): Promise<void>;
     removeSearchEntry(modelID: string, documentID: string): Promise<void>;
     searchDocuments(params: SearchDocumentsParams): Promise<Array<SearchDocumentResult>>;
+    /** Create an own catalog: stored active (scopes sync) with null provenance. */
     createCatalog(catalog: InsertCatalog): Promise<void>;
+    /**
+     * Insert a discovered catalog as known (not active) with first-discovery
+     * provenance. Idempotent on the id: an already-stored catalog is left
+     * untouched, so its local `active` flag and first-discovery source columns
+     * are never overwritten by a later re-discovery.
+     */
+    upsertDiscoveredCatalog(params: {
+        catalog: InsertCatalog;
+        sourceGroupID: string | null;
+        sourceCircleID: string | null;
+    }): Promise<void>;
+    /** Toggle a catalog's local sync activation. */
+    setCatalogActive(id: string, active: boolean): Promise<void>;
+    /** Flip several catalogs together — one statement, not one per id. */
+    setCatalogsActive(ids: Array<string>, active: boolean): Promise<void>;
+    /**
+     * All locally-stored catalog rows regardless of owner, optionally filtered by
+     * activation state. Backs the viewer's known-catalogs surface.
+     */
+    listStoredCatalogs(filter?: {
+        active?: boolean;
+    }): Promise<Array<Catalog>>;
     getCatalog(id: string): Promise<Catalog | undefined>;
     /**
      * Batch fetch catalogs by ID. Returns a Map keyed by ID; missing IDs are
@@ -71,7 +122,7 @@ export type GraphStoreAPI = {
      * Caller is responsible for deduplicating IDs (e.g. via `Array.from(new Set(...))`).
      */
     getCatalogs(ids: Array<string>): Promise<Map<string, Catalog>>;
-    updateCatalog(id: string, update: Partial<Pick<InsertCatalog, 'name' | 'description' | 'filter_criteria' | 'hlc'>>): Promise<void>;
+    updateCatalog(id: string, update: Partial<Pick<InsertCatalog, 'name' | 'description' | 'filter_criteria' | 'hlc' | 'signed_token'>>): Promise<void>;
     deleteCatalog(id: string): Promise<void>;
     listCatalogs(ownerDID: string): Promise<Array<Catalog>>;
     resolveCatalogScope(catalogID: string): Promise<{
@@ -79,7 +130,22 @@ export type GraphStoreAPI = {
         owners: Array<string> | undefined;
     }>;
     registerClusterModels(clusterID: string, entries: Array<InsertClusterModel>): Promise<void>;
+    /** A tombstoned (removed) rule reads as absent. */
     getUserModelAccessDefault(ownerDID: string, modelID: string, permissionType: 'read' | 'write'): Promise<StoredAccessRule | null>;
+    /**
+     * All active stored access-default rows for `ownerDID`, across every model and
+     * permission type. Tombstoned (removed) rows are excluded. Bounded by the
+     * owner's model count, no pagination.
+     */
+    listUserModelAccessDefaults(ownerDID: string): Promise<Array<StoredAccessDefaultRow>>;
+    /**
+     * The LWW anchor (`hlc`) stamped on a stored rule, or null when the rule is
+     * absent or was written without a stamp (a legacy or unsynced local policy).
+     * A caller applying a replicated rule reads this to reject an older write.
+     * A tombstoned row keeps its anchor: this returns the removal's `hlc` so a
+     * stale set arriving after the remove is still rejected.
+     */
+    getUserModelAccessDefaultHLC(ownerDID: string, modelID: string, permissionType: 'read' | 'write'): Promise<string | null>;
     setUserModelAccessDefault(params: {
         ownerDID: string;
         modelID: string;
@@ -88,8 +154,21 @@ export type GraphStoreAPI = {
         allowedDIDs: Array<string> | null;
         allowedCircles: Array<string> | null;
         allowedGroups: Array<string> | null;
+        /** LWW anchor. Omitted by callers that do not participate in replication. */
+        hlc?: string;
     }): Promise<void>;
-    removeUserModelAccessDefaults(ownerDID: string, modelID: string, permissionTypes: Array<string>): Promise<void>;
+    /**
+     * Tombstone the given permission types: retain each row with its rule fields
+     * nulled, `removed` set, and `hlc` stamped as the LWW anchor. The row is kept
+     * (not deleted) so a stale set arriving after the removal is rejected by HLC.
+     * A type with no existing row is skipped (nothing to tombstone).
+     */
+    removeUserModelAccessDefaults(ownerDID: string, modelID: string, permissionTypes: Array<string>, hlc: string): Promise<void>;
+    /**
+     * Document IDs across every scope, one query per distinct model. Repeating a
+     * (model, owner) pair yields its documents once — the result is a set, and the
+     * caller builds a Merkle tree from it, where a duplicate would be a defect.
+     */
     getDocumentIDsForScope(scopes: Array<{
         modelID: string;
         ownerDID: string;

package/lib/api.js

@@ -1,12 +1,6 @@
 import { DocumentID, DocumentModelID } from '@kubun/id';
 import { serializeCursor } from './cursor.js';
-function isMissingTableError(err, tableName) {
-    if (!(err instanceof Error)) return false;
-    const message = err.message;
-    // SQLite: "no such table: k_<modelID>"
-    // Postgres: `relation "k_<modelID>" does not exist`
-    return message.includes('no such table') && message.includes(tableName) || message.includes('does not exist') && message.includes(tableName);
-}
+import { isMissingTableError, ModelNotDeployedError } from './errors.js';
 import { aggregateFieldName, applyAggregateSelections, applyDocumentFilter, applyDocumentOrderBy, applyGroupBySelections, applyPagination, groupKeyAlias, knownFieldColumn } from './query-builder.js';
 // --- Helper functions ---
 // SQL numeric results round-trip as strings on some adapters (Postgres `numeric`/`sum`),
@@ -352,9 +346,62 @@ export function createGraphStore(db, adapter) {
         // --- Document operations ---
         async getDocument (id) {
             const parsedID = DocumentID.from(id);
-            const doc = await db.selectFrom(`k_${parsedID.model.toString()}`).selectAll().where('id', '=', parsedID.toString()).executeTakeFirst();
+            const modelID = parsedID.model.toString();
+            const doc = await db.selectFrom(`k_${modelID}`).selectAll().where('id', '=', parsedID.toString()).executeTakeFirst().catch((err)=>{
+                // A single-document read names its model, so an undeployed one is a
+                // distinct answer from an absent document and not an empty result:
+                // the id may well exist on a peer that holds the model.
+                if (isMissingTableError(err, `k_${modelID}`)) {
+                    throw new ModelNotDeployedError(modelID, {
+                        cause: err
+                    });
+                }
+                throw err;
+            });
             return doc ? documentNodeFromTable(adapter, doc) : null;
         },
+        async getDocuments (ids) {
+            const result = new Map();
+            if (ids.length === 0) return result;
+            // Group by model so each model's table is read once with every id asked
+            // for, rather than once per id.
+            const idsByModel = new Map();
+            for (const id of ids){
+                const parsedID = DocumentID.from(id);
+                const modelID = parsedID.model.toString();
+                const modelIDs = idsByModel.get(modelID);
+                if (modelIDs == null) {
+                    idsByModel.set(modelID, [
+                        parsedID.toString()
+                    ]);
+                } else {
+                    modelIDs.push(parsedID.toString());
+                }
+            }
+            // One read per model, all issued together: they touch disjoint tables, so
+            // a pooled adapter overlaps them and a serial one costs what it did. The
+            // rows are folded in `idsByModel` order afterwards, so what wins a
+            // 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();
+                } catch (err) {
+                    // A batch spans models, so one undeployed model contributes nothing
+                    // rather than failing the read for every other id asked for. The
+                    // single-id read throws `ModelNotDeployedError` instead: there, the
+                    // undeployed model is the whole answer.
+                    if (!isMissingTableError(err, `k_${modelID}`)) throw err;
+                    return [];
+                }
+            }));
+            for (const docs of rowsByModel){
+                for (const doc of docs){
+                    const node = documentNodeFromTable(adapter, doc);
+                    result.set(node.id, node);
+                }
+            }
+            return result;
+        },
         async getDocumentModel (id) {
             const row = await db.selectFrom('kubun_graph_document_models').selectAll().where('id', '=', id.toString()).executeTakeFirstOrThrow();
             return documentModelFromTable(row);
@@ -404,7 +451,7 @@ export function createGraphStore(db, adapter) {
                 query = query.where('owner', 'in', effectiveOwners);
             }
             if (filter != null) {
-                query = query.where((eb)=>applyDocumentFilter(eb, filter, [], coerce));
+                query = query.where((eb)=>applyDocumentFilter(eb, filter, adapter, [], coerce));
             }
             for (const model of rest){
                 query = query.unionAll((eb)=>{
@@ -416,7 +463,7 @@ export function createGraphStore(db, adapter) {
                         q = q.where('owner', 'in', effectiveOwners);
                     }
                     if (filter != null) {
-                        q = q.where((eb)=>applyDocumentFilter(eb, filter, [], coerce));
+                        q = q.where((eb)=>applyDocumentFilter(eb, filter, adapter, [], coerce));
                     }
                     return q;
                 });
@@ -507,7 +554,7 @@ export function createGraphStore(db, adapter) {
                     query = query.where('owner', 'in', effectiveOwners);
                 }
                 if (filter != null) {
-                    query = query.where((eb)=>applyDocumentFilter(eb, filter, [], coerce));
+                    query = query.where((eb)=>applyDocumentFilter(eb, filter, adapter, [], coerce));
                 }
                 if (readAccess != null) {
                     query = query.where(adapter.readAccessPredicate(readAccess, modelID));
@@ -561,7 +608,7 @@ export function createGraphStore(db, adapter) {
                     query = query.where('owner', 'in', effectiveOwners);
                 }
                 if (filter != null) {
-                    query = query.where((eb)=>applyDocumentFilter(eb, filter, [], coerce));
+                    query = query.where((eb)=>applyDocumentFilter(eb, filter, adapter, [], coerce));
                 }
                 if (readAccess != null) {
                     query = query.where(adapter.readAccessPredicate(readAccess, modelID));
@@ -748,6 +795,25 @@ export function createGraphStore(db, adapter) {
                         added.add(id);
                     }));
                 }
+                for (const [clusterID, cluster] of Object.entries(params.clusters ?? {})){
+                    const entries = Object.entries(cluster.models).map(([modelID, index])=>({
+                            model_id: modelID,
+                            cluster_id: clusterID,
+                            cluster_index: index
+                        }));
+                    if (entries.length > 0) {
+                        await trx.insertInto('kubun_graph_cluster_models').values(entries).onConflict((oc)=>oc.column('model_id').doUpdateSet((eb)=>({
+                                    cluster_id: eb.ref('excluded.cluster_id'),
+                                    cluster_index: eb.ref('excluded.cluster_index')
+                                }))).execute();
+                    }
+                    await trx.insertInto('kubun_graph_clusters').values({
+                        id: clusterID,
+                        definition: adapter.encodeJSON(cluster.definition)
+                    }).onConflict((oc)=>oc.column('id').doUpdateSet((eb)=>({
+                                definition: eb.ref('excluded.definition')
+                            }))).execute();
+                }
             });
             return graphModelID;
         },
@@ -852,9 +918,59 @@ export function createGraphStore(db, adapter) {
                 name: catalog.name,
                 description: catalog.description,
                 filter_criteria: adapter.encodeJSON(catalog.filter_criteria),
-                hlc: catalog.hlc
+                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();
         },
@@ -875,6 +991,7 @@ export function createGraphStore(db, adapter) {
                 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();
         },
@@ -922,9 +1039,12 @@ export function createGraphStore(db, adapter) {
                 'access_level',
                 'allowed_dids',
                 'allowed_circles',
-                'allowed_groups'
+                'allowed_groups',
+                'removed'
             ]).where('owner_did', '=', ownerDID).where('model_id', '=', modelID).where('permission_type', '=', permissionType).executeTakeFirst();
-            if (!result) {
+            // A tombstoned row reads as absent so a removed rule falls back to the
+            // server default rather than surfacing a nulled rule.
+            if (!result || result.removed) {
                 return null;
             }
             return {
@@ -934,6 +1054,33 @@ export function createGraphStore(db, adapter) {
                 allowedGroups: result.allowed_groups
             };
         },
+        async listUserModelAccessDefaults (ownerDID) {
+            const results = await db.selectFrom('kubun_graph_user_model_access_defaults').select([
+                'model_id',
+                'permission_type',
+                'access_level',
+                'allowed_dids',
+                'allowed_circles',
+                'allowed_groups',
+                'hlc',
+                'removed'
+            ]).where('owner_did', '=', ownerDID).execute();
+            return results.filter((result)=>!result.removed).map((result)=>({
+                    modelID: result.model_id,
+                    permissionType: result.permission_type,
+                    level: result.access_level,
+                    allowedDIDs: result.allowed_dids,
+                    allowedCircles: result.allowed_circles,
+                    allowedGroups: result.allowed_groups,
+                    hlc: result.hlc ?? null
+                }));
+        },
+        async getUserModelAccessDefaultHLC (ownerDID, modelID, permissionType) {
+            const result = await db.selectFrom('kubun_graph_user_model_access_defaults').select([
+                'hlc'
+            ]).where('owner_did', '=', ownerDID).where('model_id', '=', modelID).where('permission_type', '=', permissionType).executeTakeFirst();
+            return result?.hlc ?? null;
+        },
         async setUserModelAccessDefault (params) {
             await db.insertInto('kubun_graph_user_model_access_defaults').values({
                 owner_did: params.ownerDID,
@@ -942,33 +1089,102 @@ export function createGraphStore(db, adapter) {
                 access_level: params.accessLevel,
                 allowed_dids: params.allowedDIDs ? adapter.encodeJSON(params.allowedDIDs) : null,
                 allowed_circles: params.allowedCircles ? adapter.encodeJSON(params.allowedCircles) : null,
-                allowed_groups: params.allowedGroups ? adapter.encodeJSON(params.allowedGroups) : null
-            }).onConflict((oc)=>oc.columns([
-                    'owner_did',
-                    'model_id',
-                    'permission_type'
-                ]).doUpdateSet({
+                allowed_groups: params.allowedGroups ? adapter.encodeJSON(params.allowedGroups) : null,
+                hlc: params.hlc ?? null,
+                // A set clears any prior tombstone so a re-established rule reads again.
+                removed: 0
+            }).onConflict((oc)=>{
+                const updateValues = {
                     access_level: params.accessLevel,
                     allowed_dids: params.allowedDIDs ? adapter.encodeJSON(params.allowedDIDs) : null,
                     allowed_circles: params.allowedCircles ? adapter.encodeJSON(params.allowedCircles) : null,
                     allowed_groups: params.allowedGroups ? adapter.encodeJSON(params.allowedGroups) : null,
+                    removed: 0,
                     updated_at: adapter.encodeTimestamp(new Date())
-                })).execute();
+                };
+                if (params.hlc != null) {
+                    updateValues.hlc = params.hlc;
+                }
+                return oc.columns([
+                    'owner_did',
+                    'model_id',
+                    'permission_type'
+                ]).doUpdateSet(updateValues);
+            }).execute();
         },
-        async removeUserModelAccessDefaults (ownerDID, modelID, permissionTypes) {
-            await db.deleteFrom('kubun_graph_user_model_access_defaults').where('owner_did', '=', ownerDID).where('model_id', '=', modelID).where('permission_type', 'in', permissionTypes).execute();
+        async removeUserModelAccessDefaults (ownerDID, modelID, permissionTypes, hlc) {
+            // 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.
+            //
+            // Upsert rather than update-only, for the same reason. Broadcast delivery
+            // is unordered, so a removal can arrive on a device that never stored the
+            // rule it removes. An update would match no row, land no anchor, and the
+            // older `set` arriving afterwards would then apply against a null anchor —
+            // resurrecting a revoked grant. Inserting the tombstone makes the anchor
+            // land whether or not the rule was ever seen.
+            //
+            // `access_level` is a non-null column that a tombstone has no meaningful
+            // value for; a fresh tombstone stores the most restrictive level, and an
+            // existing row keeps whatever it had. Either way the `removed` marker
+            // hides it from reads.
+            if (permissionTypes.length === 0) {
+                return;
+            }
+            const updatedAt = adapter.encodeTimestamp(new Date());
+            await db.insertInto('kubun_graph_user_model_access_defaults').values(permissionTypes.map((permissionType)=>({
+                    owner_did: ownerDID,
+                    model_id: modelID,
+                    permission_type: permissionType,
+                    access_level: 'only_owner',
+                    allowed_dids: null,
+                    allowed_circles: null,
+                    allowed_groups: null,
+                    hlc,
+                    removed: 1
+                }))).onConflict((oc)=>oc.columns([
+                    'owner_did',
+                    'model_id',
+                    'permission_type'
+                ]).doUpdateSet({
+                    allowed_dids: null,
+                    allowed_circles: null,
+                    allowed_groups: null,
+                    hlc,
+                    removed: 1,
+                    updated_at: updatedAt
+                })).execute();
         },
         // --- Document scope / metadata helpers ---
         async getDocumentIDsForScope (scopes, excludedDocumentIDs = []) {
-            const docIDs = [];
+            // 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();
             for (const scope of scopes){
+                const owners = ownersByModel.get(scope.modelID);
+                if (owners == null) {
+                    ownersByModel.set(scope.modelID, new Set([
+                        scope.ownerDID
+                    ]));
+                } else {
+                    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])=>{
                 try {
-                    const docs = await db.selectFrom(`k_${scope.modelID}`).select('id').where('owner', '=', scope.ownerDID).execute();
-                    docIDs.push(...docs.map((d)=>d.id));
+                    const docs = await db.selectFrom(`k_${modelID}`).select('id').where('owner', 'in', Array.from(owners)).execute();
+                    return docs.map((d)=>d.id);
                 } catch (err) {
-                    if (!isMissingTableError(err, `k_${scope.modelID}`)) throw err;
+                    // A model with no table contributes nothing — one missing table
+                    // skips that model's whole owner set at once.
+                    if (!isMissingTableError(err, `k_${modelID}`)) throw err;
+                    return [];
                 }
-            }
+            }));
+            const docIDs = idsByModel.flat();
             if (excludedDocumentIDs.length > 0) {
                 const excluded = new Set(excludedDocumentIDs);
                 return docIDs.filter((id)=>!excluded.has(id));

package/lib/errors.d.ts

@@ -0,0 +1,34 @@
+/**
+ * True when `err` is the driver's way of saying `tableName` does not exist.
+ * Each adapter words it differently, so the match is the only place the two
+ * spellings are known.
+ */
+export declare function isMissingTableError(err: unknown, tableName: string): boolean;
+/**
+ * Thrown when a read names a document model this device never deployed. The
+ * model's table is created at deploy time, so its absence is a fact about this
+ * device rather than about the document — a peer holding the model reads the
+ * same id fine.
+ *
+ * Tagged with the protocol-level error code `KB15` so a caller branches on the
+ * class instead of matching a driver's wording, which differs per adapter. Not
+ * a permanent apply error: a model may be deployed later, so a mutation naming
+ * one stays retryable.
+ */
+export declare class ModelNotDeployedError extends Error {
+    #private;
+    constructor(modelID: string, options?: {
+        cause?: unknown;
+    });
+    get code(): 'KB15';
+    get modelID(): string;
+    /**
+     * graphql-js copies a wrapped error's `extensions` onto the error it locates,
+     * so a resolver that lets this through surfaces the code to the app without
+     * translating it at the throw site.
+     */
+    get extensions(): {
+        code: 'KB15';
+        modelID: string;
+    };
+}

package/lib/errors.js

@@ -0,0 +1,45 @@
+/**
+ * True when `err` is the driver's way of saying `tableName` does not exist.
+ * Each adapter words it differently, so the match is the only place the two
+ * spellings are known.
+ */ export function isMissingTableError(err, tableName) {
+    if (!(err instanceof Error)) return false;
+    const message = err.message;
+    // SQLite: "no such table: k_<modelID>"
+    // Postgres: `relation "k_<modelID>" does not exist`
+    return message.includes('no such table') && message.includes(tableName) || message.includes('does not exist') && message.includes(tableName);
+}
+/**
+ * Thrown when a read names a document model this device never deployed. The
+ * model's table is created at deploy time, so its absence is a fact about this
+ * device rather than about the document — a peer holding the model reads the
+ * same id fine.
+ *
+ * Tagged with the protocol-level error code `KB15` so a caller branches on the
+ * class instead of matching a driver's wording, which differs per adapter. Not
+ * a permanent apply error: a model may be deployed later, so a mutation naming
+ * one stays retryable.
+ */ export class ModelNotDeployedError extends Error {
+    #modelID;
+    constructor(modelID, options){
+        super(`Document model ${modelID} is not deployed on this device`, options);
+        this.name = 'ModelNotDeployedError';
+        this.#modelID = modelID;
+    }
+    get code() {
+        return 'KB15';
+    }
+    get modelID() {
+        return this.#modelID;
+    }
+    /**
+   * graphql-js copies a wrapped error's `extensions` onto the error it locates,
+   * so a resolver that lets this through surfaces the code to the app without
+   * translating it at the throw site.
+   */ get extensions() {
+        return {
+            code: 'KB15',
+            modelID: this.#modelID
+        };
+    }
+}

package/lib/index.d.ts

@@ -1,8 +1,9 @@
 import type { StoreProvider } from '@kubun/db';
 import type { GraphStoreAPI } from './api.js';
-export type { GraphStoreAPI, StoredAccessRule } from './api.js';
+export type { GraphStoreAPI, StoredAccessDefaultRow, StoredAccessRule } from './api.js';
 export { createGraphStore } from './api.js';
 export { graphStoreDefinition } from './definition.js';
+export { ModelNotDeployedError } from './errors.js';
 export declare const GRAPH_STORE: "graph";
 export declare function getGraphStore(provider: StoreProvider): Promise<GraphStoreAPI>;
 export type { AccessLevel, AccessPermissions, AddDocumentModelParams, Catalog, ClusterDefinitionRow, ClusterModel, ConnectionArguments, CreateDocumentParams, CreateGraphParams, CursorDocument, Document, DocumentAttachment, DocumentData, DocumentModelRow, DocumentParams, GraphModel, GraphModelWithRecord, GraphTables, InsertCatalog, InsertClusterModel, InsertDocument, InsertDocumentAttachment, InsertDocumentModel, InsertDocumentModelInterface, InsertMutationLogEntry, ListDocumentsParams, MutationLogEntry, PaginatedResult, PaginationParams, QueryDocumentsParams, QueryDocumentsResult, SaveDocumentParams, SearchConfig, SearchDocumentResult, SearchDocumentsParams, UpdateDocument, UpdateDocumentModel, ViewerReadAccess, } from './tables.js';

package/lib/index.js

@@ -1,5 +1,6 @@
 export { createGraphStore } from './api.js';
 export { graphStoreDefinition } from './definition.js';
+export { ModelNotDeployedError } from './errors.js';
 export const GRAPH_STORE = 'graph';
 export function getGraphStore(provider) {
     return provider.getStore(GRAPH_STORE);

package/lib/migrations.d.ts

@@ -1,3 +1,16 @@
 import type { MigrationContext } from '@kubun/db';
 import type { Migration } from 'kysely/migration';
+/**
+ * A shipped migration is immutable: once a database has run it, editing it
+ * changes nothing on that database and silently diverges the schema from the
+ * code. Every schema change after a release therefore goes in a NEW migration,
+ * which is why the later ones here say so.
+ *
+ * `0-init` is a deliberate exception on this change: it was edited in place
+ * rather than extended. That is a BREAKING change — a database created before it
+ * will not pick the new columns up and must be recreated. It was taken because
+ * this release already requires recreating local databases for unrelated reasons,
+ * so folding the change into the initial schema costs nothing and keeps `0-init`
+ * readable as the whole schema. Do NOT repeat it after this release ships.
+ */
 export declare function getGraphMigrations(ctx: MigrationContext): Record<string, Migration>;

package/lib/migrations.js

@@ -1,4 +1,16 @@
-export function getGraphMigrations(ctx) {
+/**
+ * A shipped migration is immutable: once a database has run it, editing it
+ * changes nothing on that database and silently diverges the schema from the
+ * code. Every schema change after a release therefore goes in a NEW migration,
+ * which is why the later ones here say so.
+ *
+ * `0-init` is a deliberate exception on this change: it was edited in place
+ * rather than extended. That is a BREAKING change — a database created before it
+ * will not pick the new columns up and must be recreated. It was taken because
+ * this release already requires recreating local databases for unrelated reasons,
+ * so folding the change into the initial schema costs nothing and keeps `0-init`
+ * readable as the whole schema. Do NOT repeat it after this release ships.
+ */ export function getGraphMigrations(ctx) {
     const t = ctx.types;
     const now = ctx.functions.now;
     const init = {
@@ -20,7 +32,10 @@ export function getGraphMigrations(ctx) {
                 'document_model_id'
             ]).execute();
             // User model access defaults
-            await db.schema.createTable('kubun_graph_user_model_access_defaults').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('model_id', t.text, (col)=>col.notNull()).addColumn('permission_type', t.text, (col)=>col.notNull()).addColumn('access_level', t.text, (col)=>col.notNull()).addColumn('allowed_dids', t.json).addColumn('allowed_circles', t.json).addColumn('allowed_groups', t.json).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp).addPrimaryKeyConstraint('kubun_graph_user_model_access_defaults_pkey', [
+            await db.schema.createTable('kubun_graph_user_model_access_defaults').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('model_id', t.text, (col)=>col.notNull()).addColumn('permission_type', t.text, (col)=>col.notNull()).addColumn('access_level', t.text, (col)=>col.notNull()).addColumn('allowed_dids', t.json).addColumn('allowed_circles', t.json).addColumn('allowed_groups', t.json)// LWW anchor for replicated rules; null for rows never stamped by a broadcast.
+            .addColumn('hlc', t.text)// Retained-tombstone marker (0/null = active, 1 = removed): removal keeps
+            // the row so its `hlc` stays the LWW anchor and hides it from reads.
+            .addColumn('removed', 'integer').addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp).addPrimaryKeyConstraint('kubun_graph_user_model_access_defaults_pkey', [
                 'owner_did',
                 'model_id',
                 'permission_type'
@@ -40,8 +55,31 @@ export function getGraphMigrations(ctx) {
             // Cluster definitions
             await db.schema.createTable('kubun_graph_clusters').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('definition', t.json, (col)=>col.notNull()).execute();
             // Catalogs
-            await db.schema.createTable('kubun_graph_catalogs').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('name', t.text, (col)=>col.notNull()).addColumn('description', t.text, (col)=>col.notNull().defaultTo('')).addColumn('filter_criteria', t.json, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp).execute();
+            await db.schema.createTable('kubun_graph_catalogs').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('name', t.text, (col)=>col.notNull()).addColumn('description', t.text, (col)=>col.notNull().defaultTo('')).addColumn('filter_criteria', t.json, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull())// Local-only sync activation (1 = active, 0/null = known-not-activated).
+            .addColumn('active', 'integer')// First-discovery provenance (nullable; never overwritten on re-discovery).
+            .addColumn('source_group_id', t.text).addColumn('source_circle_id', t.text)// Creator-signed `catalog:set` token; forwarded verbatim in invite seeds.
+            .addColumn('signed_token', t.text).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp).execute();
             await db.schema.createIndex('idx_graph_catalogs_owner').ifNotExists().on('kubun_graph_catalogs').column('owner_did').execute();
+            // `.ifNotExists()` protects a half-created table from being recreated —
+            // and, because this migration was edited in place, it equally protects a
+            // table an EARLIER run created from ever acquiring the columns that edit
+            // added. A database that ran the pre-edit `0-init`, or crashed after
+            // creating this table but before Kysely recorded the migration (SQLite
+            // DDL is not transactional), would otherwise complete this migration with
+            // a table that has no `hlc` and no `removed` — and every subsequent
+            // `setUserModelAccessDefault` would fail with "no such column: hlc",
+            // permanently, with no repair path. Healing it here is what makes the
+            // half-upgraded shape unrepresentable rather than merely unlikely.
+            const accessTable = (await db.introspection.getTables()).find((table)=>table.name === 'kubun_graph_user_model_access_defaults');
+            if (accessTable != null) {
+                const existing = new Set(accessTable.columns.map((column)=>column.name));
+                if (!existing.has('hlc')) {
+                    await db.schema.alterTable('kubun_graph_user_model_access_defaults').addColumn('hlc', t.text).execute();
+                }
+                if (!existing.has('removed')) {
+                    await db.schema.alterTable('kubun_graph_user_model_access_defaults').addColumn('removed', 'integer').execute();
+                }
+            }
         },
         async down (db) {
             await db.schema.dropTable('kubun_graph_catalogs').ifExists().execute();

package/lib/query-builder.d.ts

@@ -17,8 +17,9 @@ export declare function applyGroupBySelections(eb: DocumentExpressionBuilder, gr
     expressions: Array<DocumentExpressionWrapper>;
 };
 export declare function applyPagination(query: DocumentQueryBuilder, args: ConnectionArguments, orderBy?: DocumentOrderBy, coerce?: CoerceFilterValue): [DocumentQueryBuilder, number];
-export declare function applyDocumentFilter(eb: DocumentExpressionBuilder, filter: DocumentFilter, path?: Array<string>, coerce?: CoerceFilterValue): DocumentExpressionWrapper;
-export declare function applyValueFilter(eb: DocumentExpressionBuilder, keys: Array<string>, filter: AnyValueFilter, coerce?: CoerceFilterValue): DocumentExpressionWrapper;
+export declare function applyDocumentFilter(eb: DocumentExpressionBuilder, filter: DocumentFilter, adapter: Adapter, path?: Array<string>, coerce?: CoerceFilterValue): DocumentExpressionWrapper;
+export declare function escapeLikePattern(value: string): string;
+export declare function applyValueFilter(eb: DocumentExpressionBuilder, keys: Array<string>, filter: AnyValueFilter, adapter: Adapter, coerce?: CoerceFilterValue): DocumentExpressionWrapper;
 export declare function applyDocumentOrderBy(queryBuilder: DocumentQueryBuilder, adapter: Adapter, orderBy?: DocumentOrderBy, isReverse?: boolean): [DocumentQueryBuilder, Array<Array<string>> | null];
 export declare const KNOWN_FIELDS: {
     readonly _createdAt: "created_at";

package/lib/query-builder.js

@@ -12,6 +12,16 @@ function getKeyPath(eb, keys) {
     }
     return keyPath;
 }
+// Same traversal as getKeyPath, but keeps the raw JSON node (`->`) instead of extracting
+// text (`->>`), so array-membership predicates can hand adapters a JSON array to iterate
+// (json_each / jsonb_array_elements_text / `@>`) rather than a text scalar.
+function getRawKeyPath(eb, keys) {
+    let keyPath = eb.ref('data', '->');
+    for (const key of keys){
+        keyPath = keyPath.key(key);
+    }
+    return keyPath;
+}
 export function aggregateFieldName(keys) {
     return keys.join('.');
 }
@@ -220,7 +230,7 @@ function applyBackwardPagination(queryBuilder, limit, before, orderBy, coerce) {
     }
     return query.limit(limit);
 }
-export function applyDocumentFilter(eb, filter, path = [], coerce) {
+export function applyDocumentFilter(eb, filter, adapter, path = [], coerce) {
     const entries = Object.entries(filter);
     if (entries.length !== 1) {
         throw new Error('Invalid document filter');
@@ -228,33 +238,40 @@ export function applyDocumentFilter(eb, filter, path = [], coerce) {
     const [type, value] = entries[0];
     switch(type){
         case 'where':
-            return applyObjectFilter(eb, value, path, coerce);
+            return applyObjectFilter(eb, value, adapter, path, coerce);
         case 'and':
             return eb.and(value.map((filter)=>{
-                return applyDocumentFilter(eb, filter, path, coerce);
+                return applyDocumentFilter(eb, filter, adapter, path, coerce);
             }));
         case 'or':
             return eb.or(value.map((filter)=>{
-                return applyDocumentFilter(eb, filter, path, coerce);
+                return applyDocumentFilter(eb, filter, adapter, path, coerce);
             }));
         case 'not':
-            return eb.not(applyDocumentFilter(eb, value, path, coerce));
+            return eb.not(applyDocumentFilter(eb, value, adapter, path, coerce));
         default:
             throw new Error(`Invalid document filter type: ${type}`);
     }
 }
-function applyObjectFilter(eb, filter, path, coerce) {
+function applyObjectFilter(eb, filter, adapter, path, coerce) {
     const criteria = Object.entries(filter).map(([fieldName, valueFilter])=>{
         // TODO: check if value filter or nested object filter should be applied
         // for nested object, check if embedded or related object
         return applyValueFilter(eb, [
             ...path,
             fieldName
-        ], valueFilter, coerce);
+        ], valueFilter, adapter, coerce);
     });
     return eb.and(criteria);
 }
-export function applyValueFilter(eb, keys, filter, coerce) {
+// Escapes a LIKE pattern's special characters (backslash first, then the wildcards) and
+// wraps it for substring match. Order matters: escaping `%`/`_` before the backslash
+// would double-escape them.
+export function escapeLikePattern(value) {
+    const escaped = value.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
+    return `%${escaped}%`;
+}
+export function applyValueFilter(eb, keys, filter, adapter, coerce) {
     const entries = Object.entries(filter);
     if (entries.length !== 1) {
         throw new Error('Invalid value filter');
@@ -281,6 +298,29 @@ export function applyValueFilter(eb, keys, filter, coerce) {
             return eb(fieldName, '>', c(value));
         case 'greaterThanOrEqualTo':
             return eb(fieldName, '>=', c(value));
+        case 'contains':
+            return adapter.containsPredicate(fieldName, escapeLikePattern(String(value)));
+        case 'includesAll':
+            {
+                // Dedupe the candidate set so SQLite's COUNT(DISTINCT value) = set-size test matches
+                // Postgres @> containment: duplicate inputs must not inflate the required count.
+                const items = [
+                    ...new Set(value)
+                ];
+                // Vacuously true (D7): every array includes the empty set. Handled here, not in
+                // SQL, so the adapter seam never sees an empty IN-list.
+                return items.length === 0 ? sql`1 = 1` : adapter.arrayIncludesAllPredicate(getRawKeyPath(eb, keys), items);
+            }
+        case 'includesAny':
+            {
+                const items = [
+                    ...new Set(value)
+                ];
+                // An empty candidate set matches nothing.
+                return items.length === 0 ? sql`1 = 0` : adapter.arrayIncludesAnyPredicate(getRawKeyPath(eb, keys), items);
+            }
+        case 'presence':
+            return adapter.arrayPresencePredicate(getRawKeyPath(eb, keys), value);
         default:
             throw new Error(`Invalid value filter type: ${type}`);
     }

package/lib/tables.d.ts

@@ -99,6 +99,10 @@ export type UserModelAccessDefaultTable = {
     allowed_dids: JSONValueColumn<Array<string>> | null;
     allowed_circles: JSONValueColumn<Array<string>> | null;
     allowed_groups: JSONValueColumn<Array<string>> | null;
+    /** LWW anchor for replicated rules. Null for rows never stamped by a broadcast. */
+    hlc: string | null;
+    /** Retained-tombstone marker: 1 = removed, 0/null = active. */
+    removed: number | null;
     created_at: CreatedAtColumn;
     updated_at: UpdatedAtColumn;
 };
@@ -112,6 +116,30 @@ export type CatalogTable = {
     description: string;
     filter_criteria: JSONValueColumn<CatalogFilterCriteria>;
     hlc: string;
+    /**
+     * Local-only sync activation: 1 = active (scopes sync), 0/null = known (a
+     * discovered catalog that has not been activated). Insert-optional; own
+     * catalogs are created active, discovered ones arrive known.
+     */
+    active: ColumnType<number | null, number | null | undefined, number | null>;
+    /**
+     * Provenance: the group this catalog was first discovered from, null for own
+     * catalogs. First-discovery only — never overwritten on re-discovery.
+     */
+    source_group_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /**
+     * Provenance: the circle whose `catalog_ids` first referenced this catalog
+     * (set only for invite-seeded discovery), null otherwise. First-discovery only.
+     */
+    source_circle_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /**
+     * The creator-signed `catalog:set` token that authenticated this catalog: own
+     * catalogs sign it at creation, discovered ones store the verified token that
+     * delivered them. Forwarded verbatim in invite seeds so a joiner re-verifies
+     * creator-binding (`ownerDID === iss`) with the same helper the broadcast
+     * receive path uses. Null for rows that predate token capture.
+     */
+    signed_token: ColumnType<string | null, string | null | undefined, string | null>;
     created_at: CreatedAtColumn;
     updated_at: UpdatedAtColumn;
 };
@@ -142,6 +170,13 @@ export type CreateDocumentParams = DocumentParams & {
 export type SaveDocumentParams = DocumentParams & {
     existing: DocumentNode;
 };
+/** One cluster's registration, written with the graph that deploys it. */
+export type CreateGraphCluster = {
+    /** The cluster definition, stored verbatim for a peer to ship onward. */
+    definition: unknown;
+    /** modelID → index within the cluster. */
+    models: Record<string, number>;
+};
 export type CreateGraphParams = {
     aliases?: Record<string, string>;
     extensionSDL?: string;
@@ -150,6 +185,13 @@ export type CreateGraphParams = {
     pluginConfig?: Record<string, Record<string, unknown>>;
     record: DocumentModelsRecord;
     search?: SearchConfig;
+    /**
+     * Clusters to register in the SAME transaction as the graph. The cluster a
+     * model was deployed in is what lets a peer ship that model's definition to a
+     * device that lacks it, so a graph written without its clusters is one that
+     * works locally and cannot be synced to a device that has never seen it.
+     */
+    clusters?: Record<string, CreateGraphCluster>;
 };
 export type AddDocumentModelParams = {
     id: string;

package/package.json

@@ -1,40 +1,43 @@
 {
   "name": "@kubun/store-graph",
-  "version": "0.11.0",
-  "license": "see LICENSE.md",
+  "version": "0.13.0",
   "keywords": [],
+  "license": "see LICENSE.md",
+  "sideEffects": false,
   "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "exports": {
     ".": "./lib/index.js"
   },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "files": [
     "lib/*",
     "LICENSE.md"
   ],
-  "sideEffects": false,
   "dependencies": {
-    "@sozai/codec": "^0.1.0",
-    "kysely": "^0.29.2",
-    "@kubun/db": "^0.11.0",
-    "@kubun/db-adapter": "^0.11.0",
-    "@kubun/id": "^0.11.0",
-    "@kubun/protocol": "^0.11.0"
+    "@sozai/codec": "^0.4.0",
+    "kysely": "^0.29.5",
+    "@kubun/db": "^0.12.1",
+    "@kubun/protocol": "^0.13.0",
+    "@kubun/db-adapter": "^0.13.0",
+    "@kubun/id": "^0.12.0"
   },
   "devDependencies": {
-    "@testcontainers/postgresql": "^12.0.4",
-    "@kubun/db-better-sqlite": "^0.11.0",
-    "@kubun/db-postgres": "^0.11.0"
+    "@testcontainers/postgresql": "^12.1.0",
+    "@kubun/db-better-sqlite": "^0.12.1",
+    "@kubun/db-postgres": "^0.12.1"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
     "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
     "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
     "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
-    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "test": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit -p tsconfig.test.json",
-    "test:unit": "vitest run",
-    "test": "pnpm run test:types && pnpm run test:unit"
+    "test:unit": "vitest run"
   }
 }