@feasibleone/blong-gogo 1.32.0 → 1.33.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.33.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.32.0...blong-gogo-v1.33.0) (2026-09-15)
+
+
+### Features
+
+* **blong-dev:** keep frictions, todos and decisions as verified memory files ([4ca7a3b](https://github.com/feasibleone/blong/commit/4ca7a3be1f8919e0dc121974d3d5ad713883c456))
+
 ## [1.32.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.31.3...blong-gogo-v1.32.0) (2026-09-12)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "repository": {
     "url": "git+https://github.com/feasibleone/blong.git"
   },
@@ -90,7 +90,7 @@
     "tap": "^21.6.3",
     "typescript": "^6.0.3",
     "vite": "^8.2.1",
-    "@feasibleone/blong-dev": "1.3.0"
+    "@feasibleone/blong-dev": "1.4.0"
   },
   "scripts": {
     "browser-check": "node scripts/browser-compat-check.mjs",

package/src/Watch.ts

@@ -465,6 +465,10 @@ export default class Watch extends Internal implements IWatch {
                                   this.#config.enabled ? filename + '?' + Date.now() : filename
                               )
                           ).default;
+                // A module without a default export is a plain module shared by
+                // the group's handlers (e.g. `account.ts`, `accessModel.ts`), not
+                // a handler — the loader ignores it.
+                if (!item) return (api: T) => api;
                 const expectedName = this.#platform
                     .basename(filename, this.#platform.extname(filename))
                     .match(prefixRE)?.[1];

package/src/adapter/schema/knex/types.ts

@@ -78,6 +78,82 @@ export interface IEdgeBinding {
     reverse?: boolean;
 }
 
+/**
+ * Resource-backed display-name override.
+ *
+ * By default the display name of a resource-backed row is the virtual
+ * `${object}Name` field.  A table whose real display column is named differently
+ * (e.g. `party_organization.legalName`) declares it here: the `core_resource` row
+ * is then named from that column — and renamed when the column changes — and no
+ * virtual `${object}Name` field is synthesised (the real column *is* the label).
+ */
+export interface IResourceTableSpec {
+    /** Real column of the entity table that supplies `core_resource.resourceName`. */
+    nameColumn?: string;
+}
+
+/**
+ * Record-level (ACL) guard for a table.
+ *
+ * The ACL lives in `access_acl` rows — `(principalId, actionId, targetId,
+ * targetKind, effect)` — where `principalId` is a user, role, unit or capability,
+ * `targetId` is the guarded record (or a scope node) and `effect` is `allow` /
+ * `deny` (deny always wins).
+ */
+export interface IAclTableSpec {
+    /**
+     * - `none` (default) — the entity is not record-guarded; nothing changes.
+     * - `scoped` — a grant may target a scope; it covers the records linked to
+     *   that scope through one of the declared `scopes` predicates.
+     * - `explicit` — only per-record grants count (`scopes` is not consulted).
+     */
+    mode?: 'none' | 'scoped' | 'explicit';
+    /**
+     * Predicates linking a record of this table to the scope(s) it belongs to
+     * (e.g. `belongsTo`, `isPartOf`).  Consulted in `scoped` mode.
+     */
+    scopes?: string[];
+    /**
+     * The record is *its own* scope — for a table whose scopes point at it
+     * rather than the other way round (`party.organization`, which its units
+     * belong to).  Its scope set is the record itself plus its parent scopes,
+     * and `scopes` is ignored.  There is no unscoped fallback: a record is only
+     * reachable through a grant that covers it or one of its parents.
+     */
+    selfScope?: boolean;
+    /**
+     * Where the scope of a NEW record comes from.  `add` has no record key yet,
+     * so the check runs against the scope named in the payload (`column`, e.g.
+     * `unitId`) and/or carried by a declared scope edge (`predicate`, e.g.
+     * `belongsTo`).
+     */
+    addScope?: {
+        /** Payload column holding the scope's resource id. */
+        column?: string;
+        /** Scope predicate whose payload array holds the scope ids. */
+        predicate?: string;
+    };
+}
+
+/**
+ * Adapter-level ACL rules shared by every guarded table (see `ISchemaTable.acl`).
+ * The defaults match `realm/blong-access` and its `access_pathRefresh()` procedure.
+ */
+export interface IAclAdapterConfig {
+    /** The ACL table (default `access_acl`). */
+    table?: string;
+    /** The action entity table whose PK is the action resource (default `access_action`). */
+    actionTable?: string;
+    /** `core.path` pathType whose destinations are the caller's roles (default `access.effectiveRole`). */
+    rolePathType?: string;
+    /** `core.path` pathType whose destinations are the caller's unit scopes (default `access.effectiveScope`). */
+    scopePathType?: string;
+    /** `core_triple` predicate linking a principal to a unit (default `belongsTo`). */
+    unitPredicate?: string;
+    /** `core_triple` predicate linking a principal to a scope directly (default `hasScope`). */
+    scopePredicate?: string;
+}
+
 export interface ISchemaTable {
     /**
      * The TypeBox `TObject` for the table.  Optional when the definition is
@@ -95,8 +171,17 @@ export interface ISchemaTable {
      *  - `find`/`get` join `resourceName` as `${object}Name`;
      *  - `edit` renames `core_resource.resourceName` from `${object}Name`;
      *  - `remove` deletes the `core_resource` row (and the declared `edges`).
+     *
+     * Pass `{nameColumn}` when the table's real display column is not
+     * `${object}Name` (see `IResourceTableSpec`).
+     */
+    resource?: boolean | IResourceTableSpec;
+    /**
+     * Record-level (ACL) guard: which predicates are narrowed to the records the
+     * caller may act on, and where a new record's scope comes from.  Defaults to
+     * `mode: 'none'` (unguarded) when omitted.
      */
-    resource?: boolean;
+    acl?: IAclTableSpec;
     /**
      * Declarative graph-edge master-detail bindings (`core_triple` edges such
      * as `hasRole` / `hasCapability`). `get` attaches the edge rows as a
@@ -224,6 +309,12 @@ export interface IConfig {
          */
         procedurePaths?: string[];
         accessPathRefresh?: boolean; // When `true`, calls `access_pathRefresh()` after schema sync/seed (default: `false`).
+        /**
+         * Record-level (ACL) rules shared by every table declaring
+         * `ISchemaTable.acl` — the ACL table name and the graph predicates/path
+         * types used to resolve the caller's principals and a record's scopes.
+         */
+        acl?: IAclAdapterConfig;
     };
     /**
      * When `true`, mocks some handlers

package/src/adapter/server/acl.ts

@@ -0,0 +1,440 @@
+import {crockfordDecode} from '@feasibleone/blong-lib';
+import type {IObjectSchema, Knex} from '@feasibleone/blong/types';
+import {methodParts} from '../../lib.ts';
+import type {IAclAdapterConfig} from '../schema/knex/types.ts';
+
+/**
+ * Record-level (ACL) SQL helpers shared by the knex adapter's generic CRUD and
+ * by realm handlers (through the `acl` library function in `blong-access`).
+ *
+ * The ACL itself is a single table (`access_acl` unless configured otherwise):
+ *
+ * ```
+ * access_acl(aclId, principalId, actionId, targetId, targetKind, effect, isActive)
+ * ```
+ *
+ * - `principalId` — a user, role, unit or capability resource id;
+ * - `actionId`      — the `access_action` resource of the guarded method;
+ * - `targetId`      — the guarded record, or a **scope** node (`targetKind`);
+ * - `effect`        — `allow` / `deny`, where **deny always wins**.
+ *
+ * Two things grant access, and both narrow RBAC (a method the caller's action
+ * list does not contain is refused by the gateway before this ever runs):
+ *
+ * - **implicit** — a `<principal> --hasScope--> <scope>` graph edge: the
+ *   organizational/hierarchical grant, covering every action the principal
+ *   holds.  The caller inherits the edges of its roles and units.
+ * - **explicit** — an `access_acl` row targeting a scope or a single record,
+ *   optionally turning an implicit allow off with `effect: 'deny'`.
+ *
+ * The record side is derived from the graph too: a record belongs to a scope
+ * through one of the table's declared `scopes` predicates (`belongsTo`,
+ * `isPartOf`, …), and a scope may itself sit under a parent scope — a grant on a
+ * parent covers its descendants.
+ *
+ * All checks are plain SQL predicates evaluated by MySQL (no materialization of
+ * the effective ACL), so they can be used both for a single-record check and as
+ * a `WHERE` clause that filters a whole result set before paging.
+ */
+
+/** Resolved ACL rules (defaults match `realm/blong-access`). */
+export interface IResolvedAclConfig {
+    /** The ACL table. */
+    table: string;
+    /** The action entity table whose PK is the action resource. */
+    actionTable: string;
+    /** `core_path` pathType whose destinations are the caller's roles. */
+    rolePathType: string;
+    /** `core_path` pathType whose destinations are a node's scope ancestors (including itself). */
+    scopePathType: string;
+    /** `core_triple` predicate linking a principal to a unit. */
+    unitPredicate: string;
+    /** `core_triple` predicate linking a principal to a scope. */
+    scopePredicate: string;
+}
+
+const ACL_DEFAULTS: IResolvedAclConfig = {
+    table: 'access_acl',
+    actionTable: 'access_action',
+    rolePathType: 'access.effectiveRole',
+    scopePathType: 'access.effectiveScope',
+    unitPredicate: 'belongsTo',
+    scopePredicate: 'hasScope',
+};
+
+/**
+ * Merge the adapter's `schema.acl` block over the defaults, ignoring `undefined`
+ * values so a partially-filled config cannot blank a default.
+ */
+export function aclConfig(config?: IAclAdapterConfig): IResolvedAclConfig {
+    const defined = Object.fromEntries(
+        Object.entries(config ?? {}).filter(([, value]) => value !== undefined && value !== null),
+    ) as Partial<IResolvedAclConfig>;
+    return {...ACL_DEFAULTS, ...defined};
+}
+
+/**
+ * Binary resource id of the JWT `sub` claim.
+ *
+ * `sub` is crockford-encoded and `crockfordEncode` **reverses** the bytes, so
+ * decoding round-trips to the DB byte order used by `core_path.originId` and
+ * `core_triple.subjectId`.  Dashed UUIDs, hex and base64 strings are accepted
+ * too (tests and internal callers).
+ */
+export function aclActorId(actorId: string): Buffer {
+    const dashed = actorId.replaceAll('-', '');
+    if (/^[0-9a-f]{32}$/i.test(dashed)) return Buffer.from(dashed, 'hex');
+    try {
+        const raw = crockfordDecode(actorId);
+        if (raw.length === 16) return Buffer.from(raw);
+    } catch {
+        // Not crockford — fall through to the base64 attempt.
+    }
+    const base64 = Buffer.from(actorId, 'base64');
+    if (base64.length === 16) return base64;
+    throw new Error(`Cannot resolve a resource id from the actor id "${actorId}"`);
+}
+
+/**
+ * The actor id of the caller (`$meta.auth.actorId`) — undefined when the call is
+ * unauthenticated (e.g. a seed merge or an internal dispatch).
+ */
+export function aclActorOf($meta?: unknown): string | undefined {
+    return ($meta as {auth?: {actorId?: string}} | undefined)?.auth?.actorId;
+}
+
+/**
+ * The guarded entity (`subject.object`) a method belongs to — `accessUserEdit`
+ * and `access.user.edit` both resolve to `access.user`.
+ */
+export function aclEntityOf(method: string): string | undefined {
+    const bare = method.split('/').pop() ?? method;
+    const parts = methodParts(bare).split('.');
+    return parts.length >= 2 ? `${parts[0]}.${parts[1]}` : undefined;
+}
+
+/** The record key column of a table — its PK, defaulting to `${object}Id`. */
+export function aclKeyColumn(objectSchema: IObjectSchema, subject: string, object: string): string {
+    return (
+        (objectSchema[subject]?.[object] as {constraints?: {primaryKey?: string}} | undefined)
+            ?.constraints?.primaryKey ?? `${object}Id`
+    );
+}
+
+/** Guard against a predicate/pathType config value breaking out of its SQL literal. */
+function sqlLiteral(value: string, what: string): string {
+    if (!/^[A-Za-z0-9_.-]+$/.test(value)) {
+        throw new Error(
+            `Invalid ACL ${what} "${value}" — only word characters, dot and dash are allowed`,
+        );
+    }
+    return `'${value}'`;
+}
+
+function sqlList(values: string[], what: string): string {
+    if (!values.length) throw new Error(`The ACL ${what} list is empty`);
+    return values.map(value => sqlLiteral(value, what)).join(', ');
+}
+
+/**
+ * Action resource id of a method.  The action name is matched the same way the
+ * gateway matches method ids (dots stripped, lowercased) so `access.user.edit`
+ * and `accessUserEdit` resolve to the same action.
+ *
+ * An `undefined` result means the method has **no `access_action` row at all** —
+ * the realm does not manage it as an RBAC action (e.g. a plain table method), so
+ * there is nothing for the ACL to match and the caller is allowed.  An action
+ * that *does* exist but has no ACL row for the caller is a **denial**: opting a
+ * table into the ACL (`mode: 'scoped' | 'explicit'`) is deny-by-default, with
+ * the implicit `hasScope` grants and the explicit `allow` rows opening it up.
+ */
+export async function aclActionId(
+    qb: Knex,
+    cfg: IResolvedAclConfig,
+    method: string,
+): Promise<Buffer | undefined> {
+    const row = (await qb
+        .select('act.actionId')
+        .from(`${cfg.actionTable} as act`)
+        .join('core_resource as r', 'r.resourceId', 'act.actionId')
+        .whereRaw("LOWER(REPLACE(r.resourceName, '.', '')) = ?", [
+            method.replaceAll('.', '').toLowerCase(),
+        ])
+        .first()) as {actionId: Buffer} | undefined;
+    return row?.actionId;
+}
+
+export interface IAclCheck {
+    /** Raw SQL boolean expression — usable as a `SELECT` item or a `WHERE` clause. */
+    sql: string;
+    /** Positional bindings, in `?` order. */
+    bindings: unknown[];
+}
+
+/**
+ * The action resource name of a CRUD method following the repo-wide convention
+ * (`subject` + `Object` + `Predicate`, e.g. `access` + `user` + `find` →
+ * `accessUserFind`) — the same shape the gateway's `methodId` normalisation
+ * makes equivalent to `access.user.find`.
+ */
+export function aclActionName(subject: string, object: string, predicate: string): string {
+    const capitalise = (value: string): string => value[0].toUpperCase() + value.slice(1);
+    return `${subject}${capitalise(object)}${capitalise(predicate)}`;
+}
+
+export interface IAclCheckOptions {
+    cfg: IResolvedAclConfig;
+    /** Binary resource id of the caller. */
+    actorId: Buffer;
+    /**
+     * Binary resource id of the guarded action.  When `undefined` the action has
+     * no ACL rows and the caller is allowed (RBAC already decided the verb).
+     */
+    actionId: Buffer | undefined;
+    /**
+     * How the guarded record is referenced: `'?'` (bind its binary id through
+     * `recordId`) for a single-record check, or a column reference such as
+     * `party_organization.organizationId` for a correlated list filter.  Omit it
+     * for `add` — the record does not exist yet and only scopes can be targeted.
+     */
+    recordRef?: string;
+    /** Binary record id — required when `recordRef` is `'?'`. */
+    recordId?: Buffer;
+    /** The guarded table's declared scope predicates (`belongsTo`, `isPartOf`, …). */
+    scopes?: string[];
+    /**
+     * The record is its own scope (see `IAclTableSpec.selfScope`) — its scope set
+     * is the record plus the parent scopes reachable from it, and any declared
+     * `scopes` predicates are ignored.
+     */
+    selfScope?: boolean;
+    /**
+     * Explicit scope ids, replacing the record-derived scope set.  Used by `add`,
+     * where the scope comes from the payload (`addScope`).
+     */
+    scopeIds?: Buffer[];
+    /** `explicit` drops the implicit `<principal> --hasScope--> <scope>` grant. */
+    mode: 'scoped' | 'explicit';
+}
+
+/**
+ * The caller's principals: itself, its roles (from `core_path`), the units it
+ * belongs to and those units' ancestors.
+ *
+ * `subjectColumn` names the principal column of the surrounding table — it is
+ * `principalId` in the ACL table and `subjectId` in `core_triple`.
+ */
+function principalFilter(
+    cfg: IResolvedAclConfig,
+    actorId: Buffer,
+    alias: string,
+    subjectColumn: string,
+): {sql: string; bindings: unknown[]} {
+    const unitPredicate = sqlLiteral(cfg.unitPredicate, 'unit predicate');
+    const units = `SELECT tu.objectId FROM core_triple tu WHERE tu.subjectId = ? AND tu.predicateName = ${unitPredicate}`;
+    return {
+        sql: `${alias}.${subjectColumn} = ? OR ${alias}.${subjectColumn} IN (
+            SELECT pr.destinationId FROM core_path pr WHERE pr.originId = ? AND pr.pathType = ?
+            UNION SELECT t.objectId FROM core_triple t WHERE t.subjectId = ? AND t.predicateName = ${unitPredicate}
+            UNION SELECT pa.destinationId FROM core_path pa
+                WHERE pa.pathType = ? AND pa.originId IN (${units})
+        )`,
+        bindings: [actorId, actorId, cfg.rolePathType, actorId, cfg.scopePathType, actorId],
+    };
+}
+
+/**
+ * The scopes a record participates in: its own scope edges (`belongsTo`,
+ * `isPartOf`, …) plus every ancestor of those scopes — the materialized
+ * `<scope> --isPartOf--> <parent>` chain, which includes each scope itself.
+ *
+ * `recordRef` is `'?'` (then the record id is bound twice) or a column reference
+ * for a correlated list filter (then nothing is bound).
+ */
+function recordScopesSql(
+    cfg: IResolvedAclConfig,
+    scopes: string[],
+    recordRef: string,
+    recordId: Buffer | undefined,
+): {sql: string; bindings: unknown[]} {
+    const predicateList = sqlList(scopes, 'scope predicate');
+    const refs = recordRef === '?' ? [recordId, recordId] : [];
+    return {
+        sql: `SELECT ts.objectId FROM core_triple ts
+                WHERE ts.subjectId = ${recordRef} AND ts.predicateName IN (${predicateList})
+            UNION SELECT pa.destinationId FROM core_path pa
+                WHERE pa.pathType = ? AND pa.originId IN (
+                    SELECT ps.objectId FROM core_triple ps
+                    WHERE ps.subjectId = ${recordRef} AND ps.predicateName IN (${predicateList})
+                )`,
+        bindings: [...refs.slice(0, 1), cfg.scopePathType, ...refs.slice(1)],
+    };
+}
+
+/**
+ * The scope set of a record that *is* its own scope: the record plus its parent
+ * scopes (the materialized scope path).  Used by tables whose scopes point at
+ * them — `party.organization`, whose units carry `belongsTo` towards it — where
+ * the record has no scope edge of its own to follow.
+ */
+function ownScopeSql(
+    cfg: IResolvedAclConfig,
+    recordRef: string,
+    recordId: Buffer | undefined,
+): {sql: string; bindings: unknown[]} {
+    const refs = recordRef === '?' ? [recordId, recordId] : [];
+    return {
+        sql: `SELECT ${recordRef} AS objectId
+            UNION SELECT pa.destinationId FROM core_path pa
+                WHERE pa.pathType = ? AND pa.originId = ${recordRef}`,
+        bindings: [...refs.slice(0, 1), cfg.scopePathType, ...refs.slice(1)],
+    };
+}
+
+/** The scope set of an explicit list of scope ids: the ids themselves plus their ancestors. */
+function explicitScopesSql(
+    cfg: IResolvedAclConfig,
+    scopeIds: Buffer[],
+): {sql: string; bindings: unknown[]} {
+    const ids = scopeIds.map(() => 'SELECT ? AS id').join(' UNION ');
+    const placeholders = scopeIds.map(() => '?').join(', ');
+    return {
+        sql: `${ids}
+            UNION SELECT pa.destinationId FROM core_path pa
+                WHERE pa.pathType = ? AND pa.originId IN (${placeholders})`,
+        bindings: [...scopeIds, cfg.scopePathType, ...scopeIds],
+    };
+}
+
+/**
+ * Build the boolean expression that decides whether the caller may act on the
+ * record with the given action:
+ *
+ * ```sql
+ * (implicit OR explicit-allow) AND NOT explicit-deny
+ * ```
+ *
+ * `implicit` is a `hasScope` edge from one of the caller's principals to a scope
+ * the record participates in; the explicit halves are `access_acl` rows
+ * targeting the record itself or one of those scopes.  An unknown action (no
+ * `actionId`) short-circuits to `TRUE` — RBAC already decided the verb.
+ *
+ * The SQL and its bindings are assembled strictly in placeholder order; every
+ * fragment's bindings are spliced in exactly where its SQL text is spliced.
+ */
+export function aclCheckSql(options: IAclCheckOptions): IAclCheck {
+    const {cfg, actorId, actionId, recordRef, mode} = options;
+    if (!actionId) return {sql: 'TRUE', bindings: []};
+
+    const scopeIds = options.scopeIds?.length ? options.scopeIds : undefined;
+    const scopes = options.scopes ?? [];
+    // Nothing to evaluate against: no record key and no scope.  Nothing can
+    // match, so the answer is "denied" — a caller that forgot the target fails
+    // here rather than being let through (see `access.session.verify`, which
+    // turns this into a `recordRequired` refusal).
+    if (!recordRef && !scopeIds) return {sql: 'FALSE', bindings: []};
+    const scopeSet = scopeIds
+        ? explicitScopesSql(cfg, scopeIds)
+        : options.selfScope && recordRef
+          ? ownScopeSql(cfg, recordRef, options.recordId)
+          : mode === 'scoped' && recordRef && scopes.length
+            ? recordScopesSql(cfg, scopes, recordRef, options.recordId)
+            : undefined;
+
+    // The target test: the record itself (when there is one) and/or the scopes
+    // it participates in.  `add` has no record key yet, so only scopes.  A
+    // wildcard rule (`targetKind: 'all'`, anchored on a sentinel node) matches
+    // every record in every scope shape.  Built per alias so the allow (`a`) and
+    // deny (`d`) sub-queries each refer to their own row.
+    const targetOf = (alias: string): {sql: string; bindings: unknown[]} =>
+        scopeSet
+            ? {
+                  sql: recordRef
+                      ? `(${alias}.targetKind = 'all'
+            OR (${alias}.targetKind = 'record' AND ${alias}.targetId = ${recordRef})
+            OR (${alias}.targetKind = 'scope' AND ${alias}.targetId IN (${scopeSet.sql})))`
+                      : `(${alias}.targetKind = 'all'
+            OR (${alias}.targetKind = 'scope' AND ${alias}.targetId IN (${scopeSet.sql})))`,
+                  bindings: [
+                      ...(recordRef === '?' ? [options.recordId] : []),
+                      ...scopeSet.bindings,
+                  ],
+              }
+            : {
+                  sql: `(${alias}.targetKind = 'all'
+            OR (${alias}.targetKind = 'record' AND ${alias}.targetId = ${recordRef ?? '?'}))`,
+                  bindings: recordRef ? [options.recordId] : [],
+              };
+
+    const explicit = (effect: 'allow' | 'deny', alias: string): IAclCheck => {
+        const principals = principalFilter(cfg, actorId, alias, 'principalId');
+        const target = targetOf(alias);
+        return {
+            sql: `EXISTS (SELECT 1 FROM ${cfg.table} ${alias}
+                WHERE ${alias}.isActive = 1 AND ${alias}.effect = ${sqlLiteral(effect, 'effect')}
+                    AND ${alias}.actionId = ?
+                    AND (${principals.sql})
+                    AND ${target.sql})`,
+            bindings: [actionId, ...principals.bindings, ...target.bindings],
+        };
+    };
+
+    const allow = explicit('allow', 'a');
+    const deny = explicit('deny', 'd');
+
+    // Implicit grant: <principal> --hasScope--> <scope of the record>.
+    let implicit: IAclCheck | undefined;
+    if (scopeSet && mode === 'scoped') {
+        const principals = principalFilter(cfg, actorId, 'hs', 'subjectId');
+        implicit = {
+            sql: `EXISTS (SELECT 1 FROM core_triple hs
+                WHERE hs.predicateName = ${sqlLiteral(cfg.scopePredicate, 'scope predicate')}
+                    AND (${principals.sql})
+                    AND hs.objectId IN (${scopeSet.sql}))`,
+            bindings: [...principals.bindings, ...scopeSet.bindings],
+        };
+    }
+
+    // A record that participates in no scope has nothing to narrow it against,
+    // so RBAC alone decides it — the ACL restricts records *within* scopes.
+    // This is what makes opting a table in safe for existing, unsorted data.
+    const unscoped =
+        recordRef && mode === 'scoped' && scopes.length
+            ? {
+                  sql: `NOT EXISTS (SELECT 1 FROM core_triple us
+                    WHERE us.subjectId = ${recordRef}
+                        AND us.predicateName IN (${sqlList(scopes, 'scope predicate')}))`,
+                  bindings: recordRef === '?' ? [options.recordId] : [],
+              }
+            : undefined;
+
+    const grant = implicit ? `(${implicit.sql}) OR (${allow.sql})` : `(${allow.sql})`;
+    const guarded = `((${grant}) AND NOT (${deny.sql}))`;
+    const sql = unscoped ? `((${unscoped.sql}) OR ${guarded})` : guarded;
+    const bindings = [
+        ...(unscoped?.bindings ?? []),
+        ...(implicit?.bindings ?? []),
+        ...allow.bindings,
+        ...deny.bindings,
+    ];
+    const expected = sql.split('?').length - 1;
+    if (expected !== bindings.length) {
+        throw new Error(
+            `ACL SQL placeholder mismatch: ${expected} placeholders, ${bindings.length} bindings`,
+        );
+    }
+    return {sql, bindings};
+}
+
+/**
+ * Evaluate the ACL for a single record (or a single scope, for `add`) in one
+ * round trip.  Returns `true` when the caller may proceed.
+ */
+export async function aclAllowed(qb: Knex, options: IAclCheckOptions): Promise<boolean> {
+    const {sql, bindings} = aclCheckSql(options);
+    if (sql === 'TRUE') return true;
+    const row = (await qb.select(qb.raw(`${sql} AS allowed`, bindings as never[])).first()) as
+        | {allowed?: number | boolean | null}
+        | undefined;
+    return Boolean(row?.allowed);
+}

package/src/adapter/server/knex.ts

@@ -15,6 +15,17 @@ import {type TFunction, type TObject} from 'typebox';
 import {v4} from 'uuid';
 import yaml from 'yaml';
 import {methodParts} from '../../lib.ts';
+import {
+    aclActionId,
+    aclActionName,
+    aclActorId,
+    aclActorOf,
+    aclAllowed,
+    aclCheckSql,
+    aclConfig,
+    aclEntityOf,
+    aclKeyColumn,
+} from './acl.ts';
 import {
     binaryToStr,
     discoverBinaryColumns,
@@ -37,6 +48,7 @@ import {
     schemaTableSyncImpl,
 } from '../schema/knex/schemaTable.ts';
 import {
+    type IAclTableSpec,
     type IConfig,
     type IEdgeBinding,
     type IKnexConfig,
@@ -71,6 +83,16 @@ const errorMap: IErrorMap = {
     'knex.exists': 'Knex Exists',
     'knex.unique': 'Knex Unique',
     'knex.missingKey': 'Missing key value for {key}',
+    // Record-level (ACL) refusals from the generic CRUD — the same `acl.*` family
+    // the access realm declares, so a caller sees one error name wherever the
+    // check runs (adapter or realm handler).
+    'acl.denied': {message: 'Not allowed to access this record', statusCode: 403},
+    'acl.scopeDenied': {
+        message: 'Not allowed to create a record in this scope',
+        statusCode: 403,
+    },
+    // A single-record read refuses with "not found" so it does not leak existence.
+    'acl.notFound': {message: 'Record not found', statusCode: 404},
 };
 
 let _errors: Errors<typeof errorMap>;
@@ -404,8 +426,10 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
             // resource-backed table of the subject (see `_dropdownList`).
             if (object === 'dropdown' && operation === 'list') {
                 return (
-                    this as unknown as {_dropdownList(s: string): Promise<unknown>}
-                )._dropdownList(subject);
+                    this as unknown as {
+                        _dropdownList(s: string, meta?: IMeta): Promise<unknown>;
+                    }
+                )._dropdownList(subject, $meta);
             }
             // Structure discovery for the commander explorer:
             //   `{ns}.schema.list` — databases/schemas on the server
@@ -453,6 +477,149 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
                 };
             }
             const table = `${subject}_${object}`;
+            // ── Record-level (ACL) gates ──────────────────────────────────────
+            // A table opts into record-level authorization with
+            // `acl: {mode, scopes, addScope}`; everything below is a no-op for a
+            // table that does not (`mode: 'none'`, the default) and for system
+            // calls, which carry no `$meta.auth` (seed merges, internal dispatches).
+            const aclCfg = aclConfig(this.config.schema?.acl);
+            const aclActor = ($meta?.auth as {actorId?: string} | undefined)?.actorId;
+            /** The guarded table's PK column (the record key). */
+            const aclKeyName = (): string => aclKeyColumn(objectSchema, subject, object);
+
+            /**
+             * Gate a single-record operation (`get` / `edit` / `remove`).
+             * Writes are refused with 403; a read refuses with 404 so it does not
+             * leak the record's existence.
+             */
+            const aclCheckRecord = async (
+                opts: IResolvedTableOptions,
+                operation: string,
+                recordId: Buffer | undefined,
+            ): Promise<void> => {
+                const mode = opts.acl.mode ?? 'none';
+                if (mode === 'none' || !aclActor || !recordId) return;
+                const actionId = await aclActionId(this.config.context.queryBuilder!, aclCfg, method!);
+                if (!actionId) return; // the method is not an RBAC-managed action
+                const allowed = await aclAllowed(this.config.context.queryBuilder!, {
+                    cfg: aclCfg,
+                    actorId: aclActorId(aclActor),
+                    actionId,
+                    recordRef: '?',
+                    recordId,
+                    scopes: opts.acl.scopes,
+                    selfScope: opts.acl.selfScope,
+                    mode,
+                });
+                if (allowed) return;
+                throw this.error(
+                    operation === 'get'
+                        ? _errors['acl.notFound']({params: {reason: 'notFound'}})
+                        : _errors['acl.denied']({params: {reason: 'denied'}}),
+                    $meta,
+                );
+            };
+
+            /**
+             * Release the ACL rules that reference a guarded record about to be
+             * removed.
+             *
+             * `access_acl` keeps foreign keys to `core_resource` on
+             * `principalId`, `actionId` and `targetId`, so a rule left behind
+             * makes the resource delete fail *after* the entity row is already
+             * gone.  What remains is a resource-only ghost, and because
+             * `core.resource.ensure` matches a record by name it then skips the
+             * entity insert — the entity can never be created again.  A record
+             * that is being removed can no longer be a principal, a target or an
+             * action, so its rules go first.
+             */
+            const aclReleaseResource = async (
+                opts: IResolvedTableOptions,
+                recordId: Buffer,
+            ): Promise<void> => {
+                const mode = opts.acl.mode ?? 'none';
+                if (mode === 'none') return;
+                await this.config.context
+                    .queryBuilder!(aclCfg.table)
+                    .where('principalId', recordId)
+                    .orWhere('targetId', recordId)
+                    .orWhere('actionId', recordId)
+                    .del();
+            };
+
+            /**
+             * The ACL predicate for a multi-record read, correlated on the guarded
+             * table's key — applied to the query **before** paging so the result
+             * set (and its total) only contains records the caller may see.
+             */
+            const aclReadFilter = async (
+                opts: IResolvedTableOptions,
+            ): Promise<{sql: string; bindings: unknown[]} | undefined> => {
+                const mode = opts.acl.mode ?? 'none';
+                if (mode === 'none' || !aclActor) return undefined;
+                const actionId = await aclActionId(this.config.context.queryBuilder!, aclCfg, method!);
+                if (!actionId) return undefined;
+                return aclCheckSql({
+                    cfg: aclCfg,
+                    actorId: aclActorId(aclActor),
+                    actionId,
+                    recordRef: `${table}.${aclKeyName()}`,
+                    scopes: opts.acl.scopes,
+                    selfScope: opts.acl.selfScope,
+                    mode,
+                });
+            };
+
+            /**
+             * Gate `add`, which has no record key yet: the check runs against the
+             * scope named by the declaration (`addScope.column` on the payload, or
+             * `addScope.predicate` reading the ids of the submitted scope edges).
+             */
+            const aclCheckAdd = async (
+                opts: IResolvedTableOptions,
+                cols: Record<string, unknown>,
+                rest: Record<string, unknown>,
+            ): Promise<void> => {
+                const mode = opts.acl.mode ?? 'none';
+                const addScope = opts.acl.addScope;
+                if (mode === 'none' || !aclActor || !addScope) return;
+                const ids: string[] = [];
+                if (addScope.column && typeof cols[addScope.column] === 'string') {
+                    ids.push(cols[addScope.column] as string);
+                }
+                if (addScope.predicate) {
+                    // The payload array is keyed by the edge's object name
+                    // (`unit`), which the declared binding owns.
+                    const binding = opts.edges.find(e => e.predicate === addScope.predicate);
+                    const detailObject =
+                        binding?.object ?? addScope.predicate.replace(/^has/, '').toLowerCase();
+                    for (const row of (rest[detailObject] as Array<Record<string, unknown>>) ?? []) {
+                        // The scope id is the object's key in the edge row —
+                        // `{unitId: '<base64>'}` for a `belongsTo` edge.
+                        const found = Object.entries(row ?? {}).find(
+                            ([key, value]) => key.endsWith('Id') && typeof value === 'string',
+                        );
+                        if (found) ids.push(found[1] as string);
+                    }
+                }
+                if (!ids.length) return;
+                const actionId = await aclActionId(this.config.context.queryBuilder!, aclCfg, method!);
+                if (!actionId) return;
+                const allowed = await aclAllowed(this.config.context.queryBuilder!, {
+                    cfg: aclCfg,
+                    actorId: aclActorId(aclActor),
+                    actionId,
+                    scopeIds: ids.map(id => strToBinary(id)),
+                    mode,
+                });
+                if (!allowed) {
+                    throw this.error(
+                        _errors['acl.scopeDenied']({params: {reason: 'scopeDenied'}}),
+                        $meta,
+                    );
+                }
+            };
+
             switch (operation) {
                 case 'get': {
                     const {select: _select, ...where} = params;
@@ -478,13 +645,25 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
                     // the row in place (Buffers → base64 strings). The edge
                     // attachment needs the binary master key.
                     const masterKey = row?.[keyName];
+                    // Record-level ACL: checked after the fetch so a `where` that
+                    // does not carry the key (e.g. by email address) is covered too.
+                    await aclCheckRecord(
+                        opts,
+                        'get',
+                        Buffer.isBuffer(masterKey) ? masterKey : undefined,
+                    );
                     const result: Record<string, unknown> = {
                         [object]: prepareResultRow(row, binaryCols, table),
                     };
                     const masterRow = result[object] as Record<string, unknown> | undefined;
                     // Resource-backed: join the display name from
                     // `core_resource.resourceName` as `${object}Name`.
-                    if (opts.resource && masterRow && typeof masterRow[keyName] === 'string') {
+                    if (
+                        opts.resource &&
+                        !opts.nameColumn &&
+                        masterRow &&
+                        typeof masterRow[keyName] === 'string'
+                    ) {
                         const [joined] = await joinResourceNames(
                             qb,
                             [masterRow],
@@ -560,13 +739,19 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
                             });
                     }
                     if (order) query = query.orderBy(order);
+                    // Record-level ACL: the filter is applied before paging so both
+                    // the page and its total only contain readable records.
+                    const aclFilter = await aclReadFilter(opts);
+                    if (aclFilter) query = query.whereRaw(aclFilter.sql, aclFilter.bindings as never[]);
                     if (limit) query = query.limit(limit);
                     if (offset) query = query.offset(offset);
                     const rows = (await query.select(select)) as Record<string, unknown>[];
                     const prepared = prepareResultRows(rows, binaryCols, table);
                     // Resource-backed: join the display name from
-                    // `core_resource.resourceName` as `${object}Name`.
-                    if (opts.resource) {
+                    // `core_resource.resourceName` as `${object}Name`.  A table
+                    // declaring `resource: {nameColumn}` keeps its real display
+                    // column — no virtual field is synthesised.
+                    if (opts.resource && !opts.nameColumn) {
                         return joinResourceNames(qb, prepared, `${object}Id`, `${object}Name`);
                     }
                     return prepared;
@@ -601,13 +786,18 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
                     const binaryCols = getBinaryCols(this.config.context);
                     const opts = tableOptions(objectSchema, this.config, subject, object);
                     const cols = columns as Record<string, unknown>;
-                    // Resource-backed: `${object}Name` is a virtual display field
-                    // (the name lives in `core_resource.resourceName`) — capture
-                    // it for the resource row and exclude it from the table insert.
+                    // Resource-backed: the display name lives in
+                    // `core_resource.resourceName`.  By default it is the virtual
+                    // `${object}Name` field — captured for the resource row and
+                    // excluded from the table insert.  A table declaring
+                    // `resource: {nameColumn}` names the resource from that real
+                    // column instead, which therefore stays in the insert.
                     const nameColValue = opts.resource
-                        ? (cols[`${object}Name`] as string | undefined)
+                        ? ((opts.nameColumn ? cols[opts.nameColumn] : cols[`${object}Name`]) as
+                              | string
+                              | undefined)
                         : undefined;
-                    if (opts.resource) {
+                    if (opts.resource && !opts.nameColumn) {
                         delete cols[`${object}Name`];
                     }
                     // Generate real PKs server-side for id columns that carry a
@@ -677,6 +867,9 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
                             await ensureResourceRow(generatedKey, keyName);
                         }
                     }
+                    // Record-level ACL: `add` has no record key yet, so the scope
+                    // declared by `addScope` decides whether it may be created.
+                    await aclCheckAdd(opts, cols, rest);
                     // Convert any string values for binary columns to Buffer
                     const insertCols = prepareInputParams(cols, binaryCols, table);
                     const inserted = await qb(table).insert(insertCols);
@@ -756,7 +949,7 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
                     }
                     // Resource-backed: join the display name onto the master so
                     // the caller sees `${object}Name` in the created row.
-                    if (opts.resource && Buffer.isBuffer(masterKey)) {
+                    if (opts.resource && !opts.nameColumn && Buffer.isBuffer(masterKey)) {
                         const masterRow = result[object] as Record<string, unknown> | undefined;
                         if (masterRow && typeof masterRow[`${object}Id`] === 'string') {
                             const [joined] = await joinResourceNames(
@@ -779,15 +972,20 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
                     const {[keyName]: key, ...update} = cols as Record<string, unknown>;
                     const isBinaryKey =
                         isBinaryColumn(binaryCols, table, keyName) && typeof key === 'string';
-                    // Resource-backed: `${object}Name` is a virtual field — the
-                    // display name lives in `core_resource.resourceName`, so
-                    // rename that row instead of updating a table column.
+                    // Resource-backed: the display name lives in
+                    // `core_resource.resourceName`, so a change to the display
+                    // field renames that row.  With `resource: {nameColumn}` the
+                    // real column is updated as well (it stays in the update).
+                    const nameField = opts.nameColumn ?? `${object}Name`;
                     const resourceName = opts.resource
-                        ? (update[`${object}Name`] as string | undefined)
+                        ? (update[nameField] as string | undefined)
                         : undefined;
-                    if (opts.resource) {
+                    if (opts.resource && !opts.nameColumn) {
                         delete update[`${object}Name`];
                     }
+                    // Record-level ACL: refuse an edit of a record the caller may
+                    // not act on, before anything is written.
+                    await aclCheckRecord(opts, 'edit', isBinaryKey ? strToBinary(key) : undefined);
                     // Convert any string values for binary columns to Buffer (the
                     // form round-trips them as base64 strings returned by `get`).
                     const preparedUpdate = prepareInputParams(update, binaryCols, table);
@@ -891,6 +1089,16 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
                         throw this.error(_errors['knex.missingKey']({key: keyName}), $meta);
                     }
                     const qb = this.config.context.queryBuilder!;
+                    // Record-level ACL: refuse to delete a record the caller may
+                    // not act on before anything is touched.
+                    await aclCheckRecord(
+                        opts,
+                        'remove',
+                        Buffer.isBuffer(masterKey) ? masterKey : undefined,
+                    );
+                    // …then release the rules that reference the record, before
+                    // the entity row is deleted (see `aclReleaseResource`).
+                    if (Buffer.isBuffer(masterKey)) await aclReleaseResource(opts, masterKey);
                     // Master-detail: delete each FK-constrained detail table's
                     // rows for this master BEFORE deleting the master row, so a
                     // non-cascading FK does not block the delete.
@@ -1020,6 +1228,129 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
             }
             throw this.error(_errors['knex.generic']({}), $meta);
         },
+        /**
+         * `{subject}.dropdown.list` — produce `{value, label}` pairs for every
+         * resource-backed table of the subject.  A table is resource-backed when
+         * its PK (or any column) is a FK to `core.resource.resourceId`.
+         *
+         * Entries are resolved directly from `core_resource` (joined with
+         * `core_type` by `typeAlias = ${subject}.${object}`), so every realm gets
+         * dropdowns for free, matching the `blong-mock` `{subject}.dropdown.list`
+         * shape (`{value: base64, label: resourceName}`).
+         *
+         * Per-table overrides are declared via the `dropdown` option on the table
+         * spec (see `ISchemaTable`): `typeAlias`, `joinTable`, `joinColumn`,
+         * `labelColumn`.
+         */
+        /**
+         * Evaluate the record-level ACL for one record — or for one or more
+         * scopes, which is what `add` needs (the record has no key yet).
+         *
+         * Realm handlers cannot import this module (the runtime is not a library
+         * dependency of a realm), so they reach it through the port —
+         * `await this.aclCheck({recordId}, $meta)` — while the generic CRUD calls
+         * the same helper directly.
+         *
+         * `guarded: false` means the table does not opt into the ACL, or the
+         * method is not an RBAC-managed action at all: the caller is allowed.
+         * `actionId` (a raw Buffer — this call never crosses a realm boundary)
+         * and `predicate` are returned even for an unguarded entity, so a caller
+         * can reuse them for its own live-permission check.
+         */
+        async aclCheck(
+            params: {
+                /** Guarded entity as `subject.object` — defaults to the entity of `method`. */
+                entity?: string;
+                /** The method whose action is checked — defaults to `$meta.method`. */
+                method?: string;
+                /** Binary record key as a base64/hex string. */
+                recordId?: string;
+                /** Scope ids (used by `add`) as base64/hex strings. */
+                scopeIds?: string[];
+                /** Actor id override — defaults to `$meta.auth.actorId`. */
+                actorId?: string;
+            },
+            $meta?: IMeta,
+        ): Promise<{
+            guarded: boolean;
+            allowed: boolean;
+            entity?: string;
+            predicate?: string;
+            actionId?: Buffer;
+        }> {
+            const qb = this.config?.context?.queryBuilder;
+            const method = params.method ?? $meta?.method;
+            const actor = params.actorId ?? aclActorOf($meta);
+            if (!qb || !method) return {guarded: false, allowed: true};
+            const entity = params.entity ?? aclEntityOf(method);
+            const predicate = methodParts(method).split('.').pop();
+            const [subject, object] = entity ? entity.split('.') : [undefined, undefined];
+            const spec =
+                subject && object
+                    ? resolveTableSpec(
+                          objectSchema,
+                          this.config?.schema?.tables?.[`${subject}.${object}`],
+                          subject,
+                          object,
+                      ).acl
+                    : undefined;
+            const cfg = aclConfig(this.config?.schema?.acl);
+            const actionId = await aclActionId(qb, cfg, method);
+            const mode = spec?.mode ?? 'none';
+            const verdict = {entity, predicate, actionId};
+            if (!actionId || mode === 'none' || !actor) {
+                return {guarded: false, allowed: true, ...verdict};
+            }
+            const allowed = await aclAllowed(qb, {
+                cfg,
+                actionId,
+                actorId: aclActorId(actor),
+                recordRef: params.recordId ? '?' : undefined,
+                recordId: params.recordId ? strToBinary(params.recordId) : undefined,
+                scopeIds: params.scopeIds?.map(id => strToBinary(id)),
+                scopes: spec?.scopes,
+                selfScope: spec?.selfScope,
+                mode,
+            });
+            return {guarded: true, allowed, ...verdict};
+        },
+
+        /**
+         * The ACL predicate that filters a whole result set, correlated on the
+         * guarded table's key column — realm handlers apply it with
+         * `query.whereRaw(sql, bindings)` before paging.  Returns `undefined`
+         * when the entity is not guarded.
+         */
+        async aclFilter(
+            params: {entity: string; method?: string; actorId?: string},
+            $meta?: IMeta,
+        ): Promise<{sql: string; bindings: unknown[]} | undefined> {
+            const method = params.method ?? $meta?.method;
+            const [subject, object] = params.entity.split('.');
+            const actor = params.actorId ?? aclActorOf($meta);
+            const qb = this.config?.context?.queryBuilder;
+            const spec = resolveTableSpec(
+                objectSchema,
+                this.config?.schema?.tables?.[params.entity],
+                subject,
+                object,
+            ).acl;
+            const mode = spec?.mode ?? 'none';
+            if (mode === 'none' || !actor || !method || !qb) return undefined;
+            const cfg = aclConfig(this.config?.schema?.acl);
+            const actionId = await aclActionId(qb, cfg, method);
+            if (!actionId) return undefined;
+            return aclCheckSql({
+                cfg,
+                actionId,
+                actorId: aclActorId(actor),
+                recordRef: `${subject}_${object}.${aclKeyColumn(objectSchema, subject, object)}`,
+                scopes: spec?.scopes,
+                selfScope: spec?.selfScope,
+                mode,
+            });
+        },
+
         /**
          * `{subject}.dropdown.list` — produce `{value, label}` pairs for every
          * resource-backed table of the subject.  A table is resource-backed when
@@ -1037,6 +1368,7 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
         async _dropdownList(
             this: Adapter<IConfig>,
             subject: string,
+            $meta?: IMeta,
         ): Promise<Record<string, Array<{value: string; label: string}>>> {
             const qb = this.config.context?.queryBuilder;
             if (!qb) return {};
@@ -1078,6 +1410,31 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
                         'r.resourceId',
                     );
                 }
+                // Record-level ACL: a dropdown is a read path, so a guarded entity
+                // must not offer records the caller may not read.
+                const aclSpec = resolveTableSpec(objectSchema, tableConfig, s, object).acl;
+                const aclMode = aclSpec?.mode ?? 'none';
+                const dropdownActor = ($meta?.auth as {actorId?: string} | undefined)?.actorId;
+                if (aclMode !== 'none' && dropdownActor) {
+                    const dropdownAcl = aclConfig(this.config.schema?.acl);
+                    const actionId = await aclActionId(
+                        qb,
+                        dropdownAcl,
+                        aclActionName(s, object, 'find'),
+                    );
+                    if (actionId) {
+                        const filter = aclCheckSql({
+                            cfg: dropdownAcl,
+                            actorId: aclActorId(dropdownActor),
+                            actionId,
+                            recordRef: 'r.resourceId',
+                            scopes: aclSpec?.scopes,
+                            selfScope: aclSpec?.selfScope,
+                            mode: aclMode,
+                        });
+                        query = query.whereRaw(filter.sql, filter.bindings as never[]);
+                    }
+                }
                 const rows = (await query) as Array<{resourceId: Buffer; label: string}>;
                 result[`${s}.${object}`] = rows.map(r => ({
                     value: r.resourceId.toString('base64'),
@@ -1238,8 +1595,16 @@ export {attachHandlers, methodId, snakeToCamel};
 export interface IResolvedTableOptions {
     /** Whether the table is resource-backed (PK → `core.resource`). */
     resource: boolean;
+    /**
+     * Real display-name column when it is not the virtual `${object}Name`
+     * (declared as `resource: {nameColumn}`) — the resource row is named from it
+     * and the column stays a normal table column.
+     */
+    nameColumn?: string;
     /** Declarative graph-edge master-detail bindings. */
     edges: IEdgeBinding[];
+    /** Record-level ACL guard (`mode` defaults to `none`). */
+    acl: IAclTableSpec;
 }
 
 /**
@@ -1260,7 +1625,9 @@ function resolveTableSpec(
     definition?: TObject;
     dropdown?: ISchemaTable['dropdown'];
     resource?: boolean;
+    nameColumn?: string;
     edges?: IEdgeBinding[];
+    acl?: IAclTableSpec;
 } {
     if (tableConfig === undefined) return {};
     if (typeof tableConfig === 'number') {
@@ -1275,14 +1642,21 @@ function resolveTableSpec(
             'order' in tableConfig ||
             'dropdown' in tableConfig ||
             'resource' in tableConfig ||
-            'edges' in tableConfig
+            'edges' in tableConfig ||
+            'acl' in tableConfig
         ) {
             const spec = tableConfig as ISchemaTable;
+            const resourceSpec =
+                typeof spec.resource === 'object' && spec.resource !== null
+                    ? spec.resource
+                    : undefined;
             return {
                 definition: spec.definition ?? objectSchema[subject]?.[object],
                 dropdown: spec.dropdown,
-                resource: spec.resource,
+                resource: resourceSpec ? true : spec.resource === true,
+                nameColumn: resourceSpec?.nameColumn,
                 edges: spec.edges,
+                acl: spec.acl,
             };
         }
         return {definition: tableConfig as TObject};
@@ -1308,8 +1682,13 @@ function tableOptions(
             : {};
     const edges = spec.edges ?? [];
     return {
-        resource: spec.resource === true || edges.length > 0,
+        // `resource` is declared explicitly — an `edges` binding alone does NOT
+        // switch on the resource-backed name machinery (a table may carry edges
+        // while keeping its own display-name column).
+        resource: spec.resource === true,
+        nameColumn: spec.nameColumn,
         edges,
+        acl: spec.acl ?? {},
     };
 }