# 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.