@kubun/plugin-p2p 0.10.1 → 0.12.0

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

@@ -1 +1,113 @@
-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 { APP_TOPIC_LABEL } from '@kumiai/rpc';
+import { createGroupCrypto } from '../groups/group-crypto.js';
+import { MLSEncryptor } from '../groups/mls-encryptor.js';
+import { createSenderScopedHubView } from '../hub/sender-scoped-hub-view.js';
+import { createTunnelEventLogger } from './tunnel-observability.js';
+import { tunnelTopic } from './tunnel-topics.js';
+export class HubTunnelSyncProvider {
+    #hub;
+    #registry;
+    #groupID;
+    #localDID;
+    #peerDID;
+    #runtime;
+    #idleTimeoutMs;
+    #reconnectTimeoutMs;
+    #inboxCapacity;
+    #onEvent;
+    #logger;
+    constructor(params){
+        this.#hub = params.hub;
+        this.#registry = params.registry;
+        this.#groupID = params.groupID;
+        this.#localDID = params.localDID;
+        this.#peerDID = params.peerDID;
+        this.#runtime = params.runtime;
+        this.#idleTimeoutMs = params.idleTimeoutMs;
+        this.#reconnectTimeoutMs = params.reconnectTimeoutMs;
+        this.#inboxCapacity = params.inboxCapacity;
+        this.#onEvent = params.onEvent;
+        this.#logger = params.logger;
+    }
+    /**
+   * Build a fresh client transport for one tunnel sync session.
+   *
+   * The tunnel rides group-scoped, ROLE-scoped topics derived from the group's
+   * current MLS epoch secret: outbound frames publish to the peer's responder
+   * topic, and the transport subscribes to this device's own dialer topic —
+   * which the peer's listener writes its answers to and nothing else does.
+   * 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 = this.#runtime.getRandomID();
+        const encryptor = new MLSEncryptor({
+            registry: this.#registry,
+            groupID: this.#groupID
+        });
+        // The seed epoch is unread here: this port never classifies commit frames,
+        // and `exportSecret()` below records the live epoch before `epoch()` is
+        // asked for it. Only a peer that opens a receive drain needs a real seed.
+        const crypto = createGroupCrypto({
+            registry: this.#registry,
+            groupID: this.#groupID,
+            initialEpoch: 0,
+            runtime: this.#runtime
+        });
+        const secret = await crypto.exportSecret(APP_TOPIC_LABEL);
+        const epoch = crypto.epoch();
+        const sendTopicID = tunnelTopic(secret, epoch, 'responder', this.#peerDID);
+        const receiveTopicID = tunnelTopic(secret, epoch, 'dialer', this.#localDID);
+        // Bound once and carried by every line this session logs, including the
+        // frame drops below. The transport's own idle timeout names none of this —
+        // it raises a bare `TimeoutInterruption` from inside the dependency — so
+        // attributing a starved session to a group, a peer and an epoch is only
+        // possible from here.
+        const sessionLogger = this.#logger?.with({
+            role: 'dialer',
+            groupID: this.#groupID,
+            peerDID: this.#peerDID,
+            sessionID,
+            epoch,
+            receiveTopicID
+        });
+        sessionLogger?.debug('tunnel session opening');
+        const transport = createEncryptedHubTunnelTransport({
+            // The peer-scoped VIEW, never the device hub: two sessions open at once
+            // receive on this same inbox topic, and a frame one of them opens is
+            // destroyed for the other — MLS consumes a ratchet generation per open.
+            // The loser starves to its idle timeout with nothing raised.
+            // The idle timeout is reused as the publish bound on purpose: "a session
+            // that gets nothing for N gives up" and "a session that cannot even send
+            // for N gives up" are one promise to whoever is waiting, and a second knob
+            // would only let the two drift apart.
+            hub: createSenderScopedHubView({
+                hub: this.#hub,
+                peerDID: this.#peerDID,
+                ...this.#idleTimeoutMs == null ? {} : {
+                    publishTimeoutMs: this.#idleTimeoutMs
+                }
+            }),
+            encryptor,
+            groupID: this.#groupID,
+            sessionID,
+            localDID: this.#localDID,
+            sendTopicID,
+            receiveTopicID,
+            signal,
+            idleTimeoutMs: this.#idleTimeoutMs,
+            reconnectTimeoutMs: this.#reconnectTimeoutMs,
+            inboxCapacity: this.#inboxCapacity,
+            onEvent: sessionLogger == null ? this.#onEvent : createTunnelEventLogger(sessionLogger, this.#onEvent)
+        });
+        // The close is as load-bearing as the open: a session that ends without
+        // having received anything is what an unreachable peer looks like, and the
+        // pair of lines is what says whether it ran for milliseconds or waited out
+        // the full idle window.
+        transport.events.on('disposed', ()=>{
+            sessionLogger?.debug('tunnel session closed');
+        });
+        return transport;
+    }
+}

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,10 +1,11 @@
-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 DefaultAccessLevel, type 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 CircleReadGrantResolver } from './authorize.js';
 import { type PeerRegistry } from './peer-registry.js';
 /**
  * Minimal handler context shape for sync/merkle-sync channel.
@@ -47,6 +48,13 @@ export type CreateMerkleSyncChannelHandlerParams = {
      * state and cannot drift.
      */
     getRevocationChecker?: () => Promise<VerifyTokenHook>;
+    /**
+     * Resolves the circle-granted read resolver. Shared with the negotiate handler
+     * so both gates accept identical scopes. Enables a circle member to pull an
+     * owner's docs for a model the owner's tier-2 read default shares with that
+     * circle.
+     */
+    getCircleReadGrant?: () => Promise<CircleReadGrantResolver>;
 };
 export declare function createMerkleSyncChannelHandler(params: CreateMerkleSyncChannelHandlerParams): (ctx: MerkleSyncChannelContext) => Promise<SyncMerkleSyncResult>;
 export {};

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
@@ -8,15 +8,23 @@ import type { SyncDirection } from '../protocol.js';
  * Otherwise the responder's policy wins.
  */
 export declare function negotiateDirection(requested: SyncDirection, allowed: SyncDirection): SyncDirection;
+/**
+ * How to REACH a peer, plus the one policy a responder applies to it.
+ *
+ * Deliberately not a place to say what a peer may see. This row is written
+ * locally by whichever side dialled, nothing authenticates it, and it is absent
+ * entirely for a co-member reached through a group tunnel — so a gate keyed on
+ * it would be missing exactly when peering works as designed. What a peer may
+ * read is decided per document at the far end, against its authenticated DID.
+ */
 export type PeerConfig = {
     peerDID: string;
     endpoint: string;
-    mode: 'persistent' | 'on-demand';
-    allowedUsers: Array<string> | {
-        all: boolean;
-    };
-    priority: string;
-    trustLevel: 'trusted' | 'restricted';
+    /**
+     * What this device is willing to do with this peer — a resource decision
+     * about its own disk and apply path, not a claim about the peer's rights.
+     * The responder's policy wins; see {@link negotiateDirection}.
+     */
     allowedDirection?: SyncDirection;
 };
 export type PeerConfigWithID = PeerConfig & {
@@ -50,8 +58,4 @@ export declare class PeerRegistry {
         peerDID: string;
         stores: StoreProvider;
     }): Promise<void>;
-    isPeerAllowed(params: {
-        peerDID: string;
-        stores: StoreProvider;
-    }): Promise<boolean>;
 }

package/lib/sync/peer-registry.js

@@ -1 +1,82 @@
-import{getP2PStore as e}from"@kubun/store-p2p";export function negotiateDirection(e,t){return"both"===t?e:"both"===e?t:e===t?e:t}function t(e){var t,r;let o="string"==typeof(t=e.config)?JSON.parse(t):t??{};return{id:e.id,peerDID:e.peer_did,endpoint:e.endpoint,mode:e.mode,allowedUsers:"string"==typeof(r=e.allowed_users)?JSON.parse(r):r,priority:e.priority,trustLevel:e.trust_level,allowedDirection:o.allowedDirection,createdAt:e.created_at,updatedAt:e.updated_at}}export class PeerRegistry{#e;constructor(e){this.#e=e.runtime}async addPeer(t){let r=await e(t.stores);await r.addSyncPeer({id:this.#e.getRandomID(),peer_did:t.config.peerDID,endpoint:t.config.endpoint,mode:t.config.mode,allowed_users:t.config.allowedUsers,priority:t.config.priority,trust_level:t.config.trustLevel,config:{allowedDirection:t.config.allowedDirection},created_at:Date.now(),updated_at:Date.now()})}async getPeer(r){let o=await e(r.stores),i=await o.getSyncPeer(r.peerDID);if(i)return t(i)}async listPeers(r){let o=await e(r.stores);return(await o.listSyncPeers()).map(e=>t(e))}async updatePeer(t){let r=await this.getPeer({peerDID:t.peerDID,stores:t.stores});if(!r)throw Error(`Peer ${t.peerDID} not found`);let o={...r,...t.updates},i=await e(t.stores);await i.updateSyncPeer(t.peerDID,{endpoint:o.endpoint,mode:o.mode,allowed_users:o.allowedUsers,priority:o.priority,trust_level:o.trustLevel,config:{allowedDirection:o.allowedDirection}})}async removePeer(t){let r=await e(t.stores);await r.removeSyncPeer(t.peerDID)}async isPeerAllowed(e){return void 0!==await this.getPeer({peerDID:e.peerDID,stores:e.stores})}}
+import { getP2PStore } from '@kubun/store-p2p';
+/**
+ * Resolve the effective sync direction given what the initiator requested
+ * and what the responder's per-peer policy allows.
+ * If allowed is 'both' (or unset), the request passes through.
+ * Otherwise the responder's policy wins.
+ */ export function negotiateDirection(requested, allowed) {
+    if (allowed === 'both') return requested;
+    if (requested === 'both') return allowed;
+    if (requested === allowed) return requested;
+    // Incompatible — responder policy wins
+    return allowed;
+}
+function parseConfig(value) {
+    if (typeof value === 'string') {
+        return JSON.parse(value);
+    }
+    return value ?? {};
+}
+function rowToPeerConfig(row) {
+    const config = parseConfig(row.config);
+    return {
+        id: row.id,
+        peerDID: row.peer_did,
+        endpoint: row.endpoint,
+        allowedDirection: config.allowedDirection,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+    };
+}
+export class PeerRegistry {
+    #runtime;
+    constructor(params){
+        this.#runtime = params.runtime;
+    }
+    async addPeer(params) {
+        const store = await getP2PStore(params.stores);
+        await store.addSyncPeer({
+            id: this.#runtime.getRandomID(),
+            peer_did: params.config.peerDID,
+            endpoint: params.config.endpoint,
+            config: {
+                allowedDirection: params.config.allowedDirection
+            },
+            created_at: Date.now(),
+            updated_at: Date.now()
+        });
+    }
+    async getPeer(params) {
+        const store = await getP2PStore(params.stores);
+        const row = await store.getSyncPeer(params.peerDID);
+        if (!row) return undefined;
+        return rowToPeerConfig(row);
+    }
+    async listPeers(params) {
+        const store = await getP2PStore(params.stores);
+        const rows = await store.listSyncPeers();
+        return rows.map((row)=>rowToPeerConfig(row));
+    }
+    async updatePeer(params) {
+        const current = await this.getPeer({
+            peerDID: params.peerDID,
+            stores: params.stores
+        });
+        if (!current) throw new Error(`Peer ${params.peerDID} not found`);
+        const updated = {
+            ...current,
+            ...params.updates
+        };
+        const store = await getP2PStore(params.stores);
+        await store.updateSyncPeer(params.peerDID, {
+            endpoint: updated.endpoint,
+            config: {
+                allowedDirection: updated.allowedDirection
+            }
+        });
+    }
+    async removePeer(params) {
+        const store = await getP2PStore(params.stores);
+        await store.removeSyncPeer(params.peerDID);
+    }
+}

package/lib/sync/receive-access-gate.js

@@ -1 +1,24 @@
-import{createAccessChecker as e}from"@kubun/engine";export function createReceiveAccessGate(c){let t=e({viewerDID:c.selfDID,db:c.db,defaultAccessLevel:c.defaultAccessLevel});return e=>t(e,"read")}
+import { createAccessChecker } from '@kubun/engine';
+/**
+ * Build an {@link AccessGate} that returns `true` iff the local peer can
+ * read the post-state document under the resolved access rule.
+ *
+ * Used by the receive paths (`processBroadcast` mutation:apply branch and
+ * `applySyncMutations`) when `storeUnreadable: 'drop'` is configured. The
+ * gate is intentionally cheap to construct — the heavy work (rule
+ * resolution + membership lookups) happens lazily when the gate is invoked
+ * inside the engine's apply pipeline.
+ *
+ * Drop-mode access checks happen at receive time without delegation
+ * token context (the broadcast doesn't carry tokens). A peer who would
+ * gain read access only via a delegation token will have the doc
+ * dropped under `storeUnreadable: 'drop'`. Use `'persist'` if delegation
+ * chains must be honored at receive time.
+ */ export function createReceiveAccessGate(params) {
+    const checker = createAccessChecker({
+        viewerDID: params.selfDID,
+        db: params.db,
+        defaultAccessLevel: params.defaultAccessLevel
+    });
+    return (postState)=>checker(postState, 'read');
+}