@kubun/store-controller 0.16.0 → 0.18.0

package/lib/api.d.ts

@@ -1,6 +1,28 @@
-import type { LogStore } from '@kokuin/controller';
-import type { Adapter } from '@kubun/db-adapter';
+import type { LogStore, SignedEvent } from '@kokuin/controller';
+import { type Adapter } from '@kubun/db-adapter';
 import type { Kysely } from 'kysely';
-import type { ControllerStoreTables } from './tables.js';
-export type ControllerStoreAPI = LogStore;
+import type { CapabilityVerifiedAt, ControllerStoreTables } from './tables.js';
+export type ControllerRecord = {
+    log: Array<SignedEvent> | null;
+    forkGeneration: number | null;
+    forkBranches: Array<Array<SignedEvent>> | null;
+    /** Unix seconds each capability revoke first verified at, by its signed event digest. */
+    capabilityVerifiedAt: CapabilityVerifiedAt;
+    observedAt: Date;
+};
+export type ControllerRecordInput = Omit<ControllerRecord, 'observedAt'>;
+export type ControllerStoreAPI = LogStore & {
+    getRecord(did: string): Promise<ControllerRecord | undefined>;
+    /** Locks the row on Postgres; SQLite is already serialised by the transaction. */
+    getRecordForUpdate(did: string): Promise<ControllerRecord | undefined>;
+    /** Whether this call inserted: false when a row for the DID already exists. */
+    insertRecordIfAbsent(did: string, record: ControllerRecordInput): Promise<boolean>;
+    putRecord(did: string, record: ControllerRecordInput): Promise<void>;
+    /** Bumps the observation time only. */
+    touch(did: string): Promise<void>;
+    /** Last explicit store write, including a locally seeded controller log. */
+    getObservedAt(did: string): Promise<Date | undefined>;
+    /** Throws `ControllerStoreSchemaOutdatedError` when the stored table predates this version. */
+    assertSchema(): Promise<void>;
+};
 export declare function createControllerStore(db: Kysely<ControllerStoreTables>, adapter: Adapter): ControllerStoreAPI;

package/lib/api.js

@@ -1,30 +1,127 @@
+import { AbstractPostgresAdapter } from '@kubun/db-adapter';
+import { ControllerStoreSchemaOutdatedError } from './errors.js';
 // ParseJSONResultsPlugin usually parses the JSON column back to an object, but a
 // value can still arrive as a string (adapter/driver dependent). Handle both.
-function decodeLog(value) {
+function decodeJSON(value) {
+    if (value == null) return null;
     return typeof value === 'string' ? JSON.parse(value) : value;
 }
+function decodeLog(value) {
+    return decodeJSON(value);
+}
+function encodeRecord(adapter, did, record) {
+    // SQLite's `encodeJSON` stringifies, which would turn a null into the text "null".
+    const json = (value)=>value == null ? null : adapter.encodeJSON(value);
+    return {
+        did,
+        log: json(record.log),
+        fork_generation: record.forkGeneration,
+        fork_branches: json(record.forkBranches),
+        capability_verified_at: adapter.encodeJSON(record.capabilityVerifiedAt),
+        updated_at: adapter.encodeTimestamp(new Date())
+    };
+}
+async function readRecord(db, adapter, did, lock) {
+    let query = db.selectFrom('kubun_controller_logs').selectAll().where('did', '=', did);
+    if (lock && adapter instanceof AbstractPostgresAdapter) query = query.forUpdate();
+    const row = await query.executeTakeFirst();
+    if (row == null) return undefined;
+    return {
+        log: decodeJSON(row.log),
+        forkGeneration: row.fork_generation,
+        forkBranches: decodeJSON(row.fork_branches),
+        capabilityVerifiedAt: decodeJSON(row.capability_verified_at) ?? {},
+        observedAt: adapter.decodeTimestamp(row.updated_at ?? row.created_at)
+    };
+}
+// A migration key runs once, so a database that applied `0-init` before the
+// fork or capability time columns existed is only visible by inspecting the
+// table on each open.
+// Only settled results are cached per database (every transaction builds its
+// own store API, and the schema cannot change in-process without a reset). An
+// in-flight check is never shared: one started on the base provider queues
+// behind an open transaction on single-connection SQLite, so a transaction
+// awaiting it would deadlock.
+const checkedSchemas = new WeakSet();
+const outdatedSchemas = new WeakSet();
+async function checkSchema(db) {
+    const table = (await db.introspection.getTables()).find((candidate)=>candidate.name === 'kubun_controller_logs');
+    const outdated = table != null && (!table.columns.some((col)=>col.name === 'fork_generation') || !table.columns.some((col)=>col.name === 'capability_verified_at') || table.columns.find((col)=>col.name === 'log')?.isNullable === false);
+    if (outdated) throw new ControllerStoreSchemaOutdatedError();
+}
 export function createControllerStore(db, adapter) {
     const api = {
         async get (did) {
             const row = await db.selectFrom('kubun_controller_logs').select('log').where('did', '=', did).executeTakeFirst();
-            return row == null ? undefined : decodeLog(row.log);
+            return row?.log == null ? undefined : decodeLog(row.log);
+        },
+        getRecord: (did)=>readRecord(db, adapter, did, false),
+        getRecordForUpdate: (did)=>readRecord(db, adapter, did, true),
+        async insertRecordIfAbsent (did, record) {
+            const result = await db.insertInto('kubun_controller_logs').values(encodeRecord(adapter, did, record)).onConflict((oc)=>oc.column('did').doNothing()).executeTakeFirst();
+            return Number(result.numInsertedOrUpdatedRows ?? 0) > 0;
+        },
+        async putRecord (did, record) {
+            const values = encodeRecord(adapter, did, record);
+            await db.insertInto('kubun_controller_logs').values(values).onConflict((oc)=>oc.column('did').doUpdateSet({
+                    log: values.log,
+                    fork_generation: values.fork_generation,
+                    fork_branches: values.fork_branches,
+                    capability_verified_at: values.capability_verified_at,
+                    updated_at: values.updated_at
+                })).execute();
+        },
+        async touch (did) {
+            await db.updateTable('kubun_controller_logs').set({
+                updated_at: adapter.encodeTimestamp(new Date())
+            }).where('did', '=', did).execute();
         },
-        // Plain last-writer-wins: `set` is called only after the log has folded, so
-        // arbitration lives in the resolver, never here. See `@kokuin/controller`.
-        // A caller ingesting an UNTRUSTED log (e.g. one pulled from a peer) must run
-        // it through the resolver's `authoritativeStates`/`history` guard first — this
-        // store will not refuse a truncated or forked log on its own, so a direct
-        // `set` of peer bytes would bypass the anti-truncation guarantee.
+        async getObservedAt (did) {
+            const row = await db.selectFrom('kubun_controller_logs').select([
+                'created_at',
+                'updated_at'
+            ]).where('did', '=', did).executeTakeFirst();
+            if (row == null) return undefined;
+            return adapter.decodeTimestamp(row.updated_at ?? row.created_at);
+        },
+        // The guard wrapping every method does the check.
+        async assertSchema () {},
+        // Kept for the `LogStore` contract and test seeding only. Plain last-writer-wins:
+        // it refuses no truncated or forked log and leaves fork and capability state
+        // alone. Every source write, and any log from an untrusted source such as a
+        // peer, goes through the engine's `ControllerHead.ingest`, the only
+        // arbitration path.
         async set (did, log) {
             const encoded = adapter.encodeJSON(log);
+            const observedAt = adapter.encodeTimestamp(new Date());
             await db.insertInto('kubun_controller_logs').values({
                 did,
-                log: encoded
+                log: encoded,
+                updated_at: observedAt
             }).onConflict((oc)=>oc.column('did').doUpdateSet((eb)=>({
                         log: eb.ref('excluded.log'),
-                        updated_at: adapter.encodeTimestamp(new Date())
+                        updated_at: observedAt
                     }))).execute();
         }
     };
-    return api;
+    const guard = async ()=>{
+        if (outdatedSchemas.has(adapter)) throw new ControllerStoreSchemaOutdatedError();
+        if (checkedSchemas.has(adapter)) return;
+        try {
+            await checkSchema(db);
+        } catch (error) {
+            // Only an outdated schema is permanent; anything else is retried next call.
+            if (error instanceof ControllerStoreSchemaOutdatedError) outdatedSchemas.add(adapter);
+            throw error;
+        }
+        checkedSchemas.add(adapter);
+    };
+    const methods = Object.entries(api).map(([name, method])=>[
+            name,
+            async (...args)=>{
+                await guard();
+                return method(...args);
+            }
+        ]);
+    return Object.fromEntries(methods);
 }

package/lib/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class ControllerStoreSchemaOutdatedError extends Error {
+    constructor();
+}

package/lib/errors.js

@@ -0,0 +1,6 @@
+export class ControllerStoreSchemaOutdatedError extends Error {
+    constructor(){
+        super('The controller store schema is outdated (kubun_controller_logs lacks fork or capability time columns): reset the database');
+        this.name = 'ControllerStoreSchemaOutdatedError';
+    }
+}

package/lib/index.d.ts

@@ -1,8 +1,9 @@
 import type { StoreProvider } from '@kubun/db';
 import type { ControllerStoreAPI } from './api.js';
-export type { ControllerStoreAPI } from './api.js';
+export type { ControllerRecord, ControllerStoreAPI } from './api.js';
 export { createControllerStore } from './api.js';
 export { controllerStoreDefinition } from './definition.js';
+export { ControllerStoreSchemaOutdatedError } from './errors.js';
 export declare const CONTROLLER_STORE: "controller";
 export declare function getControllerStore(provider: StoreProvider): Promise<ControllerStoreAPI>;
-export type { ControllerLogRow, ControllerLogTable, ControllerStoreTables, InsertControllerLog, } from './tables.js';
+export type { CapabilityVerifiedAt, ControllerLogRow, ControllerLogTable, ControllerStoreTables, InsertControllerLog, } from './tables.js';

package/lib/index.js

@@ -1,5 +1,6 @@
 export { createControllerStore } from './api.js';
 export { controllerStoreDefinition } from './definition.js';
+export { ControllerStoreSchemaOutdatedError } from './errors.js';
 export const CONTROLLER_STORE = 'controller';
 export function getControllerStore(provider) {
     return provider.getStore(CONTROLLER_STORE);

package/lib/migrations.js

@@ -4,7 +4,11 @@ export function getControllerMigrations(ctx) {
     const init = {
         async up (db) {
             // One row per controller DID; `log` holds the signed event array verbatim.
-            await db.schema.createTable('kubun_controller_logs').ifNotExists().addColumn('did', t.text, (col)=>col.notNull()).addColumn('log', t.json, (col)=>col.notNull()).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp).addPrimaryKeyConstraint('pk_controller_logs', [
+            // `fork_*` record a detected fork: the generation and each rival branch.
+            // `capability_verified_at` maps each capability-authorised revoke's signed
+            // event digest to the unix seconds its capability first verified at, so
+            // the log still folds once the capability expires.
+            await db.schema.createTable('kubun_controller_logs').ifNotExists().addColumn('did', t.text, (col)=>col.notNull()).addColumn('log', t.json).addColumn('fork_generation', 'integer').addColumn('fork_branches', t.json).addColumn('capability_verified_at', t.json, (col)=>col.notNull().defaultTo('{}')).addColumn('created_at', t.timestamp, (col)=>col.defaultTo(now).notNull()).addColumn('updated_at', t.timestamp).addPrimaryKeyConstraint('pk_controller_logs', [
                 'did'
             ]).execute();
         },

package/lib/tables.d.ts

@@ -2,9 +2,14 @@ import type { SignedEvent } from '@kokuin/controller';
 import type { CreatedAtColumn, UpdatedAtColumn } from '@kubun/db-adapter';
 import type { ColumnType, Insertable, Selectable } from 'kysely';
 type JSONValueColumn<T> = ColumnType<T, T, T>;
+/** Unix seconds each capability revoke first verified at, keyed by its signed event digest. */
+export type CapabilityVerifiedAt = Record<string, number>;
 export type ControllerLogTable = {
     did: string;
-    log: JSONValueColumn<Array<SignedEvent>>;
+    log: JSONValueColumn<Array<SignedEvent> | null>;
+    fork_generation: number | null;
+    fork_branches: JSONValueColumn<Array<Array<SignedEvent>> | null>;
+    capability_verified_at: ColumnType<CapabilityVerifiedAt, CapabilityVerifiedAt | undefined, CapabilityVerifiedAt>;
     created_at: CreatedAtColumn;
     updated_at: UpdatedAtColumn;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-controller",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -16,14 +16,14 @@
   ],
   "dependencies": {
     "@kokuin/controller": "^0.1.0",
-    "@kubun/db": "^0.16.0",
-    "@kubun/db-adapter": "^0.16.0",
-    "kysely": "^0.29.5"
+    "@kubun/db": "^0.18.0",
+    "@kubun/db-adapter": "^0.18.0",
+    "kysely": "^0.29.7"
   },
   "devDependencies": {
-    "@kubun/db-better-sqlite": "^0.16.0",
-    "@kubun/db-postgres": "^0.16.0",
-    "@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"
@@ -31,8 +31,8 @@
   "scripts": {
     "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
-    "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
-    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "build:js": "del 'lib/**/*.js' && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del 'lib/**/*.d.ts' 'lib/**/*.d.ts.map' && tsc --emitDeclarationOnly --skipLibCheck",
     "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
     "test": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit -p tsconfig.test.json",