@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

package/dist/esm/security/authorizations/role-conferral.backend.utils.js

@@ -0,0 +1,137 @@
+/**
+ * # Role conferral — ONE derivation of "which role keys confer authority X, in scope S"
+ *
+ * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — the shared derivation every authority floor
+ * measures its protected population with.
+ *
+ * ## The role-key vocabulary is genuinely OPEN, and closing it would be a defect
+ *
+ * Recorded here because the opposite is the obvious reading and was proposed as a finding: *"a
+ * membership's `roles` field is a free string, so an application-scope role value is storable in an
+ * organisation-scoped membership row."* Both halves of that are true. The conclusion — close the
+ * vocabulary — is not, and the evidence is in the framework's own contract:
+ *
+ *  - `RolesSchema` is `union([enum(CORE_APP_ROLES), enum(CORE_ORG_ROLES), z.string().min(1)])`, and
+ *    the third arm is the SUPPORTED feature, not an oversight: an application registers its own role
+ *    keys at startup through `initializeRolesWithCustom`, and `RolesConfigurationSchema` is a
+ *    `z.record(z.string(), RoleDefinitionSchema)`. A closed enum would delete custom roles.
+ *  - So "is this string a valid role key?" has no static answer. It has a RUNTIME answer, per
+ *    application, per scope — which is exactly what the role tables are.
+ *
+ * ## What IS closed, and where its one source lives
+ *
+ * The **scope partition**. Every role key belongs to exactly one `relatedPrimaryScope`, and
+ * `AuthorizationsBackendService.getRoleHierarchy(roleKey, scope)` is the single runtime source of
+ * that fact: it selects the APPLICATION table or the ORGANIZATIONS table and never consults both. A
+ * key unknown in the passed scope expands to the EMPTY chain, which is what makes an app-scope
+ * string written into an org-scoped membership row confer nothing — the safety comes from
+ * RESOLUTION, not from the field's type, and it must stay that way.
+ *
+ * ## What was duplicated, and is not any more
+ *
+ * The derivation BUILT ON that partition. `resolveSuperAdminConferringRoles` and
+ * `resolveOrganizationOwnerConferringRoles` were the same eleven lines twice, differing only in
+ * (table, scope, anchor) — each carrying its own paragraph re-establishing the partition argument
+ * above, in its own words, for its own reader. That is the shape `CLAUDE.md` asks to have one named
+ * runtime source for: not the role STRINGS, which cannot be closed, but the QUESTION asked of them.
+ *
+ * Two floors measure populations with it today ({@link resolveSuperAdminConferringRoles},
+ * {@link resolveOrganizationOwnerConferringRoles}); a third scope's floor is one call, not another
+ * copy.
+ *
+ * ## Why this module ships with NO test file of its own
+ *
+ * A direct suite was written and then DELETED, because measuring it showed every property it
+ * asserted was already covered — and its stated rationale was false. It claimed the floor suites
+ * "stub `getRoleHierarchy` as a function that IGNORES its scope"; both actually stub
+ * `(role, scope) => scope === <their own scope> ? table[role] : []`, and both tables already contain
+ * a CUSTOM, non-enum role key (`CUSTOM_PLATFORM_OWNER`, `CUSTOM_TENANT_PRINCIPAL`) reaching the
+ * anchor — so the open-vocabulary property is pinned too.
+ *
+ * Proven rather than assumed: binding the super-admin floor to `ORGANIZATIONS` scope instead of
+ * `APPLICATION` — the one regression the extraction newly makes possible — reddens THREE tests in
+ * `super-admin-floor.backend.utils.test.ts` on its own. The bindings are the coverage.
+ *
+ * So do not add a suite here to "cover the new module". If a THIRD binding appears, pin it in its
+ * own floor's suite the way these two are; that is where a wrong `scope` argument is observable.
+ */
+/**
+ * Every role key in `declaredRoleKeys` whose `inheritFrom` chain reaches `anchorRole`, within
+ * `scope` — i.e. every role whose holder passes a gate that requires `anchorRole`.
+ *
+ * ## Why the derivation is shaped this way
+ *
+ * **It mirrors the authorization layer's own test.** `authorize` admits a caller when
+ * `getRoleHierarchy(heldRole, scope).includes(requiredRole)`. Deriving the set the same way is what
+ * keeps a floor counting exactly the principals the gates would let through; an independently
+ * written membership test is how the two drift, and a floor that measures a different population
+ * than the gate protects is worse than no floor — it reports a healthy count for an unprotected
+ * scope.
+ *
+ * **The anchor is seeded unconditionally rather than discovered by the walk.** If an application's
+ * role table somehow omitted the anchor key, `roleHierarchyResolver` would return an empty chain for
+ * every key, the conferring set would be empty, and the floor would then measure a population that
+ * is empty BY CONSTRUCTION — refusing every removal forever while protecting nothing.
+ *
+ * **`scope` is passed to the resolver, never assumed.** That single argument is what carries the
+ * closed half of the vocabulary (see this module's header): the caller states which table the keys
+ * are to be read against, and a key belonging to the other table expands to nothing. A caller that
+ * passed the wrong scope would silently get `[anchorRole]` — the seed — which is the fail-CLOSED
+ * direction for a floor (it under-counts the protected population and so refuses more, never less).
+ *
+ * @param declaredRoleKeys the keys of the LIVE role table for `scope`. Live, because the effective
+ *   hierarchy is application-configurable and a statically-derived set would silently disagree with
+ *   the roles the authorization layer actually honours.
+ */
+export function resolveRolesConferringAnchor(params) {
+    const conferringRoles = new Set([params.anchorRole]);
+    for (const roleKey of params.declaredRoleKeys) {
+        if (roleConfersAuthority({
+            heldRoleKey: roleKey,
+            requiredRoleKey: params.anchorRole,
+            scope: params.scope,
+            roleHierarchyResolver: params.roleHierarchyResolver,
+        })) {
+            conferringRoles.add(roleKey);
+        }
+    }
+    return [...conferringRoles];
+}
+/**
+ * Does holding `heldRoleKey` in `scope` satisfy a gate that requires `requiredRoleKey`?
+ *
+ * ## The one place the scope partition is consulted
+ *
+ * This is the ATOM. Everything this module's header argues about the vocabulary lands here: the role
+ * key is an open string, the SCOPE partition is what is closed, and the safety comes from RESOLUTION
+ * rather than from the field's type — a key unknown in `scope` expands to the EMPTY chain and
+ * therefore confers nothing, which is what makes an application-scope string written into an
+ * organisation-scoped membership row harmless. Every copy of these two lines is another place that
+ * argument can quietly stop being true, and the only way to notice would be a security test nobody
+ * wrote.
+ *
+ * ## Two names for one parameter, deliberately
+ *
+ * A FLOOR calls the target an ANCHOR — it is measuring the population that reaches an authority. A
+ * GATE calls it the REQUIRED ROLE — it is deciding one caller. Same question of the same table, so
+ * the parameter is named neutrally here rather than picked from one caller's vocabulary.
+ *
+ * ## What this does NOT do, and must not grow into
+ *
+ * It answers about ONE held key. The quantifier belongs to the caller, and the callers genuinely
+ * differ: `resolveRolesConferringAnchor` maps it over the declared role TABLE to produce a SET, so a
+ * floor can measure a protected population; an admission maps it over the roles the CALLER holds to
+ * produce a BOOLEAN. Those are two different questions and collapsing them into one helper that
+ * "does both" is the convenience-over-semantics failure `.claude/rules/design-philosophy.md` refuses.
+ * The distinction is kept; only the shared atom is named — which is what that rule asks for when it
+ * says to add helpers for controlled merging instead of collapsing a distinction.
+ *
+ * @param heldRoleKey a role key a principal holds, or a key declared in the role table.
+ * @param requiredRoleKey the authority being tested for — a floor's anchor, or a gate's required role.
+ * @param scope which role table `heldRoleKey` is to be read against. Passing the wrong one resolves
+ *   to the empty chain and answers `false`, which is the fail-CLOSED direction for both callers.
+ */
+export function roleConfersAuthority(params) {
+    return params.roleHierarchyResolver(params.heldRoleKey, params.scope).includes(params.requiredRoleKey);
+}
+//# sourceMappingURL=role-conferral.backend.utils.js.map

package/dist/esm/security/authorizations/role-conferral.backend.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-conferral.backend.utils.js","sourceRoot":"","sources":["../../../../src/security/authorizations/role-conferral.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAK5C;IACC,MAAM,eAAe,GAAG,IAAI,GAAG,CAAS,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAE7D,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC9C,IAAI,oBAAoB,CAAC;YACvB,WAAW,EAAE,OAAO;YACpB,eAAe,EAAE,MAAM,CAAC,UAAU;YAClC,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,qBAAqB,EAAE,MAAM,CAAC,qBAAqB;SACpD,CAAC,EAAE,CAAC;YACH,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAKpC;IACC,OAAO,MAAM,CAAC,qBAAqB,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;AACzG,CAAC","sourcesContent":["/**\n * # Role conferral — ONE derivation of \"which role keys confer authority X, in scope S\"\n *\n * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — the shared derivation every authority floor\n * measures its protected population with.\n *\n * ## The role-key vocabulary is genuinely OPEN, and closing it would be a defect\n *\n * Recorded here because the opposite is the obvious reading and was proposed as a finding: *\"a\n * membership's `roles` field is a free string, so an application-scope role value is storable in an\n * organisation-scoped membership row.\"* Both halves of that are true. The conclusion — close the\n * vocabulary — is not, and the evidence is in the framework's own contract:\n *\n *  - `RolesSchema` is `union([enum(CORE_APP_ROLES), enum(CORE_ORG_ROLES), z.string().min(1)])`, and\n *    the third arm is the SUPPORTED feature, not an oversight: an application registers its own role\n *    keys at startup through `initializeRolesWithCustom`, and `RolesConfigurationSchema` is a\n *    `z.record(z.string(), RoleDefinitionSchema)`. A closed enum would delete custom roles.\n *  - So \"is this string a valid role key?\" has no static answer. It has a RUNTIME answer, per\n *    application, per scope — which is exactly what the role tables are.\n *\n * ## What IS closed, and where its one source lives\n *\n * The **scope partition**. Every role key belongs to exactly one `relatedPrimaryScope`, and\n * `AuthorizationsBackendService.getRoleHierarchy(roleKey, scope)` is the single runtime source of\n * that fact: it selects the APPLICATION table or the ORGANIZATIONS table and never consults both. A\n * key unknown in the passed scope expands to the EMPTY chain, which is what makes an app-scope\n * string written into an org-scoped membership row confer nothing — the safety comes from\n * RESOLUTION, not from the field's type, and it must stay that way.\n *\n * ## What was duplicated, and is not any more\n *\n * The derivation BUILT ON that partition. `resolveSuperAdminConferringRoles` and\n * `resolveOrganizationOwnerConferringRoles` were the same eleven lines twice, differing only in\n * (table, scope, anchor) — each carrying its own paragraph re-establishing the partition argument\n * above, in its own words, for its own reader. That is the shape `CLAUDE.md` asks to have one named\n * runtime source for: not the role STRINGS, which cannot be closed, but the QUESTION asked of them.\n *\n * Two floors measure populations with it today ({@link resolveSuperAdminConferringRoles},\n * {@link resolveOrganizationOwnerConferringRoles}); a third scope's floor is one call, not another\n * copy.\n *\n * ## Why this module ships with NO test file of its own\n *\n * A direct suite was written and then DELETED, because measuring it showed every property it\n * asserted was already covered — and its stated rationale was false. It claimed the floor suites\n * \"stub `getRoleHierarchy` as a function that IGNORES its scope\"; both actually stub\n * `(role, scope) => scope === <their own scope> ? table[role] : []`, and both tables already contain\n * a CUSTOM, non-enum role key (`CUSTOM_PLATFORM_OWNER`, `CUSTOM_TENANT_PRINCIPAL`) reaching the\n * anchor — so the open-vocabulary property is pinned too.\n *\n * Proven rather than assumed: binding the super-admin floor to `ORGANIZATIONS` scope instead of\n * `APPLICATION` — the one regression the extraction newly makes possible — reddens THREE tests in\n * `super-admin-floor.backend.utils.test.ts` on its own. The bindings are the coverage.\n *\n * So do not add a suite here to \"cover the new module\". If a THIRD binding appears, pin it in its\n * own floor's suite the way these two are; that is where a wrong `scope` argument is observable.\n */\n\nimport type { ResourcePrimaryScope } from '@wildo-ai/saas-models';\n\n/**\n * Every role key in `declaredRoleKeys` whose `inheritFrom` chain reaches `anchorRole`, within\n * `scope` — i.e. every role whose holder passes a gate that requires `anchorRole`.\n *\n * ## Why the derivation is shaped this way\n *\n * **It mirrors the authorization layer's own test.** `authorize` admits a caller when\n * `getRoleHierarchy(heldRole, scope).includes(requiredRole)`. Deriving the set the same way is what\n * keeps a floor counting exactly the principals the gates would let through; an independently\n * written membership test is how the two drift, and a floor that measures a different population\n * than the gate protects is worse than no floor — it reports a healthy count for an unprotected\n * scope.\n *\n * **The anchor is seeded unconditionally rather than discovered by the walk.** If an application's\n * role table somehow omitted the anchor key, `roleHierarchyResolver` would return an empty chain for\n * every key, the conferring set would be empty, and the floor would then measure a population that\n * is empty BY CONSTRUCTION — refusing every removal forever while protecting nothing.\n *\n * **`scope` is passed to the resolver, never assumed.** That single argument is what carries the\n * closed half of the vocabulary (see this module's header): the caller states which table the keys\n * are to be read against, and a key belonging to the other table expands to nothing. A caller that\n * passed the wrong scope would silently get `[anchorRole]` — the seed — which is the fail-CLOSED\n * direction for a floor (it under-counts the protected population and so refuses more, never less).\n *\n * @param declaredRoleKeys the keys of the LIVE role table for `scope`. Live, because the effective\n *   hierarchy is application-configurable and a statically-derived set would silently disagree with\n *   the roles the authorization layer actually honours.\n */\nexport function resolveRolesConferringAnchor(params: {\n  readonly anchorRole: string;\n  readonly scope: ResourcePrimaryScope;\n  readonly declaredRoleKeys: readonly string[];\n  readonly roleHierarchyResolver: (roleKey: string, scope: ResourcePrimaryScope) => string[];\n}): string[] {\n  const conferringRoles = new Set<string>([params.anchorRole]);\n\n  for (const roleKey of params.declaredRoleKeys) {\n    if (roleConfersAuthority({\n      heldRoleKey: roleKey,\n      requiredRoleKey: params.anchorRole,\n      scope: params.scope,\n      roleHierarchyResolver: params.roleHierarchyResolver,\n    })) {\n      conferringRoles.add(roleKey);\n    }\n  }\n\n  return [...conferringRoles];\n}\n\n/**\n * Does holding `heldRoleKey` in `scope` satisfy a gate that requires `requiredRoleKey`?\n *\n * ## The one place the scope partition is consulted\n *\n * This is the ATOM. Everything this module's header argues about the vocabulary lands here: the role\n * key is an open string, the SCOPE partition is what is closed, and the safety comes from RESOLUTION\n * rather than from the field's type — a key unknown in `scope` expands to the EMPTY chain and\n * therefore confers nothing, which is what makes an application-scope string written into an\n * organisation-scoped membership row harmless. Every copy of these two lines is another place that\n * argument can quietly stop being true, and the only way to notice would be a security test nobody\n * wrote.\n *\n * ## Two names for one parameter, deliberately\n *\n * A FLOOR calls the target an ANCHOR — it is measuring the population that reaches an authority. A\n * GATE calls it the REQUIRED ROLE — it is deciding one caller. Same question of the same table, so\n * the parameter is named neutrally here rather than picked from one caller's vocabulary.\n *\n * ## What this does NOT do, and must not grow into\n *\n * It answers about ONE held key. The quantifier belongs to the caller, and the callers genuinely\n * differ: `resolveRolesConferringAnchor` maps it over the declared role TABLE to produce a SET, so a\n * floor can measure a protected population; an admission maps it over the roles the CALLER holds to\n * produce a BOOLEAN. Those are two different questions and collapsing them into one helper that\n * \"does both\" is the convenience-over-semantics failure `.claude/rules/design-philosophy.md` refuses.\n * The distinction is kept; only the shared atom is named — which is what that rule asks for when it\n * says to add helpers for controlled merging instead of collapsing a distinction.\n *\n * @param heldRoleKey a role key a principal holds, or a key declared in the role table.\n * @param requiredRoleKey the authority being tested for — a floor's anchor, or a gate's required role.\n * @param scope which role table `heldRoleKey` is to be read against. Passing the wrong one resolves\n *   to the empty chain and answers `false`, which is the fail-CLOSED direction for both callers.\n */\nexport function roleConfersAuthority(params: {\n  readonly heldRoleKey: string;\n  readonly requiredRoleKey: string;\n  readonly scope: ResourcePrimaryScope;\n  readonly roleHierarchyResolver: (roleKey: string, scope: ResourcePrimaryScope) => string[];\n}): boolean {\n  return params.roleHierarchyResolver(params.heldRoleKey, params.scope).includes(params.requiredRoleKey);\n}\n"]}

package/dist/esm/security/authorizations/scope-root-collection-confinement.backend.d.ts

@@ -50,9 +50,142 @@
  * tenant, not over the tenant row, and every org-wide gate in the authorization service filters
  * those out; counting one here would let a unit member enumerate the tenant they are narrowed inside.
  */
-import { CoreResourceOperation, ExecutionContext_ExecutionType } from '@wildo-ai/saas-models';
+import { CoreResourceOperation, ExecutionContext_ExecutionType, ResourcePrimaryScope } from '@wildo-ai/saas-models';
 /** The queryable key a scope-root row is addressed by. Named once so no call site can typo it. */
 export declare const SCOPE_ROOT_CONFINEMENT_FIELD = "_id";
+/**
+ * WHY a given scope root is, or is not, row-confined.
+ *
+ * A named vocabulary rather than four prose comments, because "which roots owe confinement" is a
+ * closed semantic question and had been answered four times, in four files, in four different words
+ * — the shape `CLAUDE.md` asks to have one runtime source for. It also makes the answer READABLE
+ * from the authority itself instead of from the resource configs it governs.
+ *
+ * THE RULE THAT DECIDES MEMBERSHIP, stated once so the next scope is not settled by taste:
+ *
+ * > **A scope root owes row confinement exactly when a caller's authority for that scope names ONE
+ * > INSTANCE of it, while the collection holds every instance.**
+ *
+ * That is a fact about ROLE ENTRIES, and it is measurable rather than a judgement: only an
+ * `ORGANIZATIONS` entry carries a `relatedResourceId` selecting a particular scope instance. An
+ * `APPLICATION` entry names the deployment (there is one), and `USER_SELF` / `ANONYMOUS` have no
+ * role entries at all — their instance comes from `initiatorIds`, which the request supplies about
+ * ITSELF and which therefore cannot be an authority set. So on today's vocabulary exactly one root
+ * owes it, and that is a derivation, not a denominator someone chose.
+ */
+export declare enum ScopeRootConfinementDisposition {
+    /**
+     * Confined to the tenants the caller holds an organization-WIDE role entry for. The only
+     * disposition that produces a predicate.
+     */
+    CONFINED_TO_CALLER_ORGANIZATIONS = "CONFINED_TO_CALLER_ORGANIZATIONS",
+    /**
+     * The root's HTTP collection surface is the APPLICATION-tier administrative directory, and the
+     * caller's authority for it is application-wide — so "all rows" is not wider than the authority
+     * that reached them. Narrower callers reach the same rows only through a route that confines them
+     * by a DIFFERENT mechanism (`users` is enumerated per tenant through
+     * `/organizations/{organizationId}/users/search`, whose junction filter intersects `_id` with the
+     * tenant's membership; the global routes stay admin-gated).
+     *
+     * ## ⚠️ The ELEVATION asymmetry this disposition carries, stated so nobody has to re-derive it
+     *
+     * Read against the per-row door, the sentence above is the whole of the control and it is a
+     * statement about a STANDING role. Measured 2026-09-09:
+     *
+     * | | per-row crossing | this directory read |
+     * |---|---|---|
+     * | declared per variant | `admitsCrossTenantPlatformAdministration` | nothing |
+     * | elevation required | a usable, time-bound, justified `platformAccessGrants` row | none |
+     * | role tier | `APP_ADMIN_SUPER_ADMIN` | `APP_ADMIN_VIEWER` (`users`), `ORG_MEMBER` (`applications` LIST) |
+     * | evidence | `CROSS_TENANT_ADMINISTRATIVE_ACCESS`, naming the authorizing grant | `PLATFORM_DIRECTORY_ACCESS`, naming no elevation |
+     *
+     * That WAS the correct reading of the finding, and it was worse than "not symmetric": the control
+     * was inverted.
+     *
+     * ## CLOSED 2026-09-09 — the table above is HISTORY, not current state
+     *
+     * The "elevation required" cell now reads *a usable, second-signed `applicationAccessGrants` row*
+     * on both halves. Do not reason from the table as if it still described the system; it is kept
+     * because the inversion is the argument for the mechanism that replaced it.
+     *
+     * `hasUsablePlatformAccessGrant` still needs a TARGET tenant and still answers `false` on an empty
+     * one, so the TENANT grant remains structurally inapplicable to a collection call — that half was
+     * always a fact about the mechanism rather than a proof that prevention was impossible, and it is
+     * what made a second resource necessary rather than a field.
+     *
+     * **`CoreResourceType.APPLICATION_ACCESS_GRANTS` is that second resource**, approved under a
+     * TWO-PERSON RULE: the signature must come from a platform administrator who is NOT the requester,
+     * enforced in the implementation and hidden by the operation's `enabledCondition`. Customer
+     * approval (Lockbox, Access Approval) is the industry ceiling and is structurally unavailable —
+     * there is no single customer to ask — so a second signature is the strongest control that exists
+     * for this act; `.claude/rules/administrative-continuity-floors.md` says so in as many words.
+     *
+     * The admission is `readRequiresApplicationWideGrant`, which COMPOSES this authority's own
+     * `isUnconfinedScopeRootDirectoryRead` with `isObservedCrossTenantRead` rather than asking a third
+     * question, so the gate and the trail cannot disagree about which reads are in scope. Auto-approval
+     * was rejected: it is the tenant grant's default posture only because a tenant can opt in above it,
+     * and there is no such party here.
+     *
+     * A related choice is already RECORDED and should not be quietly reversed: a browsable platform
+     * tenant directory was considered and rejected, on the reasoning that industry practice (Customer
+     * Lockbox, Access Approval) has the tenant id arrive out of band with the customer's support
+     * ticket. It is UNCHANGED by the closure above and is now load-bearing in a second way: with the
+     * directory read itself elevated, an operator who wanted to browse tenants would need an
+     * application-wide grant and a second signature to do it, which is the outcome that decision
+     * wanted anyway.
+     *
+     * ## What was rejected on MEASUREMENT rather than on cost
+     *
+     * Confining this read to tenants the caller holds a grant for is not merely undesirable here, it
+     * is structurally unavailable for the widest case: `users` rows carry NO tenant column at all
+     * (membership lives in `organizationMembers`), so there is nothing for a tenant predicate to bind
+     * to. Any such confinement would be a junction query that also removes the tenant-less user — the
+     * person who has just signed up and belongs to nobody — from the only surface that can find them.
+     */
+    UNCONFINED_APPLICATION_TIER_DIRECTORY = "UNCONFINED_APPLICATION_TIER_DIRECTORY",
+    /**
+     * ONE DATABASE PER APPLICATION. "An application's organizations live in that application's own
+     * database" — so this collection holds this deployment's own row and a caller can only ever see
+     * the application they are already using. Safe by ARCHITECTURE, not by a predicate, which is why
+     * it is spelled out: the default LIST/SEARCH variants are gated `ORG_MEMBER`, one role tier BELOW
+     * the `organizations` hole, and would be a full directory the day a second row existed.
+     *
+     * The premise is ASSERTED rather than assumed, and only a lane with a real store can assert it:
+     * `examples/wonder-todos/e2e/applications-scope-root-list-confinement.e2e.ts` fails if the
+     * deployment ever holds more than one application row. (The unit probe beside this authority
+     * asserts the complementary half — that this declaration and the compiled filter agree.)
+     */
+    UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE = "UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE",
+    /**
+     * There is NOTHING to confine to. An anonymous session is a pre-authentication visitor of the
+     * application; it has no organization, so a "confined" listing would name a relationship that does
+     * not exist. `APP_ADMIN_SUPER_ADMIN` is the whole of the control, and it is the right one.
+     *
+     * ⚠️ If anonymous sessions ever gain a tenant association this becomes an ORGANIZATIONS-axis
+     * question and the disposition moves to {@link ScopeRootConfinementDisposition.CONFINED_TO_CALLER_ORGANIZATIONS}.
+     */
+    UNCONFINED_NO_CONFINING_RELATIONSHIP = "UNCONFINED_NO_CONFINING_RELATIONSHIP"
+}
+/**
+ * The disposition of every scope root, TOTAL over `ResourcePrimaryScope`.
+ *
+ * Total on purpose (`.claude/rules/derive-before-you-ask.md` #3): a scope added to the vocabulary
+ * tomorrow is a COMPILE ERROR here, so someone has to answer the rule above for it rather than
+ * inheriting silence. The predicate this replaced was `resourcePrimaryScope !== ORGANIZATIONS` with
+ * a comment saying the other three "would change four surfaces this analysis did not measure" —
+ * true when written, and by then no longer true: all four had since been measured
+ * (`scope-root-collection-confinement.probe.test.ts`, the RESIDUAL sweep) and each answer recorded
+ * in a different resource config. This map is where that answer now lives, once.
+ */
+export declare const SCOPE_ROOT_CONFINEMENT_DISPOSITIONS: Readonly<Record<ResourcePrimaryScope, ScopeRootConfinementDisposition>>;
+/**
+ * The disposition governing this resource, or `undefined` when it is not a scope root at all.
+ *
+ * Exported so a test — or a future gate — can ask the SAME question this authority answers instead
+ * of re-deriving it from the resource configs, which is how the four recorded answers came to be
+ * four separate paragraphs in the first place.
+ */
+export declare function resolveScopeRootConfinementDisposition(resource: ScopeRootCollectionConfinementResource): ScopeRootConfinementDisposition | undefined;
 /** What this authority needs from the execution context. Deliberately narrow, like its siblings. */
 export interface ScopeRootCollectionConfinementSignal {
     readonly executionType: ExecutionContext_ExecutionType;

package/dist/esm/security/authorizations/scope-root-collection-confinement.backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-root-collection-confinement.backend.d.ts","sourceRoot":"","sources":["../../../../../src/security/authorizations/scope-root-collection-confinement.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAI/B,MAAM,uBAAuB,CAAC;AAE/B,kGAAkG;AAClG,eAAO,MAAM,4BAA4B,QAAQ,CAAC;AA8ClD,oGAAoG;AACpG,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,aAAa,EAAE,8BAA8B,CAAC;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS;QACjC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;QACtC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACnC;;;;;WAKG;QACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;KACtC,EAAE,GAAG,IAAI,CAAC;IACX;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,uCAAuC,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAC5F;AAED,iEAAiE;AACjE,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,sCAAsC,GAAG,OAAO,CAKhG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kCAAkC,CAAC,MAAM,EAAE;IACzD,QAAQ,CAAC,gBAAgB,EAAE,oCAAoC,CAAC;IAChE,QAAQ,CAAC,qBAAqB,EAAE,sCAAsC,CAAC;IACvE,QAAQ,CAAC,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAC;CACnE,GAAG,OAAO,CAcV;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,gBAAgB,EAAE,oCAAoC,GACrD,MAAM,EAAE,CASV;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,4CAA4C,CAAC,OAAO,SAAS,MAAM,EAAE,MAAM,EAAE;IAC3F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,oCAAoC,CAAC;IAChE,QAAQ,CAAC,qBAAqB,EAAE,sCAAsC,CAAC;IACvE,2FAA2F;IAC3F,QAAQ,CAAC,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAC;CACnE,GAAG,OAAO,CAsBV"}
+{"version":3,"file":"scope-root-collection-confinement.backend.d.ts","sourceRoot":"","sources":["../../../../src/security/authorizations/scope-root-collection-confinement.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAE9B,oBAAoB,EAErB,MAAM,uBAAuB,CAAC;AAE/B,kGAAkG;AAClG,eAAO,MAAM,4BAA4B,QAAQ,CAAC;AAElD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,oBAAY,+BAA+B;IACzC;;;OAGG;IACH,gCAAgC,qCAAqC;IACrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8DG;IACH,qCAAqC,0CAA0C;IAC/E;;;;;;;;;;;OAWG;IACH,qCAAqC,0CAA0C;IAC/E;;;;;;;OAOG;IACH,oCAAoC,yCAAyC;CAC9E;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mCAAmC,EAAE,QAAQ,CAAC,MAAM,CAAC,oBAAoB,EAAE,+BAA+B,CAAC,CAKtH,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,sCAAsC,CACpD,QAAQ,EAAE,sCAAsC,GAC/C,+BAA+B,GAAG,SAAS,CAG7C;AA8CD,oGAAoG;AACpG,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,aAAa,EAAE,8BAA8B,CAAC;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS;QACjC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;QACtC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACnC;;;;;WAKG;QACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;KACtC,EAAE,GAAG,IAAI,CAAC;IACX;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,uCAAuC,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAC5F;AAED,iEAAiE;AACjE,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,sCAAsC,GAAG,OAAO,CAKhG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kCAAkC,CAAC,MAAM,EAAE;IACzD,QAAQ,CAAC,gBAAgB,EAAE,oCAAoC,CAAC;IAChE,QAAQ,CAAC,qBAAqB,EAAE,sCAAsC,CAAC;IACvE,QAAQ,CAAC,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAC;CACnE,GAAG,OAAO,CAcV;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,gBAAgB,EAAE,oCAAoC,GACrD,MAAM,EAAE,CASV;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,4CAA4C,CAAC,OAAO,SAAS,MAAM,EAAE,MAAM,EAAE;IAC3F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,oCAAoC,CAAC;IAChE,QAAQ,CAAC,qBAAqB,EAAE,sCAAsC,CAAC;IACvE,2FAA2F;IAC3F,QAAQ,CAAC,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAC;CACnE,GAAG,OAAO,CA0BV"}

package/dist/esm/security/authorizations/scope-root-collection-confinement.backend.js

@@ -53,6 +53,149 @@
 import { CoreResourceOperation, ExecutionContext_ExecutionType, PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE, ResourcePrimaryScope, isOrganizationWideRoleInfo, } from '@wildo-ai/saas-models';
 /** The queryable key a scope-root row is addressed by. Named once so no call site can typo it. */
 export const SCOPE_ROOT_CONFINEMENT_FIELD = '_id';
+/**
+ * WHY a given scope root is, or is not, row-confined.
+ *
+ * A named vocabulary rather than four prose comments, because "which roots owe confinement" is a
+ * closed semantic question and had been answered four times, in four files, in four different words
+ * — the shape `CLAUDE.md` asks to have one runtime source for. It also makes the answer READABLE
+ * from the authority itself instead of from the resource configs it governs.
+ *
+ * THE RULE THAT DECIDES MEMBERSHIP, stated once so the next scope is not settled by taste:
+ *
+ * > **A scope root owes row confinement exactly when a caller's authority for that scope names ONE
+ * > INSTANCE of it, while the collection holds every instance.**
+ *
+ * That is a fact about ROLE ENTRIES, and it is measurable rather than a judgement: only an
+ * `ORGANIZATIONS` entry carries a `relatedResourceId` selecting a particular scope instance. An
+ * `APPLICATION` entry names the deployment (there is one), and `USER_SELF` / `ANONYMOUS` have no
+ * role entries at all — their instance comes from `initiatorIds`, which the request supplies about
+ * ITSELF and which therefore cannot be an authority set. So on today's vocabulary exactly one root
+ * owes it, and that is a derivation, not a denominator someone chose.
+ */
+export var ScopeRootConfinementDisposition;
+(function (ScopeRootConfinementDisposition) {
+    /**
+     * Confined to the tenants the caller holds an organization-WIDE role entry for. The only
+     * disposition that produces a predicate.
+     */
+    ScopeRootConfinementDisposition["CONFINED_TO_CALLER_ORGANIZATIONS"] = "CONFINED_TO_CALLER_ORGANIZATIONS";
+    /**
+     * The root's HTTP collection surface is the APPLICATION-tier administrative directory, and the
+     * caller's authority for it is application-wide — so "all rows" is not wider than the authority
+     * that reached them. Narrower callers reach the same rows only through a route that confines them
+     * by a DIFFERENT mechanism (`users` is enumerated per tenant through
+     * `/organizations/{organizationId}/users/search`, whose junction filter intersects `_id` with the
+     * tenant's membership; the global routes stay admin-gated).
+     *
+     * ## ⚠️ The ELEVATION asymmetry this disposition carries, stated so nobody has to re-derive it
+     *
+     * Read against the per-row door, the sentence above is the whole of the control and it is a
+     * statement about a STANDING role. Measured 2026-09-09:
+     *
+     * | | per-row crossing | this directory read |
+     * |---|---|---|
+     * | declared per variant | `admitsCrossTenantPlatformAdministration` | nothing |
+     * | elevation required | a usable, time-bound, justified `platformAccessGrants` row | none |
+     * | role tier | `APP_ADMIN_SUPER_ADMIN` | `APP_ADMIN_VIEWER` (`users`), `ORG_MEMBER` (`applications` LIST) |
+     * | evidence | `CROSS_TENANT_ADMINISTRATIVE_ACCESS`, naming the authorizing grant | `PLATFORM_DIRECTORY_ACCESS`, naming no elevation |
+     *
+     * That WAS the correct reading of the finding, and it was worse than "not symmetric": the control
+     * was inverted.
+     *
+     * ## CLOSED 2026-09-09 — the table above is HISTORY, not current state
+     *
+     * The "elevation required" cell now reads *a usable, second-signed `applicationAccessGrants` row*
+     * on both halves. Do not reason from the table as if it still described the system; it is kept
+     * because the inversion is the argument for the mechanism that replaced it.
+     *
+     * `hasUsablePlatformAccessGrant` still needs a TARGET tenant and still answers `false` on an empty
+     * one, so the TENANT grant remains structurally inapplicable to a collection call — that half was
+     * always a fact about the mechanism rather than a proof that prevention was impossible, and it is
+     * what made a second resource necessary rather than a field.
+     *
+     * **`CoreResourceType.APPLICATION_ACCESS_GRANTS` is that second resource**, approved under a
+     * TWO-PERSON RULE: the signature must come from a platform administrator who is NOT the requester,
+     * enforced in the implementation and hidden by the operation's `enabledCondition`. Customer
+     * approval (Lockbox, Access Approval) is the industry ceiling and is structurally unavailable —
+     * there is no single customer to ask — so a second signature is the strongest control that exists
+     * for this act; `.claude/rules/administrative-continuity-floors.md` says so in as many words.
+     *
+     * The admission is `readRequiresApplicationWideGrant`, which COMPOSES this authority's own
+     * `isUnconfinedScopeRootDirectoryRead` with `isObservedCrossTenantRead` rather than asking a third
+     * question, so the gate and the trail cannot disagree about which reads are in scope. Auto-approval
+     * was rejected: it is the tenant grant's default posture only because a tenant can opt in above it,
+     * and there is no such party here.
+     *
+     * A related choice is already RECORDED and should not be quietly reversed: a browsable platform
+     * tenant directory was considered and rejected, on the reasoning that industry practice (Customer
+     * Lockbox, Access Approval) has the tenant id arrive out of band with the customer's support
+     * ticket. It is UNCHANGED by the closure above and is now load-bearing in a second way: with the
+     * directory read itself elevated, an operator who wanted to browse tenants would need an
+     * application-wide grant and a second signature to do it, which is the outcome that decision
+     * wanted anyway.
+     *
+     * ## What was rejected on MEASUREMENT rather than on cost
+     *
+     * Confining this read to tenants the caller holds a grant for is not merely undesirable here, it
+     * is structurally unavailable for the widest case: `users` rows carry NO tenant column at all
+     * (membership lives in `organizationMembers`), so there is nothing for a tenant predicate to bind
+     * to. Any such confinement would be a junction query that also removes the tenant-less user — the
+     * person who has just signed up and belongs to nobody — from the only surface that can find them.
+     */
+    ScopeRootConfinementDisposition["UNCONFINED_APPLICATION_TIER_DIRECTORY"] = "UNCONFINED_APPLICATION_TIER_DIRECTORY";
+    /**
+     * ONE DATABASE PER APPLICATION. "An application's organizations live in that application's own
+     * database" — so this collection holds this deployment's own row and a caller can only ever see
+     * the application they are already using. Safe by ARCHITECTURE, not by a predicate, which is why
+     * it is spelled out: the default LIST/SEARCH variants are gated `ORG_MEMBER`, one role tier BELOW
+     * the `organizations` hole, and would be a full directory the day a second row existed.
+     *
+     * The premise is ASSERTED rather than assumed, and only a lane with a real store can assert it:
+     * `examples/wonder-todos/e2e/applications-scope-root-list-confinement.e2e.ts` fails if the
+     * deployment ever holds more than one application row. (The unit probe beside this authority
+     * asserts the complementary half — that this declaration and the compiled filter agree.)
+     */
+    ScopeRootConfinementDisposition["UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE"] = "UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE";
+    /**
+     * There is NOTHING to confine to. An anonymous session is a pre-authentication visitor of the
+     * application; it has no organization, so a "confined" listing would name a relationship that does
+     * not exist. `APP_ADMIN_SUPER_ADMIN` is the whole of the control, and it is the right one.
+     *
+     * ⚠️ If anonymous sessions ever gain a tenant association this becomes an ORGANIZATIONS-axis
+     * question and the disposition moves to {@link ScopeRootConfinementDisposition.CONFINED_TO_CALLER_ORGANIZATIONS}.
+     */
+    ScopeRootConfinementDisposition["UNCONFINED_NO_CONFINING_RELATIONSHIP"] = "UNCONFINED_NO_CONFINING_RELATIONSHIP";
+})(ScopeRootConfinementDisposition || (ScopeRootConfinementDisposition = {}));
+/**
+ * The disposition of every scope root, TOTAL over `ResourcePrimaryScope`.
+ *
+ * Total on purpose (`.claude/rules/derive-before-you-ask.md` #3): a scope added to the vocabulary
+ * tomorrow is a COMPILE ERROR here, so someone has to answer the rule above for it rather than
+ * inheriting silence. The predicate this replaced was `resourcePrimaryScope !== ORGANIZATIONS` with
+ * a comment saying the other three "would change four surfaces this analysis did not measure" —
+ * true when written, and by then no longer true: all four had since been measured
+ * (`scope-root-collection-confinement.probe.test.ts`, the RESIDUAL sweep) and each answer recorded
+ * in a different resource config. This map is where that answer now lives, once.
+ */
+export const SCOPE_ROOT_CONFINEMENT_DISPOSITIONS = Object.freeze({
+    [ResourcePrimaryScope.ORGANIZATIONS]: ScopeRootConfinementDisposition.CONFINED_TO_CALLER_ORGANIZATIONS,
+    [ResourcePrimaryScope.USER_SELF]: ScopeRootConfinementDisposition.UNCONFINED_APPLICATION_TIER_DIRECTORY,
+    [ResourcePrimaryScope.APPLICATION]: ScopeRootConfinementDisposition.UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE,
+    [ResourcePrimaryScope.ANONYMOUS]: ScopeRootConfinementDisposition.UNCONFINED_NO_CONFINING_RELATIONSHIP,
+});
+/**
+ * The disposition governing this resource, or `undefined` when it is not a scope root at all.
+ *
+ * Exported so a test — or a future gate — can ask the SAME question this authority answers instead
+ * of re-deriving it from the resource configs, which is how the four recorded answers came to be
+ * four separate paragraphs in the first place.
+ */
+export function resolveScopeRootConfinementDisposition(resource) {
+    if (!isOwnScopeRootResource(resource))
+        return undefined;
+    return SCOPE_ROOT_CONFINEMENT_DISPOSITIONS[resource.resourcePrimaryScope];
+}
 /**
  * The operations this confinement governs: those that resolve a SET of rows with no per-row
  * authorization behind them.
@@ -192,12 +335,16 @@ export function resolveCallerOrganizationIds(executionContext) {
  * G-PG-NULL). One emitter covers the confined case and the deny-all case on both adapters.
  */
 export function assignScopeRootCollectionConfinementToFilter(params) {
-    if (!isOwnScopeRootResource(params.resourceConfiguration))
+    const disposition = resolveScopeRootConfinementDisposition(params.resourceConfiguration);
+    if (!disposition)
         return false;
-    // Only the tenant axis. `users`, `applications` and `anonymous_users` are also their own scope
-    // roots, but they are APPLICATION-level directories rather than tenant data, and confining them
-    // would change four surfaces this analysis did not measure. See the analysis plan's open question.
-    if (params.resourceConfiguration.resourcePrimaryScope !== ResourcePrimaryScope.ORGANIZATIONS)
+    // Which roots owe a predicate is DECLARED, total over the scope vocabulary, with the rule that
+    // decides membership stated on the enum. An unrecognised scope cannot reach here —
+    // `isOwnScopeRootResource` already refuses a scope absent from `PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE`
+    // — but were the two maps ever to disagree, `undefined` falls through this check and CONFINES,
+    // which yields the caller's organization ids as `_id`s of some other resource: no rows, loudly,
+    // rather than every row, silently.
+    if (disposition !== undefined && disposition !== ScopeRootConfinementDisposition.CONFINED_TO_CALLER_ORGANIZATIONS)
         return false;
     if (!params.executedCoreOperation)
         return false;

package/dist/esm/security/authorizations/scope-root-collection-confinement.backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"scope-root-collection-confinement.backend.js","sourceRoot":"","sources":["../../../../../src/security/authorizations/scope-root-collection-confinement.backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * # Scope-ROOT collection confinement — ONE definition, compiled by both adapters\n *\n * assurance-control: WILDO.ACCESS.SCOPE_CONFINEMENT — confines a collection read of the tenant\n * resource itself to the tenants the caller belongs to.\n *\n * ## The hole this closes\n *\n * Every ORGANIZATIONS-scoped resource is confined by `assignInitiatorOrganizationConfinementToFilter`\n * (D3) or by the context-entry loop, both keyed on the `organizationId` COLUMN the row carries.\n * `organizations` carries no such column: it IS the tenant, addressed by `_id`. Both adapters then\n * lose the axis twice over, and independently —\n *\n *  1. `blacklistedFields` is seeded with the resource's own `resourceFieldIdentifier` \"to avoid\n *     self-reference in filtering\". For the scope root that identifier IS the scope field, so the\n *     context loop skips it and D3 returns `false` at its blacklist check;\n *  2. `OrganizationSchema` models no `organizationId` path (and PostgreSQL plans no such column), so\n *     even an admitted D3 would find nothing to write.\n *\n * Measured, not reasoned: a scope-root LIST compiled to `{}` — the empty filter, no tenant predicate\n * at all — on BOTH adapters, while a non-root org-scoped resource on the identical execution context\n * compiled to `{organizationId: 'org-caller'}`. See\n * `base-classes/__tests__/scope-root-collection-confinement.probe.test.ts`.\n *\n * Nothing leaked, because the ORGANIZATIONS branch of `validateParentScopeAccess` refused every\n * caller before the repository ran — it demands a PARENT organization scope, which the scope root\n * structurally does not have. So the gate was the SOLE control standing between an APPLICATION-role\n * caller and an unconfined cross-tenant tenant directory, and the two-line \"fix\" to that gate would\n * have been a full cross-tenant disclosure that turned every existing pin green.\n *\n * This module is therefore the half that had to land FIRST. See\n * `.claude/plans/organizations-scope-root-collection-gate-analysis.md`.\n *\n * ## Why an authority module and not two repository branches\n *\n * There are two `buildContextualFilter` implementations. The retention hide learned the cost of a\n * hand-written copy on each side (gate G-PG-NULL); D3 learned it again — it existed on PostgreSQL\n * and not on MongoDB, \"the only measured divergence where the two adapters disagreed about WHO CAN\n * SEE WHOSE ROWS\". A tenancy predicate present on one adapter and absent on the other is not a gap,\n * it is a bypass on the adapter that lacks it (`.claude/rules/invariant-call-site-enumeration.md`).\n *\n * ## Membership comes from ROLE ENTRIES, never from `initiatorIds`\n *\n * `initiatorIds.organizationId` names the ONE tenant the request is acting in, which is the wrong\n * question here: a collection read of the tenant resource asks \"which tenants are yours\", plural.\n * Role entries are also the one input a request cannot author for itself — the same reasoning\n * `holdsOrganizationWideEntryFor` and `authorizeOrganizations` rest on.\n *\n * ORGANIZATION-WIDE entries only. A unit-narrowed grant confers authority over a unit inside a\n * tenant, not over the tenant row, and every org-wide gate in the authorization service filters\n * those out; counting one here would let a unit member enumerate the tenant they are narrowed inside.\n */\n\nimport {\n  CoreResourceOperation,\n  ExecutionContext_ExecutionType,\n  PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE,\n  ResourcePrimaryScope,\n  isOrganizationWideRoleInfo,\n} from '@wildo-ai/saas-models';\n\n/** The queryable key a scope-root row is addressed by. Named once so no call site can typo it. */\nexport const SCOPE_ROOT_CONFINEMENT_FIELD = '_id';\n\n/**\n * The operations this confinement governs: those that resolve a SET of rows with no per-row\n * authorization behind them.\n *\n * Per-INSTANCE operations are deliberately absent, and this is a decision rather than an oversight.\n * `authorizeOrganizations` fetches the row and compares its tenant against the caller's org-wide\n * role entries, refusing a non-member — that gate was hardened on 2026-08-05 and is measured healthy\n * (a per-instance READ answers 200 for a member while every collection call answers 403). Adding a\n * row filter underneath it would buy no isolation and would actively BREAK the declared cross-tenant\n * repair doors (`restore`, `activate`, `requestDeletion: admin`), every one of which is per-instance\n * — silently filtering an operation authorization deliberately admitted, which is the precise\n * failure `.claude/rules/administrative-continuity-floors.md` warns about and which D3's own\n * crossing-awareness exists to prevent.\n *\n * The write-family bulk verbs ARE included. `organizations` declares none today, so including them\n * is free; excluding them would leave a set-shaped write on the tenant resource unconfined the day\n * one is declared, which is exactly how a scope-root hole comes back.\n */\nconst SCOPE_ROOT_CONFINED_OPERATIONS: readonly CoreResourceOperation[] = [\n  CoreResourceOperation.LIST,\n  CoreResourceOperation.SEARCH,\n  CoreResourceOperation.COUNT,\n  CoreResourceOperation.UPDATE_MANY,\n  CoreResourceOperation.DELETE_MANY,\n];\n\n/**\n * Execution types that carry no membership by construction and must not be confined.\n *\n * Mirrors {@link ORGANIZATION_UNIT_NARROWING_EXEMPT_EXECUTION_TYPES} and is exempt for the same\n * reason: `INTERNALLY_INITIATED_REQUEST` is the framework's context-free system actor (batch, cron,\n * cascade, bootstrap) and `WEBHOOK_CALLBACK` is trusted after signature verification. Neither holds\n * role entries, so confining them would not fail closed — it would empty every tenant sweep, purge\n * and cascade, presenting a broken system as \"no rows\".\n *\n * ⚠️ Every OTHER execution type — user, machine, anonymous, consumable-token, public — is confined,\n * and a principal with no org-wide entry is confined to the EMPTY set rather than exempted. Adding a\n * member here removes a tenant-isolation check.\n */\nconst SCOPE_ROOT_CONFINEMENT_EXEMPT_EXECUTION_TYPES: readonly ExecutionContext_ExecutionType[] = [\n  ExecutionContext_ExecutionType.INTERNALLY_INITIATED_REQUEST,\n  ExecutionContext_ExecutionType.WEBHOOK_CALLBACK,\n];\n\n/** What this authority needs from the execution context. Deliberately narrow, like its siblings. */\nexport interface ScopeRootCollectionConfinementSignal {\n  readonly executionType: ExecutionContext_ExecutionType;\n  readonly initiatorRoles?: readonly {\n    readonly relatedPrimaryScope?: string;\n    readonly relatedResourceId?: string | null;\n    readonly roles?: readonly string[];\n    /**\n     * Present ⇒ the entry is a UNIT grant, not tenant membership. Declared here rather than left\n     * implicit because omitting it is how a test fixture builds an entry that LOOKS unit-scoped and\n     * is silently treated as organization-wide — which is how the first draft of this module's own\n     * pin passed for the wrong reason.\n     */\n    readonly organizationUnitId?: string;\n  }[] | null;\n  /**\n   * Only the crossing declaration is read. An operation that did NOT declare one is confined, which\n   * is what keeps the opt-in enumerable rather than a privilege-based bypass.\n   */\n  readonly operation?: { readonly admitsCrossTenantPlatformAdministration?: boolean } | null;\n}\n\n/** What this authority needs from the resource configuration. */\nexport interface ScopeRootCollectionConfinementResource {\n  readonly resourceIdentifier?: string;\n  readonly resourcePrimaryScope?: string;\n}\n\n/**\n * Is this resource the ROOT of its own primary scope — the tenant row itself rather than a row\n * inside a tenant?\n *\n * Structural (`resourceIdentifier === PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE[scope]`) rather than a\n * comparison against `CoreResourceType.ORGANIZATIONS`, so a future tenant scope is covered the day\n * it is declared.\n *\n * **Exported because the authorization GATE asks the same question**, and the gate's answer and the\n * filter's answer must be the SAME answer. A gate that opens for a scope root the filter does not\n * recognise is precisely the disclosure this whole module exists to prevent, and two look-alike\n * derivations of one predicate is how that happens (`.claude/rules/invariant-call-site-enumeration.md`).\n */\nexport function isOwnScopeRootResource(resource: ScopeRootCollectionConfinementResource): boolean {\n  const scope = resource.resourcePrimaryScope;\n  if (!scope) return false;\n  const rootResourceType = PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE[scope as ResourcePrimaryScope];\n  return Boolean(rootResourceType) && resource.resourceIdentifier === String(rootResourceType);\n}\n\n/**\n * Is this collection read an APPLICATION-WIDE directory enumeration — a scope-root collection whose\n * rows are NOT confined to any one tenant?\n *\n * This is the audit trigger's question, and it is deliberately the exact complement of the\n * confinement decision above rather than a second, similar-looking rule. A resource is a directory\n * precisely when it is its own scope root AND this authority declines to confine it: today that is\n * `users`, `applications` and `anonymousUsers` (non-tenant scope roots), and it would become false\n * for any of them the moment the confinement is widened to their axis. Deriving the two answers from\n * one predicate is what stops the trail claiming \"unconfined\" about a read that has since been\n * confined.\n *\n * An exempt execution type is NOT a directory read for audit purposes: a batch or webhook has no\n * operator to attribute, and recording framework machinery as operator browsing would bury the\n * signal the event exists to carry.\n */\nexport function isUnconfinedScopeRootDirectoryRead(params: {\n  readonly executionContext: ScopeRootCollectionConfinementSignal;\n  readonly resourceConfiguration: ScopeRootCollectionConfinementResource;\n  readonly executedCoreOperation: CoreResourceOperation | undefined;\n}): boolean {\n  if (!isOwnScopeRootResource(params.resourceConfiguration)) return false;\n  if (!params.executedCoreOperation) return false;\n  if (!SCOPE_ROOT_CONFINED_OPERATIONS.includes(params.executedCoreOperation)) return false;\n  if (SCOPE_ROOT_CONFINEMENT_EXEMPT_EXECUTION_TYPES.includes(params.executionContext.executionType)) return false;\n\n  // Confined ⇒ not a directory. Asked of a throwaway filter so the question can be answered without\n  // a caller having to own one, and so the two answers can never disagree.\n  return !assignScopeRootCollectionConfinementToFilter({\n    filter: {},\n    executionContext: params.executionContext,\n    resourceConfiguration: params.resourceConfiguration,\n    executedCoreOperation: params.executedCoreOperation,\n  });\n}\n\n/**\n * The tenant ids the caller holds an organization-WIDE role entry for.\n *\n * Exported so the authorization gate can report the same set it is about to confine to, rather than\n * re-deriving it — two derivations of one membership set is how a gate and a filter start\n * disagreeing about who is a member.\n */\nexport function resolveCallerOrganizationIds(\n  executionContext: ScopeRootCollectionConfinementSignal,\n): string[] {\n  const ids = new Set<string>();\n  for (const roleInfo of (executionContext.initiatorRoles ?? []).filter(isOrganizationWideRoleInfo as never)) {\n    const entry = roleInfo as { relatedPrimaryScope?: string; relatedResourceId?: string | null };\n    if (entry.relatedPrimaryScope !== ResourcePrimaryScope.ORGANIZATIONS) continue;\n    const id = String(entry.relatedResourceId ?? '');\n    if (id) ids.add(id);\n  }\n  return [...ids];\n}\n\n/**\n * Confine `filter` to the caller's own tenants, in place. Returns whether it was applied.\n *\n * ## Composition with a caller-supplied `_id`\n *\n * The sibling authorities OVERWRITE at the top level, because for them a caller-supplied value for\n * the confined field is an attempt to widen and must be neutralised. Here the same reasoning gives a\n * different mechanic: `_id` is also how a legitimate request NARROWS, so an overwrite would silently\n * discard a caller's own filter and hand back MORE rows than they asked for.\n *\n * So this INTERSECTS — never skips. The result is always a subset of both the caller's request and\n * the caller's membership, so it cannot be widened by anything a caller sends. A shape the\n * intersection cannot interpret (a `$ne`, a regex, an operator object) resolves to the EMPTY set\n * rather than being passed through: an uninterpretable narrowing is not a licence to drop the\n * confinement.\n *\n * A \"skip if the caller already set `_id`\" guard would be the fail-OPEN version of this. Do not\n * add one.\n *\n * `$in: []` is the portable match-nothing: MongoDB matches nothing, and the PostgreSQL compiler\n * emits `FALSE` rather than the `IN ()` syntax error a naive translation would produce (gate\n * G-PG-NULL). One emitter covers the confined case and the deny-all case on both adapters.\n */\nexport function assignScopeRootCollectionConfinementToFilter<TFilter extends object>(params: {\n  readonly filter: TFilter;\n  readonly executionContext: ScopeRootCollectionConfinementSignal;\n  readonly resourceConfiguration: ScopeRootCollectionConfinementResource;\n  /** The core operation THIS repository call executes — NOT `executionContext.operation`. */\n  readonly executedCoreOperation: CoreResourceOperation | undefined;\n}): boolean {\n  if (!isOwnScopeRootResource(params.resourceConfiguration)) return false;\n  // Only the tenant axis. `users`, `applications` and `anonymous_users` are also their own scope\n  // roots, but they are APPLICATION-level directories rather than tenant data, and confining them\n  // would change four surfaces this analysis did not measure. See the analysis plan's open question.\n  if (params.resourceConfiguration.resourcePrimaryScope !== ResourcePrimaryScope.ORGANIZATIONS) return false;\n\n  if (!params.executedCoreOperation) return false;\n  if (!SCOPE_ROOT_CONFINED_OPERATIONS.includes(params.executedCoreOperation)) return false;\n\n  if (SCOPE_ROOT_CONFINEMENT_EXEMPT_EXECUTION_TYPES.includes(params.executionContext.executionType)) return false;\n\n  // A DECLARED crossing was admitted at the authorization layer, deliberately and with an audit\n  // record. Re-confining it here would undo that decision one layer down — D3's documented failure.\n  if (params.executionContext.operation?.admitsCrossTenantPlatformAdministration === true) return false;\n\n  const callerOrganizationIds = resolveCallerOrganizationIds(params.executionContext);\n  const requested = (params.filter as Record<string, unknown>)[SCOPE_ROOT_CONFINEMENT_FIELD];\n  const confinedIds = intersectRequestedIdsWithMembership(requested, callerOrganizationIds);\n\n  (params.filter as Record<string, unknown>)[SCOPE_ROOT_CONFINEMENT_FIELD] = { $in: confinedIds };\n  return true;\n}\n\n/**\n * Intersect whatever the caller asked for with what they are a member of.\n *\n * Fail-closed on every shape that is not plainly an id or a set of ids: an operator object could\n * express a superset (`$ne`, `$nin`, a regex), and there is no honest intersection with a predicate\n * whose extension is unknown here.\n */\nfunction intersectRequestedIdsWithMembership(requested: unknown, membershipIds: readonly string[]): string[] {\n  if (requested === undefined || requested === null) return [...membershipIds];\n\n  const membership = new Set(membershipIds);\n\n  if (typeof requested === 'string') {\n    return membership.has(requested) ? [requested] : [];\n  }\n\n  if (Array.isArray(requested)) {\n    return requested.map(String).filter((id) => membership.has(id));\n  }\n\n  if (typeof requested === 'object') {\n    const operators = Object.keys(requested as Record<string, unknown>);\n    const inValue = (requested as { $in?: unknown }).$in;\n    // ONLY a lone `$in`. A mixed operator object ({$in, $ne}) has an extension this cannot compute.\n    if (operators.length === 1 && operators[0] === '$in' && Array.isArray(inValue)) {\n      return inValue.map(String).filter((id) => membership.has(id));\n    }\n    return [];\n  }\n\n  return [];\n}\n"]}
+{"version":3,"file":"scope-root-collection-confinement.backend.js","sourceRoot":"","sources":["../../../../src/security/authorizations/scope-root-collection-confinement.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAC9B,mCAAmC,EACnC,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC;AAE/B,kGAAkG;AAClG,MAAM,CAAC,MAAM,4BAA4B,GAAG,KAAK,CAAC;AAElD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAN,IAAY,+BA4FX;AA5FD,WAAY,+BAA+B;IACzC;;;OAGG;IACH,wGAAqE,CAAA;IACrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8DG;IACH,kHAA+E,CAAA;IAC/E;;;;;;;;;;;OAWG;IACH,kHAA+E,CAAA;IAC/E;;;;;;;OAOG;IACH,gHAA6E,CAAA;AAC/E,CAAC,EA5FW,+BAA+B,KAA/B,+BAA+B,QA4F1C;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAA4E,MAAM,CAAC,MAAM,CAAC;IACxI,CAAC,oBAAoB,CAAC,aAAa,CAAC,EAAE,+BAA+B,CAAC,gCAAgC;IACtG,CAAC,oBAAoB,CAAC,SAAS,CAAC,EAAE,+BAA+B,CAAC,qCAAqC;IACvG,CAAC,oBAAoB,CAAC,WAAW,CAAC,EAAE,+BAA+B,CAAC,qCAAqC;IACzG,CAAC,oBAAoB,CAAC,SAAS,CAAC,EAAE,+BAA+B,CAAC,oCAAoC;CACvG,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,sCAAsC,CACpD,QAAgD;IAEhD,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IACxD,OAAO,mCAAmC,CAAC,QAAQ,CAAC,oBAA4C,CAAC,CAAC;AACpG,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,8BAA8B,GAAqC;IACvE,qBAAqB,CAAC,IAAI;IAC1B,qBAAqB,CAAC,MAAM;IAC5B,qBAAqB,CAAC,KAAK;IAC3B,qBAAqB,CAAC,WAAW;IACjC,qBAAqB,CAAC,WAAW;CAClC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,6CAA6C,GAA8C;IAC/F,8BAA8B,CAAC,4BAA4B;IAC3D,8BAA8B,CAAC,gBAAgB;CAChD,CAAC;AA8BF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgD;IACrF,MAAM,KAAK,GAAG,QAAQ,CAAC,oBAAoB,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,MAAM,gBAAgB,GAAG,mCAAmC,CAAC,KAA6B,CAAC,CAAC;IAC5F,OAAO,OAAO,CAAC,gBAAgB,CAAC,IAAI,QAAQ,CAAC,kBAAkB,KAAK,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAC/F,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kCAAkC,CAAC,MAIlD;IACC,IAAI,CAAC,sBAAsB,CAAC,MAAM,CAAC,qBAAqB,CAAC;QAAE,OAAO,KAAK,CAAC;IACxE,IAAI,CAAC,MAAM,CAAC,qBAAqB;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,CAAC,8BAA8B,CAAC,QAAQ,CAAC,MAAM,CAAC,qBAAqB,CAAC;QAAE,OAAO,KAAK,CAAC;IACzF,IAAI,6CAA6C,CAAC,QAAQ,CAAC,MAAM,CAAC,gBAAgB,CAAC,aAAa,CAAC;QAAE,OAAO,KAAK,CAAC;IAEhH,kGAAkG;IAClG,yEAAyE;IACzE,OAAO,CAAC,4CAA4C,CAAC;QACnD,MAAM,EAAE,EAAE;QACV,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,qBAAqB,EAAE,MAAM,CAAC,qBAAqB;QACnD,qBAAqB,EAAE,MAAM,CAAC,qBAAqB;KACpD,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B,CAC1C,gBAAsD;IAEtD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,QAAQ,IAAI,CAAC,gBAAgB,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,0BAAmC,CAAC,EAAE,CAAC;QAC3G,MAAM,KAAK,GAAG,QAA+E,CAAC;QAC9F,IAAI,KAAK,CAAC,mBAAmB,KAAK,oBAAoB,CAAC,aAAa;YAAE,SAAS;QAC/E,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;QACjD,IAAI,EAAE;YAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,4CAA4C,CAAyB,MAMpF;IACC,MAAM,WAAW,GAAG,sCAAsC,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;IACzF,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAC/B,+FAA+F;IAC/F,mFAAmF;IACnF,qGAAqG;IACrG,+FAA+F;IAC/F,gGAAgG;IAChG,mCAAmC;IACnC,IAAI,WAAW,KAAK,SAAS,IAAI,WAAW,KAAK,+BAA+B,CAAC,gCAAgC;QAAE,OAAO,KAAK,CAAC;IAEhI,IAAI,CAAC,MAAM,CAAC,qBAAqB;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,CAAC,8BAA8B,CAAC,QAAQ,CAAC,MAAM,CAAC,qBAAqB,CAAC;QAAE,OAAO,KAAK,CAAC;IAEzF,IAAI,6CAA6C,CAAC,QAAQ,CAAC,MAAM,CAAC,gBAAgB,CAAC,aAAa,CAAC;QAAE,OAAO,KAAK,CAAC;IAEhH,8FAA8F;IAC9F,kGAAkG;IAClG,IAAI,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,uCAAuC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAEtG,MAAM,qBAAqB,GAAG,4BAA4B,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACpF,MAAM,SAAS,GAAI,MAAM,CAAC,MAAkC,CAAC,4BAA4B,CAAC,CAAC;IAC3F,MAAM,WAAW,GAAG,mCAAmC,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAC;IAEzF,MAAM,CAAC,MAAkC,CAAC,4BAA4B,CAAC,GAAG,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC;IAChG,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,SAAS,mCAAmC,CAAC,SAAkB,EAAE,aAAgC;IAC/F,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,CAAC,GAAG,aAAa,CAAC,CAAC;IAE7E,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;IAE1C,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACtD,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7B,OAAO,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAClE,CAAC;IAED,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,SAAoC,CAAC,CAAC;QACpE,MAAM,OAAO,GAAI,SAA+B,CAAC,GAAG,CAAC;QACrD,gGAAgG;QAChG,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/E,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC","sourcesContent":["/**\n * # Scope-ROOT collection confinement — ONE definition, compiled by both adapters\n *\n * assurance-control: WILDO.ACCESS.SCOPE_CONFINEMENT — confines a collection read of the tenant\n * resource itself to the tenants the caller belongs to.\n *\n * ## The hole this closes\n *\n * Every ORGANIZATIONS-scoped resource is confined by `assignInitiatorOrganizationConfinementToFilter`\n * (D3) or by the context-entry loop, both keyed on the `organizationId` COLUMN the row carries.\n * `organizations` carries no such column: it IS the tenant, addressed by `_id`. Both adapters then\n * lose the axis twice over, and independently —\n *\n *  1. `blacklistedFields` is seeded with the resource's own `resourceFieldIdentifier` \"to avoid\n *     self-reference in filtering\". For the scope root that identifier IS the scope field, so the\n *     context loop skips it and D3 returns `false` at its blacklist check;\n *  2. `OrganizationSchema` models no `organizationId` path (and PostgreSQL plans no such column), so\n *     even an admitted D3 would find nothing to write.\n *\n * Measured, not reasoned: a scope-root LIST compiled to `{}` — the empty filter, no tenant predicate\n * at all — on BOTH adapters, while a non-root org-scoped resource on the identical execution context\n * compiled to `{organizationId: 'org-caller'}`. See\n * `base-classes/__tests__/scope-root-collection-confinement.probe.test.ts`.\n *\n * Nothing leaked, because the ORGANIZATIONS branch of `validateParentScopeAccess` refused every\n * caller before the repository ran — it demands a PARENT organization scope, which the scope root\n * structurally does not have. So the gate was the SOLE control standing between an APPLICATION-role\n * caller and an unconfined cross-tenant tenant directory, and the two-line \"fix\" to that gate would\n * have been a full cross-tenant disclosure that turned every existing pin green.\n *\n * This module is therefore the half that had to land FIRST. See\n * `.claude/plans/organizations-scope-root-collection-gate-analysis.md`.\n *\n * ## Why an authority module and not two repository branches\n *\n * There are two `buildContextualFilter` implementations. The retention hide learned the cost of a\n * hand-written copy on each side (gate G-PG-NULL); D3 learned it again — it existed on PostgreSQL\n * and not on MongoDB, \"the only measured divergence where the two adapters disagreed about WHO CAN\n * SEE WHOSE ROWS\". A tenancy predicate present on one adapter and absent on the other is not a gap,\n * it is a bypass on the adapter that lacks it (`.claude/rules/invariant-call-site-enumeration.md`).\n *\n * ## Membership comes from ROLE ENTRIES, never from `initiatorIds`\n *\n * `initiatorIds.organizationId` names the ONE tenant the request is acting in, which is the wrong\n * question here: a collection read of the tenant resource asks \"which tenants are yours\", plural.\n * Role entries are also the one input a request cannot author for itself — the same reasoning\n * `holdsOrganizationWideEntryFor` and `authorizeOrganizations` rest on.\n *\n * ORGANIZATION-WIDE entries only. A unit-narrowed grant confers authority over a unit inside a\n * tenant, not over the tenant row, and every org-wide gate in the authorization service filters\n * those out; counting one here would let a unit member enumerate the tenant they are narrowed inside.\n */\n\nimport {\n  CoreResourceOperation,\n  ExecutionContext_ExecutionType,\n  PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE,\n  ResourcePrimaryScope,\n  isOrganizationWideRoleInfo,\n} from '@wildo-ai/saas-models';\n\n/** The queryable key a scope-root row is addressed by. Named once so no call site can typo it. */\nexport const SCOPE_ROOT_CONFINEMENT_FIELD = '_id';\n\n/**\n * WHY a given scope root is, or is not, row-confined.\n *\n * A named vocabulary rather than four prose comments, because \"which roots owe confinement\" is a\n * closed semantic question and had been answered four times, in four files, in four different words\n * — the shape `CLAUDE.md` asks to have one runtime source for. It also makes the answer READABLE\n * from the authority itself instead of from the resource configs it governs.\n *\n * THE RULE THAT DECIDES MEMBERSHIP, stated once so the next scope is not settled by taste:\n *\n * > **A scope root owes row confinement exactly when a caller's authority for that scope names ONE\n * > INSTANCE of it, while the collection holds every instance.**\n *\n * That is a fact about ROLE ENTRIES, and it is measurable rather than a judgement: only an\n * `ORGANIZATIONS` entry carries a `relatedResourceId` selecting a particular scope instance. An\n * `APPLICATION` entry names the deployment (there is one), and `USER_SELF` / `ANONYMOUS` have no\n * role entries at all — their instance comes from `initiatorIds`, which the request supplies about\n * ITSELF and which therefore cannot be an authority set. So on today's vocabulary exactly one root\n * owes it, and that is a derivation, not a denominator someone chose.\n */\nexport enum ScopeRootConfinementDisposition {\n  /**\n   * Confined to the tenants the caller holds an organization-WIDE role entry for. The only\n   * disposition that produces a predicate.\n   */\n  CONFINED_TO_CALLER_ORGANIZATIONS = 'CONFINED_TO_CALLER_ORGANIZATIONS',\n  /**\n   * The root's HTTP collection surface is the APPLICATION-tier administrative directory, and the\n   * caller's authority for it is application-wide — so \"all rows\" is not wider than the authority\n   * that reached them. Narrower callers reach the same rows only through a route that confines them\n   * by a DIFFERENT mechanism (`users` is enumerated per tenant through\n   * `/organizations/{organizationId}/users/search`, whose junction filter intersects `_id` with the\n   * tenant's membership; the global routes stay admin-gated).\n   *\n   * ## ⚠️ The ELEVATION asymmetry this disposition carries, stated so nobody has to re-derive it\n   *\n   * Read against the per-row door, the sentence above is the whole of the control and it is a\n   * statement about a STANDING role. Measured 2026-09-09:\n   *\n   * | | per-row crossing | this directory read |\n   * |---|---|---|\n   * | declared per variant | `admitsCrossTenantPlatformAdministration` | nothing |\n   * | elevation required | a usable, time-bound, justified `platformAccessGrants` row | none |\n   * | role tier | `APP_ADMIN_SUPER_ADMIN` | `APP_ADMIN_VIEWER` (`users`), `ORG_MEMBER` (`applications` LIST) |\n   * | evidence | `CROSS_TENANT_ADMINISTRATIVE_ACCESS`, naming the authorizing grant | `PLATFORM_DIRECTORY_ACCESS`, naming no elevation |\n   *\n   * That WAS the correct reading of the finding, and it was worse than \"not symmetric\": the control\n   * was inverted.\n   *\n   * ## CLOSED 2026-09-09 — the table above is HISTORY, not current state\n   *\n   * The \"elevation required\" cell now reads *a usable, second-signed `applicationAccessGrants` row*\n   * on both halves. Do not reason from the table as if it still described the system; it is kept\n   * because the inversion is the argument for the mechanism that replaced it.\n   *\n   * `hasUsablePlatformAccessGrant` still needs a TARGET tenant and still answers `false` on an empty\n   * one, so the TENANT grant remains structurally inapplicable to a collection call — that half was\n   * always a fact about the mechanism rather than a proof that prevention was impossible, and it is\n   * what made a second resource necessary rather than a field.\n   *\n   * **`CoreResourceType.APPLICATION_ACCESS_GRANTS` is that second resource**, approved under a\n   * TWO-PERSON RULE: the signature must come from a platform administrator who is NOT the requester,\n   * enforced in the implementation and hidden by the operation's `enabledCondition`. Customer\n   * approval (Lockbox, Access Approval) is the industry ceiling and is structurally unavailable —\n   * there is no single customer to ask — so a second signature is the strongest control that exists\n   * for this act; `.claude/rules/administrative-continuity-floors.md` says so in as many words.\n   *\n   * The admission is `readRequiresApplicationWideGrant`, which COMPOSES this authority's own\n   * `isUnconfinedScopeRootDirectoryRead` with `isObservedCrossTenantRead` rather than asking a third\n   * question, so the gate and the trail cannot disagree about which reads are in scope. Auto-approval\n   * was rejected: it is the tenant grant's default posture only because a tenant can opt in above it,\n   * and there is no such party here.\n   *\n   * A related choice is already RECORDED and should not be quietly reversed: a browsable platform\n   * tenant directory was considered and rejected, on the reasoning that industry practice (Customer\n   * Lockbox, Access Approval) has the tenant id arrive out of band with the customer's support\n   * ticket. It is UNCHANGED by the closure above and is now load-bearing in a second way: with the\n   * directory read itself elevated, an operator who wanted to browse tenants would need an\n   * application-wide grant and a second signature to do it, which is the outcome that decision\n   * wanted anyway.\n   *\n   * ## What was rejected on MEASUREMENT rather than on cost\n   *\n   * Confining this read to tenants the caller holds a grant for is not merely undesirable here, it\n   * is structurally unavailable for the widest case: `users` rows carry NO tenant column at all\n   * (membership lives in `organizationMembers`), so there is nothing for a tenant predicate to bind\n   * to. Any such confinement would be a junction query that also removes the tenant-less user — the\n   * person who has just signed up and belongs to nobody — from the only surface that can find them.\n   */\n  UNCONFINED_APPLICATION_TIER_DIRECTORY = 'UNCONFINED_APPLICATION_TIER_DIRECTORY',\n  /**\n   * ONE DATABASE PER APPLICATION. \"An application's organizations live in that application's own\n   * database\" — so this collection holds this deployment's own row and a caller can only ever see\n   * the application they are already using. Safe by ARCHITECTURE, not by a predicate, which is why\n   * it is spelled out: the default LIST/SEARCH variants are gated `ORG_MEMBER`, one role tier BELOW\n   * the `organizations` hole, and would be a full directory the day a second row existed.\n   *\n   * The premise is ASSERTED rather than assumed, and only a lane with a real store can assert it:\n   * `examples/wonder-todos/e2e/applications-scope-root-list-confinement.e2e.ts` fails if the\n   * deployment ever holds more than one application row. (The unit probe beside this authority\n   * asserts the complementary half — that this declaration and the compiled filter agree.)\n   */\n  UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE = 'UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE',\n  /**\n   * There is NOTHING to confine to. An anonymous session is a pre-authentication visitor of the\n   * application; it has no organization, so a \"confined\" listing would name a relationship that does\n   * not exist. `APP_ADMIN_SUPER_ADMIN` is the whole of the control, and it is the right one.\n   *\n   * ⚠️ If anonymous sessions ever gain a tenant association this becomes an ORGANIZATIONS-axis\n   * question and the disposition moves to {@link ScopeRootConfinementDisposition.CONFINED_TO_CALLER_ORGANIZATIONS}.\n   */\n  UNCONFINED_NO_CONFINING_RELATIONSHIP = 'UNCONFINED_NO_CONFINING_RELATIONSHIP',\n}\n\n/**\n * The disposition of every scope root, TOTAL over `ResourcePrimaryScope`.\n *\n * Total on purpose (`.claude/rules/derive-before-you-ask.md` #3): a scope added to the vocabulary\n * tomorrow is a COMPILE ERROR here, so someone has to answer the rule above for it rather than\n * inheriting silence. The predicate this replaced was `resourcePrimaryScope !== ORGANIZATIONS` with\n * a comment saying the other three \"would change four surfaces this analysis did not measure\" —\n * true when written, and by then no longer true: all four had since been measured\n * (`scope-root-collection-confinement.probe.test.ts`, the RESIDUAL sweep) and each answer recorded\n * in a different resource config. This map is where that answer now lives, once.\n */\nexport const SCOPE_ROOT_CONFINEMENT_DISPOSITIONS: Readonly<Record<ResourcePrimaryScope, ScopeRootConfinementDisposition>> = Object.freeze({\n  [ResourcePrimaryScope.ORGANIZATIONS]: ScopeRootConfinementDisposition.CONFINED_TO_CALLER_ORGANIZATIONS,\n  [ResourcePrimaryScope.USER_SELF]: ScopeRootConfinementDisposition.UNCONFINED_APPLICATION_TIER_DIRECTORY,\n  [ResourcePrimaryScope.APPLICATION]: ScopeRootConfinementDisposition.UNCONFINED_SINGLE_ROW_BY_ARCHITECTURE,\n  [ResourcePrimaryScope.ANONYMOUS]: ScopeRootConfinementDisposition.UNCONFINED_NO_CONFINING_RELATIONSHIP,\n});\n\n/**\n * The disposition governing this resource, or `undefined` when it is not a scope root at all.\n *\n * Exported so a test — or a future gate — can ask the SAME question this authority answers instead\n * of re-deriving it from the resource configs, which is how the four recorded answers came to be\n * four separate paragraphs in the first place.\n */\nexport function resolveScopeRootConfinementDisposition(\n  resource: ScopeRootCollectionConfinementResource,\n): ScopeRootConfinementDisposition | undefined {\n  if (!isOwnScopeRootResource(resource)) return undefined;\n  return SCOPE_ROOT_CONFINEMENT_DISPOSITIONS[resource.resourcePrimaryScope as ResourcePrimaryScope];\n}\n\n/**\n * The operations this confinement governs: those that resolve a SET of rows with no per-row\n * authorization behind them.\n *\n * Per-INSTANCE operations are deliberately absent, and this is a decision rather than an oversight.\n * `authorizeOrganizations` fetches the row and compares its tenant against the caller's org-wide\n * role entries, refusing a non-member — that gate was hardened on 2026-08-05 and is measured healthy\n * (a per-instance READ answers 200 for a member while every collection call answers 403). Adding a\n * row filter underneath it would buy no isolation and would actively BREAK the declared cross-tenant\n * repair doors (`restore`, `activate`, `requestDeletion: admin`), every one of which is per-instance\n * — silently filtering an operation authorization deliberately admitted, which is the precise\n * failure `.claude/rules/administrative-continuity-floors.md` warns about and which D3's own\n * crossing-awareness exists to prevent.\n *\n * The write-family bulk verbs ARE included. `organizations` declares none today, so including them\n * is free; excluding them would leave a set-shaped write on the tenant resource unconfined the day\n * one is declared, which is exactly how a scope-root hole comes back.\n */\nconst SCOPE_ROOT_CONFINED_OPERATIONS: readonly CoreResourceOperation[] = [\n  CoreResourceOperation.LIST,\n  CoreResourceOperation.SEARCH,\n  CoreResourceOperation.COUNT,\n  CoreResourceOperation.UPDATE_MANY,\n  CoreResourceOperation.DELETE_MANY,\n];\n\n/**\n * Execution types that carry no membership by construction and must not be confined.\n *\n * Mirrors {@link ORGANIZATION_UNIT_NARROWING_EXEMPT_EXECUTION_TYPES} and is exempt for the same\n * reason: `INTERNALLY_INITIATED_REQUEST` is the framework's context-free system actor (batch, cron,\n * cascade, bootstrap) and `WEBHOOK_CALLBACK` is trusted after signature verification. Neither holds\n * role entries, so confining them would not fail closed — it would empty every tenant sweep, purge\n * and cascade, presenting a broken system as \"no rows\".\n *\n * ⚠️ Every OTHER execution type — user, machine, anonymous, consumable-token, public — is confined,\n * and a principal with no org-wide entry is confined to the EMPTY set rather than exempted. Adding a\n * member here removes a tenant-isolation check.\n */\nconst SCOPE_ROOT_CONFINEMENT_EXEMPT_EXECUTION_TYPES: readonly ExecutionContext_ExecutionType[] = [\n  ExecutionContext_ExecutionType.INTERNALLY_INITIATED_REQUEST,\n  ExecutionContext_ExecutionType.WEBHOOK_CALLBACK,\n];\n\n/** What this authority needs from the execution context. Deliberately narrow, like its siblings. */\nexport interface ScopeRootCollectionConfinementSignal {\n  readonly executionType: ExecutionContext_ExecutionType;\n  readonly initiatorRoles?: readonly {\n    readonly relatedPrimaryScope?: string;\n    readonly relatedResourceId?: string | null;\n    readonly roles?: readonly string[];\n    /**\n     * Present ⇒ the entry is a UNIT grant, not tenant membership. Declared here rather than left\n     * implicit because omitting it is how a test fixture builds an entry that LOOKS unit-scoped and\n     * is silently treated as organization-wide — which is how the first draft of this module's own\n     * pin passed for the wrong reason.\n     */\n    readonly organizationUnitId?: string;\n  }[] | null;\n  /**\n   * Only the crossing declaration is read. An operation that did NOT declare one is confined, which\n   * is what keeps the opt-in enumerable rather than a privilege-based bypass.\n   */\n  readonly operation?: { readonly admitsCrossTenantPlatformAdministration?: boolean } | null;\n}\n\n/** What this authority needs from the resource configuration. */\nexport interface ScopeRootCollectionConfinementResource {\n  readonly resourceIdentifier?: string;\n  readonly resourcePrimaryScope?: string;\n}\n\n/**\n * Is this resource the ROOT of its own primary scope — the tenant row itself rather than a row\n * inside a tenant?\n *\n * Structural (`resourceIdentifier === PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE[scope]`) rather than a\n * comparison against `CoreResourceType.ORGANIZATIONS`, so a future tenant scope is covered the day\n * it is declared.\n *\n * **Exported because the authorization GATE asks the same question**, and the gate's answer and the\n * filter's answer must be the SAME answer. A gate that opens for a scope root the filter does not\n * recognise is precisely the disclosure this whole module exists to prevent, and two look-alike\n * derivations of one predicate is how that happens (`.claude/rules/invariant-call-site-enumeration.md`).\n */\nexport function isOwnScopeRootResource(resource: ScopeRootCollectionConfinementResource): boolean {\n  const scope = resource.resourcePrimaryScope;\n  if (!scope) return false;\n  const rootResourceType = PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE[scope as ResourcePrimaryScope];\n  return Boolean(rootResourceType) && resource.resourceIdentifier === String(rootResourceType);\n}\n\n/**\n * Is this collection read an APPLICATION-WIDE directory enumeration — a scope-root collection whose\n * rows are NOT confined to any one tenant?\n *\n * This is the audit trigger's question, and it is deliberately the exact complement of the\n * confinement decision above rather than a second, similar-looking rule. A resource is a directory\n * precisely when it is its own scope root AND this authority declines to confine it: today that is\n * `users`, `applications` and `anonymousUsers` (non-tenant scope roots), and it would become false\n * for any of them the moment the confinement is widened to their axis. Deriving the two answers from\n * one predicate is what stops the trail claiming \"unconfined\" about a read that has since been\n * confined.\n *\n * An exempt execution type is NOT a directory read for audit purposes: a batch or webhook has no\n * operator to attribute, and recording framework machinery as operator browsing would bury the\n * signal the event exists to carry.\n */\nexport function isUnconfinedScopeRootDirectoryRead(params: {\n  readonly executionContext: ScopeRootCollectionConfinementSignal;\n  readonly resourceConfiguration: ScopeRootCollectionConfinementResource;\n  readonly executedCoreOperation: CoreResourceOperation | undefined;\n}): boolean {\n  if (!isOwnScopeRootResource(params.resourceConfiguration)) return false;\n  if (!params.executedCoreOperation) return false;\n  if (!SCOPE_ROOT_CONFINED_OPERATIONS.includes(params.executedCoreOperation)) return false;\n  if (SCOPE_ROOT_CONFINEMENT_EXEMPT_EXECUTION_TYPES.includes(params.executionContext.executionType)) return false;\n\n  // Confined ⇒ not a directory. Asked of a throwaway filter so the question can be answered without\n  // a caller having to own one, and so the two answers can never disagree.\n  return !assignScopeRootCollectionConfinementToFilter({\n    filter: {},\n    executionContext: params.executionContext,\n    resourceConfiguration: params.resourceConfiguration,\n    executedCoreOperation: params.executedCoreOperation,\n  });\n}\n\n/**\n * The tenant ids the caller holds an organization-WIDE role entry for.\n *\n * Exported so the authorization gate can report the same set it is about to confine to, rather than\n * re-deriving it — two derivations of one membership set is how a gate and a filter start\n * disagreeing about who is a member.\n */\nexport function resolveCallerOrganizationIds(\n  executionContext: ScopeRootCollectionConfinementSignal,\n): string[] {\n  const ids = new Set<string>();\n  for (const roleInfo of (executionContext.initiatorRoles ?? []).filter(isOrganizationWideRoleInfo as never)) {\n    const entry = roleInfo as { relatedPrimaryScope?: string; relatedResourceId?: string | null };\n    if (entry.relatedPrimaryScope !== ResourcePrimaryScope.ORGANIZATIONS) continue;\n    const id = String(entry.relatedResourceId ?? '');\n    if (id) ids.add(id);\n  }\n  return [...ids];\n}\n\n/**\n * Confine `filter` to the caller's own tenants, in place. Returns whether it was applied.\n *\n * ## Composition with a caller-supplied `_id`\n *\n * The sibling authorities OVERWRITE at the top level, because for them a caller-supplied value for\n * the confined field is an attempt to widen and must be neutralised. Here the same reasoning gives a\n * different mechanic: `_id` is also how a legitimate request NARROWS, so an overwrite would silently\n * discard a caller's own filter and hand back MORE rows than they asked for.\n *\n * So this INTERSECTS — never skips. The result is always a subset of both the caller's request and\n * the caller's membership, so it cannot be widened by anything a caller sends. A shape the\n * intersection cannot interpret (a `$ne`, a regex, an operator object) resolves to the EMPTY set\n * rather than being passed through: an uninterpretable narrowing is not a licence to drop the\n * confinement.\n *\n * A \"skip if the caller already set `_id`\" guard would be the fail-OPEN version of this. Do not\n * add one.\n *\n * `$in: []` is the portable match-nothing: MongoDB matches nothing, and the PostgreSQL compiler\n * emits `FALSE` rather than the `IN ()` syntax error a naive translation would produce (gate\n * G-PG-NULL). One emitter covers the confined case and the deny-all case on both adapters.\n */\nexport function assignScopeRootCollectionConfinementToFilter<TFilter extends object>(params: {\n  readonly filter: TFilter;\n  readonly executionContext: ScopeRootCollectionConfinementSignal;\n  readonly resourceConfiguration: ScopeRootCollectionConfinementResource;\n  /** The core operation THIS repository call executes — NOT `executionContext.operation`. */\n  readonly executedCoreOperation: CoreResourceOperation | undefined;\n}): boolean {\n  const disposition = resolveScopeRootConfinementDisposition(params.resourceConfiguration);\n  if (!disposition) return false;\n  // Which roots owe a predicate is DECLARED, total over the scope vocabulary, with the rule that\n  // decides membership stated on the enum. An unrecognised scope cannot reach here —\n  // `isOwnScopeRootResource` already refuses a scope absent from `PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE`\n  // — but were the two maps ever to disagree, `undefined` falls through this check and CONFINES,\n  // which yields the caller's organization ids as `_id`s of some other resource: no rows, loudly,\n  // rather than every row, silently.\n  if (disposition !== undefined && disposition !== ScopeRootConfinementDisposition.CONFINED_TO_CALLER_ORGANIZATIONS) return false;\n\n  if (!params.executedCoreOperation) return false;\n  if (!SCOPE_ROOT_CONFINED_OPERATIONS.includes(params.executedCoreOperation)) return false;\n\n  if (SCOPE_ROOT_CONFINEMENT_EXEMPT_EXECUTION_TYPES.includes(params.executionContext.executionType)) return false;\n\n  // A DECLARED crossing was admitted at the authorization layer, deliberately and with an audit\n  // record. Re-confining it here would undo that decision one layer down — D3's documented failure.\n  if (params.executionContext.operation?.admitsCrossTenantPlatformAdministration === true) return false;\n\n  const callerOrganizationIds = resolveCallerOrganizationIds(params.executionContext);\n  const requested = (params.filter as Record<string, unknown>)[SCOPE_ROOT_CONFINEMENT_FIELD];\n  const confinedIds = intersectRequestedIdsWithMembership(requested, callerOrganizationIds);\n\n  (params.filter as Record<string, unknown>)[SCOPE_ROOT_CONFINEMENT_FIELD] = { $in: confinedIds };\n  return true;\n}\n\n/**\n * Intersect whatever the caller asked for with what they are a member of.\n *\n * Fail-closed on every shape that is not plainly an id or a set of ids: an operator object could\n * express a superset (`$ne`, `$nin`, a regex), and there is no honest intersection with a predicate\n * whose extension is unknown here.\n */\nfunction intersectRequestedIdsWithMembership(requested: unknown, membershipIds: readonly string[]): string[] {\n  if (requested === undefined || requested === null) return [...membershipIds];\n\n  const membership = new Set(membershipIds);\n\n  if (typeof requested === 'string') {\n    return membership.has(requested) ? [requested] : [];\n  }\n\n  if (Array.isArray(requested)) {\n    return requested.map(String).filter((id) => membership.has(id));\n  }\n\n  if (typeof requested === 'object') {\n    const operators = Object.keys(requested as Record<string, unknown>);\n    const inValue = (requested as { $in?: unknown }).$in;\n    // ONLY a lone `$in`. A mixed operator object ({$in, $ne}) has an extension this cannot compute.\n    if (operators.length === 1 && operators[0] === '$in' && Array.isArray(inValue)) {\n      return inValue.map(String).filter((id) => membership.has(id));\n    }\n    return [];\n  }\n\n  return [];\n}\n"]}