@astram/engine 0.6.0 → 0.8.0

package/dist/pipe/record-engine.d.ts

@@ -17,7 +17,7 @@
  */
 import type { TableRegistry } from '../registry.js';
 import type { AuditPort, DecisionPort, UnitOfWork, QueryFn } from '../ports.js';
-import type { ListQuery, Principal, RecordEngine, RecordId, RecordInput, RecordPage, RecordView, ObjectType } from '../types.js';
+import type { AggregateQuery, AggregateResult, ListQuery, Principal, RecordEngine, RecordId, RecordInput, RecordPage, RecordView, ObjectType } from '../types.js';
 export interface RecordEngineDeps {
     readonly registry: TableRegistry;
     readonly uow: UnitOfWork;
@@ -98,6 +98,14 @@ export declare class RecordEngineImpl implements RecordEngine {
      */
     lockForUpdate(typeKey: string, id: RecordId, actor: Principal): Promise<void>;
     private lockIn;
+    /** Record-level decision for one declared action, no write (see `RecordEngine.authorize`). */
+    authorize(typeKey: string, id: RecordId, action: string, actor: Principal): Promise<void>;
+    /**
+     * The write path's gates without the write (SPEC §5 E): declared action → type pre-gate (no
+     * SQL) → `whereById` fetch → record-level decide on the row's facts and tenant. Read-only unit,
+     * so a deny never makes an open transaction rollback-only. No audit, no list scope.
+     */
+    private authorizeIn;
     /**
      * Run one op's body in the right unit of work: the bound/ambient transaction when there is
      * one, else a fresh `uow.run` (the original per-op transaction). A WRITE failure inside a
@@ -108,7 +116,16 @@ export declare class RecordEngineImpl implements RecordEngine {
     create(typeKey: string, input: RecordInput, actor: Principal): Promise<RecordId>;
     update(typeKey: string, id: RecordId, input: RecordInput, actor: Principal): Promise<void>;
     delete(typeKey: string, id: RecordId, actor: Principal): Promise<void>;
+    createMany(typeKey: string, inputs: readonly RecordInput[], actor: Principal): Promise<RecordId[]>;
     private createIn;
+    /**
+     * Bulk = single (Shield #7, SPEC v2 §5.G): every row runs the unchanged single-row create pipe,
+     * in order, in ONE unit of work (joins an outer transaction). No batched INSERT, no decision
+     * shared across rows. The first failing row throws and rollback-only state discards the whole
+     * batch, its audit rows included. Inputs are checked before the type lookup and before any
+     * transaction opens, so a bad call neither touches the DB nor poisons an outer transaction.
+     */
+    private createManyIn;
     private updateIn;
     private deleteIn;
     private gateRead;
@@ -118,7 +135,23 @@ export declare class RecordEngineImpl implements RecordEngine {
     get(typeKey: string, id: RecordId, actor: Principal): Promise<RecordView | null>;
     list(typeKey: string, query: ListQuery, actor: Principal): Promise<RecordPage>;
     private getIn;
+    /**
+     * The ONE read WHERE of a list (SPEC v2 §5.D): list-scope fragment resolved first, tenant
+     * clause, readScope wall, equality `where`, search, list-scope fragment. Shared by the data
+     * SELECT and the COUNT (and later `aggregate`), so they cannot diverge. Async because it
+     * awaits the list-scope seam; takes no `q` (no DB read of its own). Callers run `gateRead`
+     * first.
+     */
+    private buildReadWhere;
     private listIn;
+    aggregate(typeKey: string, query: AggregateQuery, actor: Principal): Promise<AggregateResult>;
+    /**
+     * Aggregate over exactly the rows `list()` returns (SPEC v2 §5.F, Shield #8): the SAME gate
+     * (object-type `read`, first) and the SAME `buildReadWhere`, then ONE
+     * `SELECT … FROM <table> <where> [GROUP BY … ORDER BY …] LIMIT ?`. No table alias, so a
+     * list-scope fragment's bare columns resolve. Read-only: no audit row, no write.
+     */
+    private aggregateIn;
     /** The physical column of a `tenantId`-trusted field, if the table has one. */
     private tenantColumn;
     /**

package/dist/pipe/record-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record-engine.d.ts","sourceRoot":"","sources":["../../src/pipe/record-engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"record-engine.d.ts","sourceRoot":"","sources":["../../src/pipe/record-engine.ts"],"names":[],"mappings":"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"}

package/dist/pipe/record-engine.js

@@ -19,12 +19,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RecordEngineImpl = void 0;
 const node_async_hooks_1 = require("node:async_hooks");
+const node_crypto_1 = require("node:crypto");
 const errors_js_1 = require("../errors.js");
 const registry_js_1 = require("../registry.js");
 const types_js_1 = require("../types.js");
 const context_js_1 = require("./context.js");
 const fetch_record_js_1 = require("./stages/fetch-record.js");
 const where_by_id_js_1 = require("./where-by-id.js");
+const filter_sql_js_1 = require("./filter-sql.js");
 const permission_gate_js_1 = require("./stages/permission-gate.js");
 const derive_write_context_js_1 = require("./stages/derive-write-context.js");
 const validate_js_1 = require("./stages/validate.js");
@@ -32,6 +34,8 @@ const write_js_1 = require("./stages/write.js");
 const junction_sync_js_1 = require("./stages/junction-sync.js");
 const audit_js_1 = require("./stages/audit.js");
 const errors_js_2 = require("../errors.js");
+/** `createMany` row cap (list-query-operators SPEC v2 §10). */
+const CREATE_MANY_CAP = 500;
 /** Fail closed when a transaction handle outlives its transaction or is already doomed. */
 function assertUsable(tx) {
     if (!tx.open) {
@@ -132,6 +136,9 @@ class RecordEngineImpl {
             list: (typeKey, query, actor) => this.listIn(state, typeKey, query, actor),
             transaction: (fn) => this.transactionIn(state, fn),
             lockForUpdate: (typeKey, id, actor) => this.lockIn(state, typeKey, id, actor),
+            authorize: (typeKey, id, action, actor) => this.authorizeIn(state, typeKey, id, action, actor),
+            aggregate: (typeKey, query, actor) => this.aggregateIn(state, typeKey, query, actor),
+            createMany: (typeKey, inputs, actor) => this.createManyIn(state, typeKey, inputs, actor),
         };
     }
     /**
@@ -152,6 +159,33 @@ class RecordEngineImpl {
         const where = (0, where_by_id_js_1.pkClause)(reg, id);
         await tx.query(`SELECT 1 AS locked FROM ${this.qualified(reg)} WHERE ${where.sql} FOR UPDATE`, where.params);
     }
+    /** Record-level decision for one declared action, no write (see `RecordEngine.authorize`). */
+    async authorize(typeKey, id, action, actor) {
+        return this.authorizeIn(undefined, typeKey, id, action, actor);
+    }
+    /**
+     * The write path's gates without the write (SPEC §5 E): declared action → type pre-gate (no
+     * SQL) → `whereById` fetch → record-level decide on the row's facts and tenant. Read-only unit,
+     * so a deny never makes an open transaction rollback-only. No audit, no list scope.
+     */
+    async authorizeIn(bound, typeKey, id, action, actor) {
+        const reg = this.registry.require(typeKey);
+        if (!(0, registry_js_1.effectiveActions)(reg).includes(action)) {
+            throw new errors_js_1.RegistrationError(`action '${action}' is not declared on type '${typeKey}'`);
+        }
+        const label = `authorize ${action} ${typeKey}`;
+        await (0, permission_gate_js_1.decideOrThrow)(this.decision, actor, { key: action }, { level: 'object_type', typeKey, tenantId: actor.tenantId }, { isAuthenticated: true }, label);
+        const lock = (bound ?? this.activeTx.getStore()) !== undefined;
+        await this.inUnit(bound, false, async (query) => {
+            const facts = await (0, fetch_record_js_1.fetchRecordFacts)(reg, actor, id, query, { lock });
+            await (0, permission_gate_js_1.decideOrThrow)(this.decision, actor, { key: action }, {
+                level: 'record',
+                typeKey,
+                tenantId: facts.tenantId ?? actor.tenantId,
+                ...(typeof id === 'string' ? { recordId: id } : {}),
+            }, { isAuthenticated: true, attributes: (0, fetch_record_js_1.decisionAttributes)(reg, facts) }, label);
+        });
+    }
     /**
      * Run one op's body in the right unit of work: the bound/ambient transaction when there is
      * one, else a fresh `uow.run` (the original per-op transaction). A WRITE failure inside a
@@ -173,11 +207,17 @@ class RecordEngineImpl {
     }
     async runWrite(tx, op, typeKey, actor, opts) {
         const registration = this.registry.require(typeKey); // resolve-schema
+        // R2 (ADR-0038): an authority-only type is never CRUD'd through the engine — fail closed
+        // before any SQL or decision.
+        if (registration.crudActions === false) {
+            throw new errors_js_1.RegistrationError(`type '${typeKey}' declares crudActions:false; engine ${op} refused`);
+        }
         const nowMs = this.now();
         return this.inUnit(tx, true, async (query) => {
             const ctx = (0, context_js_1.newWriteContext)({ op, actor, registration, query, nowMs }, {
                 ...(opts.id !== undefined ? { id: opts.id } : {}),
                 ...(opts.input !== undefined ? { input: opts.input } : {}),
+                ...(opts.batch !== undefined ? { batch: opts.batch } : {}),
                 junctions: { ...(opts.input?.junctions ?? {}) },
             });
             for (const stage of this.writeStages) {
@@ -207,12 +247,46 @@ class RecordEngineImpl {
     async delete(typeKey, id, actor) {
         return this.deleteIn(undefined, typeKey, id, actor);
     }
+    async createMany(typeKey, inputs, actor) {
+        return this.createManyIn(undefined, typeKey, inputs, actor);
+    }
     async createIn(tx, typeKey, input, actor) {
         const id = await this.runWrite(tx, 'create', typeKey, actor, { input });
         if (id === undefined)
             throw new errors_js_1.RegistrationError(`create '${typeKey}' produced no id`);
         return id;
     }
+    /**
+     * Bulk = single (Shield #7, SPEC v2 §5.G): every row runs the unchanged single-row create pipe,
+     * in order, in ONE unit of work (joins an outer transaction). No batched INSERT, no decision
+     * shared across rows. The first failing row throws and rollback-only state discards the whole
+     * batch, its audit rows included. Inputs are checked before the type lookup and before any
+     * transaction opens, so a bad call neither touches the DB nor poisons an outer transaction.
+     */
+    async createManyIn(tx, typeKey, inputs, actor) {
+        if (!Array.isArray(inputs))
+            throw new errors_js_2.ValidationError('inputs', 'must be an array');
+        if (inputs.length === 0)
+            throw new errors_js_2.ValidationError('inputs', 'must not be empty');
+        if (inputs.length > CREATE_MANY_CAP) {
+            throw new errors_js_2.ValidationError('inputs', `at most ${CREATE_MANY_CAP} rows per call`);
+        }
+        const batchId = (0, node_crypto_1.randomUUID)();
+        return this.transactionIn(tx, async () => {
+            const state = tx ?? this.activeTx.getStore();
+            const ids = [];
+            for (const [index, input] of inputs.entries()) {
+                const id = await this.runWrite(state, 'create', typeKey, actor, {
+                    input,
+                    batch: { id: batchId, index },
+                });
+                if (id === undefined)
+                    throw new errors_js_1.RegistrationError(`create '${typeKey}' produced no id`);
+                ids.push(id);
+            }
+            return ids;
+        });
+    }
     async updateIn(tx, typeKey, id, input, actor) {
         await this.runWrite(tx, 'update', typeKey, actor, { id, input });
     }
@@ -337,90 +411,98 @@ class RecordEngineImpl {
             return this.project(reg, first);
         });
     }
+    /**
+     * The ONE read WHERE of a list (SPEC v2 §5.D): list-scope fragment resolved first, tenant
+     * clause, readScope wall, equality `where`, search, list-scope fragment. Shared by the data
+     * SELECT and the COUNT (and later `aggregate`), so they cannot diverge. Async because it
+     * awaits the list-scope seam; takes no `q` (no DB read of its own). Callers run `gateRead`
+     * first.
+     */
+    async buildReadWhere(reg, query, actor) {
+        const typeKey = reg.typeKey;
+        const clauses = [];
+        const params = [];
+        // Mandatory tenant scoping when the table is tenant-owned (cross-tenant safety).
+        // ROOT spans all tenants — but only a STRICT `=== true` isRoot counts (fail-closed):
+        // a truthy-non-boolean must never bypass the tenant boundary.
+        // SUBTREE-AWARE (ADR-0027): a non-root actor is bounded to its reachable subtree
+        // (active node + descendants), NOT just the self-node — `tenant_col IN (?, ...)` over
+        // `actor.scopeSubtreeNodeIds` (the SAME cached set the tenant gate + list-scope use).
+        // Fail-safe to `[actor.tenantId]` (self-node) if the subtree is malformed/absent.
+        //
+        // ⛔ ONE-AUTHORITY (Invariant #3, §10bis.5): this built-in clause is the FAIL-SAFE for
+        // when the list-scope engine is NOT wired (pre-Phase-3 / a consumer without it). When
+        // `listScope` IS wired, the list-scope FRAGMENT is the single source of the tenant
+        // boundary — it already emits `tenant_col = ?` / `IN (subtree)` for non-root AND ORs in
+        // the cross-tenant grant reach (§10bis.5). Emitting BOTH here would AND this narrower
+        // own-subtree filter over the fragment and KILL every cross-tenant-granted row before the
+        // fragment's widening can include it (the exact divergence the list≡decide gate caught).
+        // So when `listScope` is present we DEFER the tenant bound entirely to the fragment — one
+        // authority, no double-filter. (readScope system-types are unaffected: they have no
+        // tenant column, so this clause never fired for them anyway; their wall is `readScope`.)
+        // The list-scope fragment is resolved up-front (a throw propagates — fail closed). An EMPTY
+        // fragment never drops the tenant bound (review L1): the built-in clause then applies.
+        const listFragment = this.listScope ? await this.listScope(reg, actor, 'read') : null;
+        const listFragmentSql = listFragment?.sql ? listFragment : null;
+        const tenantCol = this.tenantColumn(reg);
+        if (tenantCol && actor.isRoot !== true && !listFragmentSql) {
+            const nodes = this.tenantScopeNodes(actor);
+            clauses.push(`\`${tenantCol}\` IN (${nodes.map(() => '?').join(', ')})`);
+            params.push(...nodes);
+        }
+        // Read-scope wall (ADR-0027, Task 4.1): a type declaring `readScope` (the identity
+        // `system` types with no tenant column) has its NON-ROOT reads bounded to the caller's
+        // reachable subtree. ANDed AFTER the tenant clause (which won't fire for these system
+        // types) into BOTH the data SELECT and the COUNT (shared clauses/params ⇒ consistent
+        // by construction). Root gets NO clause (spans all). Injection-free — only `?`-bound
+        // node ids; identifiers are the type's own column or a fixed framework template.
+        const readScope = this.readScopeClause(reg, actor);
+        if (readScope) {
+            clauses.push(readScope.sql);
+            params.push(...readScope.params);
+        }
+        // `where` filters (SPEC v2 §5.A): scalar equality or one §10 operator per field. The
+        // COLUMN comes from a whitelisted field-key lookup; every VALUE is coerced and a bound
+        // `?` param — never interpolated. Malformed/unknown ⇒ throw (never "no filter").
+        const filters = (0, filter_sql_js_1.buildFilterClauses)(reg, query.where, typeKey);
+        clauses.push(...filters.clauses);
+        params.push(...filters.params);
+        // Free-text search: OR a `LIKE ?` across the named registered fields. Field
+        // keys are whitelisted (unknown → throw); the term is a bound `?` param with
+        // LIKE wildcards escaped, so a literal `%`/`_` in the term is not a wildcard.
+        const search = query.search;
+        if (search && search.fields.length > 0) {
+            // A non-string term is a bad operand (SPEC §13): ValidationError, never a raw TypeError.
+            if (typeof search.term !== 'string')
+                throw new errors_js_2.ValidationError('search', 'term must be a string');
+            const pattern = `%${escapeLikeTerm(search.term)}%`;
+            const ors = [];
+            for (const key of search.fields) {
+                const { column } = (0, filter_sql_js_1.resolveColumn)(reg, key, typeKey, 'search');
+                ors.push(`\`${column}\` LIKE ? ESCAPE '\\\\'`);
+                params.push(pattern);
+            }
+            clauses.push(`(${ors.join(' OR ')})`);
+        }
+        // Record-level list scope (§8.3): AND the framework-computed visible-set fragment into
+        // BOTH the data SELECT and the COUNT (via the shared clauses/params — so `total` and
+        // `rows` stay consistent BY CONSTRUCTION). Runs only AFTER the coarse object-type gate
+        // (gateRead, at the TOP of list()) has allowed the read — the scope narrows rows WITHIN
+        // an allowed object-type list; it NEVER substitutes for the gate (the root/data-plane
+        // leak-guard). A scope-fn throw PROPAGATES (fail-closed — the read fails; we never fall
+        // back to unscoped rows). An empty `sql` is not ANDed; the built-in tenant clause above applies instead.
+        if (listFragmentSql) {
+            clauses.push(listFragmentSql.sql);
+            params.push(...listFragmentSql.params);
+        }
+        const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+        return { where, params };
+    }
     async listIn(tx, typeKey, query, actor) {
         const reg = this.registry.require(typeKey);
         await this.gateRead(reg, actor);
         return this.inUnit(tx, false, async (q) => {
-            const clauses = [];
-            const params = [];
-            // Mandatory tenant scoping when the table is tenant-owned (cross-tenant safety).
-            // ROOT spans all tenants — but only a STRICT `=== true` isRoot counts (fail-closed):
-            // a truthy-non-boolean must never bypass the tenant boundary.
-            // SUBTREE-AWARE (ADR-0027): a non-root actor is bounded to its reachable subtree
-            // (active node + descendants), NOT just the self-node — `tenant_col IN (?, ...)` over
-            // `actor.scopeSubtreeNodeIds` (the SAME cached set the tenant gate + list-scope use).
-            // Fail-safe to `[actor.tenantId]` (self-node) if the subtree is malformed/absent.
-            //
-            // ⛔ ONE-AUTHORITY (Invariant #3, §10bis.5): this built-in clause is the FAIL-SAFE for
-            // when the list-scope engine is NOT wired (pre-Phase-3 / a consumer without it). When
-            // `listScope` IS wired, the list-scope FRAGMENT is the single source of the tenant
-            // boundary — it already emits `tenant_col = ?` / `IN (subtree)` for non-root AND ORs in
-            // the cross-tenant grant reach (§10bis.5). Emitting BOTH here would AND this narrower
-            // own-subtree filter over the fragment and KILL every cross-tenant-granted row before the
-            // fragment's widening can include it (the exact divergence the list≡decide gate caught).
-            // So when `listScope` is present we DEFER the tenant bound entirely to the fragment — one
-            // authority, no double-filter. (readScope system-types are unaffected: they have no
-            // tenant column, so this clause never fired for them anyway; their wall is `readScope`.)
-            // The list-scope fragment is resolved up-front (a throw propagates — fail closed). An EMPTY
-            // fragment never drops the tenant bound (review L1): the built-in clause then applies.
-            const listFragment = this.listScope ? await this.listScope(reg, actor, 'read') : null;
-            const listFragmentSql = listFragment?.sql ? listFragment : null;
-            const tenantCol = this.tenantColumn(reg);
-            if (tenantCol && actor.isRoot !== true && !listFragmentSql) {
-                const nodes = this.tenantScopeNodes(actor);
-                clauses.push(`\`${tenantCol}\` IN (${nodes.map(() => '?').join(', ')})`);
-                params.push(...nodes);
-            }
-            // Read-scope wall (ADR-0027, Task 4.1): a type declaring `readScope` (the identity
-            // `system` types with no tenant column) has its NON-ROOT reads bounded to the caller's
-            // reachable subtree. ANDed AFTER the tenant clause (which won't fire for these system
-            // types) into BOTH the data SELECT and the COUNT (shared clauses/params ⇒ consistent
-            // by construction). Root gets NO clause (spans all). Injection-free — only `?`-bound
-            // node ids; identifiers are the type's own column or a fixed framework template.
-            const readScope = this.readScopeClause(reg, actor);
-            if (readScope) {
-                clauses.push(readScope.sql);
-                params.push(...readScope.params);
-            }
-            // Equality filters on registered field columns only (unknown keys rejected).
-            // The COLUMN comes from a whitelisted field-key lookup; the VALUE is a bound
-            // `?` param — never interpolated.
-            for (const [k, v] of Object.entries(query.where ?? {})) {
-                const field = reg.fields.find((f) => f.key === k);
-                if (!field)
-                    throw new errors_js_1.RegistrationError(`list '${typeKey}': unknown filter field '${k}'`);
-                clauses.push(`\`${(0, registry_js_1.columnOf)(field)}\` = ?`);
-                params.push(v);
-            }
-            // Free-text search: OR a `LIKE ?` across the named registered fields. Field
-            // keys are whitelisted (unknown → throw); the term is a bound `?` param with
-            // LIKE wildcards escaped, so a literal `%`/`_` in the term is not a wildcard.
-            const search = query.search;
-            if (search && search.fields.length > 0) {
-                const pattern = `%${escapeLikeTerm(search.term)}%`;
-                const ors = [];
-                for (const key of search.fields) {
-                    const field = reg.fields.find((f) => f.key === key);
-                    if (!field) {
-                        throw new errors_js_1.RegistrationError(`list '${typeKey}': unknown search field '${key}'`);
-                    }
-                    ors.push(`\`${(0, registry_js_1.columnOf)(field)}\` LIKE ? ESCAPE '\\\\'`);
-                    params.push(pattern);
-                }
-                clauses.push(`(${ors.join(' OR ')})`);
-            }
-            // Record-level list scope (§8.3): AND the framework-computed visible-set fragment into
-            // BOTH the data SELECT and the COUNT (via the shared clauses/params — so `total` and
-            // `rows` stay consistent BY CONSTRUCTION). Runs only AFTER the coarse object-type gate
-            // (gateRead, at the TOP of list()) has allowed the read — the scope narrows rows WITHIN
-            // an allowed object-type list; it NEVER substitutes for the gate (the root/data-plane
-            // leak-guard). A scope-fn throw PROPAGATES (fail-closed — the read fails; we never fall
-            // back to unscoped rows). An empty `sql` is not ANDed; the built-in tenant clause above applies instead.
-            if (listFragmentSql) {
-                clauses.push(listFragmentSql.sql);
-                params.push(...listFragmentSql.params);
-            }
-            const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+            const { where, params } = await this.buildReadWhere(reg, query, actor);
             // Sort: resolve `sortBy` to a column the SAME whitelisted way as where-keys
             // (unknown key → throw). The direction is an enum-checked literal (only 'desc'
             // flips to DESC; anything else is ascending) — neither is ever raw-interpolated
@@ -433,12 +515,8 @@ class RecordEngineImpl {
             const orderTerms = [];
             let sortColumn;
             if (query.sortBy !== undefined) {
-                const field = reg.fields.find((f) => f.key === query.sortBy);
-                if (!field) {
-                    throw new errors_js_1.RegistrationError(`list '${typeKey}': unknown sort field '${query.sortBy}'`);
-                }
                 const dir = query.sortOrder === 'desc' ? 'DESC' : 'ASC';
-                sortColumn = (0, registry_js_1.columnOf)(field);
+                sortColumn = (0, filter_sql_js_1.resolveColumn)(reg, query.sortBy, typeKey, 'sort').column;
                 orderTerms.push(`\`${sortColumn}\` ${dir}`);
             }
             for (const col of (0, where_by_id_js_1.pkColumns)(reg)) {
@@ -446,14 +524,69 @@ class RecordEngineImpl {
                     orderTerms.push(`\`${col}\` ASC`);
             }
             const orderBy = `ORDER BY ${orderTerms.join(', ')}`;
-            const limit = Math.min(Math.max(query.limit ?? 100, 1), 1000);
-            const offset = Math.max(query.offset ?? 0, 0);
+            const limit = clampLimit(query.limit);
+            const offset = Number.isFinite(query.offset) ? Math.max(query.offset, 0) : 0;
             const rows = (await q(`SELECT * FROM ${this.qualified(reg)} ${where} ${orderBy} LIMIT ? OFFSET ?`, [...params, limit, offset]));
             const countRows = (await q(`SELECT COUNT(*) AS n FROM ${this.qualified(reg)} ${where}`, params));
             const total = Number(countRows[0]?.n ?? 0);
             return { rows: rows.map((r) => this.project(reg, r)), total };
         });
     }
+    async aggregate(typeKey, query, actor) {
+        return this.aggregateIn(undefined, typeKey, query, actor);
+    }
+    /**
+     * Aggregate over exactly the rows `list()` returns (SPEC v2 §5.F, Shield #8): the SAME gate
+     * (object-type `read`, first) and the SAME `buildReadWhere`, then ONE
+     * `SELECT … FROM <table> <where> [GROUP BY … ORDER BY …] LIMIT ?`. No table alias, so a
+     * list-scope fragment's bare columns resolve. Read-only: no audit row, no write.
+     */
+    async aggregateIn(tx, typeKey, query, actor) {
+        const reg = this.registry.require(typeKey);
+        await this.gateRead(reg, actor);
+        const agg = (0, filter_sql_js_1.buildAggregateSelect)(reg, query.groupBy, query.measures, typeKey);
+        return this.inUnit(tx, false, async (q) => {
+            const { where, params } = await this.buildReadWhere(reg, query, actor);
+            const limit = clampLimit(query.limit);
+            const sql = [
+                `SELECT ${agg.select} FROM ${this.qualified(reg)}`,
+                where,
+                agg.groupBy ? `GROUP BY ${agg.groupBy} ORDER BY ${agg.orderBy}` : '',
+                'LIMIT ?',
+            ]
+                .filter((part) => part !== '')
+                .join(' ');
+            const rows = (await q(sql, [...params, limit]));
+            const grouped = agg.groupBy !== '';
+            // Ungrouped SQL always yields one row; if none came back, shape the empty aggregate.
+            const source = rows.length > 0 || grouped ? rows : [{}];
+            const groups = source.map((row) => {
+                const key = {};
+                for (const [alias, fieldKey] of Object.entries(agg.keyMap)) {
+                    key[fieldKey] = ownValue(row, alias) ?? null;
+                }
+                const values = {};
+                for (const col of agg.columns) {
+                    // Own property only: an alias such as `constructor` must not read Object.prototype.
+                    const raw = ownValue(row, col.alias);
+                    if (raw === undefined || raw === null) {
+                        values[col.alias] = col.fn === 'count' ? 0 : null;
+                    }
+                    else if (col.numeric || typeof raw === 'bigint') {
+                        values[col.alias] = toSafeNumber(raw, typeKey, col.alias);
+                    }
+                    else if (typeof raw === 'string' || typeof raw === 'number' || raw instanceof Date) {
+                        values[col.alias] = raw;
+                    }
+                    else {
+                        throw new errors_js_2.EngineUnavailableError(`aggregate '${typeKey}': unexpected driver value for '${col.alias}'`);
+                    }
+                }
+                return { key, values };
+            });
+            return { groups };
+        });
+    }
     /** The physical column of a `tenantId`-trusted field, if the table has one. */
     tenantColumn(reg) {
         const f = reg.fields.find((x) => x.trusted === 'tenantId');
@@ -510,6 +643,19 @@ class RecordEngineImpl {
     }
 }
 exports.RecordEngineImpl = RecordEngineImpl;
+/**
+ * Clamp a list/aggregate `limit` to 1..1000. Absent or non-finite (`NaN`, ±Infinity) ⇒ the
+ * default 100, so a bad number is never bound as `NULL`.
+ */
+function clampLimit(limit) {
+    if (!Number.isFinite(limit))
+        return 100;
+    return Math.min(Math.max(limit, 1), 1000);
+}
+/** A row's own property value (undefined when absent; never an inherited prototype member). */
+function ownValue(row, key) {
+    return Object.prototype.hasOwnProperty.call(row, key) ? row[key] : undefined;
+}
 /**
  * Escape the SQL-LIKE meta-characters (`\`, `%`, `_`) in a user-supplied search
  * term so they match literally. The engine's LIKE clause pairs this with
@@ -520,3 +666,26 @@ exports.RecordEngineImpl = RecordEngineImpl;
 function escapeLikeTerm(term) {
     return term.replace(/[\\%_]/g, (ch) => `\\${ch}`);
 }
+/**
+ * Convert a COUNT/SUM/AVG (or numeric MIN/MAX) driver value — BigInt, DECIMAL string or number —
+ * to a JS `number` (SPEC v2 §11). An integer outside the safe range, or a non-numeric value,
+ * throws `EngineUnavailableError` rather than return a silently wrong number.
+ */
+function toSafeNumber(raw, typeKey, alias) {
+    const fail = () => {
+        throw new errors_js_2.EngineUnavailableError(`aggregate '${typeKey}': '${alias}' cannot be represented as a safe JS number`);
+    };
+    if (typeof raw === 'bigint') {
+        if (raw > BigInt(Number.MAX_SAFE_INTEGER) || raw < BigInt(Number.MIN_SAFE_INTEGER))
+            fail();
+        return Number(raw);
+    }
+    if (typeof raw !== 'number' && typeof raw !== 'string')
+        return fail();
+    const n = typeof raw === 'number' ? raw : raw.trim() === '' ? NaN : Number(raw);
+    if (!Number.isFinite(n))
+        fail();
+    if (Number.isInteger(n) && !Number.isSafeInteger(n))
+        fail();
+    return n;
+}

package/dist/pipe/records-service.d.ts

@@ -1,5 +1,5 @@
 import type { Principal } from '@astram/core';
-import type { RecordEngine, RecordInput, RecordId, RecordView, ListQuery, RecordPage } from '../types.js';
+import type { RecordEngine, RecordInput, RecordId, RecordView, ListQuery, RecordPage, AggregateQuery, AggregateResult } from '../types.js';
 /** Round-2 port: resolves a service-account KEY to a seeded principal. */
 export interface ServiceAccountResolver {
     resolve(key: string): Principal;
@@ -26,6 +26,12 @@ export declare class RecordsService {
     delete(typeKey: string, id: RecordId): Promise<void>;
     /** Row lock inside the open `transaction(fn)` (see `RecordEngine.lockForUpdate`). */
     lockForUpdate(typeKey: string, id: RecordId): Promise<void>;
+    /** Record-level decision for a declared action, no write (see `RecordEngine.authorize`). */
+    authorize(typeKey: string, id: RecordId, action: string): Promise<void>;
+    /** Aggregate over the rows `list()` returns (see `RecordEngine.aggregate`). */
+    aggregate(typeKey: string, query: AggregateQuery): Promise<AggregateResult>;
+    /** Create 1..500 records all-or-nothing (see `RecordEngine.createMany`). */
+    createMany(typeKey: string, inputs: readonly RecordInput[]): Promise<RecordId[]>;
     /**
      * Run `fn` in ONE unit of work (ADR-0034): `tx` carries the same five ops bound to the request
      * principal, and every op on it — plus any `records.*` call made from inside `fn` — shares one
@@ -40,6 +46,12 @@ export declare class RecordsService {
      * silent default. A string key requires a ServiceAccountResolver (Round 2).
      */
     as(who: string | Principal): BoundRecords;
+    /**
+     * The request principal every op on this service acts as (the guard-resolved `req.principal`).
+     * For callers that must stamp or audit with exactly the engine's identity (e.g. a storage key
+     * tenant prefix). Fail-closed: no principal ⇒ throws `EngineUnavailableError`, like every op.
+     */
+    requestPrincipal(): Readonly<Principal>;
     private actor;
     private resolveServiceAccount;
 }
@@ -60,5 +72,11 @@ export declare class BoundRecords {
     delete(typeKey: string, id: RecordId): Promise<void>;
     /** Row lock inside the open transaction (see `RecordEngine.lockForUpdate`). */
     lockForUpdate(typeKey: string, id: RecordId): Promise<void>;
+    /** Record-level decision for a declared action, no write (see `RecordEngine.authorize`). */
+    authorize(typeKey: string, id: RecordId, action: string): Promise<void>;
+    /** Aggregate over the rows `list()` returns (see `RecordEngine.aggregate`). */
+    aggregate(typeKey: string, query: AggregateQuery): Promise<AggregateResult>;
+    /** Create 1..500 records all-or-nothing (see `RecordEngine.createMany`). */
+    createMany(typeKey: string, inputs: readonly RecordInput[]): Promise<RecordId[]>;
 }
 //# sourceMappingURL=records-service.d.ts.map

package/dist/pipe/records-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"records-service.d.ts","sourceRoot":"","sources":["../../src/pipe/records-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACX,MAAM,aAAa,CAAC;AAGrB,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AACD,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;;;GAMG;AACH,qBACa,cAAc;IAEA,OAAO,CAAC,QAAQ,CAAC,MAAM;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAGrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;gBAJO,MAAM,EAAE,YAAY,EAC1B,GAAG,EAAE;QAAE,SAAS,CAAC,EAAE,SAAS,CAAA;KAAE,EAG/C,eAAe,CAAC,EAAE,sBAAsB,YAAA;IAWrD,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAG9D,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAG9D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAG5D,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAGxE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAG1D,qFAAqF;IAC/E,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE;;;;;;OAMG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAKtE;;;;OAIG;IACH,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY;IAKzC,OAAO,CAAC,KAAK;IAWb,OAAO,CAAC,qBAAqB;CAS9B;AAED;;;GAGG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,SAAS;IAEnC,4FAA4F;IAC5F,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAGhE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAG9D,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAG9D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAG5D,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAGxE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAGpD,+EAA+E;IAC/E,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAG5D"}
+{"version":3,"file":"records-service.d.ts","sourceRoot":"","sources":["../../src/pipe/records-service.ts"],"names":[],"mappings":"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"}

package/dist/pipe/records-service.js

@@ -61,6 +61,18 @@ let RecordsService = class RecordsService {
     async lockForUpdate(typeKey, id) {
         return this.engine.lockForUpdate(typeKey, id, this.actor());
     }
+    /** Record-level decision for a declared action, no write (see `RecordEngine.authorize`). */
+    async authorize(typeKey, id, action) {
+        return this.engine.authorize(typeKey, id, action, this.actor());
+    }
+    /** Aggregate over the rows `list()` returns (see `RecordEngine.aggregate`). */
+    async aggregate(typeKey, query) {
+        return this.engine.aggregate(typeKey, query, this.actor());
+    }
+    /** Create 1..500 records all-or-nothing (see `RecordEngine.createMany`). */
+    async createMany(typeKey, inputs) {
+        return this.engine.createMany(typeKey, inputs, this.actor());
+    }
     /**
      * Run `fn` in ONE unit of work (ADR-0034): `tx` carries the same five ops bound to the request
      * principal, and every op on it — plus any `records.*` call made from inside `fn` — shares one
@@ -81,6 +93,14 @@ let RecordsService = class RecordsService {
         const actor = typeof who === 'string' ? this.resolveServiceAccount(who) : who;
         return new BoundRecords(this.engine, actor);
     }
+    /**
+     * The request principal every op on this service acts as (the guard-resolved `req.principal`).
+     * For callers that must stamp or audit with exactly the engine's identity (e.g. a storage key
+     * tenant prefix). Fail-closed: no principal ⇒ throws `EngineUnavailableError`, like every op.
+     */
+    requestPrincipal() {
+        return Object.freeze({ ...this.actor() });
+    }
     actor() {
         const p = this.req?.principal;
         if (!p) {
@@ -140,5 +160,17 @@ class BoundRecords {
     lockForUpdate(typeKey, id) {
         return this.engine.lockForUpdate(typeKey, id, this.actor);
     }
+    /** Record-level decision for a declared action, no write (see `RecordEngine.authorize`). */
+    authorize(typeKey, id, action) {
+        return this.engine.authorize(typeKey, id, action, this.actor);
+    }
+    /** Aggregate over the rows `list()` returns (see `RecordEngine.aggregate`). */
+    aggregate(typeKey, query) {
+        return this.engine.aggregate(typeKey, query, this.actor);
+    }
+    /** Create 1..500 records all-or-nothing (see `RecordEngine.createMany`). */
+    createMany(typeKey, inputs) {
+        return this.engine.createMany(typeKey, inputs, this.actor);
+    }
 }
 exports.BoundRecords = BoundRecords;

package/dist/pipe/stages/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAgC,MAAM,gBAAgB,CAAC;AAC9E,OAAO,KAAK,EAAE,KAAK,EAAyB,MAAM,eAAe,CAAC;AAMlE,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,CA2BlD"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAgC,MAAM,gBAAgB,CAAC;AAC9E,OAAO,KAAK,EAAE,KAAK,EAAyB,MAAM,eAAe,CAAC;AAMlE,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,CAkClD"}