@kubun/plugin-p2p 0.10.1 → 0.11.0

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,5 +1,5 @@
-import type { VerifyTokenHook } from '@enkaku/capability';
-import type { SignedPayload } from '@enkaku/token';
+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';

package/lib/sync/merkle-channel.js

@@ -1 +1,182 @@
-import{getGraphStore as e}from"@kubun/store-graph";import{authorizeScope as t}from"./authorize.js";import{SyncAccessDeniedError as r}from"./errors.js";import{applySyncMutations as i}from"./merkle-apply.js";import{buildMerkleTree as n,findDivergentBuckets as a,getTimeBuckets as s,SYNC_BATCH_SIZE as o}from"./merkle-tree.js";import{negotiateDirection as l}from"./peer-registry.js";export function createMerkleSyncChannelHandler(c){let{db:d,graph:u,logger:m}=c,p=c.storeUnreadable??"persist";return async y=>{let{scopes:f,excludedDocumentIDs:w,tree:g,direction:h}=y.param,k=y.message?.payload;if(k?.iss==null)throw new r("unsigned","Sync access denied: missing verified signer");if(null!=k.sub&&k.sub!==k.iss)throw new r("forged-subject","Sync access denied: signed payload subject does not match issuer");let D=k.iss,b=null!=c.getRevocationChecker?await c.getRevocationChecker():void 0;for(let e of f)if(!await t({viewerDID:D,ownerDID:e.ownerDID,delegationTokens:y.param.delegationTokens??[],revocationChecker:b}))throw new r("scope-denied",`Sync access denied: caller not authorized for scope ${e.modelID}/${e.ownerDID}`);let v=h??"pull",j=await c.peerRegistry.getPeer({peerDID:D,stores:d});if(l(v,j?.allowedDirection??"both")!==v)throw new r("direction-denied",`Sync access denied: direction ${v} not permitted by peer policy`);let I=y.writable.getWriter();m.info("sync/merkle-sync channel started",{scopes:f,excludedDocumentIDs:w,direction:h});let S=0,T=0,R=0;try{let t=await e(d),r=await t.getDocumentIDsForScope(f,w),l=await t.getMutationLogForDocuments(r),k=n(l);await I.write({type:"tree",tree:k.buckets});let D={root:g.root??"",buckets:g},b=a(k,D);S=b.length;let v=async()=>{if("pull"===h||"both"===h){let e=new Set(b),t=l.filter(t=>{let{minute:r}=s(t.hlc);return e.has(r)});for(let e=0;e<t.length;e+=o){let r=t.slice(e,e+o);await I.write({type:"mutations",mutationJWTs:r.map(e=>e.mutation_jwt)}),T+=r.length}await I.write({type:"complete"})}else await I.write({type:"complete"})},j=async()=>{let e=[],t=y.readable.getReader();try{for(;;){let{done:r,value:i}=await t.read();if(r)break;if("mutations"===i.type&&null!=i.mutationJWTs)e.push(...i.mutationJWTs);else if("complete"===i.type)break}}finally{t.releaseLock()}return e},[,W]=await Promise.all([v(),j()]);if(W.length>0){let e=await i({db:d,graph:u,mutationJWTs:W,selfDID:c.selfDID,storeUnreadable:p,defaultAccessLevel:c.defaultAccessLevel});R=e.applied+e.pending,m.info("sync/merkle-sync: applied received mutations",{result:e})}}catch(e){return m.error("sync/merkle-sync channel error",{error:e}),{success:!1,divergentBuckets:0,mutationsSent:0,mutationsReceived:0}}finally{try{await I.close()}catch{}}return m.info("sync/merkle-sync channel completed",{divergentBuckets:S,mutationsSent:T,mutationsReceived:R}),{success:!0,divergentBuckets:S,mutationsSent:T,mutationsReceived:R}}}
+import { getGraphStore } from '@kubun/store-graph';
+import { authorizeScope } from './authorize.js';
+import { SyncAccessDeniedError } from './errors.js';
+import { applySyncMutations } from './merkle-apply.js';
+import { buildMerkleTree, findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-tree.js';
+import { negotiateDirection } from './peer-registry.js';
+export function createMerkleSyncChannelHandler(params) {
+    const { db, graph, logger } = params;
+    const storeUnreadable = params.storeUnreadable ?? 'persist';
+    return async (ctx)=>{
+        const { scopes, excludedDocumentIDs, tree: remoteTree, direction } = ctx.param;
+        // Authorize before any store read. The viewer is the cryptographically
+        // verified signer (`iss`). A signed payload always carries `iss`; no
+        // legitimate kubun client sets `sub`, so a `sub` that differs from `iss`
+        // is a forgery attempt and is denied here. Every requested scope must then
+        // be authorized (owner or valid delegation); the first unauthorized scope
+        // fails the whole request with no partial filtering and no store read.
+        // The throw propagates to the caller as a rejected channel call.
+        // The payload is always present under requireAuth (identity is set on every
+        // sync Server), but guard defensively: a caller that reaches this handler
+        // without a verified signer must be denied, never treated as a viewer.
+        const payload = ctx.message?.payload;
+        if (payload?.iss == null) {
+            throw new SyncAccessDeniedError('unsigned', 'Sync access denied: missing verified signer');
+        }
+        if (payload.sub != null && payload.sub !== payload.iss) {
+            throw new SyncAccessDeniedError('forged-subject', 'Sync access denied: signed payload subject does not match issuer');
+        }
+        const viewerDID = payload.iss;
+        const revocationChecker = params.getRevocationChecker != null ? await params.getRevocationChecker() : undefined;
+        for (const scope of scopes){
+            const authorized = await authorizeScope({
+                viewerDID,
+                ownerDID: scope.ownerDID,
+                delegationTokens: ctx.param.delegationTokens ?? [],
+                revocationChecker
+            });
+            if (!authorized) {
+                throw new SyncAccessDeniedError('scope-denied', `Sync access denied: caller not authorized for scope ${scope.modelID}/${scope.ownerDID}`);
+            }
+        }
+        // Re-resolve the requested direction against the peer's policy. A client can
+        // reach merkle-sync without negotiating, so this is the fail-closed backstop:
+        // a direction the peer policy does not allow is denied here, not downgraded.
+        // Unknown peers have no policy and default to 'both', so they pass through.
+        // Note the policy is keyed on the verified signing DID: it only applies when
+        // the signer matches a registered peer DID, so direction restriction is not
+        // enforced for callers whose signing identity differs from any peer record
+        // (the scope gate above, not this knob, is the access-control boundary).
+        const requestedDirection = direction ?? 'pull';
+        const peer = await params.peerRegistry.getPeer({
+            peerDID: viewerDID,
+            stores: db
+        });
+        const agreedDirection = negotiateDirection(requestedDirection, peer?.allowedDirection ?? 'both');
+        if (agreedDirection !== requestedDirection) {
+            throw new SyncAccessDeniedError('direction-denied', `Sync access denied: direction ${requestedDirection} not permitted by peer policy`);
+        }
+        const writer = ctx.writable.getWriter();
+        logger.info('sync/merkle-sync channel started', {
+            scopes,
+            excludedDocumentIDs,
+            direction
+        });
+        let divergentBucketCount = 0;
+        let mutationsSent = 0;
+        let mutationsReceived = 0;
+        try {
+            const graphStore = await getGraphStore(db);
+            // Step 1: Get all document IDs for the agreed scope
+            const documentIDs = await graphStore.getDocumentIDsForScope(scopes, excludedDocumentIDs);
+            // Step 2: Get all mutation log entries for these documents
+            const localEntries = await graphStore.getMutationLogForDocuments(documentIDs);
+            // Step 3: Build local merkle tree
+            const localTree = buildMerkleTree(localEntries);
+            // Step 4: Send local tree to initiator
+            await writer.write({
+                type: 'tree',
+                tree: localTree.buckets
+            });
+            // Step 5: Find divergent buckets
+            const remoteMerkle = {
+                root: remoteTree.root ?? '',
+                buckets: remoteTree
+            };
+            const divergentBuckets = findDivergentBuckets(localTree, remoteMerkle);
+            divergentBucketCount = divergentBuckets.length;
+            // Step 6: Concurrent send and receive
+            const sendTask = async ()=>{
+                if (direction === 'pull' || direction === 'both') {
+                    // Filter local entries to those in divergent buckets
+                    const divergentSet = new Set(divergentBuckets);
+                    const entriesToSend = localEntries.filter((entry)=>{
+                        const { minute } = getTimeBuckets(entry.hlc);
+                        return divergentSet.has(minute);
+                    });
+                    // Send in batches
+                    for(let i = 0; i < entriesToSend.length; i += SYNC_BATCH_SIZE){
+                        const batch = entriesToSend.slice(i, i + SYNC_BATCH_SIZE);
+                        await writer.write({
+                            type: 'mutations',
+                            mutationJWTs: batch.map((e)=>e.mutation_jwt)
+                        });
+                        mutationsSent += batch.length;
+                    }
+                    await writer.write({
+                        type: 'complete'
+                    });
+                } else {
+                    // direction === 'push': no mutations to send, just signal complete
+                    await writer.write({
+                        type: 'complete'
+                    });
+                }
+            };
+            const receiveTask = async ()=>{
+                const collectedJWTs = [];
+                const reader = ctx.readable.getReader();
+                try {
+                    while(true){
+                        const { done, value } = await reader.read();
+                        if (done) break;
+                        if (value.type === 'mutations' && value.mutationJWTs != null) {
+                            collectedJWTs.push(...value.mutationJWTs);
+                        } else if (value.type === 'complete') {
+                            break;
+                        }
+                    }
+                } finally{
+                    reader.releaseLock();
+                }
+                return collectedJWTs;
+            };
+            const [, receivedJWTs] = await Promise.all([
+                sendTask(),
+                receiveTask()
+            ]);
+            // Apply received mutations
+            if (receivedJWTs.length > 0) {
+                const result = await applySyncMutations({
+                    db,
+                    graph,
+                    mutationJWTs: receivedJWTs,
+                    selfDID: params.selfDID,
+                    storeUnreadable,
+                    defaultAccessLevel: params.defaultAccessLevel
+                });
+                mutationsReceived = result.applied + result.pending;
+                logger.info('sync/merkle-sync: applied received mutations', {
+                    result
+                });
+            }
+        } catch (error) {
+            logger.error('sync/merkle-sync channel error', {
+                error
+            });
+            return {
+                success: false,
+                divergentBuckets: 0,
+                mutationsSent: 0,
+                mutationsReceived: 0
+            };
+        } finally{
+            try {
+                await writer.close();
+            } catch  {
+            // Writer may already be closed by Enkaku's handler wrapper
+            }
+        }
+        logger.info('sync/merkle-sync channel completed', {
+            divergentBuckets: divergentBucketCount,
+            mutationsSent,
+            mutationsReceived
+        });
+        return {
+            success: true,
+            divergentBuckets: divergentBucketCount,
+            mutationsSent,
+            mutationsReceived
+        };
+    };
+}

package/lib/sync/merkle-tree.js

@@ -1 +1,120 @@
-import{blake3 as t}from"@noble/hashes/blake3.js";export const SYNC_BATCH_SIZE=1e3;let e=[4,7,10,16],o=new TextEncoder;export function getTimeBuckets(t){return{year:t.slice(0,4),month:t.slice(0,7),day:t.slice(0,10),minute:t.slice(0,16)}}function r(e){return Array.from(t(o.encode(e))).map(t=>t.toString(16).padStart(2,"0")).join("")}export function buildMerkleTree(t){if(0===t.length)return{root:"",buckets:{}};let e=new Map;for(let o of t){let{minute:t}=getTimeBuckets(o.hlc),r=e.get(t);null==r&&(r=[],e.set(t,r)),r.push(o)}let o={};for(let[t,n]of e){let e=[...n].sort((t,e)=>t.mutation_hash<e.mutation_hash?-1:+(t.mutation_hash>e.mutation_hash)).map(t=>t.mutation_hash).join("\n");o[t]=r(e)}for(let t of[10,7,4]){let e=10===t?16:7===t?10:7,n=new Map;for(let r of Object.keys(o)){if(r.length!==e)continue;let o=r.slice(0,t),s=n.get(o);null==s&&(s=[],n.set(o,s)),s.push(r)}for(let[t,e]of n){let n=e.sort().map(t=>`${t}\0${o[t]}`).join("\n");o[t]=r(n)}}let n=r(Object.keys(o).filter(t=>4===t.length).sort().map(t=>`${t}\0${o[t]}`).join("\n"));return o.root=n,{root:n,buckets:o}}export function findDivergentBuckets(t,o){if(t.root===o.root)return[];if(""===t.root)return Object.keys(o.buckets).filter(t=>16===t.length).sort();if(""===o.root)return Object.keys(t.buckets).filter(t=>16===t.length).sort();let r=[],n=new Set([...Object.keys(t.buckets),...Object.keys(o.buckets)]);return!function s(l,i){let u=e[i];for(let c of[...n].filter(t=>t.length===u&&(""===l||t.startsWith(l))).sort())t.buckets[c]!==o.buckets[c]&&(i===e.length-1?r.push(c):s(c,i+1))}("",0),r.sort()}
+import { blake3 } from '@noble/hashes/blake3.js';
+/** Maximum number of mutation JWTs to send in a single channel message. */ export const SYNC_BATCH_SIZE = 1000;
+// Bucket key lengths: year=4, month=7, day=10, minute=16
+const BUCKET_LEVELS = [
+    4,
+    7,
+    10,
+    16
+];
+const MINUTE_KEY_LENGTH = 16;
+const encoder = new TextEncoder();
+export function getTimeBuckets(hlc) {
+    // HLC format: "2026-02-14T10:30:45.123Z:0001:nodeID"
+    return {
+        year: hlc.slice(0, 4),
+        month: hlc.slice(0, 7),
+        day: hlc.slice(0, 10),
+        minute: hlc.slice(0, 16)
+    };
+}
+function hashHex(input) {
+    const digest = blake3(encoder.encode(input));
+    return Array.from(digest).map((b)=>b.toString(16).padStart(2, '0')).join('');
+}
+export function buildMerkleTree(entries) {
+    if (entries.length === 0) {
+        return {
+            root: '',
+            buckets: {}
+        };
+    }
+    // Group entries by minute bucket
+    const minuteGroups = new Map();
+    for (const entry of entries){
+        const { minute } = getTimeBuckets(entry.hlc);
+        let group = minuteGroups.get(minute);
+        if (group == null) {
+            group = [];
+            minuteGroups.set(minute, group);
+        }
+        group.push(entry);
+    }
+    const buckets = {};
+    // Hash each minute bucket (leaf nodes)
+    for (const [minuteKey, bucketEntries] of minuteGroups){
+        const sorted = [
+            ...bucketEntries
+        ].sort((a, b)=>a.mutation_hash < b.mutation_hash ? -1 : a.mutation_hash > b.mutation_hash ? 1 : 0);
+        const content = sorted.map((e)=>e.mutation_hash).join('\n');
+        buckets[minuteKey] = hashHex(content);
+    }
+    // Build parent buckets bottom-up: day from minutes, month from days, year from months
+    const parentLevels = [
+        10,
+        7,
+        4
+    ]// day, month, year (key lengths)
+    ;
+    for (const parentLength of parentLevels){
+        const childLength = parentLength === 10 ? 16 : parentLength === 7 ? 10 : 7;
+        const groups = new Map();
+        for (const key of Object.keys(buckets)){
+            if (key.length !== childLength) continue;
+            const parentKey = key.slice(0, parentLength);
+            let group = groups.get(parentKey);
+            if (group == null) {
+                group = [];
+                groups.set(parentKey, group);
+            }
+            group.push(key);
+        }
+        for (const [parentKey, childKeys] of groups){
+            const sorted = childKeys.sort();
+            const content = sorted.map((k)=>`${k}\0${buckets[k]}`).join('\n');
+            buckets[parentKey] = hashHex(content);
+        }
+    }
+    // Build root hash from year buckets
+    const yearKeys = Object.keys(buckets).filter((k)=>k.length === 4).sort();
+    const rootContent = yearKeys.map((k)=>`${k}\0${buckets[k]}`).join('\n');
+    const root = hashHex(rootContent);
+    buckets.root = root;
+    return {
+        root,
+        buckets
+    };
+}
+export function findDivergentBuckets(local, remote) {
+    if (local.root === remote.root) return [];
+    // If either tree is empty, all of the other's minute buckets diverge
+    if (local.root === '') {
+        return Object.keys(remote.buckets).filter((k)=>k.length === MINUTE_KEY_LENGTH).sort();
+    }
+    if (remote.root === '') {
+        return Object.keys(local.buckets).filter((k)=>k.length === MINUTE_KEY_LENGTH).sort();
+    }
+    const divergent = [];
+    const allKeys = new Set([
+        ...Object.keys(local.buckets),
+        ...Object.keys(remote.buckets)
+    ]);
+    function walk(prefix, levelIndex) {
+        const keyLength = BUCKET_LEVELS[levelIndex];
+        const keysAtLevel = [
+            ...allKeys
+        ].filter((k)=>k.length === keyLength && (prefix === '' || k.startsWith(prefix))).sort();
+        for (const key of keysAtLevel){
+            if (local.buckets[key] === remote.buckets[key]) continue;
+            if (levelIndex === BUCKET_LEVELS.length - 1) {
+                // Leaf level (minute) — this bucket diverges
+                divergent.push(key);
+            } else {
+                // Drill into next level
+                walk(key, levelIndex + 1);
+            }
+        }
+    }
+    walk('', 0);
+    return divergent.sort();
+}

package/lib/sync/peer-registry.d.ts

@@ -1,5 +1,5 @@
-import type { Runtime } from '@enkaku/runtime';
 import type { StoreProvider } from '@kubun/db';
+import type { Runtime } from '@sozai/runtime';
 import type { SyncDirection } from '../protocol.js';
 /**
  * Resolve the effective sync direction given what the initiator requested