@diister/quick-permission 0.9.0-beta.6 → 0.9.0-beta.7

package/dist/system.js

@@ -1,16 +1,3 @@
-/**
- * Moteur d'orchestration resource-pipe.
- *
- * Responsabilités :
- *  - Maintenir un cache `(resource.id, dedupKey) → Promise<T>` par context()
- *  - Filtrer les rules actives (activeWhen) avant de fetcher leurs needs
- *  - Lancer les fetches en parallèle (Promise.all) avec dedup
- *  - Évaluer les rules d'un grant en série (préserve l'ordre des reasons)
- *  - OR sémantique entre grants : un grant qui passe = `ok: true`
- *  - Validation d'arity du target au boot et au check
- *
- * Cf. RFC §"Sémantique d'exécution".
- */
 import { aggregateConstraints, combineGrantConstraints, mergeFilterSpec, resolveFilteredData, } from "./aggregation.js";
 import { buildAggregationStages } from "./indirect-aggregation.js";
 import { extractIndirectResource, } from "./indirect-resource.js";
@@ -22,16 +9,41 @@ function keyMatchesPattern(key, pattern) {
     }
     return false;
 }
-function providerHandlesKey(provider, key) {
-    if (!provider.keys && !provider.matches)
-        return true;
+function providerDeclaresKey(provider, key) {
     if (provider.keys?.some((p) => keyMatchesPattern(key, p)))
         return true;
-    if (provider.matches?.(key))
+    return provider.matches?.(key) === true;
+}
+export function refType(segment) {
+    if (typeof segment !== "string")
+        return undefined;
+    const colon = segment.indexOf(":");
+    return colon > 0 ? segment.slice(0, colon) : undefined;
+}
+function providerHandlesTarget(provider, target) {
+    if (provider.targetType === undefined)
         return true;
-    return false;
+    const first = target?.[0];
+    if (first === undefined || isWildcardSegment(first))
+        return false;
+    const type = refType(first);
+    if (type === undefined)
+        return false;
+    return typeof provider.targetType === "string"
+        ? provider.targetType === type
+        : provider.targetType.includes(type);
+}
+function callHook(invoke) {
+    try {
+        invoke();
+    }
+    catch {
+        return;
+    }
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
 }
-// ─── Schema validation au boot ──────────────────────────────────────────
 function validateSchema(schema) {
     const issues = [];
     for (const [key, perm] of Object.entries(schema)) {
@@ -45,7 +57,6 @@ function validateSchema(schema) {
             });
         }
         catch {
-            // Best-effort : si expandsTo throw sur le stub, on skip.
             continue;
         }
         for (const child of samples) {
@@ -58,27 +69,16 @@ function validateSchema(schema) {
         throw new Error(`Schema validation failed:\n  - ${issues.join("\n  - ")}`);
     }
 }
-// ─── Target matching (wildcards par segment) ────────────────────────────
 function asPath(value) {
     return Array.isArray(value) ? value : [value];
 }
-/**
- * Une request target est une "capability query" si elle contient au moins
- * un wildcard (`"*"` ou suffix `":*"`). Dans ce mode, on n'a pas de
- * ressource concrète à fetcher — les rules font silent-pass quand elles
- * ne peuvent pas vérifier leur contrainte.
- */
-function isCapabilityQuery(target) {
+/** A query with any wildcard segment asks "could this subject, on some target"; rules that need a concrete document pass silently. */
+export function isCapabilityQuery(target) {
     if (!target)
         return false;
     return target.some(isWildcardSegment);
 }
-/**
- * True if a single target segment is a wildcard (`"*"` or `"xxx:*"`).
- * Inverse de "concret" — utilisé pour décider si une resource peut être
- * fetchée en cap-mode (segment concret → fetch OK).
- */
-function isWildcardSegment(seg) {
+export function isWildcardSegment(seg) {
     return seg === "*" || (typeof seg === "string" && seg.endsWith("*"));
 }
 function segmentOverlaps(a, b) {
@@ -100,19 +100,13 @@ function segmentOverlaps(a, b) {
 function targetMatches(grantTarget, requestTarget, schemaKind, capability) {
     if (schemaKind === "none")
         return true;
-    if (grantTarget === undefined) {
-        // A target-less grant only matches when the schema permits it.
-        // `optional` documents this "global grant" mode; `required` and `path`
-        // require the grant to carry a target.
+    if (grantTarget === undefined)
         return schemaKind === "optional";
-    }
     if (requestTarget === undefined)
         return false;
     const g = asPath(grantTarget);
     if (g.length !== requestTarget.length)
         return false;
-    // Capability mode (request has wildcards) uses overlap semantics so a
-    // specific-target grant like ["user:lucas"] still matches ["user:*"].
     if (capability) {
         return g.every((seg, i) => segmentOverlaps(seg, requestTarget[i]));
     }
@@ -127,20 +121,15 @@ function targetMatches(grantTarget, requestTarget, schemaKind, capability) {
         return seg === requestTarget[i];
     });
 }
-// ─── Intermediate expansion ──────────────────────────────────────────────
 function expandGrants(grants, schema, maxDepth = 10) {
     const out = [];
     const queue = grants.map((g) => ({
         grant: g,
         depth: 0,
     }));
-    while (queue.length) {
-        const { grant, depth } = queue.shift();
+    for (let head = 0; head < queue.length; head++) {
+        const { grant, depth } = queue[head];
         const perm = schema[grant.key];
-        // Drop grants that violate the schema's target contract: a grant
-        // without `target` on a `required` / `path` schema cannot match
-        // (see `targetMatches`) and its `expandsTo` cannot synthesize valid
-        // children. Skip silently so one bad grant doesn't break the call.
         if (perm &&
             grant.target === undefined &&
             (perm.target.kind === "required" || perm.target.kind === "path")) {
@@ -158,7 +147,6 @@ function expandGrants(grants, schema, maxDepth = 10) {
     }
     return out;
 }
-// ─── Serialization (pour list/tree) ──────────────────────────────────────
 function serializeSegment(s) {
     const types = s.types;
     return { name: s.name, types };
@@ -203,17 +191,6 @@ function collectIndirectsForPermission(perm) {
     }
     return Array.from(collected.values());
 }
-/**
- * Build a wildcard target stub matching the schema's arity. Used to sample
- * `expandsTo(grant)` at catalog enumeration time — we don't have a real
- * grant target available, but we need ARG_ARITY to match or `targetMatches`
- * would drop the synthesized child grants (see `expandGrants:228-234`).
- *
- *  - none      → undefined (no segments)
- *  - optional  → ["*"]
- *  - required  → ["*"]
- *  - path(n)   → ["*", "*", ..., "*"] (n segments)
- */
 function stubTargetFor(t) {
     if (t.kind === "none")
         return undefined;
@@ -221,70 +198,52 @@ function stubTargetFor(t) {
         return ["*"];
     return t.segments.map(() => "*");
 }
-// ─── Descendant computation (pour list/tree) ─────────────────────────────
-/**
- * BFS transitive expansion of an intermediate's `expandsTo` callback,
- * collecting LEAVES only (keys whose schema entry has no `expandsTo`).
- *
- * Sampling strategy : we call `perm.expandsTo({ key, target: <wildcard> })`
- * with an arity-matched wildcard stub. Real consumers (`expandGrants`)
- * call expandsTo with a concrete grant carrying `with`/`filter`/`flags` —
- * but for catalog enumeration we only care about the resulting child KEYS
- * (the same keys would be produced regardless of grant payload, since
- * macros are by convention pure key-routers).
- *
- * Defensive : caught exceptions in `expandsTo` (e.g. a callback that
- * asserts on a concrete segment) silently drop that branch — same posture
- * as `validateSchema`. Cycles are broken by the `visited` set.
- *
- * Returns `undefined` if `rootKey` is a leaf or not in schema (the caller
- * uses this signal to omit the field from the serialized entry rather
- * than emit an empty array).
- */
-function computeDescendants(rootKey, schema, maxDepth = 10) {
-    const root = schema[rootKey];
-    if (!root?.expandsTo)
-        return undefined;
-    const leaves = new Set();
-    const visited = new Set([rootKey]);
-    const queue = [
-        { key: rootKey, depth: 0 },
-    ];
-    while (queue.length) {
-        const { key, depth } = queue.shift();
-        const perm = schema[key];
-        if (!perm)
-            continue;
-        if (!perm.expandsTo) {
-            // Leaf reached. Exclude the root itself from its own descendant list.
-            if (key !== rootKey)
-                leaves.add(key);
-            continue;
-        }
-        if (depth >= maxDepth)
+// An intermediate is sampled with a wildcard grant: by convention `expandsTo`
+// routes keys and does not depend on the grant's target or payload.
+function expansionGraph(schema, maxDepth = 10) {
+    const descendants = new Map();
+    const ancestors = new Map();
+    for (const [rootKey, root] of Object.entries(schema)) {
+        if (!root.expandsTo)
             continue;
-        let children = [];
-        try {
-            children = perm.expandsTo({
-                key,
-                target: stubTargetFor(perm.target),
-            });
-        }
-        catch {
-            // Stub-throwing macro — best-effort skip, same as validateSchema.
-            continue;
-        }
-        for (const child of children) {
-            if (visited.has(child.key))
+        const leaves = [];
+        const visited = new Set([rootKey]);
+        const queue = [
+            { key: rootKey, depth: 0 },
+        ];
+        for (let head = 0; head < queue.length; head++) {
+            const { key, depth } = queue[head];
+            const perm = schema[key];
+            if (!perm)
+                continue;
+            if (!perm.expandsTo) {
+                leaves.push(key);
+                continue;
+            }
+            if (depth >= maxDepth)
+                continue;
+            let children = [];
+            try {
+                children = perm.expandsTo({ key, target: stubTargetFor(perm.target) });
+            }
+            catch {
                 continue;
-            visited.add(child.key);
-            queue.push({ key: child.key, depth: depth + 1 });
+            }
+            for (const child of children) {
+                if (visited.has(child.key))
+                    continue;
+                visited.add(child.key);
+                const list = ancestors.get(child.key) ?? [];
+                list.push(rootKey);
+                ancestors.set(child.key, list);
+                queue.push({ key: child.key, depth: depth + 1 });
+            }
         }
+        descendants.set(rootKey, leaves);
     }
-    return [...leaves];
+    return { descendants, ancestors };
 }
-// ─── Tree builder ────────────────────────────────────────────────────────
-function buildTree(schema) {
+function buildTree(schema, graph) {
     const root = { children: {} };
     function ensureGroup(parent, name) {
         const existing = parent.children[name];
@@ -317,9 +276,7 @@ function buildTree(schema) {
             }
         }
         const leafName = parts[parts.length - 1];
-        const descendants = perm.expandsTo
-            ? computeDescendants(key, schema)
-            : undefined;
+        const descendants = graph.descendants.get(key);
         cursor.children[leafName] = {
             kind: perm.expandsTo ? "intermediate" : "permission",
             key,
@@ -331,15 +288,31 @@ function buildTree(schema) {
     }
     return root;
 }
-// ─── createSystem ────────────────────────────────────────────────────────
 export function createSystem(opts) {
-    const { schema, providers = [] } = opts;
+    const { schema, providers = [], hooks = {} } = opts;
     validateSchema(schema);
-    // Resource registry built at boot from all rules' `needs` (direct
-    // resources) and indirect descriptors. Enables `ctx.preseed("id", ...)`
-    // to look up the resource by id — callers don't need to import the
-    // resource instance (handy when it lives inside a factory closure).
-    // Typo guard : throws with the list of available ids when missed.
+    const graph = expansionGraph(schema);
+    const providerNames = new Map(providers.map((provider, index) => [
+        provider,
+        (typeof provider === "object" && provider.name) || `provider#${index}`,
+    ]));
+    const handledKeys = new Map();
+    function providerHandlesKey(provider, key) {
+        if (!provider.keys && !provider.matches)
+            return true;
+        let memo = handledKeys.get(provider);
+        if (!memo) {
+            memo = new Map();
+            handledKeys.set(provider, memo);
+        }
+        const known = memo.get(key);
+        if (known !== undefined)
+            return known;
+        const handled = providerDeclaresKey(provider, key) ||
+            (graph.ancestors.get(key) ?? []).some((ancestor) => providerDeclaresKey(provider, ancestor));
+        memo.set(key, handled);
+        return handled;
+    }
     const resourceRegistry = new Map();
     for (const perm of Object.values(schema)) {
         for (const rule of perm.rules) {
@@ -355,9 +328,7 @@ export function createSystem(opts) {
     return {
         list() {
             return Object.entries(schema).map(([key, perm]) => {
-                const descendants = perm.expandsTo
-                    ? computeDescendants(key, schema)
-                    : undefined;
+                const descendants = graph.descendants.get(key);
                 return {
                     key,
                     kind: perm.expandsTo
@@ -371,7 +342,7 @@ export function createSystem(opts) {
             });
         },
         tree() {
-            return buildTree(schema);
+            return buildTree(schema, graph);
         },
         schema(key) {
             return schema[key];
@@ -437,32 +408,95 @@ export function createSystem(opts) {
                     fetchCounters.clear();
                 },
                 async dumpGrants() {
-                    const arrays = await Promise.all(grantsCache.values());
-                    return arrays.flat();
+                    const outcomes = await Promise.all([...grantsCache.values()].flatMap((byKey) => [...byKey.values()]));
+                    return outcomes.flatMap((outcome) => outcome.grants);
                 },
             };
         },
     };
+    function reportError(event) {
+        callHook(() => hooks.onError?.(event));
+    }
+    async function fetchFromProvider(provider, name, subject, key, target) {
+        const started = performance.now();
+        let grants;
+        try {
+            grants =
+                typeof provider === "function"
+                    ? await provider(subject, key, target)
+                    : await provider.fetch(subject, key, target);
+        }
+        catch (error) {
+            reportError({
+                source: "provider",
+                provider: name,
+                subject,
+                key,
+                target,
+                error,
+            });
+            return {
+                grants: [],
+                failure: `provider ${name} failed: ${describeError(error)}`,
+            };
+        }
+        const durationMs = performance.now() - started;
+        callHook(() => hooks.onProviderFetch?.({
+            provider: name,
+            subject,
+            key,
+            target,
+            durationMs,
+            grantCount: grants.length,
+        }));
+        return { grants };
+    }
     async function invokeProvider(provider, subject, key, target, state) {
-        if (typeof provider === "function") {
-            return await provider(subject, key, target);
+        const name = providerNames.get(provider) ?? "provider";
+        if (typeof provider === "object") {
+            if (!providerHandlesKey(provider, key))
+                return { grants: [] };
+            if (!providerHandlesTarget(provider, target))
+                return { grants: [] };
         }
-        if (!providerHandlesKey(provider, key))
-            return [];
-        const ck = provider.cacheKey?.(subject, key, target);
-        if (state && ck) {
-            let pending = state.grantsCache.get(ck);
-            if (!pending) {
-                pending = Promise.resolve(provider.fetch(subject, key, target));
-                state.grantsCache.set(ck, pending);
-            }
-            return await pending;
+        let ck;
+        try {
+            ck =
+                typeof provider === "object"
+                    ? provider.cacheKey?.(subject, key, target)
+                    : undefined;
+        }
+        catch (error) {
+            reportError({
+                source: "provider",
+                provider: name,
+                subject,
+                key,
+                target,
+                error,
+            });
+            return {
+                grants: [],
+                failure: `provider ${name} failed: ${describeError(error)}`,
+            };
+        }
+        if (!state || !ck) {
+            return fetchFromProvider(provider, name, subject, key, target);
+        }
+        let byKey = state.grantsCache.get(provider);
+        if (!byKey) {
+            byKey = new Map();
+            state.grantsCache.set(provider, byKey);
+        }
+        let pending = byKey.get(ck);
+        if (!pending) {
+            pending = fetchFromProvider(provider, name, subject, key, target);
+            byKey.set(ck, pending);
         }
-        return await provider.fetch(subject, key, target);
+        return pending;
     }
     async function fetchResource(resource, ctx, state) {
         if (!state) {
-            // Mode `system.can()` direct — pas de cache cross-grant.
             return Promise.resolve(resource.fetcher(ctx));
         }
         const key = resource.computeDedupKey(ctx);
@@ -501,36 +535,28 @@ export function createSystem(opts) {
         const arityErr = validateArity(perm, target);
         if (arityErr)
             return { ok: false, reasons: [arityErr] };
-        // Collect grants depuis les providers (en série pour préserver l'ordre)
         const allGrants = [];
+        const failures = [];
         for (const provider of providers) {
-            const grants = await invokeProvider(provider, subject, key, target, state);
-            allGrants.push(...grants);
+            const outcome = await invokeProvider(provider, subject, key, target, state);
+            allGrants.push(...outcome.grants);
+            if (outcome.failure)
+                failures.push(outcome.failure);
         }
         const expanded = expandGrants(allGrants, schema);
         const capability = isCapabilityQuery(target);
         const matching = expanded.filter((g) => g.key === key &&
             targetMatches(g.target, target, perm.target.kind, capability));
         if (matching.length === 0) {
-            return { ok: false, reasons: ["no matching grant"] };
+            return { ok: false, reasons: ["no matching grant", ...failures] };
         }
         const reasons = [];
         let lastData = undefined;
         const matchedGrantIds = [];
         let anyOk = false;
-        // One entry per matched grant. undefined = "any" (no constraint).
         const collectedConstraints = [];
-        // Filter rule cross-grant aggregation. `null` once any grant exposes
-        // no filter (= all fields). Else accumulates the union of filter specs.
         let referenceSource = undefined;
         let filterUnion = undefined;
-        // Grants that PASSED their rules — needed by indirect-resource
-        // aggregation. `matching` contains all grants that match key + target
-        // shape, but rules can reject some (e.g. a `with` spec evaluated
-        // against an auto-fetched resource in cap-mode). The indirect
-        // orchestrator must consider only successful grants — otherwise a
-        // rejected grant without indirect reference would trigger any-wins
-        // and disable the filter.
         const successfulGrants = [];
         for (const grant of matching) {
             const ctx = {
@@ -547,20 +573,8 @@ export function createSystem(opts) {
                     return false;
                 return r.needs.every((res) => res.isActiveFor(grant));
             });
-            // In cap-mode the engine normally skips all fetches. Exception : a
-            // resource whose `id` matches a segment NAME of the permission's
-            // target AND whose corresponding segment in the request target is
-            // CONCRETE (not `*` / not `xxx:*`) is fetched anyway. This lets
-            // `match()` evaluate properly for foreign resources (auxiliary
-            // checks like "the request's exposition belongs to my tenant")
-            // when only one segment of a multi-segment target is wildcard.
-            //
-            // Auto-binding is by convention : `resource.id === segment.name`.
-            // No opt-in needed — it just works if the convention is respected.
-            // Resources whose id matches no segment in the permission's schema
-            // are skipped in cap-mode (silent-pass + constraint emit, the
-            // legacy behaviour that powers `users.read` + `userOf.match`
-            // self-referencing pushdown).
+            // A capability query still fetches a resource named like a segment
+            // (`resource.id === segment.name`) when that segment is concrete.
             const requestTarget = target ?? [];
             const targetSegmentIndexById = (() => {
                 const out = new Map();
@@ -589,73 +603,81 @@ export function createSystem(opts) {
                 : Array.from(new Map(activeRules
                     .flatMap((r) => r.needs)
                     .map((r) => [r.id, r])).values());
-            const fetched = new Map();
-            await Promise.all(uniqueResources.map(async (r) => {
-                fetched.set(r.id, await fetchResource(r, ctx, state));
-            }));
-            // In concrete mode, indirect resources that declared a `fetcher`
-            // are fetched as well (their joined docs are attached to the ctx
-            // so `indirect.match()` can evaluate the spec). The cache key is
-            // target-derived so `CanContext.preseed()` can inject values
-            // produced by a cap-mode pipeline aggregation (no DB hit when
-            // listed docs already carry the `_lookupAlias`).
-            const indirectFetched = new Map();
-            if (!capability) {
-                const indirectsToFetch = perm.rules
-                    .map((r) => extractIndirectResource(r))
-                    .filter((ir) => ir !== null && ir.fetcher !== undefined);
-                await Promise.all(indirectsToFetch.map(async (ir) => {
-                    const sourceDoc = fetched.get(ir.from.id);
-                    if (sourceDoc === undefined || sourceDoc === null)
-                        return;
-                    const cacheKey = ir.cacheKeyForTarget(ctx.target);
-                    if (state) {
-                        const existing = state.cache.get(cacheKey);
-                        if (existing) {
-                            indirectFetched.set(ir.id, (await existing));
-                            return;
-                        }
-                        const pending = Promise.resolve(ir.fetcher(sourceDoc, ctx));
-                        state.cache.set(cacheKey, pending);
-                        indirectFetched.set(ir.id, await pending);
-                    }
-                    else {
-                        indirectFetched.set(ir.id, await ir.fetcher(sourceDoc, ctx));
-                    }
-                }));
-            }
-            // Attach indirect-fetched joined docs to the context so
-            // `indirect.match()` rule can read them.
-            const ctxWithIndirect = Object.assign({}, ctx, {
-                _indirectFetched: indirectFetched,
-            });
             let grantOk = true;
             let grantData = undefined;
-            // Multiple match rules in one permission (e.g., expositionInfo + badge)
-            // contribute distinct constraints — AND-merge them per grant.
             const grantConstraints = [];
+            const grantFilters = [];
             let grantHasMatchRule = false;
-            for (const rule of activeRules) {
-                if (rule.descriptor.kind === "match")
-                    grantHasMatchRule = true;
-                const data = rule.needs.map((r) => fetched.get(r.id));
-                const result = rule.check(data, ctxWithIndirect);
-                if (!result.ok) {
-                    grantOk = false;
-                    reasons.push(grant.id ? `[${grant.id}] ${result.reason}` : result.reason);
-                    break;
-                }
-                if (result.data !== undefined)
-                    grantData = result.data;
-                if (result.constraint !== undefined) {
-                    grantConstraints.push(result.constraint);
+            try {
+                const fetched = new Map();
+                await Promise.all(uniqueResources.map(async (r) => {
+                    fetched.set(r.id, await fetchResource(r, ctx, state));
+                }));
+                const indirectFetched = new Map();
+                if (!capability) {
+                    const indirectsToFetch = perm.rules
+                        .map((r) => extractIndirectResource(r))
+                        .filter((ir) => ir !== null && ir.fetcher !== undefined);
+                    await Promise.all(indirectsToFetch.map(async (ir) => {
+                        const sourceDoc = fetched.get(ir.from.id);
+                        if (sourceDoc === undefined || sourceDoc === null)
+                            return;
+                        const cacheKey = ir.cacheKeyForTarget(ctx.target);
+                        if (state) {
+                            const existing = state.cache.get(cacheKey);
+                            if (existing) {
+                                indirectFetched.set(ir.id, (await existing));
+                                return;
+                            }
+                            const pending = Promise.resolve(ir.fetcher(sourceDoc, ctx));
+                            state.cache.set(cacheKey, pending);
+                            indirectFetched.set(ir.id, await pending);
+                        }
+                        else {
+                            indirectFetched.set(ir.id, await ir.fetcher(sourceDoc, ctx));
+                        }
+                    }));
                 }
-                if (result.filter !== undefined) {
-                    referenceSource = result.filter.source;
-                    filterUnion = mergeFilterSpec(filterUnion, result.filter.spec);
+                const ctxWithIndirect = Object.assign({}, ctx, {
+                    _indirectFetched: indirectFetched,
+                });
+                for (const rule of activeRules) {
+                    if (rule.descriptor.kind === "match")
+                        grantHasMatchRule = true;
+                    const data = rule.needs.map((r) => fetched.get(r.id));
+                    const result = rule.check(data, ctxWithIndirect);
+                    if (!result.ok) {
+                        grantOk = false;
+                        reasons.push(grant.id ? `[${grant.id}] ${result.reason}` : result.reason);
+                        break;
+                    }
+                    if (result.data !== undefined)
+                        grantData = result.data;
+                    if (result.constraint !== undefined) {
+                        grantConstraints.push(result.constraint);
+                    }
+                    if (result.filter !== undefined)
+                        grantFilters.push(result.filter);
                 }
             }
+            catch (error) {
+                grantOk = false;
+                reportError({
+                    source: "rule",
+                    grantId: grant.id,
+                    subject,
+                    key,
+                    target,
+                    error,
+                });
+                const reason = `rule evaluation failed: ${describeError(error)}`;
+                reasons.push(grant.id ? `[${grant.id}] ${reason}` : reason);
+            }
             if (grantOk) {
+                for (const contribution of grantFilters) {
+                    referenceSource = contribution.source;
+                    filterUnion = mergeFilterSpec(filterUnion, contribution.spec);
+                }
                 anyOk = true;
                 successfulGrants.push(grant);
                 if (grant.id)
@@ -674,15 +696,14 @@ export function createSystem(opts) {
         if (!anyOk) {
             return {
                 ok: false,
-                reasons: reasons.length > 0 ? reasons : ["no matching grant"],
+                reasons: [
+                    ...(reasons.length > 0 ? reasons : ["no matching grant"]),
+                    ...failures,
+                ],
             };
         }
         const constraints = aggregateConstraints(collectedConstraints);
         const finalData = resolveFilteredData(filterUnion, referenceSource, lastData);
-        // Collect indirect resources referenced by the permission's rules
-        // (sentinel rules with descriptor.kind === "indirect-match"). If any
-        // are referenced by matched grants' `with`, emit an aggregation
-        // pipeline that pushes the JOIN constraint to the DB.
         const declaredIndirect = [];
         for (const rule of perm.rules) {
             const ir = extractIndirectResource(rule);
@@ -692,10 +713,8 @@ export function createSystem(opts) {
         let stages;
         if (declaredIndirect.length > 0) {
             const baseFilter = constraints ?? {};
-            // Must pass `successfulGrants` (rules accepted), NOT `matching`
-            // (raw key+target match). A grant rejected by a rule must not
-            // contribute to indirect any-wins — otherwise it would silently
-            // disable the indirect filter for its siblings.
+            // A rejected grant without an indirect reference would win "any" and
+            // lift the join filter for its siblings, so only accepted grants count.
             const result = buildAggregationStages(baseFilter, successfulGrants, declaredIndirect);
             if (result !== null)
                 stages = result;