@kubun/store-graph 0.17.0 → 0.17.1

package/lib/api.d.ts

@@ -1,8 +1,36 @@
 import type { Adapter } from '@kubun/db-adapter';
 import { DocumentID, DocumentModelID } from '@kubun/id';
-import type { AggregateDocumentsParams, AggregateValues, DocumentModel, DocumentNode, GroupedAggregateDocumentsParams, GroupedAggregateValue } from '@kubun/protocol';
+import type { AggregateDocumentsParams, AggregateValues, DocumentFieldsMeta, DocumentModel, DocumentModelSchema, DocumentNode, GroupedAggregateDocumentsParams, GroupedAggregateValue } from '@kubun/protocol';
 import type { Kysely } from 'kysely';
-import type { AccessLevel, Catalog, ClusterDefinitionRow, ClusterModel, CreateDocumentParams, CreateGraphParams, GraphModel, GraphModelWithRecord, GraphTables, InsertCatalog, InsertClusterModel, InsertMutationLogEntry, ListDocumentsParams, MutationLogEntry, QueryDocumentsParams, QueryDocumentsResult, SaveDocumentParams, SearchDocumentResult, SearchDocumentsParams } from './tables.js';
+import type { AccessLevel, Catalog, ClusterDefinitionRow, ClusterModel, CreateDocumentParams, CreateGraphParams, DocumentModelRow, GraphModel, GraphModelWithRecord, GraphTables, InsertCatalog, InsertClusterModel, InsertMutationLogEntry, ListDocumentsParams, MutationLogEntry, QueryDocumentsParams, QueryDocumentsResult, SaveDocumentParams, SearchDocumentResult, SearchDocumentsParams } from './tables.js';
+export declare function documentModelFromTable(row: DocumentModelRow): DocumentModel;
+export declare function documentModelToTable(adapter: Adapter, id: string, model: DocumentModel): {
+    id: string;
+    version: "1.0";
+    name: string;
+    behavior: "unique" | "default" | "interface";
+    unique_fields: string[] | null;
+    interfaces: Array<string>;
+    schema: DocumentModelSchema;
+    fields_meta: DocumentFieldsMeta;
+    provider_merge_policy: {
+        group: Array<string>;
+    } | null;
+};
+/**
+ * Reads a document's `field_values` cell on the given transaction and
+ * delegates the merge-policy liveness comparison to `@kubun/mutation`'s pure
+ * `winnerStateDigestOf`. Returns the winning live `$setFetch` digest, the
+ * constant deleted-state digest when the delete side wins, or `null` when the
+ * document (or its fetch-order registers) is absent.
+ *
+ * Because graph and connector tables share one DB connection (the KubunDB
+ * coordinator), a caller with its own transaction over a wider `DB` type
+ * passes it here cast to `Kysely<GraphTables>` (the same pattern
+ * `addDocumentModel` above already relies on) so the read joins that
+ * transaction rather than opening a second connection.
+ */
+export declare function readWinnerStateDigest(tx: Kysely<GraphTables>, documentID: string): Promise<string | null>;
 /**
  * Persisted access rule shape as stored in `user_model_access_defaults`.
  */

package/lib/api.js

@@ -1,4 +1,5 @@
 import { DocumentID, DocumentModelID } from '@kubun/id';
+import { winnerStateDigestOf } from '@kubun/mutation';
 import { serializeCursor } from './cursor.js';
 import { isMissingTableError, ModelNotDeployedError } from './errors.js';
 import { aggregateFieldName, applyAggregateSelections, applyDocumentFilter, applyDocumentOrderBy, applyGroupBySelections, applyPagination, groupKeyAlias, knownFieldColumn } from './query-builder.js';
@@ -254,21 +255,22 @@ function compareGroups(a, b, orderBy) {
     }
     return 0;
 }
-function documentModelFromTable(row) {
+export function documentModelFromTable(row) {
     const model = {
         version: row.version,
         name: row.name,
         behavior: row.behavior,
         interfaces: row.interfaces,
         schema: row.schema,
-        fieldsMeta: row.fields_meta
+        fieldsMeta: row.fields_meta,
+        providerMergePolicy: row.provider_merge_policy ?? undefined
     };
     if (model.behavior === 'unique') {
         model.uniqueFields = row.unique_fields;
     }
     return model;
 }
-function documentModelToTable(adapter, id, model) {
+export function documentModelToTable(adapter, id, model) {
     return {
         id,
         version: model.version,
@@ -277,7 +279,8 @@ function documentModelToTable(adapter, id, model) {
         unique_fields: model.behavior === 'unique' ? adapter.encodeJSON(model.uniqueFields) : null,
         interfaces: adapter.encodeJSON(model.interfaces),
         schema: adapter.encodeJSON(model.schema),
-        fields_meta: adapter.encodeJSON(model.fieldsMeta)
+        fields_meta: adapter.encodeJSON(model.fieldsMeta),
+        provider_merge_policy: model.providerMergePolicy ? adapter.encodeJSON(model.providerMergePolicy) : null
     };
 }
 function documentNodeFromTable(adapter, doc) {
@@ -322,6 +325,29 @@ async function addDocumentModel(transaction, adapter, params) {
         document_model_id: id
     }).onConflict((oc)=>oc.doNothing()).execute();
 }
+// --- Cross-plan export: tx-scoped merge-policy winner read ---
+/**
+ * Reads a document's `field_values` cell on the given transaction and
+ * delegates the merge-policy liveness comparison to `@kubun/mutation`'s pure
+ * `winnerStateDigestOf`. Returns the winning live `$setFetch` digest, the
+ * constant deleted-state digest when the delete side wins, or `null` when the
+ * document (or its fetch-order registers) is absent.
+ *
+ * Because graph and connector tables share one DB connection (the KubunDB
+ * coordinator), a caller with its own transaction over a wider `DB` type
+ * passes it here cast to `Kysely<GraphTables>` (the same pattern
+ * `addDocumentModel` above already relies on) so the read joins that
+ * transaction rather than opening a second connection.
+ */ export async function readWinnerStateDigest(tx, documentID) {
+    const modelID = DocumentID.fromString(documentID).model.toString();
+    const row = await tx.selectFrom(`k_${modelID}`).select('field_values').where('id', '=', documentID).executeTakeFirst();
+    if (row?.field_values == null) {
+        return null;
+    }
+    // ParseJSONResultsPlugin may have already parsed the value.
+    const fieldValues = typeof row.field_values === 'string' ? JSON.parse(row.field_values) : row.field_values;
+    return winnerStateDigestOf(fieldValues);
+}
 // --- Factory function ---
 export function createGraphStore(db, adapter) {
     const coerce = adapter.coerceFilterValue.bind(adapter);
@@ -443,7 +469,9 @@ export function createGraphStore(db, adapter) {
                 id,
                 owner: params.owner,
                 model,
-                data: adapter.encodeJSON(params.data),
+                // Null data (a first-seen tombstone establishing a dead row) persists
+                // as SQL null, not the JSON string "null" — mirrors `saveDocument`.
+                data: params.data ? adapter.encodeJSON(params.data) : null,
                 unique: adapter.encodeBinary(params.unique)
             }).returningAll().executeTakeFirstOrThrow(()=>new Error(`createDocument failed to return row for ${id}`));
             if (params.data) {

package/lib/index.d.ts

@@ -1,7 +1,7 @@
 import type { StoreProvider } from '@kubun/db';
 import type { GraphStoreAPI } from './api.js';
 export type { GraphStoreAPI, StoredAccessDefaultRow, StoredAccessRule } from './api.js';
-export { createGraphStore } from './api.js';
+export { createGraphStore, readWinnerStateDigest } from './api.js';
 export { graphStoreDefinition } from './definition.js';
 export { ModelNotDeployedError } from './errors.js';
 export { resolveSearchableFields, SearchNotEnabledError } from './search.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { createGraphStore } from './api.js';
+export { createGraphStore, readWinnerStateDigest } from './api.js';
 export { graphStoreDefinition } from './definition.js';
 export { ModelNotDeployedError } from './errors.js';
 export { resolveSearchableFields, SearchNotEnabledError } from './search.js';

package/lib/migrations.js

@@ -16,7 +16,7 @@
     const init = {
         async up (db) {
             // Document models
-            await db.schema.createTable('kubun_graph_document_models').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('version', t.text, (col)=>col.notNull()).addColumn('name', t.text, (col)=>col.notNull()).addColumn('behavior', t.text, (col)=>col.notNull()).addColumn('unique_fields', t.json).addColumn('interfaces', t.json, (col)=>col.notNull()).addColumn('schema', t.json, (col)=>col.notNull()).addColumn('fields_meta', t.json, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
+            await db.schema.createTable('kubun_graph_document_models').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('version', t.text, (col)=>col.notNull()).addColumn('name', t.text, (col)=>col.notNull()).addColumn('behavior', t.text, (col)=>col.notNull()).addColumn('unique_fields', t.json).addColumn('interfaces', t.json, (col)=>col.notNull()).addColumn('schema', t.json, (col)=>col.notNull()).addColumn('fields_meta', t.json, (col)=>col.notNull()).addColumn('provider_merge_policy', t.json).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).execute();
             // Document model interfaces
             await db.schema.createTable('kubun_graph_document_model_interfaces').ifNotExists().addColumn('interface_id', t.text, (col)=>col.notNull().references('kubun_graph_document_models.id')).addColumn('implementation_id', t.text, (col)=>col.notNull().references('kubun_graph_document_models.id')).addUniqueConstraint('kubun_graph_document_model_interfaces_pkey', [
                 'interface_id',

package/lib/tables.d.ts

@@ -27,6 +27,9 @@ export type DocumentModelTable = {
     interfaces: JSONValueColumn<Array<string>>;
     schema: JSONValueColumn<DocumentModelSchema>;
     fields_meta: JSONValueColumn<DocumentFieldsMeta>;
+    provider_merge_policy: JSONValueColumn<{
+        group: Array<string>;
+    }> | null;
     created_at: CreatedAtColumn;
     updated_at: UpdatedAtColumn;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-graph",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -18,13 +18,14 @@
     "@kubun/db": "^0.17.0",
     "@kubun/db-adapter": "^0.17.0",
     "@kubun/id": "^0.17.0",
-    "@kubun/protocol": "^0.17.0",
+    "@kubun/mutation": "^0.17.1",
+    "@kubun/protocol": "^0.17.1",
     "@sozai/codec": "^0.4.0",
-    "kysely": "^0.29.5"
+    "kysely": "^0.29.6"
   },
   "devDependencies": {
     "@kubun/db-better-sqlite": "^0.17.0",
-    "@kubun/db-postgres": "^0.17.0",
+    "@kubun/db-postgres": "^0.17.1",
     "@testcontainers/postgresql": "^12.1.0"
   },
   "publishConfig": {