@astram/engine 0.6.0 → 0.8.0

package/dist/adapters/mariadb-audit-sink.d.ts

@@ -9,15 +9,24 @@
  * resolves ids to labels (no raw ids to end users). Sensitive values are never put
  * in the event by the pipe (the audit stage carries only op + typeKey attributes).
  */
+import { type FrameworkSchemas } from '@astram/core';
 import type { AuditEvent, AuditPort, QueryFn } from '../ports.js';
 export interface AuditSinkConfig {
-    /** Schema holding the audit_log table (default shield_audit). */
+    /** Schema holding the audit_log table. Wins over `schemas`. */
     readonly schema?: string;
+    /** Resolved framework names; the sink uses `schemas.audit` when `schema` is absent. */
+    readonly schemas?: Pick<FrameworkSchemas, 'audit'>;
     /** Table name (default audit_log). */
     readonly table?: string;
 }
 export declare class MariaDbAuditSink implements AuditPort {
     private readonly ref;
+    /**
+     * Default schema (configurable-framework-db, spec 5.B): `config.schema`, else
+     * `config.schemas.audit`, else the audit name resolved from `SHIELD_DB_NAMESPACE` once, here at
+     * construction (boot), never per event. Unset namespace ⇒ today's default audit database. An
+     * invalid namespace throws (fail closed).
+     */
     constructor(config?: AuditSinkConfig);
     record(event: AuditEvent, query: QueryFn): Promise<void>;
 }

package/dist/adapters/mariadb-audit-sink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mariadb-audit-sink.d.ts","sourceRoot":"","sources":["../../src/adapters/mariadb-audit-sink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,MAAM,GAAE,eAAoB;IAMlC,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAmB/D"}
+{"version":3,"file":"mariadb-audit-sink.d.ts","sourceRoot":"","sources":["../../src/adapters/mariadb-audit-sink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,uFAAuF;IACvF,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IACnD,sCAAsC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B;;;;;OAKG;gBACS,MAAM,GAAE,eAAoB;IAOlC,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAmB/D"}

package/dist/adapters/mariadb-audit-sink.js

@@ -13,10 +13,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MariaDbAuditSink = void 0;
 const node_crypto_1 = require("node:crypto");
+const core_1 = require("@astram/core");
 class MariaDbAuditSink {
     ref;
+    /**
+     * Default schema (configurable-framework-db, spec 5.B): `config.schema`, else
+     * `config.schemas.audit`, else the audit name resolved from `SHIELD_DB_NAMESPACE` once, here at
+     * construction (boot), never per event. Unset namespace ⇒ today's default audit database. An
+     * invalid namespace throws (fail closed).
+     */
     constructor(config = {}) {
-        const schema = config.schema ?? 'shield_audit';
+        const schema = config.schema ?? config.schemas?.audit ?? (0, core_1.resolveFrameworkSchemas)(process.env).audit;
         const table = config.table ?? 'audit_log';
         this.ref = `\`${schema}\`.\`${table}\``;
     }

package/dist/decorators/object-type.decorator.d.ts

@@ -51,6 +51,16 @@ export interface ObjectTypeOptions {
      * omit-when-absent discipline as `junctions`/`extensible`. See {@link ReadScope}.
      */
     readonly readScope?: ReadScope;
+    /**
+     * OPTIONAL extra actions beyond CRUD (ADR-0038). Reflected AS-IS, omit-when-absent; the
+     * REGISTRY validates them at boot. See {@link ObjectTypeContract.actions}.
+     */
+    readonly actions?: readonly string[];
+    /**
+     * OPTIONAL CRUD opt-out (default `true`; `false` for authority-only types, ADR-0038).
+     * Reflected AS-IS, omit-when-absent (a defined `false` is kept).
+     */
+    readonly crudActions?: boolean;
 }
 /** Per-member options for `@Field` (the field's `key` is read from the member name). */
 export interface FieldOptions {

package/dist/decorators/object-type.decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"object-type.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/object-type.decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EACV,iBAAiB,EAEjB,SAAS,EACT,YAAY,EACZ,YAAY,EAKZ,UAAU,IAAI,kBAAkB,EAChC,UAAU,EACV,SAAS,EACT,aAAa,EACd,MAAM,aAAa,CAAC;AAarB;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAI3C;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAIlE;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAW,SAAQ,kBAAkB;CAAG;AAEzD;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,iBAAiB,CAO3D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAIlE;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,QAAQ,GAAG,kBAAkB,CA+BnE"}
+{"version":3,"file":"object-type.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/object-type.decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EACV,iBAAiB,EAEjB,SAAS,EACT,YAAY,EACZ,YAAY,EAKZ,UAAU,IAAI,kBAAkB,EAChC,UAAU,EACV,SAAS,EACT,aAAa,EACd,MAAM,aAAa,CAAC;AAarB;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAI3C;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAIlE;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAW,SAAQ,kBAAkB;CAAG;AAEzD;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,iBAAiB,CAO3D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAIlE;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,QAAQ,GAAG,kBAAkB,CAkCnE"}

package/dist/decorators/object-type.decorator.js

@@ -149,5 +149,10 @@ function reflectObjectType(cls) {
     // type without it omits the key (matching the literal), so `deepStrictEqual` holds.
     if (opts.readScope !== undefined)
         out.readScope = opts.readScope;
+    // `actions` / `crudActions` (ADR-0038): same omit-when-absent rule; a defined `false` is kept.
+    if (opts.actions !== undefined)
+        out.actions = opts.actions;
+    if (opts.crudActions !== undefined)
+        out.crudActions = opts.crudActions;
     return out;
 }

package/dist/index.d.ts

@@ -17,14 +17,16 @@
  *  - The raw unit of work (`MariaDbUnitOfWork`, it owns a pool) is NOT here: it is on
  *    `@astram/engine/internal`, which only the composition root may import.
  */
-export type { RecordEngine, AccessDeclaration, FieldSpec, FieldType, TrustedSource, IdentityRole, PkStrategy, JunctionSpec, RecordInput, RecordId, RecordView, ListQuery, RecordPage, Principal, ReadScope, ReadScopeCreateMode, } from './types.js';
+export type { RecordEngine, AccessDeclaration, FieldSpec, FieldType, TrustedSource, IdentityRole, PkStrategy, JunctionSpec, RecordInput, RecordId, RecordView, ListQuery, FilterOperator, FilterValue, WhereClause, SearchQuery, RecordPage, AggregateFn, AggregateMeasure, AggregateQuery, AggregateGroup, AggregateResult, Principal, ReadScope, ReadScopeCreateMode, } from './types.js';
 export { READ_SCOPE_NODES_TOKEN } from './types.js';
+export { FRAMEWORK_SCHEMA } from './types.js';
+export { resolveObjectTypeSchema, type FrameworkSchemaNames } from './registry.js';
 export { canonicalUuid } from './uuid.js';
 export { EngineError, CapabilityNotSupportedError, RegistrationError, AuthorizationDeniedError, ValidationError, EngineUnavailableError, } from './errors.js';
 export { ObjectType, Field, PrimaryKey, reflectObjectType, type ObjectTypeOptions, type FieldOptions, type PrimaryKeyOptions, } from './decorators/object-type.decorator.js';
 export { AccessBundle, reflectAccessBundle, type AccessBundleOptions, type AccessBundlePermission, type AccessBundleSpec, } from './decorators/access-bundle.decorator.js';
 export { EngineModule, RECORD_ENGINE, ENGINE_ALL_REGISTRATIONS, ENGINE_ALL_ACCESS_BUNDLES, type EngineModuleOptions, type ObjectTypeInput, } from './module/engine.module.js';
-export { TableRegistry, columnOf, uuidPkColumn, isOwned, ownerColumn, tenantColumnOf, columnForRole, requireRole, } from './registry.js';
+export { TableRegistry, columnOf, uuidPkColumn, isOwned, ownerColumn, tenantColumnOf, columnForRole, requireRole, effectiveActions, } from './registry.js';
 export { RecordEngineImpl, type RecordEngineDeps } from './pipe/record-engine.js';
 export { RecordsService, BoundRecords, type ServiceAccountResolver, SERVICE_ACCOUNT_RESOLVER, } from './pipe/records-service.js';
 export type { EngineDbConfig } from './adapters/mariadb-unit-of-work.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACV,SAAS,EACT,SAAS,EACT,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAKpD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EACL,WAAW,EACX,2BAA2B,EAC3B,iBAAiB,EACjB,wBAAwB,EACxB,eAAe,EACf,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAiBrB,OAAO,EACL,UAAU,EACV,KAAK,EACL,UAAU,EACV,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACvB,MAAM,uCAAuC,CAAC;AAO/C,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACtB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,YAAY,EACZ,aAAa,EACb,wBAAwB,EACxB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EACL,cAAc,EACd,YAAY,EACZ,KAAK,sBAAsB,EAC3B,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAC1F,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC/E,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EACV,SAAS,EACT,cAAc,EACd,WAAW,EACX,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,eAAe,EACf,SAAS,EACT,SAAS,EACT,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAMpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAKnF,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EACL,WAAW,EACX,2BAA2B,EAC3B,iBAAiB,EACjB,wBAAwB,EACxB,eAAe,EACf,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAiBrB,OAAO,EACL,UAAU,EACV,KAAK,EACL,UAAU,EACV,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACvB,MAAM,uCAAuC,CAAC;AAO/C,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACtB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,YAAY,EACZ,aAAa,EACb,wBAAwB,EACxB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,EACX,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EACL,cAAc,EACd,YAAY,EACZ,KAAK,sBAAsB,EAC3B,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAC1F,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC/E,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -19,12 +19,20 @@
  *    `@astram/engine/internal`, which only the composition root may import.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MariaDbAuditSink = exports.SERVICE_ACCOUNT_RESOLVER = exports.BoundRecords = exports.RecordsService = exports.RecordEngineImpl = exports.requireRole = exports.columnForRole = exports.tenantColumnOf = exports.ownerColumn = exports.isOwned = exports.uuidPkColumn = exports.columnOf = exports.TableRegistry = exports.ENGINE_ALL_ACCESS_BUNDLES = exports.ENGINE_ALL_REGISTRATIONS = exports.RECORD_ENGINE = exports.EngineModule = exports.reflectAccessBundle = exports.AccessBundle = exports.reflectObjectType = exports.PrimaryKey = exports.Field = exports.ObjectType = exports.EngineUnavailableError = exports.ValidationError = exports.AuthorizationDeniedError = exports.RegistrationError = exports.CapabilityNotSupportedError = exports.EngineError = exports.canonicalUuid = exports.READ_SCOPE_NODES_TOKEN = void 0;
+exports.MariaDbAuditSink = exports.SERVICE_ACCOUNT_RESOLVER = exports.BoundRecords = exports.RecordsService = exports.RecordEngineImpl = exports.effectiveActions = exports.requireRole = exports.columnForRole = exports.tenantColumnOf = exports.ownerColumn = exports.isOwned = exports.uuidPkColumn = exports.columnOf = exports.TableRegistry = exports.ENGINE_ALL_ACCESS_BUNDLES = exports.ENGINE_ALL_REGISTRATIONS = exports.RECORD_ENGINE = exports.EngineModule = exports.reflectAccessBundle = exports.AccessBundle = exports.reflectObjectType = exports.PrimaryKey = exports.Field = exports.ObjectType = exports.EngineUnavailableError = exports.ValidationError = exports.AuthorizationDeniedError = exports.RegistrationError = exports.CapabilityNotSupportedError = exports.EngineError = exports.canonicalUuid = exports.resolveObjectTypeSchema = exports.FRAMEWORK_SCHEMA = exports.READ_SCOPE_NODES_TOKEN = void 0;
 // The read-scope subtree-id placeholder token (ADR-0027) — a `subtreeSubquery` template
 // uses it; the engine expands it to a `?`-list. Exported so per-type declarations can
 // reference the canonical token (rather than a stringly-typed duplicate).
 var types_js_1 = require("./types.js");
 Object.defineProperty(exports, "READ_SCOPE_NODES_TOKEN", { enumerable: true, get: function () { return types_js_1.READ_SCOPE_NODES_TOKEN; } });
+// Framework database placeholder tokens (configurable-framework-db, ADR-0037): a framework object
+// type declares `schema: FRAMEWORK_SCHEMA.app` (and may use the tokens in `readScope.subquerySql`);
+// the engine resolves them at registration. Any other reader of an object type's schema calls
+// `resolveObjectTypeSchema(reg, schemas)` before building SQL; an unresolved token throws.
+var types_js_2 = require("./types.js");
+Object.defineProperty(exports, "FRAMEWORK_SCHEMA", { enumerable: true, get: function () { return types_js_2.FRAMEWORK_SCHEMA; } });
+var registry_js_1 = require("./registry.js");
+Object.defineProperty(exports, "resolveObjectTypeSchema", { enumerable: true, get: function () { return registry_js_1.resolveObjectTypeSchema; } });
 // The ONE uuid canonicaliser (Phase 11 #1): strict 8-4-4-4-12 ASCII hex, returned lower-cased;
 // anything else (padded, fullwidth, ...) is null. Guard's `UuidPipe` and the identity body checks
 // use it; consumers may too.
@@ -71,15 +79,16 @@ Object.defineProperty(exports, "RECORD_ENGINE", { enumerable: true, get: functio
 Object.defineProperty(exports, "ENGINE_ALL_REGISTRATIONS", { enumerable: true, get: function () { return engine_module_js_1.ENGINE_ALL_REGISTRATIONS; } });
 Object.defineProperty(exports, "ENGINE_ALL_ACCESS_BUNDLES", { enumerable: true, get: function () { return engine_module_js_1.ENGINE_ALL_ACCESS_BUNDLES; } });
 // --- Framework-facing (composition + tests; NOT for feature code) ------------
-var registry_js_1 = require("./registry.js");
-Object.defineProperty(exports, "TableRegistry", { enumerable: true, get: function () { return registry_js_1.TableRegistry; } });
-Object.defineProperty(exports, "columnOf", { enumerable: true, get: function () { return registry_js_1.columnOf; } });
-Object.defineProperty(exports, "uuidPkColumn", { enumerable: true, get: function () { return registry_js_1.uuidPkColumn; } });
-Object.defineProperty(exports, "isOwned", { enumerable: true, get: function () { return registry_js_1.isOwned; } });
-Object.defineProperty(exports, "ownerColumn", { enumerable: true, get: function () { return registry_js_1.ownerColumn; } });
-Object.defineProperty(exports, "tenantColumnOf", { enumerable: true, get: function () { return registry_js_1.tenantColumnOf; } });
-Object.defineProperty(exports, "columnForRole", { enumerable: true, get: function () { return registry_js_1.columnForRole; } });
-Object.defineProperty(exports, "requireRole", { enumerable: true, get: function () { return registry_js_1.requireRole; } });
+var registry_js_2 = require("./registry.js");
+Object.defineProperty(exports, "TableRegistry", { enumerable: true, get: function () { return registry_js_2.TableRegistry; } });
+Object.defineProperty(exports, "columnOf", { enumerable: true, get: function () { return registry_js_2.columnOf; } });
+Object.defineProperty(exports, "uuidPkColumn", { enumerable: true, get: function () { return registry_js_2.uuidPkColumn; } });
+Object.defineProperty(exports, "isOwned", { enumerable: true, get: function () { return registry_js_2.isOwned; } });
+Object.defineProperty(exports, "ownerColumn", { enumerable: true, get: function () { return registry_js_2.ownerColumn; } });
+Object.defineProperty(exports, "tenantColumnOf", { enumerable: true, get: function () { return registry_js_2.tenantColumnOf; } });
+Object.defineProperty(exports, "columnForRole", { enumerable: true, get: function () { return registry_js_2.columnForRole; } });
+Object.defineProperty(exports, "requireRole", { enumerable: true, get: function () { return registry_js_2.requireRole; } });
+Object.defineProperty(exports, "effectiveActions", { enumerable: true, get: function () { return registry_js_2.effectiveActions; } });
 var record_engine_js_1 = require("./pipe/record-engine.js");
 Object.defineProperty(exports, "RecordEngineImpl", { enumerable: true, get: function () { return record_engine_js_1.RecordEngineImpl; } });
 var records_service_js_1 = require("./pipe/records-service.js");

package/dist/module/engine.module.d.ts

@@ -18,6 +18,7 @@
  * Registrations are code-registered tables loaded at boot.
  */
 import { type DynamicModule } from '@nestjs/common';
+import { type FrameworkSchemas } from '@astram/core';
 import type { QueryFn } from '../ports.js';
 import { RECORD_ENGINE } from './tokens.js';
 import { type EngineDbConfig } from '../adapters/mariadb-unit-of-work.js';
@@ -56,6 +57,13 @@ export interface EngineModuleOptions {
      *  feature module; anything passed here is merged as a base contribution. */
     readonly registrations?: readonly ObjectTypeInput[];
     readonly audit?: AuditSinkConfig;
+    /**
+     * OPTIONAL resolved framework database names (configurable-framework-db, ADR-0037).
+     * `FRAMEWORK_SCHEMA` tokens in registrations resolve to these, and the default audit sink
+     * writes to `schemas.audit`. Absent ⇒ resolved once from `SHIELD_DB_NAMESPACE` when
+     * `forRoot` is called (unset ⇒ today's names; invalid ⇒ throws, fail closed).
+     */
+    readonly schemas?: FrameworkSchemas;
     /** Test seam: a deterministic clock. */
     readonly nowMs?: () => number;
     /**

package/dist/module/engine.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.module.d.ts","sourceRoot":"","sources":["../../src/module/engine.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAEL,KAAK,aAAa,EAKnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAuC,OAAO,EAAE,MAAM,aAAa,CAAC;AAIhF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC7F,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,0CAA0C,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,QAAQ,CAAC;AAMpD;;;;2EAI2E;AAC3E,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB;;;;qCAIqC;AACrC,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;+CAI+C;AAC/C,eAAO,MAAM,yBAAyB,eAAsC,CAAC;AAmC7E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B;iFAC6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CACnB,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,KACX,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;KAAE,CAAC,CAAC;CAC3D;AAYD,qBACa,YAAY;IACvB;;;;;;;;;OASG;IACH,MAAM,CAAC,UAAU,CACf,aAAa,EAAE,SAAS,eAAe,EAAE,EACzC,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,SAAS,CAAC,gBAAgB,GAAG,QAAQ,CAAC,EAAE,CAAA;KAAE,GAClE,aAAa;IAMhB;2FACuF;IACvF,MAAM,CAAC,aAAa,IAAI,IAAI;IAK5B,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,aAAa;CAiG5D"}
+{"version":3,"file":"engine.module.d.ts","sourceRoot":"","sources":["../../src/module/engine.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAEL,KAAK,aAAa,EAKnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAuC,OAAO,EAAE,MAAM,aAAa,CAAC;AAIhF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC7F,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,0CAA0C,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,QAAQ,CAAC;AAMpD;;;;2EAI2E;AAC3E,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB;;;;qCAIqC;AACrC,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;+CAI+C;AAC/C,eAAO,MAAM,yBAAyB,eAAsC,CAAC;AAmC7E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B;iFAC6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IACpC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CACnB,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,KACX,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;KAAE,CAAC,CAAC;CAC3D;AAYD,qBACa,YAAY;IACvB;;;;;;;;;OASG;IACH,MAAM,CAAC,UAAU,CACf,aAAa,EAAE,SAAS,eAAe,EAAE,EACzC,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,SAAS,CAAC,gBAAgB,GAAG,QAAQ,CAAC,EAAE,CAAA;KAAE,GAClE,aAAa;IAMhB;2FACuF;IACvF,MAAM,CAAC,aAAa,IAAI,IAAI;IAK5B,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,aAAa;CAqG5D"}

package/dist/module/engine.module.js

@@ -136,12 +136,15 @@ let EngineModule = EngineModule_1 = class EngineModule {
             ...featureRegistrations.flat(),
             ...(options.registrations ?? []),
         ].map(toObjectType);
-        // The registry is built from the merged set. Behavior identical to before — same
-        // register() per registration (just from the collected set, not options only).
+        // The framework database names, resolved ONCE here (boot) and captured: registration
+        // tokens and the default audit sink use them; nothing reads env per request (Shield #12).
+        const schemas = options.schemas ?? (0, core_1.resolveFrameworkSchemas)(process.env);
+        // The registry is built from the merged set — same register() per registration (just from
+        // the collected set, not options only); `FRAMEWORK_SCHEMA` tokens resolve at register.
         const registryProvider = {
             provide: ENGINE_REGISTRY,
             useFactory: () => {
-                const registry = new registry_js_1.TableRegistry();
+                const registry = new registry_js_1.TableRegistry(schemas);
                 for (const reg of allRegistrations)
                     registry.register(reg);
                 return registry;
@@ -169,7 +172,7 @@ let EngineModule = EngineModule_1 = class EngineModule {
         };
         const auditProvider = {
             provide: ENGINE_AUDIT,
-            useFactory: () => new mariadb_audit_sink_js_1.MariaDbAuditSink(options.audit ?? {}),
+            useFactory: () => new mariadb_audit_sink_js_1.MariaDbAuditSink({ schemas, ...options.audit }),
         };
         const engineProvider = {
             provide: tokens_js_1.RECORD_ENGINE,

package/dist/pipe/context.d.ts

@@ -54,6 +54,14 @@ export interface WriteContext extends PipeBase {
      * falls back to the actor's tenant. NEVER set for create.
      */
     recordTenantId?: string;
+    /**
+     * Set only for a row of a `createMany()` call: the call's one `batchId` and this row's 0-based
+     * index. Changes nothing but the audit attributes; single-row writes never carry it.
+     */
+    batch?: {
+        readonly id: string;
+        readonly index: number;
+    };
 }
 /** A stage: a small, ordered, independently-testable unit of the pipe. */
 export interface Stage {

package/dist/pipe/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/pipe/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,gDAAgD;AAChD,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAErD,6DAA6D;AAC7D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC;IAClC,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,kCAAkC;AAClC,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,+CAA+C;IAC/C,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,8CAA8C;IAC9C,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAC7C,oEAAoE;IACpE,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,KAAK;IACpB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAO5F"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/pipe/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,gDAAgD;AAChD,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAErD,6DAA6D;AAC7D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC;IAClC,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,kCAAkC;AAClC,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,+CAA+C;IAC/C,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,8CAA8C;IAC9C,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAC7C,oEAAoE;IACpE,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACzD;AAED,0EAA0E;AAC1E,MAAM,WAAW,KAAK;IACpB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAO5F"}

package/dist/pipe/filter-sql.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure SQL-fragment helpers for list reads (list-query-operators, SPEC v2 §5.B).
+ *
+ * `resolveColumn` is the ONE whitelisted field-key → column lookup the list read uses for
+ * filter, search and sort keys (later group and measure keys). The column is always the type's
+ * own registered column; an unknown key throws before any SQL is built.
+ */
+import type { AggregateFn, AggregateMeasure, FieldSpec, FilterOperator, ObjectType, WhereClause } from '../types.js';
+/** What a list key is used for; names the key in the unknown-field error. */
+export type ColumnUse = 'filter' | 'search' | 'sort' | 'groupBy' | 'measure';
+/**
+ * Resolve a registered field key to its field and physical column, or throw
+ * `RegistrationError("list '<typeKey>': unknown <what> field '<key>'")`.
+ */
+export declare function resolveColumn(reg: ObjectType, fieldKey: string, typeKey: string, what: ColumnUse): {
+    field: FieldSpec;
+    column: string;
+};
+/** The `where` operators (SPEC v2 §10), exactly these keys. */
+export declare const FILTER_OPERATORS: ReadonlySet<FilterOperator>;
+/** Maximum number of values in one `in` operand (SPEC v2 §10). */
+export declare const IN_CAP = 1000;
+/**
+ * Build the `where` clauses of a list read (SPEC v2 §5.A). Pure and deterministic: one clause
+ * per entry in object key order, ANDed by the caller.
+ *
+ * - Identifiers come only from `resolveColumn` (registered field → its column); unknown key ⇒
+ *   `RegistrationError`.
+ * - Every operand passes through `coerce` (a bad one ⇒ `ValidationError(fieldKey)`) and is a
+ *   `?` param; no value is ever interpolated.
+ * - A scalar is equality (`null` ⇒ `IS NULL`); an object holds exactly one §10 operator.
+ *   Anything malformed or not allowed for the field type throws `RegistrationError`; it never
+ *   degrades to "no filter" (Shield #1).
+ */
+export declare function buildFilterClauses(reg: ObjectType, where: WhereClause | undefined, typeKey: string): {
+    clauses: string[];
+    params: unknown[];
+};
+/** Aggregate caps (SPEC v2 §10). */
+export declare const GROUP_BY_CAP = 3;
+export declare const MEASURE_CAP = 10;
+/** How the engine converts one measure's driver value (SPEC v2 §11). */
+export interface AggregateColumn {
+    readonly alias: string;
+    /** `count`/`sum`/`avg`, or `min`/`max` on a `number` field: BigInt/DECIMAL ⇒ `number`. */
+    readonly numeric: boolean;
+    readonly fn: AggregateFn;
+}
+/**
+ * Build the SELECT list, GROUP BY and ORDER BY of an aggregate (SPEC v2 §5.C). Pure.
+ *
+ * - `select`: group columns first as `` `col` AS `k_<n>` ``, then each measure
+ *   `` FN(`col`|*) AS `alias` ``. `groupBy`/`orderBy` are the group columns in order, WITHOUT the
+ *   keyword (empty strings when ungrouped). `keyMap` maps `k_<n>` back to the group field key.
+ * - Identifiers come only from `resolveColumn` (registered field → its column) or from an alias
+ *   that passed `ALIAS_RE` (no backquote possible) before it is backquoted. Anything malformed
+ *   throws `RegistrationError` before any SQL is built.
+ */
+export declare function buildAggregateSelect(reg: ObjectType, groupBy: readonly string[] | undefined, measures: readonly AggregateMeasure[], typeKey: string): {
+    select: string;
+    groupBy: string;
+    orderBy: string;
+    keyMap: Record<string, string>;
+    columns: readonly AggregateColumn[];
+};
+//# sourceMappingURL=filter-sql.d.ts.map

package/dist/pipe/filter-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-sql.d.ts","sourceRoot":"","sources":["../../src/pipe/filter-sql.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EACV,WAAW,EACX,gBAAgB,EAChB,SAAS,EAET,cAAc,EACd,UAAU,EACV,WAAW,EACZ,MAAM,aAAa,CAAC;AAErB,6EAA6E;AAC7E,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAE7E;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,GACd;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAMtC;AAED,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,cAAc,CAUvD,CAAC;AAEH,kEAAkE;AAClE,eAAO,MAAM,MAAM,OAAO,CAAC;AAmB3B;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,OAAO,EAAE,MAAM,GACd;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CAwF1C;AAED,oCAAoC;AACpC,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,WAAW,KAAK,CAAC;AAgB9B,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACtC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,OAAO,EAAE,MAAM,GACd;IACD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;CACrC,CA4EA"}

package/dist/pipe/filter-sql.js

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * Pure SQL-fragment helpers for list reads (list-query-operators, SPEC v2 §5.B).
+ *
+ * `resolveColumn` is the ONE whitelisted field-key → column lookup the list read uses for
+ * filter, search and sort keys (later group and measure keys). The column is always the type's
+ * own registered column; an unknown key throws before any SQL is built.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEASURE_CAP = exports.GROUP_BY_CAP = exports.IN_CAP = exports.FILTER_OPERATORS = void 0;
+exports.resolveColumn = resolveColumn;
+exports.buildFilterClauses = buildFilterClauses;
+exports.buildAggregateSelect = buildAggregateSelect;
+const errors_js_1 = require("../errors.js");
+const registry_js_1 = require("../registry.js");
+const validate_js_1 = require("./stages/validate.js");
+/**
+ * Resolve a registered field key to its field and physical column, or throw
+ * `RegistrationError("list '<typeKey>': unknown <what> field '<key>'")`.
+ */
+function resolveColumn(reg, fieldKey, typeKey, what) {
+    const field = reg.fields.find((f) => f.key === fieldKey);
+    if (!field) {
+        throw new errors_js_1.RegistrationError(`list '${typeKey}': unknown ${what} field '${fieldKey}'`);
+    }
+    return { field, column: (0, registry_js_1.columnOf)(field) };
+}
+/** The `where` operators (SPEC v2 §10), exactly these keys. */
+exports.FILTER_OPERATORS = new Set([
+    'eq',
+    'in',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'between',
+    'isNull',
+    'isNotNull',
+]);
+/** Maximum number of values in one `in` operand (SPEC v2 §10). */
+exports.IN_CAP = 1000;
+/** Field types the range operators (`gt|gte|lt|lte|between`) accept (SPEC v2 §10). */
+const RANGE_TYPES = new Set([
+    'string',
+    'number',
+    'uuid',
+    'timestamp',
+]);
+const RANGE_SQL = { gt: '>', gte: '>=', lt: '<', lte: '<=' };
+/** A plain operator object: not `null`, not a `Date`, not an array. */
+function isOperatorObject(value) {
+    return (typeof value === 'object' && value !== null && !(value instanceof Date) && !Array.isArray(value));
+}
+/**
+ * Build the `where` clauses of a list read (SPEC v2 §5.A). Pure and deterministic: one clause
+ * per entry in object key order, ANDed by the caller.
+ *
+ * - Identifiers come only from `resolveColumn` (registered field → its column); unknown key ⇒
+ *   `RegistrationError`.
+ * - Every operand passes through `coerce` (a bad one ⇒ `ValidationError(fieldKey)`) and is a
+ *   `?` param; no value is ever interpolated.
+ * - A scalar is equality (`null` ⇒ `IS NULL`); an object holds exactly one §10 operator.
+ *   Anything malformed or not allowed for the field type throws `RegistrationError`; it never
+ *   degrades to "no filter" (Shield #1).
+ */
+function buildFilterClauses(reg, where, typeKey) {
+    const clauses = [];
+    const params = [];
+    for (const [fieldKey, value] of Object.entries(where ?? {})) {
+        const { field, column } = resolveColumn(reg, fieldKey, typeKey, 'filter');
+        const col = `\`${column}\``;
+        const reject = (detail) => {
+            throw new errors_js_1.RegistrationError(`list '${typeKey}': filter on '${fieldKey}': ${detail}`);
+        };
+        // Scalar form: `null` ⇒ IS NULL (business rule §11); otherwise equality.
+        if (value === null) {
+            clauses.push(`${col} IS NULL`);
+            continue;
+        }
+        if (Array.isArray(value))
+            reject('an array value needs the `in` operator');
+        if (!isOperatorObject(value)) {
+            if (field.type === 'json')
+                reject("operator 'eq' is not allowed on a json field");
+            clauses.push(`${col} = ?`);
+            params.push((0, validate_js_1.coerce)(field, value));
+            continue;
+        }
+        // Operator form: exactly one known operator key.
+        const opObject = value;
+        const keys = Object.keys(opObject);
+        if (keys.length !== 1)
+            reject(`expected exactly one operator, got ${keys.length}`);
+        const op = keys[0];
+        if (!exports.FILTER_OPERATORS.has(op))
+            reject(`unknown operator '${keys[0]}'`);
+        const operand = opObject[op];
+        switch (op) {
+            case 'isNull':
+            case 'isNotNull':
+                if (operand !== true)
+                    reject(`operator '${op}' only accepts true`);
+                clauses.push(op === 'isNull' ? `${col} IS NULL` : `${col} IS NOT NULL`);
+                break;
+            case 'eq':
+                if (field.type === 'json')
+                    reject("operator 'eq' is not allowed on a json field");
+                clauses.push(`${col} = ?`);
+                params.push((0, validate_js_1.coerce)(field, operand));
+                break;
+            case 'in': {
+                if (field.type === 'json')
+                    reject("operator 'in' is not allowed on a json field");
+                if (!Array.isArray(operand))
+                    reject("operator 'in' needs an array");
+                const values = operand;
+                if (values.length > exports.IN_CAP)
+                    reject(`operator 'in' accepts at most ${exports.IN_CAP} values`);
+                if (values.length === 0) {
+                    clauses.push('FALSE');
+                    break;
+                }
+                const coerced = values.map((v) => (0, validate_js_1.coerce)(field, v));
+                clauses.push(`${col} IN (${coerced.map(() => '?').join(', ')})`);
+                params.push(...coerced);
+                break;
+            }
+            case 'gt':
+            case 'gte':
+            case 'lt':
+            case 'lte':
+                if (!RANGE_TYPES.has(field.type)) {
+                    reject(`operator '${op}' is not allowed on a ${field.type} field`);
+                }
+                clauses.push(`${col} ${RANGE_SQL[op]} ?`);
+                params.push((0, validate_js_1.coerce)(field, operand));
+                break;
+            case 'between': {
+                if (!RANGE_TYPES.has(field.type)) {
+                    reject(`operator 'between' is not allowed on a ${field.type} field`);
+                }
+                if (!Array.isArray(operand) || operand.length !== 2) {
+                    reject("operator 'between' needs a 2-element array");
+                }
+                const [lo, hi] = operand;
+                const coercedLo = (0, validate_js_1.coerce)(field, lo);
+                const coercedHi = (0, validate_js_1.coerce)(field, hi);
+                clauses.push(`${col} BETWEEN ? AND ?`);
+                params.push(coercedLo, coercedHi);
+                break;
+            }
+            default:
+                // Unreachable (FILTER_OPERATORS checked above); fail closed regardless.
+                reject(`unknown operator '${String(op)}'`);
+        }
+    }
+    return { clauses, params };
+}
+/** Aggregate caps (SPEC v2 §10). */
+exports.GROUP_BY_CAP = 3;
+exports.MEASURE_CAP = 10;
+/** A measure alias: lower-case identifier, ≤ 64 chars (SPEC v2 §10). */
+const ALIAS_RE = /^[a-z_][a-z0-9_]{0,63}$/;
+const AGGREGATE_SQL = {
+    count: 'COUNT',
+    sum: 'SUM',
+    avg: 'AVG',
+    min: 'MIN',
+    max: 'MAX',
+};
+/** Field types `min`/`max` accept (SPEC v2 §10); `sum`/`avg` accept `number` only. */
+const MIN_MAX_TYPES = RANGE_TYPES;
+/**
+ * Build the SELECT list, GROUP BY and ORDER BY of an aggregate (SPEC v2 §5.C). Pure.
+ *
+ * - `select`: group columns first as `` `col` AS `k_<n>` ``, then each measure
+ *   `` FN(`col`|*) AS `alias` ``. `groupBy`/`orderBy` are the group columns in order, WITHOUT the
+ *   keyword (empty strings when ungrouped). `keyMap` maps `k_<n>` back to the group field key.
+ * - Identifiers come only from `resolveColumn` (registered field → its column) or from an alias
+ *   that passed `ALIAS_RE` (no backquote possible) before it is backquoted. Anything malformed
+ *   throws `RegistrationError` before any SQL is built.
+ */
+function buildAggregateSelect(reg, groupBy, measures, typeKey) {
+    const reject = (detail) => {
+        throw new errors_js_1.RegistrationError(`aggregate '${typeKey}': ${detail}`);
+    };
+    const groups = groupBy ?? [];
+    if (!Array.isArray(groups))
+        reject('groupBy must be an array of field keys');
+    if (groups.length > exports.GROUP_BY_CAP)
+        reject(`groupBy accepts at most ${exports.GROUP_BY_CAP} keys`);
+    const groupCols = [];
+    const selectParts = [];
+    const keyMap = {};
+    groups.forEach((key, i) => {
+        if (groups.indexOf(key) !== i)
+            reject(`duplicate groupBy key '${key}'`);
+        const { field, column } = resolveColumn(reg, key, typeKey, 'groupBy');
+        if (field.type === 'json')
+            reject(`groupBy on json field '${key}' is not allowed`);
+        const alias = `k_${i}`;
+        groupCols.push(`\`${column}\``);
+        selectParts.push(`\`${column}\` AS \`${alias}\``);
+        keyMap[alias] = key;
+    });
+    if (!Array.isArray(measures) || measures.length === 0)
+        reject('at least one measure is required');
+    if (measures.length > exports.MEASURE_CAP)
+        reject(`at most ${exports.MEASURE_CAP} measures are allowed`);
+    const aliases = new Set();
+    const columns = [];
+    for (const raw of measures) {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            reject('each measure must be an object');
+        }
+        const m = raw;
+        const alias = m.as;
+        if (typeof alias !== 'string' || !ALIAS_RE.test(alias)) {
+            reject(`measure alias '${String(alias)}' must match ${String(ALIAS_RE)}`);
+        }
+        // `__proto__` matches ALIAS_RE but is the one name that, assigned on a plain object, would set
+        // the prototype of the shaped result instead of creating a key: reject it outright.
+        if (alias === '__proto__')
+            reject(`measure alias '${alias}' is reserved`);
+        if (aliases.has(alias))
+            reject(`duplicate measure alias '${alias}'`);
+        // A measure alias may not shadow a group key or a generated `k_<n>` group column. Own-property
+        // check only: `in` walks the prototype chain and would reject `constructor`, `toString`, ….
+        if (groups.includes(alias) || Object.prototype.hasOwnProperty.call(keyMap, alias)) {
+            reject(`measure alias '${alias}' collides with a groupBy key`);
+        }
+        aliases.add(alias);
+        const fn = m.fn;
+        if (!Object.prototype.hasOwnProperty.call(AGGREGATE_SQL, fn)) {
+            reject(`unknown aggregate function '${String(fn)}'`);
+        }
+        let arg = '*';
+        let numeric = fn === 'count' || fn === 'sum' || fn === 'avg';
+        if (m.field === undefined) {
+            if (fn !== 'count')
+                reject(`'${fn}' needs a field`);
+        }
+        else {
+            const { field, column } = resolveColumn(reg, m.field, typeKey, 'measure');
+            if ((fn === 'sum' || fn === 'avg') && field.type !== 'number') {
+                reject(`'${fn}' is not allowed on ${field.type} field '${m.field}'`);
+            }
+            if ((fn === 'min' || fn === 'max') && !MIN_MAX_TYPES.has(field.type)) {
+                reject(`'${fn}' is not allowed on ${field.type} field '${m.field}'`);
+            }
+            if (field.type === 'number')
+                numeric = true;
+            arg = `\`${column}\``;
+        }
+        selectParts.push(`${AGGREGATE_SQL[fn]}(${arg}) AS \`${alias}\``);
+        columns.push({ alias, numeric, fn });
+    }
+    const groupList = groupCols.join(', ');
+    return {
+        select: selectParts.join(', '),
+        groupBy: groupList,
+        orderBy: groupCols.map((c) => `${c} ASC`).join(', '),
+        keyMap,
+        columns,
+    };
+}