@kokuin/store-controller 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @kokuin/store-controller
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hozon-backed store for `did:kokuin:` controller key event logs.
+
+## Installation
+
+```sh
+npm install @kokuin/store-controller
+```
+
+## Usage
+
+```typescript
+import { HozonDB } from '@hozon/db'
+import { authoritativeLog } from '@kokuin/controller'
+import { controllerStoreDefinition, getControllerStore } from '@kokuin/store-controller'
+
+const db = new HozonDB({ adapter }) // an @hozon/node-sqlite or @hozon/postgres adapter
+db.register(controllerStoreDefinition)
+const logs = await getControllerStore(db)
+
+// Merge an untrusted presentation through the same arbitration the resolver uses.
+// Never write peer bytes (or a `mergeLogs` union) directly: stored events of the
+// current epoch are not re-verified, so a forged one would be applied.
+await logs.merge(
+  did,
+  async (seen) => authoritativeLog({ did, loaded: presented, seen, context: 'sync' }).log,
+)
+const stored = await logs.get(did)
+```
+
+See [docs/reference/stores.md](../../docs/reference/stores.md).

package/lib/api.d.ts

@@ -0,0 +1,9 @@
+import type { Adapter } from '@hozon/adapter';
+import { type Kysely } from '@hozon/db';
+import { type LogStore } from '@kokuin/controller';
+import type { ControllerStoreTables } from './tables.js';
+export type ControllerStoreAPI = LogStore & {
+    /** Last explicit store write, including a locally seeded controller log. */
+    getObservedAt(did: string): Promise<Date | undefined>;
+};
+export declare function createControllerStore(db: Kysely<ControllerStoreTables>, adapter: Adapter): ControllerStoreAPI;

package/lib/api.js

@@ -0,0 +1,95 @@
+import { withStoreTransaction } from '@hozon/db';
+import { isControllerLog } from '@kokuin/controller';
+// ParseJSONResultsPlugin usually parses the JSON column back to an object, but a
+// value can still arrive as a string (adapter/driver dependent). Handle both. A
+// row written before the log split into chain and epoch events is a bare event
+// array: it is that chain, with no epoch events. Anything else is not a log and
+// is no memory, as the resolver treats a stored value of that shape -- a string
+// that does not parse included: throwing would refuse every later `get` and
+// `merge` for the DID, where no memory costs one round of the guarantee and the
+// next merge replaces the row.
+function decodeLog(value) {
+    let parsed = value;
+    if (typeof value === 'string') {
+        try {
+            parsed = JSON.parse(value);
+        } catch  {
+            return undefined;
+        }
+    }
+    if (Array.isArray(parsed)) {
+        return {
+            chain: parsed,
+            events: []
+        };
+    }
+    return isControllerLog(parsed) ? parsed : undefined;
+}
+export function createControllerStore(db, adapter) {
+    const api = {
+        async get (did) {
+            const row = await db.selectFrom('controller_logs').select('log').where('did', '=', did).executeTakeFirst();
+            return row == null ? undefined : decodeLog(row.log);
+        },
+        async getObservedAt (did) {
+            const row = await db.selectFrom('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);
+        },
+        // Writes whatever `update` returns, unless it hands back `current` itself:
+        // that is "nothing changed" (see `LogStore.merge`), and the row -- written
+        // or not, legacy shape or not -- is left alone. Arbitration lives in the resolver
+        // (`authoritativeLog`), never here. A caller ingesting an UNTRUSTED log (e.g.
+        // one pulled from a peer) must build the update from `authoritativeLog` —
+        // this store will not refuse a truncated or forked log on its own, and the
+        // resolver does not re-verify the current epoch's stored events. Writing
+        // peer bytes directly would bypass the anti-truncation guarantee AND let a
+        // forged event of the current epoch be applied as authentic.
+        // The read and the write share a store transaction, which joins an enclosing
+        // one. Postgres locks the row on read (`for update`), so a concurrent merge
+        // waits and then reads this one's result. A DID with no row has nothing to
+        // lock: both merges would see none, so the insert is made `do nothing` and a
+        // lost race (no row inserted) re-reads, now locking the row the winner wrote.
+        // SQLite has no row locks: in one process the single connection's mutex
+        // serialises merges; across processes a stale deferred read fails with
+        // SQLITE_BUSY (or SQLITE_BUSY_SNAPSHOT) on write, so nothing is lost and the
+        // merge throws.
+        async merge (did, update) {
+            return await withStoreTransaction(db, async (trx)=>{
+                const lock = adapter.kind === 'postgres';
+                const values = (next)=>({
+                        did,
+                        log: adapter.encodeJSON(next),
+                        updated_at: adapter.encodeTimestamp(new Date())
+                    });
+                const write = async (next)=>{
+                    await trx.insertInto('controller_logs').values(values(next)).onConflict((oc)=>oc.column('did').doUpdateSet((eb)=>({
+                                log: eb.ref('excluded.log'),
+                                updated_at: eb.ref('excluded.updated_at')
+                            }))).execute();
+                };
+                let query = trx.selectFrom('controller_logs').select('log').where('did', '=', did);
+                if (lock) query = query.forUpdate();
+                const row = await query.executeTakeFirst();
+                if (row != null || !lock) {
+                    const current = row == null ? undefined : decodeLog(row.log);
+                    const next = await update(current);
+                    if (next !== current) await write(next);
+                    return next;
+                }
+                const first = await update(undefined);
+                const inserted = await trx.insertInto('controller_logs').values(values(first)).onConflict((oc)=>oc.column('did').doNothing()).executeTakeFirst();
+                if (Number(inserted.numInsertedOrUpdatedRows ?? 0) > 0) return first;
+                const raced = await query.executeTakeFirst();
+                const current = raced == null ? undefined : decodeLog(raced.log);
+                const next = await update(current);
+                if (next !== current) await write(next);
+                return next;
+            });
+        }
+    };
+    return api;
+}

package/lib/definition.d.ts

@@ -0,0 +1,6 @@
+import type { StoreDefinition, StoreProvider } from '@hozon/db';
+import type { ControllerStoreAPI } from './api.js';
+import type { ControllerStoreTables } from './tables.js';
+export declare const CONTROLLER_STORE: "controller";
+export declare const controllerStoreDefinition: StoreDefinition<ControllerStoreTables, ControllerStoreAPI>;
+export declare function getControllerStore(provider: StoreProvider): Promise<ControllerStoreAPI>;

package/lib/definition.js

@@ -0,0 +1,11 @@
+import { createControllerStore } from './api.js';
+import { getControllerMigrations } from './migrations.js';
+export const CONTROLLER_STORE = 'controller';
+export const controllerStoreDefinition = {
+    name: CONTROLLER_STORE,
+    migrations: getControllerMigrations,
+    createAPI: createControllerStore
+};
+export async function getControllerStore(provider) {
+    return provider.getStore(CONTROLLER_STORE);
+}

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export type { ControllerStoreAPI } from './api.js';
+export { createControllerStore } from './api.js';
+export { CONTROLLER_STORE, controllerStoreDefinition, getControllerStore, } from './definition.js';
+export type { ControllerLogRow, ControllerLogTable, ControllerStoreTables, InsertControllerLog, } from './tables.js';

package/lib/index.js

@@ -0,0 +1,2 @@
+export { createControllerStore } from './api.js';
+export { CONTROLLER_STORE, controllerStoreDefinition, getControllerStore } from './definition.js';

package/lib/migrations.d.ts

@@ -0,0 +1,2 @@
+import type { Migration, MigrationContext } from '@hozon/db';
+export declare function getControllerMigrations(ctx: MigrationContext): Record<string, Migration>;

package/lib/migrations.js

@@ -0,0 +1,18 @@
+export function getControllerMigrations(ctx) {
+    const t = ctx.types;
+    const now = ctx.functions.now;
+    const init = {
+        async up (db) {
+            // One row per controller DID; `log` holds the signed event array verbatim.
+            await db.schema.createTable('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(`${ctx.tablePrefix}_controller_logs_pkey`, [
+                'did'
+            ]).execute();
+        },
+        async down (db) {
+            await db.schema.dropTable('controller_logs').ifExists().execute();
+        }
+    };
+    return {
+        '0-init': init
+    };
+}

package/lib/tables.d.ts

@@ -0,0 +1,16 @@
+import type { CreatedAtColumn, UpdatedAtColumn } from '@hozon/adapter';
+import type { ColumnType, Insertable, Selectable } from '@hozon/db';
+import type { ControllerLog } from '@kokuin/controller';
+type JSONValueColumn<T> = ColumnType<T, T, T>;
+export type ControllerLogTable = {
+    did: string;
+    log: JSONValueColumn<ControllerLog>;
+    created_at: CreatedAtColumn;
+    updated_at: UpdatedAtColumn;
+};
+export type ControllerLogRow = Selectable<ControllerLogTable>;
+export type InsertControllerLog = Insertable<ControllerLogTable>;
+export type ControllerStoreTables = {
+    controller_logs: ControllerLogTable;
+};
+export {};

package/lib/tables.js

@@ -0,0 +1 @@
+export { };

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@kokuin/store-controller",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Hozon-backed controller log store for did:kokuin",
+  "keywords": [
+    "did",
+    "controller",
+    "store"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TairuFramework/kokuin",
+    "directory": "packages/store-controller"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@hozon/adapter": "^0.1.0",
+    "@hozon/db": "^0.3.0",
+    "@kokuin/controller": "^0.2.0"
+  },
+  "devDependencies": {
+    "@hozon/node-sqlite": "^0.1.0",
+    "@types/node": "^26.6.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli 'lib/**/*.js' && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli 'lib/**/*.d.ts' 'lib/**/*.d.ts.map' && tsc --emitDeclarationOnly --skipLibCheck",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }