@kubun/plugin-p2p 0.8.3 → 0.10.0

package/lib/sync/broadcast-queue.d.ts

@@ -0,0 +1,59 @@
+import type { Logger } from '@kubun/logger';
+import type { GroupBroadcastMessage, MutationApplyEntry } from '../groups/broadcast.js';
+/**
+ * Configuration for the per-target-group batch broadcast queue.
+ *
+ * Each queue accumulates {@link MutationApplyEntry} items destined for the
+ * same MLS group, then flushes them as a single `mutation:apply` broadcast
+ * when ANY threshold trips:
+ * - `windowMs` elapses since the first entry of the current batch
+ * - the queue accumulates `maxCount` entries
+ * - the accumulated byte size hits `maxBytes`
+ *
+ * When `enabled` is false, the queue degrades to pass-through: each enqueue
+ * fires `scheduleBroadcast` immediately as a single-entry batch.
+ */
+export type BroadcastBatchConfig = {
+    enabled: boolean;
+    windowMs: number;
+    maxCount: number;
+    maxBytes: number;
+};
+export declare const DEFAULT_BROADCAST_BATCH_CONFIG: BroadcastBatchConfig;
+export type BroadcastQueueParams = {
+    config: BroadcastBatchConfig;
+    scheduleBroadcast: (groupID: string, message: GroupBroadcastMessage) => void;
+    logger?: Logger;
+};
+export type BroadcastQueue = {
+    /**
+     * Enqueue a single mutation entry for the given target group, attributed to
+     * `senderPeerDID`. May trigger an immediate flush if a threshold is reached.
+     */
+    enqueue(targetGroupID: string, entry: MutationApplyEntry, senderPeerDID: string): void;
+    /**
+     * Cancel all pending timers and synchronously flush remaining entries
+     * via `scheduleBroadcast`. Safe to call multiple times.
+     */
+    dispose(): void;
+};
+/**
+ * Build a per-target-group batch queue around a `scheduleBroadcast` hook.
+ *
+ * The `mutation:apply` broadcast variant carries `entries: Array<...>` —
+ * a queue flush emits ONE broadcast with the accumulated entries, not one
+ * broadcast per entry.
+ *
+ * Each enqueued entry's wire size is approximated via `JSON.stringify(entry).length`.
+ * The accumulated byte budget tracks per-batch payload size only — message
+ * envelope (`type`, `senderPeerDID`) overhead is intentionally ignored to keep
+ * accounting cheap and predictable.
+ *
+ * Sender-DID consistency: the queue tracks the `senderPeerDID` of the first
+ * entry in each batch. If a later enqueue arrives with a different sender
+ * (defensive — in practice senderPeerDID is constant per peer), the prior
+ * batch is flushed and a fresh batch starts. This preserves the invariant
+ * that every flushed `mutation:apply` message carries a single coherent
+ * `senderPeerDID`.
+ */
+export declare function createBroadcastQueue(params: BroadcastQueueParams): BroadcastQueue;

package/lib/sync/broadcast-queue.js

@@ -0,0 +1 @@
+export const DEFAULT_BROADCAST_BATCH_CONFIG={enabled:!0,windowMs:500,maxCount:20,maxBytes:65536};export function createBroadcastQueue(e){let{config:t,scheduleBroadcast:r,logger:n}=e,l=new Map,o=!1;function u(e){let t=l.get(e);if(null==t||0===t.entries.length)return;null!=t.timer&&(clearTimeout(t.timer),t.timer=null);let o=t.entries,u=t.senderPeerDID;l.delete(e);try{r(e,{type:"mutation:apply",entries:o,senderPeerDID:u})}catch(t){n?.warn("broadcast-queue flush failed",{targetGroupID:e,entryCount:o.length,error:String(t)})}}return{enqueue:function(e,i,a){if(o)return void n?.warn("broadcast-queue enqueue after dispose, dropping entry",{targetGroupID:e,docID:i.docID});if(!t.enabled){try{r(e,{type:"mutation:apply",entries:[i],senderPeerDID:a})}catch(t){n?.warn("broadcast-queue pass-through scheduleBroadcast failed",{targetGroupID:e,docID:i.docID,error:String(t)})}return}let s=JSON.stringify(i).length;if(s>=t.maxBytes){let t=l.get(e);null!=t&&t.entries.length>0&&u(e);try{r(e,{type:"mutation:apply",entries:[i],senderPeerDID:a})}catch(t){n?.warn("broadcast-queue oversize-entry scheduleBroadcast failed",{targetGroupID:e,docID:i.docID,error:String(t)})}return}let d=l.get(e);if(null!=d&&d.senderPeerDID!==a&&(u(e),d=void 0),null!=d&&d.bytes+s>t.maxBytes&&(u(e),d=void 0),null==d){l.set(e,{entries:[i],bytes:s,senderPeerDID:a,timer:null});let r=l.get(e);return null!=r&&r.entries.length>=t.maxCount?void u(e):void!function(e){let r=l.get(e);if(null==r||null!=r.timer)return;let n=setTimeout(()=>{u(e)},t.windowMs),o=n.unref;"function"==typeof o&&o.call(n),r.timer=n}(e)}d.entries.push(i),d.bytes+=s,d.entries.length>=t.maxCount&&u(e)},dispose:function(){if(!o)for(let e of(o=!0,Array.from(l.keys())))u(e)}}}

package/lib/sync/broadcast-sender.d.ts

@@ -0,0 +1,52 @@
+import type { KubunDB } from '@kubun/db';
+import { type DefaultAccessLevel, type EngineEventBus, type EngineEvents } from '@kubun/engine';
+import type { Logger } from '@kubun/logger';
+import type { BroadcastQueue } from './broadcast-queue.js';
+/**
+ * Push-sync runtime config. Gates the local `engine:mutation:authored`
+ * subscriber that drives `mutation:apply` broadcasts. When disabled, no
+ * `mutation:apply` broadcasts leave this peer; merkle-pull continues to
+ * operate; the receive path is unaffected.
+ */
+export type PushSyncConfig = {
+    enabled: boolean;
+};
+/**
+ * Default push-sync config. Disabled by default — push-sync is opt-in even
+ * when a hub is configured. Apps that want immediate broadcast on local
+ * authoring must explicitly set `pushSync: { enabled: true }`.
+ */
+export declare const DEFAULT_PUSH_SYNC_CONFIG: PushSyncConfig;
+export type BroadcastSenderParams = {
+    db: KubunDB;
+    eventBus: EngineEventBus<EngineEvents>;
+    selfDID: string;
+    /**
+     * Per-target-group batch queue. The sender enqueues per-scope entries here
+     * rather than calling `scheduleBroadcast` directly — the queue accumulates
+     * entries and flushes them as a single `mutation:apply` broadcast per
+     * target group when window/count/byte thresholds trip.
+     */
+    queue: BroadcastQueue;
+    logger?: Logger;
+    /**
+     * Server default access level. Used when neither the document nor any user
+     * model default resolves a rule. Defaults to `only_owner` for both
+     * permissions (no fan-out for undeclared models).
+     */
+    defaultAccessLevel?: DefaultAccessLevel;
+};
+/**
+ * Subscribe to `engine:mutation:authored` and, for each locally-authored
+ * mutation, compute the set of MLS group scopes to broadcast to (via the
+ * pure `computeBroadcastScopes`) and fire per-scope
+ * `mutation:apply` broadcasts through the provided `scheduleBroadcast` hook.
+ *
+ * The subscriber swallows errors — a failure here must not propagate into the
+ * engine's event loop and stall other listeners. Errors are logged via the
+ * optional logger.
+ *
+ * Returns an unsubscribe function — the caller is responsible for invoking it
+ * on plugin dispose.
+ */
+export declare function wireBroadcastSender(params: BroadcastSenderParams): () => void;

package/lib/sync/broadcast-sender.js

@@ -0,0 +1 @@
+import{catalogMatchesDoc as e,resolveAccessRule as r}from"@kubun/engine";import{DocumentID as t}from"@kubun/id";import{getGraphStore as o}from"@kubun/store-graph";import{getP2PStore as l}from"@kubun/store-p2p";import{computeBroadcastScopes as a}from"./scope-resolver.js";export const DEFAULT_PUSH_SYNC_CONFIG={enabled:!1};let n={read:"only_owner",write:"only_owner"};export function wireBroadcastSender(e){let r=e.defaultAccessLevel??n;return e.eventBus.on("engine:mutation:authored",async t=>{try{await i(t,{...e,defaultAccessLevel:r})}catch(r){e.logger?.warn("broadcast-sender handler failed",{documentID:t.documentID,error:String(r)})}})}async function i(n,i){let s=await o(i.db),d=await l(i.db),u=await s.getDocument(t.fromString(n.documentID));if(null==u)return;let f=await r(u,u.model,u.owner,"read",{getUserModelAccessDefault:(e,r,t)=>s.getUserModelAccessDefault(e,r,t),isMemberOfAnyCircle:(e,r)=>d.isMemberOfAnyCircle(e,r),isMemberOfAnyGroup:(e,r)=>d.isMemberOfAnyGroup(e,r),getModelInterfaces:e=>s.getModelInterfaces(e)},i.defaultAccessLevel);if("only_owner"===f.level)return;let c=await d.getCirclesForMember(i.selfDID),m=new Set;for(let e of c)for(let r of e.catalog_ids??[])m.add(r);let w=m.size>0?await s.getCatalogs(Array.from(m)):new Map,g=[];for(let e of c)for(let r of e.catalog_ids??[]){let t=w.get(r);null!=t&&g.push({groupID:e.group_id,criteria:t.filter_criteria})}let D=await Promise.all(g.map(async r=>({groupID:r.groupID,matched:await e(r.criteria,u,d)}))),p=new Set;for(let e of D)e.matched&&p.add(e.groupID);let I=Array.from(p);if(0===I.length)return;let b=new Set(f.allowedGroups??[]),v=new Set;if(null!=f.allowedCircles&&f.allowedCircles.length>0)for(let e of(await d.getCircles(f.allowedCircles)).values())null!=e.group_id&&v.add(e.group_id);let y=new Set;if(null!=f.allowedDIDs&&f.allowedDIDs.length>0)for(let e of(await d.getGroupsForMembers(f.allowedDIDs)).values())for(let r of e)y.add(r.id);let _=a({resolvedRule:{level:f.level,allowedGroupIDs:b,allowedCircleParentGroupIDs:v,allowedDIDGroupIDs:y},senderGroupIDs:I});if(0!==_.length)for(let e of _){if(!await d.recordBroadcast({docID:n.documentID,version:n.version,mlsGroupID:e}))continue;let r={mutationJWT:n.mutationJWT,docID:n.documentID,version:n.version,modelID:n.modelID};i.queue.enqueue(e,r,i.selfDID)}}

package/lib/sync/forwarder.d.ts

@@ -0,0 +1,97 @@
+import { type DefaultAccessLevel } from '@kubun/engine';
+import type { Logger } from '@kubun/logger';
+import type { DocumentNode } from '@kubun/protocol';
+import type { GraphStoreAPI } from '@kubun/store-graph';
+import type { P2PStoreAPI } from '@kubun/store-p2p';
+import type { GroupBroadcastMessage, MutationApplyEntry } from '../groups/broadcast.js';
+export declare function rethrowIfProgrammerError(error: unknown): void;
+/**
+ * Context passed to a {@link ForwardFilter} for each candidate forwarding scope.
+ *
+ * The filter is invoked once per surviving (catalog ∧ access ∧ not-loopback)
+ * candidate group. The filter's role is to NARROW — gates are applied first,
+ * the filter only ever further reduces the forwarded set. Returning `false`
+ * skips the candidate; returning `true` (or no filter at all) forwards it.
+ */
+export type ForwardContext = {
+    docID: string;
+    modelID: string;
+    ownerDID: string;
+    /** MLS group the broadcast was received from. Excluded from forwarding. */
+    sourceGroupID: string;
+    /** Candidate MLS group ID to forward to. */
+    candidateGroupID: string;
+    /** Post-apply document state. */
+    postState: DocumentNode;
+};
+/**
+ * Per-candidate filter callback. May be sync or async.
+ *
+ * Awaited per candidate — slow filters serialize forwarding within a single
+ * broadcast batch. Filters MUST NOT throw; throwing is treated as `false`
+ * (skip) and logged.
+ */
+export type ForwardFilter = (ctx: ForwardContext) => boolean | Promise<boolean>;
+/**
+ * Forwarding configuration.
+ * - `false` (default) — forwarding disabled. Hot-path has no extra DB
+ *   lookups and no extra awaits in the receive path.
+ * - `true` — forward to every candidate group that passes catalog + access
+ *   gates and is not the source group.
+ * - {@link ForwardFilter} — same as `true`, plus per-candidate narrowing.
+ */
+export type ForwardingConfig = boolean | ForwardFilter;
+export type EvaluateAndForwardParams = {
+    /** Original broadcast entry being considered for forwarding. */
+    entry: MutationApplyEntry;
+    /** Post-apply document state — required for catalog match + filter context. */
+    postState: DocumentNode;
+    /** MLS group the broadcast was received from — never a forwarding target. */
+    sourceGroupID: string;
+    /** Bridging peer's own DID — used as `senderPeerDID` on forwarded broadcasts. */
+    selfDID: string;
+    p2pStore: P2PStoreAPI;
+    graphStore: GraphStoreAPI;
+    defaultAccessLevel: DefaultAccessLevel;
+    /** See {@link ForwardingConfig}. `false` short-circuits before any work. */
+    forwarding: ForwardingConfig;
+    /**
+     * Hub forwarding hook. Same shape as `HubWiring.scheduleBroadcast`. Called
+     * once per surviving candidate with a single-entry `mutation:apply`
+     * broadcast. Bypasses the batch queue intentionally — see
+     * {@link evaluateAndForward} for rationale.
+     */
+    scheduleBroadcast: (groupID: string, message: GroupBroadcastMessage) => void | Promise<void>;
+    logger?: Logger;
+};
+export type EvaluateAndForwardResult = {
+    /** Number of candidate groups the entry was forwarded to. */
+    forwarded: number;
+    /** Number of candidate groups skipped (filter returned false, catalog miss, dedup). */
+    skipped: number;
+};
+/**
+ * Evaluate forwarding candidates for a single mutation:apply entry the local
+ * peer has just applied, and forward to each surviving candidate group via
+ * `scheduleBroadcast`.
+ *
+ * Pipeline (per candidate group):
+ * 1. Source group exclusion — `sourceGroupID` is filtered out before any check.
+ * 2. Access gate — `computeBroadcastScopes` against the post-apply rule.
+ * 3. Catalog gate — at least one circle the local peer belongs to in the
+ *    candidate group must have a catalog whose `filter_criteria` matches the
+ *    document.
+ * 4. Filter (when `forwarding` is a function) — narrows further.
+ * 5. Dedup — `recordBroadcast` BEFORE schedule. False return → skip silently.
+ * 6. Schedule — single-entry `mutation:apply` broadcast with
+ *    `senderPeerDID = selfDID`.
+ *
+ * Per-candidate errors are isolated: one bad candidate logs + continues; the
+ * rest still get evaluated. The function never throws.
+ *
+ * Routing decision: each candidate gets its OWN single-entry broadcast (no
+ * batch queue). The queue's `senderPeerDID`-mismatch flush conflicts
+ * with mixing locally-authored and forwarded entries in one batch — deferring
+ * batched-forwarding keeps the receive path simple.
+ */
+export declare function evaluateAndForward(params: EvaluateAndForwardParams): Promise<EvaluateAndForwardResult>;

package/lib/sync/forwarder.js

@@ -0,0 +1 @@
+import{catalogMatchesDoc as r,resolveAccessRule as e}from"@kubun/engine";import{computeBroadcastScopes as o}from"./scope-resolver.js";export function rethrowIfProgrammerError(r){if(r instanceof SyntaxError||r instanceof TypeError||r instanceof ReferenceError||r instanceof RangeError)throw r}export async function evaluateAndForward(t){let a,l;if(!1===t.forwarding)return{forwarded:0,skipped:0};let i=!0===t.forwarding?()=>!0:t.forwarding,n=(await t.p2pStore.getGroupsForMember(t.selfDID)).map(r=>r.id).filter(r=>r!==t.sourceGroupID);if(0===n.length)return{forwarded:0,skipped:0};try{a=await e(t.postState,t.postState.model,t.postState.owner,"read",{getUserModelAccessDefault:(r,e,o)=>t.graphStore.getUserModelAccessDefault(r,e,o),isMemberOfAnyCircle:(r,e)=>t.p2pStore.isMemberOfAnyCircle(r,e),isMemberOfAnyGroup:(r,e)=>t.p2pStore.isMemberOfAnyGroup(r,e),getModelInterfaces:r=>t.graphStore.getModelInterfaces(r)},t.defaultAccessLevel)}catch(r){return rethrowIfProgrammerError(r),t.logger?.warn("forwarder: resolveAccessRule failed, skipping forward",{docID:t.entry.docID,version:t.entry.version,sourceGroupID:t.sourceGroupID,error:String(r)}),{forwarded:0,skipped:0}}let s=new Set(a.allowedGroups??[]),f=new Set;if(null!=a.allowedCircles&&a.allowedCircles.length>0)try{for(let r of(await t.p2pStore.getCircles(a.allowedCircles)).values())null!=r.group_id&&f.add(r.group_id)}catch(r){rethrowIfProgrammerError(r),t.logger?.warn("forwarder: getCircles failed, skipping allowedCircles",{count:a.allowedCircles.length,error:String(r)})}let d=new Set;if(null!=a.allowedDIDs&&a.allowedDIDs.length>0)try{for(let r of(await t.p2pStore.getGroupsForMembers(a.allowedDIDs)).values())for(let e of r)d.add(e.id)}catch(r){rethrowIfProgrammerError(r),t.logger?.warn("forwarder: getGroupsForMembers failed, skipping allowedDIDs",{count:a.allowedDIDs.length,error:String(r)})}let p=o({resolvedRule:{level:a.level,allowedGroupIDs:s,allowedCircleParentGroupIDs:f,allowedDIDGroupIDs:d},senderGroupIDs:n});if(0===p.length)return{forwarded:0,skipped:0};try{l=await t.p2pStore.getCirclesForMember(t.selfDID)}catch(r){return rethrowIfProgrammerError(r),t.logger?.warn("forwarder: getCirclesForMember failed",{selfDID:t.selfDID,error:String(r)}),{forwarded:0,skipped:0}}let c=new Set(p),g=new Map;for(let r of l){if(!c.has(r.group_id))continue;let e=g.get(r.group_id);null!=e?e.push(r):g.set(r.group_id,[r])}let u=new Set;for(let r of g.values())for(let e of r)for(let r of e.catalog_ids??[])u.add(r);let w=new Map;if(u.size>0)try{w=await t.graphStore.getCatalogs(Array.from(u))}catch(r){rethrowIfProgrammerError(r),t.logger?.warn("forwarder: getCatalogs failed, treating all as missing",{count:u.size,error:String(r)})}let D=0,I=0;for(let e of p)try{let o=g.get(e)??[],a=!1;for(let e of o){for(let o of e.catalog_ids??[]){let e=w.get(o);if(null!=e&&await r(e.filter_criteria,t.postState,t.p2pStore)){a=!0;break}}if(a)break}if(!a){I++;continue}let l={docID:t.entry.docID,modelID:t.entry.modelID,ownerDID:t.postState.owner,sourceGroupID:t.sourceGroupID,candidateGroupID:e,postState:t.postState};if(!await i(l)){I++;continue}if(!await t.p2pStore.recordBroadcast({docID:t.entry.docID,version:t.entry.version,mlsGroupID:e}))continue;let n={type:"mutation:apply",entries:[t.entry],senderPeerDID:t.selfDID};await t.scheduleBroadcast(e,n),D++}catch(r){t.logger?.warn("forwarder: candidate evaluation failed",{docID:t.entry.docID,version:t.entry.version,candidateGroupID:e,sourceGroupID:t.sourceGroupID,error:String(r)})}return{forwarded:D,skipped:I}}

package/lib/sync/handlers.d.ts

@@ -1,6 +1,9 @@
+import { type VerifyTokenHook } from '@enkaku/capability';
 import type { KubunDB } from '@kubun/db';
+import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { Logger } from '@kubun/logger';
 import type { SyncDirection } from '../protocol.js';
+import type { StoreUnreadableMode } from '../types.js';
 import type { PeerRegistry } from './peer-registry.js';
 /**
  * Check if delegation tokens grant the viewer read access to a user's documents.
@@ -8,13 +11,29 @@ import type { PeerRegistry } from './peer-registry.js';
  * @param viewerDID - The DID of the requesting viewer
  * @param ownerDID - The DID of the document owner
  * @param delegationTokens - Array of delegation JWT tokens
+ * @param revocationChecker - Optional per-leaf-capability verification hook.
+ *   When set, capabilities whose `jti` has been revoked cause the check to
+ *   fail closed.
  * @returns true if any token grants read access
  */
-export declare function checkSyncDelegation(viewerDID: string, ownerDID: string, delegationTokens: Array<string>): Promise<boolean>;
+export declare function checkSyncDelegation(viewerDID: string, ownerDID: string, delegationTokens: Array<string>, revocationChecker?: VerifyTokenHook): Promise<boolean>;
 export type CreateSyncHandlersParams = {
     db: KubunDB;
+    graph: GraphInternals;
     logger: Logger;
     peerRegistry: PeerRegistry;
+    /**
+     * Local peer's DID — required when `storeUnreadable === 'drop'` so the
+     * receive-time access gate can use it as viewer.
+     */
+    selfDID?: string;
+    /**
+     * Receive-side storage mode forwarded to `applySyncMutations`.
+     * Defaults to `'persist'` when omitted.
+     */
+    storeUnreadable?: StoreUnreadableMode;
+    /** Server default access level — required when `storeUnreadable === 'drop'`. */
+    defaultAccessLevel?: DefaultAccessLevel;
 };
 /**
  * Resolve the effective sync direction given what the initiator requested

package/lib/sync/handlers.js

@@ -1 +1 @@
-import{checkCapability as e}from"@enkaku/capability";import{getGraphStore as t}from"@kubun/store-graph";import{resolveCatalogSyncScopes as n}from"./catalog-scope.js";import{createMerkleSyncChannelHandler as o}from"./merkle-channel.js";export async function checkSyncDelegation(t,n,o){if(!o||0===o.length)return!1;let r=["*","urn:kubun:user:*",`urn:kubun:user:${n}`],l="document/read";for(let a of r)try{return await e({act:l,res:a},{iss:t,sub:n,cap:o}),!0}catch{}for(let a of o)for(let o of r)try{return await e({act:l,res:o},{iss:t,sub:n,cap:a}),!0}catch{}return!1}export function negotiateDirection(e,t){return"both"===t?e:"both"===e?t:e===t?e:t}export function createSyncHandlers(e){let{db:r,logger:l,peerRegistry:a}=e;return{"sync/negotiate":async e=>{let o,{scopes:s,delegationTokens:i,catalogIDs:c,knownModelIDs:u,direction:g}=e.param,f=e.message.payload,d=f.sub||f.iss;l.debug("sync/negotiate requested",{scopes:s,catalogIDs:c,viewerDID:d});let p=[],D=await t(r);if(null!=c&&c.length>0){let e=await n(r,c,u);if(e.modelIDs.length>0)if(null!=e.owners)for(let t of e.modelIDs)for(let n of e.owners){let e=d===n,o=!e&&await checkSyncDelegation(d,n,i);(e||o)&&p.push({modelID:t,ownerDID:n})}else for(let t of e.modelIDs)for(let e of(await D.getDistinctOwnersForModel(t))){let n=d===e,o=!n&&await checkSyncDelegation(d,e,i);(n||o)&&p.push({modelID:t,ownerDID:e})}e.missingClusterIDs.length>0&&(o=await D.getClusters(e.missingClusterIDs))}if(null!=s)for(let e of s){let t=d===e.ownerDID,n=!t&&await checkSyncDelegation(d,e.ownerDID,i);t||n?p.push(e):l.debug("sync/negotiate: scope rejected",{scope:e,viewerDID:d})}let h=new Set,m=p.filter(e=>{let t=`${e.modelID}:${e.ownerDID}`;return!h.has(t)&&(h.add(t),!0)});l.info("sync/negotiate completed",{requested:(s?.length??0)+(c?.length??0),accepted:m.length,missingClusters:null!=o?Object.keys(o).length:0});let w=g??"pull",y=await a.getPeer({peerDID:d,stores:r}),b=y?.allowedDirection??"both",k=negotiateDirection(w,b);return k!==w&&l.info("sync/negotiate: direction downgraded",{requested:w,allowed:b,agreed:k}),{direction:k,acceptedScopes:m,excludedDocumentIDs:[],...null!=o&&{missingClusters:o}}},"sync/merkle-sync":o({db:r,logger:l})}}
+import{checkCapability as e,createRevocationChecker as t}from"@enkaku/capability";import{getGraphStore as n}from"@kubun/store-graph";import{createP2PRevocationBackend as r,getP2PStore as o}from"@kubun/store-p2p";import{resolveCatalogSyncScopes as l}from"./catalog-scope.js";import{createMerkleSyncChannelHandler as a}from"./merkle-channel.js";export async function checkSyncDelegation(t,n,r,o){if(!r||0===r.length)return!1;let l=["*","urn:kubun:user:*",`urn:kubun:user:${n}`],a="document/read";for(let s of l)try{return await e({act:a,res:s},{iss:t,sub:n,cap:r},{verifyToken:o}),!0}catch{}for(let s of r)for(let r of l)try{return await e({act:a,res:r},{iss:t,sub:n,cap:s},{verifyToken:o}),!0}catch{}return!1}export function negotiateDirection(e,t){return"both"===t?e:"both"===e?t:e===t?e:t}export function createSyncHandlers(e){let{db:s,graph:i,logger:c,peerRegistry:u}=e,f=e.storeUnreadable??"persist",d=null;async function g(){return null==d&&(d=t(r(await o(s)))),d}return{"sync/negotiate":async e=>{let t,{scopes:r,delegationTokens:o,catalogIDs:a,knownModelIDs:i,direction:f}=e.param,d=e.message.payload,p=d.sub||d.iss;c.debug("sync/negotiate requested",{scopes:r,catalogIDs:a,viewerDID:p});let D=[],m=await n(s);if(null!=a&&a.length>0){let e=await l(s,a,i);if(e.modelIDs.length>0)if(null!=e.owners)for(let t of e.modelIDs)for(let n of e.owners){let e=p===n,r=!e&&await checkSyncDelegation(p,n,o,await g());(e||r)&&D.push({modelID:t,ownerDID:n})}else for(let t of e.modelIDs)for(let e of(await m.getDistinctOwnersForModel(t))){let n=p===e,r=!n&&await checkSyncDelegation(p,e,o,await g());(n||r)&&D.push({modelID:t,ownerDID:e})}e.missingClusterIDs.length>0&&(t=await m.getClusters(e.missingClusterIDs))}if(null!=r)for(let e of r){let t=p===e.ownerDID,n=!t&&await checkSyncDelegation(p,e.ownerDID,o,await g());t||n?D.push(e):c.debug("sync/negotiate: scope rejected",{scope:e,viewerDID:p})}let w=new Set,h=D.filter(e=>{let t=`${e.modelID}:${e.ownerDID}`;return!w.has(t)&&(w.add(t),!0)});c.info("sync/negotiate completed",{requested:(r?.length??0)+(a?.length??0),accepted:h.length,missingClusters:null!=t?Object.keys(t).length:0});let y=f??"pull",b=await u.getPeer({peerDID:p,stores:s}),k=b?.allowedDirection??"both",I=negotiateDirection(y,k);return I!==y&&c.info("sync/negotiate: direction downgraded",{requested:y,allowed:k,agreed:I}),{direction:I,acceptedScopes:h,excludedDocumentIDs:[],...null!=t&&{missingClusters:t}}},"sync/merkle-sync":a({db:s,graph:i,logger:c,selfDID:e.selfDID,storeUnreadable:f,defaultAccessLevel:e.defaultAccessLevel})}}

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

@@ -0,0 +1,24 @@
+import { type ObservabilityEventListener } from '@enkaku/hub-tunnel';
+import { type ProcedureHandlers } from '@enkaku/server';
+import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+import type { HubConnection } from '../hub/hub-connection.js';
+import type { SyncProtocol } from '../protocol.js';
+export type HubTunnelSyncListenerParams = {
+    hubConnection: HubConnection;
+    registry: GroupHandleRegistry;
+    groupID: string;
+    localDID: string;
+    peerDID: string;
+    syncHandlers: ProcedureHandlers<SyncProtocol>;
+    getRandomID?: () => string;
+    idleTimeoutMs?: number;
+    reconnectTimeoutMs?: number;
+    inboxCapacity?: number;
+    onEvent?: ObservabilityEventListener;
+};
+export declare class HubTunnelSyncListener {
+    #private;
+    constructor(params: HubTunnelSyncListenerParams);
+    start(): void;
+    stop(): Promise<void>;
+}

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

@@ -0,0 +1 @@
+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)})}}}}

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

@@ -0,0 +1,36 @@
+import { type ObservabilityEventListener } from '@enkaku/hub-tunnel';
+import type { ClientTransportOf } from '@enkaku/protocol';
+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;
+    registry: GroupHandleRegistry;
+    groupID: string;
+    localDID: string;
+    peerDID: string;
+    idleTimeoutMs?: number;
+    reconnectTimeoutMs?: number;
+    inboxCapacity?: number;
+    onEvent?: ObservabilityEventListener;
+};
+export declare class HubTunnelSyncProvider implements SyncTransportProvider {
+    #private;
+    constructor(params: HubTunnelSyncProviderParams);
+    /**
+     * 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.
+     */
+    createSyncTransport(signal?: AbortSignal): ClientTransportOf<SyncProtocol>;
+}

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

@@ -0,0 +1 @@
+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)})}}}}

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

@@ -1,12 +1,53 @@
 import type { KubunDB } from '@kubun/db';
+import { type DefaultAccessLevel, type GraphInternals } from '@kubun/engine';
+import type { StoreUnreadableMode } from '../types.js';
 export type ApplySyncMutationsParams = {
     db: KubunDB;
+    graph: GraphInternals;
     mutationJWTs: Array<string>;
+    /**
+     * Local peer's DID — required when `storeUnreadable === 'drop'` to feed the
+     * receive-time access gate. Optional otherwise.
+     */
+    selfDID?: string;
+    /**
+     * Receiver storage mode for incoming sync mutations.
+     * - `'persist'` (default) — every mutation the engine accepts persists.
+     * - `'drop'` — apply a receive-time read-access check using `selfDID` as
+     *   viewer; mutations the local peer cannot read are not persisted.
+     */
+    storeUnreadable?: StoreUnreadableMode;
+    /** Server default access level — required when `storeUnreadable === 'drop'`. */
+    defaultAccessLevel?: DefaultAccessLevel;
 };
 export type ApplySyncMutationsResult = {
     applied: number;
     rejected: number;
     pending: number;
     skipped: number;
+    /** Count of mutations denied by the receive-time access gate. */
+    dropped: number;
 };
+/**
+ * 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 declare function applySyncMutations(params: ApplySyncMutationsParams): Promise<ApplySyncMutationsResult>;

package/lib/sync/merkle-apply.js

@@ -1 +1 @@
-import{asType as t,createValidator as a}from"@enkaku/schema";import{verifyToken as i}from"@enkaku/token";import{computeMutationHash as o}from"@kubun/engine";import{DocumentID as n}from"@kubun/id";import{applyMutation as u}from"@kubun/mutation";import{documentMutation as e}from"@kubun/protocol";import{getGraphStore as r}from"@kubun/store-graph";let m=a(e);export async function applySyncMutations(a){let{db:e,mutationJWTs:s}=a,d=await r(e),l=0,c=0,h=0,p=0,_={store:d,validators:{}};for(let a of s){let e,r=o(a);if(await d.hasMutationHash(r)){p++;continue}try{let o=await i(a);e=t(m,o.payload)}catch{c++;continue}let s=e.sub,f=n.fromString(s).model.toString(),w=n.fromString(s);if(null==await d.getDocument(w)&&"change"===e.typ){await d.insertMutationLogEntry({mutation_hash:r,model_id:f,document_id:s,author_did:e.iss,hlc:e.hlc,mutation_jwt:a,status:"pending"}),h++;continue}try{if(await u(_,e),await d.insertMutationLogEntry({mutation_hash:r,model_id:f,document_id:s,author_did:e.iss,hlc:e.hlc,mutation_jwt:a,status:"applied"}),l++,"set"===e.typ)for(let a of(await d.getPendingMutations(s)))try{let o=await i(a.mutation_jwt),n=t(m,o.payload);await u(_,n),await d.updateMutationStatus(a.mutation_hash,"applied"),l++}catch{await d.updateMutationStatus(a.mutation_hash,"rejected"),c++}}catch{await d.insertMutationLogEntry({mutation_hash:r,model_id:f,document_id:s,author_did:e.iss,hlc:e.hlc,mutation_jwt:a,status:"rejected"}),c++}}return{applied:l,rejected:c,pending:h,skipped:p}}
+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}}

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

@@ -1,6 +1,8 @@
 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';
 /**
  * Minimal handler context shape for sync/merkle-sync channel.
  * Matches the Enkaku ChannelHandlerContext at runtime.
@@ -12,7 +14,20 @@ type MerkleSyncChannelContext = {
 };
 export type CreateMerkleSyncChannelHandlerParams = {
     db: KubunDB;
+    graph: GraphInternals;
     logger: Logger;
+    /**
+     * Local peer's DID — required when `storeUnreadable === 'drop'` so the
+     * receive-time access gate can use it as viewer.
+     */
+    selfDID?: string;
+    /**
+     * Receive-side storage mode forwarded to `applySyncMutations`.
+     * Defaults to `'persist'` when omitted.
+     */
+    storeUnreadable?: StoreUnreadableMode;
+    /** Server default access level — required when `storeUnreadable === 'drop'`. */
+    defaultAccessLevel?: DefaultAccessLevel;
 };
 export declare function createMerkleSyncChannelHandler(params: CreateMerkleSyncChannelHandlerParams): (ctx: MerkleSyncChannelContext) => Promise<SyncMerkleSyncResult>;
 export {};

package/lib/sync/merkle-channel.js

@@ -1 +1 @@
-import{getGraphStore as e}from"@kubun/store-graph";import{applySyncMutations as t}from"./merkle-apply.js";import{buildMerkleTree as r,findDivergentBuckets as a,getTimeBuckets as n,SYNC_BATCH_SIZE as l}from"./merkle-tree.js";export function createMerkleSyncChannelHandler(i){let{db:o,logger:s}=i;return async i=>{let{scopes:c,excludedDocumentIDs:m,tree:u,direction:p}=i.param,y=i.writable.getWriter();s.info("sync/merkle-sync channel started",{scopes:c,excludedDocumentIDs:m,direction:p});let w=0,f=0,k=0;try{let h=await e(o),d=await h.getDocumentIDsForScope(c,m),g=await h.getMutationLogForDocuments(d),b=r(g);await y.write({type:"tree",tree:b.buckets});let v={root:u.root??"",buckets:u},W=a(b,v);w=W.length;let J=async()=>{if("pull"===p||"both"===p){let e=new Set(W),t=g.filter(t=>{let{minute:r}=n(t.hlc);return e.has(r)});for(let e=0;e<t.length;e+=l){let r=t.slice(e,e+l);await y.write({type:"mutations",mutationJWTs:r.map(e=>e.mutation_jwt)}),f+=r.length}await y.write({type:"complete"})}else await y.write({type:"complete"})},S=async()=>{let e=[],t=i.readable.getReader();try{for(;;){let{done:r,value:a}=await t.read();if(r)break;if("mutations"===a.type&&null!=a.mutationJWTs)e.push(...a.mutationJWTs);else if("complete"===a.type)break}}finally{t.releaseLock()}return e},[,T]=await Promise.all([J(),S()]);if(T.length>0){let e=await t({db:o,mutationJWTs:T});k=e.applied+e.pending,s.info("sync/merkle-sync: applied received mutations",{result:e})}}catch(e){return s.error("sync/merkle-sync channel error",{error:e}),{success:!1,divergentBuckets:0,mutationsSent:0,mutationsReceived:0}}finally{try{await y.close()}catch{}}return s.info("sync/merkle-sync channel completed",{divergentBuckets:w,mutationsSent:f,mutationsReceived:k}),{success:!0,divergentBuckets:w,mutationsSent:f,mutationsReceived:k}}}
+import{getGraphStore as e}from"@kubun/store-graph";import{applySyncMutations as t}from"./merkle-apply.js";import{buildMerkleTree as r,findDivergentBuckets as a,getTimeBuckets as l,SYNC_BATCH_SIZE as n}from"./merkle-tree.js";export function createMerkleSyncChannelHandler(i){let{db:s,graph:c,logger:o}=i,u=i.storeUnreadable??"persist";return async m=>{let{scopes:p,excludedDocumentIDs:y,tree:f,direction:w}=m.param,d=m.writable.getWriter();o.info("sync/merkle-sync channel started",{scopes:p,excludedDocumentIDs:y,direction:w});let k=0,h=0,g=0;try{let b=await e(s),v=await b.getDocumentIDsForScope(p,y),D=await b.getMutationLogForDocuments(v),W=r(D);await d.write({type:"tree",tree:W.buckets});let J={root:f.root??"",buckets:f},L=a(W,J);k=L.length;let S=async()=>{if("pull"===w||"both"===w){let e=new Set(L),t=D.filter(t=>{let{minute:r}=l(t.hlc);return e.has(r)});for(let e=0;e<t.length;e+=n){let r=t.slice(e,e+n);await d.write({type:"mutations",mutationJWTs:r.map(e=>e.mutation_jwt)}),h+=r.length}await d.write({type:"complete"})}else await d.write({type:"complete"})},T=async()=>{let e=[],t=m.readable.getReader();try{for(;;){let{done:r,value:a}=await t.read();if(r)break;if("mutations"===a.type&&null!=a.mutationJWTs)e.push(...a.mutationJWTs);else if("complete"===a.type)break}}finally{t.releaseLock()}return e},[,j]=await Promise.all([S(),T()]);if(j.length>0){let e=await t({db:s,graph:c,mutationJWTs:j,selfDID:i.selfDID,storeUnreadable:u,defaultAccessLevel:i.defaultAccessLevel});g=e.applied+e.pending,o.info("sync/merkle-sync: applied received mutations",{result:e})}}catch(e){return o.error("sync/merkle-sync channel error",{error:e}),{success:!1,divergentBuckets:0,mutationsSent:0,mutationsReceived:0}}finally{try{await d.close()}catch{}}return o.info("sync/merkle-sync channel completed",{divergentBuckets:k,mutationsSent:h,mutationsReceived:g}),{success:!0,divergentBuckets:k,mutationsSent:h,mutationsReceived:g}}}

package/lib/sync/receive-access-gate.d.ts

@@ -0,0 +1,36 @@
+import { type AccessControlDB, type AccessGate, type DefaultAccessLevel } from '@kubun/engine';
+/**
+ * Inputs for {@link createReceiveAccessGate}. The gate composes
+ * `resolveAccessRule` + `checkAccess` (via `createAccessChecker`) at receive
+ * time using the local peer's DID as viewer. Builds an `AccessControlDB`
+ * adapter from the underlying p2p + graph stores.
+ */
+export type ReceiveAccessGateParams = {
+    /** Local peer's DID — used as the viewer in the access check. */
+    selfDID: string;
+    /**
+     * Access-control DB facade — typically built inline from
+     * `graphStore.getUserModelAccessDefault` + `p2pStore.isMemberOfAnyCircle` +
+     * `p2pStore.isMemberOfAnyGroup`.
+     */
+    db: AccessControlDB;
+    /** Server default access level used when no rule is declared. */
+    defaultAccessLevel: DefaultAccessLevel;
+};
+/**
+ * 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 declare function createReceiveAccessGate(params: ReceiveAccessGateParams): AccessGate;

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

@@ -0,0 +1 @@
+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")}

package/lib/sync/scope-resolver.d.ts

@@ -0,0 +1,32 @@
+export type ResolvedAccessRule = {
+    level: 'only_owner' | 'anyone' | 'restricted';
+    /** rule.allowedGroups (MLS group IDs) */
+    allowedGroupIDs: Set<string>;
+    /** MLS group IDs that are parents of any rule.allowedCircles entry */
+    allowedCircleParentGroupIDs: Set<string>;
+    /** MLS group IDs where at least one rule.allowedDIDs entry is a member */
+    allowedDIDGroupIDs: Set<string>;
+};
+export type BroadcastScopeInput = {
+    resolvedRule: ResolvedAccessRule;
+    /** MLS group IDs of sender's own memberships that already passed catalog-match for this doc */
+    senderGroupIDs: Array<string>;
+};
+/**
+ * Compute the set of MLS group IDs to broadcast a document to,
+ * given its resolved access rule and the sender's group memberships.
+ *
+ * Pure, synchronous. The caller is responsible for:
+ * - Pre-resolving the access rule into a `ResolvedAccessRule` (all rule-side
+ *   lookups — circle parent groups and per-DID group memberships —
+ *   collapsed to MLS group ID sets).
+ * - Pre-filtering `senderGroupIDs` by catalog-match against the document.
+ *
+ * Per spec §3 "Sync routing" (sender side): a sender's own MLS group is a
+ * valid broadcast scope iff that group is the encryption perimeter for at
+ * least one allowed principal — either the group itself is in allowedGroups,
+ * or an allowed circle's parent group matches, or an allowed DID is a member
+ * of that group. The receiver applies the per-recipient access check on
+ * decrypt; the sender's own circle membership is irrelevant for routing.
+ */
+export declare function computeBroadcastScopes(input: BroadcastScopeInput): Array<string>;

package/lib/sync/scope-resolver.js

@@ -0,0 +1 @@
+export function computeBroadcastScopes(e){let{resolvedRule:r,senderGroupIDs:o}=e;switch(r.level){case"only_owner":return[];case"anyone":return Array.from(new Set(o));case"restricted":{let e=new Set;for(let t of o)(r.allowedGroupIDs.has(t)||r.allowedCircleParentGroupIDs.has(t)||r.allowedDIDGroupIDs.has(t))&&e.add(t);return Array.from(e)}default:{let e=r.level;throw Error(`Unknown access level: ${String(e)}`)}}}

package/lib/sync/sync-manager.d.ts

@@ -1,8 +1,10 @@
 import type { Runtime } from '@enkaku/runtime';
 import { type Identity, type SigningIdentity } from '@enkaku/token';
 import type { StoreProvider } from '@kubun/db';
+import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { Logger } from '@kubun/logger';
 import type { SyncDirection } from '../protocol.js';
+import type { StoreUnreadableMode } from '../types.js';
 import { type PeerConfig, type PeerConfigWithID, PeerRegistry } from './peer-registry.js';
 import { type SyncScope, type SyncTransportProvider } from './sync-client.js';
 export type SyncSessionInfo = {
@@ -25,10 +27,18 @@ export type SyncEvent = {
 };
 export type SyncManagerParams = {
     deployClusters?: (clusters: Record<string, unknown>) => Promise<void>;
+    graph: GraphInternals;
     runtime: Runtime;
     identity: Identity;
     logger: Logger;
     serverResolver?: (serverID: string) => SyncTransportProvider | undefined;
+    /**
+     * Receive-side storage mode forwarded to `applySyncMutations`.
+     * Defaults to `'persist'` when omitted.
+     */
+    storeUnreadable?: StoreUnreadableMode;
+    /** Server default access level — required when `storeUnreadable === 'drop'`. */
+    defaultAccessLevel?: DefaultAccessLevel;
 };
 export type MerkleSyncParams = {
     peerDID: string;

package/lib/sync/sync-manager.js

@@ -1 +1 @@
-import{EventEmitter as e}from"@enkaku/event";import{isSigningIdentity as t}from"@enkaku/token";import{getGraphStore as r}from"@kubun/store-graph";import{applySyncMutations as s}from"./merkle-apply.js";import{buildMerkleTree as i}from"./merkle-tree.js";import{PeerRegistry as n}from"./peer-registry.js";import{SyncClient as o}from"./sync-client.js";export class SyncManager{#e;#t;#r;#s;#i=new e;#n=new Map;#o=new Map;#l;#a;constructor(e){this.#e=e.deployClusters,this.#t=e.runtime,this.#l=e.identity,this.#r=e.logger,this.#s=new n({runtime:e.runtime}),this.#a=e.serverResolver}get peerRegistry(){return this.#s}setIdentity(e){this.#l=e}setServerResolver(e){this.#a=e}async addPeer(e){await this.#s.addPeer(e),this.#r.info("Peer added",{peerDID:e.config.peerDID})}async removePeer(e){await this.#s.removePeer(e),this.#r.info("Peer removed",{peerDID:e.peerDID})}async updatePeerConfig(e){await this.#s.updatePeer(e),this.#r.info("Peer updated",{peerDID:e.peerDID})}async listPeers(e){return this.#s.listPeers(e)}async getPeer(e){return this.#s.getPeer(e)}async merkleSyncWithPeer(e){let n,{peerDID:l,scopes:a,delegationTokens:c=[],knownModelIDs:g,direction:m}=e;this.#r.info("Starting Merkle sync with peer",{peerDID:l,scopes:a});let p=await this.#s.getPeer({peerDID:l,stores:e.stores});if(!p)throw Error(`Peer ${l} not found`);let y=`merkle-sync-${l}-${Date.now()}`,u={peerID:l,startTime:Date.now(),documentsAttempted:0,documentsCompleted:0};this.#n.set(y,u),this.#c({type:"started",peerID:l,timestamp:Date.now()});try{let d=this.#l;if(!t(d))throw Error("Signing identity required for Merkle sync");let h=new o({runtime:this.#t,identity:d,logger:this.#r,serverResolver:this.#a});n=await h.connect(p.endpoint,l);let v=m??"pull";this.#r.info("Negotiating sync scopes",{scopes:a,direction:v});let{acceptedScopes:f,excludedDocumentIDs:D,missingClusters:w,direction:k}=await h.negotiate(n,a,c,g,v);if(0===f.length)return this.#r.info("No scopes accepted by peer"),this.#o.set(l,Date.now()),this.#c({type:"completed",peerID:l,timestamp:Date.now()}),this.#n.delete(y),{sessionID:y,divergentBuckets:0,messagesReceived:0,messagesSent:0,missingClusters:w};null!=w&&Object.keys(w).length>0&&(null!=this.#e?(this.#r.info("Deploying missing clusters from peer",{clusterCount:Object.keys(w).length}),await this.#e(w)):this.#r.warn("Missing clusters received but no deployClusters callback configured",{clusterCount:Object.keys(w).length})),this.#r.info("Building local Merkle tree",{acceptedScopes:f});let S=await r(e.stores),P=await S.getDocumentIDsForScope(f,D),R=await S.getMutationLogForDocuments(P),I=i(R),C=k??v;this.#r.info("Requesting Merkle sync from peer",{localTreeBuckets:Object.keys(I.buckets).length,direction:C});let B=await h.merkleSync(n,{scopes:f,excludedDocumentIDs:D,localTree:I,direction:C,localEntries:R});return B.mutationJWTs.length>0&&(this.#r.info("Applying sync mutations",{mutations:B.mutationJWTs.length}),u.documentsCompleted=(await s({db:e.stores,mutationJWTs:B.mutationJWTs})).applied),this.#o.set(l,Date.now()),this.#c({type:"completed",peerID:l,timestamp:Date.now()}),this.#r.info("Merkle sync completed",{divergentBuckets:B.divergentBuckets,mutationsReceived:B.mutationJWTs.length}),{sessionID:y,divergentBuckets:B.divergentBuckets,messagesReceived:B.mutationJWTs.length,messagesSent:B.mutationsSent,missingClusters:w}}catch(e){throw this.#r.error("Merkle sync failed",{peerDID:l,error:e}),this.#c({type:"error",peerID:l,timestamp:Date.now(),error:e instanceof Error?e.message:String(e)}),e}finally{if(null!=n)try{n.abort("SyncComplete"),await n.dispose()}catch{}this.#n.delete(y)}}getStatus(e){let{peerDID:t}=e,r=Array.from(this.#n.values()).filter(e=>!t||e.peerID===t).map(e=>({peerID:e.peerID,startTime:e.startTime,documentsAttempted:e.documentsAttempted,documentsCompleted:e.documentsCompleted})),s={};for(let[e,r]of this.#o.entries())t&&e!==t||(s[e]=r);return{activeSessions:r,lastSyncByPeer:s}}onSyncEvent(e){return this.#i.on("sync",e)}#c(e){this.#i.emit("sync",e).catch(e=>{this.#r.error("Error in sync event listener",{error:e})})}async dispose(){this.#n.clear(),this.#o.clear()}}
+import{EventEmitter as e}from"@enkaku/event";import{isSigningIdentity as t}from"@enkaku/token";import{getGraphStore as s}from"@kubun/store-graph";import{applySyncMutations as r}from"./merkle-apply.js";import{buildMerkleTree as i}from"./merkle-tree.js";import{PeerRegistry as n}from"./peer-registry.js";import{SyncClient as o}from"./sync-client.js";export class SyncManager{#e;#t;#s;#r;#i;#n=new e;#o=new Map;#a=new Map;#l;#c;#g;#p;constructor(e){this.#e=e.deployClusters,this.#t=e.graph,this.#s=e.runtime,this.#l=e.identity,this.#r=e.logger,this.#i=new n({runtime:e.runtime}),this.#c=e.serverResolver,this.#g=e.storeUnreadable??"persist",this.#p=e.defaultAccessLevel}get peerRegistry(){return this.#i}setIdentity(e){this.#l=e}setServerResolver(e){this.#c=e}async addPeer(e){await this.#i.addPeer(e),this.#r.info("Peer added",{peerDID:e.config.peerDID})}async removePeer(e){await this.#i.removePeer(e),this.#r.info("Peer removed",{peerDID:e.peerDID})}async updatePeerConfig(e){await this.#i.updatePeer(e),this.#r.info("Peer updated",{peerDID:e.peerDID})}async listPeers(e){return this.#i.listPeers(e)}async getPeer(e){return this.#i.getPeer(e)}async merkleSyncWithPeer(e){let n,{peerDID:a,scopes:l,delegationTokens:c=[],knownModelIDs:g,direction:p}=e;this.#r.info("Starting Merkle sync with peer",{peerDID:a,scopes:l});let m=await this.#i.getPeer({peerDID:a,stores:e.stores});if(!m)throw Error(`Peer ${a} not found`);let d=`merkle-sync-${a}-${Date.now()}`,h={peerID:a,startTime:Date.now(),documentsAttempted:0,documentsCompleted:0};this.#o.set(d,h),this.#m({type:"started",peerID:a,timestamp:Date.now()});try{let u=this.#l;if(!t(u))throw Error("Signing identity required for Merkle sync");let y=new o({runtime:this.#s,identity:u,logger:this.#r,serverResolver:this.#c});n=await y.connect(m.endpoint,a);let v=p??"pull";this.#r.info("Negotiating sync scopes",{scopes:l,direction:v});let{acceptedScopes:f,excludedDocumentIDs:D,missingClusters:w,direction:k}=await y.negotiate(n,l,c,g,v);if(0===f.length)return this.#r.info("No scopes accepted by peer"),this.#a.set(a,Date.now()),this.#m({type:"completed",peerID:a,timestamp:Date.now()}),this.#o.delete(d),{sessionID:d,divergentBuckets:0,messagesReceived:0,messagesSent:0,missingClusters:w};null!=w&&Object.keys(w).length>0&&(null!=this.#e?(this.#r.info("Deploying missing clusters from peer",{clusterCount:Object.keys(w).length}),await this.#e(w)):this.#r.warn("Missing clusters received but no deployClusters callback configured",{clusterCount:Object.keys(w).length})),this.#r.info("Building local Merkle tree",{acceptedScopes:f});let S=await s(e.stores),P=await S.getDocumentIDsForScope(f,D),R=await S.getMutationLogForDocuments(P),I=i(R),b=k??v;this.#r.info("Requesting Merkle sync from peer",{localTreeBuckets:Object.keys(I.buckets).length,direction:b});let C=await y.merkleSync(n,{scopes:f,excludedDocumentIDs:D,localTree:I,direction:b,localEntries:R});return C.mutationJWTs.length>0&&(this.#r.info("Applying sync mutations",{mutations:C.mutationJWTs.length}),h.documentsCompleted=(await r({db:e.stores,graph:this.#t,mutationJWTs:C.mutationJWTs,selfDID:this.#l.id,storeUnreadable:this.#g,defaultAccessLevel:this.#p})).applied),this.#a.set(a,Date.now()),this.#m({type:"completed",peerID:a,timestamp:Date.now()}),this.#r.info("Merkle sync completed",{divergentBuckets:C.divergentBuckets,mutationsReceived:C.mutationJWTs.length}),{sessionID:d,divergentBuckets:C.divergentBuckets,messagesReceived:C.mutationJWTs.length,messagesSent:C.mutationsSent,missingClusters:w}}catch(e){throw this.#r.error("Merkle sync failed",{peerDID:a,error:e}),this.#m({type:"error",peerID:a,timestamp:Date.now(),error:e instanceof Error?e.message:String(e)}),e}finally{if(null!=n)try{n.abort("SyncComplete"),await n.dispose()}catch{}this.#o.delete(d)}}getStatus(e){let{peerDID:t}=e,s=Array.from(this.#o.values()).filter(e=>!t||e.peerID===t).map(e=>({peerID:e.peerID,startTime:e.startTime,documentsAttempted:e.documentsAttempted,documentsCompleted:e.documentsCompleted})),r={};for(let[e,s]of this.#a.entries())t&&e!==t||(r[e]=s);return{activeSessions:s,lastSyncByPeer:r}}onSyncEvent(e){return this.#n.on("sync",e)}#m(e){this.#n.emit("sync",e).catch(e=>{this.#r.error("Error in sync event listener",{error:e})})}async dispose(){this.#o.clear(),this.#a.clear()}}