@kokuin/store-controller 0.1.0 → 0.2.0

package/README.md

@@ -12,13 +12,20 @@ npm install @kokuin/store-controller
 
 ```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)
 
-await logs.set(did, log) // after the log has folded
+// 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)
 ```
 

package/lib/api.d.ts

@@ -1,6 +1,6 @@
 import type { Adapter } from '@hozon/adapter';
-import type { Kysely } from '@hozon/db';
-import type { LogStore } from '@kokuin/controller';
+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. */

package/lib/api.js

@@ -1,7 +1,29 @@
+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.
+// 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) {
-    return typeof value === 'string' ? JSON.parse(value) : 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 = {
@@ -17,23 +39,56 @@ export function createControllerStore(db, adapter) {
             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();
+        // 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/tables.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokuin/store-controller",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Hozon-backed controller log store for did:kokuin",
   "keywords": [
     "did",
@@ -25,12 +25,12 @@
   ],
   "dependencies": {
     "@hozon/adapter": "^0.1.0",
-    "@hozon/db": "^0.2.2",
-    "@kokuin/controller": "^0.1.0"
+    "@hozon/db": "^0.3.0",
+    "@kokuin/controller": "^0.2.0"
   },
   "devDependencies": {
     "@hozon/node-sqlite": "^0.1.0",
-    "@types/node": "^26.6.4"
+    "@types/node": "^26.6.5"
   },
   "publishConfig": {
     "access": "public"