explain-engine.test.ts

// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
// ADR-0090 D6 — explain engine: layer verdicts, attribution, machine artifact.

import { describe, it, expect } from 'vitest';
import { resolveUserAuthzGrants, resetPlatformAdminEmailMemo } from '@objectstack/core';
import { ExplainDecisionSchema, PermissionSetSchema } from '@objectstack/spec/security';
import { PermissionEvaluator } from './permission-evaluator';
import { explainAccess, buildContextForUser, resolveDelegatorContext, type ExplainEngineDeps } from './explain-engine';
import { RLS_DENY_FILTER } from './rls-compiler';
import { unresolvedPostureRemedy } from './unresolved-posture';
import { assertEngineFindOnePredicate, type EngineFindOneQueryInput } from '@objectstack/metadata-core';
import { bindCatalogFromTables, ledgerFromTables } from './__tests__/security-catalog.testkit.js';

// [commit a68c61267] `ExplainDecision.layers` is `ExplainLayer[]` — the z.INPUT shape
// (ADR-0122), in which every `.default([])` member is OPTIONAL before a parse:
// a layer's `contributors`, and a record attribution's `rules`. The engine
// always populates both, which is why the assertions below reach through `?.`
// and not `!`: an absent member arrives at the matcher as `undefined` and the
// expectation still fails loudly, so the check survives the repair. This file
// was outside every tsc program in the package until `tsconfig.test.json`.

const SALES_USER = PermissionSetSchema.parse({
  name: 'sales_user',
  objects: { leave_request: { allowRead: true, allowCreate: true, readScope: 'unit' } },
});
const ADMIN = PermissionSetSchema.parse({
  name: 'admin_full_access',
  objects: { '*': { allowRead: true, allowCreate: true, allowEdit: true, allowDelete: true, viewAllRecords: true, modifyAllRecords: true } },
  systemPermissions: ['manage_users'],
});

const PRIVATE_SCHEMA = { name: 'leave_request', sharingModel: 'private' };

// The ONE engine double this file declares: a `ql` whose `findOne` resolves the
// `onBehalfOf` delegator, so D10 resolves instead of failing closed as
// 'missing' (which is a different report entirely). Shared by every test that
// needs a resolvable delegator — a second inline copy would be a second double
// for `check:engine-double-contract` to ratchet, and reusing the one the file
// already pins is cheaper than growing that ledger.
const DELEGATOR_QL = {
  getSchema: () => PRIVATE_SCHEMA,
  findOne: async (object: string, query?: EngineFindOneQueryInput) => {
    assertEngineFindOnePredicate(object, query);
    return { id: 'u_boss' };
  },
  find: async () => [],
};

function makeDeps(overrides: Partial<ExplainEngineDeps> & { sets?: any[]; schema?: any; rls?: any } = {}): ExplainEngineDeps {
  const evaluator = new PermissionEvaluator();
  return {
    ql: { getSchema: () => overrides.schema ?? PRIVATE_SCHEMA },
    resolveSets: async () => overrides.sets ?? [SALES_USER],
    evaluator,
    getObjectSecurityMeta: async () => ({
      isPrivate: false,
      requiredPermissions: { all: [], read: [], create: [], update: [], delete: [] },
      fieldRequiredPermissions: {},
    }),
    requiredCaps: (meta: any, op: string) => {
      const bucket = op === 'find' ? 'read' : op === 'insert' ? 'create' : op;
      return [...(meta.all ?? []), ...((meta as any)[bucket] ?? [])];
    },
    computeRlsFilter: async () => overrides.rls !== undefined ? overrides.rls : null,
    getFieldMask: () => ({}),
    getPartialMaskRules: async () => ({}),
    baselinePermissionSets: ['member_default'],
    tenancyPosture: 'single',
    ...overrides,
  };
}

const CTX = { userId: 'u1', positions: ['sales_rep', 'everyone'], permissions: [] };

describe('explainAccess (ADR-0090 D6)', () => {
  it('allows a granted read and attributes the granting set', async () => {
    const d = await explainAccess(makeDeps(), { object: 'leave_request', operation: 'read', context: CTX });
    expect(d.allowed).toBe(true);
    expect(d.principal).toMatchObject({ userId: 'u1', positions: ['sales_rep', 'everyone'], permissionSets: ['sales_user'] });
    const crud = d.layers.find((l) => l.layer === 'object_crud')!;
    expect(crud.verdict).toBe('grants');
    expect(crud.contributors).toEqual([{ kind: 'permission_set', name: 'sales_user', via: 'resolved' }]);
    // read decisions carry the composed machine artifact
    expect('readFilter' in d).toBe(true);
  });

  it('reports the full pipeline in order', async () => {
    const d = await explainAccess(makeDeps(), { object: 'leave_request', operation: 'read', context: CTX });
    expect(d.layers.map((l) => l.layer)).toEqual([
      'principal', 'required_permissions', 'object_crud', 'fls',
      'owd_baseline', 'depth', 'sharing', 'vama_bypass', 'rls',
    ]);
  });

  it('denies an ungranted operation and explains which layer denied', async () => {
    const d = await explainAccess(makeDeps(), { object: 'leave_request', operation: 'delete', context: CTX });
    expect(d.allowed).toBe(false);
    expect(d.layers.find((l) => l.layer === 'object_crud')!.verdict).toBe('denies');
  });

  it('surfaces the required_permissions AND-gate as the denying layer', async () => {
    const deps = makeDeps({
      getObjectSecurityMeta: async () => ({
        isPrivate: false,
        requiredPermissions: { all: ['manage_metadata'], read: [], create: [], update: [], delete: [] },
        fieldRequiredPermissions: {},
      }),
    });
    const d = await explainAccess(deps, { object: 'leave_request', operation: 'read', context: CTX });
    expect(d.allowed).toBe(false);
    const gate = d.layers.find((l) => l.layer === 'required_permissions')!;
    expect(gate.verdict).toBe('denies');
    expect(gate.detail).toContain('manage_metadata');
  });

  it('explains the leave_request incident shape: unset OWD reads as fail-closed private', async () => {
    const d = await explainAccess(
      makeDeps({ schema: { name: 'leave_request' } }), // no sharingModel declared
      { object: 'leave_request', operation: 'read', context: CTX },
    );
    const owd = d.layers.find((l) => l.layer === 'owd_baseline')!;
    expect(owd.verdict).toBe('narrows');
    expect(owd.detail).toContain('ADR-0090 D1');
  });

  it('reports VAMA bypass and org depth for an admin', async () => {
    const d = await explainAccess(makeDeps({ sets: [ADMIN] }), { object: 'leave_request', operation: 'read', context: { userId: 'admin', positions: ['platform_admin', 'everyone'], permissions: [] } });
    expect(d.allowed).toBe(true);
    expect(d.layers.find((l) => l.layer === 'vama_bypass')!.verdict).toBe('widens');
    expect(d.layers.find((l) => l.layer === 'depth')!.detail).toContain("'org'");
  });

  it('an RLS deny-all composition flips the decision to denied', async () => {
    const d = await explainAccess(
      makeDeps({ rls: { id: '__deny_all__' } }),
      { object: 'leave_request', operation: 'read', context: CTX },
    );
    expect(d.allowed).toBe(false);
    expect(d.layers.find((l) => l.layer === 'rls')!.verdict).toBe('denies');
  });

  it('carries D10 dual attribution when the context acts on behalf of a user', async () => {
    const d = await explainAccess(makeDeps(), {
      object: 'leave_request', operation: 'read',
      context: { ...CTX, principalKind: 'agent', onBehalfOf: { userId: 'u9' } },
    });
    expect(d.principal.principalKind).toBe('agent');
    expect(d.principal.onBehalfOf).toEqual({ userId: 'u9' });
    expect(d.layers[0].detail).toContain('on behalf of u9');
  });

  it('surfaces expired grants in the principal layer with the dedicated state (ADR-0091 D2)', async () => {
    const d = await explainAccess(makeDeps(), {
      object: 'leave_request', operation: 'read',
      context: {
        ...CTX,
        droppedGrants: [{ kind: 'position', name: 'payroll_approver', state: 'expired', until: '2026-07-01T00:00:00Z' }],
      },
    });
    const principal = d.layers.find((l) => l.layer === 'principal')!;
    expect(principal.detail).toContain('EXPIRED');
    expect(principal.detail).toContain('payroll_approver until 2026-07-01T00:00:00Z');
    expect(principal.contributors).toContainEqual({
      kind: 'position',
      name: 'payroll_approver',
      via: 'held until 2026-07-01T00:00:00Z — expired',
      state: 'expired',
    });
    // Expired grants contribute nothing to the resolved principal itself.
    expect(d.principal.positions).not.toContain('payroll_approver');
  });

  it('surfaces deactivated grants in the principal layer with the shared held-state vocabulary (ADR-0049 / #8714)', async () => {
    const d = await explainAccess(makeDeps(), {
      object: 'leave_request', operation: 'read',
      context: {
        ...CTX,
        droppedGrants: [
          { kind: 'permission_set', name: 'crm_full', state: 'deactivated' },
          { kind: 'position', name: 'field_auditor', state: 'deactivated' },
        ],
      },
    });
    const principal = d.layers.find((l) => l.layer === 'principal')!;
    expect(principal.detail).toContain('DEACTIVATED');
    expect(principal.detail).toContain('crm_full');
    expect(principal.detail).toContain('field_auditor');
    expect(principal.contributors).toContainEqual({
      kind: 'permission_set',
      name: 'crm_full',
      via: 'held — deactivated',
      state: 'deactivated',
    });
    expect(principal.contributors).toContainEqual({
      kind: 'position',
      name: 'field_auditor',
      via: 'held — deactivated',
      state: 'deactivated',
    });
    // Deactivated grants contribute nothing to the resolved principal itself.
    expect(d.principal.permissionSets).not.toContain('crm_full');
    expect(d.principal.positions).not.toContain('field_auditor');
  });

  it('expired and deactivated rows share ONE vocabulary — both states appear side by side in one principal layer (#8714)', async () => {
    const d = await explainAccess(makeDeps(), {
      object: 'leave_request', operation: 'read',
      context: {
        ...CTX,
        droppedGrants: [
          { kind: 'permission_set', name: 'quarter_close_admin', state: 'expired', until: '2026-06-01T00:00:00Z' },
          { kind: 'permission_set', name: 'crm_full', state: 'deactivated' },
        ],
      },
    });
    const principal = d.layers.find((l) => l.layer === 'principal')!;
    // `contributors` is the z.input type (defaulted, so optional pre-parse) —
    // normalize rather than dereference. Written when this file was outside
    // every tsc program and the motive was the TEST_DEBT ledger; it is the
    // right shape either way, and [commit a68c61267] made it the compiler's business.
    const dropped = (principal.contributors ?? []).filter((c) => c.state === 'expired' || c.state === 'deactivated');
    expect(dropped).toEqual([
      { kind: 'permission_set', name: 'quarter_close_admin', via: 'held until 2026-06-01T00:00:00Z — expired', state: 'expired' },
      { kind: 'permission_set', name: 'crm_full', via: 'held — deactivated', state: 'deactivated' },
    ]);
    expect(principal.detail).toContain('EXPIRED');
    expect(principal.detail).toContain('DEACTIVATED');
  });

  it('attributes a delegated position "via delegation from X until Y" in the principal layer (ADR-0091 D3)', async () => {
    const d = await explainAccess(makeDeps(), {
      object: 'leave_request', operation: 'read',
      context: {
        ...CTX,
        positions: ['sales_rep', 'approver', 'everyone'],
        delegatedPositions: [{ name: 'approver', from: 'u_boss', until: '2026-07-20T00:00:00Z' }],
      },
    });
    const principal = d.layers.find((l) => l.layer === 'principal')!;
    expect(principal.detail).toContain('held via delegation');
    expect(principal.detail).toContain('approver from u_boss until 2026-07-20T00:00:00Z');
    expect(principal.contributors).toContainEqual({
      kind: 'position',
      name: 'approver',
      via: 'delegation from u_boss until 2026-07-20T00:00:00Z',
    });
  });

  it('lists masked fields in the fls layer', async () => {
    const d = await explainAccess(
      makeDeps({ getFieldMask: () => ({ salary: { readable: false }, name: { readable: true } }) }),
      { object: 'leave_request', operation: 'read', context: CTX },
    );
    const fls = d.layers.find((l) => l.layer === 'fls')!;
    expect(fls.verdict).toBe('narrows');
    expect(fls.detail).toContain('salary');
  });
});

// ---------------------------------------------------------------------------
// [#9127] fls — the THREE-state field mask (hidden / partially masked /
// readable). #8993 landed partial masking on the enforcement channel; this
// layer reported only the binary mask, so a gated rule field read as fully
// hidden and a gate-less rule field as fully readable. `getPartialMaskRules`
// carries the enforcement composition in (never a re-derivation), and the
// hidden/partial split here is `FieldMasker.maskResults`' own.
// ---------------------------------------------------------------------------
describe('explainAccess — fls reports partial masking (#9127)', () => {
  const flsOf = async (over: Partial<ExplainEngineDeps> & { sets?: any[] }) => {
    const d = await explainAccess(makeDeps(over), {
      object: 'leave_request',
      operation: 'read',
      context: CTX,
    });
    return d.layers.find((l) => l.layer === 'fls')!;
  };

  it('HIDDEN: a field the mask denies with no applicable rule is still reported deleted', async () => {
    const fls = await flsOf({
      getFieldMask: () => ({ ssn: { readable: false }, name: { readable: true } }),
      getPartialMaskRules: async () => ({}),
    });
    expect(fls.verdict).toBe('narrows');
    expect(fls.detail).toContain('1 field(s) masked from responses');
    expect(fls.detail).toContain('ssn');
    expect(fls.detail).not.toContain('PARTIALLY');
  });

  it('[#25866] a row-conditioned entry (`when`) is reported AS a row-conditioned lock, not folded into the mask', async () => {
    // The card's shape: `amount` is locked on approved rows only. The report
    // holds no row, so it says so — which is also how every row-blind reader
    // applies the entry — instead of reporting a plain lock or nothing.
    const fls = await flsOf({
      sets: [
        {
          name: 'hr_user',
          objects: { leave_request: { allowRead: true, allowEdit: true } },
          fields: { 'leave_request.amount': { readable: true, editable: false, when: "status == 'approved'" } },
        },
      ] as any,
      getFieldMask: () => ({}),
      getPartialMaskRules: async () => ({}),
    });
    expect(fls.verdict).toBe('not_applicable');
    expect(fls.detail).toContain('No field-level masking applies.');
    expect(fls.detail).toContain('1 field permission(s) carry a row condition');
    expect(fls.detail).toContain('judged per row by the write gate');
    expect(fls.detail).toContain(`amount (locked when status == 'approved', set "hr_user")`);
  });

  // [#29610 / ruling of record 6573563853, letter A] A set holding Modify All
  // on the object votes editable on every field after the per-entry vote, under
  // every `when` verdict, so for that caller a conditioned lock binds on no row.
  // The report reads the SAME vote (`superuserFieldVote` through
  // `conditionedFieldEntries`), never a second copy of it.
  const CONDITIONED_AMOUNT = {
    'leave_request.amount': { readable: true, editable: false, when: "status == 'approved'" },
  };

  it('[#29610] a Modify All set supersedes a row-conditioned lock: the entry is reported as binding on no row', async () => {
    const fls = await flsOf({
      sets: [
        {
          name: 'hr_user',
          objects: { leave_request: { allowRead: true, allowEdit: true } },
          fields: CONDITIONED_AMOUNT,
        },
        {
          name: 'hr_admin',
          objects: { leave_request: { allowRead: true, allowEdit: true, viewAllRecords: true, modifyAllRecords: true } },
        },
      ] as any,
    });
    expect(fls.verdict).toBe('not_applicable');
    expect(fls.detail).not.toContain('judged per row by the write gate');
    expect(fls.detail).toContain('1 row-conditioned field permission(s) are superseded by the Modify All Data field vote [hr_admin]');
    expect(fls.detail).toContain('binds on no row');
    expect(fls.detail).toContain(`amount (locked when status == 'approved', set "hr_user")`);
  });

  it('[#29610] a View All set does NOT supersede it: the edit lock still binds per row (read-side control)', async () => {
    const fls = await flsOf({
      sets: [
        {
          name: 'hr_user',
          objects: { leave_request: { allowRead: true, allowEdit: true } },
          fields: CONDITIONED_AMOUNT,
        },
        {
          name: 'hr_auditor',
          objects: { leave_request: { allowRead: true, viewAllRecords: true } },
        },
      ] as any,
    });
    expect(fls.detail).toContain('1 field permission(s) carry a row condition — judged per row by the write gate');
    expect(fls.detail).toContain(`amount (locked when status == 'approved', set "hr_user")`);
    expect(fls.detail).not.toContain('superseded');
  });

  it('[#29610] a caller without the vote keeps the row-conditioned sentence as before (control)', async () => {
    const fls = await flsOf({
      sets: [
        {
          name: 'hr_user',
          objects: { leave_request: { allowRead: true, allowEdit: true } },
          fields: CONDITIONED_AMOUNT,
        },
      ] as any,
    });
    expect(fls.detail).toContain('1 field permission(s) carry a row condition — judged per row by the write gate');
    expect(fls.detail).not.toContain('superseded');
  });

  it('[#25866] an entry without a `when` adds no row-condition sentence', async () => {
    const fls = await flsOf({
      sets: [
        {
          name: 'hr_user',
          objects: { leave_request: { allowRead: true, allowEdit: true } },
          fields: { 'leave_request.amount': { readable: true, editable: false } },
        },
      ] as any,
    });
    expect(fls.detail).toBe('No field-level masking applies.');
  });

  it('PARTIAL (gated): a rule field the caller has not unmasked is NOT reported as hidden', async () => {
    // The requiredPermissions fold marks `phone` non-readable; the rule turns
    // that deletion into a replacement, so the caller receives `138****5678`,
    // not an absent key. Pre-#9127 this read "1 field(s) masked from
    // responses: [phone]" — the first misreport on the card.
    const fls = await flsOf({
      getFieldMask: () => ({ phone: { readable: false } }),
      getPartialMaskRules: async () => ({ phone: 'phone' }),
    });
    expect(fls.verdict).toBe('narrows');
    expect(fls.detail).not.toContain('masked from responses');
    expect(fls.detail).toContain('1 field(s) PARTIALLY masked');
    expect(fls.detail).toContain('phone (phone)');
  });

  it('PARTIAL (gate-less): a rule with no requiredPermissions is reported, not passed over', async () => {
    // No permission entry exists for `bank` — the binary mask is silent — yet
    // every non-system caller sees it masked. Pre-#9127 this layer answered
    // `not_applicable` / "No field-level masking applies": the second misreport.
    const fls = await flsOf({
      getFieldMask: () => ({}),
      getPartialMaskRules: async () => ({ bank: 'bank_account' }),
    });
    expect(fls.verdict).toBe('narrows');
    expect(fls.detail).not.toBe('No field-level masking applies.');
    expect(fls.detail).toContain('1 field(s) PARTIALLY masked');
    expect(fls.detail).toContain('bank (bank_account)');
  });

  it('READABLE: a field in neither set appears in neither list', async () => {
    const fls = await flsOf({
      getFieldMask: () => ({ ssn: { readable: false }, name: { readable: true } }),
      getPartialMaskRules: async () => ({ phone: 'phone' }),
    });
    expect(fls.detail).toContain('masked from responses: [ssn]');
    expect(fls.detail).toContain('PARTIALLY masked');
    expect(fls.detail).not.toContain('name');
  });

  it('reports all three states together, splitting hidden from partially masked', async () => {
    const fls = await flsOf({
      getFieldMask: () => ({
        ssn: { readable: false },
        phone: { readable: false },
        name: { readable: true },
      }),
      getPartialMaskRules: async () => ({ phone: 'phone', bank: 'bank_account' }),
    });
    expect(fls.verdict).toBe('narrows');
    // `phone` is denied by the binary mask AND carries a rule → partial, not hidden.
    expect(fls.detail).toContain('1 field(s) masked from responses: [ssn]');
    expect(fls.detail).toContain('2 field(s) PARTIALLY masked');
    expect(fls.detail).toContain('phone (phone)');
    expect(fls.detail).toContain('bank (bank_account)');
  });

  it('an explicit permission-set DENY stays HIDDEN — explain follows enforcement, it does not assume', async () => {
    // A rule never widens an explicit deny, so enforcement drops such fields
    // from `partialRules` before this layer sees them. The engine must report
    // whatever the composition hands it rather than re-deriving "has a rule ⇒
    // partial" — that second derivation is how explain drifted in the first place.
    const fls = await flsOf({
      getFieldMask: () => ({ phone: { readable: false } }),
      getPartialMaskRules: async () => ({}),
    });
    expect(fls.detail).toContain('masked from responses: [phone]');
    expect(fls.detail).not.toContain('PARTIALLY');
  });

  it('names an explicit keepHead/keepTail span rather than a preset', async () => {
    const fls = await flsOf({
      getPartialMaskRules: async () => ({ code: { keepHead: 2, keepTail: 2 } }),
    });
    expect(fls.detail).toContain('code (keepHead 2, keepTail 2)');
  });

  it('keeps the D10 delegator suffix when only partial masks apply', async () => {
    const d = await explainAccess(
      makeDeps({
        ql: DELEGATOR_QL, // resolvable delegator — otherwise D10 fails closed
        getPartialMaskRules: async () => ({ phone: 'phone' }),
      }),
      {
        object: 'leave_request',
        operation: 'read',
        context: { ...CTX, onBehalfOf: { userId: 'u_boss' } },
      },
    );
    const fls = d.layers.find((l) => l.layer === 'fls')!;
    expect(fls.detail).toContain('PARTIALLY masked');
    expect(fls.detail).toContain('D10');
  });

  it('stays not_applicable when neither dimension applies', async () => {
    const fls = await flsOf({});
    expect(fls.verdict).toBe('not_applicable');
    expect(fls.detail).toBe('No field-level masking applies.');
  });

  it('passes the delegator sets through to the enforcement composition (D10)', async () => {
    let seen: unknown = 'not-called';
    await flsOf({
      getPartialMaskRules: async (_sets, _object, delegatorSets) => {
        seen = delegatorSets;
        return {};
      },
    });
    // No on-behalf-of in CTX → the engine must pass null, not undefined.
    expect(seen).toBeNull();
  });
});

describe('explainAccess — record-grained (C2 / ADR-0095)', () => {
  const REC_CTX = { userId: 'u1', tenantId: 'org1', positions: ['sales_rep', 'everyone'], permissions: [] };

  function recDeps(opts: {
    layered?: { layer0: any; layer1: any };
    record?: Record<string, unknown> | null;
    sharingFilter?: unknown;
    shares?: any[];
    canEdit?: boolean;
    sets?: any[];
    schema?: any;
  } = {}): ExplainEngineDeps {
    const base = makeDeps({ sets: opts.sets, schema: opts.schema });
    return {
      ...base,
      computeLayeredRlsFilter: async () => opts.layered ?? { layer0: null, layer1: null },
      fetchRecord: async () => (opts.record !== undefined ? opts.record : { id: 'r1', organization_id: 'org1', owner_id: 'u1' }),
      sharingReadFilter: async () => (opts.sharingFilter !== undefined ? opts.sharingFilter : null),
      listRecordShares: async () => opts.shares ?? [],
      canEditRecord: async () => opts.canEdit ?? false,
    };
  }

  it('leaves the object-level report byte-identical when no recordId is supplied (backward compat)', async () => {
    const d = await explainAccess(recDeps(), { object: 'leave_request', operation: 'read', context: REC_CTX });
    expect(d.record).toBeUndefined();
    expect(d.principal).not.toHaveProperty('posture');
    expect(d.layers.map((l) => l.layer)).toEqual([
      'principal', 'required_permissions', 'object_crud', 'fls',
      'owd_baseline', 'depth', 'sharing', 'vama_bypass', 'rls',
    ]);
    expect(d.layers.every((l) => l.kernelTier === undefined)).toBe(true);
    expect(d.layers.every((l) => l.record === undefined)).toBe(true);
  });

  it('prepends the tenant_isolation Layer 0, tags every layer with kernelTier, and resolves posture', async () => {
    const d = await explainAccess(
      recDeps({ layered: { layer0: { organization_id: 'org1' }, layer1: null }, record: { id: 'r1', organization_id: 'org1', owner_id: 'u1' } }),
      { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'r1' },
    );
    expect(d.layers[0].layer).toBe('tenant_isolation');
    expect(d.layers[0].kernelTier).toBe('layer_0_tenant');
    expect(d.layers.find((l) => l.layer === 'rls')!.kernelTier).toBe('layer_1_business');
    expect(d.principal.posture).toBe('MEMBER');
    expect(d.record).toMatchObject({ recordId: 'r1', visible: true });
  });

  it('derives PLATFORM_ADMIN posture from the platform-grant flag', async () => {
    // [#15981] Was "from the platform_admin position". The NAME is no longer
    // that evidence: `positions[]` is the security axis and carries ADR-0057 D4
    // `sys_user_position` names from an `apiEnabled` table, so a tenant can mint
    // one spelling the built-in. `hasPlatformAdminGrant` is what
    // `buildContextForUser` sets from `grants.posture === 'PLATFORM_ADMIN'`.
    const d = await explainAccess(
      recDeps({ sets: [ADMIN], layered: { layer0: null, layer1: null } }),
      { object: 'leave_request', operation: 'read', context: { userId: 'a1', tenantId: 'org1', positions: ['platform_admin', 'everyone'], permissions: [], hasPlatformAdminGrant: true }, recordId: 'r1' },
    );
    expect(d.principal.posture).toBe('PLATFORM_ADMIN');
  });

  it('[#15981] the platform_admin NAME alone does not — it reports MEMBER', async () => {
    const d = await explainAccess(
      recDeps({ sets: [ADMIN], layered: { layer0: null, layer1: null } }),
      { object: 'leave_request', operation: 'read', context: { userId: 'a1', tenantId: 'org1', positions: ['platform_admin', 'everyone'], permissions: [] }, recordId: 'r1' },
    );
    expect(d.principal.posture).toBe('MEMBER');
  });

  it('Layer 0 (the tenant wall) excludes a cross-org record — decidedBy tenant_isolation', async () => {
    const d = await explainAccess(
      recDeps({ layered: { layer0: { organization_id: 'org1' }, layer1: null }, record: { id: 'r1', organization_id: 'org2', owner_id: 'u1' } }),
      { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'r1' },
    );
    const tenant = d.layers.find((l) => l.layer === 'tenant_isolation')!;
    expect(tenant.record!.outcome).toBe('excluded');
    expect(tenant.record!.rules?.[0]).toMatchObject({ kind: 'tenant_filter', effect: 'excludes' });
    expect(d.record).toMatchObject({ visible: false, decidedBy: 'tenant_isolation' });
  });

  it('Layer 1 (business RLS) excludes a non-matching record — decidedBy rls', async () => {
    const d = await explainAccess(
      recDeps({ layered: { layer0: null, layer1: { status: 'open' } }, record: { id: 'r1', organization_id: 'org1', owner_id: 'u1', status: 'closed' } }),
      { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'r1' },
    );
    const rls = d.layers.find((l) => l.layer === 'rls')!;
    expect(rls.record!.outcome).toBe('excluded');
    expect(rls.record!.matchesRecord).toBe(false);
    expect(d.record).toMatchObject({ visible: false, decidedBy: 'rls' });
  });

  it('a record_share admits a non-owner on a private object — sharing admits, decidedBy sharing', async () => {
    const d = await explainAccess(
      recDeps({
        layered: { layer0: null, layer1: null },
        record: { id: 'r1', organization_id: 'org1', owner_id: 'u_other' },
        shares: [{ id: 'shr_1', recipient_type: 'user', recipient_id: 'u1', access_level: 'read', source: 'manual' }],
        sharingFilter: { $or: [{ owner_id: 'u1' }, { id: { $in: ['r1'] } }] },
      }),
      { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'r1' },
    );
    const sharing = d.layers.find((l) => l.layer === 'sharing')!;
    expect(sharing.record!.outcome).toBe('admitted');
    expect(sharing.record!.rules?.[0]).toMatchObject({ kind: 'record_share', effect: 'admits', grants: 'read' });
    expect(d.record).toMatchObject({ visible: true, decidedBy: 'sharing' });
  });

  // [#26180] A pending approval step the principal is on grants READ of the
  // one record: the sharing service ORs its record id in, and explain names
  // the request it came through — on a read, and as no grant on a write.
  it('[#26180] names the pending approval request a read comes through: "via approval request N"', async () => {
    const asked: unknown[] = [];
    const deps = (canEdit?: boolean) => ({
      ...recDeps({
        layered: { layer0: null, layer1: null },
        record: { id: 'r1', organization_id: 'org1', owner_id: 'u_other' },
        shares: [],
        sharingFilter: { $or: [{ owner_id: 'u1' }, { id: { $in: ['r1'] } }] },
        canEdit,
      }),
      listApprovalReadGrants: async (object: string, recordId: string, context: unknown) => {
        asked.push([object, recordId, context]);
        return ['apr_7'];
      },
    });
    const read = await explainAccess(deps(), { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'r1' });
    const sharing = read.layers.find((l) => l.layer === 'sharing')!;
    expect(sharing.record!.outcome).toBe('admitted');
    expect(sharing.record!.rules).toEqual([
      { kind: 'record_share', name: 'apr_7', grants: 'read', via: 'approval request apr_7', effect: 'admits' },
    ]);
    expect(sharing.record!.detail).toContain('via approval request apr_7');
    expect(read.record).toMatchObject({ visible: true, decidedBy: 'sharing' });
    // Asked with the EXPLAINED principal's context, for this record.
    expect(asked).toEqual([['leave_request', 'r1', REC_CTX]]);

    // A write: the same grant is evaluated, grants no write, and the gate decides.
    const update = await explainAccess(deps(false), { object: 'leave_request', operation: 'update', context: REC_CTX, recordId: 'r1' });
    const writeSharing = update.layers.find((l) => l.layer === 'sharing')!;
    expect(writeSharing.record!.rules).toEqual([
      { kind: 'record_share', name: 'apr_7', grants: 'read', via: 'approval request apr_7', effect: 'neutral' },
    ]);
    expect(writeSharing.record!.outcome).toBe('excluded');
    expect(update.record).toMatchObject({ visible: false });
  });

  it('[#26180] a failing approval lookup attributes nothing and fails nothing', async () => {
    const d = await explainAccess(
      {
        ...recDeps({ layered: { layer0: null, layer1: null }, record: { id: 'r1', organization_id: 'org1', owner_id: 'u_other' }, shares: [], sharingFilter: { owner_id: 'u1' } }),
        listApprovalReadGrants: async () => { throw new Error('approvals unavailable'); },
      },
      { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'r1' },
    );
    expect(d.layers.find((l) => l.layer === 'sharing')!.record!.rules).toEqual([]);
    expect(d.record).toMatchObject({ visible: false, decidedBy: 'sharing' });
  });

  it('private object, non-owner, no admitting share — not visible, decidedBy sharing', async () => {
    const d = await explainAccess(
      recDeps({ layered: { layer0: null, layer1: null }, record: { id: 'r1', organization_id: 'org1', owner_id: 'u_other' }, shares: [], sharingFilter: { owner_id: 'u1' } }),
      { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'r1' },
    );
    expect(d.layers.find((l) => l.layer === 'sharing')!.record!.outcome).toBe('excluded');
    expect(d.record).toMatchObject({ visible: false, decidedBy: 'sharing' });
  });

  it('a missing record yields not_evaluated row layers and an invisible verdict', async () => {
    const d = await explainAccess(
      recDeps({ record: null }),
      { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'missing' },
    );
    expect(d.record).toMatchObject({ visible: false });
    expect(d.record!.decidedBy).toBeUndefined();
    expect(d.layers.find((l) => l.layer === 'rls')!.record!.outcome).toBe('not_evaluated');
    expect(d.layers.find((l) => l.layer === 'tenant_isolation')!.record!.outcome).toBe('not_evaluated');
  });

  it('write ops use the sharing service canEdit as the by-construction verdict', async () => {
    const editor = PermissionSetSchema.parse({ name: 'editor', objects: { leave_request: { allowRead: true, allowEdit: true } } });
    const d = await explainAccess(
      recDeps({ sets: [editor], layered: { layer0: null, layer1: null }, record: { id: 'r1', organization_id: 'org1', owner_id: 'u_other' }, canEdit: true, shares: [] }),
      { object: 'leave_request', operation: 'update', context: REC_CTX, recordId: 'r1' },
    );
    expect(d.layers.find((l) => l.layer === 'sharing')!.record!.outcome).toBe('admitted');
    expect(d.record).toMatchObject({ recordId: 'r1', visible: true });
  });

  // ── [ADR-0142 D3/D4] the queue story on the sharing layer ──────────────
  const QUEUED_ROW = { id: 'r1', organization_id: 'org1', owner_id: null, queue: 'support_intake' };
  const queueMember = (members: string[]) => async (userId: string, queue: string, org: string | null) =>
    queue === 'support_intake' && org === 'org1' && members.includes(userId);

  it('[ADR-0142 D3] a record sitting in a queue reports queue_membership — admits a member', async () => {
    const d = await explainAccess(
      { ...recDeps({ layered: { layer0: null, layer1: null }, record: QUEUED_ROW }), queueMember: queueMember(['u1']) },
      { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'r1' },
    );
    const rules = d.layers.find((l) => l.layer === 'sharing')!.record!.rules ?? [];
    expect(rules).toContainEqual(expect.objectContaining({ kind: 'queue_membership', name: 'support_intake', effect: 'admits' }));
    expect(ExplainDecisionSchema.safeParse(d).success).toBe(true);
  });

  it('[ADR-0142 D3] a non-member is reported neutral, an owned record reports no queue rule at all', async () => {
    const outsider = await explainAccess(
      { ...recDeps({ layered: { layer0: null, layer1: null }, record: QUEUED_ROW }), queueMember: queueMember(['u2']) },
      { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'r1' },
    );
    expect(outsider.layers.find((l) => l.layer === 'sharing')!.record!.rules)
      .toContainEqual(expect.objectContaining({ kind: 'queue_membership', effect: 'neutral' }));
    const owned = await explainAccess(
      { ...recDeps({ layered: { layer0: null, layer1: null }, record: { ...QUEUED_ROW, owner_id: 'u9' } }), queueMember: queueMember(['u1']) },
      { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'r1' },
    );
    expect((owned.layers.find((l) => l.layer === 'sharing')!.record!.rules ?? []).map((r) => r.kind)).not.toContain('queue_membership');
  });

  it('[ADR-0142 D4] a transfer of an unowned record reports queue_claim from the sharing verdict', async () => {
    const asked: unknown[] = [];
    const claimant = await explainAccess(
      {
        ...recDeps({ layered: { layer0: null, layer1: null }, record: QUEUED_ROW }),
        queueMember: queueMember(['u1']),
        claimVerdict: async (o, rid) => { asked.push([o, rid]); return 'allow'; },
      },
      { object: 'leave_request', operation: 'transfer', context: REC_CTX, recordId: 'r1' },
    );
    expect(asked).toEqual([['leave_request', 'r1']]);
    expect(claimant.layers.find((l) => l.layer === 'sharing')!.record!.rules)
      .toContainEqual(expect.objectContaining({ kind: 'queue_claim', name: 'support_intake', effect: 'admits' }));
    const refused = await explainAccess(
      { ...recDeps({ layered: { layer0: null, layer1: null }, record: QUEUED_ROW }), claimVerdict: async () => 'abstain' },
      { object: 'leave_request', operation: 'transfer', context: REC_CTX, recordId: 'r1' },
    );
    expect(refused.layers.find((l) => l.layer === 'sharing')!.record!.rules)
      .toContainEqual(expect.objectContaining({ kind: 'queue_claim', effect: 'neutral' }));
  });

  it('[ADR-0142 D3] a delete explanation reports no queue rule — queue members never delete', async () => {
    const d = await explainAccess(
      {
        ...recDeps({ layered: { layer0: null, layer1: null }, record: QUEUED_ROW }),
        queueMember: queueMember(['u1']),
        claimVerdict: async () => 'allow',
      },
      { object: 'leave_request', operation: 'delete', context: REC_CTX, recordId: 'r1' },
    );
    const kinds = (d.layers.find((l) => l.layer === 'sharing')!.record!.rules ?? []).map((r) => r.kind);
    expect(kinds).not.toContain('queue_membership');
    expect(kinds).not.toContain('queue_claim');
  });

  // ── [#4647] the bypass, at row granularity ──────────────────────────────
  // The report: `allowed: true` + a `vama_bypass` layer saying "ownership and
  // sharing checks are skipped", sitting next to `record: { visible: false,
  // decidedBy: 'sharing' }` — one payload, two opposite answers. Under the
  // ruling the bypass is real, so the ROW story has to show it (and the write
  // gate, which now consults the same predicate, agrees).
  const VIEW_ONLY = PermissionSetSchema.parse({
    name: 'compliance_auditor',
    objects: { '*': { allowRead: true, allowEdit: true, viewAllRecords: true } },
  });
  const OWNERLESS_ROW = { id: 'r1', organization_id: 'org1', owner_id: null };
  const ADMIN_CTX = { userId: 'a1', tenantId: 'org1', positions: ['platform_admin', 'everyone'], permissions: [] };

  it('[#4647] Modify All Data admits an OWNERLESS private record — record verdict agrees with the top level', async () => {
    const d = await explainAccess(
      recDeps({
        sets: [ADMIN], layered: { layer0: null, layer1: null },
        record: OWNERLESS_ROW, shares: [], sharingFilter: { owner_id: 'a1' },
        canEdit: true, // the fixed gate: ownership fails, the bypass admits
      }),
      { object: 'leave_request', operation: 'update', context: ADMIN_CTX, recordId: 'r1' },
    );
    expect(d.allowed).toBe(true);
    expect(d.record).toMatchObject({ visible: true, decidedBy: 'vama_bypass' });
    const vama = d.layers.find((l) => l.layer === 'vama_bypass')!;
    expect(vama.verdict).toBe('widens');
    expect(vama.record!.outcome).toBe('admitted');
    // The sharing layer credits the bypass rather than claiming a share it never saw.
    expect(d.layers.find((l) => l.layer === 'sharing')!.record!.detail).toContain('Modify All Data bypass');
  });

  it('[#4647] View All Data alone does NOT bypass a WRITE — and the layer names the missing bit', async () => {
    const d = await explainAccess(
      recDeps({
        sets: [VIEW_ONLY], layered: { layer0: null, layer1: null },
        record: OWNERLESS_ROW, shares: [], sharingFilter: { owner_id: 'a1' },
        canEdit: false, // the gate refuses: no modify bit
      }),
      { object: 'leave_request', operation: 'update', context: ADMIN_CTX, recordId: 'r1' },
    );
    expect(d.record!.visible).toBe(false);
    const vama = d.layers.find((l) => l.layer === 'vama_bypass')!;
    expect(vama.verdict).toBe('not_applicable');
    expect(vama.detail).toContain('View All Data');
    expect(vama.detail).toContain('Modify All Data');
    expect(vama.contributors).toEqual([]);
  });

  it('[#4647] the same View All Data set DOES bypass a READ of that record', async () => {
    const d = await explainAccess(
      recDeps({
        sets: [VIEW_ONLY], layered: { layer0: null, layer1: null },
        record: OWNERLESS_ROW, shares: [], sharingFilter: { owner_id: 'a1' },
      }),
      { object: 'leave_request', operation: 'read', context: ADMIN_CTX, recordId: 'r1' },
    );
    const vama = d.layers.find((l) => l.layer === 'vama_bypass')!;
    expect(vama.verdict).toBe('widens');
    expect(vama.contributors?.map((c) => c.name)).toEqual(['compliance_auditor']);
    expect(d.record).toMatchObject({ visible: true, decidedBy: 'vama_bypass' });
  });

  // ── read depth, at row granularity ──────────────────────────────────────
  // The sharing read filter is one predicate carrying two grants: the
  // owner-match the read depth widens, OR-ed with the caller's own shares. A
  // row the filter admits with no share and no ownership behind it was admitted
  // by the depth, and the report names the depth layer, not sharing.
  describe('read depth admits a row that no share does', () => {
    const ORG_READER = PermissionSetSchema.parse({
      name: 'org_reader',
      objects: { leave_request: { allowRead: true, readScope: 'org' } },
    });
    const NOT_MINE = { id: 'r1', organization_id: 'org1', owner_id: 'u_other' };
    const RULE_SHARE = {
      id: 'shr_rule', recipient_type: 'user', recipient_id: 'u1', access_level: 'read' as const,
      source: 'rule', source_id: 'rule_open_requests',
    };
    const layerRecord = (d: { layers: Array<{ layer: string; record?: any }> }, layer: string) =>
      d.layers.find((l) => l.layer === layer)!.record!;
    const read = (deps: ExplainEngineDeps, context: any = REC_CTX) =>
      explainAccess(deps, { object: 'leave_request', operation: 'read', context, recordId: 'r1' });

    it("org depth: the row explains as decidedBy 'depth', with a depth-layer record block", async () => {
      // At org depth plugin-sharing composes no owner-match: the filter is null.
      const d = await read(recDeps({ sets: [ORG_READER], record: NOT_MINE, shares: [], sharingFilter: null }));
      expect(d.record).toMatchObject({ visible: true, decidedBy: 'depth' });
      const depth = layerRecord(d, 'depth');
      expect(depth.outcome).toBe('admitted');
      expect(depth.detail).toContain("read depth 'org'");
      const sharing = layerRecord(d, 'sharing');
      expect(sharing.outcome).not.toBe('admitted');
      expect(sharing.detail).not.toContain('access is granted');
      expect(sharing.detail).toContain('see the depth layer');
    });

    it("unit depth: an owner inside the caller's unit explains as 'depth', naming the owner", async () => {
      const d = await read(recDeps({ record: NOT_MINE, shares: [], sharingFilter: { owner_id: { $in: ['u1', 'u_other'] } } }));
      expect(d.record).toMatchObject({ visible: true, decidedBy: 'depth' });
      expect(layerRecord(d, 'depth').outcome).toBe('admitted');
      expect(layerRecord(d, 'depth').detail).toContain("owner (u_other) is inside the caller's 'unit' read depth");
      expect(layerRecord(d, 'sharing').outcome).toBe('not_evaluated');
    });

    it("unit depth: an owner outside the caller's unit is excluded by the depth layer too", async () => {
      const d = await read(recDeps({ record: NOT_MINE, shares: [], sharingFilter: { owner_id: { $in: ['u1'] } } }));
      expect(d.record).toMatchObject({ visible: false, decidedBy: 'sharing' });
      expect(layerRecord(d, 'depth').outcome).toBe('excluded');
      expect(layerRecord(d, 'sharing').outcome).toBe('excluded');
    });

    // [#26188] With no hierarchy resolver the sharing service evaluates 'unit'
    // as 'own' (an owner-only filter), so the depth cell names the absent
    // resolver, not the caller's unit. A resolver mounted reads as before.
    it("unit depth, no hierarchy resolver: the depth cell names the absent resolver, not the depth", async () => {
      const deps = { ...recDeps({ record: NOT_MINE, shares: [], sharingFilter: { owner_id: { $in: ['u1'] } } }), hierarchyResolverMounted: () => false };
      const d = await read(deps);
      expect(d.record).toMatchObject({ visible: false, decidedBy: 'sharing' });
      const depth = layerRecord(d, 'depth');
      expect(depth.outcome).toBe('excluded');
      expect(depth.detail).toMatch(/^Hierarchy resolver absent — requires enterprise; depth evaluated as 'own'\./);
      expect(depth.detail).not.toContain("outside the caller's");
    });

    it("unit depth, hierarchy resolver mounted: an owner outside the unit is still blamed on the depth", async () => {
      const deps = { ...recDeps({ record: NOT_MINE, shares: [], sharingFilter: { owner_id: { $in: ['u1'] } } }), hierarchyResolverMounted: () => true };
      const depth = layerRecord(await read(deps), 'depth');
      expect(depth.outcome).toBe('excluded');
      expect(depth.detail).toContain("owner (u_other) is outside the caller's 'unit' read depth");
    });

    it("a criteria rule's share still explains as 'sharing', with '1 share(s) attached'", async () => {
      // A criteria sharing rule materialises as a `sys_record_share` row with
      // `source: 'rule'` naming the matched user (sharing-rule-service.ts).
      const d = await read(recDeps({
        record: NOT_MINE,
        shares: [RULE_SHARE],
        sharingFilter: { $or: [{ owner_id: { $in: ['u1'] } }, { id: { $in: ['r1'] } }] },
      }));
      expect(d.record).toMatchObject({ visible: true, decidedBy: 'sharing' });
      const sharing = layerRecord(d, 'sharing');
      expect(sharing.outcome).toBe('admitted');
      expect(sharing.detail).toBe('1 share(s) attached; access is granted for this record.');
      expect(sharing.rules?.[0]).toMatchObject({ kind: 'sharing_rule', name: 'rule_open_requests', effect: 'admits' });
    });

    it("a share AND org depth: 'sharing' decides, the last layer to admit; the depth layer admits as well", async () => {
      const d = await read(recDeps({ sets: [ORG_READER], record: NOT_MINE, shares: [RULE_SHARE], sharingFilter: null }));
      expect(d.record).toMatchObject({ visible: true, decidedBy: 'sharing' });
      expect(layerRecord(d, 'depth').outcome).toBe('admitted');
    });

    it("a share AND unit depth: 'sharing' decides; the depth layer says it cannot separate the two", async () => {
      const d = await read(recDeps({
        record: NOT_MINE,
        shares: [RULE_SHARE],
        sharingFilter: { $or: [{ owner_id: { $in: ['u1', 'u_other'] } }, { id: { $in: ['r1'] } }] },
      }));
      expect(d.record).toMatchObject({ visible: true, decidedBy: 'sharing' });
      expect(layerRecord(d, 'depth').outcome).toBe('not_evaluated');
      expect(layerRecord(d, 'depth').detail).toContain('not separated');
    });

    it('below org, a null filter is the sharing service imposing nothing — not the depth', async () => {
      const d = await read(recDeps({ record: NOT_MINE, shares: [], sharingFilter: null }));
      expect(d.record).toMatchObject({ visible: true, decidedBy: 'sharing' });
      const sharing = layerRecord(d, 'sharing');
      expect(sharing.detail).toContain('imposes no owner-match');
      expect(sharing.detail).not.toContain('access is granted');
      expect(layerRecord(d, 'depth').outcome).toBe('not_evaluated');
    });

    it('an on-behalf-of read never credits the depth: its filter is asked with no depth stamped', async () => {
      const d = await read(
        { ...recDeps({ record: NOT_MINE, shares: [], sharingFilter: { owner_id: { $in: ['u1', 'u_other'] } } }), ql: DELEGATOR_QL },
        { ...REC_CTX, onBehalfOf: { userId: 'u_boss' } },
      );
      expect(d.record?.visible).toBe(true);
      expect(d.record?.decidedBy).not.toBe('depth');
      expect(layerRecord(d, 'depth').outcome).toBe('not_evaluated');
      expect(layerRecord(d, 'sharing').detail).not.toContain('access is granted');
    });
  });

  // ── every published decider is reachable ────────────────────────────────
  // The enum is read from the spec, never restated here: a member the spec
  // gains, and no branch of the decision tree produces, fails by name until a
  // scenario produces it or the ledger below says why none can.
  describe('decision.record.decidedBy: each published member is produced by a branch, or ledgered', () => {
    const DECIDED_BY: readonly string[] =
      ExplainDecisionSchema.shape.record.unwrap().shape.decidedBy.unwrap().options;
    const VIEW_ALL = PermissionSetSchema.parse({
      name: 'compliance_auditor',
      objects: { '*': { allowRead: true, viewAllRecords: true } },
    });
    const CAPS_GATED = {
      isPrivate: false,
      requiredPermissions: { all: [], read: ['manage_metadata'], create: [], update: [], delete: [] },
      fieldRequiredPermissions: {},
    };
    const NOT_MINE = { id: 'r1', organization_id: 'org1', owner_id: 'u_other' };
    const ask = (deps: ExplainEngineDeps, operation: 'read' | 'delete' = 'read') =>
      explainAccess(deps, { object: 'leave_request', operation, context: REC_CTX, recordId: 'r1' });

    const PRODUCERS: Record<string, () => Promise<{ record?: { decidedBy?: string } }>> = {
      tenant_isolation: () => ask(recDeps({
        layered: { layer0: { organization_id: 'org1' }, layer1: null },
        record: { ...NOT_MINE, organization_id: 'org2' },
      })),
      required_permissions: () => ask({ ...recDeps(), getObjectSecurityMeta: async () => CAPS_GATED }),
      object_crud: () => ask(recDeps(), 'delete'),
      owd_baseline: () => ask(recDeps({ record: { id: 'r1', organization_id: 'org1', owner_id: 'u1' } })),
      depth: () => ask(recDeps({ record: NOT_MINE, shares: [], sharingFilter: { owner_id: { $in: ['u1', 'u_other'] } } })),
      sharing: () => ask(recDeps({
        record: NOT_MINE,
        shares: [{ id: 'shr_1', recipient_type: 'user', recipient_id: 'u1', access_level: 'read', source: 'manual' }],
        sharingFilter: { $or: [{ owner_id: { $in: ['u1'] } }, { id: { $in: ['r1'] } }] },
      })),
      vama_bypass: () => ask(recDeps({ sets: [VIEW_ALL], record: NOT_MINE, shares: [], sharingFilter: { owner_id: 'u1' } })),
      rls: () => ask(recDeps({
        layered: { layer0: null, layer1: { status: 'open' } },
        record: { ...NOT_MINE, owner_id: 'u1', status: 'closed' },
      })),
    };
    const NOT_PRODUCED: Record<string, string> = {
      principal:
        'The principal layer resolves who is asking and which sets they hold; it never judges a row. A principal ' +
        'whose grants fail to resolve (a missing or unresolvable delegator) is refused at object_crud, which is ' +
        'the layer the tree names for it.',
      fls:
        'Field-level security masks fields of a row that is served; it never admits or removes the row, so it ' +
        'cannot decide whether the row is visible.',
    };

    it('the producers and the ledger partition the enum exactly', () => {
      for (const member of DECIDED_BY) {
        const produced = member in PRODUCERS;
        const ledgered = member in NOT_PRODUCED;
        expect(produced || ledgered, `decidedBy member '${member}' is produced by no branch and carries no ledger reason`).toBe(true);
        expect(produced && ledgered, `decidedBy member '${member}' is both produced and ledgered`).toBe(false);
      }
      for (const key of [...Object.keys(PRODUCERS), ...Object.keys(NOT_PRODUCED)]) {
        expect(DECIDED_BY, `'${key}' is not a member of the published decidedBy enum`).toContain(key);
      }
      for (const [member, reason] of Object.entries(NOT_PRODUCED)) {
        expect(reason.trim().length, `the ledger entry for '${member}' carries no reason`).toBeGreaterThan(0);
      }
    });

    it.each(Object.keys(PRODUCERS))("'%s' is produced by the branch its scenario drives", async (member) => {
      const d = await PRODUCERS[member]();
      expect(d.record?.decidedBy).toBe(member);
    });
  });

  it('degrades gracefully with no record-grained deps — object-level layers plus a best-effort verdict', async () => {
    // Only the base object-level deps: recordId is given but fetchRecord /
    // computeLayeredRlsFilter etc. are absent (e.g. no plugin-sharing).
    const d = await explainAccess(makeDeps(), { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'r1' });
    expect(d.layers[0].layer).toBe('tenant_isolation');
    expect(d.record).toMatchObject({ recordId: 'r1' });
    // record could not be fetched → not_evaluated tenant + invisible.
    expect(d.layers.find((l) => l.layer === 'tenant_isolation')!.record!.outcome).toBe('not_evaluated');
  });
});

describe('posture derivation aligns with enforcement (label-drift elimination)', () => {
  // posture is surfaced whenever a recordId is supplied; the record-grained deps
  // are irrelevant to the posture value, so the base object-level deps suffice.
  const postureOf = async (context: any): Promise<string | undefined> => {
    const d = await explainAccess(makeDeps({ sets: [ADMIN] }), {
      object: 'leave_request',
      operation: 'read',
      context,
      recordId: 'r1',
    });
    return d.principal.posture;
  };

  it('reuses ctx.posture verbatim when enforcement already resolved it', async () => {
    // A principal resolved through resolveAuthzContext carries ctx.posture — the
    // explain panel must echo it, never re-derive a different tier.
    expect(await postureOf({ userId: 'a1', tenantId: 'org1', positions: ['everyone'], permissions: [], posture: 'PLATFORM_ADMIN' })).toBe('PLATFORM_ADMIN');
    expect(await postureOf({ userId: 'a1', tenantId: 'org1', positions: ['everyone'], permissions: [], posture: 'TENANT_ADMIN' })).toBe('TENANT_ADMIN');
    // Explicit posture wins over what the loose fallback would have guessed.
    expect(await postureOf({ userId: 'a1', tenantId: 'org1', positions: ['everyone'], permissions: ['admin_full_access'], posture: 'MEMBER' })).toBe('MEMBER');
  });

  it('a merely-SCOPED admin_full_access grant no longer over-labels as PLATFORM_ADMIN', async () => {
    // Name present in `permissions` but NOT held as the anchoring grant and NOT
    // the projected platform_admin position → MEMBER, matching enforcement (which
    // requires hasPlatformAdminGrant = the Default Organization's
    // admin_full_access user grant).
    expect(await postureOf({ userId: 'a1', tenantId: 'org1', positions: ['everyone'], permissions: ['admin_full_access'] })).toBe('MEMBER');
  });

  it('the platform-grant flag (hasPlatformAdminGrant) DOES yield PLATFORM_ADMIN', async () => {
    expect(await postureOf({ userId: 'a1', tenantId: 'org1', positions: ['everyone'], permissions: ['admin_full_access'], hasPlatformAdminGrant: true })).toBe('PLATFORM_ADMIN');
  });

  it('[#15981] the platform_admin built-in position NAME no longer yields PLATFORM_ADMIN', async () => {
    // This assertion is INVERTED from what it pinned before, deliberately. It
    // used to read "the PROJECTED platform_admin built-in position still yields
    // PLATFORM_ADMIN", whose premise was that the name is only ever projected
    // from the anchoring `admin_full_access` grant. Ruling A made `positions[]`
    // the security axis, so it now also carries ADR-0057 D4
    // `sys_user_position` names — and that table is `apiEnabled` with
    // unconstrained values, so the name can be MINTED by a tenant. The genuine
    // projection is not lost: a real operator's context carries
    // `hasPlatformAdminGrant` (the case immediately above) and, off
    // `buildContextForUser`, `posture` itself.
    expect(await postureOf({ userId: 'a1', tenantId: 'org1', positions: ['platform_admin', 'everyone'], permissions: [] })).toBe('MEMBER');
  });

  it('[#15981] …and the two are separable only by the rung, not by the array', async () => {
    const minted = { userId: 'a1', tenantId: 'org1', positions: ['platform_admin', 'everyone'], permissions: [] };
    const genuine = { ...minted, hasPlatformAdminGrant: true };
    // Identical on the axis a name-reading predicate would consult …
    expect(minted.positions).toEqual(genuine.positions);
    // … and opposite on the axis that actually decides.
    expect([await postureOf(minted), await postureOf(genuine)]).toEqual(['MEMBER', 'PLATFORM_ADMIN']);
  });

  it('org_owner / org_admin better-auth role positions no longer confer TENANT_ADMIN (ADR-0095 D3)', async () => {
    // The role is a provisioning source, not posture evidence. Absent the
    // organization_admin CAPABILITY these resolve to MEMBER, as enforcement does.
    expect(await postureOf({ userId: 'a1', tenantId: 'org1', positions: ['org_admin', 'everyone'], permissions: [] })).toBe('MEMBER');
    expect(await postureOf({ userId: 'a1', tenantId: 'org1', positions: ['org_owner', 'everyone'], permissions: [] })).toBe('MEMBER');
  });

  it('the organization_admin capability grant yields TENANT_ADMIN', async () => {
    expect(await postureOf({ userId: 'a1', tenantId: 'org1', positions: ['everyone'], permissions: ['organization_admin'] })).toBe('TENANT_ADMIN');
  });

  it('guest / anonymous → EXTERNAL floor wins even over an attached posture', async () => {
    expect(await postureOf({ userId: 'a1', principalKind: 'guest', positions: [], permissions: [], posture: 'PLATFORM_ADMIN' })).toBe('EXTERNAL');
    expect(await postureOf({ userId: null, positions: [], permissions: [] })).toBe('EXTERNAL');
  });
});

// ─── buildContextForUser (#6352) ────────────────────────────────────────────
//
// `buildContextForUser` no longer aggregates anything. It calls
// `@objectstack/core`'s `resolveUserAuthzGrants` — the SAME function every
// inbound request resolves through — and adds only presentation: the ADR-0091
// expired / delegated row annotations, and `hasPlatformAdminGrant` read back off
// the resolver's own posture verdict.
//
// ⚠ The fixtures below use a `where`-HONOURING fake, and that is load-bearing,
// not tidiness. The deleted mirror filtered rows in memory, so it produced the
// right answer even against a fake that ignored `where` and returned every row
// for a table. The resolver delegates filtering to the engine, exactly as the
// real ObjectQL engine does, so a fake that ignores `where` now reports grants
// nobody holds — a fixture defect the old shape was blind to.

type Rows = Record<string, any[]>;

/** Minimal `where`-honouring ObjectQL stand-in: scalar equality and `$in`. */
function makeGrantQl(tables: Rows) {
  return bindCatalogFromTables({
    async find(object: string, opts: any) {
      const where = opts?.where ?? {};
      // [ADR-0131 D3] The resolver AND the explainer's "deactivated"
      // annotation read deactivation from the activation ledger: a fixture's
      // `active: false` rows reach both as the ledger rows the upgrade ceremony
      // converts them to, unless the fixture states its ledger itself.
      const stored = object === 'sys_metadata_activation' && !tables[object] ? ledgerFromTables(tables) : tables[object];
      return (stored ?? []).filter((row) =>
        Object.entries(where).every(([key, cond]) => { if (key.startsWith('$')) throw new Error(`fake driver: unsupported operator ${key}`); 
          const cell = row[key];
          // `null` matches a null-valued AND a key-absent cell — the memory
          // driver's reading, and what an organization-less row looks like here.
          if (cond === null) return cell === null || cell === undefined;
          if (cond && typeof cond === 'object' && '$in' in (cond as any)) {
            return ((cond as any).$in as unknown[]).includes(cell);
          }
          return cell === cond;
        }),
      );
    },
  }, tables);
}

const NOW = Date.parse('2026-07-10T12:00:00Z');

describe('buildContextForUser', () => {
  // A grant applies only in its own organization (an organization-less row
  // applies nowhere), so the fixtures below own their grant rows by ORG and
  // explain the user IN it, unless a case says otherwise.
  const ORG = 'org1';
  const ql = makeGrantQl({
    sys_user_position: [{ user_id: 'u2', organization_id: ORG, position: 'hr_specialist' }],
    sys_user_permission_set: [{ user_id: 'u2', organization_id: ORG, permission_set_id: 'ps1', permission_set: 'payroll_reader' }],
    sys_permission_set: [{ id: 'ps1', name: 'payroll_reader' }],
  });

  it('derives hasPlatformAdminGrant from the DEFAULT ORGANIZATION\'s admin_full_access user grant (matches resolveAuthzContext)', async () => {
    const qlAnchored = makeGrantQl({
      sys_organization: [{ id: 'org_default', slug: 'default' }],
      sys_user_permission_set: [{ user_id: 'u2', permission_set_id: 'psAdmin', permission_set: 'admin_full_access', organization_id: 'org_default' }],
      sys_permission_set: [{ id: 'psAdmin', name: 'admin_full_access' }],
    });
    // Explained with NO active organization: the anchoring grant applies
    // whatever the tenant, because platform standing is the deployment's.
    const ctx = await buildContextForUser(qlAnchored, 'u2');
    expect(ctx.hasPlatformAdminGrant).toBe(true);
    expect(ctx.permissions).toContain('admin_full_access');
    // The resolver PROJECTS the built-in position from the same grant (ADR-0068
    // D2) and resolves the rung once — both now reach the panel unchanged.
    expect(ctx.positions).toContain('platform_admin');
    expect(ctx.posture).toBe('PLATFORM_ADMIN');
  });

  it('an organization-LESS admin_full_access user grant anchors nothing and confers nothing, in no organization or in one', async () => {
    const qlOrphan = makeGrantQl({
      sys_organization: [{ id: 'org_default', slug: 'default' }],
      // organization_id absent → the row belongs to no organization
      sys_user_permission_set: [{ user_id: 'u2', permission_set_id: 'psAdmin', permission_set: 'admin_full_access' }],
      sys_permission_set: [{ id: 'psAdmin', name: 'admin_full_access' }],
    });
    for (const tenantId of [undefined, 'org_default']) {
      const ctx = await buildContextForUser(qlOrphan, 'u2', NOW, tenantId);
      expect(ctx.hasPlatformAdminGrant, String(tenantId)).toBe(false);
      expect(ctx.permissions, String(tenantId)).not.toContain('admin_full_access');
      expect(ctx.positions, String(tenantId)).not.toContain('platform_admin');
      expect(ctx.posture, String(tenantId)).toBe('MEMBER');
    }
  });

  it('[#11974 / #11663 L4, P8] CONFIG-derived standing reaches the panel: a declared+verified admin with ZERO grant rows explains as PLATFORM_ADMIN', async () => {
    // Under walled postures the bootstrap mints no grant row any more, so this
    // is the ONLY shape a fresh walled deployment's administrator has. Explain
    // must agree with enforcement about it — and does so structurally, because
    // `buildContextForUser` delegates to the resolver whose §6b-config branch
    // is the one derivation site (pinned in core's
    // `resolve-authz-context.platform-admin-config.test.ts`). This pin holds
    // the panel side of that agreement.
    const prev = process.env.OS_PLATFORM_OWNER_EMAIL;
    process.env.OS_PLATFORM_OWNER_EMAIL = 'operator@corp.example';
    resetPlatformAdminEmailMemo();
    try {
      const qlConfig = makeGrantQl({
        // No sys_user_permission_set rows at all — the row anchor is absent.
        sys_user: [{ id: 'u9', email: 'operator@corp.example', email_verified: true }],
      });
      const ctx = await buildContextForUser(qlConfig, 'u9');
      expect(ctx.hasPlatformAdminGrant).toBe(true);
      expect(ctx.posture).toBe('PLATFORM_ADMIN');
      expect(ctx.permissions).toContain('admin_full_access');
      expect(ctx.positions).toContain('platform_admin');
    } finally {
      if (prev === undefined) delete process.env.OS_PLATFORM_OWNER_EMAIL;
      else process.env.OS_PLATFORM_OWNER_EMAIL = prev;
      resetPlatformAdminEmailMemo();
    }
  });

  it('a SCOPED (org-specific) admin_full_access user grant does NOT set hasPlatformAdminGrant', async () => {
    const qlScoped = makeGrantQl({
      sys_user_permission_set: [{ user_id: 'u2', permission_set_id: 'psAdmin', permission_set: 'admin_full_access', organization_id: 'org1' }],
      sys_permission_set: [{ id: 'psAdmin', name: 'admin_full_access' }],
    });
    // [#20515] Explained IN org1: a grant scoped to an organization applies
    // only while that organization is the one resolved in, so the set has to
    // resolve before "it resolves, and still confers no platform standing" is
    // a statement about anything.
    const ctx = await buildContextForUser(qlScoped, 'u2', NOW, 'org1');
    expect(ctx.hasPlatformAdminGrant).toBe(false);
    // The name is still resolved into permissions (it grants object CRUD), but it
    // no longer confers platform_admin posture — the drift this closes.
    expect(ctx.permissions).toContain('admin_full_access');
    expect(ctx.positions).not.toContain('platform_admin');
    expect(ctx.posture).toBe('MEMBER');
  });

  it('reconstructs positions + direct grants + the everyone anchor', async () => {
    const ctx = await buildContextForUser(ql, 'u2', NOW, ORG);
    expect(ctx).toEqual({
      userId: 'u2',
      positions: ['hr_specialist', 'everyone'],
      permissions: ['payroll_reader'],
      // [#25799] The resolver's channel split: `payroll_reader` is u2's own grant row.
      directPermissions: ['payroll_reader'],
      // [#6352] The resolver's full envelope now reaches the panel. These four
      // were MISSING from the hand-written mirror, which is why an explanation
      // could disagree with enforcement — see the parity suite below.
      systemPermissions: [],
      org_user_ids: ['u2'],
      posture: 'MEMBER',
      // [ADR-0105 D2] The DELEGATOR's own org access set, resolved here rather
      // than inherited — a delegated read is bounded by the delegator's own
      // memberships. This fixture serves no `sys_member` rows, so it is empty,
      // which fails the `group` wall closed.
      accessible_org_ids: [],
      droppedGrants: [],
      delegatedPositions: [],
      hasPlatformAdminGrant: false,
    });
  });

  it('surfaces delegation provenance for a position held via a delegated_from row (ADR-0091 D3)', async () => {
    const qlDelegated = makeGrantQl({
      sys_user_position: [
        { user_id: 'u2', organization_id: ORG, position: 'hr_specialist' },
        { user_id: 'u2', organization_id: ORG, position: 'approver', delegated_from: 'u_boss', valid_until: '2026-07-20T00:00:00Z' },
      ],
    });
    const ctx = await buildContextForUser(qlDelegated, 'u2', NOW, ORG);
    expect(ctx.positions).toEqual(['hr_specialist', 'approver', 'everyone']);
    expect(ctx.delegatedPositions).toEqual([
      { name: 'approver', from: 'u_boss', until: '2026-07-20T00:00:00Z' },
    ]);
  });

  it('filters grants outside their validity window and reports them as expired (ADR-0091 D2)', async () => {
    const qlWindowed = makeGrantQl({
      sys_user_position: [
        { user_id: 'u2', organization_id: ORG, position: 'hr_specialist' },
        { user_id: 'u2', organization_id: ORG, position: 'payroll_approver', valid_until: '2026-07-01T00:00:00Z' },
        // Pending (future valid_from) is filtered but NOT reported as expired.
        { user_id: 'u2', organization_id: ORG, position: 'auditor', valid_from: '2026-08-01T00:00:00Z' },
      ],
      sys_user_permission_set: [
        { user_id: 'u2', organization_id: ORG, permission_set_id: 'ps1', permission_set: 'payroll_reader' },
        {
          user_id: 'u2', organization_id: ORG, permission_set_id: 'ps2', permission_set: 'quarter_close_admin',
          valid_until: '2026-06-01T00:00:00Z',
        },
      ],
      sys_permission_set: [
        { id: 'ps1', name: 'payroll_reader' },
        { id: 'ps2', name: 'quarter_close_admin' },
      ],
    });
    const ctx = await buildContextForUser(qlWindowed, 'u2', NOW, ORG);
    expect(ctx.positions).toEqual(['hr_specialist', 'everyone']);
    expect(ctx.permissions).toEqual(['payroll_reader']);
    expect(ctx.droppedGrants).toEqual([
      { kind: 'position', name: 'payroll_approver', state: 'expired', until: '2026-07-01T00:00:00Z' },
      { kind: 'permission_set', name: 'quarter_close_admin', state: 'expired', until: '2026-06-01T00:00:00Z' },
    ]);
  });

  // [commit 42b05af89 / ADR-0049] The second reason of the shared held-state vocabulary:
  // the catalogue row's `active` switch. The resolver drops these rows
  // fail-closed (#8613); the provenance pass re-reads them so the panel can say
  // "held — deactivated" instead of answering like the grant never existed.
  it('reports a directly-granted permission set whose catalogue row is deactivated (ADR-0049 / #8714)', async () => {
    const qlDeactivated = makeGrantQl({
      sys_user_permission_set: [
        { user_id: 'u2', organization_id: ORG, permission_set_id: 'ps1', permission_set: 'payroll_reader' },
        { user_id: 'u2', organization_id: ORG, permission_set_id: 'psOff', permission_set: 'crm_full' },
      ],
      sys_permission_set: [
        { id: 'ps1', name: 'payroll_reader' },
        { id: 'psOff', name: 'crm_full', active: false },
      ],
    });
    const ctx = await buildContextForUser(qlDeactivated, 'u2', NOW, ORG);
    // The resolver's fail-closed dropping is untouched…
    expect(ctx.permissions).toEqual(['payroll_reader']);
    // …and the dropped row is REPORTED, with the deactivated reason.
    expect(ctx.droppedGrants).toEqual([
      { kind: 'permission_set', name: 'crm_full', state: 'deactivated' },
    ]);
  });

  it('reports a held position whose sys_position row is deactivated — including the 0/1 storage shape (ADR-0049 / #8714)', async () => {
    const qlDeactivated = makeGrantQl({
      sys_user_position: [
        { user_id: 'u2', organization_id: ORG, position: 'hr_specialist' },
        { user_id: 'u2', organization_id: ORG, position: 'field_auditor' },
      ],
      // 0 is what the primary driver hands back for a stored false — the
      // shared isRowActive predicate reads it as deactivated (#8613).
      sys_position: [
        { id: 'pos_hr', name: 'hr_specialist' },
        { id: 'pos_fa', name: 'field_auditor', active: 0 },
      ],
    });
    const ctx = await buildContextForUser(qlDeactivated, 'u2', NOW, ORG);
    expect(ctx.positions).toEqual(['hr_specialist', 'everyone']);
    expect(ctx.droppedGrants).toEqual([
      { kind: 'position', name: 'field_auditor', state: 'deactivated' },
    ]);
  });

  it('a row both expired AND deactivated reports expired — one reason per row, resolver drop order (#8714)', async () => {
    const qlBoth = makeGrantQl({
      sys_user_permission_set: [
        { user_id: 'u2', organization_id: ORG, permission_set_id: 'psOff', permission_set: 'crm_full', valid_until: '2026-06-01T00:00:00Z' },
      ],
      sys_permission_set: [{ id: 'psOff', name: 'crm_full', active: false }],
    });
    const ctx = await buildContextForUser(qlBoth, 'u2', NOW, ORG);
    expect(ctx.droppedGrants).toEqual([
      { kind: 'permission_set', name: 'crm_full', state: 'expired', until: '2026-06-01T00:00:00Z' },
    ]);
  });

  // [ADR-0131 D3, ADR-0126 §4] Explain and enforce read ONE switch: the
  // activation ledger, through the resolver's own `readDisabledCatalogNames`.
  // Each case below states the ledger and the rows apart, so the two disagree,
  // and the explainer must side with what the resolver enforces.
  it('a set and a position the LEDGER switched off are reported deactivated, whatever their rows say', async () => {
    const ql = makeGrantQl({
      sys_user_position: [{ user_id: 'u2', organization_id: ORG, position: 'field_auditor' }],
      sys_position: [{ id: 'pos_fa', name: 'field_auditor', active: true }],
      sys_user_permission_set: [{ user_id: 'u2', organization_id: ORG, permission_set_id: 'psOff', permission_set: 'crm_full' }],
      sys_permission_set: [{ id: 'psOff', name: 'crm_full', active: true }],
      sys_metadata_activation: [
        { metadata_type: 'position', name: 'field_auditor', active: false },
        { metadata_type: 'permission', name: 'crm_full', active: 0 },
      ],
    });
    const ctx = await buildContextForUser(ql, 'u2', NOW, ORG);
    // Enforcement dropped both…
    expect(ctx.positions).toEqual(['everyone']);
    expect(ctx.permissions).toEqual([]);
    // …and explain says why, from the same ledger.
    expect(ctx.droppedGrants).toEqual([
      { kind: 'position', name: 'field_auditor', state: 'deactivated' },
      { kind: 'permission_set', name: 'crm_full', state: 'deactivated' },
    ]);
  });

  it("a catalog ROW's `active: false` with no ledger row is in effect, and explain reports nothing dropped", async () => {
    const ql = makeGrantQl({
      sys_user_position: [{ user_id: 'u2', organization_id: ORG, position: 'field_auditor' }],
      sys_position: [{ id: 'pos_fa', name: 'field_auditor', active: false }],
      sys_user_permission_set: [{ user_id: 'u2', organization_id: ORG, permission_set_id: 'psOff', permission_set: 'crm_full' }],
      sys_permission_set: [{ id: 'psOff', name: 'crm_full', active: false }],
      sys_metadata_activation: [],
    });
    const ctx = await buildContextForUser(ql, 'u2', NOW, ORG);
    expect(ctx.positions).toEqual(['field_auditor', 'everyone']);
    expect(ctx.permissions).toEqual(['crm_full']);
    expect(ctx.droppedGrants).toEqual([]);
  });

  it('a grant naming a set the catalog does not hold is reported neither expired nor deactivated — there is no set to lose', async () => {
    // No `sys_permission_set` row, so the catalog these tables convert to holds
    // neither name; the ledger switches one of them off all the same.
    const ql = makeGrantQl({
      sys_user_permission_set: [
        { user_id: 'u2', organization_id: ORG, permission_set_id: 'ps_gone', permission_set: 'gone_set', valid_until: '2026-06-01T00:00:00Z' },
        { user_id: 'u2', organization_id: ORG, permission_set_id: 'ps_gone2', permission_set: 'gone_off' },
      ],
      sys_metadata_activation: [{ metadata_type: 'permission', name: 'gone_off', active: false }],
    });
    const ctx = await buildContextForUser(ql, 'u2', NOW, ORG);
    expect(ctx.droppedGrants).toEqual([]);
  });

  it('an absent `active` column keeps granting and is NOT reported — absent is ACTIVE (ADR-0049)', async () => {
    const qlAbsent = makeGrantQl({
      sys_user_position: [{ user_id: 'u2', organization_id: ORG, position: 'hr_specialist' }],
      sys_position: [{ id: 'pos_hr', name: 'hr_specialist' }],
      sys_user_permission_set: [{ user_id: 'u2', organization_id: ORG, permission_set_id: 'ps1', permission_set: 'payroll_reader' }],
      sys_permission_set: [{ id: 'ps1', name: 'payroll_reader' }],
    });
    const ctx = await buildContextForUser(qlAbsent, 'u2', NOW, ORG);
    expect(ctx.positions).toEqual(['hr_specialist', 'everyone']);
    expect(ctx.permissions).toEqual(['payroll_reader']);
    expect(ctx.droppedGrants).toEqual([]);
  });
});

// ─── [#6352] The explain panel and enforcement resolve ONE aggregation ───────
//
// Every case below runs `buildContextForUser` and `resolveUserAuthzGrants` over
// the SAME rows and asserts they agree — the assertion nothing in the repo made
// while the mirror existed. Convergence makes agreement structural rather than
// coincidental, so the suite's real job is the second half of each case: the
// `expected` block pins what the shared aggregation must actually PRODUCE, so
// the pin can never pass by both sides resolving to nothing.
//
// Each `expected` block was RED before convergence. Measured against the mirror
// on the first fixture's rows: it returned positions `['hr_specialist',
// 'everyone']` (no `sys_member` role projection) and permissions
// `['payroll_reader']` (no position-bound set, no `ai_seat`), against the
// resolver's `['org_admin', 'hr_specialist', 'everyone']` and
// `['payroll_reader', 'hr_tools', 'ai_seat']`. A user whose grants arrive
// through a POSITION was explained as holding none of them — the panel denying
// what enforcement allows, which is the exact failure an explain panel exists
// to prevent.
describe('buildContextForUser ↔ resolveUserAuthzGrants parity (#6352)', () => {
  const PARITY_CASES: Array<{
    name: string;
    tables: Rows;
    /** [#20515] The organization BOTH sides resolve in; omitted = no active organization. */
    tenantId?: string;
    expected: {
      positions: string[];
      permissions: string[];
      systemPermissions: string[];
      accessible_org_ids: string[];
      posture: string;
      hasPlatformAdminGrant: boolean;
    };
  }> = [
    {
      // The measured pre-change divergence, in one fixture: an org role
      // (ADR-0095 D3 `sys_member` projection), a platform-RBAC position
      // (ADR-0057 D4), a permission set the POSITION carries
      // (`sys_position_permission_set`), and the cloud ADR-0024 `ai_seat` synthesis.
      name: 'org role + position-bound permission set + ai_seat',
      // A grant applies only in its own organization, so the grant rows are
      // org1's and both sides resolve in org1.
      tenantId: 'org1',
      tables: {
        sys_user: [{ id: 'u2', email: 'u2@example.com', ai_access: true }],
        sys_member: [{ user_id: 'u2', organization_id: 'org1', role: 'admin' }],
        sys_user_position: [{ user_id: 'u2', organization_id: 'org1', position: 'hr_specialist' }],
        sys_position: [{ id: 'pos_hr', name: 'hr_specialist' }],
        sys_position_permission_set: [{ position_id: 'pos_hr', permission_set_id: 'ps_hr_tools' }],
        sys_user_permission_set: [{ user_id: 'u2', organization_id: 'org1', permission_set_id: 'ps1', permission_set: 'payroll_reader' }],
        sys_permission_set: [
          { id: 'ps1', name: 'payroll_reader' },
          { id: 'ps_hr_tools', name: 'hr_tools', system_permissions: ['manage_users'] },
        ],
      },
      expected: {
        positions: ['org_admin', 'hr_specialist', 'everyone'],
        permissions: ['payroll_reader', 'hr_tools', 'ai_seat'],
        systemPermissions: ['manage_users'],
        accessible_org_ids: ['org1'],
        posture: 'MEMBER',
        hasPlatformAdminGrant: false,
      },
    },
    {
      // [ADR-0090 D5] The audience anchor is not decoration: a set bound to the
      // implicit `everyone` position must RESOLVE. The mirror pushed `everyone`
      // onto the list and then read no position-bound sets at all, so anything
      // granted this way was invisible to the panel.
      name: 'everyone-anchor-bound permission set resolves',
      tables: {
        sys_position: [{ id: 'pos_everyone', name: 'everyone' }],
        sys_position_permission_set: [{ position_id: 'pos_everyone', permission_set_id: 'ps_base' }],
        sys_permission_set: [{ id: 'ps_base', name: 'company_directory' }],
      },
      expected: {
        positions: ['everyone'],
        permissions: ['company_directory'],
        systemPermissions: [],
        accessible_org_ids: [],
        posture: 'MEMBER',
        hasPlatformAdminGrant: false,
      },
    },
    {
      // [ADR-0068 D2] The platform_admin derivation, both polarities. The
      // anchor is the Default Organization's grant, and it applies with no
      // active organization.
      name: 'the Default Organization\'s admin_full_access derives platform_admin',
      tables: {
        sys_organization: [{ id: 'org_default', slug: 'default' }],
        sys_user_permission_set: [{ user_id: 'u2', permission_set_id: 'psAdmin', permission_set: 'admin_full_access', organization_id: 'org_default' }],
        sys_permission_set: [{ id: 'psAdmin', name: 'admin_full_access' }],
      },
      expected: {
        positions: ['platform_admin', 'everyone'],
        permissions: ['admin_full_access'],
        systemPermissions: [],
        accessible_org_ids: [],
        posture: 'PLATFORM_ADMIN',
        hasPlatformAdminGrant: true,
      },
    },
    {
      // ...and an organization-less grant of the same set anchors nothing and
      // applies nowhere: it confers neither the rung nor the set.
      name: 'organization-less admin_full_access derives nothing',
      tables: {
        sys_organization: [{ id: 'org_default', slug: 'default' }],
        sys_user_permission_set: [{ user_id: 'u2', permission_set_id: 'psAdmin', permission_set: 'admin_full_access' }],
        sys_permission_set: [{ id: 'psAdmin', name: 'admin_full_access' }],
      },
      expected: {
        positions: ['everyone'],
        permissions: [],
        systemPermissions: [],
        accessible_org_ids: [],
        posture: 'MEMBER',
        hasPlatformAdminGrant: false,
      },
    },
    {
      name: 'org-scoped admin_full_access does NOT derive platform_admin',
      // [#20515] Resolved IN org1, where the scoped set applies — with no active
      // organization it would not resolve at all, and the case would pin nothing.
      tenantId: 'org1',
      tables: {
        sys_user_permission_set: [{ user_id: 'u2', permission_set_id: 'psAdmin', permission_set: 'admin_full_access', organization_id: 'org1' }],
        sys_permission_set: [{ id: 'psAdmin', name: 'admin_full_access' }],
      },
      expected: {
        positions: ['everyone'],
        permissions: ['admin_full_access'],
        systemPermissions: [],
        accessible_org_ids: [],
        posture: 'MEMBER',
        hasPlatformAdminGrant: false,
      },
    },
    {
      // [ADR-0095 D3] The org-admin rung comes from the CAPABILITY grant
      // `auto-org-admin-grant` writes, never from the better-auth role.
      name: 'organization_admin capability grant derives TENANT_ADMIN',
      // [#20515] The auto-grant is scoped to its organization, so it confers the
      // rung while that organization is the one resolved in.
      tenantId: 'org1',
      tables: {
        sys_member: [{ user_id: 'u2', organization_id: 'org1', role: 'admin' }],
        sys_user_permission_set: [{ user_id: 'u2', permission_set_id: 'psOrg', permission_set: 'organization_admin', organization_id: 'org1' }],
        sys_permission_set: [{ id: 'psOrg', name: 'organization_admin' }],
      },
      expected: {
        positions: ['org_admin', 'everyone'],
        permissions: ['organization_admin'],
        systemPermissions: [],
        accessible_org_ids: ['org1'],
        posture: 'TENANT_ADMIN',
        hasPlatformAdminGrant: false,
      },
    },
    {
      // [ADR-0091 D2] Validity windows drop rows on BOTH sides, including the
      // platform_admin derivation: an EXPIRED admin_full_access grant of the
      // Default Organization (org1 here) must not confer the rung. Only the
      // explain-side annotation survives.
      name: 'ADR-0091 windows: expired admin grant confers nothing',
      tenantId: 'org1',
      tables: {
        sys_organization: [{ id: 'org1', slug: 'default' }],
        sys_user_position: [
          { user_id: 'u2', organization_id: 'org1', position: 'hr_specialist' },
          { user_id: 'u2', organization_id: 'org1', position: 'payroll_approver', valid_until: '2026-07-01T00:00:00Z' },
          { user_id: 'u2', organization_id: 'org1', position: 'auditor', valid_from: '2026-08-01T00:00:00Z' },
        ],
        sys_user_permission_set: [
          { user_id: 'u2', organization_id: 'org1', permission_set_id: 'ps1', permission_set: 'payroll_reader' },
          { user_id: 'u2', organization_id: 'org1', permission_set_id: 'psAdmin', permission_set: 'admin_full_access', valid_until: '2026-06-01T00:00:00Z' },
        ],
        sys_permission_set: [
          { id: 'ps1', name: 'payroll_reader' },
          { id: 'psAdmin', name: 'admin_full_access' },
        ],
      },
      expected: {
        positions: ['hr_specialist', 'everyone'],
        permissions: ['payroll_reader'],
        systemPermissions: [],
        accessible_org_ids: [],
        posture: 'MEMBER',
        hasPlatformAdminGrant: false,
      },
    },
  ];

  for (const { name, tables, tenantId, expected } of PARITY_CASES) {
    it(`agrees with the enforcement resolver — ${name}`, async () => {
      const grants = await resolveUserAuthzGrants(makeGrantQl(tables), 'u2', { nowMs: NOW, tenantId });
      const ctx = await buildContextForUser(makeGrantQl(tables), 'u2', NOW, tenantId);

      // (a) The two agree, field for field, on the whole aggregation surface.
      expect(ctx.positions).toEqual(grants.positions);
      expect(ctx.permissions).toEqual(grants.permissions);
      expect(ctx.systemPermissions).toEqual(grants.systemPermissions);
      expect(ctx.accessible_org_ids).toEqual(grants.accessible_org_ids);
      expect(ctx.org_user_ids).toEqual(grants.org_user_ids);
      expect(ctx.posture).toEqual(grants.posture);
      expect(ctx.hasPlatformAdminGrant).toBe(grants.posture === 'PLATFORM_ADMIN');

      // (b) Non-vacuity: agreeing on nothing is not agreement. Pin what the one
      // aggregation must actually produce for these rows.
      expect(ctx.positions).toEqual(expected.positions);
      expect(ctx.permissions).toEqual(expected.permissions);
      expect(ctx.systemPermissions).toEqual(expected.systemPermissions);
      expect(ctx.accessible_org_ids).toEqual(expected.accessible_org_ids);
      expect(ctx.posture).toBe(expected.posture);
      expect(ctx.hasPlatformAdminGrant).toBe(expected.hasPlatformAdminGrant);
    });
  }

  it('the explain-only surface is ADDITIVE — it annotates rows, it never changes the verdict', async () => {
    const tables: Rows = {
      sys_user_position: [
        { user_id: 'u2', organization_id: 'org1', position: 'hr_specialist' },
        { user_id: 'u2', organization_id: 'org1', position: 'approver', delegated_from: 'u_boss', valid_until: '2026-07-20T00:00:00Z' },
        { user_id: 'u2', organization_id: 'org1', position: 'payroll_approver', valid_until: '2026-07-01T00:00:00Z' },
        // [commit 42b05af89] a held position whose catalogue row is switched off
        { user_id: 'u2', organization_id: 'org1', position: 'field_auditor' },
      ],
      sys_position: [{ id: 'pos_fa', name: 'field_auditor', active: false }],
      sys_user_permission_set: [
        {
          user_id: 'u2', organization_id: 'org1', permission_set_id: 'ps2', permission_set: 'quarter_close_admin',
          valid_until: '2026-06-01T00:00:00Z',
        },
        // [commit 42b05af89] a held direct grant whose SET's catalogue row is switched off
        { user_id: 'u2', organization_id: 'org1', permission_set_id: 'psOff', permission_set: 'crm_full' },
      ],
      sys_permission_set: [
        { id: 'ps2', name: 'quarter_close_admin' },
        { id: 'psOff', name: 'crm_full', active: false },
      ],
    };
    // Both sides resolve in org1, the organization the grant rows are owned by.
    const grants = await resolveUserAuthzGrants(makeGrantQl(tables), 'u2', { nowMs: NOW, tenantId: 'org1' });
    const ctx = await buildContextForUser(makeGrantQl(tables), 'u2', NOW, 'org1');
    // Non-vacuity: the live grant the comparison below is about does resolve.
    expect(ctx.positions).toContain('hr_specialist');

    // The annotations are non-empty…
    expect(ctx.delegatedPositions).toEqual([
      { name: 'approver', from: 'u_boss', until: '2026-07-20T00:00:00Z' },
    ]);
    expect(ctx.droppedGrants).toEqual([
      { kind: 'position', name: 'payroll_approver', state: 'expired', until: '2026-07-01T00:00:00Z' },
      { kind: 'position', name: 'field_auditor', state: 'deactivated' },
      { kind: 'permission_set', name: 'quarter_close_admin', state: 'expired', until: '2026-06-01T00:00:00Z' },
      { kind: 'permission_set', name: 'crm_full', state: 'deactivated' },
    ]);
    // …and the aggregation is still byte-identical to enforcement's. A dropped
    // grant (expired OR deactivated) is REPORTED, never RESOLVED.
    expect(ctx.positions).toEqual(grants.positions);
    expect(ctx.permissions).toEqual(grants.permissions);
    expect(ctx.positions).not.toContain('payroll_approver');
    expect(ctx.positions).not.toContain('field_auditor');
    expect(ctx.permissions).not.toContain('quarter_close_admin');
    expect(ctx.permissions).not.toContain('crm_full');
  });
});

// ─── [#3544] the export axis is explainable ────────────────────────────────
//
// Without this the axis is undiagnosable: a caller hits 403
// EXPORT_NOT_PERMITTED, an admin runs explain(read), gets `allowed: true`, and
// has nowhere left to look. The answer must be a first-class operation.
describe('explainAccess — export axis (#3544)', () => {
  const READER = PermissionSetSchema.parse({
    name: 'reader',
    objects: { leave_request: { allowRead: true } },
  });
  const EXPORTER = PermissionSetSchema.parse({
    name: 'exporter',
    objects: { leave_request: { allowRead: true, allowExport: true } },
  });

  it('denies export for a reader without the grant, while read is allowed', async () => {
    const readDecision = await explainAccess(makeDeps({ sets: [READER] }), {
      object: 'leave_request', operation: 'read', context: CTX,
    });
    expect(readDecision.allowed).toBe(true);

    const exportDecision = await explainAccess(makeDeps({ sets: [READER] }), {
      object: 'leave_request', operation: 'export', context: CTX,
    });
    expect(exportDecision.allowed).toBe(false);
    const crud = exportDecision.layers.find((l) => l.layer === 'object_crud');
    expect(crud?.verdict).toBe('denies');
    expect(crud?.detail).toMatch(/export/);
  });

  it('allows export when a set carries the grant, and attributes WHICH set', async () => {
    const d = await explainAccess(makeDeps({ sets: [READER, EXPORTER] }), {
      object: 'leave_request', operation: 'export', context: CTX,
    });
    expect(d.allowed).toBe(true);
    const crud = d.layers.find((l) => l.layer === 'object_crud');
    // The attribution is the point: it names the granting set, so an admin can
    // see which grant to remove (or which one is missing).
    expect(crud?.contributors?.map((c) => c.name)).toContain('exporter');
    expect(crud?.contributors?.map((c) => c.name)).not.toContain('reader');
  });

  it('surfaces the readFilter — an export streams the same filtered rows a read does', async () => {
    const d = await explainAccess(makeDeps({ sets: [EXPORTER], rls: { owner_id: 'u1' } }), {
      object: 'leave_request', operation: 'export', context: CTX,
    });
    expect(d.readFilter).toEqual({ owner_id: 'u1' });
  });

  it('computes RLS as a find, not as an "export" the compiler has no policy for', async () => {
    // The bug this pins: asking the RLS compiler about an `export` operation
    // matches no select policy, so the report would claim "No RLS policy
    // applies" for a principal whose rows ARE filtered.
    const seen: string[] = [];
    const d = await explainAccess(
      makeDeps({
        sets: [EXPORTER],
        computeRlsFilter: async (_s: any, _o: string, op: string) => { seen.push(op); return { owner_id: 'u1' }; },
      }),
      { object: 'leave_request', operation: 'export', context: CTX },
    );
    expect(seen).toContain('find');
    expect(seen).not.toContain('export');
    expect(d.layers.find((l) => l.layer === 'rls')?.verdict).toBe('narrows');
  });

  it('resolves requiredPermissions against the READ bucket', async () => {
    const seen: string[] = [];
    await explainAccess(
      makeDeps({
        sets: [EXPORTER],
        requiredCaps: (_m: any, op: string) => { seen.push(op); return []; },
      }),
      { object: 'leave_request', operation: 'export', context: CTX },
    );
    expect(seen).toEqual(['find']);
  });

  it('a super-user wildcard does not confer export', async () => {
    const d = await explainAccess(makeDeps({ sets: [ADMIN] }), {
      object: 'leave_request', operation: 'export', context: CTX,
    });
    expect(d.allowed).toBe(false);
  });
});

// ─── #11971 — pin 6: the explainer bypasses the leg-B grants cache ──────────
//
// The ruled bypass list of #11633 (maintainer acceptance 2026-08-25): the
// explainer is the tool an administrator uses to VERIFY that a revocation took
// effect, so an explainer answering from cache would explain a state that no
// longer exists at exactly the moment someone is checking. This pin makes the
// cache demonstrably STALE first (the control), then asserts the explainer
// does not repeat it — the end of the chain, not "the flag was passed".

describe('buildContextForUser bypasses the #11971 grants cache (ruled bypass list)', () => {
  const TTL_ENV = 'OS_AUTHZ_GRANTS_CACHE_TTL_MS';

  /**
   * `makeGrantQl` plus the #11968 seams (write epoch + `registerMiddleware`),
   * so the grants cache WOULD engage for this ql if the explainer let it —
   * a seamless double would make this pin pass vacuously (the cache declines
   * to cache against a ql whose writes it cannot see).
   */
  function makeSeamGrantQl(tables: Rows) {
    type Listener = (epoch: number, reason: string) => void;
    type Middleware = (
      ctx: { object: string; operation: string },
      next: () => Promise<void>,
    ) => Promise<void>;
    const middlewares: Middleware[] = [];
    const listeners = new Set<Listener>();
    const epoch = {
      current: 0,
      bump(reason: string): number {
        epoch.current += 1;
        for (const l of [...listeners]) l(epoch.current, reason);
        return epoch.current;
      },
      subscribe(l: Listener): () => void {
        listeners.add(l);
        return () => { listeners.delete(l); };
      },
    };
    return bindCatalogFromTables({
      ...makeGrantQl(tables),
      writeEpoch: epoch,
      registerMiddleware(fn: Middleware): void { middlewares.push(fn); },
    }, tables);
  }

  it('with the cache ON and provably stale, the explainer still observes the revocation immediately', async () => {
    const saved = process.env[TTL_ENV];
    process.env[TTL_ENV] = '3600000'; // one hour — nothing here may pass by expiry
    try {
      // The Default Organization's grant: it anchors platform standing and
      // applies with no active organization, so the cached answer is the rung.
      const tables: Rows = {
        sys_organization: [{ id: 'org_default', slug: 'default' }],
        sys_user_permission_set: [{ user_id: 'u2', permission_set_id: 'psAdmin', permission_set: 'admin_full_access', organization_id: 'org_default' }],
        sys_permission_set: [{ id: 'psAdmin', name: 'admin_full_access' }],
      };
      const ql = makeSeamGrantQl(tables);

      // Populate the cache through the SAME resolver every request uses.
      const cached = await resolveUserAuthzGrants(ql, 'u2', { nowMs: NOW });
      expect(cached.permissions).toContain('admin_full_access');
      expect(cached.posture).toBe('PLATFORM_ADMIN');

      // Revoke WITHOUT an engine write: no seam reports it, so nothing
      // retires the entry and the cached path keeps the old answer…
      tables.sys_user_permission_set = [];
      const stale = await resolveUserAuthzGrants(ql, 'u2', { nowMs: NOW });
      expect(stale.permissions).toContain('admin_full_access'); // control: cache IS stale

      // …and the explainer must not repeat it: force-fresh, whatever the TTL.
      const ctx = await buildContextForUser(ql, 'u2', NOW);
      expect(ctx.permissions).not.toContain('admin_full_access');
      expect(ctx.hasPlatformAdminGrant).toBe(false);
      expect(ctx.posture).not.toBe('PLATFORM_ADMIN');
    } finally {
      if (saved === undefined) delete process.env[TTL_ENV];
      else process.env[TTL_ENV] = saved;
    }
  });
});


// ═══════════════════════════════════════════════════════════════════════════
// [#13639] A fail-closed RLS denial is reported as a DENIAL.
//
// Before this suite's repair, `explain` recognised only its own `__deny_all__`
// sentinel, so the "no active organization" path — which composes
// plugin-security's `RLS_DENY_FILTER` (`__rls_deny__:…`) and is guaranteed to
// return zero rows — was reported with verdict `narrows` and
// `decision.allowed: TRUE`. Not an imprecise label: an affirmatively wrong
// answer, handed to the operator asking why a user sees nothing.
//
// ⛔ The repair is RECOGNITION ONLY. The sentinels are not merged and the
// published `readFilter` payload is NOT rewritten — options B and C on #13639
// are the maintainer's, and the boundary between A and B is PINNED below, not
// left to a comment.
// ═══════════════════════════════════════════════════════════════════════════
describe('explainAccess — fail-closed RLS denial (#13639)', () => {
  // [ADR-0123 D2] Producers SPREAD the frozen constant rather than returning
  // it, which is why identity is decided on the sentinel's VALUE. Every
  // fixture here spreads it too, so a recognition that compared REFERENCES
  // would pass nothing.
  const rlsDeny = (): Record<string, unknown> => ({ ...RLS_DENY_FILTER });
  const readOf = async (deps: ExplainEngineDeps) =>
    explainAccess(deps, { object: 'leave_request', operation: 'read', context: CTX });

  // `DELEGATOR_QL` resolves the delegator, so BOTH computeRlsFilter calls happen
  // and `readFilter` is a real two-part composite — the only shape in which the
  // payload collapse at §9 is observable at all.
  const composedOf = async (delegatorFilter: Record<string, unknown>) =>
    explainAccess(
      makeDeps({
        ql: DELEGATOR_QL,
        computeRlsFilter: async (_s: any, _o: string, _op: string, ctx: any) =>
          ctx?.userId === 'u_boss' ? delegatorFilter : { owner_id: 'u1' },
      }),
      { object: 'leave_request', operation: 'read', context: { ...CTX, onBehalfOf: { userId: 'u_boss' } } },
    );

  // ── the object-level `rls` verdict ──────────────────────────────────────

  it('reports the rls layer as `denies`, not `narrows`', async () => {
    const rls = (await readOf(makeDeps({ rls: rlsDeny() }))).layers.find((l) => l.layer === 'rls')!;
    expect(rls.verdict).toBe('denies');
    expect(rls.detail).toContain('DENY ALL');
    expect(rls.detail).not.toContain('narrows the row set');
  });

  // ── ⭐ the assertion that matters most ──────────────────────────────────

  it('⭐ answers decision.allowed = FALSE for a request that cannot return a row', async () => {
    expect((await readOf(makeDeps({ rls: rlsDeny() }))).allowed).toBe(false);
  });

  it('decides identity on the sentinel VALUE, not on reference to the frozen constant', async () => {
    const spread = rlsDeny();
    expect(spread).not.toBe(RLS_DENY_FILTER); // control: the fixture really is a copy
    expect(spread).toEqual({ id: RLS_DENY_FILTER.id });
    expect((await readOf(makeDeps({ rls: spread }))).allowed).toBe(false);
  });

  // ── ⭐ THE A/B BOUNDARY — the payload is reported AS COMPOSED ───────────

  it('⭐ does NOT rewrite readFilter: the composed __rls_deny__ predicate is published unchanged', async () => {
    const d = await readOf(makeDeps({ rls: rlsDeny() }));
    expect(d.readFilter).toEqual({ id: RLS_DENY_FILTER.id });
    // ⛔ Option B — rewriting the payload for every deployment whose RLS fails
    // closed — is explicitly NOT what happened here.
    expect(d.readFilter).not.toEqual({ id: '__deny_all__' });
  });

  it('⭐ leaves a two-part composite INTACT when the DELEGATOR half denies — no collapse', async () => {
    const d = await composedOf(rlsDeny());
    expect(d.allowed).toBe(false);
    expect(d.layers.find((l) => l.layer === 'rls')!.verdict).toBe('denies');
    expect(d.readFilter).toEqual({ $and: [{ owner_id: 'u1' }, { id: RLS_DENY_FILTER.id }] });
  });

  // ── `__deny_all__` is unchanged in EVERY respect, collapse included ─────

  it('leaves the __deny_all__ verdict and decision exactly as they were', async () => {
    const d = await readOf(makeDeps({ rls: { id: '__deny_all__' } }));
    expect(d.allowed).toBe(false);
    const rls = d.layers.find((l) => l.layer === 'rls')!;
    expect(rls.verdict).toBe('denies');
    expect(rls.detail).toBe('Row-level security composes to DENY ALL for this principal.');
    expect(d.readFilter).toEqual({ id: '__deny_all__' });
  });

  it('⭐ still COLLAPSES a composite to { id: "__deny_all__" } for THAT sentinel', async () => {
    const d = await composedOf({ id: '__deny_all__' });
    expect(d.allowed).toBe(false);
    // The documented payload rewrite survives untouched for the sentinel the
    // published contract names.
    expect(d.readFilter).toEqual({ id: '__deny_all__' });
  });

  // ── the negative ───────────────────────────────────────────────────────

  it('a policy that genuinely NARROWS still narrows, and stays allowed', async () => {
    const d = await readOf(makeDeps({ rls: { owner_id: 'u1' } }));
    expect(d.allowed).toBe(true);
    const rls = d.layers.find((l) => l.layer === 'rls')!;
    expect(rls.verdict).toBe('narrows');
    expect(d.readFilter).toEqual({ owner_id: 'u1' });
  });

  it('an id predicate that is NOT a sentinel is a narrowing, not a denial', async () => {
    const d = await readOf(makeDeps({ rls: { id: 'r1' } }));
    expect(d.allowed).toBe(true);
    expect(d.layers.find((l) => l.layer === 'rls')!.verdict).toBe('narrows');
  });

  it('no RLS policy at all is still not_applicable and allowed', async () => {
    const d = await readOf(makeDeps({ rls: null }));
    expect(d.allowed).toBe(true);
    expect(d.layers.find((l) => l.layer === 'rls')!.verdict).toBe('not_applicable');
  });

  // ── record-grained layers: the CORRECTNESS must not move, the prose does ─
  //
  // Slice 1 measured that `outcome` and `matchesRecord` are ALREADY right at
  // both `isDenyAll` call sites today, because `matchesFilterCondition` excludes
  // every real record against either sentinel. So the two groups below are
  // asserted for opposite reasons: the correctness assertions are CONTROLS
  // (green with and without the repair), the `detail` assertions are the ones
  // the repair moves.
  describe('record-grained attribution (the isDenyAll call sites)', () => {
    const REC_CTX = { userId: 'u1', tenantId: 'org1', positions: ['sales_rep', 'everyone'], permissions: [] };
    const recOf = async (layered: { layer0: any; layer1: any }) =>
      explainAccess(
        {
          ...makeDeps({ rls: null }),
          computeLayeredRlsFilter: async () => layered,
          fetchRecord: async () => ({ id: 'r1', organization_id: 'org1', owner_id: 'u1' }),
          sharingReadFilter: async () => null,
          listRecordShares: async () => [],
          canEditRecord: async () => false,
        } as ExplainEngineDeps,
        { object: 'leave_request', operation: 'read', context: REC_CTX, recordId: 'r1' },
      );

    it('layer 0: outcome/matchesRecord/effect do NOT move — only the prose does', async () => {
      const l0 = (await recOf({ layer0: rlsDeny(), layer1: null })).layers.find((l) => l.layer === 'tenant_isolation')!;
      // CONTROL — already correct before the repair, must stay correct after.
      expect(l0.verdict).toBe('denies');
      expect(l0.record!.outcome).toBe('excluded');
      expect(l0.record!.matchesRecord).toBe(false);
      expect(l0.record!.rules?.[0]?.effect).toBe('excludes');
      expect(l0.record!.rowFilter).toEqual({ id: RLS_DENY_FILTER.id }); // payload untouched here too
      // THE PROSE — this is what the repair moves.
      expect(l0.record!.detail).toBe(
        'No active organization on the context — the tenant wall denies all rows (fail closed).',
      );
      expect(l0.record!.detail).not.toContain('does not match');
    });

    it('layer 1: outcome/matchesRecord/effect do NOT move — only the prose does', async () => {
      const l1 = (await recOf({ layer0: { organization_id: 'org1' }, layer1: rlsDeny() })).layers.find((l) => l.layer === 'rls')!;
      // CONTROL — already correct before the repair.
      expect(l1.record!.outcome).toBe('excluded');
      expect(l1.record!.matchesRecord).toBe(false);
      expect(l1.record!.rules?.[0]?.effect).toBe('excludes');
      expect(l1.record!.rowFilter).toEqual({ id: RLS_DENY_FILTER.id });
      // THE PROSE.
      expect(l1.record!.detail).toBe('Business RLS composes to DENY ALL for this principal.');
      expect(l1.record!.detail).not.toContain('does not satisfy');
    });

    it('a record the layers genuinely admit is still admitted (negative)', async () => {
      const d = await recOf({ layer0: { organization_id: 'org1' }, layer1: { owner_id: 'u1' } });
      const l0 = d.layers.find((l) => l.layer === 'tenant_isolation')!;
      expect(l0.record!.outcome).toBe('admitted');
      expect(l0.record!.matchesRecord).toBe(true);
      expect(d.layers.find((l) => l.layer === 'rls')!.record!.outcome).toBe('admitted');
    });

    it('the __deny_all__ prose at both call sites is unchanged (control)', async () => {
      const d = await recOf({ layer0: { id: '__deny_all__' }, layer1: { id: '__deny_all__' } });
      expect(d.layers.find((l) => l.layer === 'tenant_isolation')!.record!.detail).toBe(
        'No active organization on the context — the tenant wall denies all rows (fail closed).',
      );
      expect(d.layers.find((l) => l.layer === 'rls')!.record!.detail).toBe(
        'Business RLS composes to DENY ALL for this principal.',
      );
    });
  });
});

// ─────────────────────────────────────────────────────────────────────────────
// [#18253] A name nobody declared is a REFUSAL, not a verdict
// ─────────────────────────────────────────────────────────────────────────────

/**
 * Maintainer ruling of 2026-09-17, letter B: "`explain` on an object name that
 * does not exist returns a distinct error … instead of `denies`. … a typo must
 * not look like a permission decision."
 *
 * Measured before the fix (this file, one-off probe): a typo answered
 * `allowed: false` + `object_crud: 'denies'` — the pair a GENUINE denial
 * answers, on a `200`. Only the layer prose differed, and no client branches on
 * prose.
 *
 * The assertions are the ADR-0112 PAIR (`code` and `status`), never a bare
 * `toThrow()`: a `toThrow` passes for any `Error`, including the plain one a
 * regression would throw, and the ENVELOPE is what the ruling binds.
 */
describe('[#18253] explain refuses an object that does not exist', () => {
  const unresolvedDeps = (cause?: 'unpublished_draft' | 'metadata_unavailable' | 'unknown') =>
    makeDeps({
      getObjectSecurityMeta: async () => ({
        isPrivate: false,
        requiredPermissions: { all: [], read: [], create: [], update: [], delete: [] },
        fieldRequiredPermissions: {},
        unresolved: true,
        ...(cause ? { unresolvedCause: cause } : {}),
      }),
    } as Partial<ExplainEngineDeps>);

  const explainUnknown = (cause?: 'unpublished_draft' | 'metadata_unavailable' | 'unknown') =>
    explainAccess(unresolvedDeps(cause), { object: 'leave_requst', operation: 'read', context: CTX });

  it('answers 404 OBJECT_NOT_FOUND — the pair, not merely "it threw"', async () => {
    await expect(explainUnknown('unknown')).rejects.toMatchObject({
      code: 'OBJECT_NOT_FOUND',
      status: 404,
      // Both transports read a different property name (`errors.ts` header).
      statusCode: 404,
      name: 'ExplainObjectNotFoundError',
    });
  });

  it('the message says it is NOT an access decision, and names the object and operation', async () => {
    const err = await explainUnknown('unknown').then(
      () => { throw new Error('explain resolved a decision for an object that does not exist'); },
      (e: any) => e,
    );
    expect(err.message).toContain("'leave_requst'");
    expect(err.message).toContain("'read'");
    expect(err.message).toContain('NOT an access decision');
    // ⛔ NOT the `[Security] Access denied` prefix: that string is a MATCHER
    // (`isPermissionDeniedError`, `mapDataError`, the rest-server sanitiser),
    // and wearing it would re-flatten this refusal into the 403 it exists to
    // stop being.
    expect(err.message.startsWith('[Security] Access denied')).toBe(false);
    // One wording module, not a second spelling of the advice (#10401).
    expect(err.message).toContain(unresolvedPostureRemedy('unknown'));
  });

  it('a deps bag with NO cause at all refuses too — the default reading is `unknown`', async () => {
    await expect(explainUnknown(undefined)).rejects.toMatchObject({ code: 'OBJECT_NOT_FOUND', status: 404 });
  });

  it('an UNPUBLISHED DRAFT still explains as `denies` — the declaration exists', async () => {
    const d = await explainUnknown('unpublished_draft');
    expect(d.allowed).toBe(false);
    expect(d.layers.find((l) => l.layer === 'object_crud')!.verdict).toBe('denies');
    expect(d.layers.find((l) => l.layer === 'object_crud')!.detail).toContain('is not published');
  });

  it('a metadata-store OUTAGE still explains as `denies` — absence was never established', async () => {
    const d = await explainUnknown('metadata_unavailable');
    expect(d.allowed).toBe(false);
    expect(d.layers.find((l) => l.layer === 'object_crud')!.verdict).toBe('denies');
    expect(d.layers.find((l) => l.layer === 'object_crud')!.detail).toContain('OUTAGE');
  });

  it('control: a RESOLVED object whose sets grant nothing still answers `denies`, unchanged', async () => {
    const d = await explainAccess(makeDeps({ sets: [] }), {
      object: 'leave_request',
      operation: 'delete',
      context: CTX,
    });
    expect(d.allowed).toBe(false);
    expect(d.layers.find((l) => l.layer === 'object_crud')!.verdict).toBe('denies');
  });
});

// ─── [#20515] the explainer resolves IN an organization, as enforcement does ──
//
// The resolver applies a grant only while its organization is the active
// tenant; with none, no stored grant applies, and an organization-less row
// applies nowhere. The
// explainer used to reach every organization's grants by passing NO tenant —
// the very resolution that let a member removed from an organization keep that
// organization's `manage_metadata`. There is no "every organization" option to
// ask for instead: each caller names the organization it resolves in.
describe('[#20515] buildContextForUser and resolveDelegatorContext resolve in an organization', () => {
  const ALPHA = 'org_alpha';
  const BETA = 'org_beta';
  const tables = (): Rows => ({
    sys_user: [{ id: 'u_x', email: 'u_x@example.com' }],
    sys_member: [{ user_id: 'u_x', organization_id: BETA, role: 'member' }],
    sys_user_permission_set: [
      { user_id: 'u_x', permission_set_id: 'ps_alpha', permission_set: 'alpha_metadata_editors', organization_id: ALPHA },
      { user_id: 'u_x', permission_set_id: 'ps_beta', permission_set: 'beta_readers', organization_id: BETA },
      // Organization-less: invalid state since the 18.0 ownership ceremony, and
      // it confers nothing in any resolution.
      { user_id: 'u_x', permission_set_id: 'ps_orphan', permission_set: 'orphan_readers' },
    ],
    sys_permission_set: [
      { id: 'ps_alpha', name: 'alpha_metadata_editors', system_permissions: ['manage_metadata'] },
      { id: 'ps_beta', name: 'beta_readers' },
      { id: 'ps_orphan', name: 'orphan_readers' },
    ],
  });

  it('with no organization it explains what enforcement answers with none: no stored grant at all', async () => {
    const ctx = await buildContextForUser(makeGrantQl(tables()), 'u_x', NOW);
    expect([...ctx.permissions].sort()).toEqual([]);
    expect(ctx.systemPermissions).not.toContain('manage_metadata');
    // …and it is the enforcement resolver's own answer for that state.
    const enforced = await resolveUserAuthzGrants(makeGrantQl(tables()), 'u_x', { nowMs: NOW });
    expect(ctx.permissions).toEqual(enforced.permissions);
  });

  it('in an organization it explains that organization\'s grants alone, never another\'s nor the organization-less one', async () => {
    const inAlpha = await buildContextForUser(makeGrantQl(tables()), 'u_x', NOW, ALPHA);
    expect([...inAlpha.permissions].sort()).toEqual(['alpha_metadata_editors']);
    expect(inAlpha.systemPermissions).toContain('manage_metadata');
    const inBeta = await buildContextForUser(makeGrantQl(tables()), 'u_x', NOW, BETA);
    expect([...inBeta.permissions].sort()).toEqual(['beta_readers']);
    expect(inBeta.systemPermissions).not.toContain('manage_metadata');
  });

  /**
   * The delegator leg is an ENFORCEMENT input (the D10 intersection), not only
   * an explanation: `SecurityPlugin` resolves it through this function on every
   * on-behalf-of request. Resolved with no tenant it would hold none of the
   * delegator's stored grants — never what the delegator holds in the
   * organization the request runs in.
   */
  describe('resolveDelegatorContext: the delegator is resolved in the live principal\'s organization', () => {
    const delegatorQl = () => {
      const t = tables();
      return bindCatalogFromTables({
        ...makeGrantQl(t),
        async findOne(object: string, opts: EngineFindOneQueryInput) {
          assertEngineFindOnePredicate(object, opts);
          const id = (opts as any)?.where?.id;
          return (t[object] ?? []).find((r) => r.id === id) ?? null;
        },
      }, t);
    };

    it('live principal in org_alpha → the delegator\'s org_alpha grant applies, its org_beta grant does not', async () => {
      const res = await resolveDelegatorContext(
        delegatorQl(),
        { userId: 'agent_1', tenantId: ALPHA, onBehalfOf: { userId: 'u_x' } },
        NOW,
      );
      expect(res.kind).toBe('resolved');
      const ctx = (res as { kind: 'resolved'; context: any }).context;
      expect([...ctx.permissions].sort()).toEqual(['alpha_metadata_editors']);
      expect(ctx.tenantId).toBe(ALPHA);
    });

    it('live principal with no organization → none of the delegator\'s stored grants', async () => {
      const res = await resolveDelegatorContext(delegatorQl(), { userId: 'agent_1', onBehalfOf: { userId: 'u_x' } }, NOW);
      expect(res.kind).toBe('resolved');
      const ctx = (res as { kind: 'resolved'; context: any }).context;
      expect([...ctx.permissions].sort()).toEqual([]);
      expect(ctx.systemPermissions).not.toContain('manage_metadata');
    });
  });
});