@kubun/service-controller-log-api 0.17.0 → 0.18.0

package/lib/index.d.ts

@@ -1,50 +1,3 @@
 export { toControllerLogSource } from './adapter.js';
-export { createControllerLogService } from './service.js';
-export declare const controllerLogServiceProtocol: {
-    readonly 'controller/resolve': {
-        readonly type: "request";
-        readonly param: {
-            readonly type: "object";
-            readonly properties: {
-                readonly did: {
-                    readonly type: "string";
-                };
-            };
-            readonly required: readonly ["did"];
-            readonly additionalProperties: false;
-        };
-        readonly result: {
-            readonly anyOf: [{
-                readonly type: "array";
-                readonly items: {
-                    readonly type: "object";
-                };
-            }, {
-                readonly type: "null";
-            }];
-        };
-    };
-    readonly 'controller/ingest': {
-        readonly type: "request";
-        readonly param: {
-            readonly type: "object";
-            readonly properties: {
-                readonly did: {
-                    readonly type: "string";
-                };
-                readonly log: {
-                    readonly type: "array";
-                    readonly items: {
-                        readonly type: "object";
-                    };
-                };
-            };
-            readonly required: readonly ["did", "log"];
-            readonly additionalProperties: false;
-        };
-        readonly result: {
-            readonly type: "null";
-        };
-    };
-};
-export type ControllerLogServiceProtocol = typeof controllerLogServiceProtocol;
+export { type ControllerLogServiceProtocol, controllerLogServiceProtocol, } from './protocol.js';
+export { ControllerLogIngestRefusedError, createControllerLogService } from './service.js';

package/lib/index.js

@@ -5,69 +5,5 @@
 // authenticated client into the `controller-log-source` provider a consuming
 // engine consults, plus the server factory (see `./service.js`).
 export { toControllerLogSource } from './adapter.js';
-export { createControllerLogService } from './service.js';
-// `did` is a request PARAM, not the Enkaku message `sub`: a caller resolving or
-// ingesting another controller's log is not acting as that controller, and the
-// host rejects a `sub` that differs from `iss`. Same convention as
-// `service-credential-api`'s `ownerDID`.
-//
-// `resolve` yields the raw key-event log (a `SignedEvent[]`) or null; the log has
-// no JSON-schema here, so an array-of-object result is enough for the wire and the
-// adapter casts. `ingest` acks with null; its `log` is folded through kokuin's
-// anti-truncation guard server-side, so a truncated or forked push is refused
-// there rather than trusted.
-export const controllerLogServiceProtocol = {
-    'controller/resolve': {
-        type: 'request',
-        param: {
-            type: 'object',
-            properties: {
-                did: {
-                    type: 'string'
-                }
-            },
-            required: [
-                'did'
-            ],
-            additionalProperties: false
-        },
-        result: {
-            anyOf: [
-                {
-                    type: 'array',
-                    items: {
-                        type: 'object'
-                    }
-                },
-                {
-                    type: 'null'
-                }
-            ]
-        }
-    },
-    'controller/ingest': {
-        type: 'request',
-        param: {
-            type: 'object',
-            properties: {
-                did: {
-                    type: 'string'
-                },
-                log: {
-                    type: 'array',
-                    items: {
-                        type: 'object'
-                    }
-                }
-            },
-            required: [
-                'did',
-                'log'
-            ],
-            additionalProperties: false
-        },
-        result: {
-            type: 'null'
-        }
-    }
-};
+export { controllerLogServiceProtocol } from './protocol.js';
+export { ControllerLogIngestRefusedError, createControllerLogService } from './service.js';

package/lib/protocol.d.ts

@@ -0,0 +1,48 @@
+export declare const controllerLogServiceProtocol: {
+    readonly 'controller/resolve': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly did: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["did"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly anyOf: [{
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                };
+            }, {
+                readonly type: "null";
+            }];
+        };
+    };
+    readonly 'controller/ingest': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly did: {
+                    readonly type: "string";
+                };
+                readonly log: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                    };
+                };
+            };
+            readonly required: readonly ["did", "log"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "null";
+        };
+    };
+};
+export type ControllerLogServiceProtocol = typeof controllerLogServiceProtocol;

package/lib/protocol.js

@@ -0,0 +1,65 @@
+// `did` is a request PARAM, not the Enkaku message `sub`: a caller resolving or
+// ingesting another controller's log is not acting as that controller, and the
+// host rejects a `sub` that differs from `iss`. Same convention as
+// `service-credential-api`'s `ownerDID`.
+//
+// `resolve` yields the raw key-event log (a `SignedEvent[]`) or null; the log has
+// no JSON-schema here, so an array-of-object result is enough for the wire and the
+// adapter casts. `ingest` acks with null; its `log` is folded through kokuin's
+// anti-truncation guard server-side, so a truncated or forked push is refused
+// there rather than trusted.
+export const controllerLogServiceProtocol = {
+    'controller/resolve': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                did: {
+                    type: 'string'
+                }
+            },
+            required: [
+                'did'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            anyOf: [
+                {
+                    type: 'array',
+                    items: {
+                        type: 'object'
+                    }
+                },
+                {
+                    type: 'null'
+                }
+            ]
+        }
+    },
+    'controller/ingest': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                did: {
+                    type: 'string'
+                },
+                log: {
+                    type: 'array',
+                    items: {
+                        type: 'object'
+                    }
+                }
+            },
+            required: [
+                'did',
+                'log'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            type: 'null'
+        }
+    }
+};

package/lib/service.d.ts

@@ -1,4 +1,10 @@
-import type { KubunPlugin, PluginFactoryParams } from '@kubun/engine';
+import type { IngestOutcome, KubunPlugin, PluginFactoryParams } from '@kubun/engine';
+/** A pushed log that did not become, or was not already, the authoritative head. */
+export declare class ControllerLogIngestRefusedError extends Error {
+    #private;
+    constructor(did: string, outcome: IngestOutcome);
+    get outcome(): IngestOutcome;
+}
 /**
  * The controller-log service provider. It registers a `service` provider on the
  * hosting engine exposing `controller/resolve` and `controller/ingest` over a
@@ -7,9 +13,9 @@ import type { KubunPlugin, PluginFactoryParams } from '@kubun/engine';
  *
  * Neither handler subject-gates. A key-event log is public, verifiable material,
  * not owner-private data: `resolve` must answer for any DID (resolving another
- * user's controller is normal), and `ingest` is protected by kokuin's fold
- * guard — not a subject authorizer — so any verified caller may push a log the
- * guard then arbitrates. The transport access rules therefore grant both to every
- * verified issuer, and no handler calls `context.authorize`.
+ * user's controller is normal), and `ingest` is protected by the engine's
+ * controller head arbitration — not a subject authorizer — so any verified
+ * caller may push a log it then arbitrates. The transport access rules therefore
+ * grant both to every verified issuer, and no handler calls `context.authorize`.
  */
 export declare function createControllerLogService(): (params: PluginFactoryParams) => KubunPlugin;

package/lib/service.js

@@ -1,7 +1,23 @@
-import { createControllerCapabilityVerifier } from '@kokuin/capability';
-import { createControllerResolver } from '@kokuin/controller';
-import { normalizeDID } from '@kokuin/token';
-import { getControllerStore } from '@kubun/store-controller';
+import { digestOf } from '@kokuin/controller';
+import { controllerLogServiceProtocol } from './protocol.js';
+/** A pushed log that did not become, or was not already, the authoritative head. */ export class ControllerLogIngestRefusedError extends Error {
+    #outcome;
+    constructor(did, outcome){
+        super(`Controller log not accepted (${outcome}): ${did}`);
+        this.name = 'ControllerLogIngestRefusedError';
+        this.#outcome = outcome;
+    }
+    get outcome() {
+        return this.#outcome;
+    }
+}
+function logDigest(log) {
+    try {
+        return digestOf(log);
+    } catch  {
+        return undefined;
+    }
+}
 /**
  * The controller-log service provider. It registers a `service` provider on the
  * hosting engine exposing `controller/resolve` and `controller/ingest` over a
@@ -10,63 +26,34 @@ import { getControllerStore } from '@kubun/store-controller';
  *
  * Neither handler subject-gates. A key-event log is public, verifiable material,
  * not owner-private data: `resolve` must answer for any DID (resolving another
- * user's controller is normal), and `ingest` is protected by kokuin's fold
- * guard — not a subject authorizer — so any verified caller may push a log the
- * guard then arbitrates. The transport access rules therefore grant both to every
- * verified issuer, and no handler calls `context.authorize`.
+ * user's controller is normal), and `ingest` is protected by the engine's
+ * controller head arbitration — not a subject authorizer — so any verified
+ * caller may push a log it then arbitrates. The transport access rules therefore
+ * grant both to every verified issuer, and no handler calls `context.authorize`.
  */ export function createControllerLogService() {
     return (params)=>{
-        // Per-DID single-flight: the ingest fold reads the stored head then writes,
-        // and the store's `set` is unconditional LWW. Two concurrent ingests of
-        // conflicting valid branches would both read the same head and both write —
-        // last-writer-wins accepts a fork with no `LOG_FORKED` and drops an accepted
-        // event. Chaining each DID's fold+write on the prior one makes the second read
-        // the first's committed head, so its conflicting branch folds as a fork.
-        const ingestChains = new Map();
-        const ingestSerialized = (did, run)=>{
-            const key = normalizeDID(did);
-            const tail = ingestChains.get(key);
-            // `.then(run, run)` so a rejected predecessor still lets the next run rather
-            // than wedging the whole chain.
-            const next = tail == null ? run() : tail.then(run, run);
-            ingestChains.set(key, next);
-            // Cleanup observes `next` on a separate branch that always resolves, so a
-            // losing branch's rejection is not re-propagated by an unawaited derived
-            // promise. The caller still awaits `next` and sees the rejection.
-            const cleanup = ()=>{
-                if (ingestChains.get(key) === next) ingestChains.delete(key);
-            };
-            next.then(cleanup, cleanup);
-            return next;
-        };
         const handlers = {
             'controller/resolve': async (context)=>{
                 const param = context.param;
-                const log = await (await getControllerStore(params.db)).get(param.did);
-                return log ?? null;
+                // Only a checked head is handed out: a forked DID has no log to answer with.
+                const head = await params.controllerHead(params.db, param.did);
+                return head.status === 'ok' ? head.log : null;
             },
             'controller/ingest': async (context)=>{
                 const param = context.param;
-                return ingestSerialized(param.did, async ()=>{
-                    const store = await getControllerStore(params.db);
-                    // Fold the untrusted incoming log through the same anti-truncation guard
-                    // the engine's controller resolver uses (`authoritativeStates` + a
-                    // write-through `history`), rather than a raw `store.set` that would bypass
-                    // it. A behind/truncated log loses to the stored head, a fork throws
-                    // `LOG_FORKED`, and a valid extension write-throughs — all owned by kokuin.
-                    const resolver = createControllerResolver({
-                        loadLog: async (did)=>did === param.did ? param.log : undefined,
-                        verifyCapability: createControllerCapabilityVerifier(),
-                        history: {
-                            get: (did)=>store.get(did),
-                            set: (did, log)=>store.set(did, log)
-                        }
-                    });
-                    // Resolving triggers the fold and its `history.set` write-through; the
-                    // resolved key is discarded — the store write is the effect we want.
-                    await resolver.resolve(param.did, {});
-                    return null;
-                });
+                // On the base provider in its own transaction, so a fork it records
+                // survives whatever the caller does next.
+                const outcome = await params.ingestControllerLog(params.db, param.did, [
+                    param.log
+                ], 'service');
+                if (outcome === 'advanced' || outcome === 'fork-cleared') return null;
+                if (outcome === 'unchanged') {
+                    // An equal replay is accepted; a behind or losing log is refused.
+                    const head = await params.controllerHead(params.db, param.did);
+                    const pushed = logDigest(param.log);
+                    if (head.status === 'ok' && pushed != null && logDigest(head.log) === pushed) return null;
+                }
+                throw new ControllerLogIngestRefusedError(param.did, outcome);
             }
         };
         params.registerProvider('service', {
@@ -79,7 +66,8 @@ import { getControllerStore } from '@kubun/store-controller';
                 'controller/ingest': {
                     allow: true
                 }
-            }
+            },
+            protocol: controllerLogServiceProtocol
         });
         return {
             name: 'controller-log-service'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/service-controller-log-api",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,21 +15,21 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@enkaku/client": "^0.21.2",
-    "@enkaku/protocol": "^0.21.1",
-    "@kokuin/capability": "^0.3.0",
+    "@enkaku/client": "^0.21.5",
+    "@enkaku/protocol": "^0.21.5",
+    "@kokuin/capability": "^0.4.2",
     "@kokuin/controller": "^0.1.0",
-    "@kubun/engine": "^0.17.0",
-    "@kubun/plugin-service-api": "^0.17.0",
-    "@kubun/store-controller": "^0.17.0"
+    "@kubun/engine": "^0.18.0",
+    "@kubun/plugin-service-api": "^0.18.0",
+    "@kubun/store-controller": "^0.18.0"
   },
   "devDependencies": {
-    "@enkaku/transport": "^0.21.0",
-    "@kokuin/token": "^0.5.0",
-    "@kubun/db": "^0.17.0",
-    "@kubun/db-better-sqlite": "^0.17.0",
-    "@kubun/plugin-service-server": "^0.17.0",
-    "@kubun/store-graph": "^0.17.0",
+    "@enkaku/transport": "^0.21.5",
+    "@kokuin/token": "^0.5.1",
+    "@kubun/db": "^0.18.0",
+    "@kubun/db-better-sqlite": "^0.18.0",
+    "@kubun/plugin-service-server": "^0.18.0",
+    "@kubun/store-graph": "^0.18.0",
     "@kubun/test-utils": "^0.0.0"
   },
   "publishConfig": {