@diister/quick-permission 0.9.0-beta.5

package/dist/core/matching.d.ts

@@ -0,0 +1,31 @@
+type TargetPath = readonly unknown[];
+/**
+ * Match a requested target path against a pattern path.
+ *
+ * Targets are always arrays of segments. Each segment is matched against the
+ * corresponding pattern segment.
+ *
+ * Segment-level wildcards:
+ * - `"*"` matches any value in that segment.
+ * - `"prefix:*"` matches any string segment that starts with `prefix:`.
+ *
+ * For "any target" semantics, leave the permission's `target` undefined at the
+ * call site rather than passing a wildcard here.
+ *
+ * @example
+ * matchPath(["article:123"], ["article:*"]) // true
+ * matchPath(["article:123", "comment:4"], ["article:*", "*"]) // true
+ * matchPath(["a"], ["a", "b"]) // false (different arity)
+ */
+export declare function matchPath(requested: TargetPath, pattern: TargetPath): boolean;
+/**
+ * Symmetric "overlap" match: returns true if there's any concrete value that
+ * could satisfy both `a` and `b` simultaneously (treating both as patterns).
+ *
+ * Used by broad-match checks where the request target itself may carry
+ * wildcards — e.g. "do I have any badge access in this expo?" with the request
+ * `["expo:1", "*"]` overlapping a grant on `["expo:1", "badge:*"]`.
+ */
+export declare function overlapPath(a: TargetPath, b: TargetPath): boolean;
+export {};
+//# sourceMappingURL=matching.d.ts.map

package/dist/core/matching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matching.d.ts","sourceRoot":"","sources":["../../core/matching.ts"],"names":[],"mappings":"AAAA,KAAK,UAAU,GAAG,SAAS,OAAO,EAAE,CAAC;AAErC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAG7E;AAuBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAGjE"}

package/dist/core/matching.js

@@ -0,0 +1,75 @@
+/**
+ * Match a requested target path against a pattern path.
+ *
+ * Targets are always arrays of segments. Each segment is matched against the
+ * corresponding pattern segment.
+ *
+ * Segment-level wildcards:
+ * - `"*"` matches any value in that segment.
+ * - `"prefix:*"` matches any string segment that starts with `prefix:`.
+ *
+ * For "any target" semantics, leave the permission's `target` undefined at the
+ * call site rather than passing a wildcard here.
+ *
+ * @example
+ * matchPath(["article:123"], ["article:*"]) // true
+ * matchPath(["article:123", "comment:4"], ["article:*", "*"]) // true
+ * matchPath(["a"], ["a", "b"]) // false (different arity)
+ */
+export function matchPath(requested, pattern) {
+    if (requested.length !== pattern.length)
+        return false;
+    return requested.every((segment, i) => matchSegment(segment, pattern[i]));
+}
+function matchSegment(requested, pattern) {
+    // Full-segment wildcard
+    if (pattern === "*")
+        return true;
+    // Prefix wildcard on string segments: "article:*"
+    if (typeof pattern === "string" &&
+        typeof requested === "string" &&
+        pattern.endsWith("*")) {
+        return requested.startsWith(pattern.slice(0, -1));
+    }
+    // Nested array segments (rare, but supported)
+    if (Array.isArray(pattern) && Array.isArray(requested)) {
+        return matchPath(requested, pattern);
+    }
+    return requested === pattern;
+}
+/**
+ * Symmetric "overlap" match: returns true if there's any concrete value that
+ * could satisfy both `a` and `b` simultaneously (treating both as patterns).
+ *
+ * Used by broad-match checks where the request target itself may carry
+ * wildcards — e.g. "do I have any badge access in this expo?" with the request
+ * `["expo:1", "*"]` overlapping a grant on `["expo:1", "badge:*"]`.
+ */
+export function overlapPath(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((segment, i) => overlapSegment(segment, b[i]));
+}
+function overlapSegment(a, b) {
+    // Full wildcards on either side → overlap
+    if (a === "*" || b === "*")
+        return true;
+    if (typeof a === "string" && typeof b === "string") {
+        const aPrefix = a.endsWith("*") ? a.slice(0, -1) : null;
+        const bPrefix = b.endsWith("*") ? b.slice(0, -1) : null;
+        if (aPrefix !== null && bPrefix !== null) {
+            // Two prefix wildcards: overlap iff one prefix extends the other
+            return aPrefix.startsWith(bPrefix) || bPrefix.startsWith(aPrefix);
+        }
+        if (aPrefix !== null)
+            return b.startsWith(aPrefix);
+        if (bPrefix !== null)
+            return a.startsWith(bPrefix);
+    }
+    // Nested arrays
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return overlapPath(a, b);
+    }
+    return a === b;
+}
+//# sourceMappingURL=matching.js.map

package/dist/core/matching.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matching.js","sourceRoot":"","sources":["../../core/matching.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS,CAAC,SAAqB,EAAE,OAAmB;IAClE,IAAI,SAAS,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACtD,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,SAAS,YAAY,CAAC,SAAkB,EAAE,OAAgB;IACxD,wBAAwB;IACxB,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAEjC,kDAAkD;IAClD,IACE,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,SAAS,KAAK,QAAQ;QAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EACrB,CAAC;QACD,OAAO,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,8CAA8C;IAC9C,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACvD,OAAO,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,SAAS,KAAK,OAAO,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,CAAa,EAAE,CAAa;IACtD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,cAAc,CAAC,CAAU,EAAE,CAAU;IAC5C,0CAA0C;IAC1C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAExC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnD,MAAM,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACxD,MAAM,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAExD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACzC,iEAAiE;YACjE,OAAO,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACnD,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACrD,CAAC;IAED,gBAAgB;IAChB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,OAAO,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3B,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC"}

package/dist/core/merging.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Merging utilities for combining outputs from multiple permissions
+ */
+export interface FilterSpec {
+    [key: string]: boolean | FilterSpec;
+}
+/**
+ * Merge two filter specs using union strategy (more permissive)
+ *
+ * @example
+ * mergeFilters(
+ *   { _id: true, name: true },
+ *   { name: true, email: true }
+ * )
+ * // → { _id: true, name: true, email: true }
+ */
+export declare function mergeFilters(current: FilterSpec | undefined, incoming: FilterSpec | undefined): FilterSpec;
+/**
+ * Merge two outputs intelligently based on the key
+ *
+ * @example
+ * mergeOutputs(
+ *   { filter: { _id: true }, data: { _id: 1 } },
+ *   { filter: { name: true }, data: { name: "John" } }
+ * )
+ * // → { filter: { _id: true, name: true }, data: { _id: 1, name: "John" } }
+ */
+export declare function mergeOutputs(current: any, incoming: any): any;
+//# sourceMappingURL=merging.d.ts.map

package/dist/core/merging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merging.d.ts","sourceRoot":"","sources":["../../core/merging.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,QAAQ,EAAE,UAAU,GAAG,SAAS,GAC/B,UAAU,CA0BZ;AAmED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,GAAG,GAAG,CAiB7D"}

package/dist/core/merging.js

@@ -0,0 +1,124 @@
+/**
+ * Merging utilities for combining outputs from multiple permissions
+ */
+/**
+ * Merge two filter specs using union strategy (more permissive)
+ *
+ * @example
+ * mergeFilters(
+ *   { _id: true, name: true },
+ *   { name: true, email: true }
+ * )
+ * // → { _id: true, name: true, email: true }
+ */
+export function mergeFilters(current, incoming) {
+    if (!current)
+        return incoming || {};
+    if (!incoming)
+        return current;
+    const result = { ...current };
+    for (const [key, value] of Object.entries(incoming)) {
+        if (typeof value === "boolean" && typeof result[key] === "boolean") {
+            // Union: if either says true, it's true
+            result[key] = result[key] || value;
+        }
+        else if (typeof value === "object" && typeof result[key] === "object") {
+            // Recursive merge for nested filters
+            result[key] = mergeFilters(result[key], value);
+        }
+        else if (!(key in result)) {
+            // New key, add it
+            result[key] = value;
+        }
+        else {
+            // Type mismatch or other case: incoming wins
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Merge two values using the "most permissive" strategy, recursing down to
+ * the leaves of nested structures.
+ *
+ * Strategies (applied at each leaf):
+ * - filter / updateFilter / writeFilter: union via mergeFilters
+ * - arrays: concat + dedup (set union)
+ * - numbers: Math.max (largest grant wins)
+ * - booleans: OR (true wins)
+ * - Date: latest wins
+ * - plain objects: recurse field-by-field with the same strategy
+ * - everything else (string, mismatched types, null): incoming wins
+ *
+ * Recursive object handling fixes the previous `{ ...current, ...incoming }`
+ * shortcut which made nested merges depend on insertion order rather than
+ * value semantics.
+ */
+function mergeValue(key, current, incoming) {
+    // Filter-style fields are unions of allowed fields, regardless of nesting depth
+    if (key === "filter" || key === "updateFilter" || key === "writeFilter") {
+        return mergeFilters(current, incoming);
+    }
+    // Arrays: union with dedup
+    if (Array.isArray(current) && Array.isArray(incoming)) {
+        return [...new Set([...current, ...incoming])];
+    }
+    // Numbers: most permissive = largest
+    if (typeof current === "number" && typeof incoming === "number") {
+        return Math.max(current, incoming);
+    }
+    // Booleans: most permissive = OR
+    if (typeof current === "boolean" && typeof incoming === "boolean") {
+        return current || incoming;
+    }
+    // Dates: most permissive = latest
+    if (current instanceof Date && incoming instanceof Date) {
+        return new Date(Math.max(current.getTime(), incoming.getTime()));
+    }
+    // Plain objects: recurse field-by-field
+    if (typeof current === "object" &&
+        typeof incoming === "object" &&
+        current !== null &&
+        incoming !== null &&
+        !Array.isArray(current) &&
+        !Array.isArray(incoming) &&
+        !(current instanceof Date) &&
+        !(incoming instanceof Date)) {
+        const result = { ...current };
+        for (const [k, v] of Object.entries(incoming)) {
+            result[k] = k in current ? mergeValue(k, current[k], v) : v;
+        }
+        return result;
+    }
+    // Type mismatch or primitive: incoming wins
+    return incoming;
+}
+/**
+ * Merge two outputs intelligently based on the key
+ *
+ * @example
+ * mergeOutputs(
+ *   { filter: { _id: true }, data: { _id: 1 } },
+ *   { filter: { name: true }, data: { name: "John" } }
+ * )
+ * // → { filter: { _id: true, name: true }, data: { _id: 1, name: "John" } }
+ */
+export function mergeOutputs(current, incoming) {
+    if (!current)
+        return incoming;
+    if (!incoming)
+        return current;
+    const result = { ...current };
+    for (const [key, value] of Object.entries(incoming)) {
+        if (!(key in result)) {
+            // New key, add it
+            result[key] = value;
+        }
+        else {
+            // Existing key, merge intelligently
+            result[key] = mergeValue(key, result[key], value);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=merging.js.map

package/dist/core/merging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merging.js","sourceRoot":"","sources":["../../core/merging.ts"],"names":[],"mappings":"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"}

package/dist/indirect-aggregation.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Orchestrateur : transforme une liste de grants + ressources indirectes
+ * déclarées en un pipeline d'aggregation MongoDB qui pushe les
+ * contraintes de jointure en DB.
+ *
+ * Algorithme :
+ *  1. Identifier les indirect resources réellement référencées par les
+ *     `with` keys des grants.
+ *  2. Transitivement pull les indirect resources parentes (chaînage).
+ *  3. Trier topologiquement (parent avant enfant) pour que les `$lookup`
+ *     enfants puissent référencer l'alias produit par leur parent.
+ *  4. Émettre un `$lookup` par indirect resource (dédup par `id`).
+ *  5. Émettre un `$match` final OR-isé cross-grant par indirect resource,
+ *     AND-é entre indirect resources distinctes.
+ */
+import type { Grant } from "./types.ts";
+import type { IndirectResource } from "./indirect-resource.ts";
+export type AggregationStage = Record<string, unknown>;
+export type MongoFilter = Record<string, unknown>;
+/**
+ * Construit le pipeline complet à partir du `baseFilter` (les contraintes
+ * find-style classiques agrégées par `aggregateConstraints`) et de la
+ * liste des grants matchés.
+ *
+ * Retourne :
+ *  - `null` quand aucune indirect resource ne contribue effectivement
+ *    de filtre — soit aucun grant ne les référence, soit la sémantique
+ *    "any wins" s'applique (au moins un grant ne référence pas
+ *    l'indirect → le set complet est admissible). Dans ce cas le
+ *    consommateur retombe sur le mode find classique avec `constraints`.
+ *  - Un array de stages sinon (mode aggregation pipeline).
+ *
+ * La sémantique "any wins" est essentielle pour la composition
+ * cross-grant : un admin global avec un grant "open" sur la même perm
+ * doit court-circuiter le filtre que d'autres grants tenteraient
+ * d'imposer via une indirect resource — exactement comme
+ * `aggregateConstraints` traite `undefined` comme "any wins" pour les
+ * constraints find-style.
+ */
+export declare function buildAggregationStages(baseFilter: MongoFilter, grants: readonly Grant[], declaredIndirect: readonly IndirectResource[]): AggregationStage[] | null;
+//# sourceMappingURL=indirect-aggregation.d.ts.map

package/dist/indirect-aggregation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indirect-aggregation.d.ts","sourceRoot":"","sources":["../indirect-aggregation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,WAAW,EACvB,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,gBAAgB,EAAE,SAAS,gBAAgB,EAAE,GAC5C,gBAAgB,EAAE,GAAG,IAAI,CA6E3B"}

package/dist/indirect-aggregation.js

@@ -0,0 +1,185 @@
+/**
+ * Orchestrateur : transforme une liste de grants + ressources indirectes
+ * déclarées en un pipeline d'aggregation MongoDB qui pushe les
+ * contraintes de jointure en DB.
+ *
+ * Algorithme :
+ *  1. Identifier les indirect resources réellement référencées par les
+ *     `with` keys des grants.
+ *  2. Transitivement pull les indirect resources parentes (chaînage).
+ *  3. Trier topologiquement (parent avant enfant) pour que les `$lookup`
+ *     enfants puissent référencer l'alias produit par leur parent.
+ *  4. Émettre un `$lookup` par indirect resource (dédup par `id`).
+ *  5. Émettre un `$match` final OR-isé cross-grant par indirect resource,
+ *     AND-é entre indirect resources distinctes.
+ */
+import { validateSpec } from "./mongo-query.js";
+/**
+ * Construit le pipeline complet à partir du `baseFilter` (les contraintes
+ * find-style classiques agrégées par `aggregateConstraints`) et de la
+ * liste des grants matchés.
+ *
+ * Retourne :
+ *  - `null` quand aucune indirect resource ne contribue effectivement
+ *    de filtre — soit aucun grant ne les référence, soit la sémantique
+ *    "any wins" s'applique (au moins un grant ne référence pas
+ *    l'indirect → le set complet est admissible). Dans ce cas le
+ *    consommateur retombe sur le mode find classique avec `constraints`.
+ *  - Un array de stages sinon (mode aggregation pipeline).
+ *
+ * La sémantique "any wins" est essentielle pour la composition
+ * cross-grant : un admin global avec un grant "open" sur la même perm
+ * doit court-circuiter le filtre que d'autres grants tenteraient
+ * d'imposer via une indirect resource — exactement comme
+ * `aggregateConstraints` traite `undefined` comme "any wins" pour les
+ * constraints find-style.
+ */
+export function buildAggregationStages(baseFilter, grants, declaredIndirect) {
+    const indirectById = new Map();
+    for (const ir of declaredIndirect)
+        indirectById.set(ir.id, ir);
+    // Indirects référencées par AU MOINS un grant.
+    const referenced = new Set();
+    for (const g of grants) {
+        if (!g.with)
+            continue;
+        for (const id of Object.keys(g.with)) {
+            if (indirectById.has(id))
+                referenced.add(id);
+        }
+    }
+    if (referenced.size === 0)
+        return null;
+    // Sémantique "any wins" : une indirect ne contribue de filtre que si
+    // TOUS les grants matchés portent une condition pour elle. Sinon le
+    // grant sans condition ouvre la porte au set complet → on n'a pas le
+    // droit de filtrer sur cette indirect.
+    const effective = new Set();
+    for (const id of referenced) {
+        if (grants.every((g) => g.with?.[id] !== undefined)) {
+            effective.add(id);
+        }
+    }
+    if (effective.size === 0)
+        return null;
+    // Pull in chained parents (transitivement) pour les indirects effectives.
+    const required = new Set(effective);
+    for (const id of effective) {
+        walkDeps(indirectById.get(id), required, indirectById);
+    }
+    // Topological order: parent before child.
+    const ordered = topoSort([...required].map((id) => indirectById.get(id)));
+    const stages = [{ $match: baseFilter }];
+    for (const ir of ordered) {
+        stages.push(buildLookupStage(ir));
+    }
+    // Per-indirect cross-grant OR; cross-indirect AND.
+    const matchClauses = [];
+    for (const irId of effective) {
+        const ir = indirectById.get(irId);
+        const perGrantSpecs = [];
+        for (const g of grants) {
+            const spec = g.with?.[irId];
+            if (!spec)
+                continue;
+            // Security: same whitelist as `match` rule for direct resources —
+            // grants may come from untrusted providers, the spec ends up
+            // pushed to Mongo as-is. Reject dangerous operators ($where,
+            // $expr, $function, etc.) before they reach the DB.
+            validateSpec(spec);
+            perGrantSpecs.push(spec);
+        }
+        // `effective` guarantees all grants have a spec, so perGrantSpecs is
+        // non-empty here.
+        const path = lookupAlias(ir);
+        const elemMatches = perGrantSpecs.map((spec) => ({
+            [path]: { $elemMatch: { ...staticTypeFilter(ir), ...spec } },
+        }));
+        matchClauses.push(elemMatches.length === 1 ? elemMatches[0] : { $or: elemMatches });
+    }
+    if (matchClauses.length > 0) {
+        stages.push({
+            $match: matchClauses.length === 1 ? matchClauses[0] : { $and: matchClauses },
+        });
+    }
+    return stages;
+}
+// ─── Helpers ──────────────────────────────────────────────────────────
+function walkDeps(ir, acc, byId) {
+    if (ir.from.kind === "indirect") {
+        const parent = byId.get(ir.from.id);
+        if (parent && !acc.has(parent.id)) {
+            acc.add(parent.id);
+            walkDeps(parent, acc, byId);
+        }
+    }
+}
+function topoSort(items) {
+    const sorted = [];
+    const remaining = new Set(items.map((i) => i.id));
+    const byId = new Map(items.map((i) => [i.id, i]));
+    while (remaining.size > 0) {
+        let progressed = false;
+        for (const id of [...remaining]) {
+            const ir = byId.get(id);
+            const parentId = ir.from.kind === "indirect" ? ir.from.id : null;
+            const parentInSet = parentId !== null && remaining.has(parentId);
+            if (!parentInSet) {
+                sorted.push(ir);
+                remaining.delete(id);
+                progressed = true;
+            }
+        }
+        if (!progressed) {
+            throw new Error("Cycle detected in indirect resource chain");
+        }
+    }
+    return sorted;
+}
+function lookupAlias(ir) {
+    return `_${ir.id}`;
+}
+function staticTypeFilter(ir) {
+    return ir.to?._type ? { _type: ir.to._type } : {};
+}
+function buildLookupStage(ir) {
+    const isChained = ir.from.kind === "indirect";
+    // `<self>` est un placeholder neutre — le consommateur (mongodbee
+    // adapter) substitue le nom de la collection courante côté driver.
+    const fromCollection = ir.on.foreignCollection ?? "<self>";
+    const alias = lookupAlias(ir);
+    if (!isChained) {
+        const subPipeline = ir.to?._type
+            ? [{ $match: { _type: ir.to._type } }]
+            : undefined;
+        return {
+            $lookup: {
+                from: fromCollection,
+                localField: ir.on.localField,
+                foreignField: ir.on.foreignField,
+                ...(subPipeline && { pipeline: subPipeline }),
+                as: alias,
+            },
+        };
+    }
+    // Chained: lookup uses $let + $expr to dereference the parent alias.
+    const parentAlias = lookupAlias(ir.from);
+    return {
+        $lookup: {
+            from: fromCollection,
+            let: {
+                src: { $arrayElemAt: [`$${parentAlias}.${ir.on.localField}`, 0] },
+            },
+            pipeline: [
+                {
+                    $match: {
+                        $expr: { $eq: [`$${ir.on.foreignField}`, "$$src"] },
+                        ...(ir.to?._type && { _type: ir.to._type }),
+                    },
+                },
+            ],
+            as: alias,
+        },
+    };
+}
+//# sourceMappingURL=indirect-aggregation.js.map

package/dist/indirect-aggregation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indirect-aggregation.js","sourceRoot":"","sources":["../indirect-aggregation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAuB,EACvB,MAAwB,EACxB,gBAA6C;IAE7C,MAAM,YAAY,GAAG,IAAI,GAAG,EAA4B,CAAC;IACzD,KAAK,MAAM,EAAE,IAAI,gBAAgB;QAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAE/D,+CAA+C;IAC/C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,CAAC,IAAI;YAAE,SAAS;QACtB,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,IAAI,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,qEAAqE;IACrE,oEAAoE;IACpE,qEAAqE;IACrE,uCAAuC;IACvC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,EAAE,CAAC;YACpD,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtC,0EAA0E;IAC1E,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,SAAS,CAAC,CAAC;IAC5C,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAE,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;IAC1D,CAAC;IAED,0CAA0C;IAC1C,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC,CAAC,CAAC;IAE3E,MAAM,MAAM,GAAuB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IAC5D,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC;IACpC,CAAC;IAED,mDAAmD;IACnD,MAAM,YAAY,GAAkB,EAAE,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,MAAM,EAAE,GAAG,YAAY,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;QACnC,MAAM,aAAa,GAAkB,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;YACvB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAA4B,CAAC;YACvD,IAAI,CAAC,IAAI;gBAAE,SAAS;YACpB,kEAAkE;YAClE,6DAA6D;YAC7D,6DAA6D;YAC7D,oDAAoD;YACpD,YAAY,CAAC,IAAI,CAAC,CAAC;YACnB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,CAAC;QACD,qEAAqE;QACrE,kBAAkB;QAElB,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAC7B,MAAM,WAAW,GAAkB,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC9D,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,EAAE,GAAG,gBAAgB,CAAC,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE;SAC7D,CAAC,CAAC,CAAC;QACJ,YAAY,CAAC,IAAI,CACf,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,CACjE,CAAC;IACJ,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,CAAC,IAAI,CAAC;YACV,MAAM,EACJ,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE;SACvE,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,yEAAyE;AAEzE,SAAS,QAAQ,CACf,EAAoB,EACpB,GAAgB,EAChB,IAAmC;IAEnC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;YAClC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACnB,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,KAAyB;IACzC,MAAM,MAAM,GAAuB,EAAE,CAAC;IACtC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAU,CAAC,CAAC,CAAC;IAE3D,OAAO,SAAS,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QAC1B,IAAI,UAAU,GAAG,KAAK,CAAC;QACvB,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC;YAChC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;YACjE,MAAM,WAAW,GAAG,QAAQ,KAAK,IAAI,IAAI,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACjE,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBAChB,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACrB,UAAU,GAAG,IAAI,CAAC;YACpB,CAAC;QACH,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,WAAW,CAAC,EAAoB;IACvC,OAAO,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;AACrB,CAAC;AAED,SAAS,gBAAgB,CAAC,EAAoB;IAC5C,OAAO,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACpD,CAAC;AAED,SAAS,gBAAgB,CAAC,EAAoB;IAC5C,MAAM,SAAS,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC;IAC9C,kEAAkE;IAClE,mEAAmE;IACnE,MAAM,cAAc,GAAG,EAAE,CAAC,EAAE,CAAC,iBAAiB,IAAI,QAAQ,CAAC;IAC3D,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAE9B,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,WAAW,GAAG,EAAE,CAAC,EAAE,EAAE,KAAK;YAC9B,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC;YACtC,CAAC,CAAC,SAAS,CAAC;QACd,OAAO;YACL,OAAO,EAAE;gBACP,IAAI,EAAE,cAAc;gBACpB,UAAU,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU;gBAC5B,YAAY,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY;gBAChC,GAAG,CAAC,WAAW,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;gBAC7C,EAAE,EAAE,KAAK;aACV;SACF,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,MAAM,WAAW,GAAG,WAAW,CAAC,EAAE,CAAC,IAAwB,CAAC,CAAC;IAC7D,OAAO;QACL,OAAO,EAAE;YACP,IAAI,EAAE,cAAc;YACpB,GAAG,EAAE;gBACH,GAAG,EAAE,EAAE,YAAY,EAAE,CAAC,IAAI,WAAW,IAAI,EAAE,CAAC,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,EAAE;aAClE;YACD,QAAQ,EAAE;gBACR;oBACE,MAAM,EAAE;wBACN,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,YAAY,EAAE,EAAE,OAAO,CAAC,EAAE;wBACnD,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;qBAC5C;iBACF;aACF;YACD,EAAE,EAAE,KAAK;SACV;KACF,CAAC;AACJ,CAAC"}

package/dist/indirect-resource.d.ts

@@ -0,0 +1,126 @@
+/**
+ * `indirectResource` — déclaration d'une ressource atteignable via une
+ * jointure (DB-pushdown via aggregation pipeline). Pendant de `resource()`
+ * pour les cas où la donnée filtrante vit dans une autre collection (ou
+ * dans la même via un foreign field).
+ *
+ * Cas d'usage typique :
+ *  - lister les `participant` qui ont une `org_membership` matching org=X
+ *  - lister les `participant` dont l'`user` lié appartient à entreprise=Y
+ *  - chaîner sur plusieurs niveaux (`participant → user → entreprise_member`)
+ *
+ * La méthode `.match()` retourne une `Rule` sentinelle (kind="indirect-match")
+ * que l'orchestrateur de `system.ts` détecte pour générer le pipeline
+ * d'aggregation correspondant — voir `indirect-aggregation.ts`.
+ *
+ * À la différence des ressources directes :
+ *  - Pas de `fetch` ni de `dedupKey` : aucune donnée chargée à l'évaluation
+ *  - Pas de rule `filter`/`include`/`require*` — uniquement `match` pour
+ *    contribuer une contrainte au pipeline généré.
+ */
+import type { FetchCtx, Rule } from "./types.ts";
+/**
+ * Identité de jointure entre une ressource source et la cible jointe.
+ *
+ * - `localField` : nom du champ sur le doc source.
+ * - `foreignField` : nom du champ sur le doc cible.
+ * - `foreignCollection` : si absent, jointure dans la même collection
+ *   (self-lookup) — utile pour les multi-collections mongodbee où le
+ *   discriminator de type vit dans un champ `_type`. Si présent,
+ *   jointure vers une collection externe (équivalent `externalLookup`).
+ */
+export interface IndirectResourceJoin {
+    readonly localField: string;
+    readonly foreignField: string;
+    readonly foreignCollection?: string;
+}
+/**
+ * Ressource indirecte. Identifie une cible joignable et expose des rules
+ * pour contribuer aux contraintes du pipeline généré.
+ *
+ * - `from` accepte une `Resource` directe (l'objet retourné par
+ *   `resource({...})`, sans champ `kind` — on le marque "direct" par
+ *   défaut) OU une autre `IndirectResource` (qui a `kind: "indirect"`)
+ *   pour chaîner sur plusieurs niveaux.
+ * - `to._type` discrimine le type cible quand la jointure vise une
+ *   collection multi-types (mongodbee). **Barrière de sécurité** : un
+ *   grant ne peut pas adresser un autre `_type` via le `with`.
+ * - `cardinality` indique si on attend N résultats (`many`) ou 1
+ *   (`one`) — utilisé pour optimiser le pipeline généré ($unwind potentiel).
+ */
+export interface IndirectResource {
+    readonly id: string;
+    /** Marker discriminant les ressources directes des indirectes. */
+    readonly kind: "indirect";
+    /** Normalisé au factory à partir du `from` du spec (Resource → direct). */
+    readonly from: {
+        readonly id: string;
+        readonly kind: "direct" | "indirect";
+    };
+    readonly on: IndirectResourceJoin;
+    readonly to?: {
+        readonly _type?: string;
+    };
+    readonly cardinality: "one" | "many";
+    /**
+     * Fetcher opt-in pour le mode concrete (per-doc check). Quand défini,
+     * la rule `match()` évalue effectivement la condition en mode concrete
+     * (au lieu d'être une sentinelle no-op). Reçoit la valeur de la source
+     * (déjà fetchée par l'engine) et retourne le tableau de docs joints.
+     *
+     * Toujours retourner un array, même pour `cardinality: "one"` — la
+     * sémantique du match utilise `$elemMatch`-like (au moins un match).
+     *
+     * Si absent, l'indirect reste sentinelle (legacy) : ne contribue qu'au
+     * pipeline en cap-mode.
+     */
+    readonly fetcher?: (sourceDoc: unknown, ctx: FetchCtx) => readonly unknown[] | Promise<readonly unknown[]>;
+    /** Calcule la cache key pour un target (cf. `Resource.cacheKeyForTarget`). */
+    cacheKeyForTarget(target: readonly unknown[]): string;
+    /**
+     * Crée une rule qui déclare l'utilisation de cette resource indirecte
+     * dans la permission.
+     *
+     * - En cap-mode : sentinelle, détectée par `system.ts` qui collecte
+     *   l'indirect pour générer le pipeline (cf. `buildAggregationStages`).
+     * - En concrete-mode + `fetcher` défini : fetche les docs joints et
+     *   évalue `grant.with[id]` contre eux (au moins un doc match).
+     *   Sans `fetcher`, sentinelle aussi (no-op).
+     */
+    match(): Rule;
+}
+interface IndirectResourceSpec {
+    readonly id: string;
+    /**
+     * `Resource` (sans champ `kind`) ou `IndirectResource` (avec
+     * `kind: "indirect"`). Le factory normalise en stockant un
+     * `{ id, kind }` minimal pour la résolution du graphe.
+     */
+    readonly from: {
+        readonly id: string;
+        readonly kind?: "direct" | "indirect";
+    };
+    readonly on: IndirectResourceJoin;
+    readonly to?: {
+        readonly _type?: string;
+    };
+    readonly cardinality: "one" | "many";
+    readonly fetch?: (sourceDoc: unknown, ctx: FetchCtx) => readonly unknown[] | Promise<readonly unknown[]>;
+}
+/**
+ * Sentinelle dans `Rule.descriptor` pour qu'`system.ts` reconnaisse
+ * cette rule comme "indirect" et collecte la resource correspondante.
+ *
+ * Le champ est typé `unknown` côté `RuleDescriptor` parce que
+ * `[extra: string]: unknown` est la signature catch-all des descriptors —
+ * on cast à l'extraction.
+ */
+export declare const INDIRECT_RULE_KIND = "indirect-match";
+export declare function indirectResource(spec: IndirectResourceSpec): IndirectResource;
+/**
+ * Extraction utilitaire pour `system.ts` : récupère la `IndirectResource`
+ * portée par une rule sentinelle, ou `null` si la rule n'en est pas une.
+ */
+export declare function extractIndirectResource(rule: Rule): IndirectResource | null;
+export {};
+//# sourceMappingURL=indirect-resource.d.ts.map

package/dist/indirect-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indirect-resource.d.ts","sourceRoot":"","sources":["../indirect-resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAA;KAAE,CAAC;IAC7E,QAAQ,CAAC,EAAE,EAAE,oBAAoB,CAAC;IAClC,QAAQ,CAAC,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,KAAK,GAAG,MAAM,CAAC;IACrC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CACjB,SAAS,EAAE,OAAO,EAClB,GAAG,EAAE,QAAQ,KACV,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;IACtD,8EAA8E;IAC9E,iBAAiB,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAAC;IACtD;;;;;;;;;OASG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAA;KAAE,CAAC;IAC9E,QAAQ,CAAC,EAAE,EAAE,oBAAoB,CAAC;IAClC,QAAQ,CAAC,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,KAAK,GAAG,MAAM,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,CACf,SAAS,EAAE,OAAO,EAClB,GAAG,EAAE,QAAQ,KACV,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;CACvD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,gBAAgB,CAuE7E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,gBAAgB,GAAG,IAAI,CAK3E"}