security-plugin.ts

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

import { Plugin, PluginContext, POSTURE_LADDER } from '@objectstack/core';
import type { PermissionSet, RowLevelSecurityPolicy } from '@objectstack/spec/security';
import { describeHighPrivilegeBits, describeAnchorForbiddenBits, PUBLIC_FORM_SERVER_MANAGED_FIELDS } from '@objectstack/spec/security';
import { MCP_AGENT_PERMISSION_SET_RESTRICTED } from '@objectstack/spec/ai';
import { PermissionEvaluator, crudBucketForOperation } from './permission-evaluator.js';
import { DelegatedAdminGate } from './delegated-admin-gate.js';
import {
  INVITATION_PLACEMENT_SERVICE,
  createInvitationPlacementService,
} from './invitation-placement.js';
import {
  explainAccess,
  buildContextForUser,
  resolveDelegatorContext,
  intersectFieldMasks,
} from './explain-engine.js';
import type { ExplainDecision, ExplainOperation } from '@objectstack/spec/security';
import { bootstrapDeclaredPositions } from './bootstrap-declared-positions.js';
import { bootstrapDeclaredPermissions, upsertPackagePermissionSet, readDeclared } from './bootstrap-declared-permissions.js';
import { applyManagedWriteDenies } from './managed-object-write-denies.js';
import {
  createPermissionSetWriteThrough,
  registerPermissionSetProjection,
  reconcilePermissionSetProjection,
} from './permission-set-projection.js';
import { registerObjectPostureGate } from './object-posture-gate.js';
import {
  syncAudienceBindingSuggestions,
  listAudienceBindingSuggestions,
  confirmAudienceBindingSuggestion,
  dismissAudienceBindingSuggestion,
  type SuggestionDeps,
  type SuggestionListFilter,
} from './suggested-audience-bindings.js';
import { cleanupPackagePermissions } from './cleanup-package-permissions.js';
import { bootstrapBuiltinRoles } from './bootstrap-builtin-positions.js';
import { bootstrapSystemCapabilities } from './bootstrap-system-capabilities.js';
import { normalizeManagedByVocab } from './normalize-managed-by.js';
import { bootstrapDeclaredCapabilities } from './bootstrap-declared-capabilities.js';
import { RLSCompiler, RLS_DENY_FILTER } from './rls-compiler.js';
import { computeTenantLayer0Filter, andComposeLayers } from './tenant-layer.js';
import { isPlatformTenantPolicy, isAuthoredTenantPolicy } from './platform-tenant-policies.js';
import {
  normalizeTenancyPosture,
  postureEnforcesWall,
  type TenancyPosture,
} from '@objectstack/spec/security';
import {
  RLS_MEMBERSHIP_RESOLVER_SERVICE,
  RESERVED_RLS_MEMBERSHIP_KEYS,
  type IRlsMembershipResolver,
  type ISecurityService,
} from '@objectstack/spec/contracts';
import { matchesFilterCondition } from '@objectstack/formula';
import { FieldMasker } from './field-masker.js';
import { assertReadableQueryFields } from './predicate-guard.js';
import { PermissionDeniedError } from './errors.js';
import { assertEngineOwnedWriteAllowed } from './system-write-guard.js';
import { bootstrapPlatformAdmin } from './bootstrap-platform-admin.js';
import {
  backfillOrgAdminGrants,
  extractMemberPairs,
  reconcileOrgAdminGrant,
} from './auto-org-admin-grant.js';
import { SysPositionDetailPage } from '@objectstack/platform-objects/pages';
import {
  securityObjects,
  securityDefaultPermissionSets,
  securityPluginManifestHeader,
} from './manifest.js';

/**
 * [ADR-0095 D3 / Finding 2 / #2937] Platform-admin-EXCLUSIVE capabilities — the
 * platform-scoped `systemPermissions` that `admin_full_access` carries and
 * `organization_admin` DELIBERATELY withholds (see `default-permission-sets.ts`:
 * org admin is granted only `manage_org_users`/`setup.access`/`setup.write`).
 *
 * Holding ANY of these is the enforcement stand-in for the `PLATFORM_ADMIN`
 * posture rung (ADR-0095 D3): it is what distinguishes a true PLATFORM operator
 * from a TENANT org admin. Both hold `viewAllRecords`/`modifyAllRecords` via
 * their `'*'` wildcard grant, so the superuser-bypass bit ALONE cannot tell them
 * apart — which is exactly why an org admin used to cross the Layer 0 tenant wall
 * on private/platform-global/better-auth objects (Finding 2). `setup.access`/
 * `setup.write` are EXCLUDED on purpose: org admins hold them (they are the Setup
 * app shell + tenant-settings-write caps, not platform powers).
 *
 * [ADR-0099 D1 / P1] Since #2956 the resolver-derived `PLATFORM_ADMIN` rung
 * rides the ExecutionContext (`ctx.posture`), so the Layer 0 exemption gate now
 * reads the CARRIED rung as authoritative (see {@link isCarriedPosture} at the
 * decision site in `computeLayeredRlsFilter`). This capability probe DEMOTES to
 * a fallback: it applies only to contexts that never passed the shared resolver
 * (delegated-admin bridge, sharing service, `getReadFilter` consumers — the
 * hand-built-context population ADR-0096 D3 is eliminating). The probe stays a
 * strict subset of the carried rung's derivation (the unscoped `admin_full_access`
 * grant carries every capability below), so a disagreement can only NARROW the
 * exemption, never widen it (fail-safe; ADR-0099 I3).
 */
const PLATFORM_ADMIN_ONLY_CAPABILITIES: readonly string[] = [
  'manage_metadata',
  'manage_platform_settings',
  'studio.access',
  'manage_users',
];

/**
 * [ADR-0099 D1] Is `v` a carried posture rung (one of the ladder's values)?
 * Present ⇒ the value is authoritative for the Layer 0 tier decision; absent ⇒
 * fall back to the capability probe. Sourced from core's `POSTURE_LADDER` so the
 * enforcement gate and the resolver's derivation can never drift on the enum.
 */
function isCarriedPosture(v: unknown): boolean {
  return typeof v === 'string' && (POSTURE_LADDER as readonly string[]).includes(v);
}

/**
 * [ADR-0099 P0] Pure form of the platform-admin capability probe: does the held
 * capability set contain any platform-EXCLUSIVE capability? Exported so the
 * authz matrix gate (`authz-matrix-gate.test.ts`) can assert probe-vs-carried-rung
 * equivalence against the EXACT predicate enforcement runs — the P0 gate the
 * ADR-0099 P1 flip lands behind.
 */
export function hasPlatformAdminCapability(held: ReadonlySet<string>): boolean {
  for (const cap of PLATFORM_ADMIN_ONLY_CAPABILITIES) {
    if (held.has(cap)) return true;
  }
  return false;
}

/**
 * [ADR-0066 D3/⑤] Object `requiredPermissions` normalized into per-CRUD buckets.
 * `all` holds capabilities required for EVERY operation (the `string[]` form);
 * the per-op buckets hold capabilities from the `{read,create,update,delete}`
 * map form. The effective requirement for an operation is `all ∪ <bucket>`.
 */
interface NormalizedRequiredPermissions {
  all: string[];
  read: string[];
  create: string[];
  update: string[];
  delete: string[];
}

/** Per-object security posture resolved once and cached (see getObjectSecurityMeta). */
interface ObjectSecurityMeta {
  isPrivate: boolean;
  tenancyDisabled: boolean;
  isBetterAuthManaged: boolean;
  requiredPermissions: NormalizedRequiredPermissions;
  fieldRequiredPermissions: Record<string, string[]>;
}

const EMPTY_REQUIRED_PERMISSIONS: NormalizedRequiredPermissions = Object.freeze({
  all: [], read: [], create: [], update: [], delete: [],
}) as NormalizedRequiredPermissions;

/**
 * [ADR-0066 / #2918] Provenance spec for the platform/application asset objects
 * whose managed rows are write-protected by {@link SecurityPlugin.assertSystemRowWriteGate}.
 *
 * Both objects share the unified A4 (#2920) `managed_by` vocabulary — a row
 * authored by the platform or an application package is not the admin's to
 * delete or rewrite:
 *   • `platform` / `package` are managed; `admin`/∅ (tenant-authored) rows are
 *     the admin's.
 *   • sys_position additionally keeps its LEGACY values `system` (→ platform)
 *     and `config` (→ package) in the managed map: the boot normalizer
 *     (normalize-managed-by.ts) heals stored rows to the canonical vocabulary,
 *     but rows written before the normalizer runs — or in a store it has not
 *     touched yet — must not lose protection in the interim. Dropping the
 *     legacy keys here is what silently disarmed this gate for sys_position
 *     after the A4 rename (#2926 ①).
 * The map value for each managed `managed_by` is the human owner label used in
 * the (business-message-only) deny text.
 */
const SYSTEM_ROW_PROVENANCE: Record<
  string,
  { noun: string; pluralNoun: string; managed: Record<string, string> }
> = {
  sys_position: {
    noun: 'position',
    pluralNoun: 'positions',
    managed: {
      platform: 'the platform',
      package: 'an application package',
      // Legacy pre-A4 values — keep guarded until every store is normalized.
      system: 'the platform',
      config: 'an application package',
    },
  },
  sys_capability: {
    noun: 'capability',
    pluralNoun: 'capabilities',
    managed: { platform: 'the platform', package: 'an application package' },
  },
};

/** Normalize a raw object `requiredPermissions` (string[] | per-op map) into buckets. */
function normalizeRequiredPermissions(raw: unknown): NormalizedRequiredPermissions {
  if (Array.isArray(raw)) {
    return { all: raw.map(String), read: [], create: [], update: [], delete: [] };
  }
  if (raw && typeof raw === 'object') {
    const m = raw as Record<string, unknown>;
    const bucket = (v: unknown): string[] => (Array.isArray(v) ? v.map(String) : []);
    return {
      all: [],
      read: bucket(m.read),
      create: bucket(m.create),
      update: bucket(m.update),
      delete: bucket(m.delete),
    };
  }
  return { all: [], read: [], create: [], update: [], delete: [] };
}

/**
 * [ADR-0066 ⑤] Capabilities required for `operation` = the `all` bucket UNION the
 * operation's CRUD bucket. The array form (only `all` populated) thus gates EVERY
 * operation exactly as before; the map form gates only the mapped CRUD classes and
 * leaves an unmapped custom op ungated. De-duplicated for a clean error message.
 */
function requiredCapsForOperation(
  spec: NormalizedRequiredPermissions,
  operation: string,
): string[] {
  const bucket = crudBucketForOperation(operation);
  const caps = bucket ? [...spec.all, ...spec[bucket]] : spec.all;
  return caps.length > 0 ? [...new Set(caps)] : [];
}

export interface SecurityPluginOptions {
  /**
   * Additional permission sets to register with the metadata service on
   * plugin start. Defaults to {@link securityDefaultPermissionSets}
   * (admin_full_access / member_default / viewer_readonly).
   */
  defaultPermissionSets?: PermissionSet[];
  /**
   * Permission set name applied as an implicit baseline whenever an
   * authenticated request has no resolved permission sets (and no positions
   * that map to one). This guarantees baseline tenant/owner RLS for
   * every logged-in user even before an admin assigns explicit
   * profiles. Set to `null` to disable.
   *
   * @default 'member_default'
   */
  fallbackPermissionSet?: string | null;
}

/**
 * SecurityPlugin
 *
 * Provides RBAC, Row-Level Security, and Field-Level Security runtime.
 * Registers as an engine middleware on the ObjectQL engine.
 *
 * This plugin is fully optional — without it, the system operates
 * without permission checks (same as current behavior).
 *
 * **Multi-tenant Organization scoping is provided by the separate
 * `@objectstack/organizations` package** (auto-stamps
 * `organization_id` on insert, per-org seed replay, default-org
 * bootstrap). When that plugin is installed, SecurityPlugin detects
 * it via `getService('org-scoping')` and keeps the tenant-scoped RLS
 * policies that ship with the default permission sets. Without it,
 * *those shipped policies* are stripped so single-tenant deployments
 * don't pay the field-existence safety-net cost on every find —
 * app-authored policies are never stripped (ADR-0105 D3; they are
 * retained and fail closed at compile time, see
 * `platform-tenant-policies.ts`).
 *
 * Dependencies:
 * - objectql service (ObjectQL engine with middleware support)
 * - metadata service (MetadataFacade for reading permission sets and RLS policies)
 */
/**
 * [ADR-0090 D5/D9] Anchor-safety predicates moved to `@objectstack/spec/security`
 * (P3) so the authoring linter (`validateSecurityPosture`) and this runtime
 * gate share ONE definition. Re-exported here for existing consumers.
 */
export { describeHighPrivilegeBits } from '@objectstack/spec/security';

export class SecurityPlugin implements Plugin {
  name = 'com.objectstack.security';
  type = 'standard';
  version = '1.0.0';
  dependencies = ['com.objectstack.engine.objectql'];

  private permissionEvaluator = new PermissionEvaluator();
  private rlsCompiler = new RLSCompiler();
  private fieldMasker = new FieldMasker();
  private readonly bootstrapPermissionSets: PermissionSet[];
  private readonly fallbackPermissionSet: string | null;
  /**
   * Runtime probe — set in `start()` from
   * `ctx.getService('org-scoping')`. When `false`, the PLATFORM's own
   * tenant-scoped RLS policies are stripped from the per-request
   * policy set (saves the field-existence safety net cost on every
   * find in single-tenant deployments); app-authored policies are
   * retained and fail closed (ADR-0105 D3). When `true`, every policy
   * applies normally.
   */
  private tenancyPosture: TenancyPosture = 'single';
  /**
   * [ADR-0105 D11] The registered membership resolver, probed at `start()`.
   * `null` when none is installed — the overwhelmingly common case, and the
   * reason {@link stageRlsMembership} costs nothing when unused.
   */
  private rlsMembershipResolver: IRlsMembershipResolver | null = null;
  /**
   * [ADR-0105 D1] Back-compat view of {@link tenancyPosture}: "is an
   * organization wall enforced at all?" — the exact question the pre-spectrum
   * boolean answered. Layer 0 reads the posture itself; this stays for the
   * strip decision and the boot log, which only care wall / no wall.
   */
  private get orgScopingEnabled(): boolean {
    return postureEnforcesWall(this.tenancyPosture);
  }
  /**
   * [ADR-0105 D3] `object|policy` keys already reported by
   * {@link warnAuthoredTenantPolicyOnce}, so a retained authored tenant policy
   * is explained once per boot instead of on every find.
   */
  private readonly warnedAuthoredTenantPolicies = new Set<string>();
  /**
   * Per-object field-name cache. Populated lazily from the metadata
   * service / ObjectQL registry on first access per object. Schemas are
   * effectively immutable for the lifetime of the kernel today (hot
   * reload tears the kernel down), so we don't bother with
   * invalidation — a kernel restart drops the cache.
   */
  private readonly fieldNamesCache = new Map<string, Set<string> | null>();
  /**
   * Per-object cache of tenancy opt-out. `true` means the schema
   * explicitly disabled multi-tenancy (`tenancy.enabled === false` or
   * `systemFields.tenant === false`). Wildcard policies that target
   * the conventional tenant column (`organization_id`) are treated as
   * *not applicable* on these tables instead of triggering the
   * field-missing deny sentinel — without this, every read of a
   * cross-org catalog (e.g. `sys_package`, the Marketplace) returns
   * zero rows.
   */
  private readonly tenancyDisabledCache = new Map<string, boolean>();
  /**
   * Service handles captured in `start()` so the request-time RLS resolution
   * (used by BOTH the engine middleware and the public {@link getReadFilter}
   * service method) shares one code path. `null` until `start()` wires them.
   */
  private metadata: any = null;
  private ql: any = null;
  /** [ADR-0090 D12] Delegated-admin write gate — wired in start() once `ql` exists. */
  private delegatedAdminGate: DelegatedAdminGate | null = null;
  /**
   * [C2 / ADR-0095] Lazy kernel-service resolver, captured in start(). Used by the
   * record-grained explain path to reach the optional `sharing` service (a
   * deployment without plugin-sharing simply resolves `undefined`). Late-bound so
   * plugin load order does not matter.
   */
  private resolveKernelService: ((name: string) => any) | null = null;
  /** Unsubscribe handle for metadata-change cache invalidation (runtime metadata edits). */
  private metadataWatch: { unsubscribe: () => void } | null = null;
  /** ADR-0055: cache the resolved master-detail relation per controlled_by_parent object. */
  private cbpRelCache = new Map<string, { fk: string; master: string } | null>();
  /**
   * [ADR-0066 D2/D3] Per-object security posture cache: `private` flag
   * (access.default), platform-global flag (tenancy disabled), and the object's
   * `requiredPermissions` capability contract. Populated lazily from the schema;
   * cleared on metadata change alongside the other schema-derived caches.
   */
  private readonly objectSecurityMetaCache = new Map<string, ObjectSecurityMeta>();
  private dbLoader?: (names: string[]) => Promise<PermissionSet[]>;
  private logger: { info?: (...a: any[]) => void; warn?: (...a: any[]) => void; error?: (...a: any[]) => void } = {};

  constructor(options: SecurityPluginOptions = {}) {
    this.bootstrapPermissionSets =
      options.defaultPermissionSets ?? securityDefaultPermissionSets;
    this.fallbackPermissionSet =
      options.fallbackPermissionSet === undefined
        // ADR-0056 D7: an app may declare its default profile via `isDefault: true`
        // on a permission set; it becomes the fallback for users with no explicit
        // grants. Falls back to the built-in `member_default` when none is declared.
        ? (this.bootstrapPermissionSets.find((p) => (p as { isDefault?: boolean }).isDefault)?.name ?? 'member_default')
        : options.fallbackPermissionSet;
  }

  async init(ctx: PluginContext): Promise<void> {
    ctx.logger.info('Initializing Security Plugin...');

    // Register security services
    ctx.registerService('security.permissions', this.permissionEvaluator);
    ctx.registerService('security.rls', this.rlsCompiler);
    ctx.registerService('security.fieldMasker', this.fieldMasker);
    // Bootstrap permission sets (admin_full_access, member_default,
    // viewer_readonly by default) — exposed as a service so other
    // plugins (e.g. plugin-hono-server's /me/permissions endpoint)
    // can pass them as the fallback list to
    // `PermissionEvaluator.resolvePermissionSets` without re-importing
    // the platform-objects package directly.
    ctx.registerService('security.bootstrapPermissionSets', this.bootstrapPermissionSets);
    ctx.registerService('security.fallbackPermissionSet', this.fallbackPermissionSet);

    ctx.getService<{ register(m: any): void }>('manifest').register({
      ...securityPluginManifestHeader,
      objects: securityObjects,
      // [ADR-0090] SDUI detail page for sys_position — Holders (assignments,
      // name-keyed junction) + Permission Sets (bindings) as pure
      // record:related_list declarations; no bespoke UI.
      pages: [SysPositionDetailPage],
      // Permission sets ride along on the manifest so the metadata service
      // can resolve them by name when SecurityPlugin middleware queries
      // `metadata.list('permissions')`.
      permissions: this.bootstrapPermissionSets,
      // ADR-0029 D7 — contribute the RBAC entries into the Setup app's
      // `group_access_control` slot. This plugin owns these objects (K2), so it
      // ships their menu too; when the plugin is absent the entries don't appear.
      navigationContributions: [
        {
          app: 'setup',
          group: 'group_access_control',
          priority: 100,
          items: [
            { id: 'nav_positions', type: 'object', label: 'Positions', objectName: 'sys_position', icon: 'shield-check' },
            { id: 'nav_capabilities', type: 'object', label: 'Capabilities', objectName: 'sys_capability', icon: 'badge-check' },
            { id: 'nav_permission_sets', type: 'object', label: 'Permission Sets', objectName: 'sys_permission_set', icon: 'lock' },
          ],
        },
      ],
    });

    // ADR-0029 D8 — contribute this plugin's object translations to the i18n
    // service on kernel:ready (the i18n plugin may register after this one).
    if (typeof (ctx as any).hook === 'function') {
      (ctx as any).hook('kernel:ready', async () => {
        try {
          const i18n = ctx.getService<any>('i18n');
          if (i18n && typeof i18n.loadTranslations === 'function') {
            const { SecurityTranslations } = await import('./translations/index.js');
            for (const [locale, data] of Object.entries(SecurityTranslations)) {
              i18n.loadTranslations(locale, data as Record<string, unknown>);
            }
          }
        } catch { /* i18n optional */ }
      });
    }

    ctx.logger.info('Security Plugin initialized', {
      defaultPermissionSets: this.bootstrapPermissionSets.map((p) => p.name),
    });
  }

  async start(ctx: PluginContext): Promise<void> {
    ctx.logger.info('Starting Security Plugin...');

    // Get required services
    let ql: any;
    let metadata: any;

    try {
      ql = ctx.getService('objectql');
      metadata = ctx.getService('metadata');
    } catch (e) {
      ctx.logger.warn('ObjectQL or metadata service not available, security middleware not registered');
      return;
    }

    if (!ql || typeof ql.registerMiddleware !== 'function') {
      ctx.logger.warn('ObjectQL engine does not support middleware, security middleware not registered');
      return;
    }

    // Capture handles so the request-time RLS resolution is shared by the
    // engine middleware AND the public getReadFilter service method.
    this.metadata = metadata;
    this.ql = ql;
    this.logger = ctx.logger;
    this.rlsCompiler.setLogger?.(ctx.logger);
    // [C2 / ADR-0095] Late-bound resolver for the optional `sharing` service.
    this.resolveKernelService = (name: string) => {
      try { return ctx.getService(name); } catch { return undefined; }
    };

    // Invalidate metadata-derived caches when object/field metadata changes
    // at runtime (Studio / AI authoring). Without this they go stale until
    // restart — even single-node. With a cluster pub/sub driver the
    // metadata.changed event propagates cross-node, so peers invalidate too.
    const md: any = this.metadata;
    if (typeof md?.watch === 'function') {
      this.metadataWatch = md.watch('*', () => {
        this.fieldNamesCache.clear();
        this.tenancyDisabledCache.clear();
        this.cbpRelCache.clear();
        this.objectSecurityMetaCache.clear();
      });
    }

    // Resolve the tenancy POSTURE once at start time (the plugin DI graph is
    // static after start); Layer 0 and `collectRLSPolicies` consult it on every
    // request.
    //
    // ADR-0093 D4 / ADR-0105 D1 — prefer the `tenancy` service, the single
    // source of truth for which of `single` | `group` | `isolated` is in force
    // (a requested-but-unenforceable wall already resolves to `single` there).
    // Fall back to probing `org-scoping` directly when the tenancy service
    // isn't wired (e.g. an embedding without plugin-auth): its presence means
    // the historical `isolated` posture, preserving prior behavior exactly.
    try {
      const tenancy = ctx.getService<{ posture?: TenancyPosture; isolationActive?: boolean }>('tenancy');
      this.tenancyPosture =
        normalizeTenancyPosture(tenancy?.posture) ?? (tenancy?.isolationActive ? 'isolated' : 'single');
    } catch {
      try {
        this.tenancyPosture = ctx.getService('org-scoping') ? 'isolated' : 'single';
      } catch {
        this.tenancyPosture = 'single';
      }
    }
    // [ADR-0105 D2 / #3623] Hand the engine a posture accessor so its
    // driver-level NATIVE tenant scoping can widen to the caller's membership
    // union (`DriverOptions.tenantIds`) under the `group` posture. Wired from
    // HERE — the enforcement layer — on purpose: widening the driver wall is
    // only safe while the Layer 0 union wall enforces above it, so an
    // embedding without SecurityPlugin never widens (drivers keep active-org
    // equality — fail toward isolation).
    try {
      const engineSvc = ctx.getService<{ setTenancyPostureProvider?: (p: () => string | undefined) => void }>('objectql');
      engineSvc?.setTenancyPostureProvider?.(() => this.tenancyPosture);
    } catch {
      /* engine absent — nothing to widen */
    }
    // [ADR-0105 D11] Optional app/plugin membership resolver for the §7.3.1
    // `IN (current_user.<key>)` sets. Absent is the norm — probe once.
    try {
      this.rlsMembershipResolver =
        ctx.getService<IRlsMembershipResolver>(RLS_MEMBERSHIP_RESOLVER_SERVICE) ?? null;
    } catch {
      this.rlsMembershipResolver = null;
    }
    if (this.rlsMembershipResolver) {
      ctx.logger.info('[security] rls-membership-resolver registered', {
        keys: this.rlsMembershipResolver.keys,
      });
    }

    if (this.orgScopingEnabled) {
      ctx.logger.info(
        `[security] tenancy posture '${this.tenancyPosture}' — the Layer 0 organization wall is ACTIVE ` +
          `(${this.tenancyPosture === 'group'
            ? 'organization_id IN accessible_org_ids — union access across the caller\'s memberships'
            : 'organization_id = active organization'})`,
      );
    } else {
      ctx.logger.info(
        "[security] tenancy posture 'single' — Layer 0 is inert; the platform's own tenant-scoped RLS policies are stripped (app-authored ones are retained and fail closed, ADR-0105 D3)",
      );
    }

    // Construct a dbLoader once that lets resolvePermissionSets
    // surface user-defined permission sets from `sys_permission_set`
    // (created via the admin UI) in addition to plugin-registered
    // ones. Uses `isSystem` to bypass tenant RLS.
    const dbLoader = ql
      ? async (names: string[]) => {
          let rows: any;
          try {
            rows = await ql.find(
              'sys_permission_set',
              { where: { name: { $in: names } }, limit: names.length },
              { context: { isSystem: true } },
            );
          } catch {
            rows = [];
          }
          const list = Array.isArray(rows) ? rows : rows?.records ?? [];
          const parseJson = (v: any, fallback: any) => {
            if (typeof v !== 'string') return v ?? fallback;
            try { return JSON.parse(v || JSON.stringify(fallback)); } catch { return fallback; }
          };
          return list.map((r: any) => ({
            name: r.name,
            label: r.label,
            objects: parseJson(r.object_permissions, {}),
            fields: parseJson(r.field_permissions, {}),
            systemPermissions: parseJson(r.system_permissions, []),
            // [ADR-0090 D12] Hydrate the delegated-admin scope so the gate can
            // resolve a DB-authored delegate's authority. Null column → absent.
            ...(r.admin_scope ? { adminScope: parseJson(r.admin_scope, undefined) } : {}),
          }));
        }
      : undefined;
    this.dbLoader = dbLoader;

    // [ADR-0090 D12] Delegated-admin gate shares the SAME permission-set
    // resolution as the CRUD middleware, so a delegate's authority and their
    // ordinary grants can never drift. (`ql` is guaranteed non-null here —
    // start() bailed out above without a middleware-capable engine.)
    this.delegatedAdminGate = new DelegatedAdminGate({
      ql,
      resolveSets: (context: any) => this.resolvePermissionSetsForContext(context),
      logger: ctx.logger,
    });

    // [ADR-0105 D8] Scoped-invitation placement. Registered HERE because the
    // authority it enforces is this plugin's: issuance dry-runs the very same
    // DelegatedAdminGate above against the `sys_user_position` rows the
    // acceptance would write, so an invitation can never place what its issuer
    // could not have assigned directly. plugin-auth consumes the service and
    // REFUSES placement intent when it is missing — no gate, no placement.
    ctx.registerService(
      INVITATION_PLACEMENT_SERVICE,
      createInvitationPlacementService({
        ql,
        gate: this.delegatedAdminGate,
        logger: ctx.logger,
      }),
    );

    // ADR-0021 D-C — expose the per-request READ scope as a reusable service.
    // The analytics raw-SQL path (which bypasses this engine middleware)
    // auto-bridges to `getService('security').getReadFilter(object, context)`
    // to enforce tenant/RLS on every base + joined object. We register the
    // service only once the metadata/ql/dbLoader handles are wired (above), so
    // a degraded start never exposes a half-initialised resolver.
    try {
      // [ADR-0090 D5/D9] Suggested audience bindings — shared deps for the
      // list/confirm/dismiss surface (same set resolution as the middleware
      // and the delegated-admin gate, so admin-ness can never drift).
      const suggestionDeps: SuggestionDeps = {
        ql,
        metadata,
        resolveSets: (context: any) => this.resolvePermissionSetsForContext(context),
        logger: ctx.logger,
      };
      // Typed against the published contract so the registered surface cannot
      // drift from what cross-package consumers are promised: a renamed method,
      // a dropped one, or a changed return type fails THIS build rather than
      // silently degrading a consumer's feature detection at runtime.
      const securityService: ISecurityService = {
        getReadFilter: (object: string, context?: any) => this.getReadFilter(object, context),
        // [#3547] Readable-field projection for a context — the authoritative
        // column set for a read-derived export (`export ⊆ list`, #3391).
        // Same field mask as the read middleware (no drift). The REST export
        // route uses it to project columns instead of inferring readability
        // from already-masked data rows. See getReadableFields.
        getReadableFields: (object: string, context?: any) => this.getReadableFields(object, context),
        // [ADR-0046 §6.7] Effective permission-set NAMES for a caller — the
        // primitive the REST read layer needs to evaluate a permission-set-
        // gated book/doc audience ({ permissionSet: '…' }). Same resolution
        // as the middleware (positions expanded, additive baseline), so the
        // docs gate can never drift from data-plane enforcement. Throws on
        // resolution failure — callers must fail CLOSED (ADR-0049).
        resolvePermissionSetNames: async (context?: any): Promise<string[]> => {
          const sets = await this.resolvePermissionSetsForContext(context);
          return sets.map((s) => s.name);
        },
        // [ADR-0090 D6] First-class access explanation. Same code paths as
        // the middleware (resolution/evaluator/RLS compiler) — explained by
        // construction. Explaining ANOTHER user requires `manage_users`.
        explain: (request, callerContext?: any) =>
          this.explainAccessForCaller(
            { ...request, operation: String(request.operation) },
            callerContext,
          ),
        // [ADR-0090 D12 / ADR-0105 D8] What the CALLER may delegate — the read
        // half of the delegated-admin gate. A scoped-invitation form narrows
        // its unit/position pickers with this instead of listing the whole
        // tree and letting the user discover the boundary by refusal. Purely
        // self-scoped (the caller's own resolved sets are the only input), so
        // it discloses nothing beyond the authority they already hold.
        describeDelegableScope: async (callerContext?: any) => {
          const sets = await this.resolvePermissionSetsForContext(callerContext);
          // No gate wired (degraded start) → no delegable authority, and the
          // consumer renders an empty picker rather than a permissive one.
          if (!this.delegatedAdminGate) {
            return {
              isTenantAdmin: false,
              scopes: [],
              placeableBusinessUnitIds: [],
              assignablePositions: [],
            };
          }
          return this.delegatedAdminGate.describeDelegableScope(sets);
        },
        // [ADR-0090 D5/D9] Install-time suggestion surface: packages suggest
        // audience-anchor bindings; a tenant admin confirms (the binding is
        // written under the anchor + delegated-admin gates) or dismisses.
        listAudienceBindingSuggestions: (callerContext?: any, filter?: SuggestionListFilter) =>
          listAudienceBindingSuggestions(suggestionDeps, callerContext, filter),
        confirmAudienceBindingSuggestion: (callerContext: any, id: string) =>
          confirmAudienceBindingSuggestion(suggestionDeps, callerContext, id),
        dismissAudienceBindingSuggestion: (callerContext: any, id: string) =>
          dismissAudienceBindingSuggestion(suggestionDeps, callerContext, id),
      };
      ctx.registerService('security', securityService);
      ctx.logger.info('[security] registered "security" service (getReadFilter, getReadableFields, explain, audience-binding suggestions) — ADR-0021 D-C / ADR-0090 D5/D6/D9 / #3547');
    } catch (e) {
      ctx.logger.warn?.('[security] failed to register "security" service', {
        error: (e as Error).message,
      });
    }

    // Register security middleware
    ql.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {
      // System operations bypass security
      if (opCtx.context?.isSystem) {
        return next();
      }

      // ADR-0056 (Option A) — declaration-derived PUBLIC-FORM grant. A public
      // form submission carries `publicFormGrant: { object }` derived from the
      // form's declared target (set by the rest-server form-submit route). It
      // authorizes ONLY create + the immediate read-back on THAT object — never
      // anything else, and never the anonymous fall-open. This lets public forms
      // work under secure-by-default (requireAuth) WITHOUT a deployment-configured
      // `guest_portal`, scoped to exactly the declared object (the field
      // allow-list is enforced at the route; the context is request-scoped).
      const formGrant = opCtx.context?.publicFormGrant;
      if (formGrant && typeof formGrant === 'object' && (formGrant as { object?: string }).object) {
        const grantObject = (formGrant as { object: string }).object;
        const allowed =
          opCtx.object === grantObject &&
          ['insert', 'find', 'findOne', 'count'].includes(opCtx.operation);
        if (allowed) {
          // [#3022] The grant bypasses every downstream write gate (FLS 2.5,
          // owner anchor 3.5, tenant CHECK) — so the system-managed anchors
          // must be forced HERE, before the write is admitted. An anonymous
          // submission has no principal to backfill from and no conceivable
          // transfer authorization, so a supplied `owner_id` /
          // `organization_id` / audit column is stripped from every row (the
          // route-side field allow-list is the first net; this is the
          // data-layer boundary that holds even if a FormView declares — or
          // a zero-section form falls open to — one of these columns).
          // Ownership stays NULL for object hooks / the first-admin
          // bootstrap to assign, exactly like other anonymous-seeded rows.
          if (opCtx.operation === 'insert' && opCtx.data && typeof opCtx.data === 'object') {
            const rows = Array.isArray(opCtx.data) ? opCtx.data : [opCtx.data];
            const stripped = new Set<string>();
            for (const row of rows) {
              if (!row || typeof row !== 'object' || Array.isArray(row)) continue;
              for (const field of PUBLIC_FORM_SERVER_MANAGED_FIELDS) {
                if (Object.prototype.hasOwnProperty.call(row, field)) {
                  delete (row as Record<string, unknown>)[field];
                  stripped.add(field);
                }
              }
            }
            if (stripped.size > 0) {
              ctx.logger.warn(
                `[security] public-form insert on '${grantObject}' supplied server-managed ` +
                  `field(s) [${[...stripped].join(', ')}] — stripped (#3022)`,
              );
            }
          }
          return next();
        }
        throw new PermissionDeniedError(
          `[Security] Access denied: public-form grant permits only create/read-back on '${grantObject}', ` +
            `not '${opCtx.operation}' on '${opCtx.object}'`,
          { operation: opCtx.operation, object: opCtx.object },
        );
      }

      // [ADR-0086 P2 — 块2, evolved by ADR-0094] Two-doors write gate. A
      // permission set stamped `managed_by:'package'` is owned by the PACKAGE
      // door: its BASELINE is authored in the package and lands via publish
      // (块1). The admin door must never FORGE that provenance (insert or
      // update), and the lifecycle ops with no overlay translation
      // (transfer/restore/purge) stay refused on package rows. Ordinary
      // `update`/`delete` on a package row are handled downstream by the
      // ADR-0094 write-through, which translates them into env-scope OVERLAY
      // operations (customize / reset via the standard ADR-0005 layering) —
      // the boot re-seed can no longer revert an admin's change, because the
      // change lives in the overlay and the record projects overlay-wins.
      // Placed BEFORE the empty-principal fall-open and the CRUD check so the
      // forging boundary holds even for a principal-less context and a
      // superuser with modifyAllRecords. System/boot writes carry `isSystem`
      // and already short-circuited the whole middleware above.
      await this.assertPackageManagedWriteGate(opCtx);

      // [ADR-0066 / #2918] Built-in row-write guardrail for the platform/app
      // ASSET objects sys_position / sys_capability. Like the package gate
      // above, an unconditional data-layer boundary: a row authored by the
      // platform or an application package (provenance recorded in
      // `managed_by`) may not be deleted or rewritten through the admin door.
      // Unlike sys_permission_set there is NO ADR-0094 overlay write-through
      // for these objects, so the refusal must hold for update/delete here
      // rather than deferring to a downstream translation. Runs BEFORE the
      // empty-principal fall-open and the CRUD check so the boundary holds even
      // for a principal-less context and a superuser with modifyAllRecords.
      // System/boot writes carry `isSystem` and already short-circuited above,
      // so the seeder and package publish are unaffected.
      await this.assertSystemRowWriteGate(opCtx);

      // [ADR-0090 D5/D9] Audience-anchor binding guard — like the package
      // gate above, an unconditional data-layer boundary: a permission set
      // carrying high-privilege bits must never be bound to the `everyone`
      // or `guest` positions, no matter who asks. (Boot/system writes carry
      // `isSystem` and short-circuited above; the dev-mode default binding
      // is validated at seed time by the same predicate.)
      await this.assertAudienceAnchorBindingGate(opCtx);

      // [ADR-0103] Engine-owned write guard. Fail-closed on a user-context
      // generic write to a `system`/`append-only` object whose resolved
      // affordances forbid the verb (the engine-owned default). Keyed off
      // resolveCrudAffordances, not the raw bucket, so the admin/user-writable
      // members (RBAC link tables, prefs, messaging config) — which declare
      // userActions opening their verbs — pass through to the DelegatedAdminGate
      // / RLS below. System/boot writes carry `isSystem` and short-circuited
      // above; context-less service writes carry no userId and pass by
      // construction. Runs BEFORE the empty-principal fall-open so engine-owned
      // tables fail CLOSED for principal-less-but-user-context callers.
      assertEngineOwnedWriteAllowed(
        typeof ql?.getSchema === 'function' ? ql.getSchema(opCtx.object) : undefined,
        opCtx.operation,
        opCtx.context,
      );

      // [ADR-0090 D12] Delegated-administration gate. Writes to the RBAC
      // link tables (assignments / bindings / direct grants / env-set
      // authoring) are a GOVERNED operation: tenant-level admins pass
      // through to the ordinary CRUD/RLS checks; delegates need a covering
      // adminScope (BU subtree + allowlist + strict containment); everyone
      // else — including holders of plain CRUD grants on these tables — is
      // denied. Runs BEFORE the empty-principal fall-open below so RBAC
      // tables fail CLOSED for principal-less non-system contexts.
      if (this.delegatedAdminGate) {
        await this.delegatedAdminGate.assert(opCtx);
      }

      const positions = opCtx.context?.positions ?? [];
      const explicitPermissionSets = opCtx.context?.permissions ?? [];

      // Skip security checks if no positions AND no explicit permission sets
      // AND no userId (anonymous/unauthenticated). The auth middleware
      // should handle authentication separately.
      if (
        positions.length === 0 &&
        explicitPermissionSets.length === 0 &&
        !opCtx.context?.userId
      ) {
        return next();
      }

      // 1. Resolve permission sets from BOTH role names and explicit
      //    permission set names attached to the execution context. The
      //    resolution (incl. the implicit + post-resolution baseline
      //    fallback) is shared with the public getReadFilter service via
      //    resolvePermissionSetsForContext — keeping the find-path RLS and
      //    the analytics raw-SQL RLS provably in lock-step.
      let permissionSets: PermissionSet[] = [];
      try {
        permissionSets = await this.resolvePermissionSetsForContext(opCtx.context);
      } catch (e) {
        // Fail CLOSED. A permission-resolution failure must DENY the request,
        // never bypass the checks (that would let a degraded metadata service
        // expose every tenant's data). System/bootstrap operations already
        // short-circuited above (`opCtx.context?.isSystem`), so reaching here
        // means an authenticated user request whose RBAC/RLS could not be
        // resolved — deny it and alert.
        ctx.logger.error(
          `[security] permission resolution failed for operation '${opCtx.operation}' on ` +
          `object '${opCtx.object}' (user ${opCtx.context?.userId ?? 'unknown'}) — ` +
          `denying request (fail-closed)`,
          e instanceof Error ? e : new Error(String(e)),
        );
        throw new PermissionDeniedError(
          `[Security] Access denied: permission subsystem unavailable for ` +
          `operation '${opCtx.operation}' on object '${opCtx.object}'`,
        );
      }

      // [ADR-0090 D10 — agent intersection] When this principal acts ON BEHALF
      // OF a user (an AI agent or a service), its effective permission is the
      // INTERSECTION of its own grants and the delegator's grants — never the
      // union (confused-deputy prevention). Resolve the delegator's effective
      // permission sets ONCE here; every gate below AND-composes the two lists
      // so the tighter of the two wins at each axis (CRUD, capabilities, FLS,
      // depth, row-level using/check, VAMA). The whole thing is gated on the
      // presence of the delegation LINK (not the `principalKind` label — a
      // service acting for a user is the identical risk): on the ordinary
      // non-delegated path `delegatorSets` stays null, every combine reduces to
      // today's expression, no extra `ql` read happens, and behaviour is
      // byte-identical. A dangling link (delegator deleted) fails CLOSED — see
      // resolveDelegatorContext for why "empty sets" would be wrong (the
      // additive baseline would resurrect access for a non-existent user).
      let delegatorSets: PermissionSet[] | null = null;
      let delegatorContext: any = null;
      if (permissionSets.length > 0 && opCtx.context?.onBehalfOf?.userId) {
        const del = await resolveDelegatorContext(this.ql, opCtx.context);
        if (del.kind === 'missing') {
          throw new PermissionDeniedError(
            `[Security] Access denied: on-behalf-of principal names delegator ` +
              `'${del.userId}', who does not exist — refusing to act (ADR-0090 D10 fail-closed)`,
            { operation: opCtx.operation, object: opCtx.object },
          );
        }
        if (del.kind === 'resolved') {
          delegatorContext = del.context;
          delegatorSets = await this.resolvePermissionSetsForContext(delegatorContext);
        }
      }

      // [ADR-0066 D2/D3] Resolve the object's security posture (private flag,
      // platform-global flag, capability contract) once for the checks below.
      const secMeta =
        permissionSets.length > 0
          ? await this.getObjectSecurityMeta(opCtx.object)
          : { isPrivate: false, tenancyDisabled: false, isBetterAuthManaged: false, requiredPermissions: EMPTY_REQUIRED_PERMISSIONS, fieldRequiredPermissions: {} as Record<string, string[]> };

      // [#2850] $expand sub-read gate relaxation. The engine's expand path
      // re-enters `find` for a referenced object carrying `__expandRead` (a
      // server-set marker; `executionContext` is never client-built). For a
      // PUBLIC referenced object — covered by the '*' wildcard grant and thus
      // already broadly readable — applying the object-level CRUD /
      // requiredPermissions gate to the EXPANSION would only surface "never
      // designed for expand" modeling gaps (over-blocking a legitimate
      // status/owner lookup) without adding protection, since the row is
      // already visible. So waive those two throw-gates for PUBLIC expand
      // sub-reads only. RLS injection (step 3) and FLS masking (step 4) still
      // run, and a PRIVATE referenced object keeps the FULL gate — expansion
      // may reveal only rows the caller could have read directly.
      const expandSkipCrud =
        opCtx.operation === 'find' &&
        opCtx.context?.__expandRead === true &&
        !secMeta.isPrivate;

      // 1.5. [ADR-0066 D3/⑤] requiredPermissions AND-gate — a capability
      //      prerequisite checked BEFORE the CRUD grant (ADR §Precedence): a
      //      caller missing any required capability is denied regardless of how
      //      permissive their grants are. Per-operation (⑤): only the caps for
      //      THIS operation's CRUD class (plus any all-operations caps) apply.
      if (permissionSets.length > 0 && !expandSkipCrud) {
        const required = requiredCapsForOperation(secMeta.requiredPermissions, opCtx.operation);
        if (required.length > 0) {
          const held = this.permissionEvaluator.getSystemPermissions(permissionSets);
          const missing = required.filter((cap) => !held.has(cap));
          // [ADR-0090 D10] Both principals must hold every required capability.
          const missingDel = delegatorSets
            ? required.filter((cap) => !this.permissionEvaluator.getSystemPermissions(delegatorSets!).has(cap))
            : [];
          if (missing.length > 0 || missingDel.length > 0) {
            const allMissing = [...new Set([...missing, ...missingDel])];
            throw new PermissionDeniedError(
              `[Security] Access denied: '${opCtx.object}' (operation '${opCtx.operation}') requires capability ` +
                `[${required.join(', ')}] — ${missing.length > 0 ? 'caller' : 'the delegator'} is missing [${allMissing.join(', ')}]`,
              {
                operation: opCtx.operation,
                object: opCtx.object,
                positions,
                permissionSets: explicitPermissionSets,
                requiredPermissions: required,
                missingPermissions: allMissing,
              },
            );
          }
        }
      }

      // 2. CRUD permission check
      if (permissionSets.length > 0 && !expandSkipCrud) {
        const allowed = this.permissionEvaluator.checkObjectPermission(
          opCtx.operation,
          opCtx.object,
          permissionSets,
          { isPrivate: secMeta.isPrivate },
        );

        if (!allowed) {
          throw new PermissionDeniedError(
            `[Security] Access denied: operation '${opCtx.operation}' on object '${opCtx.object}' ` +
              `is not permitted for positions [${positions.join(', ')}]`,
            { operation: opCtx.operation, object: opCtx.object, positions, permissionSets: explicitPermissionSets },
          );
        }

        // [ADR-0090 D10] The delegator must independently grant the same op — an
        // agent may never act beyond the reach of the user it stands in for.
        if (delegatorSets && !this.permissionEvaluator.checkObjectPermission(
          opCtx.operation,
          opCtx.object,
          delegatorSets,
          { isPrivate: secMeta.isPrivate },
        )) {
          throw new PermissionDeniedError(
            `[Security] Access denied: on-behalf-of principal may not '${opCtx.operation}' ` +
              `'${opCtx.object}' — the delegator lacks that grant (ADR-0090 D10 intersection)`,
            { operation: opCtx.operation, object: opCtx.object, positions, permissionSets: explicitPermissionSets },
          );
        }
      }

      // 2.6. [ADR-0057 D1] Stash the grant's access DEPTH for this object so the
      //      sharing service can widen the owner-match (owner_id IN unit-set)
      //      while still OR-ing in shares. Owner-set expansion needs the BU graph
      //      (plugin-sharing), so we pass the scope STRING, not the resolved set.
      if (permissionSets.length > 0) {
        const sc: any = opCtx.context;
        // The AGENT's own depth drives plugin-sharing's owner-match for the
        // agent identity (unchanged on the non-delegated path).
        if (['find', 'findOne', 'count', 'aggregate'].includes(opCtx.operation)) {
          sc.__readScope = this.permissionEvaluator.getEffectiveScope('read', opCtx.object, permissionSets, { isPrivate: secMeta.isPrivate });
          // [ADR-0090 D10] Stash the DELEGATOR's own read depth SEPARATELY (not a
          // min of the two). The OWD/sharing owner-match is identity-scoped:
          // plugin-sharing re-runs the owner filter under the delegator's
          // identity + THIS depth and AND-s it in, giving a true per-identity
          // intersection. Narrowing __readScope alone would wrongly scope the
          // AGENT's identity to the delegator's depth (owner_id = agentId),
          // hiding the very rows the delegator legitimately owns.
          if (delegatorSets) {
            sc.__delegatorReadScope = this.permissionEvaluator.getEffectiveScope('read', opCtx.object, delegatorSets, { isPrivate: secMeta.isPrivate });
          }
        } else if (['update', 'delete', 'transfer', 'restore', 'purge'].includes(opCtx.operation)) {
          sc.__writeScope = this.permissionEvaluator.getEffectiveScope('write', opCtx.object, permissionSets, { isPrivate: secMeta.isPrivate });
          if (delegatorSets) {
            sc.__delegatorWriteScope = this.permissionEvaluator.getEffectiveScope('write', opCtx.object, delegatorSets, { isPrivate: secMeta.isPrivate });
          }
        }
      }

      // 2.7. Row-level WRITE authorization (pre-image check).
      //
      // RLS is injected as a `where` filter on the read path (step 3, via
      // `opCtx.ast`), but a single-id update/delete goes straight to
      // `driver.update(object, id, …)` / `driver.delete(object, id)` — it builds
      // no `ast`, so the row-level predicate is NEVER applied to by-id writes.
      // The result (#1985): the CRUD check passes (member_default grants edit/
      // delete) and the owner/tenant RLS that was supposed to scope the write is
      // silently bypassed — any member could modify another user's record.
      //
      // Fix: before the mutation, compute the write-operation RLS filter and
      // verify the TARGET row satisfies it. We re-read the row through the
      // engine with `{ id } AND <writeFilter>`; a `find` does not re-enter this
      // block, so there is no recursion, and read-side RLS/tenant scoping
      // compose naturally. A `null` result means the row is either gone or
      // RLS-hidden → deny. When `computeRlsFilter` returns `null` (no policy
      // applies — e.g. an admin set with no RLS, or `modifyAllRecords`) the
      // check is skipped and behaviour is unchanged.
      if (
        // update/delete today; transfer/restore/purge are pre-wired (#1883) so
        // the M2 ops inherit the pre-image check the moment they dispatch —
        // the CRUD bit alone must never be the only row-level defense.
        ['update', 'delete', 'transfer', 'restore', 'purge'].includes(opCtx.operation) &&
        permissionSets.length > 0 &&
        !!opCtx.context?.userId &&
        this.ql
      ) {
        const targetId = this.extractSingleId(opCtx);
        if (targetId != null) {
          // RLS policies declare select/insert/update/delete — map the
          // destructive lifecycle class onto its nearest write class so
          // authored policies apply (purge destroys like delete;
          // transfer/restore mutate like update).
          const rlsOperation =
            opCtx.operation === 'purge' ? 'delete'
            : opCtx.operation === 'transfer' || opCtx.operation === 'restore' ? 'update'
            : opCtx.operation;
          const writeFilter = await this.computeRlsFilter(
            permissionSets,
            opCtx.object,
            rlsOperation,
            opCtx.context,
          );
          // [ADR-0090 D10] The target row must satisfy BOTH principals' write
          // RLS — a by-id write on behalf of a user may only touch rows that
          // user could also touch. Compute the delegator's write filter against
          // the delegator's context (its userId/tenant substitutions) and AND
          // it into the same pre-image re-read.
          const delWriteFilter = delegatorSets
            ? await this.computeRlsFilter(delegatorSets, opCtx.object, rlsOperation, delegatorContext)
            : null;
          const writeParts = [writeFilter, delWriteFilter].filter(Boolean) as Record<string, unknown>[];
          if (writeParts.length > 0) {
            let visible: unknown = null;
            try {
              visible = await this.ql.findOne(opCtx.object, {
                where: { $and: [{ id: targetId }, ...writeParts] },
                context: opCtx.context,
              });
            } catch {
              // A read denial (e.g. no read permission) is itself a "cannot
              // touch this row" signal — fall through to the deny below.
              visible = null;
            }
            if (!visible) {
              throw new PermissionDeniedError(
                `[Security] Access denied: not permitted to ${opCtx.operation} this ` +
                  `'${opCtx.object}' record (row-level security)`,
                {
                  operation: opCtx.operation,
                  object: opCtx.object,
                  positions,
                  permissionSets: explicitPermissionSets,
                  recordId: targetId,
                },
              );
            }
          }
        }
      }

      // 2.8. ADR-0055 — controlled-by-parent WRITE: a detail write (insert/update/
      // delete) requires edit access to its master. The detail itself carries no
      // authored RLS, so the #1994 pre-image check above is a no-op for it; this
      // closes the by-id write path by checking the master instead.
      if (
        ['insert', 'update', 'delete', 'transfer', 'restore', 'purge'].includes(opCtx.operation) &&
        permissionSets.length > 0 &&
        !!opCtx.context?.userId &&
        this.ql
      ) {
        await this.assertControlledByParentWrite(
          permissionSets,
          opCtx.object,
          opCtx.operation,
          opCtx,
          opCtx.context,
        );
        // [ADR-0090 D10] The delegator must ALSO have edit access to the master
        // — a detail write on behalf of a user requires that user's master-edit.
        if (delegatorSets) {
          await this.assertControlledByParentWrite(
            delegatorSets,
            opCtx.object,
            opCtx.operation,
            opCtx,
            delegatorContext,
          );
        }
      }

      // 2.5. Field-Level Security write enforcement.
      //
      // The client-side masker (ObjectForm / inline grid) already hides
      // non-editable fields from the UI, but that is a UX layer only —
      // a hand-crafted POST / direct ObjectQL call can still target a
      // forbidden field. We fail-closed here with an explicit 403 and
      // the offending field names, so:
      //
      //   - honest clients get an actionable error (vs. silent drop,
      //     which manifests as a confusing partial-save), and
      //   - probing clients see that the boundary is enforced (vs.
      //     getting a 200 with the field silently ignored, which
      //     reveals nothing).
      //
      // Runs BEFORE the tenant/owner auto-injection (step 3.5) so the
      // system-set fields are not subject to the user's edit
      // permissions — they are populated from the execution context,
      // not from the caller's payload.
      if (
        (opCtx.operation === 'insert' || opCtx.operation === 'update') &&
        opCtx.data &&
        permissionSets.length > 0
      ) {
        let fieldPerms = this.permissionEvaluator.getFieldPermissions(
          opCtx.object,
          permissionSets,
        );
        // [ADR-0066 D3] AND-gate field-level requiredPermissions into the map.
        fieldPerms = this.foldFieldRequiredPermissions(fieldPerms, secMeta.fieldRequiredPermissions, permissionSets);
        // [ADR-0090 D10] Intersect with the delegator's field perms — a field
        // the agent may edit but the delegator may not becomes forbidden.
        if (delegatorSets) {
          let delFieldPerms = this.permissionEvaluator.getFieldPermissions(opCtx.object, delegatorSets);
          delFieldPerms = this.foldFieldRequiredPermissions(delFieldPerms, secMeta.fieldRequiredPermissions, delegatorSets);
          fieldPerms = intersectFieldMasks(fieldPerms, delFieldPerms);
        }
        if (Object.keys(fieldPerms).length > 0) {
          const forbidden = this.fieldMasker.detectForbiddenWrites(
            opCtx.data,
            fieldPerms,
          );
          if (forbidden.length > 0) {
            throw new PermissionDeniedError(
              `[Security] Field write denied: not permitted to edit ` +
                `[${forbidden.join(', ')}] on '${opCtx.object}'`,
              {
                operation: opCtx.operation,
                object: opCtx.object,
                positions,
                permissionSets: explicitPermissionSets,
                forbiddenFields: forbidden,
              },
            );
          }
        }
      }

      // 2.5b. Field-Level Security READ enforcement for aggregate inputs.
      //
      // The read path relies on RESULT masking (step 4) to hide FLS-protected
      // fields, but step 4 only covers find/findOne/insert/update — and an
      // aggregate's output rows carry only aliases, so masking could never
      // recover which source field fed `sum(salary) AS total`. Without an
      // input-side gate a caller may read a protected field's statistics
      // (sum/avg/min/max reveal the value outright on a single-row group).
      // Enforce on the INPUT: any groupBy / aggregation reference to an
      // FLS-unreadable field is rejected fail-closed with the offending names
      // (mirrors the write gate in 2.5). `where`-filter probing is a
      // platform-wide class shared with find() and is not widened here.
      if (opCtx.operation === 'aggregate' && permissionSets.length > 0) {
        let fieldPerms = this.permissionEvaluator.getFieldPermissions(opCtx.object, permissionSets);
        // [ADR-0066 D3] AND-gate field-level requiredPermissions into the map.
        fieldPerms = this.foldFieldRequiredPermissions(fieldPerms, secMeta.fieldRequiredPermissions, permissionSets);
        // [ADR-0090 D10] Intersect with the delegator's field perms — a field
        // the agent may read but the delegator may not stays forbidden.
        if (delegatorSets) {
          let delFieldPerms = this.permissionEvaluator.getFieldPermissions(opCtx.object, delegatorSets);
          delFieldPerms = this.foldFieldRequiredPermissions(delFieldPerms, secMeta.fieldRequiredPermissions, delegatorSets);
          fieldPerms = intersectFieldMasks(fieldPerms, delFieldPerms);
        }
        if (Object.keys(fieldPerms).length > 0) {
          const ast: any = opCtx.ast ?? {};
          const referenced = new Set<string>();
          for (const g of Array.isArray(ast.groupBy) ? ast.groupBy : []) {
            const f = typeof g === 'string' ? g : g?.field;
            if (typeof f === 'string' && f) referenced.add(f);
          }
          for (const a of Array.isArray(ast.aggregations) ? ast.aggregations : []) {
            if (typeof a?.field === 'string' && a.field) referenced.add(a.field);
          }
          const forbidden = [...referenced].filter(
            (f) => fieldPerms[f] && fieldPerms[f].readable === false,
          );
          if (forbidden.length > 0) {
            throw new PermissionDeniedError(
              `[Security] Field read denied: not permitted to aggregate ` +
                `[${forbidden.join(', ')}] on '${opCtx.object}'`,
              {
                operation: opCtx.operation,
                object: opCtx.object,
                positions,
                permissionSets: explicitPermissionSets,
                forbiddenFields: forbidden,
              },
            );
          }
        }
      }

      // 3.5. [#3004] `owner_id` — the row-ownership ANCHOR — is SYSTEM-MANAGED
      // for non-privileged writers. It is deliberately not `readonly` in the
      // schema (ownership is transferable, see registry.ts applySystemFields),
      // so the #2948 static-readonly strip never covers it; FLS doesn't gate it
      // by default; and OWD/RLS owner gates key OFF it — whoever controls the
      // value controls who may update/delete the row. So the middleware owns
      // the anchor:
      //
      //   • INSERT: an empty `owner_id` is auto-stamped to the acting user
      //     (without this the row has `owner_id = NULL` and the default
      //     `owner_only_writes` RLS policy hides it from its own creator).
      //     Batch rows included. A SUPPLIED owner that is NOT the acting user
      //     is an ownership FORGE — denied unless the caller holds the
      //     transfer grant (`allowTransfer`, or `modifyAllRecords` which
      //     implies it).
      //   • UPDATE: a supplied `owner_id` is an ownership TRANSFER (or a
      //     disown, when null) — denied without the transfer grant. The
      //     single-id no-op echo (a form save sending the unchanged owner
      //     back) is tolerated by comparing against the pre-image; a bulk
      //     change-set carrying `owner_id` has no pre-image to compare and
      //     fails CLOSED.
      //
      // System/boot writes carry `isSystem` and short-circuited the whole
      // middleware above — imports, OAuth provisioning, cron snapshots and
      // seed claims that legitimately write foreign/NULL owners are unaffected.
      // Under delegation (ADR-0090 D10) BOTH principals must hold the grant.
      //
      // `organization_id` auto-injection has moved to
      // `@objectstack/organizations`; its forge guard is step 3.7 below.
      //
      // [#3023] EXEMPTION — the engine's referential-integrity FK clear. When a
      // referenced record is deleted, `cascadeDeleteRelations` nulls the FK on
      // every dependent (owner_id included). That `owner_id = null` is an
      // integrity-mandated consequence of an already-authorized parent delete,
      // NOT a user disown, so the transfer guard must not fire and abort the
      // cascade. The marker rides a server-DERIVED context (never client-built —
      // same trust model as `__expandRead`), so it cannot be forged from a
      // request to slip an ordinary ownership write past the guard.
      if (
        (opCtx.operation === 'insert' || opCtx.operation === 'update') &&
        opCtx.data &&
        typeof opCtx.data === 'object' &&
        !opCtx.context?.__referentialFieldClear
      ) {
        const isInsert = opCtx.operation === 'insert';
        const rows = (Array.isArray(opCtx.data) ? opCtx.data : [opCtx.data]) as Record<string, unknown>[];
        // Own-property test only — never read `owner_id` through the prototype
        // chain (a polluted `Object.prototype.owner_id` must not make ordinary
        // field-only updates look like ownership writes).
        const writesOwner = (r: unknown): r is Record<string, unknown> =>
          !!r && typeof r === 'object' && !Array.isArray(r) &&
          Object.prototype.hasOwnProperty.call(r, 'owner_id');
        // A valid owner id is a NON-EMPTY SCALAR. Anything else (array / object /
        // boolean / '' ) is neither a stampable self-owner nor a tolerable echo —
        // String()-coercing it would let `owner_id: [selfId]` pass as "self" and
        // corrupt the anchor into an array (self-lockout).
        const isScalarId = (v: unknown): v is string | number =>
          (typeof v === 'string' && v !== '') || (typeof v === 'number' && Number.isFinite(v));

        // Cheap pre-check: does any row actually WRITE owner_id? On update this
        // skips the whole guard (and the field-set resolution) for the common
        // path whose change-set never mentions the anchor. Insert always runs —
        // it must stamp an absent owner.
        if (isInsert || rows.some(writesOwner)) {
          const fields = await this.getObjectFieldNames(metadata, opCtx.object, ql);
          if (fields?.has('owner_id')) {
            const userId = opCtx.context?.userId;
            const denyOwnerWrite = (action: string): never => {
              throw new PermissionDeniedError(
                `[Security] Access denied: 'owner_id' on '${opCtx.object}' is system-managed — ` +
                  `${action} requires the transfer grant (allowTransfer or modifyAllRecords)`,
                { operation: opCtx.operation, object: opCtx.object, positions, permissionSets: explicitPermissionSets },
              );
            };
            // Lazily evaluated + memoized (incl. a `false` result): the common
            // path pays nothing, and ADR-0090 D10 — under delegation BOTH
            // principals must independently hold the transfer grant.
            let transferGrant: boolean | null = null;
            const hasTransferGrant = (): boolean => {
              if (transferGrant === null) {
                transferGrant =
                  this.permissionEvaluator.checkObjectPermission('transfer', opCtx.object, permissionSets, { isPrivate: secMeta.isPrivate }) &&
                  (!delegatorSets || this.permissionEvaluator.checkObjectPermission('transfer', opCtx.object, delegatorSets, { isPrivate: secMeta.isPrivate }));
              }
              return transferGrant;
            };

            if (isInsert) {
              for (const row of rows) {
                if (!row || typeof row !== 'object' || Array.isArray(row)) continue;
                if (!writesOwner(row) || row.owner_id == null || row.owner_id === '') {
                  // Auto-stamp the acting user (batch rows included — the
                  // single-record-only stamp left bulk-inserted rows NULL-owned
                  // and invisible to their creator).
                  if (userId) row.owner_id = userId;
                } else if (
                  !(isScalarId(row.owner_id) && userId != null && String(row.owner_id) === String(userId)) &&
                  !hasTransferGrant()
                ) {
                  // A supplied owner that is not the acting user (or not a valid
                  // scalar id) is a forge — denied without the transfer grant.
                  denyOwnerWrite('creating a record owned by another user');
                }
              }
            } else {
              // UPDATE — a supplied owner_id is a transfer/disown. Only the
              // single-id no-op echo (a form save resending the UNCHANGED owner)
              // is tolerated; an array / bulk change-set has no single pre-image
              // to compare and fails CLOSED.
              const single = !Array.isArray(opCtx.data);
              for (const row of rows) {
                if (!writesOwner(row)) continue;
                if (hasTransferGrant()) break; // authorized transfer — allow every row
                let unchanged = false;
                if (single && isScalarId(row.owner_id)) {
                  const targetId = this.extractSingleId(opCtx);
                  if (targetId != null && this.ql) {
                    try {
                      // Read the pre-image under the CALLER's context (NOT
                      // isSystem): a form echo only makes sense for a row the
                      // caller can already see. This threads the caller's open
                      // transaction (an in-tx echo isn't spuriously denied) AND
                      // closes the owner-enumeration oracle a system read would
                      // open (a caller who can't read the row gets null → deny,
                      // indistinguishable from a non-owner).
                      const pre = await this.getCallerPreImage(opCtx, targetId);
                      unchanged = !!pre && pre.owner_id != null && String(pre.owner_id) === String(row.owner_id);
                    } catch {
                      unchanged = false; // fail closed
                    }
                  }
                }
                if (!unchanged) denyOwnerWrite(`changing record ownership on ${opCtx.operation}`);
              }
            }
          }
        }
      }

      // 3.6. [ADR-0058 D4] RLS WRITE `check` — post-image validation.
      //
      // `using` gates which EXISTING rows a write may target (the #1994
      // pre-image, step 2.7). `check` validates the NEW / CHANGED row
      // (post-image) on insert/update — the PostgreSQL WITH CHECK analog. We
      // compile the declared `check` clauses with the canonical compiler and
      // match the resolved FilterCondition against the post-image in-memory
      // (the single-record backend for the same filter shape, ADR-0058 D6). A
      // row that fails the check is DENIED (fail closed, D5) — never silently
      // written. Scoped to policies that EXPLICITLY declare `check`, so an
      // object governed only by `using` is unaffected.
      if (
        (opCtx.operation === 'insert' || opCtx.operation === 'update') &&
        opCtx.data &&
        typeof opCtx.data === 'object' &&
        !Array.isArray(opCtx.data) &&
        permissionSets.length > 0 &&
        !!opCtx.context?.userId
      ) {
        const checkFilter = await this.computeWriteCheckFilter(
          permissionSets,
          opCtx.object,
          opCtx.operation,
          opCtx.context,
        );
        // [ADR-0090 D10] The post-image must satisfy the delegator's CHECK too —
        // an on-behalf-of write may not produce a row the delegator itself
        // could not have written.
        const delCheckFilter = delegatorSets
          ? await this.computeWriteCheckFilter(delegatorSets, opCtx.object, opCtx.operation, delegatorContext)
          : null;
        const checkParts = [checkFilter, delCheckFilter].filter(Boolean) as Record<string, unknown>[];
        if (checkParts.length > 0) {
          // Build the post-image. Insert → the new row. Update by-id → the
          // pre-image merged with the change set (so a check on an unchanged
          // field still sees its value). A bulk update (no single id) cannot
          // form a post-image here — it is governed by the using-based AST
          // scoping (step 3); we log and skip rather than guess.
          let postImage: Record<string, unknown> | null = { ...(opCtx.data as Record<string, unknown>) };
          if (opCtx.operation === 'update') {
            const targetId = this.extractSingleId(opCtx);
            if (targetId == null) {
              this.logger.warn?.(
                `[Security] RLS check on bulk update '${opCtx.object}' is not post-image validated ` +
                  `(governed by the using-scoped where); single-id writes are checked.`,
              );
              postImage = null;
            } else if (this.ql) {
              // Shares the memoized caller pre-image with the step-3.5 owner
              // echo check — the identical (object, id, caller-context) row.
              const pre = await this.getCallerPreImage(opCtx, targetId);
              if (pre) postImage = { ...pre, ...(opCtx.data as Record<string, unknown>) };
            }
          }
          if (postImage && !checkParts.every((f) => matchesFilterCondition(postImage as any, f as any))) {
            this.logger.warn?.(
              `[Security] RLS check FAILED on ${opCtx.operation} '${opCtx.object}' — write denied (fail-closed)`,
            );
            throw new PermissionDeniedError(
              `[Security] Access denied: the ${opCtx.operation} would violate a row-level CHECK on '${opCtx.object}'`,
              { operation: opCtx.operation, object: opCtx.object, positions, permissionSets: explicitPermissionSets },
            );
          }
        }
      }

      // 3.7. [ADR-0095 D1 / #2937 / Finding 1] Layer 0 tenant post-image check
      // for INSERT and UPDATE.
      //
      // The tenant wall (Layer 0) is AND-composed onto reads and onto the
      // update/delete PRE-image, but two write paths escaped it because they
      // carry a `organization_id` VALUE that the pre-image/AST scoping never
      // inspects:
      //
      //   • INSERT has no pre-image and builds no AST, so a member could `insert`
      //     a row bearing a FORGED `organization_id` (another org) and land it in
      //     the victim tenant (the enterprise auto-stamp only fills a MISSING
      //     value, never overwrites a supplied one).
      //   • UPDATE (Finding 1 / BLOCKER): the pre-image check (step 2.7) validates
      //     only that the caller may touch the EXISTING row (old org == A); it
      //     never sees the NEW value. `organization_id` is auto-stamp-insert-only,
      //     FLS doesn't protect it, server-side `readonly` isn't enforced, and the
      //     RLS `check` fires only for explicit policies — so a member owning a
      //     row R in org A could `update` R with `{organization_id: victim org B}`
      //     and MOVE the row into another tenant, where it becomes visible. This
      //     is a cross-tenant write by any member.
      //
      // Both close identically here: a SUPPLIED (non-empty) `organization_id` in
      // the write payload must satisfy the SAME Layer 0 filter the read side uses
      // (isolation active, tenant object, platform-admin posture exemption,
      // fail-closed on a missing active org). For UPDATE this makes
      // `organization_id` effectively immutable in non-platform user contexts: the
      // only value that passes is the caller's active org (which — since the
      // pre-image already scoped the target to that org — equals the row's current
      // org), so a re-point to any OTHER tenant is denied. A bulk update carrying a
      // cross-tenant `organization_id` change-set is caught too (the check inspects
      // the change-set value, not a per-row post-image).
      //
      // Scope: only a SUPPLIED `organization_id` is validated — an ABSENT value on
      // insert is the organizations-plugin auto-stamp's responsibility, and an
      // update that doesn't touch `organization_id` carries no value here, so
      // ordinary writes are unaffected. A pure plugin-security deployment has no
      // isolation active (Layer 0 → null), so this is ordering-independent w.r.t.
      // the auto-stamp middleware. System / boot writes carry `isSystem` and
      // short-circuited the whole middleware above, so legitimate cross-org moves
      // (import engine, migrations, plugin SYSTEM_CTX) are unaffected. A true
      // platform admin on a posture-permitting object is exempt via Layer 0 (same
      // rule as reads/insert).
      //
      // [ADR-0105 D5] BULK inserts are covered here too. The check previously
      // required a non-array payload, so an `insert` of an ARRAY of rows could
      // carry a forged `organization_id` per row and never meet the wall — the
      // same defect #2937 closed for the single-row shape, one call-site down
      // (AGENTS.md #10: a `case` label is not enforcement, check the call site).
      //
      // This validates SUPPLIED values only; it never fills an absent one.
      // Auto-stamping `organization_id` stays with the enterprise
      // `@objectstack/organizations` runtime (its Middleware A), which is also
      // what ACTIVATES every walled posture — so a deployment that reaches this
      // code with a walled posture always has the stamper installed. Keeping the
      // stamp there means a forged `org-scoping` registration yields NULL-org
      // rows that the wall hides, i.e. a broken deployment rather than a working
      // unlicensed one; validation stays here because it is a security property,
      // not a packaging one.
      if (
        (opCtx.operation === 'insert' || opCtx.operation === 'update') &&
        opCtx.data &&
        typeof opCtx.data === 'object' &&
        !!opCtx.context?.userId
      ) {
        const writeRows: Record<string, unknown>[] = (
          Array.isArray(opCtx.data) ? (opCtx.data as unknown[]) : [opCtx.data as unknown]
        ).filter((r: unknown): r is Record<string, unknown> =>
          !!r && typeof r === 'object' && !Array.isArray(r),
        );

        const suppliedRows = writeRows.filter(
          (r) => r.organization_id != null && r.organization_id !== '',
        );
        if (suppliedRows.length > 0) {
          const tenantCheck = await this.computeWriteTenantCheckFilter(
            permissionSets,
            opCtx.object,
            opCtx.operation,
            opCtx.context,
          );
          // [ADR-0090 D10] The post-image must also satisfy the delegator's tenant
          // wall — an on-behalf-of write may not land a row in a tenant the
          // delegator itself could not reach.
          const delTenantCheck = delegatorSets
            ? await this.computeWriteTenantCheckFilter(delegatorSets, opCtx.object, opCtx.operation, delegatorContext)
            : null;
          const tenantParts = [tenantCheck, delTenantCheck].filter(Boolean) as Record<string, unknown>[];
          // EVERY supplied row must clear the wall — one forged row in a bulk
          // payload denies the whole write (fail closed, no partial landing).
          if (
            tenantParts.length > 0 &&
            !suppliedRows.every((row) => tenantParts.every((f) => matchesFilterCondition(row as any, f as any)))
          ) {
            this.logger.warn?.(
              `[Security] Layer 0 tenant CHECK FAILED on ${opCtx.operation} '${opCtx.object}' — write denied ` +
                `(fail-closed); a supplied organization_id is outside the caller's organization scope`,
            );
            throw new PermissionDeniedError(
              `[Security] Access denied: the ${opCtx.operation} would place '${opCtx.object}' in another tenant ` +
                `(organization_id is outside the caller's organization scope)`,
              { operation: opCtx.operation, object: opCtx.object, positions, permissionSets: explicitPermissionSets },
            );
          }
        }
      }

      // 2.9. Field-level predicate guard (anti filter-oracle, objectui#2251).
      // FieldMasker (step 4) only strips hidden fields from RESULTS — a
      // caller could still probe a hidden field's value by filtering /
      // sorting / grouping on it (row presence is the oracle; the objectui
      // /data surface makes URL-driven predicates first-class). Reject such
      // queries outright — silent predicate dropping would change query
      // semantics unpredictably. MUST run against the CALLER's OWN predicate,
      // before the RLS injection below: RLS / sharing filters legitimately
      // reference fields the caller cannot read (e.g. owner_id) and must not be
      // rejected.
      if (opCtx.ast) {
        let guardPerms = this.permissionEvaluator.getFieldPermissions(opCtx.object, permissionSets);
        guardPerms = this.foldFieldRequiredPermissions(guardPerms, secMeta.fieldRequiredPermissions, permissionSets);
        // [ADR-0090 D10] A field readable only by the agent is not queryable on
        // the delegator's behalf — intersect before the oracle guard.
        if (delegatorSets) {
          let delGuard = this.permissionEvaluator.getFieldPermissions(opCtx.object, delegatorSets);
          delGuard = this.foldFieldRequiredPermissions(delGuard, secMeta.fieldRequiredPermissions, delegatorSets);
          guardPerms = intersectFieldMasks(guardPerms, delGuard);
        }
        if (Object.keys(guardPerms).length > 0) {
          // [#2982 follow-up] For a bulk WRITE the caller's own predicate is
          // `opCtx.options.where` (untouched); `opCtx.ast.where` may ALREADY
          // carry an owner-match that plugin-sharing's write branch composed in
          // — and plugin-sharing is a SIBLING middleware whose registration
          // order relative to this one is not guaranteed. Guarding the injected
          // AST would 403 a legitimate bulk write on an object whose owner_id is
          // FLS-hidden, purely because a sibling filter mentioned it. Inspect
          // the caller's own predicate so the guard is independent of middleware
          // order and never mistakes an injected filter for a probe. Reads keep
          // guarding the ast: the read seed is the caller's query verbatim and
          // this middleware runs before its own RLS injection.
          const guardTarget: Record<string, unknown> =
            opCtx.operation === 'update' || opCtx.operation === 'delete'
              ? { where: opCtx.options?.where }
              : (opCtx.ast as unknown as Record<string, unknown>);
          assertReadableQueryFields(guardTarget, guardPerms, opCtx.object);
        }
      }

      // 3. RLS filter injection. The policy collection + field-existence
      // safety + compile (incl. the fail-closed deny sentinel) is shared with
      // the public getReadFilter service via computeRlsFilter, so the engine
      // find-path and the analytics raw-SQL path enforce identical scoping.
      if (opCtx.ast) {
        const extra: Record<string, unknown>[] = [];
        const rlsFilter = await this.computeRlsFilter(
          permissionSets,
          opCtx.object,
          opCtx.operation,
          opCtx.context,
        );
        if (rlsFilter) extra.push(rlsFilter);
        // ADR-0055: a controlled_by_parent object derives its read scope from the
        // master record — `masterFK IN (accessible master ids)`, AND-ed in.
        const cbpFilter = await this.computeControlledByParentFilter(
          permissionSets,
          opCtx.object,
          opCtx.context,
        );
        if (cbpFilter) extra.push(cbpFilter);
        // [ADR-0090 D10] AND the delegator's read RLS (and CBP) into the same
        // where — the delegated principal sees only rows BOTH may see. Computed
        // against the delegator's own context so its userId/tenant substitutions
        // are faithful.
        if (delegatorSets) {
          const delRls = await this.computeRlsFilter(delegatorSets, opCtx.object, opCtx.operation, delegatorContext);
          if (delRls) extra.push(delRls);
          const delCbp = await this.computeControlledByParentFilter(delegatorSets, opCtx.object, delegatorContext);
          if (delCbp) extra.push(delCbp);
        }
        if (extra.length) {
          opCtx.ast.where = opCtx.ast.where
            ? { $and: [opCtx.ast.where, ...extra] }
            : extra.length === 1
              ? extra[0]
              : { $and: extra };
        }
      }

      await next();

      // 4. Field-level security: mask restricted fields in returned records.
      // Covers reads AND the record echoed back by a write — otherwise a caller
      // with edit-but-not-field-read could PATCH a record and read a
      // read-protected field back out of the mutation response (FLS bypass).
      // Field WRITES are already blocked upstream (detectForbiddenWrites); this
      // closes the read leak on the response image.
      if (opCtx.result && ['find', 'findOne', 'insert', 'update'].includes(opCtx.operation)) {
        let fieldPerms = this.permissionEvaluator.getFieldPermissions(opCtx.object, permissionSets);
        // [ADR-0066 D3] AND-gate field-level requiredPermissions into the mask.
        fieldPerms = this.foldFieldRequiredPermissions(fieldPerms, secMeta.fieldRequiredPermissions, permissionSets);
        // [ADR-0090 D10] Mask any field the delegator cannot read, too.
        if (delegatorSets) {
          let delFieldPerms = this.permissionEvaluator.getFieldPermissions(opCtx.object, delegatorSets);
          delFieldPerms = this.foldFieldRequiredPermissions(delFieldPerms, secMeta.fieldRequiredPermissions, delegatorSets);
          fieldPerms = intersectFieldMasks(fieldPerms, delFieldPerms);
        }
        if (Object.keys(fieldPerms).length > 0) {
          opCtx.result = this.fieldMasker.maskResults(opCtx.result, fieldPerms, opCtx.object);
        }
      }
    });

    ctx.logger.info('Security middleware registered on ObjectQL engine');

    // [ADR-0094] Data-door write-through: every non-system CRUD write on
    // `sys_permission_set` is redirected into the metadata store (the ONE
    // authoritative store for definitions); the record is projector-owned.
    // Registered AFTER the security middleware, so it runs INSIDE it — the
    // two-doors gate, the delegated-admin gate, and the CRUD/FLS checks have
    // all passed before a write is translated. Kernels without a capable
    // metadata protocol pass through to the legacy direct write (single
    // store — no split brain to prevent).
    ql.registerMiddleware(
      createPermissionSetWriteThrough({
        ql,
        metadata,
        getProtocol: () => {
          try { return (ctx as any).getService?.('protocol') ?? null; } catch { return null; }
        },
        logger: ctx.logger,
      }),
      { object: 'sys_permission_set' },
    );

    // Defer platform admin bootstrap until all plugins finish starting —
    // sys_user / sys_permission_set objects must be registered (by
    // plugin-auth and platform-objects respectively) before we can
    // insert seed rows. Falls back to immediate execution when the
    // kernel does not expose `hook` (test stubs).
    let bootstrapRanOnce = false;
    // [ADR-0094] Guard so the env-projection wiring runs exactly once even
    // though runBootstrap re-runs (e.g. after the first user insert) —
    // registerMutationProjector replaces idempotently, but the legacy
    // onMetadataMutation fallback appends listeners, and re-wiring that would
    // project each save N times.
    let envProjectionWired = false;
    // [#3325 / ADR-0092] Union the better-auth managed-object write denies into
    // the default sets from the LIVE registry, replacing the hand-maintained
    // baseline as the source of truth (a newly-declared identity table is then
    // covered without editing a list). This mutates the shared
    // `bootstrapPermissionSets` instances IN PLACE — the same objects the
    // permission evaluator resolves and `bootstrapPlatformAdmin` serializes into
    // the seed row — so it must run BEFORE the seeder below, and once (the
    // transform is idempotent, but the once-flag avoids re-reading the registry /
    // re-logging on every runBootstrap re-entry). See managed-object-write-denies.ts.
    let managedDeniesApplied = false;
    const runBootstrap = async () => {
      try {
        if (!managedDeniesApplied) {
          const { applied, skippedExisting } = applyManagedWriteDenies(
            this.bootstrapPermissionSets,
            readDeclared(ql, 'object'),
          );
          managedDeniesApplied = true;
          if (applied > 0) {
            ctx.logger.info(
              `[security] managed-object write denies unioned from registry (ADR-0092): ` +
                `${applied} injected, ${skippedExisting} already present`,
            );
          }
        }
        const report = await bootstrapPlatformAdmin(ql, this.bootstrapPermissionSets, {
          logger: ctx.logger,
        });
        // [ADR-0057 D6 / #2077] Seed stack-declared positions into sys_position so they
        // stop being decorative (position→permission-set resolution + recipients).
        try {
          await bootstrapDeclaredPositions(ql, this.metadata, { logger: ctx.logger });
        } catch (e) {
          ctx.logger.warn('[security] declared-position seeding failed', { error: (e as Error).message });
        }
        // [ADR-0086 D5] Seed stack-declared permission sets into
        // sys_permission_set with package provenance (managed_by:'package' +
        // package_id) — packages ship working default access for their own
        // objects, and the admin surface finally sees them. Runs AFTER
        // bootstrapPlatformAdmin so the platform defaults keep their
        // insert-once, provenance-less shape (env config, never clobbered).
        try {
          await bootstrapDeclaredPermissions(ql, this.metadata, { logger: ctx.logger });
        } catch (e) {
          ctx.logger.warn('[security] declared-permission seeding failed', { error: (e as Error).message });
        }

        // [ADR-0090 D5] The baseline→`everyone` binding runs LATER — after
        // `bootstrapBuiltinRoles` seeds the `everyone` anchor (the anchor must
        // exist before it can be bound). See `bindFallbackToEveryone` below.
        // [ADR-0086 P2 — 块1] Register the publish-time materializer so a
        // permission set authored/edited through the PACKAGE door (saved as a
        // `permission` draft, then published) lands in sys_permission_set with
        // managed_by:'package' + package_id — the exact provenance the boot
        // seeder stamps, only now on the runtime publish path instead of only at
        // boot. Idempotent: registerPublishMaterializer replaces on re-run, and
        // upsertPackagePermissionSet refuses to clobber env- or foreign-owned
        // rows (ADR-0086 D4), so the two doors never overwrite each other.
        try {
          const protocol: any = ctx.getService?.('protocol');
          if (protocol && typeof protocol.registerPublishMaterializer === 'function') {
            protocol.registerPublishMaterializer(
              'permission',
              async (args: { body: unknown; packageId: string | null }) => {
                const r = await upsertPackagePermissionSet(ql, args.body, args.packageId, ctx.logger);
                const applied = r.seeded + r.updated;
                // [ADR-0090 D5] A published set carrying the install-time
                // suggestion flag surfaces (or retires) its pending
                // suggestion row right away — same convergent sync as boot.
                if (applied > 0 && (args.body as { isDefault?: boolean } | null)?.isDefault !== undefined) {
                  try { await syncAudienceBindingSuggestions(ql, this.metadata, ctx.logger); } catch { /* non-fatal */ }
                }
                // A publish that materialized nothing did NOT go live — report it
                // as a failure with the reason so the package-door UI never shows
                // a clean publish over a set the admin surface can't see (ADR-0049
                // honesty). The upsert only lands zero rows when it refused: the
                // name is owned by another package, owned by the env door, or the
                // publish carried no owning package_id to stamp.
                if (applied === 0) {
                  return {
                    success: false, inserted: 0, updated: 0,
                    error: r.skippedForeign > 0
                      ? 'permission set name is owned by another package'
                      : r.skippedEnvAuthored > 0
                        ? 'permission set name is owned by the environment (edit it through the admin door)'
                        : 'permission set was not materialized (publish carried no owning package)',
                  };
                }
                return { success: true, inserted: r.seeded, updated: r.updated };
              },
            );
          }
          // [#2747] Uninstall counterpart of the materializer above: when the
          // owning package is uninstalled, revoke its data-plane permission
          // rows (package-owned sets + their position/user bindings + the
          // package's suggestion rows) so grants die with the package — the
          // "no ghost grants" clause of ADR-0090 D5.
          if (protocol && typeof protocol.registerUninstallCleanup === 'function') {
            protocol.registerUninstallCleanup(
              'security.package-permissions',
              async (args: { packageId: string }) => {
                const r = await cleanupPackagePermissions(ql, args.packageId, ctx.logger);
                return {
                  success: true,
                  removed: r.sets + r.positionBindings + r.userGrants + r.suggestions,
                };
              },
            );
          }
          // [ADR-0094] Environment door — the `permission` mutation projector.
          // The protocol AWAITS it inside saveMetaItem / publishMetaItem /
          // deleteMetaItem, so the sys_permission_set record (and the metadata
          // manager's in-memory entry, which the evaluator's registry-first
          // list('permission') resolution reads) already reflects a Studio
          // save when it returns — no projection race. Falls back to the
          // fire-and-forget onMetadataMutation subscription (#2857/#2867) on
          // protocols that predate registerMutationProjector.
          if (!envProjectionWired) {
            envProjectionWired = registerPermissionSetProjection(protocol, {
              ql, metadata: this.metadata, logger: ctx.logger,
            });
          }
          // [#3050] OWD posture authoring gate — pre-persistence veto on
          // runtime-authored `object` bodies: env-tighten-only over packaged
          // declarations (ADR-0086 D1) + external ≤ internal (ADR-0090 D11).
          // Feature-detected; protocols predating registerAuthoringGate keep
          // the legacy (CLI-lint-only) behavior.
          registerObjectPostureGate(protocol);
          // [ADR-0094 D4] Converge record ↔ metadata: project env overlays
          // onto records (creating missing ones), backfill legacy data-door
          // creations into the metadata store once, and heal drifted records
          // from the effective body (metadata wins). Idempotent per boot.
          try {
            await reconcilePermissionSetProjection(protocol, {
              ql, metadata: this.metadata, logger: ctx.logger,
            });
          } catch (e) {
            ctx.logger.warn('[security] permission-set projection reconciliation failed (ADR-0094)', { error: (e as Error).message });
          }
        } catch (e) {
          ctx.logger.warn('[security] permission publish-materializer registration failed', { error: (e as Error).message });
        }
        // [ADR-0068 D2] Seed the framework's reserved built-in identity positions
        // (platform_admin / org_*) so the role catalog is self-describing.
        try {
          await bootstrapBuiltinRoles(ql, { logger: ctx.logger });
        } catch (e) {
          ctx.logger.warn('[security] built-in role seeding failed', { error: (e as Error).message });
        }
        // [ADR-0090 D5] Bind the configured baseline set to the `everyone`
        // audience anchor (idempotent). This makes the CLI/dev fallback
        // (`fallbackPermissionSet` — the app's `isDefault` set) visible as an
        // ordinary position binding: same table, same audit path, same explain
        // surface as any admin-authored default grant. The binding is validated
        // with the SAME high-privilege predicate the write gate enforces — a
        // dangerous baseline is refused loudly, never seeded. MUST run after
        // `bootstrapBuiltinRoles` (which seeds the `everyone` anchor) and before
        // `syncAudienceBindingSuggestions` (so the app's own fallback set is
        // already bound and never generates a redundant pending suggestion).
        try {
          if (this.fallbackPermissionSet) {
            const boot = this.bootstrapPermissionSets.find((p) => p.name === this.fallbackPermissionSet);
            const offending = boot ? describeHighPrivilegeBits(boot) : null;
            if (offending) {
              ctx.logger.warn('[security] refusing to bind fallback set to everyone — high-privilege bits', {
                set: this.fallbackPermissionSet, offending,
              });
            } else {
              const everyoneRows = await ql.find('sys_position', { where: { name: 'everyone' }, limit: 1, context: { isSystem: true } });
              const everyone: any = Array.isArray(everyoneRows) && everyoneRows[0] ? everyoneRows[0] : null;
              const setRows = await ql.find('sys_permission_set', { where: { name: this.fallbackPermissionSet }, limit: 1, context: { isSystem: true } });
              const set: any = Array.isArray(setRows) && setRows[0] ? setRows[0] : null;
              if (everyone?.id && set?.id) {
                const existing = await ql.find('sys_position_permission_set', {
                  where: { position_id: everyone.id, permission_set_id: set.id }, limit: 1, context: { isSystem: true },
                });
                if (!(Array.isArray(existing) && existing[0])) {
                  await ql.insert('sys_position_permission_set', {
                    id: `pps_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`,
                    position_id: everyone.id,
                    permission_set_id: set.id,
                  }, { context: { isSystem: true } });
                  ctx.logger.info('[security] baseline set bound to everyone anchor (ADR-0090 D5)', { set: this.fallbackPermissionSet });
                }
              }
            }
          }
        } catch (e) {
          ctx.logger.warn('[security] everyone-anchor baseline binding failed (non-fatal)', { error: (e as Error).message });
        }
        // [ADR-0090 D5/D9] Reconcile the suggested-audience-binding surface:
        // every declared `isDefault: true` set that is not already bound to
        // its anchor becomes a PENDING suggestion row awaiting admin
        // confirmation — never auto-bound. Runs after the anchors are seeded
        // and after the baseline binding above, so the app's own fallback set
        // (already bound) never nags.
        try {
          await syncAudienceBindingSuggestions(ql, this.metadata, ctx.logger);
        } catch (e) {
          ctx.logger.warn('[security] audience-binding suggestion sync failed (non-fatal)', { error: (e as Error).message });
        }
        // [ADR-0066 D1] Seed the capability registry (sys_capability) in two
        // passes. FIRST the EXPLICIT package declarations (`defineCapability` /
        // `stack.capabilities`) land with `managed_by:'package'` + package_id
        // provenance — the formal replacement for the implicit derive-from-
        // systemPermissions back-door. THEN the platform curated set + the
        // back-compat derived defaults, SKIPPING any name a package already
        // declared (so the placeholder never clobbers the authored capability).
        let declaredCapabilityNames: string[] = [];
        try {
          const capOutcome = await bootstrapDeclaredCapabilities(ql, this.metadata, { logger: ctx.logger });
          declaredCapabilityNames = capOutcome.declaredNames;
        } catch (e) {
          ctx.logger.warn('[security] declared-capability seeding failed', { error: (e as Error).message });
        }
        try {
          await bootstrapSystemCapabilities(ql, this.bootstrapPermissionSets, {
            logger: ctx.logger,
            declaredCapabilityNames,
          });
        } catch (e) {
          ctx.logger.warn('[security] capability seeding failed', { error: (e as Error).message });
        }
        // [A4 #2920] Heal residual legacy `managed_by` values (env sets stamped
        // 'user'; older positions stamped system/config/user) onto the unified
        // platform/package/admin vocab. Runs after the seeders so their canonical
        // writes land first; idempotent and non-fatal.
        try {
          await normalizeManagedByVocab(ql, { logger: ctx.logger });
        } catch (e) {
          ctx.logger.warn('[security] managed_by vocab normalization failed (non-fatal)', { error: (e as Error).message });
        }
        bootstrapRanOnce = true;
        ctx.logger.info('[security] platform bootstrap complete', report);
        return report;
      } catch (e) {
        ctx.logger.warn('[security] platform bootstrap failed', { error: (e as Error).message });
        return undefined;
      }
    };
    if (typeof (ctx as any).hook === 'function') {
      (ctx as any).hook('kernel:ready', runBootstrap);
    } else {
      void runBootstrap();
    }

    // Re-run bootstrap after a sys_user insert so the FIRST user that
    // signs up after boot is auto-promoted to platform admin (and, in
    // multi-tenant mode, bound to the seeded default organization)
    // without requiring a server restart. The function itself is
    // idempotent and bails out as soon as any platform admin exists.
    //
    // We deliberately do NOT auto-create a "personal workspace" for
    // every subsequent self-service signup. In a B2B / invitation-
    // driven product (the framework's primary target), users must
    // either accept an invitation or explicitly create their first
    // organization. The account UI's /register flow already routes
    // users with zero memberships to /organizations/new for exactly
    // this case.
    ql.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {
      await next();
      if (
        opCtx?.object === 'sys_user' &&
        (opCtx?.operation === 'create' || opCtx?.operation === 'insert')
      ) {
        if (bootstrapRanOnce) {
          await runBootstrap();
        }
      }
    });

    // ── Auto-grant `organization_admin` on sys_member lifecycle ─────────
    //
    // For every `sys_member` row whose role is `owner` or `admin`, keep
    // a `sys_user_permission_set` row scoped to that organization in
    // sync. See `auto-org-admin-grant.ts` for the full rationale and
    // the anti-escalation argument (org_admin is read-only on the
    // global RBAC tables, so a freshly-granted admin cannot rebind
    // themselves to `admin_full_access`).
    //
    // We register one middleware that handles insert / update / delete
    // uniformly by always reconciling every (user, org) pair touched
    // by the operation. `reconcileOrgAdminGrant` is idempotent so a
    // double-fire (e.g. better-auth followed by an org plugin
    // synchronizer) is harmless.
    ql.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {
      await next();
      if (opCtx?.object !== 'sys_member') return;
      const op = opCtx?.operation;
      if (
        op !== 'insert' &&
        op !== 'create' &&
        op !== 'update' &&
        op !== 'delete' &&
        op !== 'remove'
      ) {
        return;
      }
      const pairs = extractMemberPairs(opCtx);
      for (const { userId, orgId } of pairs) {
        try {
          await reconcileOrgAdminGrant(ql, userId, orgId, { logger: ctx.logger, posture: this.tenancyPosture });
        } catch (e) {
          ctx.logger.warn?.('[security] org_admin reconcile failed', {
            userId,
            orgId,
            error: (e as Error).message,
          });
        }
      }
    });

    // Backfill organization_admin grants after the platform admin
    // bootstrap settles on kernel:ready. Idempotent — only inserts
    // missing rows and revokes orphaned ones, never duplicates.
    const runOrgAdminBackfill = async () => {
      try {
        await backfillOrgAdminGrants(ql, { logger: ctx.logger, posture: this.tenancyPosture });
      } catch (e) {
        ctx.logger.warn?.('[security] organization_admin backfill failed', {
          error: (e as Error).message,
        });
      }
    };
    if (typeof (ctx as any).hook === 'function') {
      (ctx as any).hook('kernel:ready', runOrgAdminBackfill);
    } else {
      void runOrgAdminBackfill();
    }

    // Per-organization seed data replay on `sys_organization` insert
    // moved to `@objectstack/organizations` (along with
    // `claimOrphanOrgRows` / `cloneOrgSeedData`). Install that
    // plugin for multi-tenant deployments.
  }

  async destroy(): Promise<void> {
    this.metadataWatch?.unsubscribe();
    this.metadataWatch = null;
  }

  /**
   * ADR-0021 D-C — resolve the per-request READ scope (tenant + RLS predicate)
   * for one object as a canonical `FilterCondition`, WITHOUT touching the
   * ObjectQL engine. This is the seam the analytics raw-SQL path bridges to so
   * it enforces the SAME row scoping the engine middleware applies on `find`.
   *
   * Returns:
   *   - `undefined` → no scope applies (system context, or an unauthenticated
   *     request with no userId/positions/permissions — authn is gated elsewhere).
   *   - a `FilterCondition` → AND it into the object's scan (the join's `ON`/
   *     `WHERE` for analytics; the where clause for a plain find).
   *   - the `RLS_DENY_FILTER` sentinel → policies applied but none compiled, or
   *     resolution failed — fail-closed to zero rows. NEVER returns "allow all"
   *     on error, so a degraded permission subsystem cannot leak cross-tenant
   *     rows through analytics.
   *
   * Async because permission-set resolution can hit the database; the analytics
   * service pre-resolves these per request (base + every joined object) before
   * the synchronous SQL builder runs.
   */
  /**
   * [ADR-0090 D6] Explain access for a caller. `request.userId` (explaining
   * someone else) requires the caller to hold `manage_users`, be system, or —
   * [D12] — hold a delegated `adminScope` whose BU subtree covers the target
   * user (an access report is itself sensitive data, but an admin who can
   * already rewire a user's grants may read why they resolve as they do).
   * The evaluation delegates to {@link explainAccess} with the SAME internals
   * the middleware uses.
   */
  async explainAccessForCaller(
    request: { object: string; operation: string; userId?: string; recordId?: string },
    callerContext?: any,
  ): Promise<ExplainDecision> {
    const operation = String(request?.operation ?? 'read') as ExplainOperation;
    const object = String(request?.object ?? '');
    if (!object) throw new Error('[Security] explain: request.object is required');
    const recordId = request?.recordId != null && request.recordId !== '' ? String(request.recordId) : undefined;

    let targetContext = callerContext ?? {};
    if (request.userId && request.userId !== callerContext?.userId) {
      const callerIsSystem = callerContext?.isSystem === true;
      if (!callerIsSystem) {
        const callerSets = await this.resolvePermissionSetsForContext(callerContext).catch(() => []);
        const held = this.permissionEvaluator.getSystemPermissions(callerSets);
        if (!held.has('manage_users')) {
          // [ADR-0090 D12] Delegated administrators may explain principals
          // inside their delegation boundary (fail-closed on any error).
          const delegated = this.delegatedAdminGate
            ? await this.delegatedAdminGate
                .scopesCoverUser(callerSets, request.userId)
                .catch(() => false)
            : false;
          if (!delegated) {
            throw new PermissionDeniedError(
              `[Security] Access denied: explaining another user's access requires the 'manage_users' ` +
                `capability or a delegated adminScope covering that user (ADR-0090 D6/D12).`,
              { object, operation, targetUserId: request.userId },
            );
          }
        }
      }
      targetContext = await buildContextForUser(this.ql, request.userId);
    }

    // [C2 / ADR-0095] The optional `sharing` service backs the record-grained
    // sharing attribution. Resolved lazily; absent (no plugin-sharing) → the
    // record path still works, the sharing layer simply reports not_evaluated.
    const sharing = recordId ? (this.resolveKernelService?.('sharing') as any) : undefined;

    return explainAccess(
      {
        ql: this.ql,
        resolveSets: (c: any) => this.resolvePermissionSetsForContext(c),
        evaluator: this.permissionEvaluator,
        getObjectSecurityMeta: (o: string) => this.getObjectSecurityMeta(o),
        requiredCaps: (meta: any, engineOp: string) => requiredCapsForOperation(meta, engineOp),
        computeRlsFilter: (sets, o, engineOp, c) => this.computeRlsFilter(sets as any, o, engineOp, c),
        getFieldMask: (sets, o, fieldRequired) => {
          let fp = this.permissionEvaluator.getFieldPermissions(o, sets as any);
          fp = this.foldFieldRequiredPermissions(fp, fieldRequired, sets as any);
          return fp as any;
        },
        fallbackPermissionSet: this.fallbackPermissionSet,
        // ── record-grained deps (only consulted when recordId is present) ──
        computeLayeredRlsFilter: (sets, o, engineOp, c) => this.computeLayeredRlsFilter(sets as any, o, engineOp, c),
        fetchRecord: async (o: string, rid: string) => {
          try {
            const finder = this.ql?.findOne
              ? this.ql.findOne(o, { where: { id: rid }, context: { isSystem: true } })
              : this.ql?.find?.(o, { where: { id: rid }, limit: 1, context: { isSystem: true } });
            const res = await finder;
            const row = Array.isArray(res) ? res[0] : res;
            return row ?? null;
          } catch {
            return null;
          }
        },
        ...(sharing && typeof sharing.buildReadFilter === 'function'
          ? { sharingReadFilter: (o: string, c: any) => sharing.buildReadFilter(o, c) }
          : {}),
        ...(sharing && typeof sharing.listShares === 'function'
          ? { listRecordShares: (o: string, rid: string, c: any) => sharing.listShares(o, rid, c) }
          : {}),
        ...(sharing && typeof sharing.canEdit === 'function'
          ? { canEditRecord: (o: string, rid: string, c: any) => sharing.canEdit(o, rid, c) }
          : {}),
      },
      { object, operation, context: targetContext, recordId },
    );
  }

  async getReadFilter(
    object: string,
    context?: any,
  ): Promise<Record<string, unknown> | undefined> {
    // System operations bypass scoping (mirrors the middleware's isSystem skip).
    if (context?.isSystem) return undefined;
    const positions = context?.positions ?? [];
    const explicit = context?.permissions ?? [];
    // Unauthenticated + position-less + permission-less → no scope (the auth
    // layer, not RLS, gates anonymous access; the analytics REST endpoint
    // already 401s without a token). Mirrors the middleware's early `return next()`.
    if (positions.length === 0 && explicit.length === 0 && !context?.userId) {
      return undefined;
    }
    // [#2852] D10 delegator intersection is NOT implemented on this path.
    // The engine middleware (find/count/aggregate) intersects an on-behalf-of
    // read with the DELEGATOR's own RLS (resolveDelegatorContext, ~L689), but
    // getReadFilter — the read-scope provider bound by the analytics/raw-SQL
    // path — resolves only the CALLER's ceiling. Computing a filter here for a
    // delegated (agent) context would therefore SILENTLY WIDEN the read past
    // the delegator's scope (the confused-deputy widening D10 prevents on the
    // CRUD path). Until the intersection is threaded through computeRlsFilter
    // (tracked with #2920 B1 / ADR-0095 D1), FAIL CLOSED: a delegated read on
    // this path denies rather than under-scopes. System on-behalf-of already
    // returned above; today no agent surface reaches analytics, so this is a
    // latent-invariant guard, not a live-traffic change.
    if (context?.onBehalfOf?.userId) {
      this.logger.error?.(
        `[security] getReadFilter received an on-behalf-of context for object ` +
          `'${object}' (agent ${context?.userId ?? 'unknown'} on behalf of ` +
          `${context.onBehalfOf.userId}) — the D10 delegator intersection is not ` +
          `implemented on the read-scope path; denying (fail-closed, #2852)`,
      );
      return { ...RLS_DENY_FILTER };
    }
    try {
      const permissionSets = await this.resolvePermissionSetsForContext(context);
      const filter = await this.computeRlsFilter(permissionSets, object, 'find', context);
      return filter ?? undefined;
    } catch (e) {
      // Fail CLOSED — a resolution failure must deny (zero rows), never expose
      // every tenant's data through the raw-SQL analytics path.
      this.logger.error?.(
        `[security] getReadFilter failed for object '${object}' ` +
          `(user ${context?.userId ?? 'unknown'}) — denying (fail-closed)`,
        e instanceof Error ? e : new Error(String(e)),
      );
      return { ...RLS_DENY_FILTER };
    }
  }

  /**
   * [#3547] Query surface: the field names the caller MAY READ on `object`
   * under `context`. This is the authoritative column projection for a
   * read-derived export (`export ⊆ list`, #3391) — the REST export route
   * consumes it to project columns directly, instead of inferring readability
   * from already-masked data rows (which loses an all-readable-but-all-null
   * column and falls back to the full schema on an empty result set, #3498).
   *
   * Same-source-as-read-middleware, so it can never drift from data-plane FLS:
   * it resolves the caller's permission sets via
   * {@link resolvePermissionSetsForContext}, builds the field-permission map
   * with the SAME evaluator + `requiredPermissions` fold the read mask uses,
   * intersects the on-behalf-of delegator's mask (ADR-0090 D10, fail-closed on
   * a dangling delegator), then returns every schema field NOT marked
   * non-readable — the exact complement of what {@link FieldMasker.maskResults}
   * deletes (fields without an explicit permission entry pass through).
   *
   * Returns `undefined` when the object schema can't be resolved, so the caller
   * falls back to its own projection. A system context (`context.isSystem`)
   * bypasses FLS and returns the full field set, mirroring the middleware's
   * `isSystem` skip.
   */
  async getReadableFields(object: string, context?: any): Promise<string[] | undefined> {
    const objectName = String(object ?? '');
    if (!objectName) return undefined;
    // The field universe — the SAME source the RLS field pass uses (ObjectQL's
    // live SchemaRegistry first, metadata artifact fallback). `null` → schema
    // not resolvable → let the caller fall back rather than guess.
    const fieldNameSet = await this.getObjectFieldNames(this.metadata, objectName, this.ql);
    if (!fieldNameSet) return undefined;
    const allFields = [...fieldNameSet];
    // System operations bypass FLS (mirrors the middleware's isSystem skip).
    if (context?.isSystem) return allFields;

    const permissionSets = await this.resolvePermissionSetsForContext(context);
    // No sets resolved (e.g. unauthenticated) → no field mask applies, exactly
    // as the middleware (getFieldPermissions([]) === {} → nothing deleted).
    if (permissionSets.length === 0) return allFields;

    const secMeta = await this.getObjectSecurityMeta(objectName);
    let fieldPerms = this.permissionEvaluator.getFieldPermissions(objectName, permissionSets);
    fieldPerms = this.foldFieldRequiredPermissions(fieldPerms, secMeta.fieldRequiredPermissions, permissionSets);

    // [ADR-0090 D10] On an on-behalf-of read the readable set must NOT widen
    // past what the DELEGATOR can read — intersect the delegator's field mask
    // too. A dangling delegator fails CLOSED (expose no columns), the same
    // fail-closed stance the CRUD middleware takes on a 'missing' delegator.
    if (context?.onBehalfOf?.userId) {
      const del = await resolveDelegatorContext(this.ql, context);
      if (del.kind === 'missing') return [];
      if (del.kind === 'resolved') {
        const delegatorSets = await this.resolvePermissionSetsForContext(del.context);
        let delFieldPerms = this.permissionEvaluator.getFieldPermissions(objectName, delegatorSets);
        delFieldPerms = this.foldFieldRequiredPermissions(delFieldPerms, secMeta.fieldRequiredPermissions, delegatorSets);
        fieldPerms = intersectFieldMasks(fieldPerms, delFieldPerms);
      }
    }

    // Readable = every schema field NOT explicitly masked non-readable. A field
    // with no permission entry passes through (the field allow-list only
    // enumerates fields it names) — the exact complement of maskResults' delete
    // set, so the export header matches list's readable columns by construction.
    return allFields.filter((f) => fieldPerms[f]?.readable !== false);
  }

  /**
   * Resolve the effective permission sets for an execution context — positions +
   * explicit permission sets, with the configured baseline applied both as an
   * implicit request (when none were named) and as a post-resolution fallback
   * (when named ones resolved to nothing). Shared by the engine middleware and
   * {@link getReadFilter} so both enforce identical RLS. May throw if the
   * underlying metadata/db resolution fails (callers fail-closed).
   */
  private async resolvePermissionSetsForContext(
    context: any,
  ): Promise<PermissionSet[]> {
    const positions = context?.positions ?? [];
    const explicitPermissionSets = context?.permissions ?? [];
    const requested = [...positions, ...explicitPermissionSets];
    // [ADR-0090 D10] An AGENT principal's grants are EXACTLY its scope-derived
    // ceiling set(s) — the additive human baseline (member_default) must NOT
    // apply, or its write bit would silently widen a read-only agent past the
    // scope the user consented to. The agent's floor is instead the restricted
    // (no-object-access) set, so an agent whose sets fail to resolve fails
    // CLOSED (every object op denied) rather than falling open. The delegating
    // user's own baseline still applies on the OTHER side of the intersection
    // (resolved from `onBehalfOf` via a context without this flag).
    const isAgent = context?.principalKind === 'agent';
    const baseline = isAgent ? MCP_AGENT_PERMISSION_SET_RESTRICTED : this.fallbackPermissionSet;
    // [ADR-0090 D5] Baseline is ADDITIVE, always (for humans): the configured
    // baseline set applies to every authenticated request IN ADDITION to
    // whatever else resolved. The former "only when the user has nothing else"
    // conditional was the fallback CLIFF — receiving your first explicit grant
    // silently cost you the entire baseline. Agents skip this additive step
    // (their ceiling is closed, not floored) — see above.
    if (!isAgent && context?.userId && baseline && !requested.includes(baseline)) {
      requested.push(baseline);
    }
    let permissionSets = await this.permissionEvaluator.resolvePermissionSets(
      requested,
      this.metadata,
      this.bootstrapPermissionSets,
      this.dbLoader,
      { logger: this.logger },
    );
    // Post-resolution fallback — closes the fail-open hole where a populated
    // `positions` array maps to no permission set yet (no sys_position binding),
    // which would otherwise skip RLS entirely and expose every tenant's data.
    // For an agent, the fallback is the restricted set (deny all objects), NOT
    // the human baseline — a mis-resolved agent must never inherit member access.
    if (
      permissionSets.length === 0 &&
      context?.userId &&
      baseline
    ) {
      permissionSets = await this.permissionEvaluator.resolvePermissionSets(
        [baseline],
        this.metadata,
        this.bootstrapPermissionSets,
        this.dbLoader,
        { logger: this.logger },
      );
    }
    return permissionSets;
  }

  /**
   * Resolve a single scalar primary-key id from an update/delete operation
   * context, mirroring the engine's "single-id vs predicate" rule
   * (`engine.ts` update/delete): only a scalar `data.id` or `where.id`
   * identifies one row. An operator object (`{ $in: [...] }`, …) is a
   * multi-row predicate and returns `null` (multi-row writes route through the
   * `*Many` paths, out of scope for the by-id pre-image check).
   */
  /**
   * [ADR-0086 P2 — 块2, evolved by ADR-0094] Two-doors data-layer gate for
   * `sys_permission_set`.
   *
   * A row with `managed_by:'package'` is owned by the package door (its
   * baseline is authored in the package, materialized on publish). This gate
   * refuses (a) FORGING that provenance through the admin door — insert or
   * update, single object or array — and (b) the lifecycle ops with no
   * overlay translation (`transfer`/`restore`/`purge`) on package rows.
   * Ordinary `update`/`delete` pass through: the ADR-0094 write-through
   * downstream translates them into env-scope overlay operations (customize /
   * reset), and re-asserts the refusal itself when the kernel has no metadata
   * overlay layer. Fails CLOSED and never depends on the caller's grants, so
   * a platform admin with `modifyAllRecords` cannot forge provenance either.
   * System/boot writes never reach here (the middleware short-circuits on
   * `isSystem`), so the seeder and the publish materializer are unaffected.
   */
  /**
   * [ADR-0090 D5/D9] Reject binding a HIGH-PRIVILEGE permission set to an
   * audience anchor (`everyone` / `guest`). The anchors are implicit for
   * whole principal classes, so a dangerous binding here is an instant
   * tenant-wide (or anonymous-wide) grant — the one shape the model must
   * make unrepresentable rather than merely discouraged.
   */
  private async assertAudienceAnchorBindingGate(opCtx: any): Promise<void> {
    if (opCtx?.object !== 'sys_position_permission_set') return;
    if (!['insert', 'update'].includes(opCtx.operation)) return;
    const rows = Array.isArray(opCtx.data)
      ? opCtx.data
      : (opCtx.data && typeof opCtx.data === 'object' ? [opCtx.data] : []);
    if (rows.length === 0) return;

    const ql = this.ql;
    for (const row of rows) {
      const positionId = (row as any)?.position_id;
      if (!positionId || !ql?.find) continue;
      let positionName = '';
      try {
        const posRows = await ql.find('sys_position', { where: { id: positionId }, limit: 1, context: { isSystem: true } });
        positionName = String((Array.isArray(posRows) && posRows[0] ? (posRows[0] as any).name : '') ?? '');
      } catch { positionName = ''; }
      if (positionName !== 'everyone' && positionName !== 'guest') continue;

      // Resolve the target set definition (bootstrap sets by name, else the
      // sys_permission_set row itself carries the authored definition).
      const setId = (row as any)?.permission_set_id;
      let setName = '';
      let setDef: any = null;
      try {
        const setRows = await ql.find('sys_permission_set', { where: { id: setId }, limit: 1, context: { isSystem: true } });
        const sr: any = Array.isArray(setRows) && setRows[0] ? setRows[0] : null;
        if (sr) {
          setName = String(sr.name ?? '');
          setDef = sr;
        }
      } catch { /* fall through to bootstrap lookup below */ }
      const boot = this.bootstrapPermissionSets.find((p) => p.name === setName);
      // [ADR-0090 D9] Anchor-tier predicate: `guest` faces the strictest tier
      // (additionally no edit bit — read-only by default, create is the single
      // case-by-case write); `everyone` uses the high-privilege predicate.
      const offending = describeAnchorForbiddenBits(boot ?? setDef, positionName as 'everyone' | 'guest');
      if (offending) {
        throw new PermissionDeniedError(
          `[Security] Access denied: permission set '${setName || setId}' cannot be bound to the '${positionName}' audience anchor — it carries ${offending} (ADR-0090 D5/D9). ` +
            `Audience anchors accept low-privilege sets only; grant powerful sets through ordinary positions instead.`,
          { operation: opCtx.operation, object: opCtx.object, position: positionName, permissionSet: setName || setId },
        );
      }
    }
  }

  private async assertPackageManagedWriteGate(opCtx: any): Promise<void> {
    if (opCtx?.object !== 'sys_permission_set') return;
    const op = opCtx.operation;
    if (!['insert', 'update', 'delete', 'transfer', 'restore', 'purge'].includes(op)) return;

    // (a) Reject any admin-door PAYLOAD that CLAIMS package provenance
    //     (`managed_by:'package'`), on insert OR update, single object OR array
    //     (`engine.insert`/`update` both accept `T | T[]` and route arrays
    //     through this same middleware). Only the package publish path — which
    //     carries `isSystem` and short-circuited the whole middleware above —
    //     may stamp package provenance. This also closes update-to-forge: an
    //     env row cannot be re-badged package-managed through the admin door.
    const payloadRows = Array.isArray(opCtx.data)
      ? opCtx.data
      : (opCtx.data && typeof opCtx.data === 'object' ? [opCtx.data] : []);
    if (payloadRows.some((r: unknown) => r && typeof r === 'object' && (r as Record<string, unknown>).managed_by === 'package')) {
      throw new PermissionDeniedError(
        `[Security] Access denied: cannot set 'managed_by:package' on a permission set through the admin door — ` +
          `package permission sets are authored in their package and land via publish (ADR-0086 two-doors).`,
        { operation: op, object: opCtx.object },
      );
    }
    if (op === 'insert') return; // no existing row to protect

    // [ADR-0094, direction confirmed 2026-07-14] `update`/`delete` on a
    // package-managed row are no longer refused here: the write-through
    // middleware (which runs after this gate + the delegated-admin gate +
    // the CRUD checks) translates them into env-scope OVERLAY operations —
    // customize / reset via the standard ADR-0005 layering — and itself
    // re-asserts the legacy refusal when the kernel has no metadata overlay
    // layer to carry the customization. The lifecycle ops below have no
    // overlay translation, so the package-row protection stays for them.
    if (op === 'update' || op === 'delete') return;

    if (!this.ql) return;

    const targetId = this.extractSingleId(opCtx);
    if (targetId == null) {
      // Multi-row / filter write with no single id. Deny ONLY if a package-owned
      // row actually falls within the write's own filter — so a bulk edit that
      // targets only env-authored rows still succeeds (no over-broad block). A
      // whole-table write (no filter) matches every package row, so it is denied.
      const writeWhere = opCtx?.options?.where;
      const packageWhere = writeWhere && typeof writeWhere === 'object'
        ? { $and: [writeWhere, { managed_by: 'package' }] }
        : { managed_by: 'package' };
      const hitsPackageRow = await this.ql
        .findOne('sys_permission_set', { where: packageWhere, context: { isSystem: true } })
        .catch(() => null);
      if (hitsPackageRow) {
        throw new PermissionDeniedError(
          `[Security] Access denied: this '${op}' on 'sys_permission_set' targets one or more package-managed ` +
            `rows — change those by editing their package and re-publishing, not through the admin door ` +
            `(ADR-0086 two-doors separation).`,
          { operation: op, object: opCtx.object },
        );
      }
      return;
    }

    const existing = await this.readRowById('sys_permission_set', targetId, { isSystem: true });
    if (existing && (existing as Record<string, unknown>).managed_by === 'package') {
      const row = existing as Record<string, unknown>;
      throw new PermissionDeniedError(
        `[Security] Access denied: '${String(row.name ?? targetId)}' is a package-managed permission set ` +
          `(managed_by:'package') — change it by editing its package and re-publishing, not through the ` +
          `admin door (ADR-0086 two-doors separation).`,
        {
          operation: op,
          object: opCtx.object,
          recordId: targetId,
          packageId: (row.package_id as string | null) ?? null,
        },
      );
    }
  }

  /**
   * [ADR-0066 / #2918] Built-in row-write guardrail for the platform/application
   * ASSET objects `sys_position` and `sys_capability`.
   *
   * ADR-0066's asset-ownership model splits authoring from assignment: WHAT a
   * position or capability *is* is defined by the platform or an application
   * package developer; a customer admin only decides WHO it is assigned to (via
   * the RBAC link tables, which are governed separately by the delegated-admin
   * gate). The `managed_by` provenance column on each object already records
   * that ownership, but until now nothing ENFORCED it at the data layer — an
   * admin could delete or rewrite a platform/package-managed row and silently
   * break that app's authorization baseline (ADR-0049: a provenance attribute
   * that exists but is never enforced is exactly the gap to close).
   *
   * This gate is an unconditional data-layer boundary, mirroring the
   * `sys_permission_set` two-doors gate above:
   *   (a) The admin door may never FORGE managed provenance — stamping
   *       `managed_by` to a platform/package value on insert OR update (single
   *       object OR array) is refused; only the platform seeder / package
   *       publish path (which carries `isSystem` and short-circuited the whole
   *       middleware above) may author it. This also closes update-to-forge.
   *   (b) delete / update / transfer / restore / purge on a row whose EXISTING
   *       `managed_by` is platform/package-owned are refused — unlike
   *       `sys_permission_set`, these objects have NO ADR-0094 overlay
   *       write-through, so the mutation would otherwise go straight to the
   *       driver.
   *   (c) admin-authored rows (`managed_by` user/∅/admin) are untouched — the
   *       admin fully owns those (incl. a delegate's rows in their own subtree).
   * Fails CLOSED and never depends on the caller's grants, so a superuser with
   * modifyAllRecords cannot delete a platform position either.
   */
  private async assertSystemRowWriteGate(opCtx: any): Promise<void> {
    const spec = SYSTEM_ROW_PROVENANCE[opCtx?.object as string];
    if (!spec) return;
    const op = opCtx.operation;
    if (!['insert', 'update', 'delete', 'transfer', 'restore', 'purge'].includes(op)) return;

    const managedValues = Object.keys(spec.managed);

    // (a) Reject any admin-door PAYLOAD that CLAIMS platform/package provenance,
    //     on insert OR update, single object OR array. Only the seeder / publish
    //     path (which carries `isSystem` and short-circuited above) may stamp it.
    const payloadRows = Array.isArray(opCtx.data)
      ? opCtx.data
      : (opCtx.data && typeof opCtx.data === 'object' ? [opCtx.data] : []);
    if (
      payloadRows.some(
        (r: unknown) =>
          r &&
          typeof r === 'object' &&
          managedValues.includes(String((r as Record<string, unknown>).managed_by ?? '')),
      )
    ) {
      throw new PermissionDeniedError(
        `[Security] Access denied: cannot stamp a platform/package 'managed_by' value on a ${spec.noun} ` +
          `through the admin door — ${spec.pluralNoun} provided by the platform or an application package are ` +
          `authored there and land via seeding/publish, not through Setup (ADR-0066 asset ownership).`,
        { operation: op, object: opCtx.object },
      );
    }
    if (op === 'insert') return; // no existing row to protect

    if (!this.ql) return;

    const targetId = this.extractSingleId(opCtx);
    if (targetId == null) {
      // Multi-row / filter write with no single id. Deny ONLY if a managed row
      // actually falls within the write's own filter — so a bulk edit that
      // targets only admin-authored rows still succeeds (no over-broad block). A
      // whole-table write (no filter) matches every managed row, so it is denied.
      const writeWhere = opCtx?.options?.where;
      const managedWhere =
        writeWhere && typeof writeWhere === 'object'
          ? { $and: [writeWhere, { managed_by: { $in: managedValues } }] }
          : { managed_by: { $in: managedValues } };
      const hitsManagedRow = await this.ql
        .findOne(opCtx.object, { where: managedWhere, context: { isSystem: true } })
        .catch(() => null);
      if (hitsManagedRow) {
        throw new PermissionDeniedError(
          `[Security] Access denied: this '${op}' on '${opCtx.object}' targets one or more ${spec.pluralNoun} ` +
            `provided by the platform or an application package — those cannot be deleted or modified through ` +
            `the admin door (ADR-0066 asset ownership).`,
          { operation: op, object: opCtx.object },
        );
      }
      return;
    }

    const existing = await this.readRowById(opCtx.object, targetId, { isSystem: true });
    const existingManagedBy = existing
      ? String((existing as Record<string, unknown>).managed_by ?? '')
      : '';
    const ownerLabel = spec.managed[existingManagedBy];
    if (existing && ownerLabel) {
      const row = existing as Record<string, unknown>;
      const source = ownerLabel === 'the platform' ? 'platform definition' : 'application package';
      throw new PermissionDeniedError(
        `[Security] Access denied: '${String(row.name ?? row.label ?? targetId)}' is a ${spec.noun} provided ` +
          `by ${ownerLabel} — it cannot be deleted or modified through the admin door. Change it by editing ` +
          `its ${source} and re-publishing (ADR-0066 asset ownership).`,
        { operation: op, object: opCtx.object, recordId: targetId, managedBy: existingManagedBy },
      );
    }
  }

  private extractSingleId(opCtx: any): string | number | bigint | null {
    const isScalar = (v: unknown): v is string | number | bigint =>
      v !== null && (typeof v === 'string' || typeof v === 'number' || typeof v === 'bigint');
    const data = opCtx?.data;
    if (data && typeof data === 'object' && !Array.isArray(data) && isScalar(data.id)) {
      return data.id;
    }
    const where = opCtx?.options?.where;
    if (where && typeof where === 'object' && 'id' in where && isScalar((where as any).id)) {
      return (where as any).id;
    }
    return null;
  }

  /**
   * By-id row read with the standard FAIL-CLOSED contract (missing engine,
   * null id, or a thrown read → `null`), shared by every provenance / pre-image
   * gate. Centralising the read SHAPE keeps a future change (soft-delete filter,
   * field projection) from drifting across the ~5 call sites that used to
   * inline it (#3018 review — Reuse). A `null` return always DENIES downstream;
   * it never bypasses a gate.
   */
  private async readRowById(object: string, id: unknown, context: any): Promise<Record<string, unknown> | null> {
    if (id == null || typeof this.ql?.findOne !== 'function') return null;
    try {
      const row = await this.ql.findOne(object, { where: { id }, context });
      return row && typeof row === 'object' ? (row as Record<string, unknown>) : null;
    } catch {
      return null;
    }
  }

  /**
   * The single-id write PRE-IMAGE read under the CALLER's context, memoized per
   * operation. The owner-anchor echo check (step 3.5) and the RLS `check`
   * post-image (step 3.6) read the IDENTICAL `(object, id, caller-context)` row;
   * this collapses the two reads into one. Safe: no write to the row happens
   * between the gates (the driver write runs after the whole middleware pass),
   * so the pre-image is stable within the operation.
   */
  private async getCallerPreImage(opCtx: any, id: unknown): Promise<Record<string, unknown> | null> {
    if (id == null) return null;
    if (opCtx.__preImage && opCtx.__preImage.id === id) return opCtx.__preImage.row;
    const row = await this.readRowById(opCtx.object, id, opCtx.context);
    opCtx.__preImage = { id, row };
    return row;
  }

  /**
   * [ADR-0095 D1] Compute the effective row filter for (object, operation) as
   * `Layer0(tenant) AND Layer1(business RLS)`.
   *
   * - **Layer 0** (tenant isolation) is computed by {@link computeTenantLayer0Filter}
   *   from the tenancy mode + the object's field set/posture — independent of the
   *   RLS compiler, always first, unconditionally AND-composed.
   * - **Layer 1** (business RLS) is the applicable per-policy compile (ownership,
   *   depth, sharing, `_self` carve-outs), with the field-existence safety net and
   *   the posture-gated superuser bypass — which now governs BUSINESS RLS only.
   *
   * Shared by the engine middleware (read + by-id write pre-image) and
   * {@link getReadFilter}. Returns `null` when neither layer contributes.
   */
  private async computeRlsFilter(
    permissionSets: PermissionSet[],
    object: string,
    operation: string,
    context: any,
  ): Promise<Record<string, unknown> | null> {
    const { layer0, layer1 } = await this.computeLayeredRlsFilter(permissionSets, object, operation, context);
    return andComposeLayers(layer0, layer1);
  }

  /**
   * [C2 / ADR-0095 D1] The layered RLS split — `{ layer0, layer1 }` BEFORE the
   * AND-compose. `computeRlsFilter` is the thin wrapper that composes them; the
   * explain engine consumes the split directly so it can attribute the tenant
   * wall (Layer 0) and business RLS (Layer 1) to a record SEPARATELY. Single code
   * path → the record story cannot drift from the effective filter enforcement uses.
   */
  /**
   * [Finding 2 / ADR-0095 D3] Does the caller resolve to the `PLATFORM_ADMIN`
   * posture rung? True iff the resolved permission sets grant any
   * platform-EXCLUSIVE capability ({@link PLATFORM_ADMIN_ONLY_CAPABILITIES}) — the
   * caps `admin_full_access` carries and `organization_admin` deliberately
   * withholds. This is what separates a platform operator from a tenant org admin
   * (both hold the `viewAllRecords`/`modifyAllRecords` superuser bit), and it is
   * the ONLY signal permitted to cross the Layer 0 tenant wall.
   */
  private hasPlatformAdminPosture(permissionSets: PermissionSet[]): boolean {
    return hasPlatformAdminCapability(this.permissionEvaluator.getSystemPermissions(permissionSets));
  }

  private async computeLayeredRlsFilter(
    permissionSets: PermissionSet[],
    object: string,
    operation: string,
    context: any,
  ): Promise<{ layer0: Record<string, unknown> | null; layer1: Record<string, unknown> | null }> {
    // [ADR-0095 D1] Effective filter = Layer0(tenant) AND Layer1(business RLS).
    // The two are computed independently and never share a compiler, a merge
    // step, or a bypass bit (closes W1 by construction, W2 structurally).
    const meta = await this.getObjectSecurityMeta(object);
    const isWrite = operation === 'insert' || operation === 'update' || operation === 'delete';
    // Posture permits a platform admin to cross the tenant wall (ADR-0066 ①):
    // private / platform-global / better-auth-managed objects. Public tenant
    // business objects do NOT permit it, so a platform admin stays org-scoped.
    const posturePermits = meta.isPrivate || meta.tenancyDisabled || meta.isBetterAuthManaged;
    // The superuser bit (`viewAllRecords`/`modifyAllRecords`) governs the BUSINESS
    // RLS (Layer 1) short-circuit below — a TENANT_ADMIN legitimately sees every
    // row WITHIN its org, no ownership/depth/sharing narrowing (ADR-0095 D2).
    const superuserBypass = posturePermits
      ? (isWrite
          ? this.permissionEvaluator.hasSuperuserWriteBypass(object, permissionSets, { isPrivate: meta.isPrivate })
          : this.permissionEvaluator.hasSuperuserReadBypass(object, permissionSets, { isPrivate: meta.isPrivate }))
      : false;
    // [Finding 2 / #2937 / ADR-0099 D1 (P1)] The Layer 0 cross-tenant EXEMPTION
    // is stricter than the superuser bit: it requires a TRUE PLATFORM_ADMIN, so a
    // tenant `organization_admin` (which also holds the superuser bit via its `'*'`
    // wildcard) stays org-scoped even on private objects (invariant I1). The tier
    // signal is the CARRIED rung when the context passed the resolver (#2956); the
    // capability probe is the fallback for hand-built contexts that carry no rung.
    // Both are computed so a disagreement (only possible on the fallback-eligible
    // divergence class — scoped `admin_full_access` / piecemeal platform caps) is
    // logged as a defect (ADR-0099 I4) and the NARROWER rung verdict is enforced.
    const carriedPosture = context?.posture;
    const probePlatformAdmin = this.hasPlatformAdminPosture(permissionSets);
    let platformPosture: boolean;
    if (isCarriedPosture(carriedPosture)) {
      platformPosture = carriedPosture === 'PLATFORM_ADMIN';
      if (platformPosture !== probePlatformAdmin) {
        // rung ⊆ probe (I3), so this only fires as probe=true / rung≠PLATFORM_ADMIN
        // — the adjudicated narrowing (#3211 G1). A breadcrumb, never a throw.
        this.logger.warn?.(
          '[authz/ADR-0099] Layer 0 exemption: carried posture rung and capability probe disagree; ' +
            'enforcing the (narrower) carried rung',
          { object, operation, carriedPosture, probePlatformAdmin, userId: context?.userId },
        );
      }
    } else {
      platformPosture = probePlatformAdmin;
    }
    const isPlatformAdmin = superuserBypass && platformPosture;

    // Field set drives BOTH the Layer 1 field-existence net and the Layer 0
    // "is this a tenant object?" check.
    const objectFields = await this.getObjectFieldNames(this.metadata, object, this.ql);
    const tenancyDisabled = this.tenancyDisabledCache.get(object) === true || meta.tenancyDisabled;

    // [ADR-0105 D11] Stage app-resolved membership sets before Layer 1 compiles,
    // so `field IN (current_user.<key>)` predicates can resolve. Lazy (only when
    // a resolver is registered) and memoized per request — resolution is I/O and
    // the same context is reused across every object touched by one request.
    await this.stageRlsMembership(context);

    // ── Layer 1: business RLS (ownership / unit depth / sharing / _self carve-outs).
    // The wildcard tenant policy has LEFT this layer (retired from the seeds), so
    // this superuser short-circuit now governs BUSINESS RLS only — it can no
    // longer skip the tenant wall (that is Layer 0's own exemption, below).
    let layer1: Record<string, unknown> | null = null;
    if (!(posturePermits && superuserBypass)) {
      const allRlsPolicies = this.collectRLSPolicies(permissionSets, object, operation, (context?.positions ?? []) as string[]);
      if (allRlsPolicies.length > 0) {
        // Field-existence safety: a wildcard policy targeting a column the object
        // lacks is a *deny* contribution (fail-closed), unless the object opted
        // out of tenancy (skip). Schema-lookup failure keeps all policies.
        let dropped = 0;
        const compilable = objectFields
          ? allRlsPolicies.filter((p) => {
              const targetField = this.extractTargetField(p.using);
              if (!targetField) return true;
              if (objectFields.has(targetField)) return true;
              if (tenancyDisabled && targetField === 'organization_id') {
                return false;
              }
              dropped++;
              return false;
            })
          : allRlsPolicies;
        layer1 = this.rlsCompiler.compileFilter(compilable, context);
        // Every applicable policy dropped for a missing field → deny sentinel.
        if (layer1 == null && dropped > 0) {
          layer1 = { ...RLS_DENY_FILTER };
        }
      }
    }

    // ── Layer 0: tenant isolation — independent, always-first, AND-composed.
    // Decides "tenant object?" directly from the field set + tenancy posture (NOT
    // via extractTargetField's `=`-only shape match), so a `tenancy.enabled:false`
    // global object correctly contributes nothing (ADR-0095 delta c).
    const layer0 = computeTenantLayer0Filter({
      tenancyPosture: this.tenancyPosture,
      organizationId: context?.tenantId,
      // [ADR-0105 D2] The `group` wall's predicate. Resolved by
      // `resolveAuthzContext` and carried on the context — never re-derived here.
      accessibleOrgIds: context?.accessible_org_ids,
      objectHasOrgIdField: objectFields ? objectFields.has('organization_id') : undefined,
      tenancyDisabled,
      posturePermitsCrossTenant: posturePermits,
      isPlatformAdmin,
    });

    return { layer0, layer1 };
  }

  /**
   * [ADR-0058 D4] Compile the WRITE `check` predicate for a post-image
   * validation. Scoped to applicable policies that EXPLICITLY declare a `check`
   * clause — an object governed only by `using` (the pre-image path) yields no
   * check filter and is unaffected. The compiled FilterCondition is matched
   * against the post-image record by the caller (fail closed).
   */
  private async computeWriteCheckFilter(
    permissionSets: PermissionSet[],
    object: string,
    operation: string,
    context: any,
  ): Promise<Record<string, unknown> | null> {
    // [ADR-0066 ①] modifyAllRecords bypasses write-side RLS (incl. the post-image
    // check) on private/platform-global objects.
    const meta = await this.getObjectSecurityMeta(object);
    if (
      (meta.isPrivate || meta.tenancyDisabled || meta.isBetterAuthManaged) &&
      this.permissionEvaluator.hasSuperuserWriteBypass(object, permissionSets, { isPrivate: meta.isPrivate })
    ) {
      return null;
    }
    const withCheck = this.collectRLSPolicies(permissionSets, object, operation).filter(
      (p) => typeof (p as { check?: string }).check === 'string' && (p as { check?: string }).check!.trim() !== '',
    );
    if (withCheck.length === 0) return null;
    return this.rlsCompiler.compileFilter(withCheck, context, 'check');
  }

  /**
   * [ADR-0095 D1 / #2937] Compute the Layer 0 (tenant) filter that a WRITE
   * post-image must satisfy — the write-side twin of the read Layer 0 wall,
   * applied to both INSERT (Finding: forged `organization_id`) and UPDATE
   * (Finding 1: `organization_id` RE-POINTED to another tenant). Reuses
   * {@link computeLayeredRlsFilter} so the tenant decision is DERIVED FROM ONE
   * PLACE and can never drift from the read side: same isolation probe, same
   * "is this a tenant object?" field/posture test, same platform-admin posture
   * exemption, same fail-closed deny sentinel when the context has no active
   * organization. Only `layer0` is returned — business RLS (`layer1`) is NOT
   * applied to the write post-image (that path is governed by explicit `check`
   * clauses via {@link computeWriteCheckFilter}).
   */
  /**
   * [ADR-0105 D11] Populate `context.rlsMembership` from the registered
   * membership resolver, once per request.
   *
   * The RLS compiler has merged this bag since ADR-0056, but nothing in
   * production ever filled it — a declared capability with no producer, the
   * ADR-0049 defect. This is the producer: apps and plugins register an
   * {@link IRlsMembershipResolver} under `rls-membership-resolver` and own the
   * keys they declare.
   *
   * Fail-closed by construction: a throwing or partial resolver leaves keys
   * unset, which makes the policies referencing them drop out — narrowing
   * access, never widening it. Reserved kernel keys can never be overwritten,
   * so an app cannot redefine the org wall's own vocabulary.
   */
  private async stageRlsMembership(context: any): Promise<void> {
    if (!this.rlsMembershipResolver || !context || typeof context !== 'object') return;
    // One resolution per request: the same context object is threaded through
    // every object the operation touches.
    if (context.__rlsMembershipStaged) return;
    context.__rlsMembershipStaged = true;

    let resolved: Record<string, string[]> = {};
    try {
      resolved = (await this.rlsMembershipResolver.resolve({
        userId: context.userId,
        tenantId: context.tenantId,
        accessible_org_ids: context.accessible_org_ids,
        positions: context.positions,
        permissions: context.permissions,
      })) ?? {};
    } catch (e) {
      this.logger.warn?.(
        '[security/ADR-0105] rls-membership-resolver threw — its keys stay unresolved and the ' +
          'policies referencing them will fail closed',
        { error: (e as Error)?.message },
      );
      return;
    }

    const bag: Record<string, string[]> = { ...(context.rlsMembership ?? {}) };
    for (const [key, value] of Object.entries(resolved)) {
      if (RESERVED_RLS_MEMBERSHIP_KEYS.includes(key)) {
        this.logger.warn?.(
          '[security/ADR-0105] rls-membership-resolver tried to supply a RESERVED context key — ignored',
          { key },
        );
        continue;
      }
      if (!Array.isArray(value)) continue;
      // An already-staged key wins: a caller-supplied bag is closer to the
      // request than a generic resolver.
      if (bag[key] === undefined) bag[key] = value.filter((v) => typeof v === 'string');
    }
    if (Object.keys(bag).length > 0) context.rlsMembership = bag;
  }

  private async computeWriteTenantCheckFilter(
    permissionSets: PermissionSet[],
    object: string,
    operation: string,
    context: any,
  ): Promise<Record<string, unknown> | null> {
    const { layer0 } = await this.computeLayeredRlsFilter(permissionSets, object, operation, context);
    return layer0;
  }

  /**
   * Resolve a controlled_by_parent object's master-detail relation (the FK field
   * key + the master object name), or null. Prefers a required `master_detail`
   * field; falls back to any `master_detail`, then a required `lookup`. Cached.
   */
  private resolveCbpRelation(object: string): { fk: string; master: string } | null {
    if (this.cbpRelCache.has(object)) return this.cbpRelCache.get(object) ?? null;
    let rel: { fk: string; master: string } | null = null;
    const schema = typeof this.ql?.getSchema === 'function' ? this.ql.getSchema(object) : null;
    const fields = schema?.fields;
    const entries: Array<[string, any]> = Array.isArray(fields)
      ? fields.map((f: any) => [f?.name, f] as [string, any])
      : fields && typeof fields === 'object'
        ? (Object.entries(fields) as Array<[string, any]>)
        : [];
    const ref = (f: any) => f?.reference ?? f?.reference_to ?? f?.referenceTo;
    const pick = (pred: (f: any) => boolean) => entries.find(([, f]) => pred(f) && ref(f));
    const found =
      pick((f) => f?.type === 'master_detail' && f?.required) ??
      pick((f) => f?.type === 'master_detail') ??
      pick((f) => f?.type === 'lookup' && f?.required);
    if (found) rel = { fk: String(found[0]), master: String(ref(found[1])) };
    this.cbpRelCache.set(object, rel);
    return rel;
  }

  /**
   * ADR-0055 — master-detail "controlled by parent" READ derivation.
   *
   * For an object whose `sharingModel` is `controlled_by_parent`, access is
   * derived from the master: return a filter `masterFK IN (<master ids this user
   * can read>)`. The id set is resolved by running the MASTER's own read RLS
   * (reused via `computeRlsFilter`) under a system context — no middleware
   * re-entry, so no recursion. An empty set yields `{ masterFK: { $in: [] } }`,
   * which matches no rows (fail closed). A misconfigured object (no
   * master_detail/lookup to derive from) denies all reads (defense-in-depth;
   * spec validation should prevent authoring it). Returns null when the object is
   * not controlled_by_parent.
   *
   * v1 scope (ADR-0055): single level — the master's OWN controlled_by_parent is
   * not traversed transitively; master accessibility is the master's RLS filter
   * (sharing-service grants on the master are not folded in).
   */
  private async computeControlledByParentFilter(
    permissionSets: PermissionSet[],
    object: string,
    context: any,
  ): Promise<Record<string, unknown> | null> {
    if (!this.ql || !context?.userId) return null;
    const schema = typeof this.ql.getSchema === 'function' ? this.ql.getSchema(object) : null;
    const sharingModel = schema?.sharingModel ?? schema?.security?.sharingModel;
    if (sharingModel !== 'controlled_by_parent') return null;

    const rel = this.resolveCbpRelation(object);
    if (!rel) return { ...RLS_DENY_FILTER };

    const masterFilter = await this.computeRlsFilter(permissionSets, rel.master, 'find', context);
    let masterIds: string[] = [];
    try {
      const rows = await this.ql.find(rel.master, {
        where: masterFilter ?? {},
        fields: ['id'],
        context: { isSystem: true },
      });
      masterIds = (Array.isArray(rows) ? rows : [])
        .map((r: any) => r?.id)
        .filter((id: any) => id != null);
    } catch {
      masterIds = [];
    }
    return { [rel.fk]: { $in: masterIds } };
  }

  /**
   * ADR-0055 — master-detail "controlled by parent" WRITE enforcement.
   *
   * A by-id write (insert/update/delete) to a controlled_by_parent detail
   * requires EDIT access to its master: the caller must hold CRUD `update` on the
   * master object AND the master row must be visible under the master's write RLS.
   * This is the write-side companion to the read derivation — the RLS read filter
   * never applies to a by-id write (the #1994 class), so without this a member
   * could mutate a detail under a master they cannot edit. Throws on denial;
   * no-op when the object is not controlled_by_parent.
   *
   * v1 scope: single-id writes. Bulk writes flow through the AST and are already
   * scoped by the controlled-by-parent READ filter (to readable masters).
   */
  private async assertControlledByParentWrite(
    permissionSets: PermissionSet[],
    object: string,
    operation: string,
    opCtx: any,
    context: any,
  ): Promise<void> {
    const schema = typeof this.ql?.getSchema === 'function' ? this.ql.getSchema(object) : null;
    const sharingModel = schema?.sharingModel ?? schema?.security?.sharingModel;
    if (sharingModel !== 'controlled_by_parent') return;

    const deny = (reason: string, recordId?: unknown) => {
      throw new PermissionDeniedError(
        `[Security] Access denied: ${operation} on '${object}' requires edit access to its master record (${reason})`,
        { operation, object, recordId },
      );
    };

    const rel = this.resolveCbpRelation(object);
    if (!rel) deny('controlled_by_parent declared but no master_detail relation');

    // Resolve the master id: from the incoming body on insert, else from the
    // target row (read as system — we only need its FK value).
    let masterId: unknown;
    if (operation === 'insert') {
      const data = opCtx.data;
      masterId = data && typeof data === 'object' && !Array.isArray(data) ? (data as any)[rel!.fk] : undefined;
    } else {
      const targetId = this.extractSingleId(opCtx);
      if (targetId == null) return; // bulk write — scoped by the read filter on the AST
      const row = await this.readRowById(object, targetId, { isSystem: true });
      if (!row) deny('target record not found', targetId);
      masterId = row![rel!.fk];
    }
    if (masterId == null) deny('detail record has no master reference');

    // Master edit access = CRUD update on the master AND master row visible under
    // the master's write RLS.
    if (!this.permissionEvaluator.checkObjectPermission('update', rel!.master, permissionSets)) {
      deny(`no edit permission on master '${rel!.master}'`, masterId);
    }
    const masterWriteFilter = await this.computeRlsFilter(permissionSets, rel!.master, 'update', context);
    if (masterWriteFilter) {
      let visible: unknown = null;
      try {
        visible = await this.ql.findOne(rel!.master, {
          where: { $and: [{ id: masterId }, masterWriteFilter] },
          context,
        });
      } catch {
        visible = null;
      }
      if (!visible) deny(`master '${rel!.master}' not editable by this user (row-level security)`, masterId);
    }
  }

  /**
   * Collect all RLS policies from permission sets applicable to the given object/operation.
   */
  private collectRLSPolicies(
    permissionSets: PermissionSet[],
    objectName: string,
    operation: string,
    heldPositions?: string[],
  ): RowLevelSecurityPolicy[] {
    const allPolicies: RowLevelSecurityPolicy[] = [];

    for (const ps of permissionSets) {
      if (ps.rowLevelSecurity) {
        for (const policy of ps.rowLevelSecurity) {
          // [ADR-0105 D3] When org isolation is NOT active, strip the tenant
          // policies the PLATFORM itself ships — there is no meaningful active
          // organization to compare against, so they would match zero rows (or
          // be dropped by the field-existence safety net) for no benefit.
          //
          // Provenance, not pattern-matching (finding F1): the former substring
          // test on `current_user.organization_id` also swallowed app-authored
          // policies, silently unenforcing a declared security property. An
          // authored policy now always reaches the compiler and fails closed
          // there, where the operator can see it.
          if (!this.orgScopingEnabled && isPlatformTenantPolicy(policy)) {
            continue;
          }
          if (!this.orgScopingEnabled && isAuthoredTenantPolicy(policy)) {
            this.warnAuthoredTenantPolicyOnce(policy, objectName);
          }
          allPolicies.push(policy);
        }
      }
    }

    return this.rlsCompiler.getApplicablePolicies(objectName, operation, allPolicies, heldPositions);
  }

  /**
   * [ADR-0105 D3] Explain, once per policy, why an app-authored tenant-scoped
   * policy will match zero rows: it references the active organization but this
   * deployment has no org isolation, so `current_user.organization_id` resolves
   * to nothing and the policy fails closed at compile time. The policy is NOT
   * dropped — a declared security property stays declared (ADR-0049); this is
   * the operator-visible half of that contract.
   */
  private warnAuthoredTenantPolicyOnce(
    policy: RowLevelSecurityPolicy,
    objectName: string,
  ): void {
    const key = `${objectName} ${policy.name ?? ''}`;
    if (this.warnedAuthoredTenantPolicies.has(key)) return;
    this.warnedAuthoredTenantPolicies.add(key);
    this.logger.warn?.(
      '[security/ADR-0105] authored RLS policy references the active organization but org isolation ' +
        'is inactive — it is retained and will fail closed (zero rows). Install ' +
        '@objectstack/organizations (or drop the policy) if this is not intended.',
      { object: objectName, policy: policy.name, using: policy.using },
    );
  }

  /**
   * [ADR-0066 D2/D3] Resolve and cache the object's security posture: whether it
   * is `private` (access.default), platform-global (tenancy disabled), and its
   * `requiredPermissions` capability contract. Prefers the live ObjectQL schema
   * (reflects registry-time augmentation) and falls back to the metadata service.
   * Returns the permissive default when the schema can't be resolved yet (boot) —
   * the CRUD/RLS checks then behave as pre-0066 and the miss is retried next call.
   */
  private async getObjectSecurityMeta(
    object: string,
  ): Promise<ObjectSecurityMeta> {
    const cached = this.objectSecurityMetaCache.get(object);
    if (cached) return cached;
    let obj: any = typeof this.ql?.getSchema === 'function' ? this.ql.getSchema(object) : null;
    if (!obj) {
      try { obj = await this.metadata?.get?.('object', object); } catch { obj = null; }
    }
    // [ADR-0066 D3] Per-field capability requirements: { fieldName -> capability[] }.
    const fieldRequiredPermissions: Record<string, string[]> = {};
    const fields: any = (obj as any)?.fields;
    if (Array.isArray(fields)) {
      for (const f of fields) {
        if (f?.name && Array.isArray(f.requiredPermissions) && f.requiredPermissions.length > 0) {
          fieldRequiredPermissions[String(f.name)] = f.requiredPermissions.map(String);
        }
      }
    } else if (fields && typeof fields === 'object') {
      for (const [fname, fdef] of Object.entries(fields)) {
        const rp = (fdef as any)?.requiredPermissions;
        if (Array.isArray(rp) && rp.length > 0) fieldRequiredPermissions[fname] = rp.map(String);
      }
    }
    const meta = {
      isPrivate: (obj as any)?.access?.default === 'private',
      tenancyDisabled:
        (obj as any)?.tenancy?.enabled === false || (obj as any)?.systemFields?.tenant === false,
      // Identity-infrastructure tables managed by the auth library
      // (`managedBy: 'better-auth'`: sys_user, sys_account, sys_session,
      // sys_oauth_application, sys_sso_provider, …). Their rows are written by
      // better-auth's own adapter with no tenant context, so `organization_id`
      // is never stamped (and most such tables have no such column at all).
      // [ADR-0095 D1] `posturePermitsCrossTenant` uses this flag so a platform
      // admin's Layer 0 exemption lets `viewAllRecords` see all identity rows
      // env-wide. This does NOT relax member scoping (members never satisfy the
      // exemption; their `_self` carve-outs are their Layer 1 scoping, and Layer
      // 0 stays inert on a column-less table), so it can never leak to non-admins.
      isBetterAuthManaged: (obj as any)?.managedBy === 'better-auth',
      requiredPermissions: normalizeRequiredPermissions((obj as any)?.requiredPermissions),
      fieldRequiredPermissions,
    };
    if (obj) this.objectSecurityMetaCache.set(object, meta);
    return meta;
  }

  /**
   * [ADR-0066 D3] Fold per-field `requiredPermissions` into a FieldPermission map.
   * A field whose declared capabilities are NOT all held by the caller is forced
   * non-readable + non-editable (AND-gate, strictest-wins over permission-set
   * field grants) so the existing FieldMasker masks it on read and denies it on
   * write. Returns the base map unchanged when no field declares requirements.
   */
  private foldFieldRequiredPermissions(
    baseFieldPerms: Record<string, { readable: boolean; editable: boolean }>,
    fieldRequiredPermissions: Record<string, string[]>,
    permissionSets: PermissionSet[],
  ): Record<string, { readable: boolean; editable: boolean }> {
    const entries = Object.entries(fieldRequiredPermissions ?? {});
    if (entries.length === 0) return baseFieldPerms;
    const held = this.permissionEvaluator.getSystemPermissions(permissionSets);
    const merged: Record<string, { readable: boolean; editable: boolean }> = { ...baseFieldPerms };
    for (const [field, caps] of entries) {
      if (caps.length > 0 && !caps.every((c) => held.has(c))) {
        merged[field] = { readable: false, editable: false };
      }
    }
    return merged;
  }

  /**
   * Resolve the column-name set for an object (lowercased). Returns
   * `null` if the schema can't be loaded — caller should fail-closed.
   */
  private async getObjectFieldNames(
    metadata: any,
    objectName: string,
    ql?: any,
  ): Promise<Set<string> | null> {
    if (this.fieldNamesCache.has(objectName)) {
      return this.fieldNamesCache.get(objectName) ?? null;
    }
    const result = await this.loadObjectFieldNames(metadata, objectName, ql);
    // Only cache positive resolutions — a `null` may simply mean the
    // schema isn't registered yet at boot, and we want subsequent calls
    // to retry rather than be permanently denied.
    if (result) {
      this.fieldNamesCache.set(objectName, result);
    }
    return result;
  }

  private async loadObjectFieldNames(
    metadata: any,
    objectName: string,
    ql?: any,
  ): Promise<Set<string> | null> {
    try {
      // Prefer ObjectQL's per-engine SchemaRegistry as the source of truth
      // for the live field set: it reflects registry-time augmentations
      // (system-field auto-injection like `organization_id`) that the
      // standalone metadata artifact loaded at boot may not include.
      // Fall back to the metadata service for objects ObjectQL doesn't
      // know about (system tables registered through other paths).
      let obj: any = typeof ql?.getSchema === 'function' ? ql.getSchema(objectName) : null;
      if (!obj || !obj.fields) {
        obj = await metadata?.get?.('object', objectName);
      }
      if (!obj || !obj.fields) return null;
      // Populate the tenancy opt-out cache alongside the field set so
      // the RLS filter pass can decide whether a wildcard
      // `organization_id` policy is genuinely "applicable but
      // uncompilable" (deny) versus "not applicable on this object"
      // (skip without contributing to the deny sentinel).
      const tenancyDisabled =
        (obj as any)?.tenancy?.enabled === false ||
        (obj as any)?.systemFields?.tenant === false;
      this.tenancyDisabledCache.set(objectName, !!tenancyDisabled);
      const set = new Set<string>(['id']);
      if (Array.isArray(obj.fields)) {
        for (const f of obj.fields) {
          if (f?.name) set.add(String(f.name));
        }
      } else if (typeof obj.fields === 'object') {
        for (const key of Object.keys(obj.fields)) {
          set.add(key);
          const v = (obj.fields as Record<string, any>)[key];
          if (v && typeof v === 'object' && v.name) set.add(String(v.name));
        }
      } else {
        return null;
      }
      return set;
    } catch {
      return null;
    }
  }

  /**
   * Extract the left-hand field name from a simple RLS expression like
   * `field = current_user.x` or `field IN (current_user.y)`. Returns
   * `null` for unsupported shapes (in which case we keep the policy).
   */
  private extractTargetField(using?: string): string | null {
    if (!using) return null;
    // Match `field ==` (canonical CEL), `field =` (legacy SQL-ish), or
    // `field IN`/`in`. [#2936] `==` MUST be listed before `=` in the
    // alternation: alternation is ordered, so a bare `=` branch would match
    // the first `=` of `==` and then the `(?=\s|\()` lookahead — seeing the
    // SECOND `=`, not whitespace — would fail, leaving `==` unrecognized (the
    // original bug: real seeds/business policies author equality as `==`, so
    // the field-existence and tenancy-disabled safety nets that consume this
    // were inert for them). `\b` is omitted after the operator because `=` is
    // non-word and the next char (space) is non-word too — a word boundary
    // cannot exist between two non-word chars — so we require the operator to
    // be followed by whitespace or `(` instead. `!=`/`>`/`<`/`>=`/`<=` are
    // deliberately NOT recognized: returning `null` keeps such a policy (the
    // conservative default), matching the pre-#2936 behavior for any shape the
    // regex did not match.
    const m = using.match(/^\s*([a-z_][a-z0-9_]*)\s*(?:==|=|IN|in)(?=\s|\()/);
    return m ? m[1] : null;
  }
}