@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/sync/broadcast-sender.js

@@ -1 +1,179 @@
-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)}}
+import { catalogMatchesDoc, resolveAccessRule } from '@kubun/engine';
+import { DocumentID } from '@kubun/id';
+import { getGraphStore } from '@kubun/store-graph';
+import { getP2PStore } from '@kubun/store-p2p';
+import { computeBroadcastScopes } from './scope-resolver.js';
+/**
+ * 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 const DEFAULT_PUSH_SYNC_CONFIG = {
+    enabled: false
+};
+/**
+ * Default rule used by the broadcast sender when the engine is not carrying
+ * an explicit server-side default access level. Kept conservative (only the
+ * owner receives) so undeclared models never accidentally fan out.
+ */ const DEFAULT_ACCESS_LEVEL = {
+    read: 'only_owner',
+    write: 'only_owner'
+};
+/**
+ * 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 function wireBroadcastSender(params) {
+    const defaultAccessLevel = params.defaultAccessLevel ?? DEFAULT_ACCESS_LEVEL;
+    return params.eventBus.on('engine:mutation:authored', async (event)=>{
+        try {
+            await handleAuthoredMutation(event, {
+                ...params,
+                defaultAccessLevel
+            });
+        } catch (error) {
+            params.logger?.warn('broadcast-sender handler failed', {
+                documentID: event.documentID,
+                error: String(error)
+            });
+        }
+    });
+}
+async function handleAuthoredMutation(event, params) {
+    const graphStore = await getGraphStore(params.db);
+    const p2pStore = await getP2PStore(params.db);
+    // 1. Fetch document. If it no longer exists (unexpected, since the apply
+    // just completed) there is nothing to route — drop silently.
+    const doc = await graphStore.getDocument(DocumentID.fromString(event.documentID));
+    if (doc == null) {
+        return;
+    }
+    // 2. Resolve the effective read rule — broadcast scope follows read access.
+    const rule = await resolveAccessRule(doc, doc.model, doc.owner, 'read', {
+        getUserModelAccessDefault: (ownerDID, modelID, permissionType)=>graphStore.getUserModelAccessDefault(ownerDID, modelID, permissionType),
+        isMemberOfAnyCircle: (viewerDID, circleIDs)=>p2pStore.isMemberOfAnyCircle(viewerDID, circleIDs),
+        isMemberOfAnyGroup: (viewerDID, groupIDs)=>p2pStore.isMemberOfAnyGroup(viewerDID, groupIDs),
+        getModelInterfaces: (modelID)=>graphStore.getModelInterfaces(modelID)
+    }, params.defaultAccessLevel);
+    // Short-circuit only_owner — scope resolver would also drop this, but we
+    // can avoid all the catalog lookups.
+    if (rule.level === 'only_owner') {
+        return;
+    }
+    // 3. Enumerate sender's circles and catalog-match per circle. A sender's MLS
+    // group is a candidate broadcast scope iff at least one of the sender's
+    // circles within that group covers this document.
+    //
+    // Pre-fetch every catalog referenced across senderCircles in ONE batched
+    // query — replaces an O(circles × catalogs) sequential `getCatalog` loop.
+    // catalogMatchesDoc reads are then run in parallel since they have no
+    // inter-iteration ordering.
+    const senderCircles = await p2pStore.getCirclesForMember(params.selfDID);
+    const catalogIDSet = new Set();
+    for (const circle of senderCircles){
+        for (const catalogID of circle.catalog_ids ?? []){
+            catalogIDSet.add(catalogID);
+        }
+    }
+    const catalogsByID = catalogIDSet.size > 0 ? await graphStore.getCatalogs(Array.from(catalogIDSet)) : new Map();
+    const matchInputs = [];
+    for (const circle of senderCircles){
+        for (const catalogID of circle.catalog_ids ?? []){
+            const catalog = catalogsByID.get(catalogID);
+            if (catalog == null) continue;
+            matchInputs.push({
+                groupID: circle.group_id,
+                criteria: catalog.filter_criteria
+            });
+        }
+    }
+    const matchResults = await Promise.all(matchInputs.map(async (input)=>({
+            groupID: input.groupID,
+            matched: await catalogMatchesDoc(input.criteria, doc, p2pStore)
+        })));
+    const matchedGroupIDs = new Set();
+    for (const r of matchResults){
+        if (r.matched) matchedGroupIDs.add(r.groupID);
+    }
+    const senderGroupIDs = Array.from(matchedGroupIDs);
+    if (senderGroupIDs.length === 0) {
+        return;
+    }
+    // 4. Build the ResolvedAccessRule expected by computeBroadcastScopes.
+    const allowedGroupIDs = new Set(rule.allowedGroups ?? []);
+    // Single batched query for allowedCircles → parent group IDs. Replaces a
+    // per-circle `getCircle` loop.
+    const allowedCircleParentGroupIDs = new Set();
+    if (rule.allowedCircles != null && rule.allowedCircles.length > 0) {
+        const circlesByID = await p2pStore.getCircles(rule.allowedCircles);
+        for (const circle of circlesByID.values()){
+            if (circle.group_id != null) {
+                allowedCircleParentGroupIDs.add(circle.group_id);
+            }
+        }
+    }
+    // Single batched query for allowedDIDs → groups. Replaces a per-DID
+    // `getGroupsForMember` loop.
+    const allowedDIDGroupIDs = new Set();
+    if (rule.allowedDIDs != null && rule.allowedDIDs.length > 0) {
+        const groupsByDID = await p2pStore.getGroupsForMembers(rule.allowedDIDs);
+        for (const groups of groupsByDID.values()){
+            for (const g of groups){
+                allowedDIDGroupIDs.add(g.id);
+            }
+        }
+    }
+    const resolvedRule = {
+        level: rule.level,
+        allowedGroupIDs,
+        allowedCircleParentGroupIDs,
+        allowedDIDGroupIDs
+    };
+    // 5. Resolve final broadcast scopes.
+    const scopes = computeBroadcastScopes({
+        resolvedRule,
+        senderGroupIDs
+    });
+    if (scopes.length === 0) {
+        return;
+    }
+    // 6. Per scope — broadcast_log dedup (returns false if already recorded)
+    // then enqueue into the per-target-group batch queue. Dedup MUST run before
+    // enqueue so duplicate entries never enter the queue.
+    //
+    // Record-before-send: a recorded entry whose queue.enqueue throws will
+    // not be retried. This is at-most-once delivery by design; missing
+    // broadcasts are recovered via merkle-pull, not by replaying the
+    // authored event.
+    //
+    // This loop stays SEQUENTIAL (no Promise.all). `recordBroadcast` ordering
+    // matters for the at-most-once invariant, and the queue's per-group state
+    // machines have not been audited for concurrent enqueue safety. The earlier
+    // catalog-match/getCircles/getGroupsForMembers calls were parallelized
+    // because they are pure DB reads with no inter-iteration ordering — this
+    // path performs side-effecting writes and external dispatch.
+    for (const groupID of scopes){
+        const recorded = await p2pStore.recordBroadcast({
+            docID: event.documentID,
+            version: event.version,
+            mlsGroupID: groupID
+        });
+        if (!recorded) {
+            continue;
+        }
+        const entry = {
+            mutationJWT: event.mutationJWT,
+            docID: event.documentID,
+            version: event.version,
+            modelID: event.modelID
+        };
+        params.queue.enqueue(groupID, entry, params.selfDID);
+    }
+}

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

@@ -1,17 +1,18 @@
-import type { KubunDB } from '@kubun/db';
+import type { StoreProvider } from '@kubun/db';
 export type CatalogSyncScope = {
     modelIDs: Array<string>;
     owners: Array<string> | undefined;
-    requiredClusterIDs: Array<string>;
-    missingClusterIDs: Array<string>;
 };
 /**
  * Resolve catalog criteria to sync-compatible scopes.
  *
  * Takes catalog IDs, resolves their criteria, and returns:
- * - modelIDs: union of all model filters from all catalogs
+ * - modelIDs: union of all model filters from all catalogs, with an omitted
+ *   filter expanded to every model this device has deployed
  * - owners: union of all owner filters (explicit + circle members)
- * - requiredClusterIDs: cluster IDs for all required models
- * - missingClusterIDs: cluster IDs for models not in knownModelIDs
+ *
+ * Which of those models the requester lacks is NOT decided here: the negotiate
+ * handler answers that over the scopes it accepted, which is the only set that
+ * production actually sends.
  */
-export declare function resolveCatalogSyncScopes(db: KubunDB, catalogIDs: Array<string>, knownModelIDs?: Array<string>): Promise<CatalogSyncScope>;
+export declare function resolveCatalogSyncScopes(db: StoreProvider, catalogIDs: Array<string>): Promise<CatalogSyncScope>;

package/lib/sync/catalog-scope.js

@@ -1 +1,84 @@
-import{getGraphStore as e}from"@kubun/store-graph";import{getP2PStore as r}from"@kubun/store-p2p";export async function resolveCatalogSyncScopes(l,t,o){let[a,i]=await Promise.all([e(l),r(l)]),s=new Set,f=new Set,n=!1;for(let e of t){let r=await a.resolveCatalogScope(e);if(null!=r.models)for(let e of r.models)s.add(e);if(null!=r.owners)for(let e of(n=!0,r.owners))f.add(e);let l=await a.getCatalog(e);if(null!=l){let e=l.filter_criteria;if(null!=e.circles&&e.circles.length>0)for(let r of(n=!0,e.circles))for(let e of(await i.listCircleMembers(r)))f.add(e.member_did)}}let d=Array.from(s),m=n?Array.from(f):void 0,u=new Set(o??[]),c=new Set,w=new Set;return await Promise.all(d.map(async e=>{let r=await a.getClusterForModel(e);null!=r&&(c.add(r),u.has(e)||w.add(r))})),{modelIDs:d,owners:m,requiredClusterIDs:Array.from(c),missingClusterIDs:Array.from(w)}}
+import { getGraphStore } from '@kubun/store-graph';
+import { getP2PStore } from '@kubun/store-p2p';
+/**
+ * Resolve catalog criteria to sync-compatible scopes.
+ *
+ * Takes catalog IDs, resolves their criteria, and returns:
+ * - modelIDs: union of all model filters from all catalogs, with an omitted
+ *   filter expanded to every model this device has deployed
+ * - owners: union of all owner filters (explicit + circle members)
+ *
+ * Which of those models the requester lacks is NOT decided here: the negotiate
+ * handler answers that over the scopes it accepted, which is the only set that
+ * production actually sends.
+ */ export async function resolveCatalogSyncScopes(db, catalogIDs) {
+    const [graphStore, p2pStore] = await Promise.all([
+        getGraphStore(db),
+        getP2PStore(db)
+    ]);
+    const allModelIDs = new Set();
+    const allOwners = new Set();
+    let hasOwnerFilter = false;
+    // Catalogs are advisory: only a locally-activated catalog scopes sync. A known
+    // (not-activated) or unknown catalog contributes nothing. Read as one batch —
+    // the loop below needs every record anyway, and `resolveCatalogScope` reads the
+    // row again for itself, so a per-id read here would be the second of three.
+    const catalogs = await graphStore.getCatalogs(catalogIDs);
+    const circleIDs = new Set();
+    // Read once, and only if some catalog omits its model filter.
+    let deployedModelIDs;
+    const getDeployedModelIDs = async ()=>{
+        deployedModelIDs ??= await graphStore.listDocumentModelIDs();
+        return deployedModelIDs;
+    };
+    for (const catalogID of catalogIDs){
+        const catalog = catalogs.get(catalogID);
+        if (catalog == null || catalog.active !== 1) {
+            continue;
+        }
+        const scope = await graphStore.resolveCatalogScope(catalogID);
+        const criteria = catalog.filter_criteria;
+        const catalogCircles = criteria.circles != null && criteria.circles.length > 0 ? criteria.circles : undefined;
+        if (scope.owners != null) {
+            hasOwnerFilter = true;
+            for (const o of scope.owners){
+                allOwners.add(o);
+            }
+        }
+        if (catalogCircles != null) {
+            hasOwnerFilter = true;
+            for (const circleID of catalogCircles){
+                circleIDs.add(circleID);
+            }
+        }
+        if (scope.models != null) {
+            for (const m of scope.models){
+                allModelIDs.add(m);
+            }
+        } else if (scope.owners != null || catalogCircles != null) {
+            // "Omitted means no constraint" is only true where a dimension can be
+            // enumerated: expanding models at resolution time also covers a model
+            // deployed after the catalog was written. Owners stay anchorless on
+            // purpose — "everyone" is not a set — so the expansion is gated on the
+            // catalog naming owners or circles. Without that gate a criteria-less
+            // catalog would widen the SERVING side, where an absent owner filter
+            // means every distinct owner of every model.
+            for (const m of (await getDeployedModelIDs())){
+                allModelIDs.add(m);
+            }
+        }
+    }
+    // Resolve circle-based owners via the p2p store, every catalog's circles at
+    // once. `listOwnersForCircles` unions `listCircleOwners` over the set: explicit
+    // members plus, for an open circle, the whole group's members — the pull-owner
+    // set mirrors the open-access predicate.
+    if (circleIDs.size > 0) {
+        for (const owner of (await p2pStore.listOwnersForCircles(Array.from(circleIDs)))){
+            allOwners.add(owner);
+        }
+    }
+    return {
+        modelIDs: Array.from(allModelIDs),
+        owners: hasOwnerFilter ? Array.from(allOwners) : undefined
+    };
+}

package/lib/sync/errors.d.ts

@@ -5,7 +5,17 @@
  * so server-side logging and tests can assert the reason.
  */
 export declare class SyncAccessDeniedError extends Error {
-    readonly code: "KB08";
-    readonly reason: string;
+    #private;
     constructor(reason: string, message?: string);
+    get code(): 'KB08';
+    get reason(): string;
+    /**
+     * Carried alongside the code when the handler boundary translates this into a
+     * wire error, so a caller can tell the denials apart without parsing the
+     * message. The reasons are a fixed categorical set and disclose nothing the
+     * caller did not supply.
+     */
+    get data(): {
+        reason: string;
+    };
 }

package/lib/sync/errors.js

@@ -1 +1,29 @@
-export class SyncAccessDeniedError extends Error{code="KB08";reason;constructor(e,r){super(r??`Sync access denied: ${e}`),this.name="SyncAccessDeniedError",this.reason=e}}
+/**
+ * Thrown by the sync handlers when a request is denied before any store
+ * read — for example a forged subject, an unauthorized scope, or a
+ * disallowed direction. Tagged with the protocol-level error code `KB08`
+ * so server-side logging and tests can assert the reason.
+ */ export class SyncAccessDeniedError extends Error {
+    #reason;
+    constructor(reason, message){
+        super(message ?? `Sync access denied: ${reason}`);
+        this.name = 'SyncAccessDeniedError';
+        this.#reason = reason;
+    }
+    get code() {
+        return 'KB08';
+    }
+    get reason() {
+        return this.#reason;
+    }
+    /**
+   * Carried alongside the code when the handler boundary translates this into a
+   * wire error, so a caller can tell the denials apart without parsing the
+   * message. The reasons are a fixed categorical set and disclose nothing the
+   * caller did not supply.
+   */ get data() {
+        return {
+            reason: this.#reason
+        };
+    }
+}

package/lib/sync/forwarder.d.ts

@@ -71,27 +71,21 @@ export type EvaluateAndForwardResult = {
     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`.
+ * Evaluate forwarding candidates for one just-applied `mutation:apply` entry and
+ * forward to each survivor 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`.
+ * Gates per candidate group, in order: the source group is excluded first;
+ * `computeBroadcastScopes` against the post-apply rule; a circle the local peer
+ * belongs to in that group must hold a catalog whose `filter_criteria` matches
+ * the document; then the caller's `forwarding` filter when it is a function.
+ * `recordBroadcast` runs BEFORE the schedule and a false return skips silently.
  *
- * Per-candidate errors are isolated: one bad candidate logs + continues; the
- * rest still get evaluated. The function never throws.
+ * Per-candidate errors are isolated — one bad candidate logs and the rest are
+ * still evaluated — and 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.
+ * Each candidate gets its OWN single-entry broadcast, `senderPeerDID = selfDID`,
+ * rather than going through the batch queue, whose `senderPeerDID`-mismatch
+ * flush conflicts with mixing locally-authored and forwarded entries in one
+ * batch.
  */
 export declare function evaluateAndForward(params: EvaluateAndForwardParams): Promise<EvaluateAndForwardResult>;

package/lib/sync/forwarder.js

@@ -1 +1,271 @@
-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}}
+import { catalogMatchesDoc, resolveAccessRule } from '@kubun/engine';
+import { computeBroadcastScopes } from './scope-resolver.js';
+// The store-read catch blocks below degrade gracefully on a transient failure
+// (treat the result as missing and skip the forward). A SyntaxError / TypeError
+// / ReferenceError / RangeError is a bug or corrupt data, not a transient
+// condition — rethrow it so it surfaces instead of being silently swallowed.
+export function rethrowIfProgrammerError(error) {
+    if (error instanceof SyntaxError || error instanceof TypeError || error instanceof ReferenceError || error instanceof RangeError) {
+        throw error;
+    }
+}
+/**
+ * Evaluate forwarding candidates for one just-applied `mutation:apply` entry and
+ * forward to each survivor via `scheduleBroadcast`.
+ *
+ * Gates per candidate group, in order: the source group is excluded first;
+ * `computeBroadcastScopes` against the post-apply rule; a circle the local peer
+ * belongs to in that group must hold a catalog whose `filter_criteria` matches
+ * the document; then the caller's `forwarding` filter when it is a function.
+ * `recordBroadcast` runs BEFORE the schedule and a false return skips silently.
+ *
+ * Per-candidate errors are isolated — one bad candidate logs and the rest are
+ * still evaluated — and the function never throws.
+ *
+ * Each candidate gets its OWN single-entry broadcast, `senderPeerDID = selfDID`,
+ * rather than going through the batch queue, whose `senderPeerDID`-mismatch
+ * flush conflicts with mixing locally-authored and forwarded entries in one
+ * batch.
+ */ export async function evaluateAndForward(params) {
+    // 1. Zero-overhead short-circuit when forwarding is disabled.
+    if (params.forwarding === false) {
+        return {
+            forwarded: 0,
+            skipped: 0
+        };
+    }
+    const filter = params.forwarding === true ? ()=>true : params.forwarding;
+    // 2. Enumerate self group memberships and exclude the source group.
+    const myGroups = await params.p2pStore.getGroupsForMember(params.selfDID);
+    const candidateGroupIDs = myGroups.map((g)=>g.id).filter((id)=>id !== params.sourceGroupID);
+    if (candidateGroupIDs.length === 0) {
+        return {
+            forwarded: 0,
+            skipped: 0
+        };
+    }
+    // 3. Resolve the effective read rule against the post-apply state. Same
+    // db-shape wrappers as `processBroadcast` uses for `createReceiveAccessGate`.
+    let rule;
+    try {
+        rule = await resolveAccessRule(params.postState, params.postState.model, params.postState.owner, 'read', {
+            getUserModelAccessDefault: (ownerDID, modelID, permissionType)=>params.graphStore.getUserModelAccessDefault(ownerDID, modelID, permissionType),
+            isMemberOfAnyCircle: (viewerDID, circleIDs)=>params.p2pStore.isMemberOfAnyCircle(viewerDID, circleIDs),
+            isMemberOfAnyGroup: (viewerDID, groupIDs)=>params.p2pStore.isMemberOfAnyGroup(viewerDID, groupIDs),
+            getModelInterfaces: (modelID)=>params.graphStore.getModelInterfaces(modelID)
+        }, params.defaultAccessLevel);
+    } catch (error) {
+        rethrowIfProgrammerError(error);
+        params.logger?.warn('forwarder: resolveAccessRule failed, skipping forward', {
+            docID: params.entry.docID,
+            version: params.entry.version,
+            sourceGroupID: params.sourceGroupID,
+            error: String(error)
+        });
+        return {
+            forwarded: 0,
+            skipped: 0
+        };
+    }
+    // 4. Build the resolved-rule shape consumed by computeBroadcastScopes. This
+    // mirrors the sender's pre-resolution in broadcast-sender.ts.
+    const allowedGroupIDs = new Set(rule.allowedGroups ?? []);
+    // Single batched query for allowedCircles → parent group IDs. Replaces a
+    // per-circle `getCircle` loop. A query-level failure aborts only this
+    // sub-step (with a log) and yields an empty set, mirroring the prior
+    // per-circle skip-on-error behavior in aggregate.
+    const allowedCircleParentGroupIDs = new Set();
+    if (rule.allowedCircles != null && rule.allowedCircles.length > 0) {
+        try {
+            const circlesByID = await params.p2pStore.getCircles(rule.allowedCircles);
+            for (const circle of circlesByID.values()){
+                if (circle.group_id != null) {
+                    allowedCircleParentGroupIDs.add(circle.group_id);
+                }
+            }
+        } catch (error) {
+            rethrowIfProgrammerError(error);
+            params.logger?.warn('forwarder: getCircles failed, skipping allowedCircles', {
+                count: rule.allowedCircles.length,
+                error: String(error)
+            });
+        }
+    }
+    // Single batched query for allowedDIDs → groups. Replaces a per-DID
+    // `getGroupsForMember` loop.
+    const allowedDIDGroupIDs = new Set();
+    if (rule.allowedDIDs != null && rule.allowedDIDs.length > 0) {
+        try {
+            const groupsByDID = await params.p2pStore.getGroupsForMembers(rule.allowedDIDs);
+            for (const groups of groupsByDID.values()){
+                for (const g of groups){
+                    allowedDIDGroupIDs.add(g.id);
+                }
+            }
+        } catch (error) {
+            rethrowIfProgrammerError(error);
+            params.logger?.warn('forwarder: getGroupsForMembers failed, skipping allowedDIDs', {
+                count: rule.allowedDIDs.length,
+                error: String(error)
+            });
+        }
+    }
+    const resolvedRule = {
+        level: rule.level,
+        allowedGroupIDs,
+        allowedCircleParentGroupIDs,
+        allowedDIDGroupIDs
+    };
+    // 5. Apply access gate via computeBroadcastScopes.
+    const accessPermitted = computeBroadcastScopes({
+        resolvedRule,
+        senderGroupIDs: candidateGroupIDs
+    });
+    if (accessPermitted.length === 0) {
+        return {
+            forwarded: 0,
+            skipped: 0
+        };
+    }
+    // 6. Resolve self circles once and bucket by group_id for catalog-match
+    // lookups. A candidate group is catalog-eligible iff at least one of the
+    // local peer's circles WITHIN that group has a catalog matching the doc.
+    let myCircles;
+    try {
+        myCircles = await params.p2pStore.getCirclesForMember(params.selfDID);
+    } catch (error) {
+        rethrowIfProgrammerError(error);
+        params.logger?.warn('forwarder: getCirclesForMember failed', {
+            selfDID: params.selfDID,
+            error: String(error)
+        });
+        return {
+            forwarded: 0,
+            skipped: 0
+        };
+    }
+    const accessSet = new Set(accessPermitted);
+    const circlesByGroup = new Map();
+    for (const circle of myCircles){
+        if (!accessSet.has(circle.group_id)) continue;
+        const list = circlesByGroup.get(circle.group_id);
+        if (list != null) {
+            list.push(circle);
+        } else {
+            circlesByGroup.set(circle.group_id, [
+                circle
+            ]);
+        }
+    }
+    // 6b. Pre-fetch every catalog referenced by the relevant circles in a
+    // single batched DB query. This collapses O(candidates × circles ×
+    // catalogs) sequential awaits in the candidate loop down to ONE DB call
+    // per evaluation. Catalogs can be shared across circles, so the Set
+    // already dedups IDs before the call.
+    const catalogIDSet = new Set();
+    for (const circles of circlesByGroup.values()){
+        for (const circle of circles){
+            for (const catalogID of circle.catalog_ids ?? []){
+                catalogIDSet.add(catalogID);
+            }
+        }
+    }
+    let catalogByID = new Map();
+    if (catalogIDSet.size > 0) {
+        try {
+            catalogByID = await params.graphStore.getCatalogs(Array.from(catalogIDSet));
+        } catch (error) {
+            rethrowIfProgrammerError(error);
+            // Single-query failure: treat all catalogs as missing (preserves the
+            // prior per-getCatalog-failure semantics in aggregate). Candidate
+            // groups whose catalogs are now unresolved will fall through the
+            // catalog gate as no-match.
+            params.logger?.warn('forwarder: getCatalogs failed, treating all as missing', {
+                count: catalogIDSet.size,
+                error: String(error)
+            });
+        }
+    }
+    let forwarded = 0;
+    let skipped = 0;
+    // 7. Evaluate each candidate group SEQUENTIALLY. This loop is deliberately
+    // not parallelized:
+    //   - `filter(ctx)` is a user-supplied callback whose side effects (e.g.
+    //     logging, metrics) may rely on candidate order.
+    //   - `recordBroadcast` ordering matters for the at-most-once invariant —
+    //     a failure mid-loop must not leave broadcasts recorded for groups
+    //     that were never scheduled.
+    //   - `scheduleBroadcast` ordering keeps test assertions stable and
+    //     surfaces failures deterministically.
+    // Pure DB reads upstream (catalog batch fetch, getCircles,
+    // getGroupsForMembers) are batched/parallel — only this side-effecting
+    // dispatch stays sequential.
+    for (const candidateGroupID of accessPermitted){
+        try {
+            // Catalog gate.
+            const circlesInGroup = circlesByGroup.get(candidateGroupID) ?? [];
+            let catalogEligible = false;
+            for (const circle of circlesInGroup){
+                const catalogIDs = circle.catalog_ids ?? [];
+                for (const catalogID of catalogIDs){
+                    const catalog = catalogByID.get(catalogID);
+                    if (catalog == null) continue;
+                    if (await catalogMatchesDoc(catalog.filter_criteria, params.postState, params.p2pStore)) {
+                        catalogEligible = true;
+                        break;
+                    }
+                }
+                if (catalogEligible) break;
+            }
+            if (!catalogEligible) {
+                skipped++;
+                continue;
+            }
+            // Filter gate.
+            const ctx = {
+                docID: params.entry.docID,
+                modelID: params.entry.modelID,
+                ownerDID: params.postState.owner,
+                sourceGroupID: params.sourceGroupID,
+                candidateGroupID,
+                postState: params.postState
+            };
+            const allow = await filter(ctx);
+            if (!allow) {
+                skipped++;
+                continue;
+            }
+            // Dedup BEFORE schedule — record-before-send pattern (sender mirror).
+            const recorded = await params.p2pStore.recordBroadcast({
+                docID: params.entry.docID,
+                version: params.entry.version,
+                mlsGroupID: candidateGroupID
+            });
+            if (!recorded) {
+                continue;
+            }
+            const message = {
+                type: 'mutation:apply',
+                entries: [
+                    params.entry
+                ],
+                senderPeerDID: params.selfDID
+            };
+            await params.scheduleBroadcast(candidateGroupID, message);
+            forwarded++;
+        } catch (error) {
+            // Per-candidate isolation: log and continue with rest.
+            params.logger?.warn('forwarder: candidate evaluation failed', {
+                docID: params.entry.docID,
+                version: params.entry.version,
+                candidateGroupID,
+                sourceGroupID: params.sourceGroupID,
+                error: String(error)
+            });
+        }
+    }
+    return {
+        forwarded,
+        skipped
+    };
+}