@kubun/store-graph 0.17.1 → 0.18.0

package/lib/migrations.js

@@ -1,22 +1,21 @@
+import { sql } from 'kysely';
 /**
- * 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.
+ * A shipped migration should be immutable: once a database has run it, editing
+ * it changes nothing on that database and silently diverges its schema from the
+ * code. Schema changes after a release that preserves databases need a NEW
+ * migration.
  *
- * `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.
+ * `0-init` was edited in place again for the pending arrival group, sender, retry columns and
+ * due index. Existing databases will not acquire them and must be recreated.
+ * This is a breaking reset. Do NOT repeat an in-place edit once a release that
+ * must preserve existing databases ships; add a new migration then.
  */ export function getGraphMigrations(ctx) {
     const t = ctx.types;
     const now = ctx.functions.now;
     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('provider_merge_policy', t.json).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('date_field', t.text).addColumn('resolved_date_field', t.text).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',
@@ -47,22 +46,97 @@
                 'owner_did',
                 'model_id'
             ]).execute();
+            // The group row serialises concurrent parking on PostgreSQL. SQLite serialises writers.
+            await db.schema.createTable('kubun_graph_pending_groups').ifNotExists().addColumn('group_id', t.text, (col)=>col.primaryKey()).execute();
             // Mutation log
-            await db.schema.createTable('kubun_graph_mutation_log').ifNotExists().addColumn('mutation_hash', t.text, (col)=>col.primaryKey()).addColumn('model_id', t.text, (col)=>col.notNull()).addColumn('document_id', t.text, (col)=>col.notNull()).addColumn('author_did', t.text, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('mutation_jwt', t.text, (col)=>col.notNull()).addColumn('status', t.text, (col)=>col.notNull().defaultTo('applied')).execute();
+            await db.schema.createTable('kubun_graph_mutation_log').ifNotExists().addColumn('mutation_hash', t.text, (col)=>col.primaryKey()).addColumn('model_id', t.text, (col)=>col.notNull()).addColumn('document_id', t.text, (col)=>col.notNull()).addColumn('author_did', t.text, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('mutation_jwt', t.text, (col)=>col.notNull()).addColumn('arrival_group_id', t.text).addColumn('sender_peer_did', t.text).addColumn('parked_at', t.bigint).addColumn('status', t.text, (col)=>col.notNull().defaultTo('applied')).addColumn('attempt_count', 'integer', (col)=>col.notNull().defaultTo(0)).addColumn('last_attempt_at', t.bigint).addColumn('next_attempt_at', t.bigint).execute();
             await db.schema.createIndex('idx_graph_mutation_log_hlc').ifNotExists().on('kubun_graph_mutation_log').column('hlc').execute();
             await db.schema.createIndex('idx_graph_mutation_log_document').ifNotExists().on('kubun_graph_mutation_log').column('document_id').execute();
             await db.schema.createIndex('idx_graph_mutation_log_status').ifNotExists().on('kubun_graph_mutation_log').column('status').execute();
+            await db.schema.createIndex('idx_graph_mutation_log_pending_group').ifNotExists().on('kubun_graph_mutation_log').columns([
+                'status',
+                'arrival_group_id',
+                'sender_peer_did'
+            ]).execute();
+            await db.schema.createIndex('idx_graph_mutation_log_due_pending').ifNotExists().on('kubun_graph_mutation_log').columns([
+                'status',
+                'next_attempt_at'
+            ]).execute();
+            await db.schema.createTable('kubun_graph_catalog_use').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('catalog_id', t.text, (col)=>col.notNull()).addColumn('name', t.text, (col)=>col.notNull()).addColumn('rules', t.json, (col)=>col.notNull()).addColumn('level', t.text).addColumn('followed', 'integer', (col)=>col.notNull().defaultTo(0)).addPrimaryKeyConstraint('kubun_graph_catalog_use_pkey', [
+                'owner_did',
+                'catalog_id'
+            ]).execute();
+            await db.schema.createTable('kubun_graph_scope_identity').ifNotExists().addColumn('id', 'integer', (col)=>col.primaryKey()).addColumn('reader_did', t.text, (col)=>col.notNull()).addColumn('default_read_level', t.text, (col)=>col.notNull()).execute();
+            await db.schema.createTable('kubun_graph_catalog_scope_tick').ifNotExists().addColumn('id', 'integer', (col)=>col.primaryKey()).addColumn('last_at', t.bigint, (col)=>col.notNull()).execute();
+            await db.schema.createTable('kubun_graph_scope_changes').ifNotExists().addColumn('document_id', t.text, (col)=>col.primaryKey()).addColumn('version', 'integer', (col)=>col.notNull()).execute();
+            await db.schema.createTable('kubun_graph_document_refs').ifNotExists().addColumn('document_id', t.text, (col)=>col.notNull()).addColumn('ref', t.text, (col)=>col.notNull()).addColumn('displays', 'integer', (col)=>col.notNull()).addColumn('retains', 'integer', (col)=>col.notNull()).addPrimaryKeyConstraint('kubun_graph_document_refs_pkey', [
+                'document_id',
+                'ref'
+            ]).execute();
+            await db.schema.createTable('kubun_graph_gc_marks').ifNotExists().addColumn('document_id', t.text, (col)=>col.primaryKey()).addColumn('digest', t.text, (col)=>col.notNull()).addColumn('marked_at', t.bigint, (col)=>col.notNull()).execute();
+            await db.schema.createTable('kubun_graph_custody_scans').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('catalog_id', t.text, (col)=>col.notNull()).addColumn('after_document_id', t.text).addPrimaryKeyConstraint('kubun_graph_custody_scans_pkey', [
+                'owner_did',
+                'catalog_id'
+            ]).execute();
+            await db.schema.createTable('kubun_graph_custody_nonces').ifNotExists().addColumn('nonce', t.text, (col)=>col.primaryKey()).addColumn('custodian', t.text, (col)=>col.notNull()).addColumn('assignment_digest', t.text, (col)=>col.notNull()).addColumn('expires_at', t.bigint, (col)=>col.notNull()).execute();
+            await db.schema.createTable('kubun_graph_custody_receipts').ifNotExists().addColumn('document_id', t.text, (col)=>col.notNull()).addColumn('custodian', t.text, (col)=>col.notNull()).addColumn('group_id', t.text, (col)=>col.notNull()).addColumn('custody_owner', t.text, (col)=>col.notNull()).addColumn('catalog_owner', t.text, (col)=>col.notNull()).addColumn('catalog_id', t.text, (col)=>col.notNull()).addColumn('assignment_digest', t.text, (col)=>col.notNull()).addColumn('head_digest', t.text, (col)=>col.notNull()).addColumn('mutation_digest', t.text, (col)=>col.notNull()).addColumn('received_at', t.bigint, (col)=>col.notNull()).addPrimaryKeyConstraint('kubun_graph_custody_receipts_pkey', [
+                'document_id',
+                'custodian'
+            ]).execute();
+            await db.schema.createTable('kubun_graph_document_holds').ifNotExists().addColumn('hold_id', t.text, (col)=>col.primaryKey()).addColumn('document_id', t.text, (col)=>col.notNull()).addColumn('created_by', t.text, (col)=>col.notNull()).addColumn('reason', t.text).addColumn('expires_at', t.bigint).addColumn('released_at', t.bigint).execute();
+            await db.schema.createIndex('idx_graph_document_holds_document').ifNotExists().on('kubun_graph_document_holds').column('document_id').execute();
+            // Aging finds the holds that expired since its last tick.
+            await db.schema.createIndex('idx_graph_document_holds_expires_at').ifNotExists().on('kubun_graph_document_holds').column('expires_at').execute();
+            await db.schema.createTable('kubun_graph_document_scope_dates').ifNotExists().addColumn('document_id', t.text, (col)=>col.notNull()).addColumn('field', t.text, (col)=>col.notNull()).addColumn('scope_date', t.bigint, (col)=>col.notNull()).addPrimaryKeyConstraint('kubun_graph_document_scope_dates_pkey', [
+                'document_id',
+                'field'
+            ]).execute();
+            // Documents this device swept: what a ref recompute reads of each, so a rule matching it
+            // again can be told apart from a document never received. Local only.
+            await db.schema.createTable('kubun_graph_swept_documents').ifNotExists().addColumn('document_id', t.text, (col)=>col.primaryKey()).addColumn('model_id', t.text, (col)=>col.notNull()).addColumn('owner', t.text, (col)=>col.notNull()).addColumn('created_at', t.bigint, (col)=>col.notNull()).addColumn('scope_date', t.bigint).addColumn('field_dates', t.text, (col)=>col.notNull()).addColumn('read_access', t.text).addColumn('mutation_digest', t.text, (col)=>col.notNull()).addColumn('swept_at', t.bigint, (col)=>col.notNull()).addColumn('in_scope', 'integer', (col)=>col.notNull()).addColumn('scope_left_at', t.bigint, (col)=>col.notNull()).execute();
+            await db.schema.createIndex('idx_graph_swept_documents_model').ifNotExists().on('kubun_graph_swept_documents').column('model_id').execute();
+            await db.schema.createIndex('idx_graph_document_scope_dates_window').ifNotExists().on('kubun_graph_document_scope_dates').columns([
+                'field',
+                'scope_date'
+            ]).execute();
+            // Catalog holder lookups are bytewise prefix ranges. On Postgres they
+            // compare `ref collate "C"`, which an index under a linguistic database
+            // collation cannot serve; SQLite compares bytewise already.
+            const refIndex = db.schema.createIndex('idx_graph_document_refs_ref').ifNotExists().on('kubun_graph_document_refs');
+            await (ctx.dialect === 'postgres' ? refIndex.expression(sql`ref collate "C"`) : refIndex.column('ref')).execute();
             // Cluster models (model -> cluster mapping)
             await db.schema.createTable('kubun_graph_cluster_models').ifNotExists().addColumn('model_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('cluster_id', t.text, (col)=>col.notNull()).addColumn('cluster_index', 'integer', (col)=>col.notNull()).execute();
             await db.schema.createIndex('idx_graph_cluster_models_cluster').ifNotExists().on('kubun_graph_cluster_models').column('cluster_id').execute();
             // 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();
+            await db.schema.createTable('kubun_graph_access_default_records').ifNotExists().addColumn('type', t.text, (col)=>col.notNull()).addColumn('owner', t.text, (col)=>col.notNull()).addColumn('id', t.text, (col)=>col.notNull()).addColumn('op_hash', t.text, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('op_jwt', t.text, (col)=>col.notNull()).addColumn('payload', t.binary).addPrimaryKeyConstraint('kubun_graph_access_default_records_pkey', [
+                'type',
+                'owner',
+                'id'
+            ]).execute();
+            await db.schema.createTable('kubun_graph_catalog_drafts').ifNotExists().addColumn('catalog_id', t.text, (col)=>col.primaryKey()).addColumn('state', t.text, (col)=>col.notNull()).execute();
+            await db.schema.createTable('kubun_graph_catalog_publications').ifNotExists().addColumn('catalog_id', t.text, (col)=>col.notNull()).addColumn('version_id', t.text, (col)=>col.notNull()).addPrimaryKeyConstraint('kubun_graph_catalog_publications_pkey', [
+                'catalog_id',
+                'version_id'
+            ]).execute();
+            await db.schema.createTable('kubun_graph_catalog_recipient_versions').ifNotExists().addColumn('catalog_id', t.text, (col)=>col.notNull()).addColumn('version_id', t.text, (col)=>col.notNull()).addColumn('signed_record', t.text, (col)=>col.notNull()).addPrimaryKeyConstraint('kubun_graph_catalog_recipient_versions_pkey', [
+                'catalog_id',
+                'version_id'
+            ]).execute();
+            await db.schema.createTable('kubun_graph_catalog_pending_heads').ifNotExists().addColumn('catalog_id', t.text, (col)=>col.primaryKey()).addColumn('head_version_id', t.text, (col)=>col.notNull()).addColumn('group_id', t.text).addColumn('retry_at', t.bigint, (col)=>col.notNull()).addColumn('attempts', 'integer', (col)=>col.notNull()).execute();
+            await db.schema.createTable('kubun_graph_catalog_admitted_heads').ifNotExists().addColumn('catalog_id', t.text, (col)=>col.primaryKey()).addColumn('signed_record', t.text, (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())// 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();
+            await db.schema.createTable('kubun_graph_catalog_records').ifNotExists().addColumn('type', t.text, (col)=>col.notNull()).addColumn('owner', t.text, (col)=>col.notNull()).addColumn('id', t.text, (col)=>col.notNull()).addColumn('op_hash', t.text, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('op_jwt', t.text, (col)=>col.notNull()).addColumn('payload', t.binary).addColumn('catalog_id', t.text).addColumn('group_id', t.text).addColumn('circle_id', t.text).addPrimaryKeyConstraint('kubun_graph_catalog_records_pkey', [
+                'type',
+                'owner',
+                'id',
+                'op_hash'
+            ]).execute();
+            await db.schema.createIndex('idx_graph_catalog_record_group').ifNotExists().on('kubun_graph_catalog_records').columns([
+                'group_id',
+                'catalog_id',
+                'circle_id'
+            ]).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
@@ -85,11 +159,30 @@
             }
         },
         async down (db) {
+            await db.schema.dropTable('kubun_graph_catalog_drafts').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_catalog_publications').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_catalog_recipient_versions').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_catalog_pending_heads').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_catalog_admitted_heads').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_access_default_records').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_catalog_records').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_scope_changes').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_catalog_scope_tick').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_scope_identity').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_document_scope_dates').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_swept_documents').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_gc_marks').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_custody_scans').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_custody_nonces').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_custody_receipts').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_document_holds').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_document_refs').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_catalog_use').ifExists().execute();
             await db.schema.dropTable('kubun_graph_search_models').ifExists().execute();
-            await db.schema.dropTable('kubun_graph_catalogs').ifExists().execute();
             await db.schema.dropTable('kubun_graph_clusters').ifExists().execute();
             await db.schema.dropTable('kubun_graph_cluster_models').ifExists().execute();
             await db.schema.dropTable('kubun_graph_mutation_log').ifExists().execute();
+            await db.schema.dropTable('kubun_graph_pending_groups').ifExists().execute();
             await db.schema.dropTable('kubun_graph_user_model_access_defaults').ifExists().execute();
             await db.schema.dropTable('kubun_graph_document_model_links').ifExists().execute();
             await db.schema.dropTable('kubun_graph_models').ifExists().execute();

package/lib/query-builder.js

@@ -315,7 +315,7 @@ export function applyValueFilter(eb, keys, filter, adapter, coerce) {
                 const items = [
                     ...new Set(value)
                 ];
-                // Vacuously true (D7): every array includes the empty set. Handled here, not in
+                // Vacuously true: 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);
             }

package/lib/tables.d.ts

@@ -1,7 +1,7 @@
 import type { CreatedAtColumn, UpdatedAtColumn } from '@kubun/db-adapter';
 import type { DocumentID } from '@kubun/id';
-import type { CatalogFilterCriteria, DocumentFieldsMeta, DocumentFilter, DocumentModelSchema, DocumentModelsRecord, DocumentNode, DocumentOrderBy } from '@kubun/protocol';
-import type { ColumnType, Insertable, Selectable, Updateable } from 'kysely';
+import type { AccessLevel, DocumentFieldsMeta, DocumentFilter, DocumentModel, DocumentModelSchema, DocumentModelsRecord, DocumentNode, DocumentOrderBy } from '@kubun/protocol';
+import type { ColumnType, Generated, Insertable, Selectable, Updateable } from 'kysely';
 type JSONValueColumn<T> = ColumnType<T, T, T>;
 export type DocumentData = Record<string, unknown>;
 export type DocumentTable<Data extends DocumentData = DocumentData> = {
@@ -14,6 +14,9 @@ export type DocumentTable<Data extends DocumentData = DocumentData> = {
     unique: Uint8Array;
     created_at: CreatedAtColumn;
     updated_at: UpdatedAtColumn;
+    mutation_created_at: ColumnType<number | null, number | null | undefined, number | null>;
+    mutation_updated_at: ColumnType<number | null, number | null | undefined, number | null>;
+    scope_date: ColumnType<number | null, number | null | undefined, number | null>;
 };
 export type Document<Data extends DocumentData = DocumentData> = Selectable<DocumentTable<Data>>;
 export type InsertDocument<Data extends DocumentData = DocumentData> = Insertable<DocumentTable<Data>>;
@@ -30,6 +33,8 @@ export type DocumentModelTable = {
     provider_merge_policy: JSONValueColumn<{
         group: Array<string>;
     }> | null;
+    date_field: ColumnType<string | null, string | null | undefined, string | null>;
+    resolved_date_field: ColumnType<string | null, string | null | undefined, string | null>;
     created_at: CreatedAtColumn;
     updated_at: UpdatedAtColumn;
 };
@@ -74,13 +79,139 @@ export type MutationLogTable = {
     mutation_hash: string;
     model_id: string;
     document_id: string;
+    /** Unverified signed issuer, informational only. Caps and authorisation use sender_peer_did. */
     author_did: string;
     hlc: string;
     mutation_jwt: string;
+    arrival_group_id: ColumnType<string | null, string | null | undefined, string | null>;
+    sender_peer_did: ColumnType<string | null, string | null | undefined, string | null>;
+    parked_at: ColumnType<number | null, number | null | undefined, number | null>;
     status: string;
+    attempt_count: Generated<number>;
+    last_attempt_at: ColumnType<number | null, number | null | undefined, number | null>;
+    next_attempt_at: ColumnType<number | null, number | null | undefined, number | null>;
 };
 export type MutationLogEntry = Selectable<MutationLogTable>;
 export type InsertMutationLogEntry = Insertable<MutationLogTable>;
+/**
+ * One concrete rule as a document-leaf page selects by it: a model, the owners
+ * (null: any owner), and an optional window `[from, to)` over a date field.
+ */
+export type DocumentLeafRule = {
+    modelID: string;
+    owners: ReadonlyArray<string> | null;
+    dateField: string | null;
+    from: number | null;
+    to: number | null;
+};
+export type DocumentLeafPageParams = {
+    groupRead?: {
+        groupID: string;
+        circleIDs: Array<string>;
+    };
+    rules: ReadonlyArray<DocumentLeafRule>;
+    /** Exclusive lower document key; null starts at the first key. */
+    after: string | null;
+    /** Inclusive upper document key; null reads to the last key. */
+    through?: string | null;
+    limit: number;
+};
+/** A stored document matching a rule, with the IDs of its applied mutations, sorted. */
+export type DocumentLeafRow = {
+    documentID: string;
+    owner: string;
+    /** The document was created on this device rather than received. */
+    authoredHere: boolean;
+    acceptedMutationIDs: Array<string>;
+};
+export type CatalogUseTable = {
+    owner_did: string;
+    catalog_id: string;
+    name: string;
+    rules: JSONValueColumn<Array<{
+        id: string;
+        models?: Array<string>;
+        owners?: Array<string>;
+        maxAge?: string;
+        maxAhead?: string;
+        dateField?: string;
+    }>>;
+    level: 'KNOWN' | 'OFFLINE' | 'SERVE_ONLY' | null;
+    followed: number;
+};
+export type DocumentRefTable = {
+    document_id: string;
+    ref: string;
+    displays: number;
+    retains: number;
+};
+export type CustodyScanTable = {
+    owner_did: string;
+    catalog_id: string;
+    after_document_id: string | null;
+};
+export type GCMarkTable = {
+    document_id: string;
+    digest: string;
+    marked_at: number;
+};
+export type CustodyNonceTable = {
+    nonce: string;
+    custodian: string;
+    assignment_digest: string;
+    expires_at: number;
+};
+export type CustodyReceiptTable = {
+    document_id: string;
+    custodian: string;
+    group_id: string;
+    custody_owner: string;
+    catalog_owner: string;
+    catalog_id: string;
+    assignment_digest: string;
+    head_digest: string;
+    mutation_digest: string;
+    received_at: number;
+};
+export type DocumentHoldTable = {
+    hold_id: string;
+    document_id: string;
+    created_by: string;
+    reason: string | null;
+    expires_at: number | null;
+    released_at: number | null;
+};
+export type DocumentScopeDateTable = {
+    document_id: string;
+    field: string;
+    scope_date: number;
+};
+export type SweptDocumentTable = {
+    document_id: string;
+    model_id: string;
+    owner: string;
+    created_at: number;
+    scope_date: number | null;
+    field_dates: string;
+    read_access: string | null;
+    mutation_digest: string;
+    swept_at: number;
+    in_scope: number;
+    scope_left_at: number;
+};
+export type ScopeIdentityTable = {
+    id: number;
+    reader_did: string;
+    default_read_level: AccessLevel;
+};
+export type CatalogScopeTickTable = {
+    id: number;
+    last_at: number;
+};
+export type CatalogScopeChangeTable = {
+    document_id: string;
+    version: number;
+};
 export type ClusterModelTable = {
     model_id: string;
     cluster_id: string;
@@ -111,45 +242,58 @@ export type UserModelAccessDefaultTable = {
 export type UserModelAccessDefault = Selectable<UserModelAccessDefaultTable>;
 export type InsertUserModelAccessDefault = Insertable<UserModelAccessDefaultTable>;
 export type UpdateUserModelAccessDefault = Updateable<UserModelAccessDefaultTable>;
-export type CatalogTable = {
+export type GraphCatalogRecordTable = {
+    type: string;
+    owner: string;
     id: string;
-    owner_did: string;
-    name: string;
-    description: string;
-    filter_criteria: JSONValueColumn<CatalogFilterCriteria>;
+    op_hash: string;
     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;
+    op_jwt: string;
+    payload: Uint8Array | null;
+    catalog_id: string | null;
+    group_id: string | null;
+    circle_id: string | null;
 };
-export type Catalog = Selectable<CatalogTable>;
-export type InsertCatalog = Insertable<CatalogTable>;
-export type UpdateCatalog = Updateable<CatalogTable>;
+export type GraphCatalogRecordRow = Selectable<GraphCatalogRecordTable>;
 export type GraphTables = {
-    kubun_graph_catalogs: CatalogTable;
+    kubun_graph_catalog_admitted_heads: {
+        catalog_id: string;
+        signed_record: string;
+    };
+    kubun_graph_catalog_drafts: {
+        catalog_id: string;
+        state: string;
+    };
+    kubun_graph_catalog_publications: {
+        catalog_id: string;
+        version_id: string;
+    };
+    kubun_graph_catalog_recipient_versions: {
+        catalog_id: string;
+        version_id: string;
+        signed_record: string;
+    };
+    kubun_graph_catalog_pending_heads: {
+        catalog_id: string;
+        head_version_id: string;
+        group_id: string | null;
+        retry_at: number;
+        attempts: number;
+    };
+    kubun_graph_access_default_records: Omit<GraphCatalogRecordTable, 'catalog_id' | 'group_id' | 'circle_id'>;
+    kubun_graph_catalog_records: GraphCatalogRecordTable;
+    kubun_graph_scope_changes: CatalogScopeChangeTable;
+    kubun_graph_catalog_scope_tick: CatalogScopeTickTable;
+    kubun_graph_scope_identity: ScopeIdentityTable;
+    kubun_graph_catalog_use: CatalogUseTable;
+    kubun_graph_document_refs: DocumentRefTable;
+    kubun_graph_document_holds: DocumentHoldTable;
+    kubun_graph_gc_marks: GCMarkTable;
+    kubun_graph_custody_scans: CustodyScanTable;
+    kubun_graph_custody_nonces: CustodyNonceTable;
+    kubun_graph_custody_receipts: CustodyReceiptTable;
+    kubun_graph_document_scope_dates: DocumentScopeDateTable;
+    kubun_graph_swept_documents: SweptDocumentTable;
     kubun_graph_cluster_models: ClusterModelTable;
     kubun_graph_clusters: ClusterDefinitionTable;
     kubun_graph_document_models: DocumentModelTable;
@@ -157,6 +301,9 @@ export type GraphTables = {
     kubun_graph_document_model_links: GraphDocumentModelTable;
     kubun_graph_models: GraphModelTable;
     kubun_graph_mutation_log: MutationLogTable;
+    kubun_graph_pending_groups: {
+        group_id: string;
+    };
     kubun_graph_search_models: SearchModelTable;
     kubun_graph_user_model_access_defaults: UserModelAccessDefaultTable;
     [key: `k_${string}`]: DocumentTable;
@@ -168,6 +315,7 @@ export type DocumentParams = {
 export type CreateDocumentParams = DocumentParams & {
     owner: string;
     unique: Uint8Array;
+    authoredHere?: boolean;
 };
 export type SaveDocumentParams = DocumentParams & {
     existing: DocumentNode;
@@ -198,7 +346,7 @@ export type CreateGraphParams = {
 export type AddDocumentModelParams = {
     id: string;
     graphModelID: string;
-    model: import('@kubun/protocol').DocumentModel;
+    model: DocumentModel;
 };
 export type GraphModelWithRecord = GraphModel & {
     record: DocumentModelsRecord;
@@ -218,7 +366,10 @@ export type QueryDocumentsParams = ConnectionArguments & {
     filter?: DocumentFilter;
     orderBy?: DocumentOrderBy;
     owner?: string;
-    catalogID?: string;
+    catalogRef?: {
+        owner: string;
+        id: string;
+    };
 };
 export type CursorDocument = {
     cursor: string;
@@ -241,6 +392,10 @@ export type SearchDocumentsParams = {
     modelIDs: Array<string>;
     first?: number;
     offset?: number;
+    catalogRef?: {
+        owner: string;
+        id: string;
+    };
 };
 export type SearchDocumentResult = {
     documentID: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-graph",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,18 +15,21 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/db": "^0.17.0",
-    "@kubun/db-adapter": "^0.17.0",
-    "@kubun/id": "^0.17.0",
-    "@kubun/mutation": "^0.17.1",
-    "@kubun/protocol": "^0.17.1",
-    "@sozai/codec": "^0.4.0",
-    "kysely": "^0.29.6"
+    "@kokuin/token": "^0.5.1",
+    "@kubun/db": "^0.18.0",
+    "@kubun/db-adapter": "^0.18.0",
+    "@kubun/id": "^0.18.0",
+    "@kubun/mutation": "^0.18.0",
+    "@kubun/protocol": "^0.18.0",
+    "@kubun/records": "^0.18.0",
+    "@noble/hashes": "^2.4.0",
+    "@sozai/codec": "^0.4.3",
+    "kysely": "^0.29.7"
   },
   "devDependencies": {
-    "@kubun/db-better-sqlite": "^0.17.0",
-    "@kubun/db-postgres": "^0.17.1",
-    "@testcontainers/postgresql": "^12.1.0"
+    "@kubun/db-better-sqlite": "^0.18.0",
+    "@kubun/db-postgres": "^0.18.0",
+    "@testcontainers/postgresql": "^12.2.1"
   },
   "publishConfig": {
     "access": "public"