@astram/engine 0.1.0

package/dist/pipe/context.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The pipe context — the mutable envelope that flows through every stage. Each
+ * stage reads what it needs and enriches it for downstream stages. The engine
+ * builds the initial context, runs the ordered stages inside ONE transaction, and
+ * returns the result. A stage that throws aborts the pipe (rollback).
+ */
+import type { Principal, RecordId, RecordInput, ObjectType } from '../types.js';
+import type { QueryFn } from '../ports.js';
+/** The operation a write pipe is performing. */
+export type WriteOp = 'create' | 'update' | 'delete';
+/** Shared, immutable-per-run inputs every stage can read. */
+export interface PipeBase {
+    readonly op: WriteOp;
+    readonly actor: Principal;
+    readonly registration: ObjectType;
+    /** The bound transactional query fn (sealed — stages use ONLY this for DB work). */
+    readonly query: QueryFn;
+    /** UTC epoch ms stamped once at pipe entry (deterministic within a run). */
+    readonly nowMs: number;
+}
+/** The evolving write context. */
+export interface WriteContext extends PipeBase {
+    /** For update/delete: the target record id. */
+    id?: RecordId;
+    /** The caller's raw input (create/update). */
+    input?: RecordInput;
+    /**
+     * Field values AFTER derive-write-context + validate: trusted attributes have
+     * been overwritten with server values, types coerced. This is what `write`
+     * persists. Keyed by physical column name.
+     */
+    columns: Record<string, unknown>;
+    /** Junction values to sync (foreign ids per junction name), post-validate. */
+    junctions: Record<string, readonly string[]>;
+    /** The id assigned/targeted by the write stage (set for create). */
+    resultId?: RecordId;
+    /**
+     * For an OWNED type's update/delete: the existing row's owner id, fetched
+     * tenant-scoped by the fetch-owner stage BEFORE the permission gate, and passed to
+     * `decide()` as `context.attributes.ownerId` so core's owner baseline can compare it
+     * to the actor. `undefined` when the type is not owned OR the target row does not
+     * exist in the actor's tenant (a missing row ⇒ absent owner ⇒ the baseline won't
+     * match ⇒ the gate denies; the row is never surfaced). NEVER set for create.
+     */
+    ownerId?: string;
+}
+/** A stage: a small, ordered, independently-testable unit of the pipe. */
+export interface Stage {
+    /** Stable stage name (for tests + tracing). */
+    readonly name: string;
+    run(ctx: WriteContext): Promise<void>;
+}
+/** Build the initial write context for a create/update/delete. */
+export declare function newWriteContext(base: PipeBase, partial: Partial<WriteContext>): WriteContext;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +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;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;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/context.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * The pipe context — the mutable envelope that flows through every stage. Each
+ * stage reads what it needs and enriches it for downstream stages. The engine
+ * builds the initial context, runs the ordered stages inside ONE transaction, and
+ * returns the result. A stage that throws aborts the pipe (rollback).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newWriteContext = newWriteContext;
+/** Build the initial write context for a create/update/delete. */
+function newWriteContext(base, partial) {
+    return {
+        ...base,
+        columns: {},
+        junctions: {},
+        ...partial,
+    };
+}

package/dist/pipe/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/pipe/context.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAsDH,0CAOC;AARD,kEAAkE;AAClE,SAAgB,eAAe,CAAC,IAAc,EAAE,OAA8B;IAC5E,OAAO;QACL,GAAG,IAAI;QACP,OAAO,EAAE,EAAE;QACX,SAAS,EAAE,EAAE;QACb,GAAG,OAAO;KACX,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,72 @@
+/**
+ * The RecordEngine — the ONE facade a feature calls, and the composer of the pipe.
+ *
+ * Every write (create/update/delete) runs the FIXED, ordered stage sequence inside
+ * ONE transaction:
+ *   permission-gate (MANDATORY) → derive-write-context → validate → compute (no-op
+ *   Phase 1) → write → junction-sync → audit (MANDATORY) → emit-event (no-op).
+ * A caller cannot reorder, add, or drop stages — the pipe shape is fixed here, so
+ * the security gate + audit ALWAYS run (fixes ORS's optional gate + off-road writes).
+ * Any stage throwing aborts the transaction (rollback) — fail-closed.
+ *
+ * Reads (get/list) run a lean read path: permission-gate (read) → query → project.
+ * (Row/column access-filtering + ref/label projection are Phase-2 enrichments; the
+ * Phase-1 read still gates on decide() and never surfaces raw internal ids as labels.)
+ */
+import type { TableRegistry } from '../registry.js';
+import type { AuditPort, DecisionPort, UnitOfWork, QueryFn } from '../ports.js';
+import type { ListQuery, Principal, RecordEngine, RecordId, RecordInput, RecordPage, RecordView } from '../types.js';
+export interface RecordEngineDeps {
+    readonly registry: TableRegistry;
+    readonly uow: UnitOfWork;
+    readonly decision: DecisionPort;
+    readonly audit: AuditPort;
+    /** Injectable clock (defaults to Date.now); keeps the pipe deterministic in tests. */
+    readonly nowMs?: () => number;
+    /**
+     * OPTIONAL post-delete hook (design §6.2 orphan-share cleanup). Called AFTER a successful
+     * delete of an `owned`-type record so the consumer can cascade-remove that record's
+     * `record_share` rows (guard's `makeShareDeleteCascade`).
+     *
+     * ⛔ SAME-TRANSACTION (mirrors {@link AuditPort.record}, ports.ts): the hook receives the
+     * pipe's TX-BOUND {@link QueryFn} as its FIRST arg and MUST run its cascade DELETE through
+     * THAT — so the share cleanup commits/rolls back ATOMICALLY with the record delete. If the
+     * hook ran on a separate pool connection (autocommit), a rolled-back delete would leave the
+     * shares destroyed for a still-existing record (and self-deadlock on the delete's row lock).
+     * Using the same `query` is what makes the atomicity real, not just documented.
+     *
+     * ⛔ LAYERING (ADR-0003): the engine must NOT depend on guard. This hook is the seam — the
+     * engine calls it if present; the CONSUMER wires it to guard's cascade function. Absent ⇒
+     * no cascade (correct for apps with no shares). Called only for `owned` types (the only
+     * shareable ones) and only on a delete whose stages produced no error.
+     *
+     * The hook runs INSIDE the write transaction's `uow.run` callback (after the delete
+     * stages), so a hook throw aborts + rolls back the delete — an un-cascadable share (a
+     * store error) prevents leaving the record deleted with orphaned grants (fail-closed).
+     */
+    readonly onRecordDeleted?: (query: QueryFn, typeKey: string, recordId: string, tenantId: string) => Promise<void>;
+}
+export declare class RecordEngineImpl implements RecordEngine {
+    private readonly registry;
+    private readonly uow;
+    private readonly decision;
+    private readonly audit;
+    private readonly now;
+    private readonly onRecordDeleted;
+    /** The FIXED write-stage order. Built once; identical for every write. */
+    private readonly writeStages;
+    constructor(deps: RecordEngineDeps);
+    private runWrite;
+    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>;
+    private gateRead;
+    private qualified;
+    /** Project a raw DB row → RecordView (field keys, not columns). */
+    private project;
+    get(typeKey: string, id: RecordId, actor: Principal): Promise<RecordView | null>;
+    list(typeKey: string, query: ListQuery, actor: Principal): Promise<RecordPage>;
+    /** The physical column of a `tenantId`-trusted field, if the table has one. */
+    private tenantColumn;
+}
+//# sourceMappingURL=record-engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record-engine.d.ts","sourceRoot":"","sources":["../../src/pipe/record-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,UAAU,EACV,UAAU,EAEX,MAAM,aAAa,CAAC;AAWrB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;;OAoBG;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;CACpB;AAED,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAOlB;IACd,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;gBAEnC,IAAI,EAAE,gBAAgB;YAwBpB,QAAQ;IAsChB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IAMhF,MAAM,CACV,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,IAAI,CAAC;IAIV,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;YAM9D,QAAQ;IAiCtB,OAAO,CAAC,SAAS;IAIjB,mEAAmE;IACnE,OAAO,CAAC,OAAO;IAiBT,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA8DhF,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAyEpF,+EAA+E;IAC/E,OAAO,CAAC,YAAY;CAIrB"}

package/dist/pipe/record-engine.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * The RecordEngine — the ONE facade a feature calls, and the composer of the pipe.
+ *
+ * Every write (create/update/delete) runs the FIXED, ordered stage sequence inside
+ * ONE transaction:
+ *   permission-gate (MANDATORY) → derive-write-context → validate → compute (no-op
+ *   Phase 1) → write → junction-sync → audit (MANDATORY) → emit-event (no-op).
+ * A caller cannot reorder, add, or drop stages — the pipe shape is fixed here, so
+ * the security gate + audit ALWAYS run (fixes ORS's optional gate + off-road writes).
+ * Any stage throwing aborts the transaction (rollback) — fail-closed.
+ *
+ * Reads (get/list) run a lean read path: permission-gate (read) → query → project.
+ * (Row/column access-filtering + ref/label projection are Phase-2 enrichments; the
+ * Phase-1 read still gates on decide() and never surfaces raw internal ids as labels.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecordEngineImpl = void 0;
+const errors_js_1 = require("../errors.js");
+const registry_js_1 = require("../registry.js");
+const context_js_1 = require("./context.js");
+const fetch_owner_js_1 = require("./stages/fetch-owner.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");
+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");
+class RecordEngineImpl {
+    registry;
+    uow;
+    decision;
+    audit;
+    now;
+    onRecordDeleted;
+    /** The FIXED write-stage order. Built once; identical for every write. */
+    writeStages;
+    constructor(deps) {
+        this.registry = deps.registry;
+        this.uow = deps.uow;
+        this.decision = deps.decision;
+        this.audit = deps.audit;
+        this.now = deps.nowMs ?? (() => Date.now());
+        this.onRecordDeleted = deps.onRecordDeleted;
+        // permission-gate + audit are ALWAYS present, in this order — no skip flag.
+        // fetch-owner runs FIRST (before the gate) so an OWNED update/delete's existing-row
+        // owner is available to decide() as context.attributes.ownerId (core owner baseline).
+        // It no-ops for create + non-owned types (no unnecessary query).
+        this.writeStages = [
+            (0, fetch_owner_js_1.fetchOwnerStage)(),
+            (0, permission_gate_js_1.permissionGateStage)(this.decision),
+            (0, derive_write_context_js_1.deriveWriteContextStage)(),
+            (0, validate_js_1.validateStage)(),
+            // compute stage: Phase-1 no-op (formula/lookup/rollup land with the no-code engine)
+            (0, write_js_1.writeStage)(),
+            (0, junction_sync_js_1.junctionSyncStage)(),
+            (0, audit_js_1.auditStage)(this.audit),
+            // emit-event stage: Phase-1 no-op (business rules land later)
+        ];
+    }
+    async runWrite(op, typeKey, actor, opts) {
+        const registration = this.registry.require(typeKey); // resolve-schema
+        const nowMs = this.now();
+        return this.uow.run(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 } : {}),
+                junctions: { ...(opts.input?.junctions ?? {}) },
+            });
+            for (const stage of this.writeStages) {
+                await stage.run(ctx);
+            }
+            // Post-delete orphan-share cascade (design §6.2). Runs for an OWNED-type delete only
+            // (the only shareable types) when a cascade hook is wired. Passed the TX-BOUND `query`
+            // (the SAME connection the delete stages used) so the cascade commits/rolls back
+            // ATOMICALLY with the delete — a hook throw rolls the delete back (no record deleted
+            // with orphaned shares, and no separate-connection self-deadlock on the delete's row
+            // lock). No-op for create/update, non-owned types, a non-string id, or when no hook.
+            if (op === 'delete' &&
+                this.onRecordDeleted !== undefined &&
+                (0, registry_js_1.isOwned)(registration) &&
+                typeof opts.id === 'string') {
+                await this.onRecordDeleted(query, typeKey, opts.id, actor.tenantId);
+            }
+            return ctx.resultId;
+        });
+    }
+    async create(typeKey, input, actor) {
+        const id = await this.runWrite('create', typeKey, actor, { input });
+        if (id === undefined)
+            throw new errors_js_1.RegistrationError(`create '${typeKey}' produced no id`);
+        return id;
+    }
+    async update(typeKey, id, input, actor) {
+        await this.runWrite('update', typeKey, actor, { id, input });
+    }
+    async delete(typeKey, id, actor) {
+        await this.runWrite('delete', typeKey, actor, { id });
+    }
+    // --- reads -----------------------------------------------------------------
+    async gateRead(registration, actor, id, ownerId) {
+        const action = { key: 'read' };
+        const resource = {
+            level: id !== undefined ? 'record' : 'object_type',
+            typeKey: registration.typeKey,
+            tenantId: actor.tenantId,
+            ...(typeof id === 'string' ? { recordId: id } : {}),
+        };
+        // For an OWNED record read, pass the pre-fetched row owner so core's owner baseline
+        // can compare it to the actor. Absent ⇒ no owner match ⇒ deny (missing row / other
+        // tenant / non-owned type reads without it, as before).
+        const context = {
+            isAuthenticated: true,
+            ...(ownerId !== undefined ? { attributes: { ownerId } } : {}),
+        };
+        let outcome;
+        try {
+            outcome = await this.decision.decide(actor, action, resource, context);
+        }
+        catch (err) {
+            throw new errors_js_2.EngineUnavailableError(`decision authority unavailable for read ${registration.typeKey}: ${err.message}`);
+        }
+        if (outcome.effect !== 'allow') {
+            throw new errors_js_2.AuthorizationDeniedError(outcome.reason, outcome.detail);
+        }
+    }
+    qualified(reg) {
+        return reg.schema ? `\`${reg.schema}\`.\`${reg.table}\`` : `\`${reg.table}\``;
+    }
+    /** Project a raw DB row → RecordView (field keys, not columns). */
+    project(reg, row) {
+        const fields = {};
+        for (const f of reg.fields) {
+            const col = (0, registry_js_1.columnOf)(f);
+            if (Object.prototype.hasOwnProperty.call(row, col))
+                fields[f.key] = row[col];
+        }
+        let id;
+        if (reg.primaryKey.kind === 'uuid') {
+            id = row[reg.primaryKey.column];
+        }
+        else {
+            const key = {};
+            for (const c of reg.primaryKey.columns)
+                key[c] = String(row[c]);
+            id = key;
+        }
+        return { id, fields };
+    }
+    async get(typeKey, id, actor) {
+        const reg = this.registry.require(typeKey);
+        return this.uow.run(async (query) => {
+            const pk = reg.primaryKey;
+            let where;
+            let params;
+            if (pk.kind === 'uuid') {
+                if (typeof id !== 'string')
+                    throw new errors_js_1.RegistrationError(`'${typeKey}' needs a string id`);
+                where = `\`${(0, registry_js_1.uuidPkColumn)(pk)}\` = ?`;
+                params = [id];
+            }
+            else {
+                if (typeof id === 'string')
+                    throw new errors_js_1.RegistrationError(`'${typeKey}' needs a key map`);
+                where = pk.columns.map((c) => `\`${c}\` = ?`).join(' AND ');
+                params = pk.columns.map((c) => id[c]);
+            }
+            // Tenant scoping: if the table has a tenant column, constrain to the actor's tenant.
+            const tenantCol = this.tenantColumn(reg);
+            if (tenantCol) {
+                where += ` AND \`${tenantCol}\` = ?`;
+                params = [...params, actor.tenantId];
+            }
+            if ((0, registry_js_1.isOwned)(reg)) {
+                // OWNED read — FETCH-THEN-GATE. Core's owner baseline needs the row's owner,
+                // which core (zero-dep) can't fetch. So we SELECT the row FIRST (tenant-scoped),
+                // extract its owner, and gate on it. ⛔ THE FETCHED ROW IS NEVER SURFACED UNLESS
+                // THE GATE ALLOWS: gateRead throws on deny BEFORE we project()/return, so a denied
+                // read leaks nothing. A missing row ⇒ no owner ⇒ deny (never "null" that reveals
+                // presence/absence differently from a real deny — both throw/deny before any row
+                // data is returned).
+                const rows = (await query(`SELECT * FROM ${this.qualified(reg)} WHERE ${where} LIMIT 1`, params));
+                const first = rows[0];
+                const ownerCol = (0, registry_js_1.ownerColumn)(reg);
+                const owner = first && ownerCol ? first[ownerCol] : undefined;
+                // gateRead THROWS AuthorizationDeniedError on deny → the row below is never reached.
+                await this.gateRead(reg, actor, id, typeof owner === 'string' ? owner : undefined);
+                // Allowed. Project the ALREADY-fetched row (no second query). A genuinely absent
+                // row (owner undefined) would have been denied above by the missing owner match,
+                // so reaching here with `!first` is not expected for owned types; guard anyway.
+                return first ? this.project(reg, first) : null;
+            }
+            // NON-owned / system type — gate BEFORE fetch (no owner to check; avoid an extra
+            // query on the deny path). This is the original lean read path.
+            await this.gateRead(reg, actor, id);
+            const rows = (await query(`SELECT * FROM ${this.qualified(reg)} WHERE ${where} LIMIT 1`, params));
+            const first = rows[0];
+            return first ? this.project(reg, first) : null;
+        });
+    }
+    async list(typeKey, query, actor) {
+        const reg = this.registry.require(typeKey);
+        await this.gateRead(reg, actor);
+        return this.uow.run(async (q) => {
+            const clauses = [];
+            const params = [];
+            // Mandatory tenant scoping when the table is tenant-owned (cross-tenant safety).
+            const tenantCol = this.tenantColumn(reg);
+            if (tenantCol) {
+                clauses.push(`\`${tenantCol}\` = ?`);
+                params.push(actor.tenantId);
+            }
+            // 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 ')})`);
+            }
+            const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+            // 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
+            // user input.
+            let orderBy = '';
+            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';
+                orderBy = `ORDER BY \`${(0, registry_js_1.columnOf)(field)}\` ${dir}`;
+            }
+            const limit = Math.min(Math.max(query.limit ?? 100, 1), 1000);
+            const 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 };
+        });
+    }
+    /** The physical column of a `tenantId`-trusted field, if the table has one. */
+    tenantColumn(reg) {
+        const f = reg.fields.find((x) => x.trusted === 'tenantId');
+        return f ? (0, registry_js_1.columnOf)(f) : null;
+    }
+}
+exports.RecordEngineImpl = RecordEngineImpl;
+/**
+ * Escape the SQL-LIKE meta-characters (`\`, `%`, `_`) in a user-supplied search
+ * term so they match literally. The engine's LIKE clause pairs this with
+ * `ESCAPE '\'`, so a `%` a user types finds a literal percent sign — not "match
+ * anything". The term itself is still bound as a `?` param (no interpolation);
+ * this only prevents accidental wildcard behavior, not injection.
+ */
+function escapeLikeTerm(term) {
+    return term.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}

package/dist/pipe/record-engine.js.map

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

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

@@ -0,0 +1,47 @@
+import type { Principal } from '@astram/core';
+import type { RecordEngine, RecordInput, RecordId, RecordView, ListQuery, RecordPage } from '../types.js';
+/** Round-2 port: resolves a service-account KEY to a seeded principal. */
+export interface ServiceAccountResolver {
+    resolve(key: string): Principal;
+}
+export declare const SERVICE_ACCOUNT_RESOLVER: unique symbol;
+/**
+ * The single record-CRUD entry point a consumer app uses. Request-scoped: it reads the
+ * guard-resolved `req.principal` and forwards it to the platform-agnostic (singleton)
+ * RecordEngine as the `actor` — so the app never threads identity, and record permission
+ * (decide()) runs in the framework with identity it already has. Fail-closed: no principal
+ * (and no `.as()`) ⇒ throw, never act as nobody.
+ */
+export declare class RecordsService {
+    private readonly engine;
+    private readonly req;
+    private readonly serviceAccounts?;
+    constructor(engine: RecordEngine, req: {
+        principal?: Principal;
+    }, serviceAccounts?: ServiceAccountResolver | undefined);
+    create(typeKey: string, input: RecordInput): Promise<RecordId>;
+    get(typeKey: string, id: RecordId): Promise<RecordView | null>;
+    list(typeKey: string, query: ListQuery): Promise<RecordPage>;
+    update(typeKey: string, id: RecordId, input: RecordInput): Promise<void>;
+    delete(typeKey: string, id: RecordId): Promise<void>;
+    /**
+     * Run subsequent ops as a declared identity (an in-request act-as, or — via a
+     * registered resolver — a named service account). Explicit + auditable; never a
+     * silent default. A string key requires a ServiceAccountResolver (Round 2).
+     */
+    as(who: string | Principal): BoundRecords;
+    private actor;
+    private resolveServiceAccount;
+}
+/** The `.as(...)` bound view — same 5 ops, fixed actor. */
+export declare class BoundRecords {
+    private readonly engine;
+    private readonly actor;
+    constructor(engine: RecordEngine, actor: Principal);
+    create(typeKey: string, input: RecordInput): Promise<RecordId>;
+    get(typeKey: string, id: RecordId): Promise<RecordView | null>;
+    list(typeKey: string, query: ListQuery): Promise<RecordPage>;
+    update(typeKey: string, id: RecordId, input: RecordInput): Promise<void>;
+    delete(typeKey: string, id: RecordId): Promise<void>;
+}
+//# sourceMappingURL=records-service.d.ts.map

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

@@ -0,0 +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,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG1G,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;IACS,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;gBAFvC,MAAM,EAAE,YAAY,EAC1B,GAAG,EAAE;QAAE,SAAS,CAAC,EAAE,SAAS,CAAA;KAAE,EACD,eAAe,CAAC,EAAE,sBAAsB,YAAA;IAWnG,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;IAI1D;;;;OAIG;IACH,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY;IAKzC,OAAO,CAAC,KAAK;IAWb,OAAO,CAAC,qBAAqB;CAS9B;AAED,2DAA2D;AAC3D,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,SAAS;IAEnC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC9D,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAC5D,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IACxE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CACrD"}

package/dist/pipe/records-service.js

@@ -0,0 +1,108 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundRecords = exports.RecordsService = exports.SERVICE_ACCOUNT_RESOLVER = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const tokens_js_1 = require("../module/tokens.js");
+const errors_js_1 = require("../errors.js");
+exports.SERVICE_ACCOUNT_RESOLVER = Symbol('SERVICE_ACCOUNT_RESOLVER');
+/**
+ * The single record-CRUD entry point a consumer app uses. Request-scoped: it reads the
+ * guard-resolved `req.principal` and forwards it to the platform-agnostic (singleton)
+ * RecordEngine as the `actor` — so the app never threads identity, and record permission
+ * (decide()) runs in the framework with identity it already has. Fail-closed: no principal
+ * (and no `.as()`) ⇒ throw, never act as nobody.
+ */
+let RecordsService = class RecordsService {
+    engine;
+    req;
+    serviceAccounts;
+    constructor(engine, req, serviceAccounts) {
+        this.engine = engine;
+        this.req = req;
+        this.serviceAccounts = serviceAccounts;
+    }
+    // NOTE: `async` here is load-bearing, not stylistic. `this.actor()` throws
+    // SYNCHRONOUSLY when there is no request principal (fail-closed). Without
+    // `async`, that throw would escape as a synchronous exception from e.g.
+    // `svc.create(...)` — before a Promise even exists — which breaks every
+    // caller that (correctly) expects a Promise it can `await`/`.catch()`
+    // (incl. `expect(svc.create(...)).rejects...` in this file's own test
+    // suite). `async` captures the synchronous throw into a rejected Promise,
+    // matching the declared `Promise<...>` return type exactly.
+    async create(typeKey, input) {
+        return this.engine.create(typeKey, input, this.actor());
+    }
+    async get(typeKey, id) {
+        return this.engine.get(typeKey, id, this.actor());
+    }
+    async list(typeKey, query) {
+        return this.engine.list(typeKey, query, this.actor());
+    }
+    async update(typeKey, id, input) {
+        return this.engine.update(typeKey, id, input, this.actor());
+    }
+    async delete(typeKey, id) {
+        return this.engine.delete(typeKey, id, this.actor());
+    }
+    /**
+     * Run subsequent ops as a declared identity (an in-request act-as, or — via a
+     * registered resolver — a named service account). Explicit + auditable; never a
+     * silent default. A string key requires a ServiceAccountResolver (Round 2).
+     */
+    as(who) {
+        const actor = typeof who === 'string' ? this.resolveServiceAccount(who) : who;
+        return new BoundRecords(this.engine, actor);
+    }
+    actor() {
+        const p = this.req?.principal;
+        if (!p) {
+            throw new errors_js_1.EngineUnavailableError('RecordsService used with no request principal. In a request the guard sets it; ' +
+                'outside a request use records.as(<service-account>). Refusing to act as nobody.');
+        }
+        return p;
+    }
+    resolveServiceAccount(key) {
+        if (!this.serviceAccounts) {
+            throw new errors_js_1.EngineUnavailableError(`records.as('${key}') requires a ServiceAccountResolver, which is not configured. ` +
+                'Seed + register service accounts (Round 2) before using .as() with a key.');
+        }
+        return this.serviceAccounts.resolve(key);
+    }
+};
+exports.RecordsService = RecordsService;
+exports.RecordsService = RecordsService = __decorate([
+    (0, common_1.Injectable)({ scope: common_1.Scope.REQUEST }),
+    __param(0, (0, common_1.Inject)(tokens_js_1.RECORD_ENGINE)),
+    __param(1, (0, common_1.Inject)(core_1.REQUEST)),
+    __param(2, (0, common_1.Optional)()),
+    __param(2, (0, common_1.Inject)(exports.SERVICE_ACCOUNT_RESOLVER)),
+    __metadata("design:paramtypes", [Object, Object, Object])
+], RecordsService);
+/** The `.as(...)` bound view — same 5 ops, fixed actor. */
+class BoundRecords {
+    engine;
+    actor;
+    constructor(engine, actor) {
+        this.engine = engine;
+        this.actor = actor;
+    }
+    create(typeKey, input) { return this.engine.create(typeKey, input, this.actor); }
+    get(typeKey, id) { return this.engine.get(typeKey, id, this.actor); }
+    list(typeKey, query) { return this.engine.list(typeKey, query, this.actor); }
+    update(typeKey, id, input) { return this.engine.update(typeKey, id, input, this.actor); }
+    delete(typeKey, id) { return this.engine.delete(typeKey, id, this.actor); }
+}
+exports.BoundRecords = BoundRecords;

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

@@ -0,0 +1,15 @@
+/**
+ * Stage: audit (MANDATORY). Records an append-only audit event for the write via the
+ * injected {@link AuditPort} (core's AuditSink). Like the permission gate, this stage
+ * is a fixed segment of the pipe — there is no way for a caller to skip it, so EVERY
+ * write is attributable. Runs after the write succeeds, inside the same transaction,
+ * so the audit row commits atomically with the data (no data without its audit).
+ *
+ * The event carries the actor, tenant, action, and resource — NEVER the row's secret
+ * values (core's audit sink additionally strips sensitive keys). Actor is referenced
+ * by stable id; the presentation layer resolves it to a label (no raw ids to users).
+ */
+import type { AuditPort } from '../../ports.js';
+import type { Stage } from '../context.js';
+export declare function auditStage(audit: AuditPort): Stage;
+//# sourceMappingURL=audit.d.ts.map

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

@@ -0,0 +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,CA0BlD"}