@terreno/mcp 0.21.0

package/dist/docs/versioned/next/implementationPlans/model-router-actions.md

@@ -0,0 +1,639 @@
+# Implementation Plan: modelRouter Actions
+
+## Goal
+
+Add first-class support for **actions** in `modelRouter` — URLs that perform a named operation rather than CRUD. Actions live either at `/resource/action` (collection scope) or `/resource/:id/action` (instance scope). They inherit modelRouter's permissions system, are wrapped in `asyncHandler` + the standard error envelope automatically, and appear in the generated OpenAPI spec without extra wiring.
+
+Today, callers like `consentApp.ts` hand-roll actions inside the existing `endpoints` callback — wiring auth, error handling, doc loading, and OpenAPI manually. This plan replaces that boilerplate with a declarative API.
+
+## Decisions
+
+| Topic | Decision |
+|---|---|
+| Methods | `GET` and `POST` only. `PUT`, `PATCH`, and `DELETE` actions are intentionally unsupported in v1 to avoid confusion with CRUD and array-field update/delete routes |
+| Schemas | Zod (input + output), used for both runtime validation and OpenAPI |
+| Doc loading | Auto-load on instance actions; 404 if missing; pass via `ctx.doc` |
+| Permissions | Same `PermissionMethod<T>[]` shape as CRUD; **required**; empty array `[]` means "disabled" (returns 405, matching CRUD semantics at `permissions.ts:90–95`); missing field throws at register time |
+| Handler signature | RORO: `async ({req, res, doc, body, query, user}) => result` |
+| Config shape | Top-level `instanceActions` and `collectionActions` records on `ModelRouterOptions` |
+| URL casing | Action name verbatim (no kebab-case transform) |
+| Response | Handler returns raw data; framework auto-wraps in `{data: ...}`. Skipped if `res.headersSent` (streaming escape hatch) |
+| OpenAPI tag | Default to model tag; per-action `tag` override |
+| Collisions | Throw at register time on conflicts with CRUD paths (`/`, `/:id`) or array-field operations (`/:id/:field`) |
+| Hooks | No pre/post hooks on actions in v1 |
+| Bulk helpers | Userland — no built-in `bulkUpdate` |
+
+## Public API
+
+### Types (added to `api/src/actions.ts`, re-exported from `api/src/index.ts`)
+
+```typescript
+import {z, ZodSchema} from 'zod';
+import type {PermissionMethod} from './permissions';
+import type {Request, Response} from 'express';
+
+export interface ActionContext<TDoc, TBody, TQuery> {
+  req: Request;
+  res: Response;
+  user: User | undefined;
+  body: TBody;    // inferred from body schema; undefined if no schema
+  query: TQuery;  // inferred from query schema; undefined if no schema
+  doc: TDoc;      // only present for instance actions
+}
+
+interface BaseActionConfig<TDoc, TBody, TQuery, TResponse> {
+  method: 'GET' | 'POST';
+  permissions: PermissionMethod<TDoc>[];
+  body?: ZodSchema<TBody>;
+  query?: ZodSchema<TQuery>;
+  response?: ZodSchema<TResponse>;
+  summary?: string;
+  description?: string;
+  tag?: string;
+  status?: number;  // default 200
+}
+
+export interface InstanceActionConfig<TDoc, TBody, TQuery, TResponse>
+    extends BaseActionConfig<TDoc, TBody, TQuery, TResponse> {
+  handler: (ctx: ActionContext<TDoc, TBody, TQuery>) =>
+    TResponse | Promise<TResponse>;
+}
+
+export interface CollectionActionConfig<TBody, TQuery, TResponse>
+    extends BaseActionConfig<never, TBody, TQuery, TResponse> {
+  handler: (ctx: Omit<ActionContext<never, TBody, TQuery>, 'doc'>) =>
+    TResponse | Promise<TResponse>;
+}
+```
+
+### `ModelRouterOptions<T>` additions (in `api/src/api.ts`)
+
+```typescript
+export interface ModelRouterOptions<T> {
+  // ... existing fields ...
+  instanceActions?: Record<string, InstanceActionConfig<T, unknown, unknown, unknown>>;
+  collectionActions?: Record<string, CollectionActionConfig<unknown, unknown, unknown>>;
+}
+```
+
+### Type-preserving action factories
+
+The `Record<string, ...<unknown, unknown, unknown>>` boundary above erases per-action generics. To let call-sites keep full inference of `body`/`query`/`response` types inside handlers, ship two const-friendly factory helpers:
+
+```typescript
+// Returns the config as-is, but with per-action generics preserved by the `const` capture.
+export function defineInstanceAction<TDoc, TBody = never, TQuery = never, TResponse = unknown>(
+  config: InstanceActionConfig<TDoc, TBody, TQuery, TResponse>
+): InstanceActionConfig<TDoc, TBody, TQuery, TResponse> {
+  return config;
+}
+
+export function defineCollectionAction<TBody = never, TQuery = never, TResponse = unknown>(
+  config: CollectionActionConfig<TBody, TQuery, TResponse>
+): CollectionActionConfig<TBody, TQuery, TResponse> {
+  return config;
+}
+```
+
+Call-site:
+
+```typescript
+import {defineInstanceAction, defineCollectionAction} from '@terreno/api';
+
+instanceActions: {
+  publish: defineInstanceAction<ScheduleDoc>({
+    method: 'POST',
+    permissions: [Permissions.IsOwner],
+    body: z.object({notifyUsers: z.boolean()}),
+    handler: async ({doc, body}) => {
+      //                ^ ScheduleDoc, ^ {notifyUsers: boolean} — fully inferred
+    },
+  }),
+}
+```
+
+The factories are zero-runtime-cost (identity functions). They're optional — bare object literals still work, just with `unknown` widening on the per-action generics.
+
+### Call-site example
+
+```typescript
+import {z} from 'zod';
+import {modelRouter, Permissions} from '@terreno/api';
+
+export const scheduleRouter = modelRouter('/schedules', Schedule, {
+  permissions: { /* CRUD perms */ },
+
+  instanceActions: {
+    status: {
+      method: 'GET',
+      permissions: [Permissions.IsOwner],
+      response: z.object({state: z.enum(['draft', 'published'])}),
+      summary: 'Get schedule status',
+      handler: async ({doc}) => {
+        return {state: doc.publishedAt ? 'published' : 'draft'};
+      },
+    },
+
+    publish: {
+      method: 'POST',
+      permissions: [Permissions.IsOwner],
+      body: z.object({notifyUsers: z.boolean()}),
+      response: z.object({publishedAt: z.string().datetime()}),
+      summary: 'Publish a schedule',
+      handler: async ({doc, body}) => {
+        doc.publishedAt = new Date();
+        if (body.notifyUsers) await notifyUsers(doc);
+        await doc.save();
+        return {publishedAt: doc.publishedAt.toISOString()};
+      },
+    },
+  },
+
+  collectionActions: {
+    bulkArchive: {
+      method: 'POST',
+      permissions: [Permissions.IsAdmin],
+      body: z.object({ids: z.array(z.string())}),
+      response: z.object({archivedCount: z.number()}),
+      handler: async ({body}) => {
+        const result = await Schedule.updateMany(
+          {_id: {$in: body.ids}},
+          {$set: {archived: true}}
+        );
+        return {archivedCount: result.modifiedCount};
+      },
+    },
+  },
+});
+```
+
+### Wire response
+
+```
+GET /schedules/507f.../status
+→ 200 OK
+{"data": {"state": "published"}}
+
+POST /schedules/507f.../publish
+→ 200 OK
+{"data": {"publishedAt": "2026-05-15T18:32:11.000Z"}}
+```
+
+## Internal Mechanics
+
+### Action name validation
+
+Before route registration, each action name is validated against `/^[A-Za-z][A-Za-z0-9_-]+$/`. Empty names and names containing path-special characters (`*`, `:`, `/`, `(`, `)`) throw at register time with a clear message. This guards against `path-to-regexp` v6 surprises in Express 5.
+
+### Permission method mapping
+
+When invoking permission functions, the action passes a synthetic CRUD `method` so existing permissions like `IsAuthenticatedOrReadOnly` work:
+
+| Scope | HTTP | `method` passed to permission |
+|---|---|---|
+| instance | GET | `'read'` |
+| instance | POST | `'update'` |
+| collection | GET | `'list'` |
+| collection | POST | `'create'` |
+
+### Action middleware chain (per registered action)
+
+```
+asyncHandler(
+  authenticateMiddleware(options.allowAnonymous)   // honors parent allowAnonymous
+  → runActionPermissions(action, req, undefined)   // pre-doc cheap check (matches CRUD)
+  → (instance only) loadDocOr404(model, id)        // attaches req.obj
+  → (instance only) runActionPermissions(action, req, req.obj)  // post-doc with-doc check
+  → validateZod(body, query) if provided           // throws APIError 400 on failure
+  → action.handler(ctx)                            // user code; receives parsed body/query in ctx
+  → autoWrapResponse(returned, action.status, res)
+)
+```
+
+`apiErrorMiddleware` already lives at the router level and converts thrown errors.
+
+**Important compatibility points:**
+- `authenticateMiddleware(options.allowAnonymous)` — must pass the parent `allowAnonymous` so anonymous-allowed routers don't 401 before permission checks run (`auth.ts:42`).
+- **Two-stage permission check** mirrors `permissions.ts:135–207`. Pre-doc check throws **405** ("Method not allowed") on denial (matches CRUD `permissions.ts:136`). Post-doc check throws **403** on denial (matches CRUD `permissions.ts:203`). Empty `permissions: []` fails the pre-doc check → 405 disabled.
+- Instance auto-load uses `model.findById(id)` only — **`queryFilter` is intentionally not applied** to match existing CRUD permission middleware (`permissions.ts:148`). This means action handlers may see docs that wouldn't appear in list responses; permission functions are responsible for the final check. This is an existing leak (403 confirms existence vs. 404 hides it) that the actions feature inherits. Document; don't fix in this PR.
+- `req.obj` is set to the loaded doc on instance actions, matching CRUD behavior. `ctx.doc` aliases `req.obj`.
+
+### `loadDocOr404` helper
+
+Extracted from the existing permission middleware doc-load logic (`api/src/api.ts:148–210`). Signature:
+
+```typescript
+async function loadDocOr404<T>(
+  model: Model<T>,
+  id: string,
+  populatePaths?: PopulatePath[]
+): Promise<T>;
+```
+
+Preserves the soft-delete-aware 404 metadata behavior. Used by both the existing CRUD permission middleware (after refactor) and the new instance-action middleware.
+
+### `runActionPermissions` helper
+
+```typescript
+async function runActionPermissions<T>(
+  action: BaseActionConfig<unknown, unknown, unknown, unknown>,
+  scope: 'instance' | 'collection',
+  req: Request,
+  doc?: T  // undefined for pre-doc check or for collection actions
+): Promise<void>;
+```
+
+Maps HTTP method + scope → CRUD method (table above). Invokes each `PermissionMethod` with `(method, req.user, doc)`. **Status codes match the existing CRUD middleware exactly** (`permissions.ts:103–217`):
+
+- Pre-doc denial (or any denial on collection actions) → **`APIError({status: 405, title: \`Access to ${METHOD} on ${model.modelName} denied for ${user?.id}\`})`** (parity with `permissions.ts:136`).
+- Post-doc denial on instance actions → **`APIError({status: 403, title: \`Access to ${METHOD} on ${model.modelName}:${id} denied for ${user?.id}\`})`** (parity with `permissions.ts:203`).
+- Empty `permissions: []` array → `checkPermissions` returns `false` on the pre-doc check → 405 (matches CRUD: empty array disables the method).
+- 401 responses come from `apiUnauthorizedMiddleware` for passport failures, not from this helper. Tests should assert the wire envelope from that path, not synthesize it.
+
+### Zod validation
+
+```typescript
+const parsedBody = action.body?.safeParse(req.body);
+if (parsedBody && !parsedBody.success) {
+  const fieldErrors = parsedBody.error.flatten().fieldErrors;
+  const fields: Record<string, string> = {};
+  for (const [key, msgs] of Object.entries(fieldErrors)) {
+    fields[key] = (msgs as string[])[0];
+  }
+  throw new APIError({status: 400, title: 'Validation failed', fields});
+}
+const parsedQuery = action.query?.safeParse(req.query);
+// (query parsing follows same pattern)
+
+// Parsed values are passed through ctx — DO NOT reassign req.body / req.query.
+// Express 5 makes req.query a getter; assignment throws.
+ctx.body = parsedBody?.data;
+ctx.query = parsedQuery?.data;
+```
+
+**Wire shape of validation errors:** `APIError.fields` is folded into `meta.fields` by `errors.ts:117–121` and emitted as `{status: 400, title: "Validation failed", meta: {fields: {...}}}` (not `{..., fields: {...}}`). Tests and frontends consume `meta.fields`. This matches existing CRUD validation errors.
+
+**Zod object parsing strategy:** Zod 4 `.object()` defaults to **strip** (silently drops unknown fields). For actions we use `safeParse` against the user's schema as-is — the user can opt into `.strict()` to reject unknown fields. Document the default in the explainer.
+
+### Auto-wrap response
+
+```typescript
+const result = await action.handler(ctx);
+if (res.headersSent) return; // handler streamed
+res.status(action.status ?? 200).json({data: result ?? null});
+```
+
+Matches the **read/update/delete** CRUD envelope (`{data: ...}`). It deliberately does **not** match:
+
+- **List shape** (`{data, limit, more, page, total}` at `api.ts:761–767`) — list-style pagination is the user's responsibility. If a collection action wants paginated output, the handler builds the envelope itself and calls `res.json(...)`, then returns; the `headersSent` check skips the auto-wrap.
+- **Create status 201** (`api.ts:615`) — actions default to **200**. Users who want 201 set `status: 201` on the action config.
+
+Streaming handlers must complete the response (write headers via `res.json`/`res.end`) before returning so `res.headersSent` is true on the check.
+
+### Collision detection (register time)
+
+Before routes register, walk both action maps and validate:
+
+1. Empty action name → `Error("Action name cannot be empty")`.
+2. Action name matches a Mongoose schema array field path → `Error("instanceAction 'tags' collides with array field operations on /:id/tags")`.
+3. Action name is one of the reserved CRUD path segments (`""`, none for `:id` since the param is positional — but action paths like `id` are fine).
+4. Duplicate names across `instanceActions` and `collectionActions` are allowed (different scopes, different paths).
+
+Throw synchronously so app boot fails loudly.
+
+### OpenAPI emission
+
+**Emission must work under both `TerrenoApp` (which calls `_buildWithOpenApi`) and legacy `setupServer` (which never calls `_buildWithOpenApi`; `expressServer.ts:257`).** Therefore action OpenAPI registration uses the **same per-request middleware pattern as CRUD** (`openApi.ts:138–326`): a middleware factory captures the action config + Zod schemas at register time and emits the operation via `oapi.path()` on first request through that route.
+
+```typescript
+// Composed into the action middleware chain at register time:
+const actionOpenApiMiddleware = createActionOpenApiMiddleware({
+  action,
+  model,
+  scope,            // 'instance' | 'collection'
+  actionName,
+  tag: action.tag,  // defaults to model.collection.collectionName
+});
+```
+
+Inside the middleware, the first request through the route calls `oapi.path(operationObject)` with an Operation Object built from:
+- method/path/tag/summary/description/status
+- `operationId: '${tag}_${actionName}'` so RTK Query Code Generation produces stable, deterministic hook names
+- `parameters` containing `id` for instance actions
+- `requestBody`/`responses` whose `schema` is the inlined JSON-Schema fragment from `@asteasolutions/zod-to-openapi`'s `OpenApiGeneratorV3.generateSchema()` (no global registry — every schema is inlined, so no cross-router component-name collisions)
+
+**Dependency pinning:** `@asteasolutions/zod-to-openapi` MUST be pinned to **`^8.5.0`** (the first major with `peerDependencies: {zod: "^4.0.0"}`). Earlier majors pin to Zod 3 and break against the codebase's `zod ^4.3.6`.
+
+**Double-build interaction:** `api.ts:495` shows `_buildWithOpenApi` re-invokes `_buildModelRouter`, which re-invokes `options.endpoints` — so action route registration also happens twice for `TerrenoApp` consumers (once with `openApi: undefined`, once with `openApi: <real>`). This is fine because each invocation gets a fresh `express.Router()`, and the OpenAPI middleware no-ops when `options.openApi` is undefined. `assertNoActionCollisions` runs synchronously inside the constructor and is also idempotent (just throws or doesn't).
+
+## Files to Create / Modify
+
+| File | Action | Why |
+|---|---|---|
+| `api/src/actions.ts` | **create** | Public types (`ActionContext`, `InstanceActionConfig`, `CollectionActionConfig`) + helpers (`runActionPermissions`, `validateActionRequest`, `wrapActionResponse`, `registerActionRoutes`, `createActionOpenApiMiddleware`, `assertNoActionCollisions`) |
+| `api/src/docLoader.ts` | **create** | `loadDocOr404(model, id, populatePaths?)` helper, extracted from existing permission middleware. Neutral module to avoid `actions.ts` ↔ `permissions.ts` circular import |
+| `api/src/permissions.ts` | modify | Refactor `permissionMiddleware` to call `loadDocOr404` (behavior-preserving; soft-delete metadata + 404 fallback intact) |
+| `api/src/api.ts` | modify | Extend `ModelRouterOptions<T>` with `instanceActions`/`collectionActions`; call `assertNoActionCollisions` + `registerActionRoutes` in the pre-CRUD endpoints slot. No new `_buildWithOpenApi` work — action OpenAPI emits via per-request middleware composed into the action chain |
+| `api/src/index.ts` | modify | Re-export `ActionContext`, `InstanceActionConfig`, `CollectionActionConfig` |
+| `api/package.json` | modify | Add `zod ^4.3.6` as a **peerDependency** (matching `example-backend`'s installed version) plus `^4.3.6` in `devDependencies` for compile + tests. Add `@asteasolutions/zod-to-openapi ^8.5.0` as a regular `dependency` (it bundles its own usage). Bump `@terreno/api` version |
+| `api/src/consentApp.ts` | modify | Migrate the three `/consent-forms` `endpoints` actions (`generate`, `translate` — both conditional on `aiConfig`; `/:id/publish`). The `/consents/*` routes (`consentApp.ts:195–457`) are out of scope — they aren't on a `modelRouter` |
+| `api/src/actions.test.ts` | **create** | Unit + integration tests (see test plan) |
+| `example-backend/src/api/todos.ts` | modify | Add an instance action (`markComplete`) and a collection action (`bulkComplete`) to dogfood + demonstrate |
+| `example-frontend/store/openApiSdk.ts` | regenerate | Via `bun run sdk` after backend changes |
+| `docs/explanation/model-router-actions.md` | **create** | User-facing docs page |
+| `mcp-server/src/tools.ts` or `prompts.ts` | modify (if applicable) | Add `actions` to `generate_route` so AI assistants suggest the new API |
+
+## Phasing
+
+### Phase 1 — Foundation (types + runtime + per-route OpenAPI middleware)
+
+1. Add `zod ^4.3.6` and `@asteasolutions/zod-to-openapi ^8.5.0` to `api/package.json`. If a Bun catalog version of Zod exists, use it.
+2. Create `api/src/docLoader.ts` exporting `loadDocOr404(model, id, populatePaths?)`. Refactor `permissionMiddleware` in `api/src/permissions.ts` to call it. Behavior-preserving — added test asserts soft-delete 404 metadata is intact.
+3. Create `api/src/actions.ts` with public types and helpers, including the per-route `createActionOpenApiMiddleware` factory (no-ops when `options.openApi` is undefined; emits via `oapi.path()` on first request when present).
+4. Extend `ModelRouterOptions<T>` types in `api/src/api.ts`.
+5. Wire `assertNoActionCollisions` + `registerActionRoutes` into modelRouter, registered in the pre-CRUD `endpoints` slot. Action middleware chain composes: `authenticateMiddleware(options.allowAnonymous)` → pre-doc `runActionPermissions` → (instance) `loadDocOr404` → (instance) post-doc `runActionPermissions` → `validateActionRequest` → `action.handler` → `wrapActionResponse`. The `actionOpenApiMiddleware` runs alongside the chain for spec emission.
+6. Unit tests cover: types compile; instance + collection happy path (GET + POST); pre-doc perm denied → 405 (with title matching CRUD's "Method not allowed"); post-doc perm denied → 403; 401 path comes from `apiUnauthorizedMiddleware`; doc not found → 404 with soft-delete metadata; validation error → 400 with `meta.fields`; collision detection at register time; action-name regex; empty-array `permissions: []` → 405; auto-wrap shape; `res.headersSent` escape hatch.
+
+### Phase 2 — OpenAPI verification
+
+Per-action OpenAPI emission is part of Phase 1's middleware chain; this phase verifies the emitted spec.
+
+1. Tests against the generated `openapi.json`: contains action operations under `paths`; method + path correct; default tag = `model.collection.collectionName`; `tag` override honored; `requestBody.content."application/json".schema` is the Zod-derived JSON Schema (inlined); `responses[status].content."application/json".schema` likewise; instance paths include the `id` path parameter; collection paths do not; deterministic `operationId: '${tag}_${actionName}'`.
+2. Verify both code paths emit: `TerrenoApp` (via `_buildWithOpenApi` rebuild) **and** legacy `setupServer` (per-request middleware fires on first hit). Add a test asserting parity between the two paths.
+
+### Phase 3 — Migration + dogfooding
+
+1. Migrate `consentApp.ts` `/consent-forms` endpoint actions to the new API:
+   - `generate` → `collectionActions.generate` (constructed conditionally on `aiConfig`).
+   - `translate` → `collectionActions.translate` (same conditional).
+   - `/:id/publish` → `instanceActions.publish`.
+   - Leave `/consents/*` routes (`consentApp.ts:195–457`) unchanged — not on a `modelRouter`.
+2. Confirm existing consent-form tests pass without modification.
+3. Add a `markComplete` instance action and `bulkComplete` collection action to `example-backend/src/api/todos.ts`.
+4. Regenerate `example-frontend` SDK: `cd example-frontend && bun run sdk`.
+5. Smoke-test full stack: `bun run backend:dev` + `bun run frontend:web`; exercise both new todo actions via curl + regenerated hooks.
+
+### Phase 4 — Consumer compile-check + docs
+
+1. Verify all in-repo consumers of `@terreno/api` compile and test cleanly under the new deps: `admin-backend`, `admin-frontend`, `ai`, `api-health`, `feature-flags`, `mcp-server`, `rtk`, `example-backend`. Run `bun run compile` (and `bun run test` where present) per package.
+2. Decide and document whether `zod` is a `dependency` or `peerDependency` of `@terreno/api`. Default: hard `dependency` (matches `mongoose-to-swagger` etc.).
+3. Write `docs/explanation/model-router-actions.md` with the call-site example, semantics (permission status codes, response envelope, validation wire shape, collision detection, Zod `.strict()` recommendation), and migration notes from hand-rolled `endpoints` actions.
+4. Update `mcp-server/src/tools.ts` `generate_route` to suggest `instanceActions`/`collectionActions`.
+5. Bump `@terreno/api` version and prepare changelog entry mentioning the new feature, the new deps, and the behavior-preserving permission middleware refactor.
+
+## Test Plan
+
+All tests in `api/src/actions.test.ts` using the existing pattern (`getBaseServer`, `authAsUser`, `setupDb`, `supertest`).
+
+### Registration
+
+- Throws when `permissions` missing.
+- Throws when `permissions` is an empty array.
+- Throws when an action name collides with an array-field operation.
+- Throws on empty action name.
+- Does not throw on instance + collection actions sharing a name.
+
+### Routing & permissions
+
+- `POST /resource/:id/action` invokes handler with loaded `doc` and `req.obj` set.
+- `POST /resource/action` invokes handler with no `doc`.
+- `GET` actions work for both scopes.
+- `404` when instance action id doesn't exist (and reflects soft-delete metadata, matching CRUD).
+- `401` when unauthenticated and `IsAuthenticated` in permissions — coming from `apiUnauthorizedMiddleware`, with the existing 401 wire shape (not from a synthesized APIError).
+- Pre-doc perm denial → **405** with title `Access to <METHOD> on <Model> denied for <userId>` (matches `permissions.ts:136`).
+- Post-doc perm denial → **403** with title `Access to <METHOD> on <Model>:<id> denied for <userId>` (matches `permissions.ts:203`).
+- Empty `permissions: []` → **405** (method disabled), matching CRUD.
+- `IsAuthenticatedOrReadOnly` passes for GET actions even when `allowAnonymous: true` and no auth header (validates the method mapping AND that `authenticateMiddleware(options.allowAnonymous)` is honoured).
+- `IsOwner` works on instance actions (validates the two-phase permission flow: pre-doc returns true when `obj` is undefined; post-doc checks `ownerId`).
+
+### Validation
+
+- Valid body parses through and reaches handler via `ctx.body`.
+- Invalid body → 400 with `meta.fields` populated (per `errors.ts:117–121` wire shape).
+- Body parsing coerces (Zod-style) — `z.coerce.number()` transforms `"5"` to `5` in `ctx.body`.
+- Query schema validates query params; parsed result in `ctx.query`. `req.query` is NOT reassigned (Express 5 getter).
+- Missing body when schema requires → 400.
+- Default `.strip` behavior of Zod objects — unknown fields silently dropped from `ctx.body`. Tests assert this and the explainer doc recommends `.strict()`.
+
+### Response shape
+
+- Handler return value wrapped in `{data: ...}` (matches read/update/delete CRUD envelope).
+- `status` option respected (e.g. 202).
+- `null`/`undefined` return → `{data: null}`.
+- Headers-sent escape hatch: handler that calls `res.json` directly is not re-wrapped.
+- Test asserting list-style envelope is **user's responsibility** (collection action that calls `res.json({data, total, more, ...})` then returns is not re-wrapped).
+
+### OpenAPI
+
+- Generated spec contains operations for each registered action.
+- Default tag = model collection name; `tag` override applied when set.
+- Request body schema converted from Zod and included in operation.
+- Response schema included under the configured status code.
+- Path parameters present for instance actions (`{id}`).
+
+### Migration
+
+- Existing `consentApp.ts` tests pass against migrated code.
+
+## Acceptance Criteria
+
+Each criterion is independently testable. Most are exercised by the bun-test suite in `api/src/actions.test.ts`; smoke criteria are exercised manually against `example-backend` + `example-frontend`.
+
+### AC1 — Instance action happy path (POST)
+
+**Given** a modelRouter with `instanceActions: {publish: {method: 'POST', permissions: [IsOwner], body: z.object({notify: z.boolean()}), response: z.object({ok: z.boolean()}), handler}}`
+**When** an owner POSTs `{notify: true}` to `/resource/{validId}/publish`
+**Then** the handler receives `ctx.doc` (the loaded document), `ctx.body.notify === true`, `ctx.user` is set; response is `200 {data: {ok: true}}`.
+
+### AC2 — Collection action happy path (POST)
+
+**Given** a modelRouter with `collectionActions: {bulkArchive: {method: 'POST', permissions: [IsAdmin], body, handler}}`
+**When** an admin POSTs a valid body to `/resource/bulkArchive`
+**Then** the handler receives `ctx.body` parsed and `ctx.doc` is `undefined`; response is `200 {data: <handler return>}`.
+
+### AC3 — GET actions
+
+**Given** an instance action with `method: 'GET'` and a `query` schema
+**When** a permitted user GETs `/resource/{id}/actionName?x=1`
+**Then** `ctx.query` is parsed and passed; response is wrapped in `{data: ...}`.
+
+### AC4 — Auth required → 401
+
+**Given** an action with `permissions: [IsAuthenticated]`
+**When** an unauthenticated request hits the action URL
+**Then** response is `401` with the existing unauthorized wire shape from `apiUnauthorizedMiddleware` (`errors.ts:208–219`).
+
+### AC5 — Permission denied: pre-doc → 405, post-doc → 403
+
+**Given** an instance action with `permissions: [IsOwner]` and a non-owner authenticated user
+**When** they POST to the action
+**Then** the request reaches the post-doc permission check (since `IsOwner` returns `true` when `obj` is undefined). The post-doc check fails on `ownerId` mismatch and response is **403** with title `Access to UPDATE on <Model>:<id> denied for <userId>`.
+
+**Given** a collection action with `permissions: [IsAdmin]` and a non-admin authenticated user
+**When** they POST to the action
+**Then** response is **405** with title `Access to CREATE on <Model> denied for <userId>` (pre-doc denial, matching `permissions.ts:136`).
+
+### AC6 — `IsAuthenticatedOrReadOnly` mapping
+
+**Given** an action with `permissions: [IsAuthenticatedOrReadOnly]` and `method: 'GET'`
+**When** an unauthenticated user GETs it
+**Then** request succeeds (validates that the method mapping treats GET actions as `'read'` / `'list'`).
+
+### AC7 — Instance doc not found → 404
+
+**Given** any instance action
+**When** a request hits `/resource/{nonexistentId}/action`
+**Then** response is `404` with the existing `APIError` shape (matching the CRUD GET-by-id 404 metadata behavior for soft-deleted documents).
+
+### AC8 — Validation error → 400 with field-level errors
+
+**Given** an action with `body: z.object({email: z.string().email()})`
+**When** a request sends `{email: "not-an-email"}`
+**Then** response is `400` with `title === "Validation failed"` and the body contains `meta.fields.email` populated with the Zod error message (per `errors.ts:117–121` wire shape — `fields` is folded into `meta.fields`).
+
+### AC9 — Coercion via Zod
+
+**Given** an action with `body: z.object({count: z.coerce.number()})` and request body `{count: "5"}`
+**Then** handler receives `ctx.body.count === 5` (parsed value passed via `ctx`, NOT via mutating `req.body`).
+
+### AC10 — Response envelope
+
+**Given** an action handler that returns `{x: 1}`
+**Then** the HTTP response body is exactly `{"data": {"x": 1}}` and HTTP status defaults to `200`.
+
+### AC11 — Custom status code
+
+**Given** an action with `status: 202` returning `{queued: true}`
+**Then** the HTTP response status is `202` and body is `{"data": {"queued": true}}`.
+
+### AC12 — Null return
+
+**Given** an action handler that returns `undefined`
+**Then** the response body is `{"data": null}`.
+
+### AC13 — Streaming escape hatch
+
+**Given** an action handler that calls `res.json({custom: 1})` then returns
+**Then** the response body is `{"custom": 1}` (not re-wrapped); no exception thrown.
+
+### AC14 — Missing permissions throws at register time; empty array disables
+
+**Given** an action config with `permissions` **omitted entirely**
+**When** modelRouter is constructed
+**Then** an `Error` is thrown synchronously with a clear message naming the offending action.
+
+**Given** an action config with `permissions: []`
+**When** modelRouter is constructed
+**Then** no error is thrown at register time — the action is registered but every request to it returns **405** (pre-doc check fails because `checkPermissions` returns false for empty arrays per `permissions.ts:90–95`). This matches CRUD "method disabled" semantics.
+
+### AC14b — Action name validation
+
+**Given** an action keyed under `"foo*bar"` or `"foo:bar"` or `"foo/bar"`
+**When** modelRouter is constructed
+**Then** an `Error` is thrown naming the invalid name and the regex it must match (`/^[A-Za-z][A-Za-z0-9_-]+$/`).
+
+### AC15 — Collision detection
+
+**Given** an instance action named `tags` on a model with a `tags` array field
+**When** modelRouter is constructed
+**Then** an `Error` is thrown naming the collision (`/:id/tags`).
+
+### AC16 — Empty action name rejected
+
+**Given** an action keyed under `""`
+**Then** modelRouter construction throws.
+
+### AC17 — OpenAPI: operation appears under BOTH TerrenoApp and setupServer
+
+**Given** an action registered as above
+**When** the generated `openapi.json` is fetched (after at least one request through the action route, since OpenAPI emission is on-first-request middleware)
+**Then** the spec contains an operation at the correct path + method with the action's `summary` (or default), `description`, `tag` (default = model collection name), `requestBody` schema (from Zod, inlined), `responses[status].content.application/json.schema` (inlined Zod-derived), and `operationId: '${tag}_${actionName}'`. This must hold both for routers registered via `TerrenoApp.register(...)` and via `setupServer({addRoutes})` paths.
+
+### AC18 — OpenAPI: tag override
+
+**Given** an action with `tag: 'Custom Tag'`
+**Then** the OpenAPI operation lists `tags: ['Custom Tag']`.
+
+### AC19 — OpenAPI: path parameter present for instance actions
+
+**Given** any instance action
+**Then** its OpenAPI operation lists a path parameter `id` (string).
+
+### AC19b — OpenAPI: deterministic operationId
+
+**Given** an action named `publish` on a model with tag `schedules`
+**Then** the operation's `operationId` is `schedules_publish` — guaranteeing RTK Query Code Generation produces a stable hook name.
+
+### AC20 — `consentApp.ts` migration behaviour-preserving
+
+**Given** the consent forms test suite
+**When** `consentApp.ts` is migrated to the new actions API
+**Then** all existing tests pass without modification.
+
+### AC21 — Example backend exposes new actions
+
+**Given** `example-backend/src/api/todos.ts` declares `markComplete` and `bulkComplete` actions
+**When** the backend is started and the OpenAPI spec is fetched
+**Then** both operations appear under the Todos tag with correct paths/methods.
+
+### AC22 — Example frontend SDK regeneration
+
+**Given** the regenerated `example-frontend/store/openApiSdk.ts`
+**Then** typed hooks for both new actions exist and compile.
+
+### AC23 — Test suite passes
+
+**Given** `bun run test` in `api/`
+**Then** all tests pass (including new `actions.test.ts` and existing consent + modelRouter suites).
+
+### AC24 — Type checking
+
+**Given** `bun run compile` in every `@terreno/api` consumer (`api`, `admin-backend`, `admin-frontend`, `ai`, `api-health`, `feature-flags`, `mcp-server`, `rtk`, `example-backend`, `example-frontend`)
+**Then** all compilations succeed.
+
+### AC25 — No regression in `endpoints` callback
+
+**Given** an existing modelRouter using `endpoints: (router) => { router.get('/custom', handler) }`
+**Then** the custom route still works unchanged after this PR (the action system is additive).
+
+### AC26 — `allowAnonymous` propagation
+
+**Given** `modelRouter(Model, {allowAnonymous: true, instanceActions: {foo: {method: 'GET', permissions: [IsAuthenticatedOrReadOnly], handler}}})`
+**When** an unauthenticated request hits `/{id}/foo`
+**Then** the request succeeds (no 401). Validates that `authenticateMiddleware(options.allowAnonymous)` is honoured.
+
+### AC27 — Co-registration precedence
+
+**Given** a modelRouter with `instanceActions: {foo: {...}}` **and** `endpoints: (router) => { router.get('/:id/foo', handler) }`
+**When** a request hits `/:id/foo`
+**Then** the action handler runs (actions register first in the pre-CRUD slot, before user `options.endpoints`).
+
+### AC28 — Type-preserving factories
+
+**Given** a call-site using `defineInstanceAction<ScheduleDoc>({body: z.object({x: z.string()}), handler: async ({doc, body}) => { /* ... */ }})`
+**Then** `tsc --noEmit` confirms `doc: ScheduleDoc` and `body: {x: string}` (per-action generics preserved across the `Record<string, ...>` boundary).
+
+## Risks & Open Items
+
+| # | Risk / Item | Mitigation |
+|---|---|---|
+| 1 | Adding `zod` + `zod-to-openapi` to `@terreno/api` is a new direction (today's validation is AJV/JSON-schema). | Action validation is parallel, not replacing AJV. Coexists. Pin `@asteasolutions/zod-to-openapi ^8.5.0` so the Zod 4 peer-dep is satisfied. |
+| 2 | `loadDocOr404` extraction touches the hot permission middleware path. | Extract to a neutral `api/src/docLoader.ts` module to avoid circular imports. Refactor must be behavior-preserving — added test asserting current 404 metadata behavior. |
+| 3 | TypeScript inference across `Record<string, InstanceActionConfig<T, unknown, unknown, unknown>>` loses per-action body/query/response types at the record boundary. | Ship `defineInstanceAction()` / `defineCollectionAction()` identity helpers that preserve per-action generics (`TBody`, `TQuery`, `TResponse`) for full handler-side inference. Bare object literals still work, just with `unknown` widening. |
+| 4 | `IsAuthenticatedOrReadOnly` on collection POST → mapped to `'create'`, denies anon access. | Cover in test + docs. |
+| 5 | Generated SDK changes — frontends consuming `@terreno/rtk` will see new endpoints with deterministic `operationId`-based hook names. | Expected. Standard SDK regeneration step in Phase 3. `operationId: '${tag}_${actionName}'` ensures stable names. |
+| 6 | Existing `endpoints` callers might want to migrate piecemeal — both APIs need to coexist. | They do: actions sit on top of the `endpoints` slot internally. Document `endpoints` as the escape hatch. AC25 explicitly tests this. |
+| 7 | `_buildModelRouter` runs twice for `TerrenoApp` registrations (`api.ts:495`). Action registration + OpenAPI middleware fire twice. | Idempotent: each call gets a fresh router; OpenAPI middleware no-ops when `options.openApi` is undefined (first call) and emits when defined (second call). Documented in "Internal Mechanics → Double-build interaction." |
+| 8 | Instance action auto-load uses `findById` and bypasses `queryFilter` (matches existing CRUD permission middleware at `permissions.ts:148`). Reveals doc existence via 403 vs 404. | Pre-existing leak inherited unchanged. Document. Out of scope to fix. |
+| 9 | Concurrent action handlers loading the same doc + `doc.save()` → `VersionError` → 500. | Existing CRUD limitation (see `api.ts:1118–1130`). Document in explainer: "actions are not transactional; for concurrent writes prefer `findOneAndUpdate`." |
+| 10 | Express 5 makes `req.query` getter-only. Plan avoids mutating it; parsed body/query is passed via `ctx`. | Tests assert `ctx.query` carries parsed value while `req.query` is untouched. |
+| 11 | Zod 4 `.object()` defaults to `.strip` — unknown fields silently dropped. | Document and recommend `.strict()` in the explainer. AC test asserts default `.strip` behavior so users aren't surprised. |
+
+## Out of Scope
+
+- Pre/post hooks on actions (deferred until a clear pattern emerges).
+- Built-in bulk helpers (`bulkUpdate`, `bulkDelete`) — userland for now.
+- Automatic kebab-case URL transformation.
+- Action permissions inheritance from the model's CRUD permissions.
+- Webhook / async actions.
+- Per-action rate limiting.