@astram/engine 0.3.0 → 0.5.0

package/dist/pipe/record-engine.js

@@ -4,23 +4,27 @@
  *
  * 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).
+ *   type-pre-gate (update/delete) → fetch-record (update/delete) → 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.)
+ * Reads: get() is fetch → gate (on the row's fields + tenant) → project the same row;
+ * list() is gate (object type) → SQL-scoped query (list scope fragment, no fetch-then-
+ * discard) → project, ordered with a PK tiebreaker. (Column projection is still pending, G2.)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RecordEngineImpl = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
 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_owner_js_1 = require("./stages/fetch-owner.js");
+const fetch_record_js_1 = require("./stages/fetch-record.js");
+const where_by_id_js_1 = require("./where-by-id.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");
@@ -28,6 +32,16 @@ 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");
+/** Fail closed when a transaction handle outlives its transaction or is already doomed. */
+function assertUsable(tx) {
+    if (!tx.open) {
+        throw new errors_js_2.EngineUnavailableError('record transaction has already ended; a transaction handle cannot be used after its ' +
+            'transaction(fn) settled.');
+    }
+    if (tx.failure !== undefined) {
+        throw new errors_js_2.EngineUnavailableError('record transaction is rollback-only: an earlier write inside it failed.');
+    }
+}
 class RecordEngineImpl {
     registry;
     uow;
@@ -38,6 +52,8 @@ class RecordEngineImpl {
     listScope;
     /** The FIXED write-stage order. Built once; identical for every write. */
     writeStages;
+    /** The ambient `transaction(fn)` (ADR-0034) so plain calls made inside `fn` join it. */
+    activeTx = new node_async_hooks_1.AsyncLocalStorage();
     constructor(deps) {
         this.registry = deps.registry;
         this.uow = deps.uow;
@@ -47,11 +63,14 @@ class RecordEngineImpl {
         this.onRecordDeleted = deps.onRecordDeleted;
         this.listScope = deps.listScope;
         // 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).
+        // fetch-record runs FIRST (before the gate): for update/delete on EVERY type it row-locks
+        // and reads the existing row through the shared whereById, so decide() sees the record's
+        // fields, owner and tenant (block D, #10). A missing row throws there. No-op for create.
+        // type-pre-gate runs before it (Phase 8 #7): a coarse object-type decide() so an actor with
+        // no permission on the type is denied before it can take any row lock. No-op for create.
         this.writeStages = [
-            (0, fetch_owner_js_1.fetchOwnerStage)(),
+            (0, permission_gate_js_1.typePreGateStage)(this.decision),
+            (0, fetch_record_js_1.fetchRecordStage)(),
             (0, permission_gate_js_1.permissionGateStage)(this.decision),
             (0, derive_write_context_js_1.deriveWriteContextStage)(),
             (0, validate_js_1.validateStage)(),
@@ -62,10 +81,100 @@ class RecordEngineImpl {
             // emit-event stage: Phase-1 no-op (business rules land later)
         ];
     }
-    async runWrite(op, typeKey, actor, opts) {
+    // --- transactions (ADR-0034) ---------------------------------------------------
+    /**
+     * Run `fn` in ONE unit of work: every op on the handle, and every plain call on this engine
+     * made from inside `fn` (found via AsyncLocalStorage), shares the transaction. Each op still
+     * runs its full pipe. Commit on resolve, rollback on throw. ROLLBACK-ONLY once any write op
+     * (or a nested `fn`) inside it has failed, even if the caller swallowed the error — so the
+     * INSERT of a create the wall denied can never be committed by a careless `catch`. Nested calls
+     * reuse the outer transaction; a handle used after its transaction ended fails closed.
+     */
+    async transaction(fn) {
+        return this.transactionIn(undefined, fn);
+    }
+    async transactionIn(bound, fn) {
+        const outer = bound ?? this.activeTx.getStore();
+        if (outer !== undefined) {
+            // NESTED: reuse the outer unit of work. A throw out of the nested fn marks the outer
+            // transaction rollback-only (its writes must not commit just because an outer catch ran).
+            assertUsable(outer);
+            try {
+                return await fn(this.handleFor(outer));
+            }
+            catch (err) {
+                outer.failure ??= err;
+                throw err;
+            }
+        }
+        return this.uow.run(async (query) => {
+            const state = { query, open: true, failure: undefined };
+            try {
+                const out = await this.activeTx.run(state, () => fn(this.handleFor(state)));
+                // Rollback-only: a write failed inside fn and the caller swallowed it ⇒ re-raise it so
+                // the unit of work rolls back instead of committing a partial write.
+                if (state.failure !== undefined)
+                    throw state.failure;
+                return out;
+            }
+            finally {
+                state.open = false;
+            }
+        });
+    }
+    /** The transaction-bound engine handle passed to `transaction(fn)`. */
+    handleFor(state) {
+        return {
+            create: (typeKey, input, actor) => this.createIn(state, typeKey, input, actor),
+            update: (typeKey, id, input, actor) => this.updateIn(state, typeKey, id, input, actor),
+            delete: (typeKey, id, actor) => this.deleteIn(state, typeKey, id, actor),
+            get: (typeKey, id, actor) => this.getIn(state, typeKey, id, actor),
+            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),
+        };
+    }
+    /**
+     * Row lock on one record inside the open transaction (see `RecordEngine.lockForUpdate`). Keyed
+     * by the primary key only and returning nothing, so it reveals no data and needs no read gate.
+     */
+    async lockForUpdate(typeKey, id, actor) {
+        return this.lockIn(undefined, typeKey, id, actor);
+    }
+    async lockIn(bound, typeKey, id, _actor) {
+        const tx = bound ?? this.activeTx.getStore();
+        if (tx === undefined) {
+            throw new errors_js_2.EngineUnavailableError('lockForUpdate needs an open transaction(fn): a lock taken outside one is released at ' +
+                'once and serialises nothing.');
+        }
+        assertUsable(tx);
+        const reg = this.registry.require(typeKey);
+        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);
+    }
+    /**
+     * 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
+     * shared transaction marks it rollback-only.
+     */
+    async inUnit(bound, write, body) {
+        const tx = bound ?? this.activeTx.getStore();
+        if (tx === undefined)
+            return this.uow.run(body);
+        assertUsable(tx);
+        try {
+            return await body(tx.query);
+        }
+        catch (err) {
+            if (write)
+                tx.failure ??= err;
+            throw err;
+        }
+    }
+    async runWrite(tx, op, typeKey, actor, opts) {
         const registration = this.registry.require(typeKey); // resolve-schema
         const nowMs = this.now();
-        return this.uow.run(async (query) => {
+        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 } : {}),
@@ -90,32 +199,42 @@ class RecordEngineImpl {
         });
     }
     async create(typeKey, input, actor) {
-        const id = await this.runWrite('create', typeKey, actor, { input });
+        return this.createIn(undefined, typeKey, input, actor);
+    }
+    async update(typeKey, id, input, actor) {
+        return this.updateIn(undefined, typeKey, id, input, actor);
+    }
+    async delete(typeKey, id, actor) {
+        return this.deleteIn(undefined, typeKey, id, 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;
     }
-    async update(typeKey, id, input, actor) {
-        await this.runWrite('update', typeKey, actor, { id, input });
+    async updateIn(tx, typeKey, id, input, actor) {
+        await this.runWrite(tx, 'update', typeKey, actor, { id, input });
     }
-    async delete(typeKey, id, actor) {
-        await this.runWrite('delete', typeKey, actor, { id });
+    async deleteIn(tx, typeKey, id, actor) {
+        await this.runWrite(tx, 'delete', typeKey, actor, { id });
     }
     // --- reads -----------------------------------------------------------------
-    async gateRead(registration, actor, id, ownerId) {
+    async gateRead(registration, actor, id, record) {
         const action = { key: 'read' };
         const resource = {
             level: id !== undefined ? 'record' : 'object_type',
             typeKey: registration.typeKey,
-            tenantId: actor.tenantId,
+            // Block D (#10): a fetched record is judged at ITS tenant; otherwise the actor's.
+            tenantId: record?.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).
+        // For a fetched record, every registered field + `ownerId` reach decide() (block D), so a
+        // field-conditioned rule fires on get() as it does in list(). No record (a missing row) ⇒
+        // no attributes ⇒ an owned type's owner baseline cannot match ⇒ deny, as before.
         const context = {
             isAuthenticated: true,
-            ...(ownerId !== undefined ? { attributes: { ownerId } } : {}),
+            ...(record !== undefined ? { attributes: record.attributes } : {}),
         };
         let outcome;
         try {
@@ -129,7 +248,7 @@ class RecordEngineImpl {
         }
     }
     qualified(reg) {
-        return reg.schema ? `\`${reg.schema}\`.\`${reg.table}\`` : `\`${reg.table}\``;
+        return (0, where_by_id_js_1.qualifiedTable)(reg);
     }
     /** Project a raw DB row → RecordView (field keys, not columns). */
     project(reg, row) {
@@ -152,29 +271,30 @@ class RecordEngineImpl {
         return { id, fields };
     }
     async get(typeKey, id, actor) {
+        return this.getIn(undefined, typeKey, id, actor);
+    }
+    async list(typeKey, query, actor) {
+        return this.listIn(undefined, typeKey, query, actor);
+    }
+    async getIn(tx, 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]);
-            }
+        return this.inUnit(tx, false, async (query) => {
+            const pk = (0, where_by_id_js_1.pkClause)(reg, id);
+            let where = pk.sql;
+            let params = pk.params;
             // Tenant scoping: if the table has a tenant column, constrain to the actor's reachable
             // subtree (ADR-0027 — active node + descendants), NOT just the self-node. ROOT spans all
             // tenants — only a STRICT `=== true` isRoot counts (fail-closed). Fail-safe to the
             // self-node if the subtree is malformed/absent (non-widening).
+            // Review M6 (get ≡ list): exactly as in list(), when the record-level list scope is wired
+            // its fragment is the ONE tenant authority (it carries the own-subtree bound AND the
+            // cross-tenant grant reach), so the built-in clause is deferred to it.
+            // Resolve the list-scope fragment FIRST (a throw propagates before any SELECT). An EMPTY
+            // fragment never drops the tenant bound (review L1): the built-in clause then applies.
+            const fragment = this.listScope ? await this.listScope(reg, actor, 'read') : null;
+            const fragmentSql = fragment?.sql ? fragment : null;
             const tenantCol = this.tenantColumn(reg);
-            if (tenantCol && actor.isRoot !== true) {
+            if (tenantCol && actor.isRoot !== true && !fragmentSql) {
                 const nodes = this.tenantScopeNodes(actor);
                 where += ` AND \`${tenantCol}\` IN (${nodes.map(() => '?').join(', ')})`;
                 params = [...params, ...nodes];
@@ -188,37 +308,39 @@ class RecordEngineImpl {
                 where += ` AND ${scope.sql}`;
                 params = [...params, ...scope.params];
             }
-            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;
+            // Review M6: AND the SAME list-scope fragment list() uses, so get() reaches exactly the
+            // rows list() shows (incl. cross-tenant-granted ones) and hides what list() hides. A throw
+            // propagates (fail closed) before any SELECT runs.
+            if (fragmentSql) {
+                where += ` AND ${fragmentSql.sql}`;
+                params = [...params, ...fragmentSql.params];
             }
-            // 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);
+            // FETCH-THEN-GATE for EVERY type (block D, #10). Core's decide() is zero-dep and cannot
+            // read the row, so the row is SELECTed first and its fields, owner and tenant are handed
+            // to the gate. ⛔ THE FETCHED ROW IS NEVER SURFACED UNLESS THE GATE ALLOWS: gateRead
+            // throws on deny before project(). The SAME row is projected (no second query).
             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;
+            if (first === undefined) {
+                // Missing — or outside the walled WHERE (foreign tenant/subtree, hidden by the list
+                // scope): indistinguishable by construction. Gate as before this change: record level,
+                // no attributes, actor tenant ⇒ an owned type denies (no owner match), any other type
+                // answers null. The caller learns nothing it did not learn before.
+                await this.gateRead(reg, actor, id);
+                return null;
+            }
+            const facts = (0, fetch_record_js_1.recordFacts)(reg, first);
+            await this.gateRead(reg, actor, id, {
+                attributes: (0, fetch_record_js_1.decisionAttributes)(reg, facts),
+                ...(facts.tenantId !== undefined ? { tenantId: facts.tenantId } : {}),
+            });
+            return this.project(reg, first);
         });
     }
-    async list(typeKey, query, actor) {
+    async listIn(tx, typeKey, query, actor) {
         const reg = this.registry.require(typeKey);
         await this.gateRead(reg, actor);
-        return this.uow.run(async (q) => {
+        return this.inUnit(tx, false, async (q) => {
             const clauses = [];
             const params = [];
             // Mandatory tenant scoping when the table is tenant-owned (cross-tenant safety).
@@ -239,8 +361,12 @@ class RecordEngineImpl {
             // 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 && !this.listScope) {
+            if (tenantCol && actor.isRoot !== true && !listFragmentSql) {
                 const nodes = this.tenantScopeNodes(actor);
                 clauses.push(`\`${tenantCol}\` IN (${nodes.map(() => '?').join(', ')})`);
                 params.push(...nodes);
@@ -289,28 +415,37 @@ class RecordEngineImpl {
             // (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 simply not ANDed (no fabricated widening).
-            if (this.listScope) {
-                const scope = await this.listScope(reg, actor, 'read');
-                if (scope.sql) {
-                    clauses.push(scope.sql);
-                    params.push(...scope.params);
-                }
+            // 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 ')}` : '';
             // 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 = '';
+            //
+            // Review M1: the PK column(s) are ALWAYS appended as the final tiebreaker (`ORDER BY <pk>`
+            // alone when there is no sortBy), so the order is total and OFFSET paging never repeats or
+            // skips rows that tie on the sort column. PK columns come from `primaryKey` (often not a
+            // registered field); a PK column already used as the sort key is not repeated.
+            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';
-                orderBy = `ORDER BY \`${(0, registry_js_1.columnOf)(field)}\` ${dir}`;
+                sortColumn = (0, registry_js_1.columnOf)(field);
+                orderTerms.push(`\`${sortColumn}\` ${dir}`);
+            }
+            for (const col of (0, where_by_id_js_1.pkColumns)(reg)) {
+                if (col !== sortColumn)
+                    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 rows = (await q(`SELECT * FROM ${this.qualified(reg)} ${where} ${orderBy} LIMIT ? OFFSET ?`, [...params, limit, offset]));

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

@@ -24,6 +24,16 @@ export declare class RecordsService {
     list(typeKey: string, query: ListQuery): Promise<RecordPage>;
     update(typeKey: string, id: RecordId, input: RecordInput): Promise<void>;
     delete(typeKey: string, id: RecordId): Promise<void>;
+    /** Row lock inside the open `transaction(fn)` (see `RecordEngine.lockForUpdate`). */
+    lockForUpdate(typeKey: string, id: RecordId): Promise<void>;
+    /**
+     * 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
+     * transaction, each still through the full gate/validate/write/audit pipe. Commits when `fn`
+     * resolves, rolls back when it throws (and when a write inside it failed, even if swallowed).
+     * Nested calls reuse the outer transaction. Fail-closed: no principal ⇒ throw before any work.
+     */
+    transaction<T>(fn: (tx: BoundRecords) => Promise<T>): Promise<T>;
     /**
      * 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
@@ -33,15 +43,22 @@ export declare class RecordsService {
     private actor;
     private resolveServiceAccount;
 }
-/** The `.as(...)` bound view — same 5 ops, fixed actor. */
+/**
+ * The `.as(...)` bound view — same 5 ops, fixed actor. Also the handle `transaction(fn)` passes
+ * (ADR-0034): there `engine` is the transaction-bound engine, so its ops share one unit of work.
+ */
 export declare class BoundRecords {
     private readonly engine;
     private readonly actor;
     constructor(engine: RecordEngine, actor: Principal);
+    /** Run `fn` in one unit of work as this actor; nested inside a transaction it is reused. */
+    transaction<T>(fn: (tx: BoundRecords) => Promise<T>): Promise<T>;
     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>;
+    /** Row lock inside the open transaction (see `RecordEngine.lockForUpdate`). */
+    lockForUpdate(typeKey: string, id: RecordId): Promise<void>;
 }
 //# 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,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"}
+{"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"}

package/dist/pipe/records-service.js

@@ -57,6 +57,21 @@ let RecordsService = class RecordsService {
     async delete(typeKey, id) {
         return this.engine.delete(typeKey, id, this.actor());
     }
+    /** Row lock inside the open `transaction(fn)` (see `RecordEngine.lockForUpdate`). */
+    async lockForUpdate(typeKey, id) {
+        return this.engine.lockForUpdate(typeKey, id, 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
+     * transaction, each still through the full gate/validate/write/audit pipe. Commits when `fn`
+     * resolves, rolls back when it throws (and when a write inside it failed, even if swallowed).
+     * Nested calls reuse the outer transaction. Fail-closed: no principal ⇒ throw before any work.
+     */
+    async transaction(fn) {
+        const actor = this.actor();
+        return this.engine.transaction((tx) => fn(new BoundRecords(tx, 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
@@ -91,7 +106,10 @@ exports.RecordsService = RecordsService = __decorate([
     __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. */
+/**
+ * The `.as(...)` bound view — same 5 ops, fixed actor. Also the handle `transaction(fn)` passes
+ * (ADR-0034): there `engine` is the transaction-bound engine, so its ops share one unit of work.
+ */
 class BoundRecords {
     engine;
     actor;
@@ -99,10 +117,28 @@ class BoundRecords {
         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); }
+    /** Run `fn` in one unit of work as this actor; nested inside a transaction it is reused. */
+    transaction(fn) {
+        return this.engine.transaction((tx) => fn(new BoundRecords(tx, this.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);
+    }
+    /** Row lock inside the open transaction (see `RecordEngine.lockForUpdate`). */
+    lockForUpdate(typeKey, id) {
+        return this.engine.lockForUpdate(typeKey, id, 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,CA0BlD"}
+{"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"}

package/dist/pipe/stages/derive-write-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive-write-context.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/derive-write-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,eAAe,CAAC;AAYzD,wBAAgB,uBAAuB,IAAI,KAAK,CA4B/C"}
+{"version":3,"file":"derive-write-context.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/derive-write-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,eAAe,CAAC;AAYzD,wBAAgB,uBAAuB,IAAI,KAAK,CAiC/C"}

package/dist/pipe/stages/derive-write-context.js

@@ -52,6 +52,12 @@ function deriveWriteContextStage() {
                         ctx.columns[col] = trustedValue(field.trusted, ctx);
                     }
                 }
+                else if (field.immutable === true && ctx.op !== 'create') {
+                    // ADR-0034: a CREATE-ONLY field. Like a trusted field on update, any client value is
+                    // IGNORED — the column is not written, so the stored value stands. Moving such a link
+                    // (a company's parent, a membership's user/company) is a dedicated, checked operation,
+                    // never a side effect of a generic patch.
+                }
                 else if (Object.prototype.hasOwnProperty.call(input, field.key)) {
                     ctx.columns[col] = input[field.key];
                 }

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

@@ -0,0 +1,56 @@
+/**
+ * Stage: fetch-record (update/delete on EVERY type — runs BEFORE the permission gate).
+ * Security hardening block D (#10); replaces the owner-only `fetch-owner` stage. Since Phase 8
+ * #7 it runs AFTER `type-pre-gate` (permission-gate.ts), so an actor with no permission on the
+ * type is denied before this stage can take a row lock.
+ *
+ * Core's decision authority is zero-dep (no DB), so it cannot read the record it judges. This
+ * stage reads the EXISTING row, inside the pipe's unit of work, with
+ *
+ *     SELECT * FROM <table> WHERE <whereById> LIMIT 1 FOR UPDATE
+ *
+ * through the SAME `whereById` the write stage uses (pk + actor-tenant clause + ADR-0030 write
+ * scope), and stashes:
+ *   - `ctx.existing`       — the row projected to registered field keys (the PRE-image, D9),
+ *   - `ctx.ownerId`        — the `trusted:'actorId'` column, when it is a string,
+ *   - `ctx.recordTenantId` — the `trusted:'tenantId'` column, when it is a string.
+ * The gate passes `attributes = { ...existing, ownerId }` and `resource.tenantId =
+ * recordTenantId ?? actor.tenantId` to `decide()`, so field-conditioned rules (e.g. deny
+ * `status eq locked`) fire on update/delete exactly as they do in `list()`.
+ *
+ * ── SECURITY (fail-closed, no existence oracle):
+ *   - No row ⇒ `AuthorizationDeniedError('no_record_permit')`, thrown inside the transaction
+ *     (rollback: no write, no junction sync, no audit). A missing id and a foreign-tenant or
+ *     foreign-subtree id both match zero rows here, so they are the same error. It is also the
+ *     reason core returns for an owned record the actor does not own, which is what the
+ *     previous owner pre-fetch produced for a missing owned row.
+ *   - `FOR UPDATE` row-locks the pre-image until commit, so the row the gate judged is the row
+ *     the write changes (no TOCTOU between gate and write).
+ *   - The row is never returned to the caller; only the gate sees it.
+ *   - `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 { Stage } from '../context.js';
+/** The decision-relevant facts of one fetched row. */
+export interface RecordFacts {
+    /** Registered fields present in the row, keyed by FIELD KEY (never the column). */
+    readonly fields: Record<string, unknown>;
+    /** The `trusted:'actorId'` column value, when the type has one and it is a string. */
+    readonly ownerId?: string;
+    /** The `trusted:'tenantId'` column value, when the type has one and it is a string. */
+    readonly tenantId?: string;
+}
+/** Project a raw row to its decision facts (shared by the write pre-fetch and `get()`). */
+export declare function recordFacts(reg: ObjectType, row: Record<string, unknown>): RecordFacts;
+/**
+ * The `context.attributes` bag for `decide()`: every registered field by key, plus `ownerId`
+ * (the owner baseline's input). When the type has an owner column, `ownerId` is that column's
+ * string value or absent: a null/non-string owner is never passed, so core's strict `===` owner
+ * match can never spuriously succeed.
+ */
+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;
+export declare function fetchRecordStage(): Stage;
+//# sourceMappingURL=fetch-record.d.ts.map

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

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