@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/sync/hub-tunnel-sync-listener.js

@@ -1 +1,172 @@
-import{createEncryptedHubTunnelTransport as t}from"@enkaku/hub-tunnel";import{Server as e}from"@enkaku/server";import{MLSEncryptor as s}from"../groups/mls-encryptor.js";export class HubTunnelSyncListener{#t;#e;#s;#n;#i;#r;#o;#c;#a;#h;#p;#u=!1;#l=!1;#d;#D;#y;constructor(t){this.#t=t.hubConnection,this.#e=t.registry,this.#s=t.groupID,this.#n=t.localDID,this.#i=t.peerDID,this.#r=t.syncHandlers,this.#o=t.getRandomID,this.#c=t.idleTimeoutMs,this.#a=t.reconnectTimeoutMs,this.#h=t.inboxCapacity,this.#p=t.onEvent}start(){this.#u||this.#l||(this.#u=!0,this.#y=new s({registry:this.#e,groupID:this.#s}),this.#D=this.#t.tunnelMessageStream({peerDID:this.#i}),this.#m())}async stop(){if(this.#l)return;this.#l=!0;let t=this.#d;if(this.#d=void 0,null!=t){try{await t.transport.dispose()}catch{}try{await t.server.dispose()}catch{}}let e=this.#D;if(this.#D=void 0,null!=e)try{e.return()}catch{}this.#y=void 0}#m(){let s;if(this.#l)return;let n=this.#y;if(null==n)throw Error("HubTunnelSyncListener: encryptor not initialized; call start() first");let i=t({hub:this.#I(),encryptor:n,groupID:this.#s,sessionID:{auto:!0},localDID:this.#n,peerDID:this.#i,idleTimeoutMs:this.#c,reconnectTimeoutMs:this.#a,inboxCapacity:this.#h,onEvent:this.#p,onSessionEnd:()=>{s?.dispose().catch(()=>{})}});s=i;let r=new e({getRandomID:this.#o,handlers:this.#r,transports:[i]}),o={transport:i,server:r};this.#d=o,i.events.on("disposed",()=>{this.#d===o&&(this.#d=void 0),r.dispose().catch(()=>{}),this.#m()})}#I(){let t=this.#t,e=this.#D;if(null==e)throw Error("HubTunnelSyncListener: stream not initialized; call start() first");return{send:async e=>t.send({recipients:e.recipients,payload:e.payload}),receive:t=>e,events:{subscribe:e=>t.events.on("lifecycle",t=>{let s=function(t){switch(t.type){case"connected":return{type:"connected"};case"disconnected":return{type:"disconnected"};case"reconnecting":return{type:"reconnecting"};case"error":return}}(t);void 0!==s&&e(s)})}}}}
+import { Server } from '@enkaku/server';
+import { createEncryptedHubTunnelTransport } from '@kumiai/hub-tunnel';
+import { inboxTopic } from '@kumiai/rpc';
+import { createGroupCrypto } from '../groups/group-crypto.js';
+import { MLSEncryptor } from '../groups/mls-encryptor.js';
+export class HubTunnelSyncListener {
+    #hub;
+    #registry;
+    #groupID;
+    #localDID;
+    #peerDID;
+    #identity;
+    #syncHandlers;
+    #getRandomID;
+    #idleTimeoutMs;
+    #reconnectTimeoutMs;
+    #inboxCapacity;
+    #onEvent;
+    #started = false;
+    #stopped = false;
+    #current;
+    // Single MLSEncryptor reused across spawns. Ordering across overlapping
+    // spawns (old transport's last decrypt vs. new spawn's first encrypt) is
+    // covered by the GroupHandleRegistry's per-group mutex.
+    #encryptor;
+    // This device's inbox topic for the live epoch, cached from the first spawn.
+    // Within an epoch it is stable (same secret + localDID), so it lets the
+    // disposed handler re-subscribe synchronously and close the gap left by the
+    // departing transport's teardown-unsubscribe before the async respawn lands.
+    #receiveTopicID;
+    constructor(params){
+        this.#hub = params.hub;
+        this.#registry = params.registry;
+        this.#groupID = params.groupID;
+        this.#localDID = params.localDID;
+        this.#peerDID = params.peerDID;
+        this.#identity = params.identity;
+        this.#syncHandlers = params.syncHandlers;
+        this.#getRandomID = params.getRandomID;
+        this.#idleTimeoutMs = params.idleTimeoutMs;
+        this.#reconnectTimeoutMs = params.reconnectTimeoutMs;
+        this.#inboxCapacity = params.inboxCapacity;
+        this.#onEvent = params.onEvent;
+    }
+    start() {
+        if (this.#started || this.#stopped) return;
+        this.#started = true;
+        this.#encryptor = new MLSEncryptor({
+            registry: this.#registry,
+            groupID: this.#groupID
+        });
+        void this.#spawn();
+    }
+    async stop() {
+        if (this.#stopped) return;
+        this.#stopped = true;
+        const current = this.#current;
+        this.#current = undefined;
+        if (current != null) {
+            try {
+                await current.transport.dispose();
+            } catch  {
+            // ignore — best-effort teardown
+            }
+            try {
+                await current.server.dispose();
+            } catch  {
+            // ignore — best-effort teardown
+            }
+        }
+        this.#encryptor = undefined;
+    }
+    async #spawn() {
+        if (this.#stopped) return;
+        const encryptor = this.#encryptor;
+        if (encryptor == null) {
+            throw new Error('HubTunnelSyncListener: encryptor not initialized; call start() first');
+        }
+        // Derive the epoch-bound inbox topics for this spawn. The server accepts
+        // inbound frames on its own inbox (`receiveTopicID`) and replies to the
+        // peer's inbox (`sendTopicID`). Topics rotate with the MLS epoch, so each
+        // spawn re-derives them against the live handle. MLS decrypt inside the
+        // registry lock remains the authoritative membership/forward-secrecy gate;
+        // stale-after-remove ciphertext surfaces as DecryptError.
+        const crypto = createGroupCrypto(this.#registry, this.#groupID);
+        const secret = await crypto.exportSecret();
+        const epoch = crypto.epoch();
+        const sendTopicID = inboxTopic(secret, epoch, this.#peerDID);
+        const receiveTopicID = inboxTopic(secret, epoch, this.#localDID);
+        this.#receiveTopicID = receiveTopicID;
+        // A stop() that landed while we awaited the handle must abort the spawn.
+        if (this.#stopped) return;
+        let transportRef;
+        const transport = createEncryptedHubTunnelTransport({
+            hub: this.#hub,
+            encryptor,
+            groupID: this.#groupID,
+            sessionID: {
+                auto: true
+            },
+            localDID: this.#localDID,
+            sendTopicID,
+            receiveTopicID,
+            idleTimeoutMs: this.#idleTimeoutMs,
+            reconnectTimeoutMs: this.#reconnectTimeoutMs,
+            inboxCapacity: this.#inboxCapacity,
+            onEvent: this.#onEvent,
+            onSessionEnd: ()=>{
+                // Peer signaled end-of-session. Dispose the transport deterministically
+                // so the `disposed` event fires and the spawn loop re-arms for the
+                // next session arriving on the shared device drain.
+                void transportRef?.dispose().catch(()=>{
+                // ignore — best-effort
+                });
+            }
+        });
+        transportRef = transport;
+        // Setting identity forces requireAuth: the tunnel server verifies token
+        // signatures and that aud equals its own DID, matching the direct/HTTP sync
+        // servers. Per-scope authorization is handled uniformly by the merkle-sync
+        // scope-gate, not here.
+        const server = new Server({
+            getRandomID: this.#getRandomID,
+            handlers: this.#syncHandlers,
+            identity: this.#identity,
+            accessRules: {
+                'sync/*': {
+                    allow: true
+                }
+            },
+            transports: [
+                transport
+            ]
+        });
+        const session = {
+            transport,
+            server
+        };
+        this.#current = session;
+        // `disposed` may fire more than once for a single session (disposing the
+        // server can re-enter the transport's dispose). Collapse to exactly one
+        // teardown + respawn so the inbox is re-armed once, not N times.
+        let handled = false;
+        transport.events.on('disposed', ()=>{
+            if (handled) return;
+            handled = true;
+            if (this.#current === session) {
+                this.#current = undefined;
+            }
+            // Server stays around until its handlers drain; explicit cleanup here so
+            // long-running sessions don't leak server instances.
+            void server.dispose().catch(()=>{
+            // ignore
+            });
+            // The departing transport's teardown unsubscribes this device's inbox
+            // topic. Re-subscribe it eagerly (idempotent server-side) so a peer that
+            // reconnects immediately — before the async respawn re-derives and
+            // re-subscribes — does not lose its first frame to a momentarily empty
+            // topic. Within an epoch the topic is stable, so this targets the same
+            // inbox the next spawn will use.
+            const receiveTopicID = this.#receiveTopicID;
+            if (receiveTopicID != null) {
+                void Promise.resolve(this.#hub.subscribe(this.#localDID, receiveTopicID)).catch(()=>{
+                // best-effort; the respawn re-subscribes authoritatively
+                });
+            }
+            // Respawn for the next session. The next spawn re-derives the topics
+            // against the (possibly advanced) epoch and re-subscribes.
+            void this.#spawn();
+        });
+    }
+}

package/lib/sync/hub-tunnel-sync-provider.d.ts

@@ -1,11 +1,15 @@
-import { type ObservabilityEventListener } from '@enkaku/hub-tunnel';
 import type { ClientTransportOf } from '@enkaku/protocol';
+import { type HubLike, type ObservabilityEventListener } from '@kumiai/hub-tunnel';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
-import type { HubConnection } from '../hub/hub-connection.js';
 import type { SyncProtocol } from '../protocol.js';
 import type { SyncTransportProvider } from './sync-client.js';
 export type HubTunnelSyncProviderParams = {
-    hubConnection: HubConnection;
+    /**
+     * Shared multi-subscriber device hub (from `createHubLike`). The transport's
+     * `receive()` attaches its own sink to this device-wide drain and filters to
+     * `receiveTopicID`; lifecycle events ride `hub.events`.
+     */
+    hub: HubLike;
     registry: GroupHandleRegistry;
     groupID: string;
     localDID: string;
@@ -21,16 +25,12 @@ export declare class HubTunnelSyncProvider implements SyncTransportProvider {
     /**
      * Build a fresh client transport for one tunnel sync session.
      *
-     * **Concurrent-call constraint:** the underlying `HubConnection` keys its
-     * tunnel inbox by `peerDID`, and only one inbox per peer can be registered
-     * at a time. Callers must therefore fully dispose the previous transport
-     * (via `client.dispose()`) before invoking `createSyncTransport` again for
-     * the same provider instance — otherwise the second call throws
-     * `Error('tunnelMessageStream: peerDID already registered')`.
-     *
-     * The default `SyncManager.merkleSyncWithPeer` flow already awaits
-     * `client.dispose()` in its `finally` block, so sequential sync calls are
-     * safe. Concurrent calls are not.
+     * The tunnel rides group-scoped inbox topics derived from the group's current
+     * MLS epoch secret: outbound frames publish to the peer's inbox
+     * (`inboxTopic(secret, epoch, peerDID)`) and the transport subscribes to this
+     * device's own inbox (`inboxTopic(secret, epoch, localDID)`). Topics rotate
+     * with the epoch, so a transport built in epoch N stops matching once a commit
+     * advances the group — callers create a new transport per session.
      */
-    createSyncTransport(signal?: AbortSignal): ClientTransportOf<SyncProtocol>;
+    createSyncTransport(signal?: AbortSignal): Promise<ClientTransportOf<SyncProtocol>>;
 }

package/lib/sync/hub-tunnel-sync-provider.js

@@ -1 +1,64 @@
-import{createEncryptedHubTunnelTransport as e}from"@enkaku/hub-tunnel";import{MLSEncryptor as t}from"../groups/mls-encryptor.js";export class HubTunnelSyncProvider{#e;#t;#n;#r;#o;#i;#s;#c;#u;constructor(e){this.#e=e.hubConnection,this.#t=e.registry,this.#n=e.groupID,this.#r=e.localDID,this.#o=e.peerDID,this.#i=e.idleTimeoutMs,this.#s=e.reconnectTimeoutMs,this.#c=e.inboxCapacity,this.#u=e.onEvent}createSyncTransport(n){let r=crypto.randomUUID(),o=new t({registry:this.#t,groupID:this.#n});return e({hub:this.#a(),encryptor:o,groupID:this.#n,sessionID:r,localDID:this.#r,peerDID:this.#o,signal:n,idleTimeoutMs:this.#i,reconnectTimeoutMs:this.#s,inboxCapacity:this.#c,onEvent:this.#u})}#a(){let e=this.#e,t=this.#o;return{send:async t=>e.send({recipients:t.recipients,payload:t.payload}),receive(n){let r=e.tunnelMessageStream({peerDID:t}),o=r[Symbol.asyncIterator](),i={next:()=>o.next(),return:()=>(r.return(),Promise.resolve({value:void 0,done:!0}))};return{[Symbol.asyncIterator]:()=>i,return:()=>{r.return()}}},events:{subscribe:t=>e.events.on("lifecycle",e=>{let n=function(e){switch(e.type){case"connected":return{type:"connected"};case"disconnected":return{type:"disconnected"};case"reconnecting":return{type:"reconnecting"};case"error":return}}(e);void 0!==n&&t(n)})}}}}
+import { createEncryptedHubTunnelTransport } from '@kumiai/hub-tunnel';
+import { inboxTopic } from '@kumiai/rpc';
+import { createGroupCrypto } from '../groups/group-crypto.js';
+import { MLSEncryptor } from '../groups/mls-encryptor.js';
+export class HubTunnelSyncProvider {
+    #hub;
+    #registry;
+    #groupID;
+    #localDID;
+    #peerDID;
+    #idleTimeoutMs;
+    #reconnectTimeoutMs;
+    #inboxCapacity;
+    #onEvent;
+    constructor(params){
+        this.#hub = params.hub;
+        this.#registry = params.registry;
+        this.#groupID = params.groupID;
+        this.#localDID = params.localDID;
+        this.#peerDID = params.peerDID;
+        this.#idleTimeoutMs = params.idleTimeoutMs;
+        this.#reconnectTimeoutMs = params.reconnectTimeoutMs;
+        this.#inboxCapacity = params.inboxCapacity;
+        this.#onEvent = params.onEvent;
+    }
+    /**
+   * Build a fresh client transport for one tunnel sync session.
+   *
+   * The tunnel rides group-scoped inbox topics derived from the group's current
+   * MLS epoch secret: outbound frames publish to the peer's inbox
+   * (`inboxTopic(secret, epoch, peerDID)`) and the transport subscribes to this
+   * device's own inbox (`inboxTopic(secret, epoch, localDID)`). Topics rotate
+   * with the epoch, so a transport built in epoch N stops matching once a commit
+   * advances the group — callers create a new transport per session.
+   */ async createSyncTransport(signal) {
+        const sessionID = generateSessionID();
+        const encryptor = new MLSEncryptor({
+            registry: this.#registry,
+            groupID: this.#groupID
+        });
+        const crypto1 = createGroupCrypto(this.#registry, this.#groupID);
+        const secret = await crypto1.exportSecret();
+        const epoch = crypto1.epoch();
+        const sendTopicID = inboxTopic(secret, epoch, this.#peerDID);
+        const receiveTopicID = inboxTopic(secret, epoch, this.#localDID);
+        return createEncryptedHubTunnelTransport({
+            hub: this.#hub,
+            encryptor,
+            groupID: this.#groupID,
+            sessionID,
+            localDID: this.#localDID,
+            sendTopicID,
+            receiveTopicID,
+            signal,
+            idleTimeoutMs: this.#idleTimeoutMs,
+            reconnectTimeoutMs: this.#reconnectTimeoutMs,
+            inboxCapacity: this.#inboxCapacity,
+            onEvent: this.#onEvent
+        });
+    }
+}
+function generateSessionID() {
+    return crypto.randomUUID();
+}

package/lib/sync/merkle-apply.d.ts

@@ -27,6 +27,11 @@ export type ApplySyncMutationsResult = {
     skipped: number;
     /** Count of mutations denied by the receive-time access gate. */
     dropped: number;
+    /**
+     * Count of mutations whose apply failed transiently (store/db error). No log
+     * row is written for these, so the next merkle round re-fetches and retries.
+     */
+    deferred: number;
 };
 /**
  * Apply mutation JWTs received from a peer via Merkle sync.

package/lib/sync/merkle-apply.js

@@ -1 +1,194 @@
-import{asType as t,createValidator as e}from"@enkaku/schema";import{verifyToken as a}from"@enkaku/token";import{computeMutationHash as i}from"@kubun/engine";import{DocumentID as o}from"@kubun/id";import{documentMutation as n}from"@kubun/protocol";import{getGraphStore as r}from"@kubun/store-graph";import{getP2PStore as u}from"@kubun/store-p2p";import{createReceiveAccessGate as s}from"./receive-access-gate.js";let l=e(n);export async function applySyncMutations(e){let n,{db:c,graph:d,mutationJWTs:p}=e,f=await r(c);if("drop"===(e.storeUnreadable??"persist")){if(null==e.selfDID)throw Error("applySyncMutations: 'storeUnreadable: drop' requires selfDID");let t=await u(c);n=s({selfDID:e.selfDID,db:{getUserModelAccessDefault:(t,e,a)=>f.getUserModelAccessDefault(t,e,a),isMemberOfAnyCircle:(e,a)=>t.isMemberOfAnyCircle(e,a),isMemberOfAnyGroup:(e,a)=>t.isMemberOfAnyGroup(e,a),getModelInterfaces:t=>f.getModelInterfaces(t)},defaultAccessLevel:e.defaultAccessLevel??{read:"only_owner",write:"only_owner"}})}let m=0,h=0,y=0,w=0,g=0;for(let e of p){let r,u=i(e);if(await f.hasMutationHash(u)){w++;continue}try{let i=await a(e);r=t(l,i.payload)}catch{h++;continue}let s=r.sub,c=o.fromString(s).model.toString(),p=o.fromString(s);if(null==await f.getDocument(p)&&"change"===r.typ){await f.insertMutationLogEntry({mutation_hash:u,model_id:c,document_id:s,author_did:r.iss,hlc:r.hlc,mutation_jwt:e,status:"pending"}),y++;continue}try{if((await d.applyVerifiedMutation({token:e,origin:"peer",...null!=n?{accessGate:n}:{}})).dropped){g++;continue}if(m++,"set"===r.typ)for(let t of(await f.getPendingMutations(s)))try{if((await d.applyVerifiedMutation({token:t.mutation_jwt,origin:"peer",...null!=n?{accessGate:n}:{}})).dropped){await f.updateMutationStatus(t.mutation_hash,"rejected"),g++;continue}await f.updateMutationStatus(t.mutation_hash,"applied"),m++}catch{await f.updateMutationStatus(t.mutation_hash,"rejected"),h++}}catch{await f.insertMutationLogEntry({mutation_hash:u,model_id:c,document_id:s,author_did:r.iss,hlc:r.hlc,mutation_jwt:e,status:"rejected"}),h++}}return{applied:m,rejected:h,pending:y,skipped:w,dropped:g}}
+import { verifyToken } from '@kokuin/token';
+import { computeMutationHash } from '@kubun/engine';
+import { DocumentID } from '@kubun/id';
+import { isPermanentApplyError } from '@kubun/mutation';
+import { documentMutation } from '@kubun/protocol';
+import { getGraphStore } from '@kubun/store-graph';
+import { asType, createValidator } from '@sozai/schema';
+import { rethrowIfProgrammerError } from './forwarder.js';
+import { createReceiveAccessGate } from './receive-access-gate.js';
+const validateMutation = createValidator(documentMutation);
+/**
+ * Apply mutation JWTs received from a peer via Merkle sync.
+ *
+ * Routes the successful-apply path through {@link GraphInternals.applyVerifiedMutation}
+ * with `origin: 'peer'` so GraphQL subscriptions (and other engine event
+ * consumers) fire for peer-received documents. The engine handles JWT
+ * verification, validator cache, applying the mutation, and inserting the
+ * `status: 'applied'` mutation log entry.
+ *
+ * Paths that bypass the engine (manual mutation-log insert):
+ * - **skipped**: mutation hash already seen — no-op.
+ * - **pending**: change mutation for a document that doesn't exist yet;
+ *   parked in the log with `status: 'pending'` to be resolved when the
+ *   set arrives.
+ * - **rejected**: JWT verify/validate fails, or engine throws during apply;
+ *   recorded with `status: 'rejected'`.
+ *
+ * We still verify + validate the JWT up front to peek at `mutation.typ` for
+ * the pending-path routing decision. The engine re-verifies on the success
+ * path (defense in depth + avoids plumbing verified payloads through the
+ * public API).
+ */ export async function applySyncMutations(params) {
+    const { db, graph, mutationJWTs } = params;
+    const graphStore = await getGraphStore(db);
+    const storeUnreadable = params.storeUnreadable ?? 'persist';
+    // Build the receive-time access gate as a factory over the apply's
+    // transaction-scoped stores so its access reads run inside the apply
+    // transaction (a main-connection read there deadlocks on single-connection
+    // SQLite). When `'persist'` (default), the gate is omitted —
+    // `applyVerifiedMutation` takes its existing zero-overhead no-gate path.
+    let accessGate;
+    if (storeUnreadable === 'drop') {
+        if (params.selfDID == null) {
+            throw new Error("applySyncMutations: 'storeUnreadable: drop' requires selfDID");
+        }
+        const selfDID = params.selfDID;
+        const defaultAccessLevel = params.defaultAccessLevel ?? {
+            read: 'only_owner',
+            write: 'only_owner'
+        };
+        accessGate = ({ graphStore: txGraphStore, p2pStore: txP2PStore })=>{
+            if (txP2PStore == null) {
+                return undefined;
+            }
+            return createReceiveAccessGate({
+                selfDID,
+                db: {
+                    getUserModelAccessDefault: (ownerDID, modelID, permissionType)=>txGraphStore.getUserModelAccessDefault(ownerDID, modelID, permissionType),
+                    isMemberOfAnyCircle: (viewerDID, circleIDs)=>txP2PStore.isMemberOfAnyCircle(viewerDID, circleIDs),
+                    isMemberOfAnyGroup: (viewerDID, groupIDs)=>txP2PStore.isMemberOfAnyGroup(viewerDID, groupIDs),
+                    getModelInterfaces: (modelID)=>txGraphStore.getModelInterfaces(modelID)
+                },
+                defaultAccessLevel
+            });
+        };
+    }
+    let applied = 0;
+    let rejected = 0;
+    let pending = 0;
+    let skipped = 0;
+    let dropped = 0;
+    let deferred = 0;
+    for (const jwt of mutationJWTs){
+        const mutationHash = computeMutationHash(jwt);
+        // Step 1: Dedup
+        if (await graphStore.hasMutationHash(mutationHash)) {
+            skipped++;
+            continue;
+        }
+        // Step 2: Verify JWT signature — needed to peek at mutation.typ for
+        // pending-path routing.
+        let mutation;
+        try {
+            const verified = await verifyToken(jwt);
+            mutation = asType(validateMutation, verified.payload);
+        } catch  {
+            rejected++;
+            continue;
+        }
+        const documentID = mutation.sub;
+        const modelID = DocumentID.fromString(documentID).model.toString();
+        // Step 3: Check if document exists for change mutations
+        const docID = DocumentID.fromString(documentID);
+        const doc = await graphStore.getDocument(docID);
+        if (doc == null && mutation.typ === 'change') {
+            await graphStore.insertMutationLogEntry({
+                mutation_hash: mutationHash,
+                model_id: modelID,
+                document_id: documentID,
+                author_did: mutation.iss,
+                hlc: mutation.hlc,
+                mutation_jwt: jwt,
+                status: 'pending'
+            });
+            pending++;
+            continue;
+        }
+        // Step 4: Route through engine so GraphQL subscriptions fire
+        try {
+            const applyResult = await graph.applyVerifiedMutation({
+                token: jwt,
+                origin: 'peer',
+                ...accessGate != null ? {
+                    accessGate
+                } : {}
+            });
+            if (applyResult.dropped) {
+                dropped++;
+                continue;
+            }
+            applied++;
+            // Step 5: Resolve pending mutations after set
+            if (mutation.typ === 'set') {
+                const pendingMutations = await graphStore.getPendingMutations(documentID);
+                for (const pendingEntry of pendingMutations){
+                    try {
+                        const pendingResult = await graph.applyVerifiedMutation({
+                            token: pendingEntry.mutation_jwt,
+                            origin: 'peer',
+                            ...accessGate != null ? {
+                                accessGate
+                            } : {}
+                        });
+                        if (pendingResult.dropped) {
+                            // Pending entry denied by gate. Mark the original pending row
+                            // resolved as `rejected` so downstream consumers don't keep
+                            // retrying it. The doc itself is on disk via the parent set
+                            // (which already passed the gate). Counted as `dropped`,
+                            // not `rejected`, to keep semantics aligned with the gate
+                            // definition.
+                            await graphStore.updateMutationStatus(pendingEntry.mutation_hash, 'rejected');
+                            dropped++;
+                            continue;
+                        }
+                        // Engine inserted a fresh `applied` log entry for the pending
+                        // mutation. Mark the original `pending` entry resolved too so
+                        // downstream consumers see consistent state.
+                        await graphStore.updateMutationStatus(pendingEntry.mutation_hash, 'applied');
+                        applied++;
+                    } catch (err) {
+                        rethrowIfProgrammerError(err);
+                        // A permanent reject converges the tree (mark resolved). A transient
+                        // failure leaves the `pending` row untouched: its hash already
+                        // dedups in the tree, so it is retried not by the next merkle round
+                        // but when a later set to this document re-walks `getPendingMutations`.
+                        if (isPermanentApplyError(err)) {
+                            await graphStore.updateMutationStatus(pendingEntry.mutation_hash, 'rejected');
+                            rejected++;
+                        } else {
+                            deferred++;
+                        }
+                    }
+                }
+            }
+        } catch (err) {
+            rethrowIfProgrammerError(err);
+            // A permanent reject persists a `rejected` row so the tree converges and
+            // the sender stops resending. A transient failure writes no row and is
+            // counted as deferred, so the next merkle round re-fetches and retries.
+            if (isPermanentApplyError(err)) {
+                await graphStore.insertMutationLogEntry({
+                    mutation_hash: mutationHash,
+                    model_id: modelID,
+                    document_id: documentID,
+                    author_did: mutation.iss,
+                    hlc: mutation.hlc,
+                    mutation_jwt: jwt,
+                    status: 'rejected'
+                });
+                rejected++;
+            } else {
+                deferred++;
+            }
+        }
+    }
+    return {
+        applied,
+        rejected,
+        pending,
+        skipped,
+        dropped,
+        deferred
+    };
+}

package/lib/sync/merkle-channel.d.ts

@@ -1,14 +1,20 @@
+import type { VerifyTokenHook } from '@kokuin/capability';
+import type { SignedPayload } from '@kokuin/token';
 import type { KubunDB } from '@kubun/db';
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { Logger } from '@kubun/logger';
 import type { SyncMerkleSyncParams, SyncMerkleSyncReceive, SyncMerkleSyncResult, SyncMerkleSyncSend } from '../protocol.js';
 import type { StoreUnreadableMode } from '../types.js';
+import { type PeerRegistry } from './peer-registry.js';
 /**
  * Minimal handler context shape for sync/merkle-sync channel.
  * Matches the Enkaku ChannelHandlerContext at runtime.
  */
 type MerkleSyncChannelContext = {
     param: SyncMerkleSyncParams;
+    message: {
+        payload: SignedPayload;
+    };
     readable: ReadableStream<SyncMerkleSyncSend>;
     writable: WritableStream<SyncMerkleSyncReceive>;
 };
@@ -16,6 +22,13 @@ export type CreateMerkleSyncChannelHandlerParams = {
     db: KubunDB;
     graph: GraphInternals;
     logger: Logger;
+    /**
+     * Per-peer policy registry. The requested direction is re-resolved against
+     * the peer's `allowedDirection` here: merkle-sync is the fail-closed backstop
+     * for a client that skips negotiate, so a disallowed direction is denied
+     * rather than downgraded.
+     */
+    peerRegistry: PeerRegistry;
     /**
      * Local peer's DID — required when `storeUnreadable === 'drop'` so the
      * receive-time access gate can use it as viewer.
@@ -28,6 +41,12 @@ export type CreateMerkleSyncChannelHandlerParams = {
     storeUnreadable?: StoreUnreadableMode;
     /** Server default access level — required when `storeUnreadable === 'drop'`. */
     defaultAccessLevel?: DefaultAccessLevel;
+    /**
+     * Resolves the revocation checker used to authorize delegated scopes. Shared
+     * with the negotiate handler so the two access gates use the same revocation
+     * state and cannot drift.
+     */
+    getRevocationChecker?: () => Promise<VerifyTokenHook>;
 };
 export declare function createMerkleSyncChannelHandler(params: CreateMerkleSyncChannelHandlerParams): (ctx: MerkleSyncChannelContext) => Promise<SyncMerkleSyncResult>;
 export {};