@astram/engine 0.6.0 → 0.8.0

package/dist/pipe/stages/audit.js

@@ -33,7 +33,14 @@ function auditStage(audit) {
                 tenantId: ctx.actor.tenantId,
                 action,
                 resource,
-                attributes: { op: ctx.op, typeKey: ctx.registration.typeKey },
+                attributes: {
+                    op: ctx.op,
+                    typeKey: ctx.registration.typeKey,
+                    // createMany rows only: single-row writes keep exactly { op, typeKey }.
+                    ...(ctx.batch !== undefined
+                        ? { batchId: ctx.batch.id, batchIndex: ctx.batch.index }
+                        : {}),
+                },
             };
             // Write the audit row on the pipe's OWN transaction (atomic with the data).
             await audit.record(event, ctx.query);

package/dist/pipe/stages/fetch-record.d.ts

@@ -30,7 +30,8 @@
  *   - `create` no-ops: there is no existing row (the create wall is ADR-0034, in `write.ts`).
  */
 import { AuthorizationDeniedError } from '../../errors.js';
-import type { ObjectType } from '../../types.js';
+import type { QueryFn } from '../../ports.js';
+import type { ObjectType, Principal, RecordId } from '../../types.js';
 import type { Stage } from '../context.js';
 /** The decision-relevant facts of one fetched row. */
 export interface RecordFacts {
@@ -52,5 +53,14 @@ export declare function recordFacts(reg: ObjectType, row: Record<string, unknown
 export declare function decisionAttributes(reg: ObjectType, facts: Pick<RecordFacts, 'fields' | 'ownerId'>): Record<string, unknown>;
 /** The ONE refusal for a record the actor cannot reach (missing ≡ foreign; no ids). */
 export declare function recordNotReachable(reg: ObjectType): AuthorizationDeniedError;
+/**
+ * Read one record's decision facts through `whereById` (pk + actor tenant + ADR-0030 write
+ * scope), `LIMIT 1`, with `FOR UPDATE` when `lock` is set. No row (missing ≡ foreign) ⇒
+ * `recordNotReachable`. Shared by `fetchRecordStage` (lock) and `RecordEngine.authorize`
+ * (lock only inside a transaction). The row itself is never returned, only its facts.
+ */
+export declare function fetchRecordFacts(reg: ObjectType, actor: Principal, id: RecordId, query: QueryFn, opts: {
+    readonly lock: boolean;
+}): Promise<RecordFacts>;
 export declare function fetchRecordStage(): Stage;
 //# sourceMappingURL=fetch-record.d.ts.map

package/dist/pipe/stages/fetch-record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-record.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/fetch-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,wBAAwB,EAAqB,MAAM,iBAAiB,CAAC;AAE9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,eAAe,CAAC;AAGzD,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,sFAAsF;IACtF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAetF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,SAAS,CAAC,GAC7C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,wBAAwB,CAK5E;AAED,wBAAgB,gBAAgB,IAAI,KAAK,CAwBxC"}
+{"version":3,"file":"fetch-record.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/fetch-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,wBAAwB,EAAqB,MAAM,iBAAiB,CAAC;AAE9E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,eAAe,CAAC;AAGzD,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,sFAAsF;IACtF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAetF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,SAAS,CAAC,GAC7C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,wBAAwB,CAK5E;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,SAAS,EAChB,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,OAAO,EACd,IAAI,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC/B,OAAO,CAAC,WAAW,CAAC,CAStB;AAED,wBAAgB,gBAAgB,IAAI,KAAK,CAexC"}

package/dist/pipe/stages/fetch-record.js

@@ -34,6 +34,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.recordFacts = recordFacts;
 exports.decisionAttributes = decisionAttributes;
 exports.recordNotReachable = recordNotReachable;
+exports.fetchRecordFacts = fetchRecordFacts;
 exports.fetchRecordStage = fetchRecordStage;
 const errors_js_1 = require("../../errors.js");
 const registry_js_1 = require("../../registry.js");
@@ -76,6 +77,20 @@ function decisionAttributes(reg, facts) {
 function recordNotReachable(reg) {
     return new errors_js_1.AuthorizationDeniedError('no_record_permit', `no reachable '${reg.typeKey}' record for this operation`);
 }
+/**
+ * Read one record's decision facts through `whereById` (pk + actor tenant + ADR-0030 write
+ * scope), `LIMIT 1`, with `FOR UPDATE` when `lock` is set. No row (missing ≡ foreign) ⇒
+ * `recordNotReachable`. Shared by `fetchRecordStage` (lock) and `RecordEngine.authorize`
+ * (lock only inside a transaction). The row itself is never returned, only its facts.
+ */
+async function fetchRecordFacts(reg, actor, id, query, opts) {
+    const where = (0, where_by_id_js_1.whereById)(reg, actor, id);
+    const rows = (await query(`SELECT * FROM ${(0, where_by_id_js_1.qualifiedTable)(reg)} WHERE ${where.sql} LIMIT 1${opts.lock ? ' FOR UPDATE' : ''}`, where.params));
+    const first = Array.isArray(rows) ? rows[0] : undefined;
+    if (first === undefined || first === null)
+        throw recordNotReachable(reg);
+    return recordFacts(reg, first);
+}
 function fetchRecordStage() {
     return {
         name: 'fetch-record',
@@ -84,15 +99,9 @@ function fetchRecordStage() {
                 return;
             if (ctx.id === undefined)
                 throw new errors_js_1.RegistrationError(`${ctx.op} requires an id`);
-            const reg = ctx.registration;
-            const where = (0, where_by_id_js_1.whereById)(reg, ctx.actor, ctx.id);
-            const rows = (await ctx.query(`SELECT * FROM ${(0, where_by_id_js_1.qualifiedTable)(reg)} WHERE ${where.sql} LIMIT 1 FOR UPDATE`, where.params));
-            const first = Array.isArray(rows)
-                ? rows[0]
-                : undefined;
-            if (first === undefined || first === null)
-                throw recordNotReachable(reg);
-            const facts = recordFacts(reg, first);
+            const facts = await fetchRecordFacts(ctx.registration, ctx.actor, ctx.id, ctx.query, {
+                lock: true,
+            });
             ctx.existing = facts.fields;
             if (facts.ownerId !== undefined)
                 ctx.ownerId = facts.ownerId;

package/dist/pipe/stages/permission-gate.d.ts

@@ -6,8 +6,16 @@
  * own allow/deny logic; it asks `decide()` and obeys.
  */
 import type { DecisionPort } from '../../ports.js';
+import type { Action, Resource, DecisionContext } from '../../ports.js';
+import type { Principal } from '../../types.js';
 import type { Stage } from '../context.js';
 export declare function permissionGateStage(decision: DecisionPort): Stage;
+/**
+ * Ask `decide()` once; throw on deny (AuthorizationDeniedError) or a throw (unavailable).
+ * Shared by the write stages and `RecordEngine.authorize` (custom object actions, D3); `label`
+ * names the operation in the `EngineUnavailableError` message only.
+ */
+export declare function decideOrThrow(decision: DecisionPort, actor: Principal, action: Action, resource: Resource, context: DecisionContext, label: string): Promise<void>;
 /**
  * Stage: type pre-gate (update/delete only; runs FIRST, before fetch-record's row lock).
  * Security-hardening Phase 8 #7.

package/dist/pipe/stages/permission-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permission-gate.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/permission-gate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,KAAK,EAAE,KAAK,EAAyB,MAAM,eAAe,CAAC;AAQlE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,KAAK,CAiCjE;AA2BD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,KAAK,CAe9D"}
+{"version":3,"file":"permission-gate.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/permission-gate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,KAAK,EAAyB,MAAM,eAAe,CAAC;AAQlE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,KAAK,CAiCjE;AAOD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,KAAK,CAoB9D"}

package/dist/pipe/stages/permission-gate.js

@@ -8,6 +8,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.permissionGateStage = permissionGateStage;
+exports.decideOrThrow = decideOrThrow;
 exports.typePreGateStage = typePreGateStage;
 const errors_js_1 = require("../../errors.js");
 const fetch_record_js_1 = require("./fetch-record.js");
@@ -44,21 +45,28 @@ function permissionGateStage(decision) {
                     }
                     : {}),
             };
-            await decideOrThrow(decision, ctx, action, resource, context);
+            await decideOrThrow(decision, ctx.actor, action, resource, context, gateLabel(ctx));
         },
     };
 }
-/** Ask `decide()` once; throw on deny (AuthorizationDeniedError) or a throw (unavailable). */
-async function decideOrThrow(decision, ctx, action, resource, context) {
+/** The `EngineUnavailableError` label of a pipe stage: `<op> <typeKey>`. */
+function gateLabel(ctx) {
+    return `${ctx.op} ${ctx.registration.typeKey}`;
+}
+/**
+ * Ask `decide()` once; throw on deny (AuthorizationDeniedError) or a throw (unavailable).
+ * Shared by the write stages and `RecordEngine.authorize` (custom object actions, D3); `label`
+ * names the operation in the `EngineUnavailableError` message only.
+ */
+async function decideOrThrow(decision, actor, action, resource, context, label) {
     let outcome;
     try {
-        outcome = await decision.decide(ctx.actor, action, resource, context);
+        outcome = await decision.decide(actor, action, resource, context);
     }
     catch (err) {
         // A thrown decision = transient/unavailable (ADR-0016). Fail-closed: do NOT
         // proceed; signal retryable.
-        throw new errors_js_1.EngineUnavailableError(`decision authority unavailable for ${ctx.op} ${ctx.registration.typeKey}: ` +
-            `${err.message}`);
+        throw new errors_js_1.EngineUnavailableError(`decision authority unavailable for ${label}: ${err.message}`);
     }
     if (outcome.effect !== 'allow') {
         throw new errors_js_1.AuthorizationDeniedError(outcome.reason, outcome.detail);
@@ -103,9 +111,7 @@ function typePreGateStage(decision) {
                 typeKey: ctx.registration.typeKey,
                 tenantId: ctx.actor.tenantId,
             };
-            await decideOrThrow(decision, ctx, { key: actionKey(ctx.op) }, resource, {
-                isAuthenticated: true,
-            });
+            await decideOrThrow(decision, ctx.actor, { key: actionKey(ctx.op) }, resource, { isAuthenticated: true }, gateLabel(ctx));
         },
     };
 }

package/dist/pipe/stages/validate.d.ts

@@ -7,5 +7,11 @@
  * Runs AFTER derive-write-context so trusted (server) values are validated too.
  */
 import type { Stage } from '../context.js';
+import type { FieldSpec } from '../../types.js';
+/**
+ * Validate + coerce one value against a field type. Returns the coerced value. Also used by
+ * the list filter builder (`buildFilterClauses`) for every `where` operand.
+ */
+export declare function coerce(field: FieldSpec, value: unknown): unknown;
 export declare function validateStage(): Stage;
 //# sourceMappingURL=validate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,eAAe,CAAC;AAiDzD,wBAAgB,aAAa,IAAI,KAAK,CAmCrC"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,gBAAgB,CAAC;AAW3D;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CA6ChE;AAED,wBAAgB,aAAa,IAAI,KAAK,CAmCrC"}

package/dist/pipe/stages/validate.js

@@ -8,6 +8,7 @@
  * Runs AFTER derive-write-context so trusted (server) values are validated too.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.coerce = coerce;
 exports.validateStage = validateStage;
 const errors_js_1 = require("../../errors.js");
 const registry_js_1 = require("../../registry.js");
@@ -20,7 +21,10 @@ const SUPPORTED = new Set([
     'timestamp',
     'json',
 ]);
-/** Validate + coerce one value against a field type. Returns the coerced value. */
+/**
+ * Validate + coerce one value against a field type. Returns the coerced value. Also used by
+ * the list filter builder (`buildFilterClauses`) for every `where` operand.
+ */
 function coerce(field, value) {
     switch (field.type) {
         case 'string':
@@ -31,6 +35,10 @@ function coerce(field, value) {
             if (typeof value !== 'number' || Number.isNaN(value)) {
                 throw new errors_js_1.ValidationError(field.key, 'expected a number');
             }
+            // ±Infinity is not a storable column value and not a meaningful filter operand.
+            if (!Number.isFinite(value)) {
+                throw new errors_js_1.ValidationError(field.key, 'expected a finite number');
+            }
             return value;
         case 'boolean':
             if (typeof value === 'boolean')
@@ -44,14 +52,20 @@ function coerce(field, value) {
                 throw new errors_js_1.ValidationError(field.key, 'expected a uuid');
             return canonical;
         }
-        case 'timestamp':
+        case 'timestamp': {
+            // An invalid Date (NaN / ±Infinity epoch) is rejected here, never bound as a parameter.
+            let date = null;
             if (value instanceof Date)
-                return value;
-            if (typeof value === 'number')
-                return new Date(value);
-            if (typeof value === 'string' && !Number.isNaN(Date.parse(value)))
-                return new Date(value);
-            throw new errors_js_1.ValidationError(field.key, 'expected a timestamp (Date | epoch ms | ISO string)');
+                date = value;
+            else if (typeof value === 'number')
+                date = new Date(value);
+            else if (typeof value === 'string' && !Number.isNaN(Date.parse(value)))
+                date = new Date(value);
+            if (date === null || Number.isNaN(date.getTime())) {
+                throw new errors_js_1.ValidationError(field.key, 'expected a timestamp (Date | epoch ms | ISO string)');
+            }
+            return date;
+        }
         case 'json':
             return JSON.stringify(value);
         default:

package/dist/registry.d.ts

@@ -8,11 +8,34 @@
  * Runtime-registered (no-code) tables will register through the SAME registry later
  * (the no-code phase); the pipe does not distinguish how a registration arrived.
  */
+import { type FrameworkSchemas } from '@astram/core';
 import type { FieldSpec, PkStrategy, ObjectType, Principal } from './types.js';
+/** The four resolved names `resolveObjectTypeSchema` needs (a core `FrameworkSchemas` fits). */
+export type FrameworkSchemaNames = Pick<FrameworkSchemas, 'app' | 'identity' | 'authz' | 'audit'>;
+/**
+ * Return `reg` with every {@link FRAMEWORK_SCHEMA} token in `schema` and
+ * `readScope.subquerySql` replaced by the resolved name (configurable-framework-db, spec 5.B).
+ * Pure: the input is not mutated. A literal schema or an absent one is returned unchanged.
+ *
+ * FAIL CLOSED (Shield #1): throws a `RegistrationError` when `schemas` is absent but a token is
+ * used, when a used token's resolved name is missing or not a plain identifier, or when any
+ * token-like text survives resolution. Every reader of an object type's schema outside the
+ * registry must call this before building SQL.
+ */
+export declare function resolveObjectTypeSchema(reg: ObjectType, schemas: FrameworkSchemaNames | undefined): ObjectType;
 export declare class TableRegistry {
+    private readonly schemas?;
     private readonly byType;
-    /** Register a table. Throws on a duplicate typeKey or an invalid registration. */
-    register(reg: ObjectType): void;
+    /**
+     * @param schemas the resolved framework database names `FRAMEWORK_SCHEMA` tokens resolve to.
+     *   Absent ⇒ a registration that uses a token fails (fail closed); others are unaffected.
+     */
+    constructor(schemas?: FrameworkSchemaNames | undefined);
+    /**
+     * Register a table. Resolves `FRAMEWORK_SCHEMA` tokens first (an unresolved token throws),
+     * then throws on a duplicate typeKey or an invalid registration.
+     */
+    register(input: ObjectType): void;
     /** Resolve a registration, or throw a RegistrationError if unknown. */
     require(typeKey: string): ObjectType;
     has(typeKey: string): boolean;
@@ -70,4 +93,17 @@ export declare function writeScopeClause(reg: ObjectType, actor: Principal): {
 export declare function isCreateWalled(reg: ObjectType): boolean;
 /** Boot-enforce that exactly-one field claims `role`; throw if none. */
 export declare function requireRole(reg: ObjectType, role: NonNullable<FieldSpec['role']>): void;
+/** What the action vocabulary reads from a registration (typeKey only names it in errors). */
+type ActionDeclaration = Pick<ObjectType, 'actions' | 'crudActions'> & {
+    readonly typeKey?: string;
+};
+/**
+ * The type's action vocabulary (ADR-0038): `read, create, update, delete` then the declared
+ * extras in declared order, or exactly the declared list when `crudActions === false`.
+ * Validates first (throws `RegistrationError`), so a registration read without
+ * `TableRegistry.register` (e.g. identity `extraObjects`) is held to the same rules.
+ * Framework-facing: the guard registry bridge, identity lookups and `authorize()` read it.
+ */
+export declare function effectiveActions(reg: ActionDeclaration): readonly string[];
+export {};
 //# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE/E,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IAExD,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAQ/B,uEAAuE;IACvE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAWpC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B,GAAG,IAAI,SAAS,UAAU,EAAE;CAG7B;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEjD;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,CAKnD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAEhD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAG1D;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAG7D;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAGrF;AAaD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,SAAS,GACf;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,GAAG,IAAI,CAYpD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAEvD;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAMvF"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAOrE,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE/E,gGAAgG;AAChG,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC,CAAC;AAOlG;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,oBAAoB,GAAG,SAAS,GACxC,UAAU,CAuCZ;AAED,qBAAa,aAAa;IAOZ,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IANrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IAExD;;;OAGG;gBAC0B,OAAO,CAAC,EAAE,oBAAoB,YAAA;IAE3D;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IASjC,uEAAuE;IACvE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAWpC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B,GAAG,IAAI,SAAS,UAAU,EAAE;CAG7B;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEjD;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,CAKnD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAEhD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAG1D;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAG7D;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAGrF;AAaD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,SAAS,GACf;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,GAAG,IAAI,CAYpD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAEvD;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAMvF;AAmDD,8FAA8F;AAC9F,KAAK,iBAAiB,GAAG,IAAI,CAAC,UAAU,EAAE,SAAS,GAAG,aAAa,CAAC,GAAG;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAgEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,MAAM,EAAE,CAI1E"}

package/dist/registry.js

@@ -11,6 +11,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TableRegistry = void 0;
+exports.resolveObjectTypeSchema = resolveObjectTypeSchema;
 exports.columnOf = columnOf;
 exports.uuidPkColumn = uuidPkColumn;
 exports.isOwned = isOwned;
@@ -20,12 +21,73 @@ exports.columnForRole = columnForRole;
 exports.writeScopeClause = writeScopeClause;
 exports.isCreateWalled = isCreateWalled;
 exports.requireRole = requireRole;
+exports.effectiveActions = effectiveActions;
+const core_1 = require("@astram/core");
 const errors_js_1 = require("./errors.js");
 const types_js_1 = require("./types.js");
+/** A resolved database name: unquoted identifier, MariaDB's 64-character limit. */
+const RESOLVED_SCHEMA_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+const SCHEMA_KEYS = ['app', 'identity', 'authz', 'audit'];
+/**
+ * Return `reg` with every {@link FRAMEWORK_SCHEMA} token in `schema` and
+ * `readScope.subquerySql` replaced by the resolved name (configurable-framework-db, spec 5.B).
+ * Pure: the input is not mutated. A literal schema or an absent one is returned unchanged.
+ *
+ * FAIL CLOSED (Shield #1): throws a `RegistrationError` when `schemas` is absent but a token is
+ * used, when a used token's resolved name is missing or not a plain identifier, or when any
+ * token-like text survives resolution. Every reader of an object type's schema outside the
+ * registry must call this before building SQL.
+ */
+function resolveObjectTypeSchema(reg, schemas) {
+    const usesToken = (text) => text !== undefined && text.includes(types_js_1.FRAMEWORK_SCHEMA_TOKEN_MARKER);
+    const subquerySql = reg.readScope?.kind === 'subtreeSubquery' ? reg.readScope.subquerySql : undefined;
+    if (!usesToken(reg.schema) && !usesToken(subquerySql))
+        return reg;
+    const nameFor = (key) => {
+        const name = schemas?.[key];
+        if (typeof name !== 'string' || !RESOLVED_SCHEMA_NAME.test(name)) {
+            throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': framework schema '${key}' is not resolved; ` +
+                `the engine needs the resolved framework database names (SHIELD_DB_NAMESPACE).`);
+        }
+        return name;
+    };
+    const leftover = (where) => new errors_js_1.RegistrationError(`registration '${reg.typeKey}': unresolved framework schema token in ${where}.`);
+    let out = reg;
+    if (usesToken(reg.schema)) {
+        // The schema is exactly one token, never a token inside a longer name.
+        const key = SCHEMA_KEYS.find((k) => types_js_1.FRAMEWORK_SCHEMA[k] === reg.schema);
+        if (key === undefined)
+            throw leftover('schema');
+        out = { ...out, schema: nameFor(key) };
+    }
+    if (usesToken(subquerySql) && reg.readScope?.kind === 'subtreeSubquery') {
+        let sql = reg.readScope.subquerySql;
+        for (const key of SCHEMA_KEYS) {
+            if (sql.includes(types_js_1.FRAMEWORK_SCHEMA[key]))
+                sql = sql.split(types_js_1.FRAMEWORK_SCHEMA[key]).join(nameFor(key));
+        }
+        if (usesToken(sql))
+            throw leftover('readScope.subquerySql');
+        out = { ...out, readScope: { ...reg.readScope, subquerySql: sql } };
+    }
+    return out;
+}
 class TableRegistry {
+    schemas;
     byType = new Map();
-    /** Register a table. Throws on a duplicate typeKey or an invalid registration. */
-    register(reg) {
+    /**
+     * @param schemas the resolved framework database names `FRAMEWORK_SCHEMA` tokens resolve to.
+     *   Absent ⇒ a registration that uses a token fails (fail closed); others are unaffected.
+     */
+    constructor(schemas) {
+        this.schemas = schemas;
+    }
+    /**
+     * Register a table. Resolves `FRAMEWORK_SCHEMA` tokens first (an unresolved token throws),
+     * then throws on a duplicate typeKey or an invalid registration.
+     */
+    register(input) {
+        const reg = resolveObjectTypeSchema(input, this.schemas);
         validate(reg);
         if (this.byType.has(reg.typeKey)) {
             throw new errors_js_1.RegistrationError(`duplicate table registration for typeKey '${reg.typeKey}'`);
@@ -178,6 +240,70 @@ function validate(reg) {
         throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': composite primary key needs >= 2 columns`);
     }
     validateAccess(reg);
+    validateActions(reg);
+}
+/** The CRUD vocabulary, in the `IDENTITY_ACTIONS` order (guard `identity-actions.ts`). */
+const CRUD_ACTIONS = ['read', 'create', 'update', 'delete'];
+/** Names no type may declare: the wildcard and the bare `@Classified` default (ADR-0038). */
+const RESERVED_ACTIONS = new Set(['*', 'access']);
+/** The narrowest action column (`perm_action`, `rpr_action`, `rs_action`) is VARCHAR(64). */
+const MAX_ACTION_LENGTH = 64;
+/**
+ * Boot-time validation of the declared action vocabulary (ADR-0038). Pure, no IO. Every
+ * failure is a `RegistrationError` naming the type and the action, so a bad name fails boot
+ * instead of silently denying at request time (Shield #2).
+ */
+function validateActions(reg) {
+    const type = reg.typeKey ?? '(unnamed)';
+    const crud = reg.crudActions;
+    if (crud !== undefined && typeof crud !== 'boolean') {
+        throw new errors_js_1.RegistrationError(`registration '${type}': crudActions must be a boolean, got ${typeof crud} (${String(crud)}).`);
+    }
+    const actions = reg.actions;
+    if (actions !== undefined && !Array.isArray(actions)) {
+        throw new errors_js_1.RegistrationError(`registration '${type}': actions must be an array of action names, got ${typeof actions}.`);
+    }
+    const list = actions ?? [];
+    if (crud === false && list.length === 0) {
+        throw new errors_js_1.RegistrationError(`registration '${type}': crudActions:false requires a non-empty actions list ` +
+            `(a type with no actions could never be granted).`);
+    }
+    const seen = new Set();
+    for (const a of list) {
+        if (typeof a !== 'string') {
+            throw new errors_js_1.RegistrationError(`registration '${type}': action ${String(a)} must be a string, got ${typeof a}.`);
+        }
+        if (RESERVED_ACTIONS.has(a)) {
+            throw new errors_js_1.RegistrationError(`registration '${type}': action '${a}' is reserved ('*' is the wildcard, 'access' the ` +
+                `@Classified default).`);
+        }
+        if (a.length > MAX_ACTION_LENGTH) {
+            throw new errors_js_1.RegistrationError(`registration '${type}': action '${a}' is longer than ${MAX_ACTION_LENGTH} characters.`);
+        }
+        if (!core_1.SEGMENT_FORMAT.test(a)) {
+            throw new errors_js_1.RegistrationError(`registration '${type}': action '${a}' must be snake_case (${String(core_1.SEGMENT_FORMAT)}).`);
+        }
+        if (crud !== false && CRUD_ACTIONS.includes(a)) {
+            throw new errors_js_1.RegistrationError(`registration '${type}': action '${a}' is a CRUD verb, already granted by default; ` +
+                `list it only with crudActions:false.`);
+        }
+        if (seen.has(a)) {
+            throw new errors_js_1.RegistrationError(`registration '${type}': duplicate action '${a}'.`);
+        }
+        seen.add(a);
+    }
+}
+/**
+ * The type's action vocabulary (ADR-0038): `read, create, update, delete` then the declared
+ * extras in declared order, or exactly the declared list when `crudActions === false`.
+ * Validates first (throws `RegistrationError`), so a registration read without
+ * `TableRegistry.register` (e.g. identity `extraObjects`) is held to the same rules.
+ * Framework-facing: the guard registry bridge, identity lookups and `authorize()` read it.
+ */
+function effectiveActions(reg) {
+    validateActions(reg);
+    const declared = reg.actions ?? [];
+    return reg.crudActions === false ? [...declared] : [...CRUD_ACTIONS, ...declared];
 }
 /**
  * Chokepoint 1 (§4.1 of the framework-owns-data-layer design). Every registered