@kubun/store-graph 0.10.1 → 0.11.0

package/lib/api.js

@@ -1 +1,993 @@
-import{DocumentID as e,DocumentModelID as t}from"@kubun/id";import{serializeCursor as l}from"./cursor.js";function n(e,t){if(!(e instanceof Error))return!1;let l=e.message;return l.includes("no such table")&&l.includes(t)||l.includes("does not exist")&&l.includes(t)}import{aggregateFieldName as r,applyAggregateSelections as a,applyDocumentFilter as o,applyDocumentOrderBy as u,applyGroupBySelections as s,applyPagination as i,groupKeyAlias as c}from"./query-builder.js";function d(e){if(null==e)return null;let t="number"==typeof e?e:Number(e);return Number.isNaN(t)?null:t}function m(){return{count:0,sums:new Map,fieldCounts:new Map,mins:new Map,maxes:new Map}}function _(e,t,l){e.count+=Number(l.count??0);let n=new Set,a=new Set;for(let o of t){let t=r(o.keys);switch(o.op){case"sum":case"average":if(!n.has(t)){n.add(t);let r=d(l[`sum_${t}`]);null!=r&&e.sums.set(t,(e.sums.get(t)??0)+r)}if("average"===o.op&&!a.has(t)){a.add(t);let n=d(l[`count_${t}`]);null!=n&&e.fieldCounts.set(t,(e.fieldCounts.get(t)??0)+n)}break;case"min":{let n=o.numeric?d(l[`min_${t}`]):l[`min_${t}`]??null;null!=n&&(!e.mins.has(t)||function(e,t,l){if(l){let l=d(e),n=d(t);return null!=l&&(null==n||l<n)}return e<t}(n,e.mins.get(t),o.numeric))&&e.mins.set(t,n);break}case"max":{let n=o.numeric?d(l[`max_${t}`]):l[`max_${t}`]??null;null!=n&&(!e.maxes.has(t)||function(e,t,l){if(l){let l=d(e),n=d(t);return null!=l&&(null==n||l>n)}return e>t}(n,e.maxes.get(t),o.numeric))&&e.maxes.set(t,n)}}}}function h(e,t,l){let n={};for(let a of(e&&(n.count=l.count),t)){let e=r(a.keys);switch(a.op){case"sum":n.sum??={},n.sum[e]=l.sums.get(e)??null;break;case"average":{n.average??={};let t=l.sums.get(e),r=l.fieldCounts.get(e)??0;n.average[e]=null==t||0===r?null:t/r;break}case"min":n.min??={},n.min[e]=l.mins.get(e)??null;break;case"max":n.max??={},n.max[e]=l.maxes.get(e)??null}}return n}function w(e,t){return null==e?null:e<t?-1:+(e>t)}function f(e,t){if(null!=t.isNull&&t.isNull!==(null==e)||null!=t.equalTo&&e!==t.equalTo||null!=t.notEqualTo&&e===t.notEqualTo||null!=t.in&&!t.in.includes(e)||t.notIn?.includes(e))return!1;if(null!=t.greaterThan){let l=w(e,t.greaterThan);if(null==l||l<=0)return!1}if(null!=t.greaterThanOrEqualTo){let l=w(e,t.greaterThanOrEqualTo);if(null==l||l<0)return!1}if(null!=t.lessThan){let l=w(e,t.lessThan);if(null==l||l>=0)return!1}if(null!=t.lessThanOrEqualTo){let l=w(e,t.lessThanOrEqualTo);if(null==l||l>0)return!1}return!0}function g(e,t){let l=e;for(let e of t){if(null==l||"object"!=typeof l)return null;l=l[e]}return l??null}function p(e){let t={version:e.version,name:e.name,behavior:e.behavior,interfaces:e.interfaces,schema:e.schema,fieldsMeta:e.fields_meta};return"unique"===t.behavior&&(t.uniqueFields=e.unique_fields),t}function y(e,t){return{id:t.id,model:t.model,owner:t.owner,data:t.data,createdAt:e.decodeTimestamp(t.created_at),updatedAt:t.updated_at?e.decodeTimestamp(t.updated_at):null}}function k(e,l){let n=t.fromString(l);return n.isLocal?n.toGlobal(t.fromString(e)).toString():l}async function x(e,t,l){let{id:n,graphModelID:r,model:a}=l,o=t.types;for(let l of(await e.schema.createTable(`k_${n}`).ifNotExists().addColumn("id",o.text,e=>e.notNull().primaryKey()).addColumn("owner",o.text,e=>e.notNull()).addColumn("model",o.text,e=>e.notNull()).addColumn("data",o.json).addColumn("field_hlcs",o.json).addColumn("unique",o.binary,e=>e.notNull()).addColumn("created_at",o.timestamp,e=>e.defaultTo(t.functions.now).notNull()).addColumn("updated_at",o.timestamp).execute(),await e.insertInto("kubun_graph_document_models").values({id:n,version:a.version,name:a.name,behavior:a.behavior,unique_fields:"unique"===a.behavior?t.encodeJSON(a.uniqueFields):null,interfaces:t.encodeJSON(a.interfaces),schema:t.encodeJSON(a.schema),fields_meta:t.encodeJSON(a.fieldsMeta)}).onConflict(e=>e.doNothing()).execute(),a.interfaces))await e.insertInto("kubun_graph_document_model_interfaces").values({interface_id:k(n,l),implementation_id:n}).onConflict(e=>e.doNothing()).execute();await e.insertInto("kubun_graph_document_model_links").values({graph_model_id:r,document_model_id:n}).onConflict(e=>e.doNothing()).execute()}export function createGraphStore(t,w){let b=w.coerceFilterValue.bind(w);async function S(e,t){if(null==t)return{effectiveModelIDs:e,effectiveOwners:void 0};let{models:l,owners:n}=await v.resolveCatalogScope(t),r=e;if(null!=l){let e=new Set(l);r=r.filter(t=>e.has(t))}return{effectiveModelIDs:r,effectiveOwners:n}}let v={async getDocument(l){let n=e.from(l),r=await t.selectFrom(`k_${n.model.toString()}`).selectAll().where("id","=",n.toString()).executeTakeFirst();return r?y(w,r):null},getDocumentModel:async e=>p(await t.selectFrom("kubun_graph_document_models").selectAll().where("id","=",e.toString()).executeTakeFirstOrThrow()),getModelInterfaces:async e=>(await t.selectFrom("kubun_graph_document_model_interfaces").select("interface_id").where("implementation_id","=",e).execute()).map(e=>e.interface_id),async createDocument(e){let l=e.id.toString(),n=e.id.model.toString(),r=await t.insertInto(`k_${n}`).values({id:l,owner:e.owner,model:n,data:w.encodeJSON(e.data),unique:w.encodeBinary(e.unique)}).returningAll().executeTakeFirstOrThrow(()=>Error(`createDocument failed to return row for ${l}`));return y(w,r)},async saveDocument(e){let l=e.id.toString(),n=await t.updateTable(`k_${e.id.model.toString()}`).set({data:e.data?w.encodeJSON(e.data):null,updated_at:w.encodeTimestamp(new Date)}).where("id","=",l).returningAll().executeTakeFirstOrThrow(()=>Error(`saveDocument: document not found for id=${l}`));return y(w,n)},async queryDocuments(e){let{catalogID:n,filter:r,modelIDs:a,orderBy:s,owner:c,...d}=e,m=null!=e.last,{effectiveModelIDs:_,effectiveOwners:h}=await S(a,n);if(0===_.length)return{entries:[],hasMore:!1};let[f,...g]=_,p=t.selectFrom(`k_${f}`).selectAll().where("data","is not",null);for(let e of(null!=c&&(p=p.where("owner","=",c)),null!=h&&(p=p.where("owner","in",h)),null!=r&&(p=p.where(e=>o(e,r,[],b))),g))p=p.unionAll(t=>{let l=t.selectFrom(`k_${e}`).selectAll().where("data","is not",null);return null!=c&&(l=l.where("owner","=",c)),null!=h&&(l=l.where("owner","in",h)),null!=r&&(l=l.where(e=>o(e,r,[],b))),l});let[k,x]=u(p,s,m),[v,F]=i(k,d,s),D=await v.execute(),C=m?D.slice(0,F).reverse():D.slice(0,F);return{entries:x?C.map(e=>{let t={};for(let l of x){let n=e.data;for(let e of l)null!=n&&(n=n[e]);null!=n&&(t[l.join(".")]=n)}return{cursor:l({id:e.id,values:t}),document:y(w,e)}}):C.map(e=>({cursor:l({id:e.id,ts:+e.created_at}),document:y(w,e)})),hasMore:D.length>F}},async aggregateDocuments(e){let{aggregates:l,catalogID:u,count:s,filter:i,modelIDs:c,owner:d,readAccess:f}=e,g=function(e,t){let l={};for(let n of(e&&(l.count=0),t)){let e=r(n.keys);switch(n.op){case"sum":l.sum??={},l.sum[e]=null;break;case"average":l.average??={},l.average[e]=null;break;case"min":l.min??={},l.min[e]=null;break;case"max":l.max??={},l.max[e]=null}}return l}(s,l);if(!s&&0===l.length)return g;let{effectiveModelIDs:p,effectiveOwners:y}=await S(c,u);if(0===p.length)return g;let k=await Promise.all(p.map(async e=>{let r=t.selectFrom(`k_${e}`).select(e=>{let t=a(e,l,w);return s&&t.push(e.fn.countAll().as("count")),t});r=r.where("data","is not",null),null!=d&&(r=r.where("owner","=",d)),null!=y&&(r=r.where("owner","in",y)),null!=i&&(r=r.where(e=>o(e,i,[],b))),null!=f&&(r=r.where(w.readAccessPredicate(f,e)));try{return await r.executeTakeFirst()}catch(t){if(n(t,`k_${e}`))return;throw t}})),x=m(),v=!1;for(let e of k)null!=e&&(v=!0,_(x,l,e));return v?h(s,l,x):g},async groupedAggregateDocuments(e){let{aggregates:l,catalogID:u,count:i,filter:p,groupBy:y,having:k,limit:x,modelIDs:v,orderBy:F,owner:D,readAccess:C}=e,{effectiveModelIDs:T,effectiveOwners:N}=await S(v,u);if(0===T.length)return[];let I=await Promise.all(T.map(async e=>{let r=t.selectFrom(`k_${e}`).select(e=>{let{selections:t}=s(e,y),n=[...t,...a(e,l,w)];return i&&n.push(e.fn.countAll().as("count")),n});r=(r=r.groupBy(e=>s(e,y).expressions)).where("data","is not",null),null!=D&&(r=r.where("owner","=",D)),null!=N&&(r=r.where("owner","in",N)),null!=p&&(r=r.where(e=>o(e,p,[],b))),null!=C&&(r=r.where(w.readAccessPredicate(C,e)));try{return await r.execute()}catch(t){if(n(t,`k_${e}`))return[];throw t}})),A=new Map;for(let e of I)for(let t of e){let e={};for(let l of y){let n=t[c(l.keys)];e[r(l.keys)]=n??null}let n=JSON.stringify(y.map(t=>e[r(t.keys)])),a=A.get(n);null==a&&(a={keys:e,acc:m()},A.set(n,a)),_(a.acc,l,t)}let O=Array.from(A.values()).map(e=>({keys:e.keys,...h(i,l,e.acc)})),M=null==k?O:O.filter(e=>(function(e,t){if(null!=t.count&&!f(e.count??null,t.count))return!1;for(let l of["sum","average","min","max"]){let n=t[l];if(null==n)continue;let r=e[l];for(let[e,t]of Object.entries(n))if(!f(r?.[e]??null,t))return!1}return!0})(e,k)),$=null!=F&&F.length>0?[...M].sort((e,t)=>(function(e,t,l){for(let n of l){let l=function(e,t,l){let n,r=g(e,l.path),a=g(t,l.path),o=l.numeric?d(r):r,u=l.numeric?d(a):a,s=null==o,i=null==u;return s&&i?0:s?1:i?-1:(n=o<u?-1:+(o>u),"desc"===l.direction?-n:n)}(e,t,n);if(0!==l)return l}return 0})(e,t,F)):M;return null!=x?$.slice(0,Math.max(0,x)):$},async listDocuments(e){let[l,...n]=e.modelIDs,r=t.selectFrom(`k_${l}`).selectAll().where("id","in",e.docIDs).where("data","is not",null);for(let t of n)r=r.unionAll(l=>l.selectFrom(`k_${t}`).selectAll().where("id","in",e.docIDs).where("data","is not",null));return(await r.execute()).map(e=>y(w,e))},listDocumentModelIDs:async()=>(await t.selectFrom("kubun_graph_document_models").select("id").execute()).map(e=>e.id),async getDistinctOwnersForModel(e){try{return(await t.selectFrom(`k_${e}`).select("owner").distinct().execute()).map(e=>e.owner)}catch(t){if(n(t,`k_${e}`))return[];throw t}},queryDocumentsByOwner:async(e,l)=>(await t.selectFrom(`k_${e}`).selectAll().where("owner","=",l).execute()).map(e=>y(w,e)),async insertMutationLogEntry(e){await t.insertInto("kubun_graph_mutation_log").values(e).onConflict(e=>e.doNothing()).execute()},hasMutationHash:async e=>null!=await t.selectFrom("kubun_graph_mutation_log").select("mutation_hash").where("mutation_hash","=",e).executeTakeFirst(),async updateMutationStatus(e,l){await t.updateTable("kubun_graph_mutation_log").set({status:l}).where("mutation_hash","=",e).execute()},getMutationLogForDocuments:async e=>0===e.length?[]:await t.selectFrom("kubun_graph_mutation_log").selectAll().where("document_id","in",e).orderBy("hlc","asc").execute(),getPendingMutations:async e=>await t.selectFrom("kubun_graph_mutation_log").selectAll().where("document_id","=",e).where("status","=","pending").orderBy("hlc","asc").execute(),async getFieldHLCs(l){let n=e.fromString(l).model.toString(),r=await t.selectFrom(`k_${n}`).select("field_hlcs").where("id","=",l).executeTakeFirst();if(r?.field_hlcs==null)return null;let a=r.field_hlcs;return"string"==typeof a?JSON.parse(a):a},async updateFieldHLCs(e,l){let n=e.model.toString();await t.updateTable(`k_${n}`).set({field_hlcs:w.encodeJSON(l)}).where("id","=",e.toString()).execute()},listGraphs:async()=>await t.selectFrom("kubun_graph_models").selectAll().execute(),async createGraph(e){let l=e.id,n=e.name??l;return await t.transaction().setIsolationLevel("read committed").execute(async t=>{await t.insertInto("kubun_graph_models").values({aliases:w.encodeJSON(e.aliases??{}),extension_sdl:e.extensionSDL??null,id:l,name:n,plugin_config:e.pluginConfig?w.encodeJSON(e.pluginConfig):null,search:e.search?w.encodeJSON(e.search):null}).onConflict(e=>e.doNothing()).execute();let r=Object.entries(e.record),a=new Set;for(;a.size<r.length;){let e=r.filter(([e,t])=>!a.has(e)&&t.interfaces.every(t=>a.has(k(e,t))));if(0===e.length)throw Error("Could not create graph: no valid model to add");await Promise.all(e.map(async([e,n])=>{await x(t,w,{id:e,graphModelID:l,model:n}),a.add(e)}))}}),l},async getGraph(e){let l=await t.selectFrom("kubun_graph_models").selectAll().where("id","=",e).executeTakeFirst();if(null==l)return null;let n={};for(let l of(await t.selectFrom("kubun_graph_document_model_links").innerJoin("kubun_graph_document_models","kubun_graph_document_model_links.document_model_id","kubun_graph_document_models.id").selectAll("kubun_graph_document_models").where("kubun_graph_document_model_links.graph_model_id","=",e).execute()))n[l.id]=p(l);return{...l,record:n}},async getClusterForModel(e){let l=await t.selectFrom("kubun_graph_cluster_models").select("cluster_id").where("model_id","=",e).executeTakeFirst();return l?.cluster_id},getClusterModels:async e=>await t.selectFrom("kubun_graph_cluster_models").selectAll().where("cluster_id","=",e).orderBy("cluster_index").execute(),async saveCluster(e,l){await t.insertInto("kubun_graph_clusters").values({id:e,definition:w.encodeJSON(l)}).onConflict(e=>e.column("id").doUpdateSet(e=>({definition:e.ref("excluded.definition")}))).execute()},getCluster:async e=>await t.selectFrom("kubun_graph_clusters").selectAll().where("id","=",e).executeTakeFirst(),async getClusters(e){if(0===e.length)return{};let l=await t.selectFrom("kubun_graph_clusters").selectAll().where("id","in",e).execute(),n={};for(let e of l)n[e.id]=e.definition;return n},async addAttachments(e){await t.insertInto("kubun_graph_document_attachments").values(e).onConflict(e=>e.doNothing()).execute()},async createSearchIndex(e,l){await w.createSearchIndex(t,{modelID:e,fields:l})},async dropSearchIndex(e){await w.dropSearchIndex(t,e)},async updateSearchEntry(e,l,n,r){let a={};for(let e of r){let t=function(e,t){let l=t.split("."),n=e;for(let e of l){if(null==n||"object"!=typeof n)return null;n=n[e]}return n}(n,e);null!=t&&(a[e]=String(t))}await w.updateSearchEntry(t,e,l,a,r)},async removeSearchEntry(e,l){await w.removeSearchEntry(t,e,l)},async searchDocuments(e){let l=[];for(let n of e.modelIDs)for(let r of(await w.searchIndex(t,{query:e.query,modelID:n,limit:e.first??50})))l.push({documentID:r.documentID,modelID:n,rank:r.rank});return(l.sort((e,t)=>Math.abs(t.rank)-Math.abs(e.rank)),e.first)?l.slice(0,e.first):l},async createCatalog(e){await t.insertInto("kubun_graph_catalogs").values({id:e.id,owner_did:e.owner_did,name:e.name,description:e.description,filter_criteria:w.encodeJSON(e.filter_criteria),hlc:e.hlc}).execute()},getCatalog:async e=>await t.selectFrom("kubun_graph_catalogs").selectAll().where("id","=",e).executeTakeFirst(),async getCatalogs(e){let l=new Map;if(0===e.length)return l;for(let n of(await t.selectFrom("kubun_graph_catalogs").selectAll().where("id","in",e).execute()))l.set(n.id,n);return l},async updateCatalog(e,l){let n={};null!=l.name&&(n.name=l.name),null!=l.description&&(n.description=l.description),null!=l.filter_criteria&&(n.filter_criteria=w.encodeJSON(l.filter_criteria)),null!=l.hlc&&(n.hlc=l.hlc),n.updated_at=w.encodeTimestamp(new Date),await t.updateTable("kubun_graph_catalogs").set(n).where("id","=",e).execute()},async deleteCatalog(e){await t.deleteFrom("kubun_graph_catalogs").where("id","=",e).execute()},listCatalogs:async e=>await t.selectFrom("kubun_graph_catalogs").selectAll().where("owner_did","=",e).execute(),async resolveCatalogScope(e){let t,l=await v.getCatalog(e);if(null==l)return{models:void 0,owners:void 0};let n=l.filter_criteria,r=null!=n.models&&n.models.length>0?n.models:void 0;return null!=n.owners&&n.owners.length>0&&(t=[...n.owners]),{models:r,owners:t}},async registerClusterModels(e,l){0!==l.length&&await t.insertInto("kubun_graph_cluster_models").values(l).onConflict(e=>e.column("model_id").doUpdateSet(e=>({cluster_id:e.ref("excluded.cluster_id"),cluster_index:e.ref("excluded.cluster_index")}))).execute()},async getUserModelAccessDefault(e,l,n){let r=await t.selectFrom("kubun_graph_user_model_access_defaults").select(["access_level","allowed_dids","allowed_circles","allowed_groups"]).where("owner_did","=",e).where("model_id","=",l).where("permission_type","=",n).executeTakeFirst();return r?{level:r.access_level,allowedDIDs:r.allowed_dids,allowedCircles:r.allowed_circles,allowedGroups:r.allowed_groups}:null},async setUserModelAccessDefault(e){await t.insertInto("kubun_graph_user_model_access_defaults").values({owner_did:e.ownerDID,model_id:e.modelID,permission_type:e.permissionType,access_level:e.accessLevel,allowed_dids:e.allowedDIDs?w.encodeJSON(e.allowedDIDs):null,allowed_circles:e.allowedCircles?w.encodeJSON(e.allowedCircles):null,allowed_groups:e.allowedGroups?w.encodeJSON(e.allowedGroups):null}).onConflict(t=>t.columns(["owner_did","model_id","permission_type"]).doUpdateSet({access_level:e.accessLevel,allowed_dids:e.allowedDIDs?w.encodeJSON(e.allowedDIDs):null,allowed_circles:e.allowedCircles?w.encodeJSON(e.allowedCircles):null,allowed_groups:e.allowedGroups?w.encodeJSON(e.allowedGroups):null,updated_at:w.encodeTimestamp(new Date)})).execute()},async removeUserModelAccessDefaults(e,l,n){await t.deleteFrom("kubun_graph_user_model_access_defaults").where("owner_did","=",e).where("model_id","=",l).where("permission_type","in",n).execute()},async getDocumentIDsForScope(e,l=[]){let r=[];for(let l of e)try{let e=await t.selectFrom(`k_${l.modelID}`).select("id").where("owner","=",l.ownerDID).execute();r.push(...e.map(e=>e.id))}catch(e){if(!n(e,`k_${l.modelID}`))throw e}if(l.length>0){let e=new Set(l);return r.filter(t=>!e.has(t))}return r},getDocumentMetadataForSync:async(e,l)=>0===l.length?[]:(await t.selectFrom(`k_${e}`).select(["id","model","owner"]).where("id","in",l).execute()).map(e=>({id:e.id,model:e.model,owner:e.owner}))};return v}
+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 { 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`),
+// so normalise to a JS number, treating NULL/empty as null.
+function toNumberOrNull(value) {
+    if (value == null) return null;
+    const num = typeof value === 'number' ? value : Number(value);
+    return Number.isNaN(num) ? null : num;
+}
+function emptyAggregateValues(count, aggregates) {
+    const result = {};
+    if (count) result.count = 0;
+    for (const spec of aggregates){
+        const field = aggregateFieldName(spec.keys);
+        switch(spec.op){
+            case 'sum':
+                result.sum ??= {};
+                result.sum[field] = null;
+                break;
+            case 'average':
+                result.average ??= {};
+                result.average[field] = null;
+                break;
+            case 'min':
+                result.min ??= {};
+                result.min[field] = null;
+                break;
+            case 'max':
+                result.max ??= {};
+                result.max[field] = null;
+                break;
+        }
+    }
+    return result;
+}
+function createAggregateAccumulator() {
+    return {
+        count: 0,
+        sums: new Map(),
+        fieldCounts: new Map(),
+        mins: new Map(),
+        maxes: new Map()
+    };
+}
+function isLess(candidate, current, numeric) {
+    if (numeric) {
+        const a = toNumberOrNull(candidate);
+        const b = toNumberOrNull(current);
+        if (a == null) return false;
+        if (b == null) return true;
+        return a < b;
+    }
+    return candidate < current;
+}
+function isGreater(candidate, current, numeric) {
+    if (numeric) {
+        const a = toNumberOrNull(candidate);
+        const b = toNumberOrNull(current);
+        if (a == null) return false;
+        if (b == null) return true;
+        return a > b;
+    }
+    return candidate > current;
+}
+function accumulateAggregateRow(acc, aggregates, row) {
+    acc.count += Number(row.count ?? 0);
+    // `sum` and `average` on the same field share the `sum_<field>` column, so add each
+    // raw column at most once per row to avoid double-counting overlapping specs.
+    const summedFields = new Set();
+    const countedFields = new Set();
+    for (const spec of aggregates){
+        const field = aggregateFieldName(spec.keys);
+        switch(spec.op){
+            case 'sum':
+            case 'average':
+                {
+                    if (!summedFields.has(field)) {
+                        summedFields.add(field);
+                        const value = toNumberOrNull(row[`sum_${field}`]);
+                        if (value != null) {
+                            acc.sums.set(field, (acc.sums.get(field) ?? 0) + value);
+                        }
+                    }
+                    if (spec.op === 'average' && !countedFields.has(field)) {
+                        countedFields.add(field);
+                        const fieldCount = toNumberOrNull(row[`count_${field}`]);
+                        if (fieldCount != null) {
+                            acc.fieldCounts.set(field, (acc.fieldCounts.get(field) ?? 0) + fieldCount);
+                        }
+                    }
+                    break;
+                }
+            case 'min':
+                {
+                    const value = spec.numeric ? toNumberOrNull(row[`min_${field}`]) : row[`min_${field}`] ?? null;
+                    if (value != null) {
+                        if (!acc.mins.has(field) || isLess(value, acc.mins.get(field), spec.numeric)) {
+                            acc.mins.set(field, value);
+                        }
+                    }
+                    break;
+                }
+            case 'max':
+                {
+                    const value = spec.numeric ? toNumberOrNull(row[`max_${field}`]) : row[`max_${field}`] ?? null;
+                    if (value != null) {
+                        if (!acc.maxes.has(field) || isGreater(value, acc.maxes.get(field), spec.numeric)) {
+                            acc.maxes.set(field, value);
+                        }
+                    }
+                    break;
+                }
+        }
+    }
+}
+function finalizeAggregateValues(count, aggregates, acc) {
+    const result = {};
+    if (count) result.count = acc.count;
+    for (const spec of aggregates){
+        const field = aggregateFieldName(spec.keys);
+        switch(spec.op){
+            case 'sum':
+                {
+                    result.sum ??= {};
+                    result.sum[field] = acc.sums.get(field) ?? null;
+                    break;
+                }
+            case 'average':
+                {
+                    result.average ??= {};
+                    const sum = acc.sums.get(field);
+                    const fieldCount = acc.fieldCounts.get(field) ?? 0;
+                    result.average[field] = sum == null || fieldCount === 0 ? null : sum / fieldCount;
+                    break;
+                }
+            case 'min':
+                {
+                    result.min ??= {};
+                    result.min[field] = acc.mins.get(field) ?? null;
+                    break;
+                }
+            case 'max':
+                {
+                    result.max ??= {};
+                    result.max[field] = acc.maxes.get(field) ?? null;
+                    break;
+                }
+        }
+    }
+    return result;
+}
+// Ordered comparison between a group value and a bound. Numeric when both operands
+// are numbers ('9' < '10'), otherwise lexical, matching the min/max/aggregate merge
+// logic in this file. A null group value yields null (it satisfies no ordering),
+// letting the caller fail ordered operators on nulls per SQL semantics.
+function compareHavingValue(value, bound) {
+    if (value == null) return null;
+    if (typeof value === 'number' && typeof bound === 'number') {
+        return value < bound ? -1 : value > bound ? 1 : 0;
+    }
+    return value < bound ? -1 : value > bound ? 1 : 0;
+}
+// Evaluate one comparison clause against a finalised group value, supporting the
+// full value-filter operator set. Every present operator must hold (logical AND).
+// `isNull` is the only operator a null value can satisfy; the ordered operators
+// (lessThan etc.) fail on null, matching SQL NULL semantics.
+function passesHavingComparison(value, comparison) {
+    if (comparison.isNull != null && comparison.isNull !== (value == null)) return false;
+    if (comparison.equalTo != null && value !== comparison.equalTo) return false;
+    if (comparison.notEqualTo != null && value === comparison.notEqualTo) return false;
+    if (comparison.in != null && !comparison.in.includes(value)) return false;
+    if (comparison.notIn?.includes(value)) return false;
+    if (comparison.greaterThan != null) {
+        const cmp = compareHavingValue(value, comparison.greaterThan);
+        if (cmp == null || cmp <= 0) return false;
+    }
+    if (comparison.greaterThanOrEqualTo != null) {
+        const cmp = compareHavingValue(value, comparison.greaterThanOrEqualTo);
+        if (cmp == null || cmp < 0) return false;
+    }
+    if (comparison.lessThan != null) {
+        const cmp = compareHavingValue(value, comparison.lessThan);
+        if (cmp == null || cmp >= 0) return false;
+    }
+    if (comparison.lessThanOrEqualTo != null) {
+        const cmp = compareHavingValue(value, comparison.lessThanOrEqualTo);
+        if (cmp == null || cmp > 0) return false;
+    }
+    return true;
+}
+// Whether a finalised, merged group satisfies the having predicate. Every present
+// clause (count, and each field under sum/average/min/max) must pass.
+function passesHaving(group, having) {
+    if (having.count != null && !passesHavingComparison(group.count ?? null, having.count)) {
+        return false;
+    }
+    for (const op of [
+        'sum',
+        'average',
+        'min',
+        'max'
+    ]){
+        const clauses = having[op];
+        if (clauses == null) continue;
+        const values = group[op];
+        for (const [field, comparison] of Object.entries(clauses)){
+            // Pass the raw value: count/sum/average finalise as numbers, while min/max may
+            // be strings, which must compare lexically rather than coerce to null.
+            if (!passesHavingComparison(values?.[field] ?? null, comparison)) return false;
+        }
+    }
+    return true;
+}
+// Read the value at an ordering path from a finalised group object, e.g.
+// ['sum', 'delta'] or ['keys', 'area']. A missing intermediate or leaf yields null.
+function readGroupPath(group, path) {
+    let value = group;
+    for (const key of path){
+        if (value == null || typeof value !== 'object') return null;
+        value = value[key];
+    }
+    return value ?? null;
+}
+// Compare two group values for one ordering term. Returns a negative, zero, or
+// positive number. A null/absent value always sorts last regardless of direction;
+// the non-null ordering is flipped for 'desc'. Numeric terms coerce both sides to a
+// number, otherwise comparison is lexical (so '9' < '10' only when numeric).
+function compareGroupTerm(a, b, term) {
+    const rawA = readGroupPath(a, term.path);
+    const rawB = readGroupPath(b, term.path);
+    const valueA = term.numeric ? toNumberOrNull(rawA) : rawA;
+    const valueB = term.numeric ? toNumberOrNull(rawB) : rawB;
+    const aMissing = valueA == null;
+    const bMissing = valueB == null;
+    if (aMissing && bMissing) return 0;
+    if (aMissing) return 1;
+    if (bMissing) return -1;
+    let result;
+    if (valueA < valueB) result = -1;
+    else if (valueA > valueB) result = 1;
+    else result = 0;
+    return term.direction === 'desc' ? -result : result;
+}
+// Stable multi-term comparator over finalised groups: terms are tried in order and
+// the first non-equal term decides; later terms break ties.
+function compareGroups(a, b, orderBy) {
+    for (const term of orderBy){
+        const result = compareGroupTerm(a, b, term);
+        if (result !== 0) return result;
+    }
+    return 0;
+}
+function documentModelFromTable(row) {
+    const model = {
+        version: row.version,
+        name: row.name,
+        behavior: row.behavior,
+        interfaces: row.interfaces,
+        schema: row.schema,
+        fieldsMeta: row.fields_meta
+    };
+    if (model.behavior === 'unique') {
+        model.uniqueFields = row.unique_fields;
+    }
+    return model;
+}
+function documentModelToTable(adapter, id, model) {
+    return {
+        id,
+        version: model.version,
+        name: model.name,
+        behavior: model.behavior,
+        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)
+    };
+}
+function documentNodeFromTable(adapter, doc) {
+    return {
+        id: doc.id,
+        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
+    };
+}
+function toGlobalInterfaceID(modelID, interfaceID) {
+    const id = DocumentModelID.fromString(interfaceID);
+    return id.isLocal ? id.toGlobal(DocumentModelID.fromString(modelID)).toString() : interfaceID;
+}
+function extractFieldValue(data, fieldPath) {
+    const keys = fieldPath.split('.');
+    let value = data;
+    for (const key of keys){
+        if (value == null || typeof value !== 'object') return null;
+        value = value[key];
+    }
+    return value;
+}
+// --- Private helper for adding a document model within a transaction ---
+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)=>{
+        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();
+    for (const interfaceID of model.interfaces){
+        await transaction.insertInto('kubun_graph_document_model_interfaces').values({
+            interface_id: toGlobalInterfaceID(id, interfaceID),
+            implementation_id: id
+        }).onConflict((oc)=>oc.doNothing()).execute();
+    }
+    await transaction.insertInto('kubun_graph_document_model_links').values({
+        graph_model_id: graphModelID,
+        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));
+        }
+        return {
+            effectiveModelIDs,
+            effectiveOwners: owners
+        };
+    }
+    const api = {
+        // --- 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();
+            return doc ? documentNodeFromTable(adapter, doc) : null;
+        },
+        async getDocumentModel (id) {
+            const row = await db.selectFrom('kubun_graph_document_models').selectAll().where('id', '=', id.toString()).executeTakeFirstOrThrow();
+            return documentModelFromTable(row);
+        },
+        async getModelInterfaces (modelID) {
+            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 createDocument (params) {
+            const id = params.id.toString();
+            const model = params.id.model.toString();
+            const doc = await db.insertInto(`k_${model}`).values({
+                id,
+                owner: params.owner,
+                model,
+                data: adapter.encodeJSON(params.data),
+                unique: adapter.encodeBinary(params.unique)
+            }).returningAll().executeTakeFirstOrThrow(()=>new Error(`createDocument failed to return row for ${id}`));
+            return documentNodeFromTable(adapter, doc);
+        },
+        async saveDocument (params) {
+            const id = params.id.toString();
+            const doc = await db.updateTable(`k_${params.id.model.toString()}`).set({
+                data: params.data ? adapter.encodeJSON(params.data) : null,
+                updated_at: adapter.encodeTimestamp(new Date())
+            }).where('id', '=', id).returningAll().executeTakeFirstOrThrow(()=>new Error(`saveDocument: document not found for id=${id}`));
+            return documentNodeFromTable(adapter, doc);
+        },
+        async queryDocuments (params) {
+            const { catalogID, filter, modelIDs, orderBy, owner, ...pagination } = params;
+            const isReverse = params.last != null;
+            const { effectiveModelIDs, effectiveOwners } = await resolveCatalogFilter(modelIDs, catalogID);
+            if (effectiveModelIDs.length === 0) {
+                return {
+                    entries: [],
+                    hasMore: false
+                };
+            }
+            const [first, ...rest] = effectiveModelIDs;
+            // 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 (owner != null) {
+                query = query.where('owner', '=', owner);
+            }
+            if (effectiveOwners != null) {
+                query = query.where('owner', 'in', effectiveOwners);
+            }
+            if (filter != null) {
+                query = query.where((eb)=>applyDocumentFilter(eb, filter, [], coerce));
+            }
+            for (const model of rest){
+                query = query.unionAll((eb)=>{
+                    let q = eb.selectFrom(`k_${model}`).selectAll().where('data', 'is not', null);
+                    if (owner != null) {
+                        q = q.where('owner', '=', owner);
+                    }
+                    if (effectiveOwners != null) {
+                        q = q.where('owner', 'in', effectiveOwners);
+                    }
+                    if (filter != null) {
+                        q = q.where((eb)=>applyDocumentFilter(eb, filter, [], coerce));
+                    }
+                    return q;
+                });
+            }
+            const [orderedQuery, orderedFieldsPaths] = applyDocumentOrderBy(query, 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);
+            const entries = orderedFieldsPaths ? docs.map((document)=>{
+                const values = {};
+                const nullKeys = [];
+                for (const path of orderedFieldsPaths){
+                    const column = knownFieldColumn(path);
+                    let value;
+                    if (column != null) {
+                        // Known fields order on a non-null table column, not a JSON key inside
+                        // `data`. Read the ordered value from the row column so the next page's
+                        // keyset predicate compares against a real value instead of treating
+                        // every row as the null bucket.
+                        value = document[column];
+                    } else {
+                        value = document.data;
+                        for (const key of path){
+                            if (value != null) {
+                                value = value[key];
+                            } else {
+                                value = undefined;
+                            }
+                        }
+                    }
+                    const key = path.join('.');
+                    if (value == null) {
+                        // Tag the null ordered value explicitly so the keyset predicate places
+                        // this row in the null bucket instead of losing the ordering dimension.
+                        nullKeys.push(key);
+                    } else {
+                        values[key] = value;
+                    }
+                }
+                const cursor = serializeCursor({
+                    id: document.id,
+                    values,
+                    nullKeys
+                });
+                return {
+                    cursor,
+                    document: documentNodeFromTable(adapter, document)
+                };
+            }) : docs.map((document)=>{
+                const cursor = serializeCursor({
+                    id: document.id,
+                    ts: +document.created_at
+                });
+                return {
+                    cursor,
+                    document: documentNodeFromTable(adapter, document)
+                };
+            });
+            return {
+                entries,
+                hasMore: results.length > limit
+            };
+        },
+        async aggregateDocuments (params) {
+            const { aggregates, catalogID, 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);
+            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 /
+            // Σcount across the implementing models rather than averaging per-model means.
+            const rows = await Promise.all(effectiveModelIDs.map(async (modelID)=>{
+                let query = db.selectFrom(`k_${modelID}`).select((eb)=>{
+                    const selections = applyAggregateSelections(eb, aggregates, adapter);
+                    if (count) {
+                        selections.push(eb.fn.countAll().as('count'));
+                    }
+                    return selections;
+                });
+                query = query.where('data', 'is not', null);
+                if (owner != null) {
+                    query = query.where('owner', '=', owner);
+                }
+                if (effectiveOwners != null) {
+                    query = query.where('owner', 'in', effectiveOwners);
+                }
+                if (filter != null) {
+                    query = query.where((eb)=>applyDocumentFilter(eb, filter, [], coerce));
+                }
+                if (readAccess != null) {
+                    query = query.where(adapter.readAccessPredicate(readAccess, modelID));
+                }
+                try {
+                    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.
+                    if (isMissingTableError(err, `k_${modelID}`)) return undefined;
+                    throw err;
+                }
+            }));
+            const acc = createAggregateAccumulator();
+            let contributed = false;
+            for (const row of rows){
+                if (row == null) continue;
+                contributed = true;
+                accumulateAggregateRow(acc, aggregates, row);
+            }
+            if (!contributed) return empty;
+            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);
+            if (effectiveModelIDs.length === 0) return [];
+            // 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.
+            const modelRows = await Promise.all(effectiveModelIDs.map(async (modelID)=>{
+                let query = db.selectFrom(`k_${modelID}`).select((eb)=>{
+                    const { selections: keySelections } = applyGroupBySelections(eb, groupBy);
+                    const aggregateSelections = applyAggregateSelections(eb, aggregates, adapter);
+                    const selections = [
+                        ...keySelections,
+                        ...aggregateSelections
+                    ];
+                    if (count) {
+                        selections.push(eb.fn.countAll().as('count'));
+                    }
+                    return selections;
+                });
+                query = query.groupBy((eb)=>applyGroupBySelections(eb, groupBy).expressions);
+                query = query.where('data', 'is not', null);
+                if (owner != null) {
+                    query = query.where('owner', '=', owner);
+                }
+                if (effectiveOwners != null) {
+                    query = query.where('owner', 'in', effectiveOwners);
+                }
+                if (filter != null) {
+                    query = query.where((eb)=>applyDocumentFilter(eb, filter, [], coerce));
+                }
+                if (readAccess != null) {
+                    query = query.where(adapter.readAccessPredicate(readAccess, modelID));
+                }
+                try {
+                    return await query.execute();
+                } catch (err) {
+                    if (isMissingTableError(err, `k_${modelID}`)) return [];
+                    throw err;
+                }
+            }));
+            // Merge every grouped row from every model into one bucket per distinct
+            // group-key combination. State stays at the raw sum/count/min/max level (the
+            // v1 accumulator) so the same group appearing in multiple model tables combines
+            // correctly: sums/counts add and min/max merge, making averages Σsum / Σcount
+            // across models rather than the mean of per-model means. The bucket key is a
+            // stable serialisation of the ordered group-key values; a null/absent key value
+            // forms its own bucket (it is never coalesced with other values).
+            const buckets = new Map();
+            for (const rows of modelRows){
+                for (const row of rows){
+                    const keys = {};
+                    for (const group of groupBy){
+                        const value = row[groupKeyAlias(group.keys)];
+                        keys[aggregateFieldName(group.keys)] = value ?? null;
+                    }
+                    const bucketKey = JSON.stringify(groupBy.map((group)=>keys[aggregateFieldName(group.keys)]));
+                    let bucket = buckets.get(bucketKey);
+                    if (bucket == null) {
+                        bucket = {
+                            keys,
+                            acc: createAggregateAccumulator()
+                        };
+                        buckets.set(bucketKey, bucket);
+                    }
+                    accumulateAggregateRow(bucket.acc, aggregates, row);
+                }
+            }
+            const groups = Array.from(buckets.values()).map((bucket)=>({
+                    keys: bucket.keys,
+                    ...finalizeAggregateValues(count, aggregates, bucket.acc)
+                }));
+            // Apply `having` after merging across models and finalising, so derived values
+            // like `average` are available and the predicate runs on the merged group rather
+            // than per-table partials.
+            const filtered = having == null ? groups : groups.filter((group)=>passesHaving(group, having));
+            // Order then limit the merged set, strictly after `having`. Ordering is numeric
+            // or lexical per term with nulls last; the limit takes the top-N of that order.
+            // Without `orderBy` the retained set under a limit is unspecified.
+            const ordered = orderBy != null && orderBy.length > 0 ? [
+                ...filtered
+            ].sort((a, b)=>compareGroups(a, b, orderBy)) : filtered;
+            // Clamp the limit: a negative value would otherwise drop groups from the
+            // end via slice's negative-index semantics rather than capping the count.
+            return limit != null ? ordered.slice(0, Math.max(0, limit)) : ordered;
+        },
+        async listDocuments (params) {
+            const [first, ...rest] = params.modelIDs;
+            let query = db.selectFrom(`k_${first}`).selectAll().where('id', 'in', params.docIDs).where('data', 'is not', null);
+            for (const model of rest){
+                query = query.unionAll((eb)=>{
+                    return eb.selectFrom(`k_${model}`).selectAll().where('id', 'in', params.docIDs).where('data', 'is not', null);
+                });
+            }
+            const rows = await query.execute();
+            return rows.map((row)=>documentNodeFromTable(adapter, row));
+        },
+        async listDocumentModelIDs () {
+            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();
+        },
+        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({
+                status
+            }).where('mutation_hash', '=', mutationHash).execute();
+        },
+        async getMutationLogForDocuments (documentIDs) {
+            if (documentIDs.length === 0) return [];
+            return await db.selectFrom('kubun_graph_mutation_log').selectAll().where('document_id', 'in', documentIDs).orderBy('hlc', 'asc').execute();
+        },
+        async getMaxMutationHLC () {
+            const row = await db.selectFrom('kubun_graph_mutation_log').select((eb)=>eb.fn.max('hlc').as('max_hlc')).executeTakeFirst();
+            return row?.max_hlc ?? null;
+        },
+        async getPendingMutations (documentID) {
+            return await db.selectFrom('kubun_graph_mutation_log').selectAll().where('document_id', '=', documentID).where('status', '=', 'pending').orderBy('hlc', 'asc').execute();
+        },
+        // --- Field HLCs ---
+        async getFieldHLCs (documentID) {
+            const modelID = DocumentID.fromString(documentID).model.toString();
+            const row = await db.selectFrom(`k_${modelID}`).select('field_hlcs').where('id', '=', documentID).executeTakeFirst();
+            if (row?.field_hlcs == null) return null;
+            const hlcs = row.field_hlcs;
+            // ParseJSONResultsPlugin may have already parsed the value
+            if (typeof hlcs === 'string') {
+                return JSON.parse(hlcs);
+            }
+            return hlcs;
+        },
+        async getFieldValues (documentID) {
+            const modelID = DocumentID.fromString(documentID).model.toString();
+            const row = await db.selectFrom(`k_${modelID}`).select('field_values').where('id', '=', documentID).executeTakeFirst();
+            if (row?.field_values == null) return null;
+            const values = row.field_values;
+            // ParseJSONResultsPlugin may have already parsed the value
+            if (typeof values === 'string') {
+                return JSON.parse(values);
+            }
+            return values;
+        },
+        async updateFieldHLCs (docID, fieldHLCs, fieldValues) {
+            const modelID = docID.model.toString();
+            await db.updateTable(`k_${modelID}`).set({
+                field_hlcs: adapter.encodeJSON(fieldHLCs),
+                field_values: adapter.encodeJSON(fieldValues)
+            }).where('id', '=', docID.toString()).execute();
+        },
+        // --- Graph operations ---
+        async listGraphs () {
+            return await db.selectFrom('kubun_graph_models').selectAll().execute();
+        },
+        async createGraph (params) {
+            const graphModelID = params.id;
+            const name = params.name ?? graphModelID;
+            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({
+                    aliases: adapter.encodeJSON(params.aliases ?? {}),
+                    extension_sdl: params.extensionSDL ?? null,
+                    id: graphModelID,
+                    name,
+                    plugin_config: pluginConfigValue,
+                    search: params.search ? adapter.encodeJSON(params.search) : null
+                })// A re-deploy under an existing id that supplies plugins grows the
+                // graph's plugin schema (e.g. adding P2P group types later), so persist
+                // the new extension SDL + plugin config rather than freezing them at
+                // first deploy. A re-deploy without plugins keeps the existing config.
+                // This replaces the whole plugin set, not a per-plugin merge: a
+                // multi-plugin graph re-deployed with a subset would drop the omitted
+                // plugins for all readers. Merge is avoided on purpose — it would
+                // require regenerating SDL from the union, and an engine missing one of
+                // the existing plugins throws "Plugin not found". No call site combines
+                // plugins today; a future multi-plugin deploy would need merge here.
+                .onConflict((oc)=>params.pluginConfig != null ? oc.column('id').doUpdateSet({
+                        extension_sdl: params.extensionSDL ?? null,
+                        plugin_config: pluginConfigValue
+                    }) : oc.doNothing()).execute();
+                const entries = Object.entries(params.record);
+                const added = new Set();
+                while(added.size < entries.length){
+                    const toAdd = entries.filter(([id, model])=>{
+                        return !added.has(id) && model.interfaces.every((iid)=>added.has(toGlobalInterfaceID(id, iid)));
+                    });
+                    if (toAdd.length === 0) {
+                        throw new Error('Could not create graph: no valid model to add');
+                    }
+                    await Promise.all(toAdd.map(async ([id, model])=>{
+                        await addDocumentModel(trx, adapter, {
+                            id,
+                            graphModelID,
+                            model
+                        });
+                        added.add(id);
+                    }));
+                }
+            });
+            return graphModelID;
+        },
+        async getGraph (id) {
+            const graph = await db.selectFrom('kubun_graph_models').selectAll().where('id', '=', id).executeTakeFirst();
+            if (graph == null) {
+                return null;
+            }
+            const record = {};
+            const rows = await db.selectFrom('kubun_graph_document_model_links').innerJoin('kubun_graph_document_models', 'kubun_graph_document_model_links.document_model_id', 'kubun_graph_document_models.id').selectAll('kubun_graph_document_models').where('kubun_graph_document_model_links.graph_model_id', '=', id).execute();
+            for (const row of rows){
+                record[row.id] = documentModelFromTable(row);
+            }
+            return {
+                ...graph,
+                record
+            };
+        },
+        // --- Cluster operations ---
+        async getClusterForModel (modelID) {
+            const result = await db.selectFrom('kubun_graph_cluster_models').select('cluster_id').where('model_id', '=', modelID).executeTakeFirst();
+            return result?.cluster_id;
+        },
+        async getClusterModels (clusterID) {
+            return await db.selectFrom('kubun_graph_cluster_models').selectAll().where('cluster_id', '=', clusterID).orderBy('cluster_index').execute();
+        },
+        async saveCluster (id, definition) {
+            await db.insertInto('kubun_graph_clusters').values({
+                id,
+                definition: adapter.encodeJSON(definition)
+            }).onConflict((oc)=>oc.column('id').doUpdateSet((eb)=>({
+                        definition: eb.ref('excluded.definition')
+                    }))).execute();
+        },
+        async getCluster (id) {
+            return await db.selectFrom('kubun_graph_clusters').selectAll().where('id', '=', id).executeTakeFirst();
+        },
+        async getClusters (ids) {
+            if (ids.length === 0) return {};
+            const rows = await db.selectFrom('kubun_graph_clusters').selectAll().where('id', 'in', ids).execute();
+            const result = {};
+            for (const row of rows){
+                result[row.id] = row.definition;
+            }
+            return result;
+        },
+        // --- Attachments ---
+        async addAttachments (attachments) {
+            await db.insertInto('kubun_graph_document_attachments').values(attachments).onConflict((oc)=>oc.doNothing()).execute();
+        },
+        // --- Search ---
+        async createSearchIndex (modelID, fields) {
+            await adapter.createSearchIndex(db, {
+                modelID,
+                fields
+            });
+        },
+        async dropSearchIndex (modelID) {
+            await adapter.dropSearchIndex(db, modelID);
+        },
+        async updateSearchEntry (modelID, documentID, data, fields) {
+            const fieldValues = {};
+            for (const field of fields){
+                const value = extractFieldValue(data, field);
+                if (value != null) {
+                    fieldValues[field] = String(value);
+                }
+            }
+            await adapter.updateSearchEntry(db, modelID, documentID, fieldValues, fields);
+        },
+        async removeSearchEntry (modelID, documentID) {
+            await adapter.removeSearchEntry(db, modelID, documentID);
+        },
+        async searchDocuments (params) {
+            const allResults = [];
+            for (const modelID of params.modelIDs){
+                const hits = await adapter.searchIndex(db, {
+                    query: params.query,
+                    modelID,
+                    limit: params.first ?? 50
+                });
+                for (const hit of hits){
+                    allResults.push({
+                        documentID: hit.documentID,
+                        modelID,
+                        rank: hit.rank
+                    });
+                }
+            }
+            // Sort by absolute rank descending (SQLite bm25 returns negative, PG ts_rank positive)
+            allResults.sort((a, b)=>Math.abs(b.rank) - Math.abs(a.rank));
+            if (params.first) {
+                return allResults.slice(0, params.first);
+            }
+            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
+            }).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;
+            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;
+            await db.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();
+        },
+        // --- User model access defaults ---
+        async getUserModelAccessDefault (ownerDID, modelID, permissionType) {
+            const result = await db.selectFrom('kubun_graph_user_model_access_defaults').select([
+                'access_level',
+                'allowed_dids',
+                'allowed_circles',
+                'allowed_groups'
+            ]).where('owner_did', '=', ownerDID).where('model_id', '=', modelID).where('permission_type', '=', permissionType).executeTakeFirst();
+            if (!result) {
+                return null;
+            }
+            return {
+                level: result.access_level,
+                allowedDIDs: result.allowed_dids,
+                allowedCircles: result.allowed_circles,
+                allowedGroups: result.allowed_groups
+            };
+        },
+        async setUserModelAccessDefault (params) {
+            await db.insertInto('kubun_graph_user_model_access_defaults').values({
+                owner_did: params.ownerDID,
+                model_id: params.modelID,
+                permission_type: params.permissionType,
+                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({
+                    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,
+                    updated_at: adapter.encodeTimestamp(new Date())
+                })).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();
+        },
+        // --- Document scope / metadata helpers ---
+        async getDocumentIDsForScope (scopes, excludedDocumentIDs = []) {
+            const docIDs = [];
+            for (const scope of scopes){
+                try {
+                    const docs = await db.selectFrom(`k_${scope.modelID}`).select('id').where('owner', '=', scope.ownerDID).execute();
+                    docIDs.push(...docs.map((d)=>d.id));
+                } catch (err) {
+                    if (!isMissingTableError(err, `k_${scope.modelID}`)) throw err;
+                }
+            }
+            if (excludedDocumentIDs.length > 0) {
+                const excluded = new Set(excludedDocumentIDs);
+                return docIDs.filter((id)=>!excluded.has(id));
+            }
+            return docIDs;
+        },
+        async getDocumentMetadataForSync (modelID, documentIDs) {
+            if (documentIDs.length === 0) return [];
+            const rows = await db.selectFrom(`k_${modelID}`).select([
+                'id',
+                'model',
+                'owner'
+            ]).where('id', 'in', documentIDs).execute();
+            return rows.map((r)=>({
+                    id: r.id,
+                    model: r.model,
+                    owner: r.owner
+                }));
+        }
+    };
+    return api;
+}