explain-engine.ts

// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.

/**
 * [ADR-0090 D6] Access-explanation engine — `explain(principal, object,
 * operation)` as a first-class API.
 *
 * "Explained by construction": every layer below calls the SAME functions the
 * enforcement middleware calls — the shared permission-set resolution, the
 * shared `PermissionEvaluator`, the shared RLS compiler — injected from
 * `SecurityPlugin` so the report can never drift from enforcement. The engine
 * adds no evaluation logic of its own; it only records what each pipeline
 * layer contributed:
 *
 *   principal → required_permissions → object_crud → fls → owd_baseline →
 *   depth → sharing → vama_bypass → rls
 *
 * The dual use (D6): admins ask "why can 张三 PATCH 李四's leave_request?",
 * and the AI-safety story gets its audit substrate — a publish gate can show
 * the SEMANTIC impact of a grant change instead of a JSON diff.
 */

import {
  isGrantActive,
  isGrantExpired,
  derivePosture as deriveAdminPosture,
  readDisabledCatalogNames,
  resolveUserAuthzGrants,
  securityCatalogReaderOf,
} from '@objectstack/core';
import {
  crossFieldClassRefusalCarriedBy,
  findCrossFieldClassRefusal,
  matchesFilterCondition,
  type CrossFieldClassRefusal,
  type MatchesFilterOptions,
} from '@objectstack/formula';
import { ORGANIZATION_ADMIN_GRANTS } from '@objectstack/spec';
import type {
  AuthoredRowWriteOperation,
  AuthoredRowWriteVerdict,
  ControlledByParentWriteDenialLeg,
  ControlledByParentWriteOutcome,
  ControlledByParentWriteUnresolvedReason,
} from '@objectstack/spec/contracts';
import type { FieldMaskingRule } from '@objectstack/spec/data';
import type { PermissionSet } from '@objectstack/spec/security';
import type {
  AuthzPosture,
  ExplainDecision,
  ExplainLayer,
  ExplainMatchedRule,
  ExplainOperation,
  ExplainRecordAttribution,
} from '@objectstack/spec/security';
import type { PermissionEvaluator } from './permission-evaluator.js';
import { superuserBypassBitForOperation } from './permission-evaluator.js';
import { rlsOperationForVerb } from './lifecycle-verb-rls-operation.js';
import { ExplainObjectNotFoundError } from './errors.js';
import { RLS_DENY_FILTER, compiledObjectDefaultRowScopeOf, compiledPolicyNameOf } from './rls-compiler.js';
import { declaredComparisonColumns } from './declared-comparison-columns.js';
import {
  declaredJsonStoredColumns,
  findJsonColumnCheckRefusal,
  jsonColumnCheckRefusalError,
  type DeclaredJsonStoredColumns,
  type JsonColumnCheckRefusal,
} from './rls-check-stored-form.js';
import {
  unresolvedPostureExplainDetail,
  type UnresolvedPostureCause,
} from './unresolved-posture.js';
import { grantSetNameOf } from './grant-permission-set-name.js';

const SYSTEM_CTX = { isSystem: true } as const;

/** Owner field convention — mirrors plugin-sharing's `OWNER_FIELD` (single-owner MVP). */
const OWNER_FIELD = 'owner_id';

/**
 * [C2 / ADR-0095 D1] Which kernel tier a pipeline layer belongs to: the
 * always-first tenant wall (`layer_0_tenant`) vs. everything downstream of it
 * (business RLS / sharing / ownership / the capability gates), all
 * `layer_1_business`. The binary mirrors the enforcement split — Layer 0 has its
 * own code path and is AND-composed BEFORE any business rule.
 */
function kernelTierOf(layer: ExplainLayer['layer']): 'layer_0_tenant' | 'layer_1_business' {
  return layer === 'tenant_isolation' ? 'layer_0_tenant' : 'layer_1_business';
}

const AUTHZ_POSTURES: ReadonlySet<string> = new Set<AuthzPosture>([
  'PLATFORM_ADMIN',
  'TENANT_ADMIN',
  'MEMBER',
  'EXTERNAL',
]);
function isAuthzPosture(v: unknown): v is AuthzPosture {
  return typeof v === 'string' && AUTHZ_POSTURES.has(v);
}

/**
 * [C2 / ADR-0095 D2/D3] Resolve the principal's posture rung, using the SAME
 * evidence enforcement uses so the explain panel's tier can never sit HIGHER
 * than the runtime's (label-drift elimination — security review low-severity).
 *
 * Order of preference:
 *
 *  1. **guest / anonymous → EXTERNAL.** Explain layers one thing on top the
 *     enforcement resolver deliberately does NOT: a guest principal is EXTERNAL
 *     for the debugger. The enforcement floor is MEMBER (no external principal
 *     type exists yet — ADR-0095 D2), so this mapping lives here, and it wins
 *     first.
 *  2. **Reuse `ctx.posture` verbatim when present.** A principal resolved through
 *     the full `resolveAuthzContext` already carries the enforcement-derived
 *     rung; consuming it directly makes drift structurally impossible.
 *  3. **Fallback — re-derive from capability-grant evidence.** Reached only by a
 *     HAND-BUILT context (tests, an internal caller assembling `{ userId,
 *     positions, permissions }` itself). Since #6352 the explain API's
 *     `buildContextForUser` resolves through `resolveUserAuthzGrants` and
 *     therefore carries the enforcement-derived `posture`, so it lands on (2) —
 *     structurally, not by agreement. This branch derives from the SAME evidence
 *     `resolveAuthzContext` uses — NOT the previous loose permission-set-NAME
 *     match:
 *       - `PLATFORM_ADMIN` ← the **unscoped `admin_full_access` USER grant**
 *         (`hasPlatformAdminGrant`, which `buildContextForUser` READS OFF the
 *         resolver's own verdict rather than recomputing), and nothing else. A
 *         merely-SCOPED `admin_full_access` grant (name present in
 *         `permissions`, not held unscoped) does not over-label.
 *
 *         ⛔ [#15981] It is NOT ALSO the `platform_admin` built-in POSITION.
 *         That arm rested on the position being "only ever PROJECTED from that
 *         same grant", which stopped being true when `positions[]` became the
 *         security axis: it now carries ADR-0057 D4 `sys_user_position` names,
 *         and that table is `apiEnabled` with unconstrained `position` values,
 *         so a tenant could mint a row spelling the built-in. ⚠️ Reachability
 *         here was NARROWER than at #15981's three sibling sites, and it is
 *         worth stating precisely rather than overclaiming: preference (2)
 *         above returns first for any principal `buildContextForUser` builds,
 *         so the SHIPPING path never reached this line and a D4 row never moved
 *         it. What the name-read did reach was a posture-less HAND-BUILT
 *         context — and there it made the panel REPORT `PLATFORM_ADMIN` for a
 *         principal enforcement treats as a MEMBER. That is a misreport, not an
 *         admission — this engine explains, it does not admit — but it is a
 *         misreport in the tool an administrator opens to check exactly this,
 *         so it answered reassuringly wrong at the worst moment.
 *       - `TENANT_ADMIN` ← the `organization_admin` **capability** grant, exactly
 *         like enforcement (ADR-0095 D3). The better-auth `org_owner`/`org_admin`
 *         role positions are a provisioning source only and are no longer read
 *         as posture evidence — closing the same #2836 dual-track explain-side.
 */
function derivePosture(context: any): AuthzPosture {
  if (!context?.userId || context?.principalKind === 'guest') return 'EXTERNAL';
  if (isAuthzPosture(context?.posture)) return context.posture;
  const permissions: string[] = Array.isArray(context?.permissions) ? context.permissions : [];
  return deriveAdminPosture({
    isPlatformAdmin: context?.hasPlatformAdminGrant === true,
    isTenantAdmin: ORGANIZATION_ADMIN_GRANTS.some((n) => permissions.includes(n)),
  });
}

/**
 * The `explain`/sharing zero-rows deny sentinel — the one named in the PUBLISHED
 * `readFilter` contract (`ExplainDecisionSchema.readFilter`,
 * `ExplainRecordAttributionSchema.rowFilter`), produced by plugin-sharing's
 * `buildReadFilter`/`buildWriteFilter` and by this engine's own
 * `computeRlsFilter` catch fallback in §9 below.
 */
const DENY_ALL_SENTINEL_ID = '__deny_all__';

/**
 * True iff `filter` is THAT sentinel specifically — the narrow question, kept
 * apart from {@link isDenyAll} because §9's payload collapse is keyed to this
 * one value and must NOT follow the widened recognition (see below).
 */
function isDenyAllSentinel(filter: unknown): boolean {
  return !!filter && typeof filter === 'object' && (filter as { id?: unknown }).id === DENY_ALL_SENTINEL_ID;
}

/**
 * True iff `filter` is plugin-security's fail-closed RLS sentinel
 * (`RLS_DENY_FILTER`) — an `id` equality against a UUID-shaped string no record
 * can carry, so the SQL layer returns zero rows without raising.
 *
 * Identity is decided on the sentinel's own VALUE, not on its shape — the same
 * rule `isTenantWallDenial` states (ADR-0123 D2), and for the same reason:
 * producers SPREAD the frozen constant (`{ ...RLS_DENY_FILTER }`), so a
 * reference check would answer `false` for every real denial.
 */
function isRlsDenySentinel(filter: unknown): boolean {
  return !!filter && typeof filter === 'object' && (filter as { id?: unknown }).id === RLS_DENY_FILTER.id;
}

/**
 * [#13639] True iff a composed filter denies EVERY row — whichever of the two
 * sentinels the platform composed. ⭐ This is THE question the engine asks, and
 * every deny-recognition site routes through it.
 *
 * It used to recognise `__deny_all__` alone, and the object-level `rls` verdict
 * in §9 compared the same literal a second time, INLINE. So a fail-closed RLS
 * denial — the "no active organization" path, which composes `RLS_DENY_FILTER`
 * and is guaranteed to return zero rows — was reported as verdict `narrows`
 * with `decision.allowed: TRUE`. That is not an imprecise label; it is an
 * affirmatively wrong answer about a request that cannot return a row, handed
 * to the operator debugging exactly "why does this user see nothing?".
 *
 * ⛔ Recognition is deliberately all this widening does. The two sentinels are
 * NOT merged (`__deny_all__` is in the published spec schema and docs;
 * `__rls_deny__` is pinned as a bound SQL parameter by service-analytics and
 * dispatched on by value by `isTenantWallDenial`), and §9's payload
 * replacement is NOT extended to `__rls_deny__` — a deployment that receives
 * `{ id: '__rls_deny__:…' }` in `readFilter` today keeps receiving it. Both of
 * those are deployment-facing changes recorded on #13639 as the maintainer's.
 */
function isDenyAll(filter: unknown): boolean {
  return isDenyAllSentinel(filter) || isRlsDenySentinel(filter);
}

/**
 * A dependency call that REJECTED, kept apart from every value it could have
 * resolved to.
 *
 * The engine calls the functions enforcement calls, and enforcement runs them
 * un-caught: when one rejects, the request being explained FAILS. Folding that
 * rejection into an answer — `null` read as "no filter", `undefined` read as
 * "no gate wired", `{ kind: 'none' }` read as "no delegation" — explains a
 * request that fails as one that succeeds. {@link settle} hands back this
 * sentinel instead; each site reports its layer `not_evaluated` and its
 * verdict fail-closed, and never as an admission.
 */
const DEPENDENCY_FAULT: unique symbol = Symbol('explain.dependency-fault');

function settle<T>(call: Promise<T>): Promise<T | typeof DEPENDENCY_FAULT> {
  return call.then((value) => value, () => DEPENDENCY_FAULT);
}

/** Explain-operation → engine-operation (the middleware's vocabulary). */
const EXPLAIN_TO_ENGINE_OP: Record<ExplainOperation, string> = {
  read: 'find',
  create: 'insert',
  update: 'update',
  delete: 'delete',
  transfer: 'transfer',
  restore: 'restore',
  purge: 'purge',
  // [#3544] Not a copy-paste slip: `export` IS its own evaluator operation
  // (`read ∧ the export grant`). It is also the only entry whose data path
  // differs from its gate — see {@link dataOpOf}.
  export: 'export',
};

/**
 * [#3544] The operation every DATA-shaped layer must be computed as.
 *
 * `export` is gated as its own operation but performs an ordinary `find` to
 * fetch its rows, so requiredPermissions, OWD/depth/sharing, RLS and record
 * attribution all have to resolve as a READ. Asking the RLS compiler about an
 * `export` operation would match no policy and report "no RLS applies" for a
 * principal whose rows are in fact filtered — an explanation that contradicts
 * the export it is explaining. Only `object_crud` uses the gate operation,
 * because that is the only layer the axis changes.
 */
function dataOpOf(operation: ExplainOperation, engineOp: string): string {
  return operation === 'export' ? 'find' : engineOp;
}

export interface ExplainEngineDeps {
  ql: any;
  /** The middleware's own set resolution (baseline + everyone semantics included). */
  resolveSets: (context: any) => Promise<PermissionSet[]>;
  evaluator: PermissionEvaluator;
  getObjectSecurityMeta: (object: string) => Promise<{
    isPrivate: boolean;
    requiredPermissions: any;
    fieldRequiredPermissions: Record<string, string[]>;
    /** [#3545] Posture could not be read — the middleware denies (fail-closed). */
    unresolved?: boolean;
    /**
     * [#10401] Which condition that is — an unpublished draft, or a declaration
     * that genuinely cannot be read. Optional: a deps bag wired without it (or a
     * deployment whose probe could not run) explains as `'unknown'`, the wording
     * that covers both. Never an input to the verdict — only to the prose.
     */
    unresolvedCause?: UnresolvedPostureCause;
  }>;
  /** The middleware's requiredPermissions AND-gate resolution for an operation. */
  requiredCaps: (meta: any, engineOperation: string) => string[];
  /**
   * The middleware's RLS filter composition (same inputs, same output). Asked
   * for the operation the door composes the explained verb's row-level
   * security for ({@link rlsOperationForVerb}): a lifecycle verb arrives as its
   * write class, every other verb as itself.
   */
  computeRlsFilter: (
    sets: PermissionSet[],
    object: string,
    engineOperation: string,
    context: any,
  ) => Promise<Record<string, unknown> | null | undefined>;
  /** The middleware's merged FLS mask (field requiredPermissions folded in). */
  getFieldMask: (
    sets: PermissionSet[],
    object: string,
    fieldRequiredPermissions: Record<string, string[]>,
  ) => Record<string, { readable?: boolean; editable?: boolean }>;
  /**
   * [#9127] The middleware's EFFECTIVE partial-mask set for this caller — the
   * `partialRules` argument enforcement hands `FieldMasker.maskResults`, after
   * the explicit-deny exclusion. Keyed by field, valued by the rule that will
   * be applied.
   *
   * REQUIRED, deliberately. The field-mask decision has three outcomes
   * (deleted / partially masked / served whole) and the binary
   * {@link getFieldMask} can express only two, so an engine wired without this
   * would report a partially-masked field as fully hidden and a gate-less
   * rule field as fully readable — the exact misreport this dep exists to
   * close. An optional dep would have let a new embedder re-open it silently;
   * a required one makes the omission a compile error.
   *
   * Supply the enforcement composition, never a re-derivation of it: explain's
   * module contract is that it "matches enforcement by construction".
   */
  getPartialMaskRules: (
    sets: PermissionSet[],
    object: string,
    delegatorSets: PermissionSet[] | null,
  ) => Promise<Record<string, FieldMaskingRule>>;
  /**
   * Configured additive baseline set NAMES (default `['member_default']`), for
   * attribution.
   *
   * [#7555] A list, not a name: the baseline is the app-declared set COMPOSED
   * with the platform's `member_default`, so a report that attributed only one
   * of them would label the other "resolved" — the vaguest bucket `viaOf` has,
   * on the grant most likely to be the answer to "why can this member read
   * anything at all".
   */
  baselinePermissionSets: string[];

  // ── [C2 / ADR-0095] Record-grained deps. All OPTIONAL: absent → the engine
  // stays object-level and byte-compatible. Present → the sharing / rls / owd /
  // tenant_isolation layers gain per-record attribution. Every one reuses an
  // enforcement code path so the row story cannot drift from execution. ──

  /**
   * The middleware's RLS composition, SPLIT into its two independent kernel
   * layers (the same `Layer0(tenant) AND Layer1(business)` the effective filter
   * is built from). Lets the tenant wall (Layer 0) and business RLS (Layer 1) be
   * attributed to a record separately. `undefined` return = engine cannot split.
   * Asked for the same operation as {@link computeRlsFilter} (the explained
   * verb through {@link rlsOperationForVerb}), so a `transfer`'s row story is
   * composed as the update the door composes it as.
   */
  computeLayeredRlsFilter?: (
    sets: PermissionSet[],
    object: string,
    engineOperation: string,
    context: any,
  ) => Promise<{ layer0: Record<string, unknown> | null; layer1: Record<string, unknown> | null }>;
  /** Fetch the one record under a system context (organization_id / owner_id + fields for filter matching). */
  fetchRecord?: (object: string, recordId: string, engineOperation: string) => Promise<Record<string, unknown> | null>;
  /** The sharing service's own read-filter contribution for the object (owner-match OR granted-ids), same as enforcement AND-s in. */
  sharingReadFilter?: (object: string, context: any) => Promise<unknown | null>;
  /**
   * The concrete `sys_record_share` rows attached to the record (for `rules[]`
   * attribution).
   *
   * `access_level` stays wider than the authorable `read`/`edit`: explain
   * REPORTS stored rows, and a `full` row written before #3865 retired that
   * level (normalised to `edit` by the sharing plugin's boot backfill) must
   * still be explainable rather than crash the panel.
   */
  listRecordShares?: (
    object: string,
    recordId: string,
    context: any,
  ) => Promise<Array<{ id?: string; recipient_type?: string; recipient_id?: string; access_level?: 'read' | 'edit' | 'full'; source?: string; source_id?: string }>>;
  /** The sharing service's per-record UPDATE gate (`canEdit`) — the by-construction verdict for update operations. */
  canEditRecord?: (object: string, recordId: string, context: any) => Promise<boolean>;
  /**
   * [ADR-0111 D3] The sharing service's per-record DELETE gate (`canDelete`) —
   * the by-construction verdict for a delete operation. Narrower than
   * `canEditRecord`: an edit-level share opens update but not delete, so the
   * explanation for a `delete` must consult this rather than the update gate.
   */
  canDeleteRecord?: (object: string, recordId: string, context: any) => Promise<boolean>;
  /**
   * [#5493 / ADR-0105 D3] The by-id write gate's DEFERRAL: whether an
   * APP-AUTHORED row-level policy admits the row for the refusing gate's verb
   * (`ISecurityService.checkAuthoredRowWrite`, reached through the sharing
   * service's own probe). The sharing middleware asks it only after its
   * per-record gate refused the row, and only the literal `admit` lifts that
   * refusal: the row then goes on to the pre-image gate, which is the
   * row-level security this report's `rls` layer explains.
   *
   * Asked on the same condition here: for a by-id `update` or `delete` whose
   * gate above ({@link canEditRecord} / {@link canDeleteRecord}) answered
   * `false`, with that gate's verb and the context being EXPLAINED, and for a
   * `transfer` as an `update` (its door is the by-id update of `owner_id`,
   * which the update gate judges). Every
   * other answer leaves the refusal standing, and so does a rejection: the
   * door's probe catches its own failure and keeps its refusal, so a failing
   * probe is not a failing request and is not reported as one.
   *
   * Optional: a deps bag wired without it reports the gate's refusal as the
   * write verdict, as before.
   */
  probeAuthoredRowWrite?: (
    object: string,
    recordId: string,
    operation: AuthoredRowWriteOperation,
    context: any,
  ) => Promise<AuthoredRowWriteVerdict | string>;
  /**
   * [ADR-0055] The master-detail write check's own answer for a by-id UPDATE
   * of `recordId` by `context`: `ISecurityService.checkControlledByParentWrite`,
   * the composition step 2.8 of the write path runs. On a
   * `controlled_by_parent` record the per-record sharing gates above abstain
   * (the object's effective model is `public`), so they cannot be a write's
   * verdict there: this check is, and the door refuses on every outcome but
   * `allow` and `not_applicable`.
   *
   * Asked for every by-id write step 2.8 runs the check on
   * ({@link MASTER_CHECKED_BY_ID_WRITES}: `update`, `delete`, `transfer`,
   * `restore`, `purge`) of a record that exists, with the context being
   * EXPLAINED. The update's answer is each of those writes' answer: the check
   * judges EDIT access to the master whatever the record's own verb, and reads
   * the verb only to pick its `insert` branch. The member holds the
   * `controlled_by_parent` predicate, so the engine keeps no second copy of it:
   * `not_applicable` leaves the report exactly as it was. A rejection (a
   * context the write path refuses, or a store fault) is a dependency fault,
   * reported fail-closed.
   *
   * Optional: a deps bag wired without it explains each write from the sharing
   * gates alone, as before, and claims nothing about a master.
   */
  checkControlledByParentWrite?: (
    object: string,
    recordId: string,
    context: any,
  ) => Promise<ControlledByParentWriteOutcome>;
  /**
   * [#21771] Enforcement's own read question for an addressed by-id write:
   * would the read door, asked by this principal, NOT return the record?
   * `true` only for absence; a read-time policy refusal answers `false`, and a
   * store fault propagates — exactly as the write path asks it, so the
   * explanation cannot drift from the answer the write gets.
   *
   * [#22571] Asked for every explained verb whose door is a by-id update or
   * delete, read through {@link rlsOperationForVerb}: `update`, `delete`, and
   * the lifecycle verbs that map onto them (`transfer` and `restore` onto
   * update, `purge` onto delete).
   *
   * [ADR-0055] Asked for a record-grained read too, of a
   * `controlled_by_parent` record the rest of the read's row story admits: the
   * read door also scopes such a record by its master, a leg no other
   * dependency here answers, so the door's own answer is what the read verdict
   * takes ({@link applyRecordAttribution}).
   *
   * [#22792] Asked first of the ASKER, for every record-grained
   * self-explanation: whether the explanation may say the record exists is
   * decided by the read access of whoever asked for it, not by the explained
   * principal's (the asker gate in the engine's record pass). [#22851] An
   * asker explaining ANOTHER principal is asked the same caller-context by-id
   * read through the security service's own binding, where a declared refusal
   * counts as "cannot read" too (ruling C); this dependency keeps the write
   * path's notion, which a principal explaining itself is asked.
   */
  recordAbsentToCaller?: (object: string, recordId: string, context: any) => Promise<boolean>;
}

export interface ExplainInput {
  object: string;
  operation: ExplainOperation;
  /** Execution context of the principal being EXPLAINED (not the caller). */
  context: any;
  /**
   * [C2 / ADR-0095] Optional id of ONE concrete record to explain at row
   * granularity. Omitted → object-level (the report is byte-identical to the
   * pre-C2 engine). Present → the row-scoped layers gain a `record` attribution,
   * the tenant wall surfaces as the `tenant_isolation` Layer 0, every layer is
   * tagged with its `kernelTier`, the principal's `posture` is resolved, and the
   * decision carries a top-level `record` verdict.
   */
  recordId?: string;
}

/** The ADR-0091 `valid_until` of a grant row, as the panel prints it. */
function untilOfGrantRow(r: any): string | undefined {
  const v = r?.valid_until ?? r?.validUntil;
  return v == null || v === '' ? undefined : String(v);
}

/**
 * [commit 42b05af89] One entry of the shared "held but not resolving, because X"
 * vocabulary (the internal counterpart of the spec contract's
 * `contributors[].state`): a grant row the principal HOLDS that the resolver
 * fail-closed DROPPED, with the closed reason enumeration naming why —
 * `expired` (ADR-0091 D2 validity window) or `deactivated` (ADR-0049 / #8613
 * switch, read from the `sys_metadata_activation` ledger). `until` is the window bound, present only for
 * the expired reason. One array, one reason discriminant — deliberately NOT a
 * sibling array per cause (maintainer ruling 2026-08-18).
 */
export interface DroppedGrant {
  kind: 'position' | 'permission_set';
  name: string;
  state: 'expired' | 'deactivated';
  until?: string;
}

/**
 * [#6352 / ADR-0091 D2/D3 / commit 42b05af89] The explain-ONLY provenance pass: the
 * annotations the panel prints that the authorization resolver, correctly,
 * throws away.
 *
 * This is presentation, not aggregation. It decides nothing about who is
 * authorized — `resolveUserAuthzGrants` has already decided that, and this pass
 * never feeds `positions` / `permissions` / the `platform_admin` derivation. It
 * only re-reads the same rows to answer questions the resolver's output
 * cannot express, because the resolver's output is by construction the set of
 * grants that DID resolve:
 *
 *  - **expired** — a row whose `valid_until` has passed, so the panel can say
 *    "held until … — expired" instead of silently omitting a grant the admin
 *    knows they granted. This is "why did access DISAPPEAR", and only a dropped
 *    row can answer it.
 *  - **deactivated** (commit 42b05af89) — a row whose position or permission
 *    set is switched off (ADR-0049 / #8613), so the grant stopped resolving
 *    for everyone holding it. The switch is the activation ledger's
 *    (`sys_metadata_activation`, ADR-0126 §3 regime C as ADR-0131 D6 amends
 *    it), asked through the resolver's own read (`readDisabledCatalogNames`),
 *    so explain and enforce cannot disagree; a catalog row's `active` column
 *    is not read. Deactivation is an incident-response control with no date on the
 *    user's own grant row, so without this state the set is simply ABSENT and
 *    explain answers like the grant never existed — the exact silence the
 *    contributor-attribution feature exists to prevent.
 *  - **delegated** — the `delegated_from` provenance of a row that DID resolve,
 *    so a position can be attributed "via delegation from X, until Y".
 *
 * All verdicts come from the SAME shared reads the resolver uses
 * (`isGrantActive` / `isGrantExpired` for the ADR-0091 window,
 * `readDisabledCatalogNames` for the ADR-0049 switch, the security catalog
 * (`securityCatalogReaderOf`) for whether a set exists — all
 * `@objectstack/core`) — one implementation of each rule, consulted twice,
 * never re-derived here.
 *
 * A row that is BOTH expired and deactivated reports `expired`: the window
 * verdict is judged on the user's own grant row, the same order the resolver
 * drops in, and each dropped row carries exactly one reason (closed enum).
 *
 * Boundary (the ruling's cheaper sketch, deliberately): deactivation is
 * re-read for the grants this pass already walks — `sys_user_position` rows
 * and direct `sys_user_permission_set` grants. A deactivated position held via
 * role projection, or a deactivated SET reached only through an active
 * position's `permissionSets`, is not re-derived here — that would replicate
 * the resolver's aggregation, which is the design this pass exists to avoid.
 */
async function collectGrantProvenance(
  ql: any,
  userId: string,
  nowMs: number,
): Promise<{
  droppedGrants: DroppedGrant[];
  delegatedPositions: Array<{ name: string; from: string; until?: string }>;
}> {
  const droppedGrants: DroppedGrant[] = [];
  const delegatedPositions: Array<{ name: string; from: string; until?: string }> = [];

  try {
    const rows = await ql.find('sys_user_position', { where: { user_id: userId }, limit: 500, context: SYSTEM_CTX });
    // Window-ACTIVE position names — held now, so the only thing that can
    // still drop them is the catalogue `active` switch, checked below.
    const heldPositionNames = new Set<string>();
    for (const r of Array.isArray(rows) ? rows : []) {
      const p = String((r as any)?.position ?? '');
      if (!p) continue;
      if (isGrantActive(r, nowMs)) {
        heldPositionNames.add(p);
        const from = (r as any)?.delegated_from;
        if (from != null && from !== '') {
          delegatedPositions.push({ name: p, from: String(from), until: untilOfGrantRow(r) });
        }
      } else if (isGrantExpired(r, nowMs)) {
        // Pending (future `valid_from`) rows are inactive but NOT expired — they
        // are not reported, because nothing was lost yet.
        droppedGrants.push({ kind: 'position', name: p, state: 'expired', until: untilOfGrantRow(r) });
      }
    }
    // [commit 42b05af89 / ADR-0049] A held position the activation ledger
    // switched off was dropped by the resolver (step 6a) — report it instead of
    // letting it vanish. The resolver's own ledger read, so a name with no
    // ledger row is in effect here exactly as it is there.
    if (heldPositionNames.size > 0) {
      const disabled = await readDisabledCatalogNames(ql, Array.from(heldPositionNames), []);
      for (const n of heldPositionNames) {
        if (disabled.positions.has(n)) droppedGrants.push({ kind: 'position', name: n, state: 'deactivated' });
      }
    }
  } catch { /* table unavailable → no provenance to report */ }

  try {
    const rows = await ql.find('sys_user_permission_set', { where: { user_id: userId }, limit: 500, context: SYSTEM_CTX });
    // [ADR-0131 D4] A grant names its set (`permission_set`); one that names
    // nothing ({@link grantSetNameOf}) reports nothing — it resolves no set.
    const grantRows = (Array.isArray(rows) ? rows : []).filter((g: any) => grantSetNameOf(g) !== undefined);
    const expiredRows = grantRows.filter((g: any) => !isGrantActive(g, nowMs) && isGrantExpired(g, nowMs));
    // Window-ACTIVE direct grants: resolvable unless the SET's catalogue row is
    // deactivated — the one remaining reason the resolver drops them (step 6b).
    const activeRows = grantRows.filter((g: any) => isGrantActive(g, nowMs));
    if (expiredRows.length > 0 || activeRows.length > 0) {
      // [ADR-0131 D3/D4] A grant's set is the security catalog's definition of
      // the name it carries — the one the resolver grants (step 6). A name the
      // catalog does not hold resolves nothing either way, so it is reported
      // neither as expired nor as deactivated: there is no set to lose.
      const catalog = securityCatalogReaderOf(ql);
      const held = new Set<string>();
      for (const g of [...expiredRows, ...activeRows]) {
        const n = grantSetNameOf(g) as string;
        if (!held.has(n) && catalog && (await catalog.resolve('permission', n))) held.add(n);
      }
      for (const g of expiredRows) {
        const n = grantSetNameOf(g) as string;
        if (held.has(n)) droppedGrants.push({ kind: 'permission_set', name: n, state: 'expired', until: untilOfGrantRow(g) });
      }
      // [commit 42b05af89 / ADR-0049] Whether a held set is switched off is the
      // activation ledger's answer, read once for every name a window-active
      // grant carries — the resolver's own read. Several grant rows can name
      // one deactivated set; the fact is reported once.
      const activeNames = [...new Set(activeRows.map((g: any) => grantSetNameOf(g) as string))].filter((n) => held.has(n));
      if (activeNames.length > 0) {
        const disabled = await readDisabledCatalogNames(ql, [], activeNames);
        for (const n of activeNames) {
          if (disabled.permissions.has(n)) droppedGrants.push({ kind: 'permission_set', name: n, state: 'deactivated' });
        }
      }
    }
  } catch { /* table unavailable → no provenance to report */ }

  return { droppedGrants, delegatedPositions };
}

/**
 * Reconstruct an evaluation context for an arbitrary user, for the explain API's
 * `userId` parameter. The caller-facing authorization for explaining OTHERS
 * lives in the route/service wrapper (`explainAccessForCaller`), not here.
 *
 * [#6352] **The authorization aggregation is not implemented here.** It is
 * `@objectstack/core`'s `resolveUserAuthzGrants` — the userId-driven core of
 * `resolveAuthzContext`, i.e. the exact function every inbound request resolves
 * through, called with the exact arguments (`ql`, `userId`, the ADR-0091 clock).
 * So the positions (`sys_member` role projection + `sys_user_position` + the
 * ADR-0090 D5 `everyone` anchor), the permission-set names (user-bound AND
 * position-bound), the ADR-0091 validity windows, the ADR-0068 D2 `platform_admin`
 * derivation, the ADR-0095 posture rung and the ADR-0105 D2 `accessible_org_ids`
 * are all ONE implementation, not two kept in step by comment.
 *
 * This used to be a hand-written mirror whose only guarantee was two comments
 * saying it matched. It did not: measured over identical rows it dropped the
 * `sys_member` role positions, every position-bound permission set
 * (`sys_position_permission_set`), the `ai_seat` synthesis, `systemPermissions`
 * and the posture rung — so a user whose grants arrive through a POSITION was
 * explained as holding nothing, and the panel reported a deny that enforcement
 * did not make. That is the failure mode the panel exists to prevent, so the
 * mirror is gone rather than pinned.
 *
 * What stays explain-side is presentation only, and additive: the dropped-grant
 * (expired / deactivated) and delegated row annotations
 * ({@link collectGrantProvenance}), and `hasPlatformAdminGrant`, which is now
 * READ OFF the resolver's own posture verdict instead of being recomputed from
 * the grant rows.
 *
 * [#20515] `tenantId` is the organization the user is resolved IN, handed to
 * the resolver exactly as enforcement hands it — the resolver applies an
 * organization-scoped grant only while its organization is the active tenant,
 * and with no tenant only the global grants. There is no "every organization"
 * reading: the explainer used to get one by passing no tenant, which is the
 * very resolution that kept a removed member's grants. Each caller passes the
 * organization it is explaining in — the live principal's for a delegator
 * ({@link resolveDelegatorContext}), the caller's own for the explain API.
 * [#20580] The explain API passes the caller's organization only once
 * `vetOrganizationClaim` (`@objectstack/core`) has let it stand for the
 * explained user, as enforcement does for that user's session claim: this
 * function passes on what it is handed and vets nothing itself.
 * Omitted, the context is the user with NO active organization. The returned
 * context still carries no `tenantId` of its own; a caller that needs one sets
 * it, as {@link resolveDelegatorContext} does, and as the explain API does
 * (#20604) with the organization it resolved the user in.
 */
export async function buildContextForUser(
  ql: any,
  userId: string,
  nowMs: number = Date.now(),
  tenantId?: string,
): Promise<any> {
  // [#11971] ⭐ Ruled bypass of the #11633 leg-B grants cache (maintainer
  // acceptance 2026-08-25): the explainer is the tool an administrator uses to
  // VERIFY that a revocation took effect. An explainer answering from cache
  // would explain a state that no longer exists — and would do it at exactly
  // the moment someone is checking. `explain` therefore takes the force-fresh
  // path unconditionally, whatever `OS_AUTHZ_GRANTS_CACHE_TTL_MS` says.
  const grants = await resolveUserAuthzGrants(ql, userId, { tenantId, nowMs, bypassGrantsCache: true });
  const { droppedGrants, delegatedPositions } = await collectGrantProvenance(ql, userId, nowMs);
  return {
    userId,
    positions: grants.positions,
    permissions: grants.permissions,
    systemPermissions: grants.systemPermissions,
    org_user_ids: grants.org_user_ids,
    accessible_org_ids: grants.accessible_org_ids,
    ...(grants.tabPermissions ? { tabPermissions: grants.tabPermissions } : {}),
    ...(grants.email != null ? { email: grants.email } : {}),
    ...(grants.posture ? { posture: grants.posture } : {}),
    droppedGrants,
    delegatedPositions,
    // [ADR-0068 D2] Not a second derivation: `derivePosture` returns
    // PLATFORM_ADMIN if and only if the resolver saw the unscoped
    // `admin_full_access` USER grant, so this reads that one verdict back.
    hasPlatformAdminGrant: grants.posture === 'PLATFORM_ADMIN',
  };
}

/**
 * [ADR-0090 D10] Result of resolving the delegator behind an on-behalf-of
 * principal. `none` = no delegation link; `missing` = the link names a user that
 * does not exist (the caller must fail CLOSED — see {@link resolveDelegatorContext});
 * `resolved` = the delegator's reconstructed evaluation context.
 */
export type DelegatorResolution =
  | { kind: 'none' }
  | { kind: 'missing'; userId: string }
  | { kind: 'resolved'; context: any };

/**
 * [ADR-0090 D10 — agent intersection] Resolve the evaluation context of the USER
 * behind an agent/service principal that acts `onBehalfOf` them. The effective
 * permission of the delegated principal is the INTERSECTION of its own grants
 * and this delegator's grants (confused-deputy prevention) — never the union —
 * so every enforcement layer combines the two set-lists with AND.
 *
 * Semantics this helper pins down (single-sourced for the middleware AND the
 * explain engine so enforcement and its explanation can never drift):
 *
 *  - **Fail-closed on a dangling link (edge b).** A `missing` delegator must be
 *    reported as such by the caller and denied — NOT resolved to empty sets:
 *    `resolvePermissionSetsForContext` synthesises the additive `member_default`
 *    baseline for ANY `userId`, so a deleted delegator would otherwise still
 *    intersect against baseline-level access. The `sys_user` existence check is
 *    the only correct fail-closed point.
 *  - **Tenant-scoped bags are inherited from the live principal, and the
 *    inheritance still WINS.** The agent and its delegator are, by construction,
 *    in the same org, so `tenantId` / `org_user_ids` carry over — delegator-side
 *    RLS that substitutes them then compiles faithfully instead of collapsing to
 *    the deny sentinel. Since #6352, `buildContextForUser` returns the resolver's
 *    own `org_user_ids`; the live principal's org peer set is the answer the
 *    delegated request runs under, so the assignment below overwrites it
 *    exactly as before. The delegator's GRANTS are the one tenant-scoped thing
 *    resolved rather than copied: since #20515 they are resolved IN the live
 *    principal's organization, so a delegator grant scoped to that organization
 *    applies and one scoped to any other does not.
 *    `accessible_org_ids` (ADR-0105 D2) is the exception: it is resolved from
 *    the DELEGATOR's own memberships by `buildContextForUser`, never inherited,
 *    because inheriting it would widen a delegated read past the organizations
 *    the delegator actually belongs to.
 *  - **Person-specific membership bags (`rlsMembership`) are left unresolved.**
 *    Absent → the RLS compiler's fail-closed substitution NARROWS the
 *    delegator's row set, never widens it — safe by construction. #6352 routed
 *    the delegator through the shared resolver (`resolveUserAuthzGrants`), which
 *    closed the positions / permission-set / posture half of this gap; the
 *    team/territory bags are not part of that envelope on either side, so they
 *    remain a follow-up for the `RlsMembershipResolver` contract rather than for
 *    this function.
 *  - **One hop only (edge a).** The `onBehalfOf` shape carries a single delegator
 *    id with no nested link, so a transitive agent→service→user chain is not
 *    representable in one context. Intersecting against the immediate delegator
 *    is a safe lower bound on the true multi-hop intersection (each hop only
 *    narrows), so this never escalates; true chain-walk is a producer-side
 *    follow-up that collapses the chain to the ultimate human delegator.
 *  - **Trigger is the LINK, not the label (edge d).** A `service` acting for a
 *    user is the identical confused-deputy risk as an `agent`; both intersect.
 *    `principalKind` stays advisory. `human`/`system`/`guest` never carry
 *    `onBehalfOf` in practice, so they are unaffected.
 */
export async function resolveDelegatorContext(
  ql: any,
  context: any,
  nowMs: number = Date.now(),
): Promise<DelegatorResolution> {
  const oboId = context?.onBehalfOf?.userId;
  if (!oboId) return { kind: 'none' };
  let user: any = null;
  try {
    user = await ql.findOne('sys_user', { where: { id: oboId }, context: SYSTEM_CTX });
  } catch {
    user = null;
  }
  if (!user) return { kind: 'missing', userId: String(oboId) };
  // [#20515] The delegator's GRANTS are resolved in the live principal's
  // organization — the organization the delegated request runs in, which this
  // function already hands the delegator's context below. Resolved with no
  // tenant, the delegator leg would hold only global grants (and before the
  // resolver's no-tenant rule, every organization's), never the grants the
  // delegator actually holds where the request runs.
  const liveTenantId = typeof context?.tenantId === 'string' && context.tenantId !== ''
    ? context.tenantId
    : undefined;
  const dctx = await buildContextForUser(ql, oboId, nowMs, liveTenantId);
  // Inherit tenant-scoped substitution bags from the live principal (same org).
  if (context?.tenantId != null) dctx.tenantId = context.tenantId;
  if (context?.org_user_ids != null) dctx.org_user_ids = context.org_user_ids;
  // [ADR-0105 D2] The delegator's own org access set is NOT inherited — it is
  // the delegator's membership that bounds a delegated read, and
  // `buildContextForUser` resolves it for them. Inheriting the live principal's
  // set would widen the delegator past their own memberships.
  if (user.email != null && user.email !== '') dctx.email = user.email;
  return { kind: 'resolved', context: dctx };
}

const SCOPE_ORDER = ['own', 'own_and_reports', 'unit', 'unit_and_below', 'org'] as const;

/**
 * [ADR-0090 D10] The NARROWER of two access-depth scopes (min rank). Unknown
 * values clamp to the narrowest (`own`, fail-closed). Used to intersect the
 * agent's and the delegator's effective read/write depth so the stash that
 * flows to plugin-sharing carries the tighter of the two.
 */
export function narrowerScope(a: string, b: string): string {
  const rank = (s: string): number => {
    const i = SCOPE_ORDER.indexOf(s as (typeof SCOPE_ORDER)[number]);
    return i < 0 ? 0 : i;
  };
  return rank(a) <= rank(b) ? a : b;
}

/**
 * [ADR-0090 D10 — maintainer ruling 2026-09-08, option 1] The depth the
 * DELEGATED principal's own leg contributes, and whether that leg is what
 * narrowed the read.
 *
 * **The rule: a ceiling that says nothing subtracts nothing.** `ceilingScope`
 * is `PermissionEvaluator.getDeclaredScope` — `undefined` when every set the
 * delegated principal holds is silent about depth. Silence is "no opinion", so
 * this leg contributes NO owner narrowing (`'org'`) and every row bound comes
 * from the delegator's leg, which plugin-sharing AND-s in beside it. A ceiling
 * that DOES declare a depth contributes exactly that depth, unchanged.
 *
 * ⚠️ This is deliberately NOT `narrowerScope(ceiling, delegator)`. The
 * OWD/sharing owner-match is IDENTITY-scoped: `__readScope` bounds the AGENT
 * identity's owner-match and `__delegatorReadScope` bounds the DELEGATOR's, and
 * the true intersection is the AND of the two filters (`sharing-plugin.ts`).
 * Folding the minimum into this leg would scope the agent identity to the
 * delegator's depth — `owner_id = agentId` at the delegator's depth — hiding
 * the very rows the delegator legitimately owns.
 *
 * Why the rule exists, in one measurement: `mcp_agent_data_read` /
 * `mcp_agent_data_write` are pure CAPABILITY ceilings — `{'*': {allowRead:
 * true, …}}`, no `readScope`, no `viewAllRecords`, and their own doc comment
 * says "NO row-level security … all row/owner/tenant narrowing comes from the
 * delegating user". `getEffectiveScope` nonetheless answered `'own'` for them
 * (its owner-only default for a granting-but-silent set), so this leg imposed
 * an owner-match nobody declared and a `viewAllRecords` sales manager who reads
 * 9 accounts / 23 opportunities / 45 tasks through the Console or a per-user
 * API key read 5 / 0 / 0 through an OAuth MCP client — silently, `total: 0`,
 * with the agent then reporting "there are no opportunities this quarter" as
 * fact.
 *
 * ⛔ This widens VISIBILITY DEPTH only, and only on the SILENT-ceiling input.
 * Every other subtraction is decided elsewhere and is unchanged — see the
 * subtraction table on `MCP_AGENT_PERMISSION_SET_READ` in
 * `objects/default-permission-sets.ts`.
 *
 * `narrowedByCeiling` is the diagnostic half of the same ruling: true iff the
 * ceiling's OWN declared depth is strictly narrower than the delegator's, i.e.
 * the delegated read is answering from a row set THIS leg shrank — and the MCP
 * `query_records` result must then SAY so rather than serve a bare count.
 */
export function intersectDelegatedScope(
  ceilingScope: string | undefined,
  delegatorScope: string,
): { agentLegScope: string; narrowedByCeiling: boolean } {
  if (ceilingScope === undefined) {
    return { agentLegScope: 'org', narrowedByCeiling: false };
  }
  return {
    agentLegScope: ceilingScope,
    narrowedByCeiling: narrowerScope(ceilingScope, delegatorScope) !== delegatorScope,
  };
}

/**
 * [ADR-0090 D10 — ruling 2026-09-08, consequence 2] The sentence a delegated
 * read carries when the ceiling narrowed it.
 *
 * ONE spelling, so the explain path (`layer: 'object_crud'` / `depth`) and the
 * MCP tool result cannot describe the same intersection differently. It states
 * the DIRECTION of the error — the row set is a subset, the count is not a fact
 * about the data — because the consumer being corrected is an AI that would
 * otherwise report `total: 0` as an answer.
 */
export function d10NarrowingStatement(input: {
  object: string;
  delegatorId: string;
  effectiveScope: string;
  delegatorScope: string;
}): string {
  return (
    `This result was narrowed by the ADR-0090 D10 intersection: the agent principal acting on behalf of `
    + `${input.delegatorId} is capped at '${input.effectiveScope}' record depth on ${input.object}, while `
    + `${input.delegatorId} alone reaches '${input.delegatorScope}'. Rows outside that depth are ABSENT from `
    + `this result and are NOT absent from the object — do not report this count as a fact about the data. `
    + `Ask ${input.delegatorId} to re-run the question under their own credentials to see the full set.`
  );
}

/**
 * [ADR-0090 D10] Intersect two FLS masks. A field is readable/editable in the
 * result only if it is readable/editable on BOTH sides. A field ABSENT from a
 * side is unconstrained on that side (the FieldMasker leaves unlisted fields
 * fully visible/editable), so an absent side contributes `true` — the AND then
 * lets the OTHER side's constraint win. Net effect: the intersection hides or
 * write-locks every field that EITHER principal hides or write-locks.
 */
export function intersectFieldMasks(
  a: Record<string, { readable?: boolean; editable?: boolean }>,
  b: Record<string, { readable?: boolean; editable?: boolean }>,
): Record<string, { readable: boolean; editable: boolean }> {
  const out: Record<string, { readable: boolean; editable: boolean }> = {};
  const keys = new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})]);
  for (const k of keys) {
    const ar = k in a ? a[k]?.readable !== false : true;
    const ae = k in a ? a[k]?.editable !== false : true;
    const br = k in b ? b[k]?.readable !== false : true;
    const be = k in b ? b[k]?.editable !== false : true;
    out[k] = { readable: ar && br, editable: ae && be };
  }
  return out;
}

/**
 * [#9127] Render a `maskingRule` for the report. PRESENTATION ONLY — it never
 * decides whether the rule applies (that is enforcement's call, arriving via
 * `deps.getPartialMaskRules`); it only names the rule the caller's masked
 * value was produced by, so an admin reading "why is this `138****5678`" gets
 * the preset or the explicit span instead of a bare field name.
 */
function describeMaskingRule(rule: FieldMaskingRule): string {
  return typeof rule === 'string' ? rule : `keepHead ${rule.keepHead}, keepTail ${rule.keepTail}`;
}

/** D1-equivalent OWD reading (mirrors plugin-sharing's effectiveSharingModel). */
function describeOwd(schema: any): { model: string; declared: boolean; effect: 'private' | 'read' | 'public' } {
  const m = schema?.sharingModel ?? schema?.security?.sharingModel;
  if (m === 'private') return { model: 'private', declared: true, effect: 'private' };
  if (m === 'public_read') return { model: 'public_read', declared: true, effect: 'read' };
  if (m === 'public_read_write' || m === 'controlled_by_parent') {
    return { model: String(m), declared: true, effect: 'public' };
  }
  if (m == null) {
    const isSystem = schema?.isSystem === true || String(schema?.name ?? '').startsWith('sys_');
    return isSystem
      ? { model: '(unset, system default: public)', declared: false, effect: 'public' }
      : { model: "(unset → 'private', ADR-0090 D1 fail-closed default)", declared: false, effect: 'private' };
  }
  return { model: `${String(m)} (unknown → private, fail-closed)`, declared: true, effect: 'private' };
}

/** [ADR-0055] What each refusing leg of the master-detail write check means, for the report's prose. */
const MASTER_DENIAL_LEG_DETAIL: Record<ControlledByParentWriteDenialLeg, string> = {
  object_permission: 'the principal holds no object-level update grant on a master',
  row_level_security: "a master row is outside the principal's write row-level security on that master",
  record_sharing:
    'record sharing does not let the principal edit a master row, and no app-authored update policy on that ' +
    'master admits it',
  master_chain: 'the controlled_by_parent chain cannot be walked to a master that governs its own rows',
};

/**
 * [ADR-0055] Why the master-detail write check reached no verdict, and what the
 * write answers instead. The answer is the same for every by-id write the check
 * runs on: each condition throws one error class whatever the verb.
 */
const MASTER_UNRESOLVED_DETAIL: Record<ControlledByParentWriteUnresolvedReason, { condition: string; answer: string }> = {
  master_detail_relation_missing: {
    condition:
      'the object declares controlled_by_parent without exactly one required master_detail field to derive access from',
    answer: '422 INVALID_METADATA',
  },
  record_not_found: { condition: 'the record does not exist', answer: '404 RECORD_NOT_FOUND' },
  master_reference_missing: { condition: "the record's master reference is empty", answer: '422 MISSING_REQUIRED_FIELD' },
};

const MASTER_DERIVED = 'Write access to this record derives from its master (controlled_by_parent, ADR-0055)';
const MASTER_READ_DERIVED = 'Read access to this record derives from its master (controlled_by_parent, ADR-0055)';

/**
 * [ADR-0055] The record-grained writes whose verdict on a `controlled_by_parent`
 * record the master-detail write check decides: every write step 2.8 of the
 * write path runs that check on (the guard of step 2.8 in `security-plugin.ts`)
 * that addresses one existing record by id.
 *
 * `insert` is the one verb step 2.8 runs on that is not here. Its master is read
 * off the request BODY, which an explanation does not carry, and it addresses
 * no existing record, so a record-grained `create` has no master check to ask.
 *
 * One answer serves every verb here. Whatever the record's own verb, the check
 * judges EDIT access to the master (the object-level `update` grant, the
 * master's write row-level security and record sharing, on every hop up the
 * chain) and reads the verb only to pick its `insert` branch.
 * `masterGateCoversOperation` states the same fact for the ownership floor's
 * hand-over: deleting a child does not delete its master. So the answer the
 * served member computes for an update is the answer step 2.8 gives each of
 * these writes, and the engine asks it for each.
 *
 * `restore` and `purge` are refused at the object gate for every principal
 * until their grants return, so the object-level CRUD layer decides their
 * record verdict first. They are listed because step 2.8 lists them, so the
 * report stays the door's on the day they can be granted.
 */
const MASTER_CHECKED_BY_ID_WRITES: ReadonlySet<string> = new Set(['update', 'delete', 'transfer', 'restore', 'purge']);

/**
 * [ADR-0055] The sharing layer's record attribution for a by-id write the
 * master-detail write check REFUSES — the check that decides such a write of a
 * `controlled_by_parent` record — or `undefined` where it does not refuse.
 * `verb` is the write being explained (one of
 * {@link MASTER_CHECKED_BY_ID_WRITES}), named in the prose.
 *
 * The mapping is the door's: the write proceeds on `allow` and on
 * `not_applicable`, and is refused on every other outcome, one outside the
 * vocabulary included (fail closed). A proceeding outcome leaves the report
 * exactly as the rest of the pipeline computes it. ⛔ It does not name the
 * master on `allow`: the member answers `allow` for a system context on ANY
 * object (the write path's first exit), so `allow` is not evidence that the
 * record's access derives from a master at all.
 */
function masterWriteCheckRefusal(
  outcome: ControlledByParentWriteOutcome,
  verb: string,
): { outcome: ExplainRecordAttribution['outcome']; detail: string } | undefined {
  switch (outcome?.outcome) {
    case 'allow':
    case 'not_applicable':
      return undefined;
    case 'deny':
      return {
        outcome: 'excluded',
        detail: `${MASTER_DERIVED}: the master-detail write check the by-id ${verb} runs refuses this ${verb} on its ` +
          `'${outcome.leg}' leg — ${MASTER_DENIAL_LEG_DETAIL[outcome.leg] ?? 'a leg this report does not describe'}. ` +
          `The ${verb} answers 403 PERMISSION_DENIED.`,
      };
    case 'unresolvable': {
      const unresolved = MASTER_UNRESOLVED_DETAIL[outcome.reason];
      return {
        outcome: 'not_evaluated',
        detail: `${MASTER_DERIVED}, and the master-detail write check reaches no verdict ('${outcome.reason}'): ` +
          `${unresolved ? `${unresolved.condition}, and the ${verb} answers ${unresolved.answer}` : 'a reason this report does not describe'}. ` +
          'The record is reported NOT writable (fail closed), never admitted.',
      };
    }
    default:
      return {
        outcome: 'not_evaluated',
        detail: `${MASTER_DERIVED}, and the master-detail write check answered an outcome this report does not ` +
          'recognise. The record is reported NOT writable (fail closed), never admitted.',
      };
  }
}

/**
 * [#20431] The object's declared columns, handed to the record matcher so it
 * applies the spec's cross-field comparison class (`crossFieldComparisonVerdict`)
 * — the rule driver-sql applies when it compiles the find this report explains,
 * and the rule the RLS write check applies to the same policy (`options.fields`
 * of `matchesFilterCondition`, #20355).
 *
 * Read off `ql.getSchema`, the schema the engine already reads for the OWD: the
 * ObjectQL registry is the declaration the find's driver compiles against. A
 * schema that cannot be read hands over no columns, and the matcher then judges
 * values only, as it did before — a missing schema never manufactures a refusal.
 *
 * [#20604] What the declaration says about each column is
 * {@link declaredComparisonColumns}, the reading the RLS write check hands the
 * same matcher, so the two judges of one policy cannot read one declaration
 * two ways.
 */
function declaredColumnsOf(schema: any): MatchesFilterOptions | undefined {
  return declaredComparisonColumns(schema);
}

/**
 * The members of a composed row filter that can each be one policy's compiled
 * filter: a `$or` of policies (Layer 1 with several applicable policies), and
 * the `$and` that puts the tenant wall, or a delegator's filter, beside it.
 * A node `compiledPolicyNameOf` recognises is a member however it is shaped.
 */
function policyMembersOf(node: unknown): unknown[] {
  if (node === null || typeof node !== 'object' || compiledPolicyNameOf(node) !== undefined) return [node];
  const keys = Object.keys(node as Record<string, unknown>);
  const list = keys.length === 1 && (keys[0] === '$and' || keys[0] === '$or')
    ? (node as Record<string, unknown>)[keys[0]]
    : undefined;
  return Array.isArray(list) ? list.flatMap(policyMembersOf) : [node];
}

/**
 * [#24164 ruling E′] The object default row scopes a composed row filter
 * applies: each member {@link policyMembersOf} finds whose compiled filter the
 * compiler recorded as an object's declared default, once per policy name.
 * Empty when every member came from a held permission set (the default only
 * ever applies to an empty collection, so a filter is one or the other).
 */
function objectDefaultRowScopesOf(filters: readonly unknown[]): Array<{ name?: string; label?: string; description?: string }> {
  const out = new Map<string, { name?: string; label?: string; description?: string }>();
  for (const filter of filters) {
    for (const member of policyMembersOf(filter)) {
      const scope = compiledObjectDefaultRowScopeOf(member);
      if (scope && !out.has(scope.name ?? '')) out.set(scope.name ?? '', scope);
    }
  }
  return [...out.values()];
}

/**
 * [#24164 ruling E′] The sentence explain adds where an object's default row
 * scope is the row-level predicate: the source is the object's declaration,
 * named with the label and description it declares, never a permission set.
 */
function objectDefaultRowScopeSource(
  object: string,
  scopes: ReadonlyArray<{ name?: string; label?: string; description?: string }>,
): string {
  const named = scopes
    .map((scope) => {
      const about = [scope.label, scope.description].filter(
        (text): text is string => typeof text === 'string' && text.trim() !== '',
      );
      return `'${scope.name ?? '(unnamed)'}'${about.length > 0 ? ` (${about.join(' — ')})` : ''}`;
    })
    .join(', ');
  return (
    ` Source: the object default row scope ${named} declared on '${object}', not a permission set — ` +
    'no permission set held carries a row policy for this object and operation.'
  );
}

/**
 * [#20431] The names of the policies in a compiled row filter whose own filter
 * `refuses` — the attribution the RLS write check logs for the same refusal.
 * The composed filter is one policy's filter, `{ $or: [...] }` of them, or (the
 * object-level pass, #20604) either one `$and`-composed beside the tenant wall
 * or a delegator's filter; `compiledPolicyNameOf` recognises each policy by
 * identity ({@link policyMembersOf}).
 *
 * [#21319] `refuses` is the rule of the refusal being answered: the spec's
 * comparison-class rule for a field-to-field comparison, the JSON-column rule
 * for an operator the read refuses on a declared JSON-stored column.
 */
function refusedPolicyNamesOf(
  filter: Record<string, unknown>,
  refuses: (member: Record<string, unknown>) => boolean,
): string[] {
  const names = policyMembersOf(filter)
    .filter((m) => refuses(m as Record<string, unknown>))
    .map((m) => compiledPolicyNameOf(m) ?? '(unnamed)');
  return [...new Set(names)];
}

/**
 * [#20431] Who carries a refused filter, as explain's refusal names it: the
 * policies {@link refusedPolicyNamesOf} found, or the filter itself when it
 * found none.
 */
function refusalSubjectOf(object: string, policies: readonly string[]): string {
  return policies.length === 0
    ? `A row-level filter on '${object}'`
    : `The row-level security ${policies.length === 1 ? 'policy' : 'policies'} ` +
      `${policies.map((p) => `'${p}'`).join(', ')} on '${object}'`;
}

/**
 * [#20431] Why explain answers with a refusal and no verdict. The last sentence
 * of every refusal explain gives, so it is the part a long subject may cut.
 */
const EXPLAIN_ANSWERS_THE_REFUSAL =
  'Enforcement refuses every request this filter scopes (the find answers INVALID_FILTER / 400), so explain answers ' +
  'with the same refusal and reports no verdict.';

/**
 * [#21319] How explain's JSON-column refusal names the filters it judged in
 * the refusal's `path` ({@link findJsonColumnCheckRefusal}): the row filters a
 * read runs under, which the report calls `rowFilter`.
 */
const ROW_FILTER_ROOT = 'rowFilter';

/**
 * [#20431] What explain answers when the record matcher refuses a
 * field-to-field comparison: enforcement's own refusal. The code and status
 * are the matcher's (`INVALID_FILTER` / 400, the envelope the find answers),
 * and the matcher's error rides as `cause`.
 *
 * The message names the policy and both columns, where the matcher's own
 * message withholds them. The matcher withholds them because the caller of a
 * refused find or write is usually not the policy's author. Explain is the tool
 * that shows a principal the policy it runs under, and the report it gives the
 * same caller for the same object publishes the same predicate: `readFilter`
 * without a `recordId`, the `rls` layer's `rowFilter` with one. So naming the
 * policy and its two columns here discloses nothing that report does not.
 *
 * The remedy leads, BEFORE the subject. The REST door bounds a 4xx message
 * (`CLIENT_MESSAGE_MAX` in `@objectstack/rest`: 500 characters or more is cut
 * to 499 plus an ellipsis), and the subject and the diagnostic have no length
 * bound: object, field and policy names declare no maximum, and the subject
 * lists every refused policy. So no subject-first order can keep a trailing
 * remedy on the wire for every policy; at index 0 it survives any length. The
 * reason comes last and is the part a long subject may cut.
 */
function crossFieldRefusalForExplain(
  cause: unknown,
  refusal: CrossFieldClassRefusal,
  object: string,
  filter: unknown,
  fields: NonNullable<MatchesFilterOptions['fields']>,
): Error {
  const policies = filter !== null && typeof filter === 'object'
    ? refusedPolicyNamesOf(filter as Record<string, unknown>, (m) => findCrossFieldClassRefusal(m, fields) !== null)
    : [];
  const err = new Error(
    'Compare a field only with a field of the same class, or fix the declaration of the one that is ' +
      `declared with the wrong type. ${refusalSubjectOf(object, policies)} cannot be evaluated: ` +
      `${refusal.diagnostic}. ${EXPLAIN_ANSWERS_THE_REFUSAL}`,
  );
  const { code, status } = cause as { code?: string; status?: number };
  return Object.assign(err, { code, status, cause });
}

/**
 * [#21319] What explain answers when a row filter aims an operator the read
 * refuses at a column the object declares JSON-stored: the read's refusal.
 *
 * The read a policy scopes is compiled by the driver, which refuses
 * `@objectstack/core`'s `JSON_COLUMN_INCOMPATIBLE_OPERATORS`, and implicit
 * equality, on such a column with `INVALID_FILTER` / 400 whatever the rows; the
 * RLS write check refuses the same operators since #21254. The record matcher
 * would evaluate them instead, so explain answered `visible: true`, decided by
 * the policy, for a record whose find was refused. The rule is the write
 * check's, imported ({@link findJsonColumnCheckRefusal}): one operator set and
 * one traversal for the three judges of one policy, and ⛔ no copy of either.
 *
 * The shape is {@link crossFieldRefusalForExplain}'s, so explain gives one
 * answer shape for every refusal: a thrown error with no decision, carrying
 * the refusal as its `cause` and taking its code and status from it. The
 * cause is the error the write check throws for the same refusal (core's
 * message, the read's envelope), so the envelope has one constructor here.
 *
 * The message is core's diagnostic (`jsonColumnOperatorRefusalText`), which
 * names the field and the operator, then the policy that carries it, for the
 * reason the cross-class refusal names its columns: explain publishes the
 * same predicate to the same caller. Core's own message withholds both and
 * points to the server log; explain logs nothing, so that sentence would be
 * false here. The diagnostic leads because it holds the remedy: its length
 * grows only with the field's name, while the subject lists every refusing
 * policy, so under the REST door's bound a subject-first order would cut the
 * remedy for long policy names. The subject and the reason come last.
 */
function jsonColumnRefusalForExplain(
  refusal: JsonColumnCheckRefusal,
  object: string,
  filter: Record<string, unknown>,
  jsonStored: DeclaredJsonStoredColumns,
): Error {
  const cause = jsonColumnCheckRefusalError(refusal);
  const policies = refusedPolicyNamesOf(
    filter,
    (m) => findJsonColumnCheckRefusal([m], jsonStored, ROW_FILTER_ROOT) !== null,
  );
  const err = new Error(
    `${refusal.diagnostic} ${refusalSubjectOf(object, policies)} cannot be evaluated. ${EXPLAIN_ANSWERS_THE_REFUSAL}`,
  );
  const { code, status } = cause as { code?: string; status?: number };
  return Object.assign(err, { code, status, cause });
}

/**
 * [#20431] The record matcher, handed the object's declared columns, with its
 * refusal answered the way explain answers it: a field-to-field comparison of
 * no shared comparison class becomes {@link crossFieldRefusalForExplain}, and
 * any other refusal of the matcher's propagates as the matcher raised it.
 *
 * [#21319] Before the matcher reads the record, the filter is judged by the
 * JSON-column rule the read and the write check apply: an operator in
 * `JSON_COLUMN_INCOMPATIBLE_OPERATORS`, or implicit equality, aimed at a column
 * the object declares JSON-stored becomes {@link jsonColumnRefusalForExplain}.
 * It reads the declaration, never the record, so it refuses for every record
 * or for none. What still answers on such a column is unchanged: the
 * membership pair (`$contains` / `$notContains`) and the presence predicates.
 * No declared columns → no JSON-stored column → no judgement, as before.
 */
function matchUnderDeclaredColumns(
  record: Record<string, unknown>,
  filter: unknown,
  object: string,
  declaredColumns: MatchesFilterOptions | undefined,
): boolean {
  if (filter !== null && typeof filter === 'object') {
    const node = filter as Record<string, unknown>;
    const jsonStored = declaredJsonStoredColumns(declaredColumns);
    const jsonRefusal = findJsonColumnCheckRefusal([node], jsonStored, ROW_FILTER_ROOT);
    if (jsonRefusal) throw jsonColumnRefusalForExplain(jsonRefusal, object, node, jsonStored);
  }
  try {
    return matchesFilterCondition(record, filter as any, declaredColumns);
  } catch (e) {
    const refusal = crossFieldClassRefusalCarriedBy(e);
    if (refusal && declaredColumns?.fields) {
      throw crossFieldRefusalForExplain(e, refusal, object, filter, declaredColumns.fields);
    }
    throw e;
  }
}

/**
 * [#20604] Refuse, as enforcement does, a composed row filter the find cannot
 * run — before any verdict is computed from it.
 *
 * The object-level pass used to publish the composed filter as a fact: `rls`
 * `narrows`, the predicate as `readFilter`, `allowed: true`. For a filter
 * comparing two columns of no shared comparison class, enforcement runs no
 * such request: driver-sql refuses to compile the read, so the find answers
 * `INVALID_FILTER` / 400 whatever the rows, a by-id write whose pre-image read
 * is that filter fails closed (403), and an insert whose check judges it is
 * refused (400). Measured on the real stack: the report said `allowed: true`
 * for every operation, for both orderings of one pair, and a record id no row
 * carries was reported `visible: false` with no decider, because the record
 * matcher never ran.
 *
 * The judgement is the record matcher's own, not a second rule: the matcher
 * judges the declared columns before it reads a record ("refused for every
 * record or for none"), so it is asked with no row, and its refusal is
 * answered by {@link matchUnderDeclaredColumns}, exactly as the record-grained
 * pass answers it. ⛔ No second refusal dialect: the envelope, the message and
 * the `cause` are the record-grained pass's. It is asked only when the spec's
 * classification finds a refused comparison, so no filter the find runs is
 * evaluated here. No declared columns → no judgement, as before.
 *
 * [#21319] The same holds for an operator the read refuses on a declared
 * JSON-stored column, measured the same way: the object-level report said
 * `allowed: true` with `rls` `narrows` for every operation, and a record id no
 * row carries was reported `visible: false`, while the find answered 400. So
 * the JSON-column rule ({@link findJsonColumnCheckRefusal}) is the second
 * classification that asks {@link matchUnderDeclaredColumns}, which answers it.
 */
function refuseWhatTheMatcherRefuses(
  filter: unknown,
  object: string,
  declaredColumns: MatchesFilterOptions | undefined,
): void {
  const fields = declaredColumns?.fields;
  if (!fields || filter === null || typeof filter !== 'object') return;
  const node = filter as Record<string, unknown>;
  if (
    findCrossFieldClassRefusal(node, fields) === null &&
    findJsonColumnCheckRefusal([node], declaredJsonStoredColumns(declaredColumns), ROW_FILTER_ROOT) === null
  ) return;
  matchUnderDeclaredColumns({}, filter, object, declaredColumns);
}

/**
 * [C2 / ADR-0095] Inputs the record-grained augmentation needs from the already
 * computed object-level pass — the row story is decomposed FROM the same facts,
 * never re-judged.
 */
interface RecordAttributionContext {
  deps: ExplainEngineDeps;
  object: string;
  recordId: string;
  engineOp: string;
  /**
   * [#22550] The operation the record's row-level security is composed for:
   * `engineOp` through {@link rlsOperationForVerb}, as the by-id write
   * pre-image gate (step 2.7) maps it. Only the RLS composition reads it; every
   * other row judgement (the write gate, the master-detail check, the prose)
   * keeps the verb as asked.
   */
  rlsOp: string;
  context: any;
  sets: PermissionSet[];
  layers: ExplainLayer[];
  owd: { model: string; effect: 'private' | 'read' | 'public' };
  capsDeny: boolean;
  crudAllowed: boolean;
  /**
   * [#4647] Whether the object-level pass found the View/Modify All Data bypass
   * EFFECTIVE for this operation (already D10-intersected, already
   * operation-scoped to the right bit). The row story consumes the verdict the
   * `vama_bypass` layer published — it never re-derives it — so the layer, the
   * record attribution and the write gate stay one answer.
   */
  vamaEffective: boolean;
  /** [#4647] The sets that carry the bypass, for the row-level detail text. */
  vamaSets: string[];
  /** [#20431] The object's declared columns ({@link declaredColumnsOf}); absent → values only. */
  declaredColumns: MatchesFilterOptions | undefined;
  /**
   * The effective depth the object-level `depth` layer published for this
   * operation (ADR-0057 D1, already D10-intersected). The row story reads the
   * layer's own value, never a second evaluator call, so the depth layer's
   * object-level detail and its record block name one depth.
   */
  depthScope: string;
}

/**
 * [C2 / ADR-0095] Fill the per-record row story onto the pipeline. Prepends the
 * `tenant_isolation` Layer 0, tags every layer with its `kernelTier`, attaches a
 * `record` attribution to the row-scoped layers (tenant / owd / depth / sharing /
 * vama_bypass / rls), and returns the top-level `record` verdict. Every row-level judgement is
 * evaluated with the SAME artifacts enforcement produces:
 *   - Layer 0 / Layer 1 filters come from `computeLayeredRlsFilter` (the middleware's
 *     own `Layer0(tenant) AND Layer1(business)` split);
 *   - "does THIS record satisfy the filter?" is `matchesFilterCondition` — the
 *     third canonical backend for the same FilterCondition shape the query runs —
 *     handed the object's declared columns, so it refuses what the query refuses;
 *   - the write verdict is the sharing service's own `canEdit`.
 * So the record story is explained by construction, exactly like the object-level pass.
 */
async function applyRecordAttribution(
  ra: RecordAttributionContext,
): Promise<{ record: NonNullable<ExplainDecision['record']>; posture: AuthzPosture }> {
  const {
    deps, object, recordId, engineOp, rlsOp, context, sets, layers, owd, capsDeny, crudAllowed, vamaEffective, vamaSets,
    declaredColumns, depthScope,
  } = ra;
  const isRead = engineOp === 'find';
  const posture = derivePosture(context);

  const record = deps.fetchRecord
    ? await deps.fetchRecord(object, recordId, engineOp).catch(() => null)
    : null;
  const recordExists = record != null;
  // [#20431] Given the declared columns, the matcher REFUSES a field-to-field
  // comparison between two columns of no shared comparison class, with
  // `INVALID_FILTER` / 400, for every record or for none. That is the
  // comparison the find's driver refuses to compile. Without the columns, the
  // matcher compared the two raw values, so the report answered `visible` true
  // or false, depending on how they happened to compare, for a request
  // enforcement refuses outright. Explain now answers with the refusal, the way
  // it already answers the matcher's other `INVALID_FILTER` refusals: the
  // explanation fails with the envelope the find fails with, and no record
  // verdict is reported.
  // [#21319] The same answer, by the same seam, for an operator the read
  // refuses on a column the object declares JSON-stored (a multi-valued field,
  // or a structured-JSON type): `matchUnderDeclaredColumns` judges it before
  // the matcher reads the record.
  const matches = (filter: unknown): boolean | undefined => {
    if (!recordExists) return undefined;
    if (filter == null) return true;
    return matchUnderDeclaredColumns(record as Record<string, unknown>, filter, object, declaredColumns);
  };

  // The composition enforcement runs before the query: when it throws, neither
  // layer answered, so neither may read as "contributes nothing".
  // [#22550] Composed for `rlsOp`, the door's operation for this verb. Composed
  // for the raw verb, a `transfer` reached the RLS compiler as a READ
  // (`mapOperationToRLS` sends an unlisted verb to `select`), so no
  // update-class policy and no ownership floor reached its verdict: a row an
  // update policy excludes was reported writable beside the door's 403.
  const layeredOrFault = deps.computeLayeredRlsFilter
    ? await settle(deps.computeLayeredRlsFilter(sets, object, rlsOp, context))
    : undefined;
  const layeredFault = layeredOrFault === DEPENDENCY_FAULT;
  const layered = layeredOrFault === DEPENDENCY_FAULT ? undefined : layeredOrFault;
  const layer0 = layered?.layer0;
  const layer1 = layered?.layer1;
  const layeredFaultDetail = (layerName: string): string =>
    `${layerName} could not be evaluated: the row-level security composition threw, and enforcement ` +
    'fails the request on the same call — so the record is reported NOT visible (fail closed), never admitted.';

  // ── Layer 0: tenant_isolation (prepended as the always-first layer) ──────
  let tenantRecord: ExplainRecordAttribution;
  if (!recordExists) {
    tenantRecord = { outcome: 'not_evaluated', rules: [], detail: 'Record not found under a system read — filtered, deleted, or never existed.' };
  } else if (layeredFault) {
    tenantRecord = { outcome: 'not_evaluated', rules: [], detail: layeredFaultDetail('Layer 0 (the tenant wall)') };
  } else if (layered === undefined) {
    tenantRecord = { outcome: 'not_evaluated', rules: [], detail: 'Tenant layer split is unavailable on this engine build.' };
  } else if (layer0 == null) {
    tenantRecord = {
      outcome: 'not_evaluated', rowFilter: null, rules: [],
      detail: 'Layer 0 contributes nothing here — single-tenant mode, a non-tenant object, or a platform-admin crossing the wall (ADR-0095 D1).',
    };
  } else {
    const deny = isDenyAll(layer0);
    const m = matches(layer0);
    const excluded = deny || m === false;
    tenantRecord = {
      outcome: excluded ? 'excluded' : 'admitted',
      rowFilter: layer0,
      matchesRecord: deny ? false : m,
      rules: [{
        kind: 'tenant_filter',
        name: 'organization_isolation',
        predicate: layer0,
        via: context?.tenantId ? `organization ${context.tenantId}` : 'organization wall',
        effect: excluded ? 'excludes' : 'admits',
      }],
      detail: deny
        ? 'No active organization on the context — the tenant wall denies all rows (fail closed).'
        : excluded
          ? `Record's organization does not match the caller's active organization (${context?.tenantId ?? 'none'}).`
          : `Record is inside the caller's active organization (${context?.tenantId ?? 'none'}).`,
    };
  }
  layers.unshift({
    layer: 'tenant_isolation',
    kernelTier: 'layer_0_tenant',
    verdict: tenantRecord.outcome === 'excluded' ? 'denies' : layer0 ? 'narrows' : 'not_applicable',
    detail: 'Layer 0 tenant isolation — the always-first org wall, AND-composed before any business RLS (ADR-0095 D1).',
    contributors: [],
    record: tenantRecord,
  });

  // ── owd_baseline: ownership + the record baseline's own contribution ─────
  const ownerRaw = recordExists ? (record as Record<string, unknown>)[OWNER_FIELD] : undefined;
  const hasOwnerField = recordExists && OWNER_FIELD in (record as Record<string, unknown>);
  const ownerIsMe = ownerRaw != null && context?.userId != null && String(ownerRaw) === String(context.userId);
  const owdLayer = layers.find((l) => l.layer === 'owd_baseline');
  if (owdLayer) {
    const owdRules: ExplainMatchedRule[] = [{
      kind: 'owd_baseline',
      name: owd.model,
      effect: owd.effect === 'private' ? (ownerIsMe ? 'admits' : 'excludes') : 'admits',
      via: `OWD ${owd.model}`,
    }];
    if (hasOwnerField) {
      owdRules.push({
        kind: 'ownership',
        name: OWNER_FIELD,
        via: ownerIsMe ? 'owner' : `owned by ${ownerRaw ?? 'nobody'}`,
        effect: ownerIsMe ? 'admits' : 'neutral',
      });
    }
    owdLayer.record = !recordExists
      ? { outcome: 'not_evaluated', rules: [], detail: 'Record not found; baseline not evaluated.' }
      : {
          outcome: owd.effect === 'private' ? (ownerIsMe ? 'admitted' : 'excluded') : 'admitted',
          matchesRecord: owd.effect === 'private' ? ownerIsMe : true,
          rules: owdRules,
          detail: owd.effect === 'private'
            ? (ownerIsMe
                ? 'Caller owns the record — the private baseline admits it.'
                : 'Private baseline admits only the owner; a share or sharing rule may still widen access (see the sharing layer).')
            : `Baseline ${owd.model} admits the record at the row level; capability and field layers still apply.`,
        };
  }

  // ── sharing: the concrete shares + the sharing service's filter/gate ─────
  const shares = deps.listRecordShares && recordExists
    ? await deps.listRecordShares(object, recordId, context).catch(() => [])
    : [];
  const shareRules: ExplainMatchedRule[] = (shares ?? []).map((s) => {
    const recipMatchesUser = s.recipient_type === 'user' && s.recipient_id != null && String(s.recipient_id) === String(context?.userId);
    const kind: ExplainMatchedRule['kind'] =
      s.source === 'rule' ? 'sharing_rule' : s.source === 'team' ? 'team' : 'record_share';
    return {
      kind,
      name: String(s.source_id || s.id || 'share'),
      grants: s.access_level,
      via: `${s.recipient_type ?? 'user'}:${s.recipient_id ?? '?'}`,
      // A group/role/unit recipient can't be confirmed against the principal
      // without expansion → reported `neutral` (evaluated, effect unknown here).
      effect: recipMatchesUser ? 'admits' : 'neutral',
    };
  });
  // A rejected read filter is not a `null` one: the matcher reads `null` as
  // "no filter" and admits the row, while the find it explains fails.
  const sharingFilterOrFault = deps.sharingReadFilter && recordExists
    ? await settle(deps.sharingReadFilter(object, context))
    : undefined;
  const readFilterFault = sharingFilterOrFault === DEPENDENCY_FAULT;
  const sharingFilter = sharingFilterOrFault === DEPENDENCY_FAULT ? undefined : sharingFilterOrFault;
  const sharingMatches = sharingFilter === undefined ? undefined : matches(sharingFilter);
  // Write ops: the by-construction verdict is the sharing service's own gate.
  // [ADR-0111 D3] delete has its own narrower gate (an edit share does not
  // confer delete), so a `delete` explanation consults canDelete, not canEdit.
  const writeGate = engineOp === 'delete' ? deps.canDeleteRecord : deps.canEditRecord;
  // A rejected gate is not an absent one: "no gate wired" hands the verdict to
  // ownership and read shares, while the by-id write it explains fails.
  const canEditOrFault = !isRead && writeGate && recordExists
    ? await settle(writeGate(object, recordId, context))
    : undefined;
  const writeGateFault = canEditOrFault === DEPENDENCY_FAULT;
  const canEdit = canEditOrFault === DEPENDENCY_FAULT ? undefined : canEditOrFault;
  // [#5493 / ADR-0105 D3] The by-id write gate DEFERS before it refuses: when
  // its per-record gate refuses an `update` or a `delete`, the sharing
  // middleware asks whether an app-authored row-level policy admits the row
  // for that verb, and only `admit` lifts the refusal, handing the row to the
  // pre-image gate (the `rls` layer below). Asked on that condition alone, so
  // a row the gate admits, abstains on or faulted on is explained as before;
  // every answer but `admit`, and a rejection, keeps the refusal, as at the door.
  // A transfer's door is the by-id update of `owner_id`, so it is deferred as
  // an update; restore and purge have no by-id door (the object gate refuses
  // both), so nothing defers them.
  const authoredDeferralVerb: AuthoredRowWriteOperation | undefined =
    engineOp === 'update' || engineOp === 'transfer' ? 'update' : engineOp === 'delete' ? 'delete' : undefined;
  const authoredRowWriteAdmits = canEdit === false && authoredDeferralVerb && deps.probeAuthoredRowWrite
    ? (await deps.probeAuthoredRowWrite(object, recordId, authoredDeferralVerb, context).catch(() => 'abstain')) === 'admit'
    : false;
  // [ADR-0055] A by-id write of a `controlled_by_parent` record (an update, a
  // delete, a transfer: {@link MASTER_CHECKED_BY_ID_WRITES}) is judged by the
  // master-detail write check (step 2.8), which the sharing gate above cannot
  // stand in for: it abstains on such a record, and its abstention reads as
  // `true`. So the check is asked for every such write of a record that exists,
  // with the explained context, and it decides whether it applies: `allow` and
  // `not_applicable` change nothing, every other outcome refuses
  // ({@link masterWriteCheckRefusal}). A rejection is the request failing,
  // exactly as for the gate.
  const masterOrFault = MASTER_CHECKED_BY_ID_WRITES.has(engineOp) && recordExists && deps.checkControlledByParentWrite
    ? await settle(deps.checkControlledByParentWrite(object, recordId, context))
    : undefined;
  const masterFault = masterOrFault === DEPENDENCY_FAULT;
  const masterRefusal = masterOrFault === undefined || masterOrFault === DEPENDENCY_FAULT
    ? undefined
    : masterWriteCheckRefusal(masterOrFault, engineOp);
  // [ADR-0055] A record-grained read of a `controlled_by_parent` record meets
  // a master leg too: the read door ANDs the record's master-derived read scope
  // (the master ids the principal can read, the chain included) into the find,
  // beside the row-level security above, and the sharing service imposes
  // nothing of its own on such an object (its effective model is `public`).
  // No other dependency answers that leg, so the read door's own by-id read is
  // asked (`recordAbsentToCaller`, the question the by-id writes ask), with the
  // explained context, and only where every leg this report models admits the
  // record: there the master leg is the one left that withholds it. A record
  // the door withholds is reported NOT visible, as the door answers, on the
  // sharing layer, the layer the write verbs' master check names. A rejection
  // fails the find, so it is reported fail-closed.
  const readStoryAdmits = isRead && recordExists && owd.model === 'controlled_by_parent'
    && !capsDeny && crudAllowed && !layeredFault && !readFilterFault
    && tenantRecord.outcome !== 'excluded'
    && !(layer1 != null && (isDenyAll(layer1) || matches(layer1) === false));
  const masterReadOrFault = readStoryAdmits && deps.recordAbsentToCaller
    ? await settle(deps.recordAbsentToCaller(object, recordId, context))
    : undefined;
  const masterReadFault = masterReadOrFault === DEPENDENCY_FAULT;
  const masterReadRefusal: { outcome: ExplainRecordAttribution['outcome']; detail: string } | undefined =
    masterReadOrFault === true
      ? {
          outcome: 'excluded',
          detail: `${MASTER_READ_DERIVED}: the read door, asked by this principal, does not return the record, though ` +
            "every row-level layer above admits it, so its master is outside the principal's read scope" +
            (context?.onBehalfOf?.userId != null
              ? " (on this on-behalf-of read, the delegator's read scope is composed in as well)"
              : '') +
            '. The record is reported NOT visible, as the read door answers.',
        }
      : undefined;
  // One master leg per verb: the write check for a by-id write, the read
  // door's master scope for a read. At most one of the two is ever asked.
  const masterLegRefusal = masterRefusal ?? masterReadRefusal;
  // The sharing call THIS operation's row verdict rests on: the read filter for
  // a read (the sharing middleware ANDs it into every find), the per-record gate
  // for a write (the middleware gates every by-id write on it). Either one
  // rejecting fails the request whatever the OWD, so it is judged before the
  // baseline is.
  const sharingFaultDetail = isRead
    ? (readFilterFault
        ? "The sharing service's read filter could not be evaluated: it threw, and the find fails on the same " +
          'call — so the record is reported NOT visible (fail closed), never admitted.'
        : masterReadFault
          ? `${MASTER_READ_DERIVED}, and the read door's own by-id read of it could not be evaluated: it threw, and ` +
            'the find fails on the same call — so the record is reported NOT visible (fail closed), never admitted.'
          : undefined)
    : (writeGateFault
        ? `The sharing service's per-record ${engineOp === 'delete' ? 'delete' : 'update'} gate could not be ` +
          'evaluated: it threw, and the by-id write fails on the same call — so the record is reported NOT ' +
          'writable (fail closed), never admitted.'
        : masterFault
          ? 'The master-detail write check (controlled_by_parent, ADR-0055) could not be evaluated: it rejected — ' +
            `a refusal of the context or a store fault — and the by-id ${engineOp} fails on the same call, so the ` +
            'record is reported NOT writable (fail closed), never admitted.'
          : undefined);
  const anyShareAdmits = shareRules.some((r) => r.effect === 'admits');
  // ── read depth: did the depth-widened owner-match admit THIS row? ────────
  // The sharing read filter is ONE predicate carrying two grants: the
  // owner-match, which the read depth widens (own → [me], unit → my unit's
  // owners, org → no owner-match at all, ADR-0057 D1), OR-ed with the ids of the
  // caller's own shares. So "the filter admits the row" does not say WHICH half
  // admitted it. Read off facts this pass already holds: a filter match on a row
  // the caller neither owns nor holds a share on came from the owner-match
  // beyond the caller, which only a depth wider than `own` can reach.
  //   - An on-behalf-of read hands plugin-sharing the delegated context with no
  //     depth stamped, so its owner-match never widens there.
  //   - Below `org`, a `null` filter means the sharing service imposes no
  //     owner-match on this object at all (no owner column, a bypass object),
  //     which no depth produced.
  const delegatedRead = context?.onBehalfOf?.userId != null;
  const depthWidens = depthScope !== 'own';
  const depthAdmitsRow = isRead && recordExists && !sharingFaultDetail && owd.effect === 'private'
    && !delegatedRead && depthWidens
    && sharingMatches === true && !ownerIsMe && !anyShareAdmits
    && (depthScope === 'org' || sharingFilter !== null);
  let sharingOutcome: ExplainRecordAttribution['outcome'];
  if (!recordExists) {
    sharingOutcome = 'not_evaluated';
  } else if (sharingFaultDetail) {
    sharingOutcome = 'not_evaluated';
  } else if (masterLegRefusal) {
    sharingOutcome = masterLegRefusal.outcome;
  } else if (owd.effect !== 'private') {
    sharingOutcome = 'not_evaluated'; // baseline already grants the rows sharing would add
  } else if (canEdit !== undefined) {
    sharingOutcome = canEdit ? 'admitted' : 'excluded';
  } else if (depthAdmitsRow) {
    sharingOutcome = 'not_evaluated'; // read depth already admits the row sharing would add
  } else if (ownerIsMe || anyShareAdmits || sharingMatches === true) {
    sharingOutcome = 'admitted';
  } else if (sharingFilter === undefined && shares.length === 0) {
    sharingOutcome = 'not_evaluated';
  } else {
    sharingOutcome = 'excluded';
  }
  const sharingLayer = layers.find((l) => l.layer === 'sharing');
  if (sharingLayer) {
    sharingLayer.record = {
      outcome: sharingOutcome,
      // A faulted layer publishes no predicate and no match: neither is the
      // judgement behind a `not_evaluated` outcome.
      rowFilter: sharingFaultDetail || sharingFilter === undefined ? undefined : sharingFilter,
      matchesRecord: sharingFaultDetail ? undefined : sharingMatches,
      rules: shareRules,
      // A fault is only ever recorded against an existing record, and the
      // master leg [ADR-0055] is only ever asked of one.
      detail: sharingFaultDetail ?? masterLegRefusal?.detail ?? (!recordExists
        ? 'Record not found; sharing not evaluated.'
        : owd.effect !== 'private'
          ? 'Baseline is not private — sharing adds nothing beyond it for this record.'
          : canEdit !== undefined
            ? (canEdit
                // [#4647] Name the REAL reason the gate admitted the row. The
                // write gate consults the Modify All Data bypass after
                // ownership and shares, so "the sharing service grants write"
                // would be a false attribution for a bypass holder — precisely
                // the mis-reporting this issue was filed on, inverted.
                ? (!ownerIsMe && !anyShareAdmits && vamaEffective
                    ? `The write gate admits this record via the Modify All Data bypass [${vamaSets.join(', ')}], ` +
                      'not ownership or a share (see the vama_bypass layer).'
                    : 'The sharing service grants write on this record (ownership or an edit/full share).')
                : 'No ownership and no edit/full share grants write on this record.' +
                  (authoredRowWriteAdmits
                    ? ` The by-id ${engineOp} does not stop at that refusal: an app-authored row-level ${authoredDeferralVerb} ` +
                      'policy admits this record, so the write gate defers to row-level security (see the rls layer).'
                    : ''))
            : depthAdmitsRow
              ? `${shareRules.length} share(s) attached; none grants the caller access to this record — read depth ` +
                `'${depthScope}' already admits it, so sharing adds nothing here (see the depth layer).`
              : sharingOutcome === 'admitted'
                // A grant is named only where one exists: a share naming the
                // caller. A filter that admits the row without one says which
                // part of the sharing service let it through instead.
                ? (ownerIsMe
                    ? 'Caller owns the record — visible without a share.'
                    : anyShareAdmits
                      ? `${shareRules.length} share(s) attached; access is granted for this record.`
                      : sharingFilter === null
                        ? `${shareRules.length} share(s) attached; none grants the caller access, but the sharing ` +
                          'service imposes no owner-match on this object (rowFilter null), so the record is admitted without one.'
                        : `The sharing service's read filter admits this record (see rowFilter), but none of the ` +
                          `${shareRules.length} share(s) attached names the caller directly.`)
                : `${shareRules.length} share(s) attached; none grants the caller access to this record.` +
                  (vamaEffective
                    ? ` Superseded by the View/Modify All Data bypass [${vamaSets.join(', ')}] — see the vama_bypass layer.`
                    : '')),
    };
  }

  // ── depth: what the read depth did to THIS row ───────────────────────────
  // Judged from the facts above (`depthAdmitsRow`), never from a second filter.
  // A row a share admits as well keeps `sharing` as its decider, the last layer
  // to admit it in pipeline order (`decidedBy`'s published contract); below
  // `org`, the one predicate cannot say whether the depth reached its owner
  // too, so that cell says so rather than guess.
  const depthLayer = layers.find((l) => l.layer === 'depth');
  if (depthLayer) {
    const ownerLabel = String(ownerRaw ?? 'nobody');
    const depthRecord = (outcome: ExplainRecordAttribution['outcome'], detail: string): ExplainRecordAttribution =>
      ({ outcome, rules: [], detail });
    depthLayer.record = !recordExists
      ? depthRecord('not_evaluated', 'Record not found; read depth not evaluated.')
      : !isRead
        ? depthRecord('not_evaluated',
            'The write depth is judged inside the sharing service\'s per-record write gate, together with ownership ' +
            'and shares; this report does not separate it from them (see the sharing layer).')
        : sharingFaultDetail
          ? depthRecord('not_evaluated',
              "Read depth widens the sharing service's owner-match, whose read filter could not be evaluated " +
              '(see the sharing layer).')
          : owd.effect !== 'private'
            ? depthRecord('not_evaluated', 'Baseline is not private — read depth adds nothing beyond it for this record.')
            : delegatedRead
              ? depthRecord('not_evaluated',
                  'On an on-behalf-of read the sharing filter is asked with the delegated context as it stands, so ' +
                  'read depth is not separated from it for this record (see the sharing layer).')
              : !depthWidens
                ? depthRecord('not_evaluated',
                    "Effective read depth is 'own' — it reaches no owner beyond the caller, so it adds nothing to " +
                    'the baseline for this record (see owd_baseline).')
                : sharingFilter === undefined
                  ? depthRecord('not_evaluated',
                      "Read depth widens the sharing service's owner-match, which is unavailable on this deployment.")
                  : ownerIsMe
                    ? depthRecord('admitted',
                        `Caller owns the record — inside every read depth, including '${depthScope}'; the baseline ` +
                        'already admits it (see owd_baseline).')
                    : depthAdmitsRow
                      ? depthRecord('admitted', depthScope === 'org'
                          ? "Effective read depth 'org' admits this record without a share: at org depth the sharing " +
                            'service imposes no owner-match (ADR-0057 D1).'
                          : `The record's owner (${ownerLabel}) is inside the caller's '${depthScope}' read depth — ` +
                            "the sharing service's owner-match admits it without a share (ADR-0057 D1).")
                      : sharingMatches === false
                        ? depthRecord('excluded',
                            `The record's owner (${ownerLabel}) is outside the caller's '${depthScope}' read depth; ` +
                            'a share may still widen access (see the sharing layer).')
                        : depthScope === 'org'
                          ? depthRecord('admitted',
                              "Effective read depth 'org' admits this record (no owner-match at org depth); a share " +
                              'admits it as well (see the sharing layer).')
                          : sharingFilter === null
                            ? depthRecord('not_evaluated',
                                'The sharing service imposes no owner-match on this object, so read depth has ' +
                                'nothing to widen for this record (see the sharing layer).')
                            : depthRecord('not_evaluated',
                                `A share admits this record (see the sharing layer); whether the caller's ` +
                                `'${depthScope}' read depth also reaches its owner is not separated from that share here.`);
  }

  // ── vama_bypass: what the bypass did to THIS row ─────────────────────────
  // [#4647] The layer that claims "ownership and sharing checks are skipped"
  // now says so at row granularity too, and says it from the same verdict the
  // write gate consults.
  const vamaLayer = layers.find((l) => l.layer === 'vama_bypass');
  if (vamaLayer) {
    vamaLayer.record = !recordExists
      ? { outcome: 'not_evaluated', rules: [], detail: 'Record not found; the bypass was not evaluated.' }
      : vamaEffective
        ? {
            outcome: 'admitted',
            rowFilter: null,
            rules: [],
            detail: `View/Modify All Data via [${vamaSets.join(', ')}] admits this record regardless of ownership — ` +
              'the same bypass the write path consults.',
          }
        : { outcome: 'not_evaluated', rules: [], detail: 'No View/Modify All Data bypass applies to this record.' };
  }

  // ── rls: the business (Layer 1) predicate for this record ────────────────
  const rlsLayer = layers.find((l) => l.layer === 'rls');
  if (rlsLayer) {
    if (!recordExists) {
      rlsLayer.record = { outcome: 'not_evaluated', rules: [], detail: 'Record not found; business RLS not evaluated.' };
    } else if (layeredFault) {
      rlsLayer.record = { outcome: 'not_evaluated', rules: [], detail: layeredFaultDetail('Business RLS') };
    } else if (layered === undefined) {
      rlsLayer.record = { outcome: 'not_evaluated', rules: [], detail: 'Business RLS split is unavailable on this engine build.' };
    } else if (layer1 == null) {
      rlsLayer.record = { outcome: 'not_evaluated', rowFilter: null, rules: [], detail: 'No business RLS policy applies to this record.' };
    } else {
      const deny = isDenyAll(layer1);
      const m = matches(layer1);
      const excluded = deny || m === false;
      // [#24164 ruling E′] An object's default row scope is named as itself,
      // reached through the object's declaration rather than a held set.
      const [objectDefault] = objectDefaultRowScopesOf([layer1]);
      rlsLayer.record = {
        outcome: excluded ? 'excluded' : 'admitted',
        rowFilter: layer1,
        matchesRecord: deny ? false : m,
        rules: [
          objectDefault
            ? {
                kind: 'rls_policy',
                name: objectDefault.name ?? '(unnamed)',
                via: 'object_default',
                predicate: layer1,
                effect: excluded ? 'excludes' : 'admits',
              }
            : { kind: 'rls_policy', name: 'business_rls', predicate: layer1, effect: excluded ? 'excludes' : 'admits' },
        ],
        detail: (deny
          ? 'Business RLS composes to DENY ALL for this principal.'
          : excluded
            ? 'The record does not satisfy the business row-level predicate.'
            : 'The record satisfies the business row-level predicate.') +
          (objectDefault ? objectDefaultRowScopeSource(object, [objectDefault]) : ''),
      };
    }
  }

  // ── kernelTier on every layer + posture resolution ───────────────────────
  for (const l of layers) {
    if (!l.kernelTier) l.kernelTier = kernelTierOf(l.layer);
  }

  // ── decision.record: bottom line + decisive layer ────────────────────────
  const tenantExcluded = tenantRecord.outcome === 'excluded';
  const rlsExcluded = rlsLayer?.record?.outcome === 'excluded';
  // [#4647] The bypass admits any row of this object for this principal — the
  // row-level meaning of the `vama_bypass` layer's own claim. On the WRITE
  // branch the gate (`canEdit`/`canDelete`) is still the authority when it is
  // available, because the gate is what the request will actually hit and it
  // now consults this same bypass; the disjunction below only carries the
  // bypass where no gate answered (a deployment without plugin-sharing) and on
  // the read branch, whose row filter the bypass short-circuits identically.
  const vamaAdmitsRow = vamaEffective && recordExists;
  // `depthAdmitsRow` is the part of the sharing filter's match the sharing
  // layer no longer claims, so the disjunction is the one it always was.
  const businessRowAdmits = isRead
    ? owd.effect !== 'private' || ownerIsMe || sharingOutcome === 'admitted' || depthAdmitsRow || vamaAdmitsRow
    : canEdit !== undefined
      ? canEdit || authoredRowWriteAdmits
      : owd.effect === 'public' || ownerIsMe || sharingOutcome === 'admitted' || vamaAdmitsRow;

  // [#4647] Was the bypass DECISIVE? Only where the baseline and the concrete
  // shares would otherwise have excluded the row — an owner or a shared-to
  // principal is admitted with or without it, and reporting `vama_bypass` there
  // would over-credit the grant.
  const baselineAdmitsRow = isRead ? owd.effect !== 'private' : owd.effect === 'public';
  const bypassWasDecisive = vamaAdmitsRow && !baselineAdmitsRow && !ownerIsMe && !anyShareAdmits;

  let visible: boolean;
  let decidedBy: NonNullable<ExplainDecision['record']>['decidedBy'];
  if (capsDeny) { visible = false; decidedBy = 'required_permissions'; }
  else if (!crudAllowed) { visible = false; decidedBy = 'object_crud'; }
  else if (!recordExists) { visible = false; decidedBy = undefined; }
  else if (tenantExcluded) { visible = false; decidedBy = 'tenant_isolation'; }
  else if (rlsExcluded) { visible = false; decidedBy = 'rls'; }
  // A dependency that threw decides by failing the request, in the order the
  // pipeline calls it: the RLS composition runs before the sharing middleware.
  else if (layeredFault) { visible = false; decidedBy = 'rls'; }
  else if (sharingFaultDetail) { visible = false; decidedBy = 'sharing'; }
  // [ADR-0055] The master check refuses after the record's own row-level
  // security (step 2.8 runs below the pre-image gate), and names its leg on
  // the sharing layer, the record's write gate. A read's master leg is asked
  // only where the record's own row-level security admits it, and is named on
  // the same layer.
  else if (masterLegRefusal) { visible = false; decidedBy = 'sharing'; }
  else if (!businessRowAdmits) { visible = false; decidedBy = owd.effect === 'private' ? 'sharing' : 'owd_baseline'; }
  // [#5493 / ADR-0105 D3] A row the write gate refused and its deferral
  // admitted was last admitted by the app-authored row-level policy.
  else if (authoredRowWriteAdmits) { visible = true; decidedBy = 'rls'; }
  else {
    visible = true;
    // `depth` ranks with `sharing`, the other layer that widens a private
    // baseline past its owner: a row no share and no ownership admits, but the
    // read depth does, is the depth layer's admission.
    decidedBy = bypassWasDecisive
      ? 'vama_bypass'
      : (owd.effect === 'private' && !ownerIsMe && sharingOutcome === 'admitted')
        ? 'sharing'
        : depthAdmitsRow
          ? 'depth'
          : layer1 != null
            ? 'rls'
            : owd.effect === 'private' && ownerIsMe
              ? 'owd_baseline'
              : layer0 != null
                ? 'tenant_isolation'
                : 'object_crud';
  }

  return {
    record: { recordId, visible, ...(decidedBy ? { decidedBy } : {}) },
    posture,
  };
}

/**
 * Explain `input.context`'s access, asked by that same principal: a
 * self-explanation. Whether the explanation may say a record exists is decided
 * by the asker's read, and here the asker is the explained principal itself.
 */
export async function explainAccess(deps: ExplainEngineDeps, input: ExplainInput): Promise<ExplainDecision> {
  return explainAccessForAsker(deps, input, undefined);
}

/**
 * [#22792] The principal that asked for an explanation. Module-internal, as
 * {@link explainAccessForAsker} is.
 */
export interface ExplainAsker {
  /** The asking principal's context; `undefined` or the explained context itself is a self-explanation. */
  context: any;
  /**
   * [#22851, ruling C] The asker's own caller-context by-id read, classified
   * for an asker who is NOT the explained principal: `true` when the read
   * leaves the asker without the row, by returning none OR by refusing (a
   * declared 4xx); a store fault rejects. Asked only for such an asker. A
   * principal explaining itself is asked the write path's question
   * (`recordAbsentToCaller`: absent means no row) instead, so a
   * self-explanation shows what that principal's own doors do.
   */
  cannotRead: (object: string, recordId: string) => Promise<boolean>;
}

/**
 * [#22792] Explain `input.context`'s access, asked by `asker`: the principal
 * that requested the explanation, which is not the principal being explained
 * when an administrator explains another user (ADR-0090 D6/D12). `undefined`
 * means the explained principal asks for itself.
 *
 * Ruling A of the explain-asker decision: whether an explanation may disclose
 * that a record exists is decided by the ASKER's read access, never by the
 * explained principal's. An asker who cannot read the record gets, for every
 * operation, exactly what an id no row carries gets: the record verdict and
 * every layer's per-record attribution. An asker who can read it learns
 * nothing new about its existence, and gets the full record story.
 *
 * [#22851] Ruling C settles what "cannot read" means for each asker, on the
 * one caller-context by-id read: for an asker explaining ANOTHER principal,
 * no row or a declared refusal (`asker.cannotRead`); for a principal
 * explaining itself, no row (`recordAbsentToCaller`, the write path's notion).
 *
 * Module-internal on purpose: the package publishes {@link explainAccess},
 * whose signature and self-explanation answer this leaves as they are. The
 * security service's caller-authorized explain (`explainAccessForCaller`)
 * is the one caller that knows a different asker.
 */
export async function explainAccessForAsker(
  deps: ExplainEngineDeps,
  input: ExplainInput,
  asker: ExplainAsker | undefined,
): Promise<ExplainDecision> {
  // One explanation asks the read question of at most two principals (the
  // asker and the explained), from up to three places (the asker gate, the
  // by-id write guard, the master leg of a read), and the principal's READ
  // pass below asks it again: each (principal, record) pair is read once.
  const askerOnce: ExplainAsker | undefined = asker && { context: asker.context, cannotRead: oncePerRecord(asker.cannotRead) };
  return explainOnce({ ...deps, recordAbsentToCaller: askedOnce(deps.recordAbsentToCaller) }, input, askerOnce);
}

/** One answer per (object, record) for the length of one explanation; a rejection stays the rejection it was. */
function oncePerRecord(
  question: (object: string, recordId: string) => Promise<boolean>,
): (object: string, recordId: string) => Promise<boolean> {
  const asked = new Map<string, Promise<boolean>>();
  return (object, recordId) => {
    const key = JSON.stringify([object, recordId]);
    let answer = asked.get(key);
    if (!answer) {
      answer = question(object, recordId);
      asked.set(key, answer);
    }
    return answer;
  };
}

/**
 * The read question, memoized per (context, object, record) for the length of
 * one explanation. The answer to a question is the same however often it is
 * asked within one request; a rejection stays the rejection it was.
 */
function askedOnce(
  question: ExplainEngineDeps['recordAbsentToCaller'],
): ExplainEngineDeps['recordAbsentToCaller'] {
  if (question === undefined) return undefined;
  const byContext = new Map<unknown, (object: string, recordId: string) => Promise<boolean>>();
  return (object, recordId, context) => {
    let ask = byContext.get(context);
    if (!ask) {
      ask = oncePerRecord((o, r) => question(o, r, context));
      byContext.set(context, ask);
    }
    return ask(object, recordId);
  };
}

/**
 * [#22792] The preface every per-record attribution carries when a by-id write
 * is explained to an asker who can read a record the explained principal
 * cannot: the write never gets past that read, so the attribution shown is the
 * read's, and it says so.
 */
function principalReadPreface(operation: ExplainOperation): string {
  return `The principal cannot read this record, so its by-id ${operation} answers 404 RECORD_NOT_FOUND, as an id ` +
    'no row carries does. This attribution is of that read: ';
}

/**
 * [#22792] Carry the explained principal's READ attribution onto a by-id write
 * explanation, layer by layer: each row-scoped layer's `record` becomes the
 * read's (prefaced), and the tenant layer's verdict, which its record decides,
 * follows it. The object-level fields stay the write's own.
 */
function attributeThePrincipalsRead(layers: ExplainLayer[], read: ExplainDecision, operation: ExplainOperation): void {
  const readLayers = new Map(read.layers.map((l) => [l.layer, l]));
  for (const layer of layers) {
    const readLayer = readLayers.get(layer.layer);
    if (!layer.record || !readLayer?.record) continue;
    layer.record = { ...readLayer.record, detail: principalReadPreface(operation) + (readLayer.record.detail ?? '') };
    if (layer.layer === 'tenant_isolation') layer.verdict = readLayer.verdict;
  }
}

/**
 * [#23157] The person a user id names, for the principal layer's prose: the
 * display name and email first and the id secondary — `Ada Lovelace
 * (ada@example.com; id usr_1)` — the way the explain panel's own Principal
 * line shows that person.
 *
 * The user row is read through the ASKER's door: `ql.findOne` under the
 * asker's context, every data middleware included, so the sentence carries
 * only what the asker could read of that user anyway, row-level and
 * field-level security both. An asker the read returns no row to, or a row
 * with neither a name nor an email, gets the bare id the sentence always
 * carried, and nothing more. So does a read that cannot run or that throws:
 * the label is presentation, never an input to a verdict, and the id it falls
 * back to is the fact the context already states.
 */
async function personOf(ql: any, askerContext: any, userId: string): Promise<string> {
  if (!userId || typeof ql?.findOne !== 'function') return userId;
  let row: any;
  try {
    row = await ql.findOne('sys_user', { where: { id: userId }, context: askerContext });
  } catch {
    return userId;
  }
  const text = (v: unknown): string => (typeof v === 'string' ? v.trim() : '');
  const name = text(row?.name);
  const email = text(row?.email);
  if (name && email && name !== email) return `${name} (${email}; id ${userId})`;
  if (name || email) return `${name || email} (id ${userId})`;
  return userId;
}

async function explainOnce(deps: ExplainEngineDeps, input: ExplainInput, asker: ExplainAsker | undefined): Promise<ExplainDecision> {
  const { object, operation, context } = input;
  const engineOp = EXPLAIN_TO_ENGINE_OP[operation];
  // [#3544] The gate operation (`engineOp`) and the data operation may differ —
  // today only for `export`, which is gated as itself but reads as a `find`.
  const dataOp = dataOpOf(operation, engineOp);
  // [#22550] ...and the row-level security operation may differ from both: a
  // lifecycle verb is composed as its nearest write class (transfer and restore
  // as update, purge as delete), the mapping the by-id write pre-image gate
  // (step 2.7) reads. Both RLS compositions below are asked for it.
  const rlsOp = rlsOperationForVerb(dataOp);
  const layers: ExplainLayer[] = [];

  // ── 1. principal ──────────────────────────────────────────────────────
  const sets = await deps.resolveSets(context).catch(() => [] as PermissionSet[]);
  const setNames = sets.map((s: any) => String(s.name ?? '?'));
  // [ADR-0090 D10] Agent/service intersection. When the principal acts on
  // behalf of a user, every layer below reports the INTERSECTION verdict —
  // the narrower of the agent's own grants and the delegator's. `delegatorSets`
  // stays null on the ordinary path, so each fold is a no-op and the report is
  // byte-identical to a non-delegated principal.
  let delegatorSets: PermissionSet[] | null = null;
  let delegatorContextForRls: any = null;
  let delegatorMissing = false;
  // The delegator's grants could not be READ — the resolution threw. The
  // middleware resolves the delegator un-caught, so the request fails: a
  // fail-closed denial like a missing delegator, never "no delegation", which
  // would let the agent's own grants decide alone.
  let delegatorUnresolved = false;
  let delegatorNames: string[] = [];
  if (context?.onBehalfOf?.userId) {
    const del = await settle(resolveDelegatorContext(deps.ql, context));
    if (del === DEPENDENCY_FAULT) {
      delegatorUnresolved = true;
    } else if (del.kind === 'missing') {
      delegatorMissing = true;
    } else if (del.kind === 'resolved') {
      delegatorContextForRls = del.context;
      delegatorSets = await deps.resolveSets(del.context).catch(() => [] as PermissionSet[]);
      delegatorNames = delegatorSets.map((s: any) => String(s.name ?? '?'));
    }
  }
  const positions: string[] = context?.positions ?? [];
  const viaOf = (name: string): string => {
    if (deps.baselinePermissionSets.includes(name)) return 'additive baseline (ADR-0090 D5)';
    if (positions.includes(name)) return `position:${name}`;
    if ((context?.permissions ?? []).includes(name)) return 'direct grant';
    return 'resolved';
  };
  // [ADR-0091 D2 / ADR-0049 / commit 42b05af89] Held-but-dropped grant rows (populated by
  // buildContextForUser when explaining by userId): present, but contributing
  // nothing, each carrying the closed reason enumeration (`expired` |
  // `deactivated`) — reported so "why did access disappear" is self-answering
  // for BOTH lifecycle controls, in ONE shared vocabulary.
  const droppedGrants: DroppedGrant[] =
    Array.isArray(context?.droppedGrants) ? context.droppedGrants : [];
  const expiredGrants = droppedGrants.filter((g) => g.state === 'expired');
  const deactivatedGrants = droppedGrants.filter((g) => g.state === 'deactivated');
  // [ADR-0091 D3] Positions held via delegation — attributed "via delegation
  // from X, until Y" so a delegated hat is visible in the report.
  const delegatedPositions: Array<{ name: string; from: string; until?: string }> =
    Array.isArray(context?.delegatedPositions) ? context.delegatedPositions : [];
  const delegationOf = (name: string): { from: string; until?: string } | undefined =>
    delegatedPositions.find((d) => d.name === name);
  // [#23157] The principal and its delegator are named as people, read
  // through the asker's door ({@link personOf}); a self-explanation's asker is
  // the explained principal.
  const askerContext = asker?.context ?? context;
  const principalPerson = context?.userId != null
    ? await personOf(deps.ql, askerContext, String(context.userId))
    : '(anonymous)';
  const delegatorPerson = context?.onBehalfOf?.userId
    ? await personOf(deps.ql, askerContext, String(context.onBehalfOf.userId))
    : '';
  // ...and so is the user each ADR-0091 D3 delegated position came from, once
  // per distinct user, in the clause and in the position's attribution alike.
  const positionDelegators = new Map<string, string>();
  for (const from of new Set(delegatedPositions.map((d) => d.from))) {
    positionDelegators.set(from, await personOf(deps.ql, askerContext, from));
  }
  const delegatorOf = (from: string): string => positionDelegators.get(from) ?? from;
  layers.push({
    layer: 'principal',
    verdict: delegatorMissing || delegatorUnresolved ? 'denies' : 'neutral',
    detail:
      `Principal ${principalPerson} holds position(s) [${positions.join(', ') || 'none'}] ` +
      `resolving to permission set(s) [${setNames.join(', ') || 'none'}] (union-merged, most-permissive).` +
      (context?.onBehalfOf?.userId
        ? delegatorMissing
          ? ` Acting on behalf of ${delegatorPerson}, who no longer exists — D10 fails CLOSED (access denied).`
          : delegatorUnresolved
            ? ` Acting on behalf of ${delegatorPerson}, whose grants could not be resolved (the lookup threw) — D10 fails CLOSED (access denied).`
            : ` Acting on behalf of ${delegatorPerson} — effective access is the D10 INTERSECTION with the delegator's set(s) [${delegatorNames.join(', ') || 'none'}].`
        : '') +
      (delegatedPositions.length > 0
        ? ` ${delegatedPositions.length} position(s) held via delegation (ADR-0091 D3): [${delegatedPositions
            .map((d) => `${d.name} from ${delegatorOf(d.from)}${d.until ? ` until ${d.until}` : ''}`)
            .join(', ')}].`
        : '') +
      (expiredGrants.length > 0
        ? ` ${expiredGrants.length} grant(s) present but EXPIRED (ADR-0091): [${expiredGrants
            .map((g) => `${g.name}${g.until ? ` until ${g.until}` : ''}`)
            .join(', ')}] — contributing nothing.`
        : '') +
      (deactivatedGrants.length > 0
        ? ` ${deactivatedGrants.length} grant(s) present but DEACTIVATED (ADR-0049): [${deactivatedGrants
            .map((g) => g.name)
            .join(', ')}] — the catalogue row is switched off, contributing nothing until re-activated.`
        : ''),
    contributors: [
      ...positions.map((p) => {
        const d = delegationOf(p);
        return d
          ? { kind: 'position' as const, name: p, via: `delegation from ${delegatorOf(d.from)}${d.until ? ` until ${d.until}` : ''}` }
          : { kind: 'position' as const, name: p };
      }),
      ...setNames.map((n) => ({ kind: 'permission_set' as const, name: n, via: viaOf(n) })),
      // [commit 42b05af89] One shared "held but not resolving, because X" vocabulary for
      // every dropped row — the state member IS the reason, closed enum.
      ...droppedGrants.map((g) => ({
        kind: g.kind,
        name: g.name,
        via: g.state === 'expired'
          ? (g.until ? `held until ${g.until} — expired` : 'expired')
          : 'held — deactivated',
        state: g.state,
      })),
    ],
  });

  // ── posture shared by later layers ────────────────────────────────────
  const secMeta = await deps.getObjectSecurityMeta(object);
  // [#18253] A name nobody declared is not a verdict — REFUSE instead of
  // walking nine layers and reporting `denies`.
  //
  // Every machine-readable channel of the report (`allowed: false`,
  // `object_crud: 'denies'`, HTTP 200) was byte-identical to a genuine
  // permission denial, so a misspelled API name reached the administrator as a
  // permission decision about a record that does not exist. Only the layer
  // PROSE differed (#10401/#10424), and no client branches on prose. The
  // maintainer ruling of 2026-09-17 (letter B): "a typo must not look like a
  // permission decision".
  //
  // ⚠️ The condition is the `'unknown'` CAUSE, not `unresolved` alone. The
  // other two causes are not absent objects and must keep the explanation they
  // have: an `'unpublished_draft'` declaration EXISTS (its remedy is "publish
  // it"), and `'metadata_unavailable'` is a read that did not answer, where
  // claiming absence would state as fact the half the outage made unknowable.
  // An absent `unresolvedCause` defaults to `'unknown'` — the same reading the
  // prose path has always given it (`unresolvedPostureExplainDetail`), so a
  // deps bag wired before #10401 is not silently exempted from the fix.
  //
  // This lives in the ENGINE rather than at the REST door so every caller of
  // `ISecurityService.explain` gets the same refusal: the door owns the
  // transport mapping (404 `OBJECT_NOT_FOUND`), never the judgement.
  if (secMeta.unresolved === true && (secMeta.unresolvedCause ?? 'unknown') === 'unknown') {
    throw new ExplainObjectNotFoundError(object, operation);
  }
  let schema: any = null;
  try { schema = deps.ql?.getSchema?.(object) ?? null; } catch { schema = null; }
  const declaredColumns = declaredColumnsOf(schema);

  // ── 2. required_permissions AND-gate ──────────────────────────────────
  const required = deps.requiredCaps(secMeta.requiredPermissions, dataOp);
  let capsDeny = false;
  if (required.length > 0) {
    const held = deps.evaluator.getSystemPermissions(sets);
    const missing = required.filter((c) => !held.has(c));
    // [ADR-0090 D10] Both principals must hold every required capability.
    const heldDel = delegatorSets ? deps.evaluator.getSystemPermissions(delegatorSets) : null;
    const missingDel = heldDel ? required.filter((c) => !heldDel.has(c)) : [];
    capsDeny = missing.length > 0 || missingDel.length > 0;
    layers.push({
      layer: 'required_permissions',
      verdict: capsDeny ? 'denies' : 'neutral',
      detail: capsDeny
        ? `'${object}' requires capability [${required.join(', ')}] for ${operation} — missing ` +
          `[${[...new Set([...missing, ...missingDel])].join(', ')}]` +
          (missingDel.length > 0 && missing.length === 0
            ? ' (the DELEGATOR lacks it — D10 intersection)'
            : '') +
          ` (checked BEFORE the CRUD grant, ADR-0066 ⑤).`
        : `Capability prerequisite [${required.join(', ')}] satisfied` +
          (delegatorSets ? ' by BOTH the agent and the delegator (D10)' : '') + '.',
      contributors: [],
    });
  } else {
    layers.push({
      layer: 'required_permissions',
      verdict: 'not_applicable',
      detail: `'${object}' declares no requiredPermissions for ${operation}.`,
      contributors: [],
    });
  }

  // ── 3. object_crud — the core grant, with per-set attribution ─────────
  const agentCrud = deps.evaluator.checkObjectPermission(engineOp, object, sets, { isPrivate: secMeta.isPrivate });
  // [ADR-0090 D10] Both principals must grant the CRUD op; the agent may not
  // act beyond the delegator's own reach (and vice-versa).
  const delegatorCrud = delegatorSets
    ? deps.evaluator.checkObjectPermission(engineOp, object, delegatorSets, { isPrivate: secMeta.isPrivate })
    : true;
  // [#3545] An UNRESOLVED posture is a denial in the middleware, so it must read
  // as one here too — explain and enforcement disagreeing on a security surface
  // is the same `declared ≠ enforced` gap this engine exists to expose. Reported
  // on the existing `object_crud` layer (no new layer kind): the posture is what
  // that layer's grant is computed FROM, and reporting the real cause beats a
  // misleading "no set grants it" when the sets were never the problem.
  const postureUnresolved = secMeta.unresolved === true;
  const crudAllowed = agentCrud && delegatorCrud && !delegatorMissing && !delegatorUnresolved && !postureUnresolved;
  const granting = postureUnresolved
    ? []
    : sets
        .filter((s) => deps.evaluator.checkObjectPermission(engineOp, object, [s], { isPrivate: secMeta.isPrivate }))
        .map((s: any) => String(s.name ?? '?'));
  layers.push({
    layer: 'object_crud',
    verdict: crudAllowed ? 'grants' : 'denies',
    detail: crudAllowed
      ? `${operation} on '${object}' is granted by [${granting.join(', ')}]` +
        (delegatorSets ? ' AND by the delegator (D10 intersection).' : '.')
      : postureUnresolved
        // [#10401] One wording, shared with the middleware's own throw, so
        // explanation and enforcement cannot drift into telling a reader two
        // different things about one refusal. See `unresolved-posture.ts`.
        ? unresolvedPostureExplainDetail(object, secMeta.unresolvedCause ?? 'unknown')
        : delegatorMissing
          ? `Delegator no longer exists — D10 fails closed (access denied).`
          : delegatorUnresolved
            ? `The delegator's grants could not be resolved — D10 fails closed (access denied).`
            : agentCrud && !delegatorCrud
              ? `The agent grants ${operation} on '${object}' but the DELEGATOR does not — D10 intersection denies (an agent may not exceed the user it acts for).`
              : `No resolved permission set grants ${operation} on '${object}'` +
                (secMeta.isPrivate ? " (object is 'private' posture — non-superuser '*' wildcards are excluded, ADR-0066 D2)." : '.'),
    contributors: granting.map((n) => ({ kind: 'permission_set' as const, name: n, via: viaOf(n) })),
  });

  // ── 4. fls ─────────────────────────────────────────────────────────────
  const agentMask = deps.getFieldMask(sets, object, secMeta.fieldRequiredPermissions);
  // [ADR-0090 D10] Intersect the two masks — a field is readable only if BOTH
  // principals can read it.
  const mask = delegatorSets
    ? intersectFieldMasks(agentMask, deps.getFieldMask(delegatorSets, object, secMeta.fieldRequiredPermissions))
    : agentMask;
  // [#9127] The field-mask decision has THREE outcomes, not two — hidden
  // (key deleted), PARTIALLY masked (key served, value replaced by the
  // field's `maskingRule`), and readable. `deps.getPartialMaskRules` is the
  // enforcement composition verbatim, never a second derivation of it: the
  // binary mask below cannot express the middle state, and reading it alone
  // is what made this layer call a partially-masked field fully hidden and a
  // gate-less rule field fully readable.
  //
  // The hidden/partial split is `FieldMasker.maskResults`' own: it deletes a
  // field when the binary mask denies it AND no rule applies, so a rule that
  // survived the explicit-deny exclusion always demotes `hidden` to `partial`
  // — including the capability-gated case, where the mask says `readable:
  // false` precisely because the unmask gate is what the rule softens.
  const partialRules = await deps.getPartialMaskRules(sets, object, delegatorSets);
  const partial = Object.keys(partialRules);
  const hidden = Object.entries(mask)
    .filter(([f, p]) => p?.readable === false && !(f in partialRules))
    .map(([f]) => f);
  const listFields = (fields: string[], label: (f: string) => string): string =>
    `[${fields.slice(0, 25).map(label).join(', ')}${fields.length > 25 ? ', …' : ''}]`;
  const maskNarrows = hidden.length > 0 || partial.length > 0;
  layers.push({
    layer: 'fls',
    verdict: maskNarrows ? 'narrows' : 'not_applicable',
    detail: maskNarrows
      ? [
          hidden.length > 0
            ? `${hidden.length} field(s) masked from responses: ${listFields(hidden, (f) => f)}`
            : null,
          partial.length > 0
            ? `${partial.length} field(s) PARTIALLY masked — the key is still served, its value ` +
              `replaced: ${listFields(partial, (f) => `${f} (${describeMaskingRule(partialRules[f])})`)}`
            : null,
        ]
          .filter((s): s is string => s !== null)
          .join('; ') +
        (delegatorSets ? ' (intersection of agent + delegator masks, D10).' : '.')
      : 'No field-level masking applies.',
    contributors: [],
  });

  // ── 5. owd_baseline ────────────────────────────────────────────────────
  const owd = describeOwd(schema);
  layers.push({
    layer: 'owd_baseline',
    verdict: owd.effect === 'public' ? 'neutral' : 'narrows',
    detail:
      `Record baseline (OWD) is ${owd.model}: ` +
      (owd.effect === 'private'
        ? 'rows are owner-visible only; sharing can only WIDEN from here.'
        : owd.effect === 'read'
          ? 'all rows readable org-wide, writes owner-scoped.'
          : 'rows are org-shared at this baseline.'),
    contributors: [],
  });

  // ── 6. depth ───────────────────────────────────────────────────────────
  const opClass = dataOp === 'find' ? 'read' : 'write';
  const agentScope = deps.evaluator.getEffectiveScope(opClass as 'read' | 'write', object, sets, { isPrivate: secMeta.isPrivate });
  // [ADR-0090 D10 — ruling 2026-09-08] The delegated row set is the AND of the
  // two identity legs, so the depth a reader of this report cares about is the
  // narrower of them — and a ceiling that DECLARES no depth contributes no
  // narrowing at all (`intersectDelegatedScope`). The agent leg here is the
  // SAME value the middleware stashes as `__readScope` (`security-plugin.ts`
  // step 2.6), computed by the SAME function from the SAME two evaluator calls,
  // so a report saying "narrowed to 'own'" can never sit beside a query that
  // was not narrowed.
  const delegatorScope = delegatorSets
    ? deps.evaluator.getEffectiveScope(opClass as 'read' | 'write', object, delegatorSets, { isPrivate: secMeta.isPrivate })
    : null;
  const delegated = delegatorSets
    ? intersectDelegatedScope(
        deps.evaluator.getDeclaredScope(opClass as 'read' | 'write', object, sets, { isPrivate: secMeta.isPrivate }),
        delegatorScope!,
      )
    : null;
  const scope = delegated ? narrowerScope(delegated.agentLegScope, delegatorScope!) : agentScope;
  const depthApplies = owd.effect !== 'public';
  layers.push({
    layer: 'depth',
    verdict: !depthApplies ? 'not_applicable' : scope === 'own' ? 'neutral' : 'widens',
    detail: !depthApplies
      ? 'Depth axis does not apply (baseline already org-wide).'
      : `Effective ${opClass} depth: '${scope}' (ADR-0057 D1 — widest across granting sets; ` +
        (delegated
          ? delegated.narrowedByCeiling
            ? `narrowed from the delegator's '${delegatorScope}' to the agent ceiling's '${delegated.agentLegScope}' by the D10 intersection; `
            : `the agent ceiling declares no depth, so the delegator's '${delegatorScope}' stands under the D10 intersection; `
          : '') +
        `assignment BU anchors narrow which unit 'unit*' means, ADR-0090 Addendum).`,
    contributors: [],
  });

  // ── 7. sharing ─────────────────────────────────────────────────────────
  layers.push({
    layer: 'sharing',
    verdict: owd.effect === 'private' ? 'widens' : 'not_applicable',
    detail: owd.effect === 'private'
      ? 'Record shares, sharing rules and team grants OR-in additional rows at query time (record-level; evaluate per record via the sharing service).'
      : 'Baseline already grants the rows sharing would add.',
    contributors: [],
  });

  // ── 8. vama_bypass ─────────────────────────────────────────────────────
  // [#4647] Resolved through `PermissionEvaluator.superuserBypassSets` — the
  // ONE bypass predicate. `ISecurityService.hasWriteBypass` folds through the
  // same function, and that is what plugin-sharing's `canEdit`/`canDelete`
  // (hence the `sys_attachment` `canEdit(parent)` gate) consult on the write
  // path. explain and enforcement ask the same question of the same code, so
  // they can no longer answer it differently for one (principal, record,
  // operation) triple.
  //
  // The bit is OPERATION-scoped: a write asks for `modifyAllRecords` exactly as
  // the write gate does, because "View All Data" is a read power and must not
  // widen a write. Reading either bit here (the pre-#4647 behaviour) would have
  // re-created the same contradiction one bit down.
  const vamaBit = superuserBypassBitForOperation(dataOp);
  const vamaOf = (list: PermissionSet[]): string[] =>
    deps.evaluator.superuserBypassSets(object, list, { isPrivate: secMeta.isPrivate, bit: vamaBit });
  const agentVama = vamaOf(sets);
  const delegatorVama = delegatorSets ? vamaOf(delegatorSets) : null;
  // [ADR-0090 D10] The bypass only survives the intersection when BOTH sides
  // hold it — an agent's own View-All must never let it see rows its delegator
  // cannot (the grant-ceiling makes agent VAMA impossible anyway; this is the
  // belt-and-braces at evaluation time).
  const vamaEffective = agentVama.length > 0 && (delegatorVama === null || delegatorVama.length > 0);
  const vamaSets = agentVama;
  // [#4647] A write question whose answer is "no bypass" still owes the admin
  // WHICH bit is missing: holding View All Data and being refused an update is
  // exactly the case this layer is read for.
  const viewOnlySets = vamaBit === 'modify' && agentVama.length === 0
    ? deps.evaluator.superuserBypassSets(object, sets, { isPrivate: secMeta.isPrivate, bit: 'view' })
    : [];
  layers.push({
    layer: 'vama_bypass',
    verdict: vamaEffective ? 'widens' : 'not_applicable',
    detail: vamaEffective
      ? `View/Modify All Data bypass held via [${vamaSets.join(', ')}]` +
        (delegatorVama ? ` AND by the delegator [${delegatorVama.join(', ')}]` : '') +
        ` — ownership and sharing checks are skipped` +
        (vamaBit === 'modify'
          ? ` (Modify All Data: the write path consults this SAME bypass).`
          : `.`)
      : agentVama.length > 0 && delegatorVama !== null && delegatorVama.length === 0
        ? `Agent holds View/Modify All Data via [${agentVama.join(', ')}] but the DELEGATOR does not — D10 intersection strips the bypass.`
        : viewOnlySets.length > 0
          ? `View All Data held via [${viewOnlySets.join(', ')}] does NOT bypass ownership for ${operation} — ` +
            `a write bypass requires Modify All Data (modifyAllRecords), so ownership and sharing still decide.`
          : 'No View/Modify All Data bypass.',
    contributors: vamaEffective ? vamaSets.map((n) => ({ kind: 'permission_set' as const, name: n, via: viaOf(n) })) : [],
  });

  // ── 9. rls — the composed machine artifact ─────────────────────────────
  let agentFilter: Record<string, unknown> | null | undefined;
  try {
    agentFilter = await deps.computeRlsFilter(sets, object, rlsOp, context);
  } catch {
    agentFilter = { id: DENY_ALL_SENTINEL_ID };
  }
  // [ADR-0090 D10] AND the delegator's read filter into the composite — the
  // delegated principal sees only rows BOTH principals may see.
  let delegatorFilter: Record<string, unknown> | null | undefined;
  if (delegatorSets && delegatorContextForRls) {
    try {
      delegatorFilter = await deps.computeRlsFilter(delegatorSets, object, rlsOp, delegatorContextForRls);
    } catch {
      delegatorFilter = { id: DENY_ALL_SENTINEL_ID };
    }
  }
  const filterParts = [agentFilter, delegatorFilter].filter(Boolean) as Record<string, unknown>[];
  // [#20604] A composed filter the find cannot run is refused here, as
  // enforcement refuses it, and never published as the filter a read runs
  // under. Before the record-grained pass, so a record id no row carries is
  // refused too, as its find is. Only for a request that reaches the filter:
  // one the capability or CRUD gate denies is refused there first, by
  // enforcement and by this report alike.
  if (!capsDeny && crudAllowed) {
    for (const part of filterParts) refuseWhatTheMatcherRefuses(part, object, declaredColumns);
  }
  let readFilter: Record<string, unknown> | null | undefined =
    filterParts.length === 0 ? undefined : filterParts.length === 1 ? filterParts[0] : { $and: filterParts };
  const denyAll = filterParts.some(isDenyAll);
  // [#13639] The verdict above is value-agnostic; this payload collapse is NOT.
  // It rewrites the published `readFilter` into the documented `__deny_all__`
  // shape, so it stays keyed to the sentinel that shape already names. An
  // `__rls_deny__` denial is now reported as `denies` while `readFilter` keeps
  // reporting the predicate that was ACTUALLY composed.
  if (filterParts.some(isDenyAllSentinel)) readFilter = { id: DENY_ALL_SENTINEL_ID };
  // [#24164 ruling E′] Where the narrowing is an object's declared default row
  // scope, say so: its source is the object, not a set the principal holds.
  const objectDefaults = objectDefaultRowScopesOf(filterParts);
  layers.push({
    layer: 'rls',
    verdict: denyAll ? 'denies' : readFilter ? 'narrows' : 'not_applicable',
    detail: denyAll
      ? 'Row-level security composes to DENY ALL for this principal.'
      : readFilter
        ? 'Row-level security narrows the row set (see readFilter for the composed predicate)' +
          (delegatorFilter ? ' — intersection of agent + delegator filters (D10).' : '.') +
          (objectDefaults.length > 0 ? objectDefaultRowScopeSource(object, objectDefaults) : '')
        : 'No RLS policy applies.',
    contributors: [],
  });

  const allowed = !capsDeny && crudAllowed && !denyAll && !delegatorMissing;

  // ── [C2 / ADR-0095] Record-grained augmentation ─────────────────────────
  // Object-level (no recordId) is left BYTE-IDENTICAL: no tenant_isolation
  // layer, no kernelTier, no posture, no per-layer/decision `record`.
  let recordVerdict: ExplainDecision['record'] | undefined;
  let posture: AuthzPosture | undefined;
  if (input.recordId) {
    const recordId = input.recordId;
    const readQuestion = deps.recordAbsentToCaller;
    // [#22792] Ruling A of the explain-asker decision: the ASKER's read decides
    // whether this explanation may say the record exists. An asker the read
    // door does not return the record to gets, for every operation, the whole
    // answer an id no row carries gets: the record verdict and every layer's
    // `record`, all from the one missing-record path below. The read is the
    // read door's own caller-context by-id read, asked with the asker's
    // context, and no exemption sits beside it: a system asker is asked too,
    // and the door returns it every row.
    //
    // [#22851] Ruling C: what "cannot read" means differs by asker, on that one
    // read. A principal explaining itself is asked the write path's question
    // (`recordAbsentToCaller`: absent means no row), so its explanation shows
    // what its own doors do; an asker explaining ANOTHER principal is asked
    // `asker.cannotRead`, where a declared refusal of its read counts as
    // "cannot read" too. A store fault fails the explanation either way.
    const askerContext = asker?.context ?? context;
    const askerIsPrincipal = askerContext === context;
    const askerCannotRead = askerIsPrincipal
      ? readQuestion !== undefined && (await readQuestion(object, recordId, context))
      : await asker!.cannotRead(object, recordId);
    // [#21771] Ruling A on the write doors: a row the principal cannot READ is
    // a row that does not exist, so an update or delete of it answers what a
    // nonexistent id answers, wherever enforcement reaches that question: past
    // the capability and object CRUD gates (which answer first, as they do
    // here), for a principal with an identity. (A system principal reads every
    // row, so the question cannot change its answer.)
    //
    // [#22571] The door asks that question of the by-id `update` and `delete`
    // the caller addresses (`addressedByIdWriteId` in `security-plugin.ts`),
    // and a lifecycle verb reaches it as the operation its door is: a transfer
    // is the PATCH that writes `owner_id`, an update. So the guard reads the
    // explained verb through the one mapping step 2.7 reads, `rlsOp`
    // ({@link rlsOperationForVerb}), never the verb as asked: keyed on the raw
    // verb, a transfer of a row the caller cannot read was reported visible
    // beside the transfer door's 404. `restore` and `purge` map the same way
    // and are refused at the object gate first, so the question never reaches
    // them while their grants are retired.
    //
    // [#22761] The WHOLE record story answers it, not the record verdict
    // alone. The question is asked before the row story is written.
    //
    // [#22792] Who learns that the row exists is the asker's question, above.
    // When the asker is the explained principal, its answer is this one, and
    // a row the principal cannot read is attributed exactly as an id no row
    // carries. When the asker is someone else who CAN read the row, the
    // principal's write still answers what a nonexistent id answers, so the
    // verdict stays `visible: false`; but nothing about the row's existence is
    // withheld from that asker, so the verdict carries the decider of the
    // principal's READ, and each row-scoped layer carries that read's
    // attribution: the read is where the write stops, so it is the story of
    // the write. A second, read-operation pass yields it: no write-operation
    // pass composes the read's row-level security, read filter, read depth or
    // view bypass.
    const principalCannotRead =
      !askerCannotRead &&
      !askerIsPrincipal &&
      (rlsOp === 'update' || rlsOp === 'delete') &&
      !capsDeny &&
      crudAllowed &&
      Boolean(context?.userId) &&
      readQuestion !== undefined &&
      (await readQuestion(object, recordId, context));
    const out = await applyRecordAttribution({
      deps: askerCannotRead || principalCannotRead ? { ...deps, fetchRecord: async () => null } : deps,
      object, recordId, engineOp: dataOp, rlsOp, context, sets, layers, owd, capsDeny, crudAllowed,
      vamaEffective, vamaSets, declaredColumns, depthScope: scope,
    });
    recordVerdict = out.record;
    posture = out.posture;
    if (principalCannotRead) {
      const read = await explainOnce(deps, { object, operation: 'read', context, recordId }, asker);
      attributeThePrincipalsRead(layers, read, operation);
      // A read story that reaches no refusal names no decider: the door's
      // answer stands, `visible: false`, and no layer is credited with it.
      const readDecider = read.record && read.record.visible === false ? read.record.decidedBy : undefined;
      recordVerdict = { recordId, visible: false, ...(readDecider ? { decidedBy: readDecider } : {}) };
    }
  }

  const decision: ExplainDecision = {
    allowed,
    object,
    operation,
    principal: {
      userId: context?.userId ?? null,
      positions,
      permissionSets: setNames,
      ...(context?.principalKind ? { principalKind: context.principalKind } : {}),
      ...(context?.onBehalfOf?.userId ? { onBehalfOf: { userId: context.onBehalfOf.userId } } : {}),
      ...(posture ? { posture } : {}),
    },
    layers,
    // [#3544] `export` surfaces the read filter too — it streams the same
    // rows through the same filter, so omitting it would hide the very
    // narrowing that explains a short export.
    ...(operation === 'read' || operation === 'export' ? { readFilter: readFilter ?? null } : {}),
    // [#4647] `allowed` answers the OBJECT question and `record` the ROW one;
    // what they may never do is contradict each other about the same row. The
    // pre-#4647 payload could carry `allowed: true` beside
    // `record: { visible: false, decidedBy: 'sharing' }` for a Modify All Data
    // holder — the row verdict denying what the bypass layer above it said was
    // skipped. They agree now because the row verdict comes from the write gate
    // that consults the same bypass `allowed`'s RLS composition short-circuits.
    ...(recordVerdict ? { record: recordVerdict } : {}),
  };
  return decision;
}