@kokuin/store-controller 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,25 @@
-# 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 { 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)
+
+await logs.set(did, log) // after the log has folded
+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,40 @@
+// 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) {
+    return typeof value === 'string' ? JSON.parse(value) : value;
+}
+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);
+        },
+        // 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 set (did, log) {
+            const encoded = adapter.encodeJSON(log);
+            const observedAt = adapter.encodeTimestamp(new Date());
+            await db.insertInto('controller_logs').values({
+                did,
+                log: encoded,
+                updated_at: observedAt
+            }).onConflict((oc)=>oc.column('did').doUpdateSet((eb)=>({
+                        log: eb.ref('excluded.log'),
+                        updated_at: observedAt
+                    }))).execute();
+        }
+    };
+    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 { SignedEvent } from '@kokuin/controller';
+type JSONValueColumn<T> = ColumnType<T, T, T>;
+export type ControllerLogTable = {
+    did: string;
+    log: JSONValueColumn<Array<SignedEvent>>;
+    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.1.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.2.2",
+    "@kokuin/controller": "^0.1.0"
+  },
+  "devDependencies": {
+    "@hozon/node-sqlite": "^0.1.0",
+    "@types/node": "^26.6.4"
+  },
+  "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"
+  }
 }