@adula/kit 1.0.0 → 1.2.0

package/build/src/workflows/define_workflow.d.ts

@@ -12,11 +12,23 @@ export type StepContext = {
     };
     db: Knex;
 };
-export type Recipients = 'creator' | 'submitter' | {
+export type Recipients = 'creator' | 'submitter'
+/**
+ * The members of a role, addressed by its stable key (roles.key). A role without a
+ * key is still found by its display name, which administrators can rename.
+ */
+ | {
     role: string;
 } | {
     users: number[];
 } | ((context: StepContext) => number[] | Promise<number[]>);
+/** One decision an approver can take at a decision step (#42). */
+export type DecisionOutcome = {
+    label: string;
+    next: string;
+    /** Whether the decision needs a comment; defaults to optional. */
+    comment?: 'optional' | 'required';
+};
 export type WorkflowStep = {
     type: 'condition';
     label?: string;
@@ -43,6 +55,17 @@ export type WorkflowStep = {
     dueInDays?: number;
     approve: string;
     reject: string;
+} | {
+    /**
+     * An approval with named outcomes, for example approve, reject and return. Each
+     * outcome names its next step (a later or an earlier one) and may require a comment.
+     * The submitted document stays locked: a decision never changes its fields.
+     */
+    type: 'decision';
+    label: string;
+    assignees: Recipients;
+    dueInDays?: number;
+    outcomes: Record<string, DecisionOutcome>;
 } | {
     type: 'delay';
     label?: string;
@@ -62,11 +85,13 @@ export type WorkflowStep = {
     cancelDocument?: boolean;
 };
 export type WorkflowInput = {
+    /** Lower-case letters, digits and underscores, starting with a letter (for example release_approval). */
     name: string;
     version: number;
     resource: string;
     label: string;
     start: string;
+    /** Step names follow the workflow name rule (for example notify_approved). */
     steps: Record<string, WorkflowStep>;
     /** Failed step attempts before the run stops as failed (default 5). */
     maxAttempts?: number;
@@ -83,7 +108,11 @@ export type WorkflowEvent = {
     type: 'APPROVE';
 } | {
     type: 'REJECT';
+} | {
+    type: 'DECIDE';
+    outcome: string;
 };
+export declare const WORKFLOW_NAME_RULE = "use lower-case letters, digits and underscores, starting with a letter";
 /**
  * Declares a versioned workflow. Steps compile to an XState machine; the engine
  * performs each step's effect and asks the machine for the next step. Runs keep

package/build/src/workflows/define_workflow.js

@@ -1,11 +1,30 @@
 import { createMachine, getNextSnapshot } from 'xstate';
 const IDENTIFIER = /^[a-z][a-z0-9_]*$/;
+export const WORKFLOW_NAME_RULE = 'use lower-case letters, digits and underscores, starting with a letter';
+/** Names the rule and a valid spelling, since dotted event-style names are a natural first try. */
+function assertIdentifier(kind, value) {
+    if (IDENTIFIER.test(value))
+        return;
+    const suggestion = value
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^[^a-z]+|_+$/g, '');
+    const example = IDENTIFIER.test(suggestion)
+        ? suggestion
+        : kind === 'workflow'
+            ? 'release_approval'
+            : 'notify_approved';
+    throw new Error(`Invalid ${kind} name "${value}": ${WORKFLOW_NAME_RULE} (for example ${example}).`);
+}
 function targets(step) {
     switch (step.type) {
         case 'condition':
             return [step.then, step.else];
         case 'approval':
             return [step.approve, step.reject];
+        case 'decision':
+            return Object.values(step.outcomes).map((outcome) => outcome.next);
         case 'end':
             return [];
         default:
@@ -19,22 +38,31 @@ function targets(step) {
  * running workflow (migrate explicitly with WorkflowEngine.migrateRuns).
  */
 export function defineWorkflow(input) {
-    if (!IDENTIFIER.test(input.name))
-        throw new Error(`Invalid workflow name: ${input.name}`);
+    assertIdentifier('workflow', input.name);
     if (!Number.isInteger(input.version) || input.version < 1)
         throw new Error('Workflow version must be a positive integer');
     if (!(input.start in input.steps))
         throw new Error(`Unknown start step: ${input.start}`);
     const keys = Object.keys(input.steps);
     for (const key of keys) {
-        if (!IDENTIFIER.test(key))
-            throw new Error(`Invalid step name: ${key}`);
+        assertIdentifier('step', key);
         for (const target of targets(input.steps[key]))
             if (!(target in input.steps))
                 throw new Error(`Step ${key} points to unknown step ${target}`);
         const step = input.steps[key];
         if (step.type === 'delay' && (!Number.isInteger(step.ms) || step.ms < 0))
             throw new Error(`Step ${key} needs a non-negative integer delay`);
+        if (step.type === 'decision') {
+            const outcomes = Object.entries(step.outcomes ?? {});
+            if (outcomes.length < 2)
+                throw new Error(`Decision step ${key} needs at least two outcomes`);
+            for (const [name, outcome] of outcomes) {
+                if (!IDENTIFIER.test(name) || name.length > 20)
+                    throw new Error(`Invalid outcome name "${name}" in step ${key}: ${WORKFLOW_NAME_RULE}, at most 20 characters`);
+                if (!outcome.label)
+                    throw new Error(`Outcome ${name} of step ${key} needs a label`);
+            }
+        }
     }
     if (!keys.some((key) => input.steps[key].type === 'end'))
         throw new Error('A workflow needs at least one end step');
@@ -61,6 +89,18 @@ export function defineWorkflow(input) {
                     ];
                 case 'approval':
                     return [key, { on: { APPROVE: step.approve, REJECT: step.reject } }];
+                case 'decision':
+                    return [
+                        key,
+                        {
+                            on: {
+                                DECIDE: Object.entries(step.outcomes).map(([name, outcome]) => ({
+                                    target: outcome.next,
+                                    guard: ({ event }) => event.type === 'DECIDE' && event.outcome === name,
+                                })),
+                            },
+                        },
+                    ];
                 case 'end':
                     return [key, { type: 'final' }];
                 default:

package/build/src/workflows/engine.d.ts

@@ -13,6 +13,8 @@ export type WorkflowRun = {
     resource: string;
     resourceLabel: string;
     recordId: number;
+    /** The record title for the approver (#32); null in admin views or when not readable. */
+    recordTitle: string | null;
     definition: string;
     label: string;
     version: number;
@@ -38,8 +40,18 @@ export type WorkflowRun = {
     myApproval: {
         assignmentId: number;
         title: string;
+        /** Set at a decision step: its outcomes in declaration order (#42). */
+        decision?: WorkflowDecisionForm;
     } | null;
 };
+/** What an approver needs to take a decision at a decision step. */
+export type WorkflowDecisionForm = {
+    outcomes: {
+        key: string;
+        label: string;
+        comment: 'optional' | 'required';
+    }[];
+};
 export type WorkflowOptions = {
     post?: HttpPoster;
     /** Test hook simulating a crash after a step's effect and before its commit. */
@@ -87,7 +99,7 @@ export declare class WorkflowEngine {
      * Records an approver's decision. Only an open approval assigned to the actor
      * counts, and the run is locked so concurrent decisions cannot both apply.
      */
-    decide(runId: string, actor: Actor, decision: 'approve' | 'reject', comment?: unknown): Promise<WorkflowRun>;
+    decide(runId: string, actor: Actor, decision: string, comment?: unknown): Promise<WorkflowRun>;
     /** Administrators put a failed run back to its failed step. */
     retry(runId: string, actorId: number): Promise<void>;
     /**
@@ -98,9 +110,17 @@ export declare class WorkflowEngine {
     runsFor(name: string, id: number, actor: Actor): Promise<WorkflowRun[]>;
     run(runId: string, actor: Actor): Promise<WorkflowRun>;
     /** Runs waiting for the actor's decision, newest first, on records they can still read. */
-    inbox(actor: Actor): Promise<WorkflowRun[]>;
+    /**
+     * Runs waiting for this user's decision, newest first (at most 100). `runIds` narrows the
+     * inbox to those runs, for pages that list their own rows (My tasks).
+     */
+    inbox(actor: Actor, options?: {
+        runIds?: readonly string[];
+    }): Promise<WorkflowRun[]>;
     failed(limit?: number): Promise<WorkflowRun[]>;
     private present;
+    /** The outcomes an approver can choose at a decision step. */
+    private decisionForm;
     private fail;
     private cancelRuns;
     private context;
@@ -108,6 +128,8 @@ export declare class WorkflowEngine {
     private updateRecord;
     private cancelDocument;
     private recipients;
+    /** A role reference is its stable key; for compatibility a display name also matches. */
+    private roleId;
     private canView;
     private log;
     private now;

package/build/src/workflows/engine.js

@@ -7,6 +7,12 @@ import { nextStep, } from './define_workflow.js';
 const MAX_STEPS_PER_TICK = 25;
 const BACKOFF_SECONDS = [30, 120, 600, 1800, 7200];
 class StepFailure extends Error {
+    permanent;
+    /** A permanent failure stops the run now instead of retrying a configuration error. */
+    constructor(message, permanent = false) {
+        super(message);
+        this.permanent = permanent;
+    }
 }
 /**
  * Durable workflow engine over workflow_runs. Every step runs inside the run's
@@ -174,7 +180,7 @@ export class WorkflowEngine {
                     return;
             }
             catch (error) {
-                await this.fail(trx, run, error, false);
+                await this.fail(trx, run, error, error instanceof StepFailure && error.permanent);
                 return;
             }
         }
@@ -216,21 +222,27 @@ export class WorkflowEngine {
                         id: run.record_id,
                         workflow: definition.label,
                         step: step.label ?? stepName,
-                    });
+                    }, undefined, { resource: String(run.resource), recordId: Number(run.record_id) });
                 return move({ type: 'DONE' }, { recipients: users.length });
             }
-            case 'approval': {
+            case 'approval':
+            case 'decision': {
                 const open = await trx('assignments')
                     .where({ workflow_run_id: run.id, workflow_step: stepName, status: 'open' })
                     .first('id');
                 if (!open) {
-                    const users = await this.recipients(trx, run, context, step.assignees);
+                    const assignees = step.assignees;
+                    if (typeof assignees === 'object' && 'role' in assignees)
+                        if ((await this.roleId(trx, assignees.role)) === null)
+                            throw new StepFailure(`Approval step ${stepName} is addressed to role "${assignees.role}", which matches no role key or name. Give the role that key (or update the workflow), then retry the run.`, true);
+                    const users = await this.recipients(trx, run, context, assignees);
                     const eligible = [];
                     for (const userId of users)
                         if (await this.canView(run.resource, run.record_id, userId))
                             eligible.push(userId);
+                    // Waiting on nobody would hide the run for hours of retries; fail it where admins look.
                     if (!eligible.length)
-                        throw new StepFailure(`No eligible approver for ${stepName}`);
+                        throw new StepFailure(`No eligible approver for ${stepName}: ${users.length ? `${users.length} recipients cannot view the record` : 'the recipients resolve to no active user'}. Fix the recipients, then retry the run.`, true);
                     const due = step.dueInDays
                         ? new Date(this.now().getTime() + step.dueInDays * 86400000).toISOString().slice(0, 10)
                         : null;
@@ -317,7 +329,7 @@ export class WorkflowEngine {
      * counts, and the run is locked so concurrent decisions cannot both apply.
      */
     async decide(runId, actor, decision, comment) {
-        if (!['approve', 'reject'].includes(decision))
+        if (typeof decision !== 'string' || !decision)
             throw new KitError(422, 'E_WORKFLOW_DECISION', 'القرار غير صالح');
         const note = typeof comment === 'string' ? comment.trim().slice(0, 1000) : '';
         await this.db.transaction(async (trx) => {
@@ -337,9 +349,25 @@ export class WorkflowEngine {
             if (run.status !== 'waiting' || !assignment)
                 throw new KitError(409, 'E_WORKFLOW_STATE', 'لا توجد موافقة مطلوبة منك في هذه الخطوة');
             const definition = this.definition(run.definition, run.definition_version);
-            const target = nextStep(definition, run.current_step, {
-                type: decision === 'approve' ? 'APPROVE' : 'REJECT',
-            });
+            const step = definition.steps[run.current_step];
+            let event;
+            let logged;
+            if (step?.type === 'decision') {
+                const outcome = Object.hasOwn(step.outcomes, decision) ? step.outcomes[decision] : undefined;
+                if (!outcome)
+                    throw new KitError(422, 'E_WORKFLOW_DECISION', 'القرار غير صالح');
+                if (outcome.comment === 'required' && !note)
+                    throw new KitError(422, 'E_WORKFLOW_COMMENT', 'اكتب ملاحظة القرار');
+                event = { type: 'DECIDE', outcome: decision };
+                logged = 'decided';
+            }
+            else {
+                if (decision !== 'approve' && decision !== 'reject')
+                    throw new KitError(422, 'E_WORKFLOW_DECISION', 'القرار غير صالح');
+                event = { type: decision === 'approve' ? 'APPROVE' : 'REJECT' };
+                logged = decision === 'approve' ? 'approved' : 'rejected';
+            }
+            const target = nextStep(definition, run.current_step, event);
             await trx('assignments').where('id', assignment.id).update({
                 status: 'done',
                 outcome: decision,
@@ -361,7 +389,8 @@ export class WorkflowEngine {
                 last_error: null,
                 updated_at: trx.fn.now(),
             });
-            await this.log(trx, run.id, run.current_step, decision === 'approve' ? 'approved' : 'rejected', actor.id, {
+            await this.log(trx, run.id, run.current_step, logged, actor.id, {
+                ...(logged === 'decided' ? { outcome: decision } : {}),
                 ...(note ? { comment: note } : {}),
                 next: target,
             });
@@ -425,14 +454,20 @@ export class WorkflowEngine {
         return this.present(row, actor);
     }
     /** Runs waiting for the actor's decision, newest first, on records they can still read. */
-    async inbox(actor) {
-        const rows = await this.db('workflow_runs as r')
+    /**
+     * Runs waiting for this user's decision, newest first (at most 100). `runIds` narrows the
+     * inbox to those runs, for pages that list their own rows (My tasks).
+     */
+    async inbox(actor, options = {}) {
+        if (options.runIds && !options.runIds.length)
+            return [];
+        const query = this.db('workflow_runs as r')
             .join('assignments as a', 'a.workflow_run_id', 'r.id')
             .where({ 'a.assignee_id': actor.id, 'a.status': 'open', 'r.status': 'waiting' })
-            .whereRaw('a.workflow_step = r.current_step')
-            .orderBy('a.id', 'desc')
-            .limit(100)
-            .select('r.*');
+            .whereRaw('a.workflow_step = r.current_step');
+        if (options.runIds)
+            query.whereIn('r.id', [...new Set(options.runIds)].slice(0, 100));
+        const rows = await query.orderBy('a.id', 'desc').limit(100).select('r.*');
         const runs = [];
         for (const row of rows)
             if (await this.resources.permits(row.resource, Number(row.record_id), actor))
@@ -469,6 +504,9 @@ export class WorkflowEngine {
                 .first('id', 'title')
             : undefined;
         const step = row.current_step ? definition?.steps[row.current_step] : undefined;
+        const titles = actor
+            ? await this.resources.titles(row.resource, [Number(row.record_id)], actor)
+            : undefined;
         let resourceLabel = String(row.resource);
         try {
             resourceLabel = this.resources.label(row.resource);
@@ -479,6 +517,7 @@ export class WorkflowEngine {
             resource: String(row.resource),
             resourceLabel,
             recordId: Number(row.record_id),
+            recordTitle: titles?.get(Number(row.record_id)) ?? null,
             definition: String(row.definition),
             label: definition?.label ?? String(row.definition),
             version: Number(row.definition_version),
@@ -498,7 +537,23 @@ export class WorkflowEngine {
                 detail: (event.detail ?? {}),
                 at: new Date(event.created_at).toISOString(),
             })),
-            myApproval: mine ? { assignmentId: Number(mine.id), title: String(mine.title) } : null,
+            myApproval: mine
+                ? {
+                    assignmentId: Number(mine.id),
+                    title: String(mine.title),
+                    ...(step?.type === 'decision' ? { decision: this.decisionForm(step) } : {}),
+                }
+                : null,
+        };
+    }
+    /** The outcomes an approver can choose at a decision step. */
+    decisionForm(step) {
+        return {
+            outcomes: Object.entries(step.outcomes).map(([key, outcome]) => ({
+                key,
+                label: outcome.label,
+                comment: outcome.comment ?? 'optional',
+            })),
         };
     }
     async fail(trx, run, error, permanent) {
@@ -532,7 +587,7 @@ export class WorkflowEngine {
                 resource: this.resources.label(run.resource),
                 id: run.record_id,
                 error: message,
-            });
+            }, undefined, { resource: String(run.resource), recordId: Number(run.record_id) });
     }
     async cancelRuns(trx, resource, id, actorId) {
         const runs = await trx('workflow_runs')
@@ -635,16 +690,26 @@ export class WorkflowEngine {
         else if ('users' in to)
             ids = to.users;
         else {
-            const members = await trx('user_roles as ur')
-                .join('roles as r', 'r.id', 'ur.role_id')
-                .join('users as u', 'u.id', 'ur.user_id')
-                .where('r.name', to.role)
-                .whereNull('u.disabled_at')
-                .distinct('ur.user_id');
+            const roleId = await this.roleId(trx, to.role);
+            const members = roleId === null
+                ? []
+                : await trx('user_roles as ur')
+                    .join('users as u', 'u.id', 'ur.user_id')
+                    .where('ur.role_id', roleId)
+                    .whereNull('u.disabled_at')
+                    .distinct('ur.user_id');
             ids = members.map((row) => Number(row.user_id));
         }
         return [...new Set(ids.filter((id) => Number.isSafeInteger(id) && id > 0))];
     }
+    /** A role reference is its stable key; for compatibility a display name also matches. */
+    async roleId(db, reference) {
+        const byKey = await db('roles').where('key', reference).first('id');
+        if (byKey)
+            return Number(byKey.id);
+        const byName = await db('roles').where('name', reference).first('id');
+        return byName ? Number(byName.id) : null;
+    }
     async canView(resource, id, userId) {
         const user = await this.db('users').where('id', userId).first('disabled_at');
         if (!user || user.disabled_at)

package/build/stubs/resource_contract.txt

@@ -5,7 +5,7 @@ import db from '@adonisjs/lucid/services/db'
 import { kit } from '#services/kit'
 import { randomUUID } from 'node:crypto'
 import { columnName } from '@adula/kit'
-import type { Field, RecordData, Resource, SerializedRecord } from '@adula/kit'
+import type { Action, Field, RecordData, Resource, SerializedRecord } from '@adula/kit'
 
 export type FixtureContext = { userId: number; orgUnitId: number; unique: string }
 export type ContractFixture = {
@@ -16,9 +16,12 @@ export type ContractFixture = {
   stored?: RecordData
   /** All live child rows after creation, ordered by ID, using public field names. */
   inline?: Record<string, RecordData[]>
-  /** A valid update for this same record, including required validator fields. */
-  update: RecordData
-  updated: SerializedRecord
+  /**
+   * A valid update for this same record, including required validator fields. Required
+   * when the resource declares the `update` action.
+   */
+  update?: RecordData
+  updated?: SerializedRecord
   updatedStored?: RecordData
   updatedInline?: Record<string, RecordData[]>
 }
@@ -48,8 +51,13 @@ export function resourceContract(name: string, fixture: ResourceFixture) {
     let resource: Resource
     const base = `/resources/${name}`
     const fresh = () => fixture({ userId: writer.id, orgUnitId, unique: randomUUID() })
-    const input = (values: RecordData) => ({ ...values, ...(resource.scoped ? { orgUnitId } : {}) })
+    const input = (values: RecordData) => ({
+      ...values,
+      ...(resource.scoped && !resource.scope ? { orgUnitId } : {}),
+    })
     const version = (row: SerializedRecord) => (resource.version ? { version: row.version } : {})
+    // Actions the resource does not declare are refused even to a role that manages all.
+    const allows = (action: Action) => resource.actions.includes(action)
 
     group.setup(async () => {
       const knex = db.connection().getWriteClient()
@@ -124,10 +132,27 @@ export function resourceContract(name: string, fixture: ResourceFixture) {
       const response = await client.get(base).header('Accept', 'application/json')
       response.assertStatus(401)
     })
+    test('undeclared actions are refused to a role that manages all resources', async ({
+      client,
+    }) => {
+      for (const [action, method, suffix] of [
+        ['create', 'post', ''],
+        ['update', 'patch', '/999999'],
+        ['delete', 'delete', '/999999'],
+      ] as const) {
+        if (allows(action)) continue
+        const response = await client[method](`${base}${suffix}`)
+          .loginAs(writer)
+          .withCsrfToken()
+          .header('Accept', 'application/json')
+        response.assertStatus(403)
+      }
+    })
     test('existing records enforce scope on reads and writes; central resources stay shared', async ({
       client,
       assert,
     }) => {
+      if (!allows('create')) return
       const values = await fresh()
       const created = await client
         .post(base)
@@ -159,21 +184,21 @@ export function resourceContract(name: string, fixture: ResourceFixture) {
         .get(`${base}/${row.id}/edit`)
         .loginAs(outsider)
         .header('Accept', 'application/json')
-      edit.assertStatus(404)
+      edit.assertStatus(allows('update') ? 404 : 403)
       const changed = await client
         .patch(`${base}/${row.id}`)
         .loginAs(outsider)
         .withCsrfToken()
         .header('Accept', 'application/json')
-        .json({ ...values.update, ...version(row) })
-      changed.assertStatus(404)
+        .json({ ...(values.update ?? values.input), ...version(row) })
+      changed.assertStatus(allows('update') ? 404 : 403)
       const deleted = await client
         .delete(`${base}/${row.id}`)
         .loginAs(outsider)
         .withCsrfToken()
         .header('Accept', 'application/json')
         .json(version(row))
-      deleted.assertStatus(404)
+      deleted.assertStatus(allows('delete') ? 404 : 403)
       const after = await client
         .get(`${base}/${row.id}`)
         .loginAs(writer)
@@ -185,6 +210,7 @@ export function resourceContract(name: string, fixture: ResourceFixture) {
       client,
       assert,
     }) => {
+      if (!allows('create')) return
       const values = await fresh()
       for (const key of resource.form)
         assert.property(values.input, key, `Missing ${name}.${key} fixture`)
@@ -268,64 +294,99 @@ export function resourceContract(name: string, fixture: ResourceFixture) {
         if (field.permissionLevel || resource.hidden?.includes(key))
           assert.notProperty(shown.body().data, key)
       }
-      for (const key of ['createdBy', 'updatedBy', 'deletedAt', 'orgPath', 'searchVector']) {
-        const invalid = await client
+      const stored = async () => db.connection().getWriteClient()(name).where('id', row.id).first()
+      const inserted = await stored()
+      assert.equal(inserted.created_by, writer.id)
+      if (!allows('update')) {
+        const refused = await client
           .patch(`${base}/${row.id}`)
           .loginAs(writer)
           .withCsrfToken()
           .header('Accept', 'application/json')
-          .json({ ...values.update, ...version(row), [key]: writer.id })
-        invalid.assertStatus(422)
-        assert.equal(invalid.body().error.code, 'E_FIELD_NOT_WRITABLE')
+          .json({ ...values.input, ...version(row) })
+        refused.assertStatus(403)
       }
-      const updated = await client
-        .patch(`${base}/${row.id}`)
-        .loginAs(writer)
-        .withCsrfToken()
-        .header('Accept', 'application/json')
-        .json({ ...values.update, ...version(row) })
-      updated.assertStatus(200)
-      for (const [key, value] of Object.entries(values.updated))
-        assert.deepEqual(updated.body().data[key], value, key)
-      await assertStored(values.update, values.updated, values.updatedStored, values.updatedInline)
-      if (resource.version) {
-        assert.equal(updated.body().data.version, Number(row.version) + 1)
-        const stale = await client
-          .patch(`${base}/${row.id}`)
+      const current = allows('update') ? await updateRecord() : row
+      if (!allows('delete')) {
+        const refused = await client
+          .delete(`${base}/${row.id}`)
           .loginAs(writer)
           .withCsrfToken()
           .header('Accept', 'application/json')
-          .json({ ...values.update, ...version(row) })
-        stale.assertStatus(409)
+          .json(version(current))
+        refused.assertStatus(403)
+        const kept = await client
+          .get(`${base}/${row.id}`)
+          .loginAs(writer)
+          .header('Accept', 'application/json')
+        kept.assertStatus(200)
+        assert.deepEqual(kept.body().data, current)
+        return
       }
-      const persisted = await client
-        .get(`${base}/${row.id}`)
-        .loginAs(writer)
-        .header('Accept', 'application/json')
-      persisted.assertStatus(200)
-      assert.deepEqual(persisted.body().data, updated.body().data)
       const removed = await client
         .delete(`${base}/${row.id}`)
         .loginAs(writer)
         .withCsrfToken()
         .header('Accept', 'application/json')
-        .json(version(updated.body().data))
+        .json(version(current))
       removed.assertStatus(200)
-      const stored = await db.connection().getWriteClient()(name).where('id', row.id).first()
-      assert.exists(stored.deleted_at)
-      assert.equal(stored.created_by, writer.id)
+      const deleted = await stored()
+      assert.exists(deleted.deleted_at)
       const missing = await client
         .get(`${base}/${row.id}`)
         .loginAs(writer)
         .header('Accept', 'application/json')
       missing.assertStatus(404)
+
+      async function updateRecord() {
+        assert.exists(values.update, `Missing ${name} update fixture`)
+        assert.exists(values.updated, `Missing ${name} updated fixture`)
+        const update = values.update!
+        for (const key of ['createdBy', 'updatedBy', 'deletedAt', 'orgPath', 'searchVector']) {
+          const invalid = await client
+            .patch(`${base}/${row.id}`)
+            .loginAs(writer)
+            .withCsrfToken()
+            .header('Accept', 'application/json')
+            .json({ ...update, ...version(row), [key]: writer.id })
+          invalid.assertStatus(422)
+          assert.equal(invalid.body().error.code, 'E_FIELD_NOT_WRITABLE')
+        }
+        const updated = await client
+          .patch(`${base}/${row.id}`)
+          .loginAs(writer)
+          .withCsrfToken()
+          .header('Accept', 'application/json')
+          .json({ ...update, ...version(row) })
+        updated.assertStatus(200)
+        for (const [key, value] of Object.entries(values.updated!))
+          assert.deepEqual(updated.body().data[key], value, key)
+        await assertStored(update, values.updated!, values.updatedStored, values.updatedInline)
+        if (resource.version) {
+          assert.equal(updated.body().data.version, Number(row.version) + 1)
+          const stale = await client
+            .patch(`${base}/${row.id}`)
+            .loginAs(writer)
+            .withCsrfToken()
+            .header('Accept', 'application/json')
+            .json({ ...update, ...version(row) })
+          stale.assertStatus(409)
+        }
+        const persisted = await client
+          .get(`${base}/${row.id}`)
+          .loginAs(writer)
+          .header('Accept', 'application/json')
+        persisted.assertStatus(200)
+        assert.deepEqual(persisted.body().data, updated.body().data)
+        return updated.body().data as SerializedRecord
+      }
     })
     test('unique constraints reject duplicates and allow reuse after soft deletion', async ({
       client,
       assert,
     }) => {
       const keys = Object.entries(resource.fields).filter(([, field]) => field.unique)
-      if (!keys.length) return
+      if (!keys.length || !allows('create')) return
       const values = await fresh()
       const created = await client
         .post(base)
@@ -369,6 +430,7 @@ export function resourceContract(name: string, fixture: ResourceFixture) {
         rejected.assertStatus(409)
         assert.equal(rejected.body().error.code, 'E_DUPLICATE')
       }
+      if (!allows('delete')) return
       const removed = await client
         .delete(`${base}/${row.id}`)
         .loginAs(writer)