@weave-kit/engine 0.4.0 → 0.6.0

package/dist/runtime/data-access/query.js

@@ -1,14 +1,22 @@
-import { SchemaError, primaryKeyOf } from '../../core/index.js';
-import { DETAILS_COLUMNS, FIELD_TYPES } from '../../core/index.js';
+import { SchemaError, primaryFieldsOf, encodeRecordKey, decodeRecordKey, canonicalizePrimaryValue } from '../../core/index.js';
+import { DETAILS_COLUMNS, FIELD_TYPES, isSideTableVirtualField, RECORD_META_ID_FIELD, recordKeySql, recordMetaTableName } from '../../core/index.js';
 import { AUDIT_ACTOR_TYPES, DATA_ACTIONS } from '../../core/audit/index.js';
 import { NOOP_SCRIPT_DISPATCHER, SCRIPT_HOOKS } from '../../core/index.js';
+import { evaluateTransition } from '../tools/policies.js';
 import { buildCountSql, buildFindSql, scopeSuffix } from './builder.js';
 import { deleteDetailsChildren, insertDetails } from './details.js';
+import { insertLinks, replaceLinks } from './link.js';
+import { runWorkflowTransition, getWorkflowStatus, acquireWorkflowLock, releaseWorkflowLock, getWorkflowHistory, getWorkflowTodos, overrideWorkflow, } from './workflow.js';
 import { computeFormulas } from './formula.js';
-import { ensureSeqTable, generateSeqNo } from './seqno.js';
+import { generateSeqNo } from './seqno.js';
 import { validateRecord } from './validate.js';
 import { WRITE_MODES } from './values.js';
+import { upsertRecordMeta, deleteRecordMeta } from '../record-meta/index.js';
 const q = (id) => `"${id}"`;
+/** cross-object formula authorization derived from the request context */
+function formulaAuth(ctx) {
+    return { subject: ctx.subject, roles: ctx.subject?.roles ?? [], locale: ctx.locale };
+}
 /** PG error 42703 = undefined_column: a query referenced a column that doesn't exist */
 function isUndefinedColumn(error) {
     return typeof error === 'object' && error !== null && error.code === '42703';
@@ -21,6 +29,21 @@ function undefinedColumnOf(error) {
     const m = /column "([^"]+)" of relation/.exec(message);
     return m?.[1];
 }
+/** PG error 23505 = unique_violation: a unique constraint (column or object constraint) was hit */
+function isUniqueViolation(error) {
+    return typeof error === 'object' && error !== null && error.code === '23505';
+}
+/** readable field list behind a unique violation (from the detail `Key (a, b)=(...)`) */
+function uniqueFieldsOf(error) {
+    const detail = error?.detail;
+    if (typeof detail === 'string') {
+        const m = /Key \(([^)]+)\)/.exec(detail);
+        if (m?.[1] !== undefined)
+            return m[1];
+    }
+    const constraint = error?.constraint;
+    return typeof constraint === 'string' ? constraint : '?';
+}
 /**
  * Run a SQL statement against an object's table, mapping PG `undefined_column`
  * (42703) — a schema/DB drift (schema declares a field the table lacks) — to an
@@ -35,6 +58,9 @@ async function runTableQuery(q, objectName, sql, params, locale) {
             const field = undefinedColumnOf(error);
             throw new SchemaError('data.schemaDrift', { object: objectName, field: field ?? '' }, locale);
         }
+        if (isUniqueViolation(error)) {
+            throw new SchemaError('data.unique', { object: objectName, fields: uniqueFieldsOf(error) }, locale);
+        }
         throw error;
     }
 }
@@ -64,7 +90,7 @@ function scriptUserOf(ctx) {
     return {
         id: ctx.subject?.id ?? 'system',
         roles: ctx.subject?.roles ?? [],
-        teamId: ctx.subject?.teamId,
+        departmentId: ctx.subject?.departmentId,
     };
 }
 const PARENT_COLUMNS = new Set([
@@ -84,7 +110,99 @@ function requireDef(ctx, objectName) {
     return def;
 }
 function bctx(ctx, objectName) {
-    return { object: objectName, locale: ctx.locale, allowParentCols: isDetailsChild(ctx.registry, objectName) };
+    return {
+        object: objectName,
+        locale: ctx.locale,
+        allowParentCols: isDetailsChild(ctx.registry, objectName),
+        lookup: ctx.registry,
+        ...(ctx.subject === undefined ? {} : { subject: ctx.subject }),
+    };
+}
+/** hidden select column carrying the SQL-computed record_key for a fetched row */
+const META_KEY_COL = '__weave_record_key';
+/** select expression for the SQL-computed record_key (lossless for temporal keys) */
+function recordKeySelect(def) {
+    return `${recordKeySql(def, (name) => q(name))} AS ${q(META_KEY_COL)}`;
+}
+/** the record_key of a row, from its declared primary fields (declaration order) */
+function recordKeyOfRow(def, record) {
+    return encodeRecordKey(primaryFieldsOf(def).map((f) => canonicalizePrimaryValue(record[f.name])));
+}
+/** declared primary field names, in declaration order */
+function primaryNames(def) {
+    return primaryFieldsOf(def).map((f) => f.name);
+}
+/** decode an external id (the record_key, for single and composite keys alike) into primary values */
+function pkValuesOf(def, id, ctx) {
+    const names = primaryNames(def);
+    let values;
+    try {
+        values = decodeRecordKey(id);
+    }
+    catch {
+        throw new SchemaError('recordKey.invalid', { key: id }, ctx.locale);
+    }
+    if (values.length !== names.length) {
+        throw new SchemaError('recordKey.invalid', { key: id }, ctx.locale);
+    }
+    return values;
+}
+/** primary-key filter object for `find` (declared names zipped with values) */
+function pkFilter(def, values) {
+    const filter = {};
+    primaryNames(def).forEach((name, i) => {
+        filter[name] = values[i];
+    });
+    return filter;
+}
+/** `"a" = $1 AND "b" = $2` predicate for the primary names, starting at `startIndex` */
+function pkWhereSql(def, startIndex) {
+    return primaryNames(def)
+        .map((name, i) => `${q(name)} = $${startIndex + i}`)
+        .join(' AND ');
+}
+/** the external id of a record: always its record_key (single and composite keys alike) */
+function externalIdOf(def, record) {
+    return recordKeyOfRow(def, record);
+}
+/** true when the query references a side-table virtual field (`weave_*` minus the derived `weave_id`) */
+function needsSideTable(opts) {
+    if ((opts.fields ?? []).some((f) => isSideTableVirtualField(f)))
+        return true;
+    if ((opts.sort ?? []).some((s) => isSideTableVirtualField(s.field)))
+        return true;
+    const filter = opts.filter;
+    if (filter !== undefined) {
+        for (const [key, value] of Object.entries(filter)) {
+            if (key === '$or') {
+                if (Array.isArray(value) &&
+                    value.some((group) => group !== null &&
+                        typeof group === 'object' &&
+                        Object.keys(group).some((k) => isSideTableVirtualField(k)))) {
+                    return true;
+                }
+            }
+            else if (isSideTableVirtualField(key)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Narrow `ToolDataAccess` over this data-access for guardrail policies: a policy
+ * calls `ctx.dataAccess.find(obj, opts, { subject? })` with no pool/registry, so
+ * those are injected from the execution context (mirrors the tool executor's
+ * wrapper; `...c` lets a policy override the subject per call).
+ */
+function toolDataAccessOver(inner, base) {
+    return {
+        find: (n, o, c) => inner.find(n, o, { ...base, ...c }),
+        findOne: (n, id, c) => inner.findOne(n, id, { ...base, ...c }),
+        create: (n, d, c) => inner.create(n, d, { ...base, ...c }),
+        update: (n, id, changes, c) => inner.update(n, id, changes, { ...base, ...c }),
+        delete: (n, id, c) => inner.delete(n, id, { ...base, ...c }),
+    };
 }
 /**
  * Serialize a value for binding to a DB column. pg (node-postgres) auto-stringifies
@@ -93,7 +211,10 @@ function bctx(ctx, objectName) {
  * (arrays/objects/numbers/booleans) to valid JSON text. `null` stays SQL NULL.
  */
 function dbJsonValue(field, value) {
-    if (field !== undefined && field.type === FIELD_TYPES.JSON && value !== null && typeof value !== 'string') {
+    if (field !== undefined &&
+        (field.type === FIELD_TYPES.JSON || field.type === FIELD_TYPES.JSONB) &&
+        value !== null &&
+        typeof value !== 'string') {
         return JSON.stringify(value);
     }
     return value;
@@ -102,17 +223,26 @@ function dbJsonValue(field, value) {
 export class DefaultObjectDataAccess {
     audit;
     script;
-    /** M10 diff replay: attach before/after row snapshots to update/delete audit events */
+    /** audit diff replay: attach before/after row snapshots to update/delete audit events */
     replay;
-    /** M12 live events: publish committed writes to the bus (undefined = zero overhead) */
+    /** live events: publish committed writes to the bus (undefined = zero overhead) */
     events;
     /** objects currently dispatching onLoad — skips re-entrant onLoad (a hook re-reading the same object) */
     onLoadInFlight = new Set();
+    /** guardrail policies shared with the open-contract (empty = no policy gate on transitions) */
+    policies;
+    /** approval queue used when a policy or a transition requires approval */
+    approvals;
+    /** workflow timer handle: re-arm/cancel a record's `onTimeout` on state changes */
+    workflowTimers;
     constructor(options = {}) {
         this.audit = options.audit;
         this.script = options.script ?? NOOP_SCRIPT_DISPATCHER;
         this.replay = options.replay ?? false;
         this.events = options.events;
+        this.policies = options.policies ?? [];
+        this.approvals = options.approvals;
+        this.workflowTimers = options.workflowTimers;
     }
     /**
      * Run the read hook (`onLoad`) over a fetched batch. The hook receives the
@@ -150,13 +280,14 @@ export class DefaultObjectDataAccess {
      * hook failure → the surrounding transaction rolls back. Returns the
      * possibly-modified changes from beforeUpdate (undefined = keep original).
      */
-    async runBeforeHook(hook, objectName, record, changes, ctx) {
+    async runBeforeHook(hook, objectName, record, changes, ctx, extra) {
         if (!this.script.has(objectName, hook))
             return undefined;
         const result = await this.script.dispatch(objectName, hook, {
             record,
             changes,
             user: scriptUserOf(ctx),
+            ...(extra ?? {}),
         });
         return result.changes;
     }
@@ -165,7 +296,7 @@ export class DefaultObjectDataAccess {
      * committed, so a hook failure is a non-fatal warning: recorded to audit and
      * delivered via `ctx.onWarnings`, never rethrown.
      */
-    async runAfterHook(hook, action, objectName, record, changes, ctx, warnings, objectId) {
+    async runAfterHook(hook, action, objectName, record, changes, ctx, warnings, objectId, extra) {
         if (!this.script.has(objectName, hook))
             return;
         try {
@@ -173,6 +304,7 @@ export class DefaultObjectDataAccess {
                 record,
                 changes,
                 user: scriptUserOf(ctx),
+                ...(extra ?? {}),
             });
         }
         catch (error) {
@@ -189,26 +321,33 @@ export class DefaultObjectDataAccess {
     async find(objectName, opts, ctx) {
         const def = requireDef(ctx, objectName);
         const q = ctx.client ?? ctx.pool;
-        const { sql, params } = buildFindSql(def, opts, bctx(ctx, objectName), ctx.rowScope, opts.exclude);
+        // `weave_*` virtual fields live in the engine side table; when referenced,
+        // LEFT JOIN it and select/filter/sort them in SQL (never customer columns)
+        const meta = needsSideTable(opts) ? { table: recordMetaTableName(def.name) } : undefined;
+        const buildCtx = { ...bctx(ctx, objectName), ...(meta === undefined ? {} : { meta }) };
+        const { sql, params } = buildFindSql(def, opts, buildCtx, ctx.rowScope, opts.exclude);
         const { rows } = await runTableQuery(q, objectName, sql, params, ctx.locale);
-        const { sql: countSql, params: countParams } = buildCountSql(def, opts, bctx(ctx, objectName), ctx.rowScope);
+        const { sql: countSql, params: countParams } = buildCountSql(def, opts, buildCtx, ctx.rowScope);
         const { rows: countRows } = await runTableQuery(q, objectName, countSql, countParams, ctx.locale);
         const loaded = await this.runOnLoad(objectName, rows, ctx);
         return { rows: loaded, total: countRows[0].total };
     }
     async findOne(objectName, id, ctx) {
         const def = requireDef(ctx, objectName);
-        const pk = primaryKeyOf(def);
-        if (pk === undefined) {
+        if (primaryNames(def).length === 0) {
             throw new SchemaError('data.recordNotFound', { object: objectName, id }, ctx.locale);
         }
-        const result = await this.find(objectName, { filter: { [pk]: id }, limit: 1 }, ctx);
+        // project every declared column plus the derived `weave_id` (the record's
+        // external id) so a fetched record is self-identifying
+        const cols = def.fields.filter((f) => f.type !== FIELD_TYPES.DETAILS).map((f) => f.name);
+        if (isDetailsChild(ctx.registry, objectName))
+            cols.push(...PARENT_COLUMNS);
+        const result = await this.find(objectName, { filter: pkFilter(def, pkValuesOf(def, id, ctx)), limit: 1, fields: [...cols, RECORD_META_ID_FIELD] }, ctx);
         return result.rows[0] ?? null;
     }
     async create(objectName, data, ctx) {
         const def = requireDef(ctx, objectName);
-        const pk = primaryKeyOf(def);
-        if (pk === undefined) {
+        if (primaryNames(def).length === 0) {
             throw new SchemaError('data.recordNotFound', { object: objectName }, ctx.locale);
         }
         let client;
@@ -243,14 +382,16 @@ export class DefaultObjectDataAccess {
                 if (payload[field.name] !== undefined)
                     continue;
                 record[field.name] =
-                    (field.type === FIELD_TYPES.DATETIME || field.type === FIELD_TYPES.DATE) && raw.default === 'now'
+                    (field.type === FIELD_TYPES.DATE ||
+                        field.type === FIELD_TYPES.TIMESTAMP ||
+                        field.type === FIELD_TYPES.TIMESTAMPTZ) &&
+                        raw.default === 'now'
                         ? now.toISOString()
                         : raw.default;
             }
             Object.assign(record, payload);
             const seqFields = def.fields.filter((f) => f.type === FIELD_TYPES.SEQ_NO);
             if (seqFields.length > 0) {
-                await ensureSeqTable(client);
                 for (const f of seqFields)
                     record[f.name] = await generateSeqNo(client, def.name, f, now);
             }
@@ -261,29 +402,37 @@ export class DefaultObjectDataAccess {
                 record[DETAILS_COLUMNS.PARENT_IDX] = res.rows[0].n;
             }
             const cols = [
-                ...def.fields.filter((f) => f.type !== FIELD_TYPES.DETAILS).map((f) => f.name),
+                ...def.fields
+                    .filter((f) => f.type !== FIELD_TYPES.DETAILS && f.type !== FIELD_TYPES.MULTI_RELATION)
+                    .map((f) => f.name),
                 ...(child ? [...PARENT_COLUMNS] : []),
             ];
             const fieldByName = new Map(def.fields.map((f) => [f.name, f]));
             const values = cols.map((c) => dbJsonValue(fieldByName.get(c), record[c] ?? null));
             const placeholders = cols.map((_, i) => `$${i + 1}`).join(', ');
-            await runTableQuery(client, def.name, `INSERT INTO ${q(def.name)} (${cols.map(q).join(', ')}) VALUES (${placeholders})`, values, ctx.locale);
-            await insertDetails(client, def, record[pk], payload, ctx.registry, ctx.locale);
+            const insertRes = await runTableQuery(client, def.name, `INSERT INTO ${q(def.name)} (${cols.map(q).join(', ')}) VALUES (${placeholders}) RETURNING ${recordKeySql(def, q)} AS ${q(META_KEY_COL)}`, values, ctx.locale);
+            const metaKey = String(insertRes.rows[0]?.[META_KEY_COL] ?? '');
+            const externalId = metaKey;
+            record[RECORD_META_ID_FIELD] = externalId;
+            await insertDetails(client, def, externalId, payload, ctx.registry, ctx.locale);
+            await insertLinks(client, def, primaryFieldsOf(def).map((f) => record[f.name]), payload, ctx.registry, ctx.locale);
             // compute formula fields AFTER children exist (aggregates see them), then persist
-            await computeFormulas(def, record, client, ctx.registry, now);
+            await computeFormulas(def, record, client, ctx.registry, now, externalId, formulaAuth(ctx));
             const formulaCols = def.fields
                 .filter((f) => f.formula !== undefined)
                 .map((f) => f.name);
             if (formulaCols.length > 0) {
                 const setSql = formulaCols.map((c, i) => `${q(c)} = $${i + 1}`).join(', ');
                 const formulaValues = formulaCols.map((c) => record[c] ?? null);
-                await runTableQuery(client, def.name, `UPDATE ${q(def.name)} SET ${setSql} WHERE ${q(pk)} = $${formulaCols.length + 1}`, [...formulaValues, record[pk]], ctx.locale);
+                const pkValues = pkValuesOf(def, externalId, ctx);
+                await runTableQuery(client, def.name, `UPDATE ${q(def.name)} SET ${setSql} WHERE ${pkWhereSql(def, formulaCols.length + 1)}`, [...formulaValues, ...pkValues], ctx.locale);
             }
+            await this.writeRecordMeta(client, def, metaKey, ctx, now, true);
             if (owned)
                 await client.query('COMMIT');
-            auditWrite(this.audit, ctx, DATA_ACTIONS.CREATE, objectName, String(record[pk] ?? ''), record);
-            this.events?.publishRecordChange('created', objectName, String(record[pk] ?? ''));
-            await this.runAfterHook(SCRIPT_HOOKS.AFTER_UPDATE, DATA_ACTIONS.CREATE, objectName, record, payload, ctx, warnings, String(record[pk] ?? ''));
+            auditWrite(this.audit, ctx, DATA_ACTIONS.CREATE, objectName, externalId, record);
+            this.events?.publishRecordChange('created', objectName, externalId);
+            await this.runAfterHook(SCRIPT_HOOKS.AFTER_UPDATE, DATA_ACTIONS.CREATE, objectName, record, payload, ctx, warnings, externalId);
             if (warnings.length > 0)
                 ctx.onWarnings?.(warnings);
             const loaded = await this.runOnLoad(objectName, [record], ctx);
@@ -292,7 +441,10 @@ export class DefaultObjectDataAccess {
         catch (err) {
             if (owned)
                 await client.query('ROLLBACK');
-            auditWrite(this.audit, ctx, DATA_ACTIONS.CREATE, objectName, data[pk] === undefined ? undefined : String(data[pk]), data, err);
+            const failedId = primaryNames(def).every((n) => data[n] !== undefined)
+                ? externalIdOf(def, data)
+                : undefined;
+            auditWrite(this.audit, ctx, DATA_ACTIONS.CREATE, objectName, failedId, data, err);
             throw err;
         }
         finally {
@@ -302,10 +454,10 @@ export class DefaultObjectDataAccess {
     }
     async update(objectName, id, changes, ctx) {
         const def = requireDef(ctx, objectName);
-        const pk = primaryKeyOf(def);
-        if (pk === undefined) {
+        if (primaryNames(def).length === 0) {
             throw new SchemaError('data.recordNotFound', { object: objectName, id }, ctx.locale);
         }
+        const pkValues = pkValuesOf(def, id, ctx);
         let client;
         let owned = false;
         if (ctx.client !== undefined) {
@@ -320,21 +472,31 @@ export class DefaultObjectDataAccess {
             if (owned)
                 await client.query('BEGIN');
             await validateRecord(def, changes, WRITE_MODES.UPDATE, { pool: client, registry: ctx.registry, locale: ctx.locale });
-            const { sql, params } = buildFindSql(def, { filter: { [pk]: id }, limit: 1 }, bctx(ctx, objectName), ctx.rowScope);
+            const { sql, params } = buildFindSql(def, { filter: pkFilter(def, pkValues), limit: 1 }, bctx(ctx, objectName), ctx.rowScope, undefined, [recordKeySelect(def)]);
             const { rows } = await runTableQuery(client, objectName, sql, params, ctx.locale);
-            const existing = rows[0];
-            if (existing === undefined) {
+            const raw = rows[0];
+            if (raw === undefined) {
                 throw new SchemaError('data.recordNotFound', { object: objectName, id }, ctx.locale);
             }
+            const metaKey = String(raw[META_KEY_COL] ?? '');
+            const existing = { ...raw };
+            delete existing[META_KEY_COL];
             // validate → beforeUpdate; hooks see the pre-update record and may rewrite changes
             await this.runBeforeHook(SCRIPT_HOOKS.VALIDATE, objectName, existing, changes, ctx);
             let payload = changes;
             const before = await this.runBeforeHook(SCRIPT_HOOKS.BEFORE_UPDATE, objectName, existing, changes, ctx);
             if (before !== undefined)
                 payload = before;
+            // primary keys are immutable: reject any attempt to change them (drift-free record_key)
+            for (const name of primaryNames(def)) {
+                if (payload[name] !== undefined) {
+                    throw new SchemaError('object.primary.mutable', { object: objectName, field: name }, ctx.locale);
+                }
+            }
             const now = new Date();
             const record = { ...existing, ...payload };
-            await computeFormulas(def, record, client, ctx.registry, now);
+            record[RECORD_META_ID_FIELD] = metaKey;
+            await computeFormulas(def, record, client, ctx.registry, now, metaKey, formulaAuth(ctx));
             const settable = new Set();
             for (const key of Object.keys(payload)) {
                 if (isDetailsChild(ctx.registry, def.name) && PARENT_COLUMNS.has(key)) {
@@ -342,21 +504,25 @@ export class DefaultObjectDataAccess {
                     continue;
                 }
                 const field = def.fields.find((f) => f.name === key);
-                if (field !== undefined && field.type !== FIELD_TYPES.DETAILS)
+                if (field !== undefined && field.type !== FIELD_TYPES.DETAILS && field.type !== FIELD_TYPES.MULTI_RELATION) {
                     settable.add(key);
+                }
             }
             for (const field of def.fields) {
                 if (field.formula !== undefined)
                     settable.add(field.name);
             }
-            settable.delete(pk);
+            for (const name of primaryNames(def))
+                settable.delete(name);
             if (settable.size > 0) {
                 const cols = [...settable];
                 const setSql = cols.map((c, i) => `${q(c)} = $${i + 1}`).join(', ');
-                const scope = ctx.rowScope !== undefined ? scopeSuffix(ctx.rowScope, cols.length + 1) : undefined;
+                const scope = ctx.rowScope !== undefined ? scopeSuffix(ctx.rowScope, cols.length + pkValues.length) : undefined;
                 const values = cols.map((c) => dbJsonValue(def.fields.find((f) => f.name === c), record[c] ?? null));
-                await runTableQuery(client, objectName, `UPDATE ${q(def.name)} SET ${setSql} WHERE ${q(pk)} = $${cols.length + 1}${scope !== undefined ? ` AND (${scope.sql})` : ''}`, [...values, id, ...(scope?.params ?? [])], ctx.locale);
+                await runTableQuery(client, objectName, `UPDATE ${q(def.name)} SET ${setSql} WHERE ${pkWhereSql(def, cols.length + 1)}${scope !== undefined ? ` AND (${scope.sql})` : ''}`, [...values, ...pkValues, ...(scope?.params ?? [])], ctx.locale);
             }
+            await this.writeRecordMeta(client, def, metaKey, ctx, now, false);
+            await replaceLinks(client, def, pkValues, payload, ctx.registry, ctx.locale);
             if (owned)
                 await client.query('COMMIT');
             auditWrite(this.audit, ctx, DATA_ACTIONS.UPDATE, objectName, id, payload, undefined, this.replay ? existing : undefined, this.replay ? record : undefined);
@@ -378,12 +544,195 @@ export class DefaultObjectDataAccess {
                 client.release();
         }
     }
+    /**
+     * Fire a workflow action against the three-layer runtime (instance/step/
+     * workitem). Runs in one transaction: the instance row is locked, the current
+     * step's workitems are quorum-evaluated, the new step/workitems are opened and
+     * the side-table status mirror is updated. The customer row is never touched.
+     */
+    async transition(objectName, id, action, ctx, payload) {
+        const def = requireDef(ctx, objectName);
+        if (def.workflow === undefined) {
+            throw new SchemaError('workflow.transition.unknown', { object: objectName, action }, ctx.locale);
+        }
+        if (primaryNames(def).length === 0) {
+            throw new SchemaError('data.recordNotFound', { object: objectName, id }, ctx.locale);
+        }
+        const pkValues = pkValuesOf(def, id, ctx);
+        let client;
+        let owned = false;
+        if (ctx.client !== undefined) {
+            client = ctx.client;
+        }
+        else {
+            owned = true;
+            client = await ctx.pool.connect();
+        }
+        try {
+            if (owned)
+                await client.query('BEGIN');
+            // the customer record must exist (transitions never create records)
+            const { sql, params } = buildFindSql(def, { filter: pkFilter(def, pkValues), limit: 1 }, bctx(ctx, objectName), undefined, undefined, [recordKeySelect(def)]);
+            const found = await runTableQuery(client, objectName, sql, params, ctx.locale);
+            if (found.rows[0] === undefined) {
+                throw new SchemaError('data.recordNotFound', { object: objectName, id }, ctx.locale);
+            }
+            // guardrail policy + approval gate (shared policy set with the open contract):
+            // a policy self-filters on `workflow.transition.<object>.<action>`; a node may
+            // also declare `requiresApproval`. deny → error; requireApproval → pending.
+            const currentNode = await getWorkflowStatus(client, def, id, ctx.subject);
+            const nodeDef = currentNode.node === undefined ? undefined : def.workflow.nodes.find((n) => n.id === currentNode.node);
+            const requireApproval = nodeDef?.requiresApproval === true;
+            if (this.policies.length > 0 || requireApproval) {
+                const actorId = ctx.subject?.id ?? 'system';
+                const guardrailCtx = {
+                    actor: { key: actorId, label: actorId, onBehalfOf: actorId },
+                    subject: ctx.subject ?? { id: 'system', roles: [] },
+                    action: `workflow.transition.${def.name}.${action}`,
+                    args: { object: def.name, id, action },
+                    dataAccess: toolDataAccessOver(this, {
+                        pool: ctx.pool,
+                        registry: ctx.registry,
+                        ...(ctx.locale === undefined ? {} : { locale: ctx.locale }),
+                        ...(ctx.client === undefined ? {} : { client: ctx.client }),
+                        ...(ctx.subject === undefined ? {} : { subject: ctx.subject }),
+                    }),
+                };
+                const gate = await evaluateTransition(this.policies, this.approvals, guardrailCtx, requireApproval);
+                if (gate.kind === 'deny') {
+                    throw new SchemaError(gate.code, { object: objectName, action, reason: gate.reason ?? '' }, ctx.locale);
+                }
+                if (gate.kind === 'pending') {
+                    throw new SchemaError('workflow.transition.pending', { object: objectName, action, approvalKey: gate.approvalKey }, ctx.locale);
+                }
+            }
+            const outcome = await runWorkflowTransition(client, def, id, action, ctx.subject, payload, ctx.locale);
+            if (owned)
+                await client.query('COMMIT');
+            auditWrite(this.audit, ctx, DATA_ACTIONS.TRANSITION, objectName, id, {
+                action,
+                node: outcome.toNodeId ?? null,
+                from: outcome.fromNodeId ?? null,
+                ...(def.workflowHash === undefined ? {} : { workflowHash: def.workflowHash }),
+            });
+            this.events?.publishRecordChange('updated', objectName, id);
+            this.events?.publishRecordTransitioned(objectName, id, outcome.fromNodeId ?? '', outcome.toNodeId ?? '', action, def.workflow.version, def.workflowHash);
+            if (outcome.nodeId !== undefined) {
+                await this.workflowTimers?.sync(objectName, id, outcome.nodeId).catch(() => { });
+            }
+            else {
+                await this.workflowTimers?.cancel(objectName, id).catch(() => { });
+            }
+            const updated = await this.findOne(objectName, id, ctx);
+            const transitionInfo = { from: outcome.fromNodeId ?? '', to: outcome.toNodeId ?? '' };
+            const warnings = [];
+            if (updated !== null) {
+                await this.runAfterHook(SCRIPT_HOOKS.ON_EXIT, DATA_ACTIONS.TRANSITION, objectName, updated, {}, ctx, warnings, id, { transition: transitionInfo, state: outcome.fromNodeId });
+                await this.runAfterHook(SCRIPT_HOOKS.ON_ENTER, DATA_ACTIONS.TRANSITION, objectName, updated, {}, ctx, warnings, id, { transition: transitionInfo, state: outcome.toNodeId });
+                await this.runAfterHook(SCRIPT_HOOKS.AFTER_TRANSITION, DATA_ACTIONS.TRANSITION, objectName, updated, {}, ctx, warnings, id, { transition: transitionInfo, state: outcome.toNodeId });
+            }
+            if (warnings.length > 0)
+                ctx.onWarnings?.(warnings);
+            return updated;
+        }
+        catch (err) {
+            if (owned)
+                await client.query('ROLLBACK');
+            auditWrite(this.audit, ctx, DATA_ACTIONS.TRANSITION, objectName, id, { action }, err);
+            throw err;
+        }
+        finally {
+            if (owned)
+                client.release();
+        }
+    }
+    /**
+     * Read a record's workflow status (state/node/actions/own workitems).
+     */
+    async workflowStatus(objectName, id, ctx) {
+        const def = requireDef(ctx, objectName);
+        if (def.workflow === undefined) {
+            throw new SchemaError('workflow.transition.unknown', { object: objectName, action: 'status' }, ctx.locale);
+        }
+        return getWorkflowStatus(ctx.client ?? ctx.pool, def, id, ctx.subject);
+    }
+    /** Acquire/renew the caller's presence lock on the current step (TTL lease). */
+    async acquireWorkflowLock(objectName, id, ctx) {
+        const def = requireDef(ctx, objectName);
+        return acquireWorkflowLock(ctx.pool, def, id, ctx.subject, ctx.locale);
+    }
+    /** Release the caller's presence lock. */
+    async releaseWorkflowLock(objectName, id, ctx) {
+        const def = requireDef(ctx, objectName);
+        await releaseWorkflowLock(ctx.pool, def, id, ctx.subject);
+    }
+    /** Read a record's workflow history (steps + workitems). */
+    async workflowHistory(objectName, id, ctx) {
+        const def = requireDef(ctx, objectName);
+        if (def.workflow === undefined) {
+            throw new SchemaError('workflow.transition.unknown', { object: objectName, action: 'history' }, ctx.locale);
+        }
+        return getWorkflowHistory(ctx.client ?? ctx.pool, def, id);
+    }
+    /** The subject's pending workitems across all objects. */
+    async workflowTodos(ctx) {
+        return getWorkflowTodos(ctx.pool, ctx.subject);
+    }
+    /** Admin override: jump the record to a node or terminate the instance. */
+    async overrideWorkflow(objectName, id, patch, ctx) {
+        const def = requireDef(ctx, objectName);
+        if (def.workflow === undefined) {
+            throw new SchemaError('workflow.transition.unknown', { object: objectName, action: 'override' }, ctx.locale);
+        }
+        let client;
+        let owned = false;
+        if (ctx.client !== undefined) {
+            client = ctx.client;
+        }
+        else {
+            owned = true;
+            client = await ctx.pool.connect();
+        }
+        try {
+            if (owned)
+                await client.query('BEGIN');
+            const result = await overrideWorkflow(client, def, id, patch, ctx.subject, ctx.locale);
+            if (owned)
+                await client.query('COMMIT');
+            if (result.nodeId !== undefined) {
+                await this.workflowTimers?.sync(objectName, id, result.nodeId).catch(() => { });
+            }
+            else {
+                await this.workflowTimers?.cancel(objectName, id).catch(() => { });
+            }
+            return result;
+        }
+        catch (err) {
+            if (owned)
+                await client.query('ROLLBACK');
+            throw err;
+        }
+        finally {
+            if (owned)
+                client.release();
+        }
+    }
+    /**
+     * Upsert a record's sparse metadata side-table row (status/owner/timestamps)
+     * inside the caller's transaction. `created` also stamps the creation facts.
+     */
+    async writeRecordMeta(client, def, key, ctx, now, created) {
+        const actor = ctx.subject?.id ?? 'system';
+        await upsertRecordMeta(client, def.name, key, created
+            ? { createdBy: actor, modifiedBy: actor, createdTime: now, modifiedTime: now }
+            : { modifiedBy: actor, modifiedTime: now });
+    }
     async delete(objectName, id, ctx) {
         const def = requireDef(ctx, objectName);
-        const pk = primaryKeyOf(def);
-        if (pk === undefined) {
+        if (primaryNames(def).length === 0) {
             throw new SchemaError('data.recordNotFound', { object: objectName, id }, ctx.locale);
         }
+        const pkValues = pkValuesOf(def, id, ctx);
         let client;
         let owned = false;
         if (ctx.client !== undefined) {
@@ -397,22 +746,27 @@ export class DefaultObjectDataAccess {
         try {
             if (owned)
                 await client.query('BEGIN');
-            const { sql, params } = buildFindSql(def, { filter: { [pk]: id }, limit: 1 }, bctx(ctx, objectName), ctx.rowScope);
+            const { sql, params } = buildFindSql(def, { filter: pkFilter(def, pkValues), limit: 1 }, bctx(ctx, objectName), ctx.rowScope, undefined, [recordKeySelect(def)]);
             const { rows } = await runTableQuery(client, objectName, sql, params, ctx.locale);
-            const existing = rows[0];
-            if (existing === undefined) {
+            const raw = rows[0];
+            if (raw === undefined) {
                 throw new SchemaError('data.recordNotFound', { object: objectName, id }, ctx.locale);
             }
+            const metaKey = String(raw[META_KEY_COL] ?? '');
+            const existing = { ...raw };
+            delete existing[META_KEY_COL];
             await this.runBeforeHook(SCRIPT_HOOKS.BEFORE_DELETE, objectName, existing, {}, ctx);
             await deleteDetailsChildren(client, def, id, ctx.registry);
-            const scope = ctx.rowScope !== undefined ? scopeSuffix(ctx.rowScope, 1) : undefined;
-            const res = await runTableQuery(client, objectName, `DELETE FROM ${q(def.name)} WHERE ${q(pk)} = $1${scope !== undefined ? ` AND (${scope.sql})` : ''}`, [id, ...(scope?.params ?? [])], ctx.locale);
+            const scope = ctx.rowScope !== undefined ? scopeSuffix(ctx.rowScope, pkValues.length) : undefined;
+            const res = await runTableQuery(client, objectName, `DELETE FROM ${q(def.name)} WHERE ${pkWhereSql(def, 1)}${scope !== undefined ? ` AND (${scope.sql})` : ''}`, [...pkValues, ...(scope?.params ?? [])], ctx.locale);
             if (res.rowCount === 0)
                 throw new SchemaError('data.recordNotFound', { object: objectName, id }, ctx.locale);
+            await deleteRecordMeta(client, def.name, metaKey);
             if (owned)
                 await client.query('COMMIT');
             auditWrite(this.audit, ctx, DATA_ACTIONS.DELETE, objectName, id, undefined, undefined, this.replay ? existing : undefined);
             this.events?.publishRecordChange('deleted', objectName, id);
+            await this.workflowTimers?.cancel(objectName, id).catch(() => { });
             await this.runAfterHook(SCRIPT_HOOKS.AFTER_DELETE, DATA_ACTIONS.DELETE, objectName, existing, {}, ctx, warnings, id);
             if (warnings.length > 0)
                 ctx.onWarnings?.(warnings);