@classytic/arc 2.8.5 → 2.9.1

package/README.md

@@ -2,7 +2,7 @@
 
 Database-agnostic resource framework for Fastify. Define resources, get CRUD routes, permissions, presets, caching, events, OpenAPI, and MCP tools — without boilerplate.
 
-**v2.8.4** | Fastify 5+ | Node.js 22+ | ESM only | 279+ test files, 3867+ tests
+**v2.9** | Fastify 5+ | Node.js 22+ | ESM only
 
 ## Install
 
@@ -65,8 +65,13 @@ const app = await createApp({
 Clean DX without growing exclude lists:
 
 ```typescript
-// app.ts — register once with perResource mode
-await fastify.register(auditPlugin, { autoAudit: { perResource: true } });
+import { Repository } from '@classytic/mongokit';
+
+// app.ts — pass any RepositoryLike (mongokit / prismakit / custom)
+await fastify.register(auditPlugin, {
+  autoAudit: { perResource: true },
+  repository: new Repository(AuditModel),  // or omit for in-memory dev
+});
 
 // order.resource.ts — opt in
 defineResource({ name: 'order', audit: true });
@@ -99,8 +104,8 @@ const productResource = defineResource({
     delete: roles('admin'),
   },
   cache: { staleTime: 30, gcTime: 300, tags: ['catalog'] }, // QueryCache (opt-in)
-  additionalRoutes: [
-    { method: 'GET', path: '/featured', handler: 'getFeatured', permissions: allowPublic(), wrapHandler: true },
+  routes: [
+    { method: 'GET', path: '/featured', handler: 'getFeatured', permissions: allowPublic() },
   ],
 });
 
@@ -383,6 +388,29 @@ await app.events.subscribe('order.*', async (event) => { ... });
 
 CRUD events (`product.created`, `product.updated`, `product.deleted`) emit automatically.
 
+### Causation Chains & DLQ (v2.9)
+
+```typescript
+import { createEvent, createChildEvent, type DeadLetteredEvent } from '@classytic/arc/events';
+
+const placed = createEvent('order.placed', { orderId: 'o1' }, {
+  correlationId: req.id, userId: user.id,
+});
+await app.events.publish(placed.type, placed.payload, placed.meta);
+
+// Downstream handler emits a child — correlation inherited, causation linked:
+const reserved = createChildEvent(placed, 'inventory.reserved', { sku: 'a' });
+// reserved.meta.correlationId === placed.meta.correlationId (stays stable across chain)
+// reserved.meta.causationId   === placed.meta.id            (direct parent)
+
+// Transports with native DLQ (Kafka, SQS) implement optional deadLetter():
+class KafkaTransport implements EventTransport {
+  async deadLetter(dlq: DeadLetteredEvent) { /* route to .DLQ topic */ }
+}
+```
+
+`EventMeta` also accepts `schemaVersion` (evolve event payloads) and `partitionKey` (ordered delivery hint for Kafka/Kinesis).
+
 ### defineEvent — Typed Events with Schema Validation
 
 Declare events with schemas for runtime validation and introspection:
@@ -722,6 +750,61 @@ Arc sets `"sideEffects": false` in [package.json](package.json), so modern bundl
 | `@classytic/arc/docs` | OpenAPI generation |
 | `@classytic/arc/cli` | CLI commands (programmatic) |
 
+## v2.9.1 Highlights
+
+`auditPlugin`, `idempotencyPlugin`, and `EventOutbox` take a
+`repository: RepositoryLike` option — pass any `Repository` (mongokit /
+prismakit / your own kit). Arc calls `create` / `getOne` / `findAll` /
+`deleteMany` / `findOneAndUpdate` on it directly:
+
+```typescript
+import { Repository } from '@classytic/mongokit';
+import { auditPlugin } from '@classytic/arc/audit';
+import { idempotencyPlugin } from '@classytic/arc/idempotency';
+import { EventOutbox } from '@classytic/arc/events';
+
+await fastify.register(auditPlugin, { repository: new Repository(AuditModel) });
+await fastify.register(idempotencyPlugin, {
+  repository: new Repository(IdempotencyModel, [
+    methodRegistryPlugin(), batchOperationsPlugin(), mongoOperationsPlugin(),
+  ]),
+});
+new EventOutbox({ repository: new Repository(OutboxModel), transport });
+```
+
+Memory + Redis stores unchanged via `store` / `customStores`. Requires
+`@classytic/mongokit ≥3.8.0`.
+
+## v2.9 Highlights
+
+**Security defaults (breaking):**
+- **Field-write perms reject by default** — requests with non-writable fields return 403 with denied-field list. Opt into legacy silent-strip via `defineResource({ onFieldWriteDenied: 'strip' })`.
+- **multiTenant preset injects org on UPDATE** — body-supplied `organizationId` is overwritten with caller's scope (prior: CREATE only; a member could hop their own doc to another tenant).
+- **Elevation always emits `arc.scope.elevated`** — privilege elevation can no longer be silently un-audited. Subscribe via `fastify.events.subscribe('arc.scope.elevated', …)`. `onElevation` callback still supported.
+- **`verifySignature` throws on parsed body** — prevents the common `req.body` vs `req.rawBody` footgun that looks like a wrong secret.
+- **Upload `sanitizeFilename` policy** — rejects path separators, NUL, `.`/`..`, >255 chars by default. Flexible: pass `false` / `'*'` / custom function to override.
+- **Idempotency `namespace`** — optional key folded into fingerprint for shared-store deployments (prod + canary on one Redis).
+
+**Event contract v2 (additive):**
+- `EventMeta` gets `schemaVersion`, `causationId`, `partitionKey`, `source`, `idempotencyKey`, `aggregate: { type, id }`
+- `createChildEvent(parent, type, payload)` — auto-chains causation + inherits correlation / userId / organizationId / source / idempotencyKey (aggregate stays explicit)
+- `DeadLetteredEvent<T>` type + optional `transport.deadLetter()` for first-class DLQ
+- `withRetry({ transport })` auto-routes exhausted events to `transport.deadLetter()` — no custom `$deadLetter` plumbing
+- Downstream packages narrow `aggregate.type` to a closed DDD union via interface extension
+
+**Outbox v2 (additive):**
+- `EventOutbox.store()` auto-maps `event.meta.idempotencyKey` → `OutboxWriteOptions.dedupeKey` (caller's explicit `dedupeKey` still wins)
+- `new EventOutbox({ failurePolicy: ({ attempts, error }) => ({ retryAt?, deadLetter? }) })` — centralises retry + DLQ escalation, no more hand-rolled `exponentialBackoff` at every failure site
+- `outbox.getDeadLettered(limit)` returns typed `DeadLetteredEvent[]` — same shape `withRetry` produces, closes the loop between retry DLQ and outbox DLQ state
+- `RelayResult.deadLettered` — per-batch DLQ transition count for dashboards
+- Durable outbox via any `RepositoryLike` — `new EventOutbox({ repository, transport })` (2.9.1); multi-worker claim, TTL purge, dedupe, and session-threaded writes come from the repository's backing kit
+
+**Removed (no replacement kept):**
+- `createActionRouter`, `buildActionBodySchema` — use `defineResource({ actions })`
+- `ResourceConfig.onRegister` — use `actions` or resource `hooks`
+- `PluginResourceResult.additionalRoutes` → `routes: RouteDefinition[]`
+- `PolicyContext` / `PolicyResult` `any` fields → `unknown` (tighten downstream narrowing)
+
 ## v2.8.4 Highlights
 
 - **MCP ↔ AI SDK bridge** — expose AI SDK `tool()` definitions over MCP without duplicating code. `bridgeToMcp(bridge)` adapts any AI SDK tool into an MCP tool with automatic auth, guard delegation, and `{ error } → isError` envelope translation. `buildMcpToolsFromBridges(bridges, { include, exclude })` registers a whole catalog at once with per-environment filtering.

package/dist/{BaseController-DAGGc5Xn.mjs → BaseController-Vu2yc56T.mjs}

@@ -2,9 +2,10 @@ import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-Cxde4
 import { _ as isElevated, n as PUBLIC_SCOPE, o as getOrgId, v as isMember } from "./types-AOD8fxIw.mjs";
 import { t as buildQueryKey } from "./keys-qcD-TVJl.mjs";
 import { getUserId } from "./types/index.mjs";
-import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-ipsbIRPK.mjs";
+import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-CU6FlaDV.mjs";
 import { t as getUserRoles } from "./types-ZUu_h0jp.mjs";
-import { t as ArcQueryParser } from "./queryParser-CgCtsjti.mjs";
+import { r as ForbiddenError } from "./errors-CqWnSqM-.mjs";
+import { t as ArcQueryParser } from "./queryParser-Cs-6SHQK.mjs";
 //#region src/core/AccessControl.ts
 /**
 * AccessControl - Composable access control logic extracted from BaseController.
@@ -95,20 +96,82 @@ var AccessControl = class AccessControl {
 	*   buildIdFilter -> getOne (or getById + checkOrgScope + checkPolicyFilters)
 	*/
 	async fetchWithAccessControl(id, req, repository, queryOptions) {
+		return (await this.fetchDetailed(id, req, repository, queryOptions)).doc;
+	}
+	/**
+	* Same as `fetchWithAccessControl` but returns a structured result with
+	* a denial reason so callers can distinguish "doc doesn't exist" from
+	* "doc exists but was filtered by policy/org scope" from "repo threw".
+	*
+	* Codes:
+	* - `null`               — doc was found, no denial
+	* - `'NOT_FOUND'`        — doc genuinely doesn't exist in the DB
+	* - `'POLICY_FILTERED'`  — doc exists but the request's policy filters exclude it
+	* - `'ORG_SCOPE_DENIED'` — doc exists but the caller's org context doesn't match
+	* - `'REPO_ERROR'`       — the repository threw a "not found" error (mongokit style)
+	*/
+	async fetchDetailed(id, req, repository, queryOptions) {
 		const compoundFilter = this.buildIdFilter(id, req);
-		const needsCompoundLookup = Object.keys(compoundFilter).length > 1 || this.idField !== "_id";
+		const hasCompoundFilters = Object.keys(compoundFilter).length > 1;
+		const needsCompoundLookup = hasCompoundFilters || this.idField !== "_id";
+		const translateStatus404 = (error) => {
+			if (error && typeof error === "object" && error.status === 404) return {
+				doc: null,
+				reason: "NOT_FOUND"
+			};
+			return null;
+		};
 		try {
-			if (needsCompoundLookup && typeof repository.getOne === "function") return await repository.getOne(compoundFilter, queryOptions);
+			if (needsCompoundLookup && typeof repository.getOne === "function") {
+				const doc = await repository.getOne(compoundFilter, queryOptions);
+				if (doc) return {
+					doc,
+					reason: null
+				};
+				if (hasCompoundFilters) {
+					const idOnly = { [this.idField]: id };
+					const rawDoc = await repository.getOne(idOnly);
+					if (rawDoc) {
+						const arcContext = this._meta(req);
+						if (!this.checkOrgScope(rawDoc, arcContext)) return {
+							doc: null,
+							reason: "ORG_SCOPE_DENIED"
+						};
+						return {
+							doc: null,
+							reason: "POLICY_FILTERED"
+						};
+					}
+				}
+				return {
+					doc: null,
+					reason: "NOT_FOUND"
+				};
+			}
 			if (this.idField !== "_id") {
 				if (typeof repository.getOne !== "function") throw new Error(`Resource with idField="${this.idField}" requires repository.getOne() to look up by custom field. Arc's BaseController cannot fall back to getById() because it would query by _id.`);
 			}
 			const item = await repository.getById(id, queryOptions);
-			if (!item) return null;
+			if (!item) return {
+				doc: null,
+				reason: "NOT_FOUND"
+			};
 			const arcContext = this._meta(req);
-			if (!this.checkOrgScope(item, arcContext) || !this.checkPolicyFilters(item, req)) return null;
-			return item;
+			if (!this.checkOrgScope(item, arcContext)) return {
+				doc: null,
+				reason: "ORG_SCOPE_DENIED"
+			};
+			if (!this.checkPolicyFilters(item, req)) return {
+				doc: null,
+				reason: "POLICY_FILTERED"
+			};
+			return {
+				doc: item,
+				reason: null
+			};
 		} catch (error) {
-			if (error instanceof Error && error.message?.includes("not found")) return null;
+			const translated = translateStatus404(error);
+			if (translated) return translated;
 			throw error;
 		}
 	}
@@ -224,20 +287,12 @@ var AccessControl = class AccessControl {
 		}
 	}
 };
-//#endregion
-//#region src/core/BodySanitizer.ts
-/**
-* BodySanitizer - Composable body sanitization logic extracted from BaseController.
-*
-* Strips readonly fields, system-managed fields, and applies field-level
-* write permissions from request bodies before create/update operations.
-*
-* Designed to be used standalone or composed into controllers.
-*/
 var BodySanitizer = class {
 	schemaOptions;
+	onFieldWriteDenied;
 	constructor(config) {
 		this.schemaOptions = config.schemaOptions;
+		this.onFieldWriteDenied = config.onFieldWriteDenied ?? "reject";
 	}
 	/**
 	* Strip readonly and system-managed fields from request body.
@@ -261,7 +316,9 @@ var BodySanitizer = class {
 				const fieldPerms = arcContext?.arc?.fields;
 				if (fieldPerms) {
 					const effectiveRoles = resolveEffectiveRoles(getUserRoles(req.user), isMember(scope) ? scope.orgRoles : []);
-					sanitized = applyFieldWritePermissions(sanitized, fieldPerms, effectiveRoles);
+					const { body: filtered, deniedFields } = applyFieldWritePermissions(sanitized, fieldPerms, effectiveRoles);
+					if (deniedFields.length > 0 && this.onFieldWriteDenied === "reject") throw new ForbiddenError(`Not permitted to write field${deniedFields.length === 1 ? "" : "s"}: ${deniedFields.join(", ")}`);
+					sanitized = filtered;
 				}
 			}
 		}
@@ -404,6 +461,12 @@ var QueryResolver = class {
 //#endregion
 //#region src/core/BaseController.ts
 /**
+* Portable "run on next tick" scheduler. `setImmediate` is Node-only — not
+* available in Bun workers, Deno, Cloudflare Workers, or edge runtimes. Fall
+* back to queueMicrotask (universal) when setImmediate is absent.
+*/
+const scheduleBackground = typeof setImmediate === "function" ? (cb) => void setImmediate(cb) : (cb) => queueMicrotask(cb);
+/**
 * Framework-agnostic base controller implementing IController.
 *
 * Composes AccessControl, BodySanitizer, and QueryResolver for clean
@@ -450,7 +513,10 @@ var BaseController = class {
 			idField: this.idField,
 			matchesFilter: this._matchesFilter
 		});
-		this.bodySanitizer = new BodySanitizer({ schemaOptions: this.schemaOptions });
+		this.bodySanitizer = new BodySanitizer({
+			schemaOptions: this.schemaOptions,
+			onFieldWriteDenied: options.onFieldWriteDenied
+		});
 		this.queryResolver = new QueryResolver({
 			queryParser: this.queryParser,
 			maxLimit: this.maxLimit,
@@ -506,6 +572,28 @@ var BaseController = class {
 		if (repoIdField && repoIdField === this.idField) return id;
 		return String(existing["_id"] ?? id);
 	}
+	/**
+	* Centralized 404 response builder. Maps the denial reason from
+	* `fetchDetailed()` into a structured `details.code` so consumers can
+	* programmatically distinguish "doc doesn't exist" from "doc filtered
+	* by policy/org scope" without parsing error strings.
+	*
+	* Error messages are intentionally vague in the `error` field (don't
+	* leak whether the doc exists) — the detail is in `details.code` only.
+	*/
+	notFoundResponse(reason = "NOT_FOUND") {
+		const code = reason ?? "NOT_FOUND";
+		return {
+			success: false,
+			error: {
+				NOT_FOUND: "Resource not found",
+				POLICY_FILTERED: "Resource not found",
+				ORG_SCOPE_DENIED: "Resource not found"
+			}[code] ?? "Resource not found",
+			status: 404,
+			details: { code }
+		};
+	}
 	/** Resolve cache config for a specific operation, merging per-op overrides */
 	resolveCacheConfig(operation) {
 		const cfg = this._cacheConfig;
@@ -547,7 +635,7 @@ var BaseController = class {
 				headers: { "x-cache": "HIT" }
 			};
 			if (status === "stale") {
-				setImmediate(() => {
+				scheduleBackground(() => {
 					this.executeListQuery(options, req).then((fresh) => qc.set(key, fresh, cacheConfig)).catch(() => {});
 				});
 				return {
@@ -616,8 +704,8 @@ var BaseController = class {
 				headers: { "x-cache": "HIT" }
 			};
 			if (status === "stale") {
-				setImmediate(() => {
-					this.executeGetQuery(id, options, req).then((fresh) => {
+				scheduleBackground(() => {
+					this.executeGetQuery(id, options, req).then(({ doc: fresh }) => {
 						if (fresh) qc.set(key, fresh, cacheConfig);
 					}).catch(() => {});
 				});
@@ -628,49 +716,42 @@ var BaseController = class {
 					headers: { "x-cache": "STALE" }
 				};
 			}
-			const item = await this.executeGetQuery(id, options, req);
-			if (!item) return {
-				success: false,
-				error: "Resource not found",
-				status: 404
-			};
-			await qc.set(key, item, cacheConfig);
+			const { doc: cached, reason: cacheReason } = await this.executeGetQuery(id, options, req);
+			if (!cached) return this.notFoundResponse(cacheReason);
+			await qc.set(key, cached, cacheConfig);
 			return {
 				success: true,
-				data: item,
+				data: cached,
 				status: 200,
 				headers: { "x-cache": "MISS" }
 			};
 		}
-		try {
-			const item = await this.executeGetQuery(id, options, req);
-			if (!item) return {
-				success: false,
-				error: "Resource not found",
-				status: 404
-			};
-			return {
-				success: true,
-				data: item,
-				status: 200
-			};
-		} catch (error) {
-			if (error instanceof Error && error.message?.includes("not found")) return {
-				success: false,
-				error: "Resource not found",
-				status: 404
-			};
-			throw error;
-		}
+		const { doc, reason } = await this.executeGetQuery(id, options, req);
+		if (!doc) return this.notFoundResponse(reason);
+		return {
+			success: true,
+			data: doc,
+			status: 200
+		};
 	}
 	/** Execute get query through hooks (extracted for cache revalidation) */
 	async executeGetQuery(id, options, req) {
 		const hooks = this.getHooks(req);
-		const fetchItem = async () => this.accessControl.fetchWithAccessControl(id, req, this.repository, options);
-		return (hooks && this.resourceName ? await hooks.executeAround(this.resourceName, "read", null, fetchItem, {
-			user: req.user,
-			context: this.meta(req)
-		}) : await fetchItem()) ?? null;
+		const fetchItem = async () => {
+			return await this.accessControl.fetchDetailed(id, req, this.repository, options);
+		};
+		if (hooks && this.resourceName) {
+			const result = await fetchItem();
+			if (!result.doc) return result;
+			return {
+				doc: await hooks.executeAround(this.resourceName, "read", null, async () => result.doc, {
+					user: req.user,
+					context: this.meta(req)
+				}) ?? null,
+				reason: null
+			};
+		}
+		return fetchItem();
 	}
 	async create(req) {
 		const arcContext = this.meta(req);
@@ -733,12 +814,8 @@ var BaseController = class {
 		const user = req.user;
 		const userId = getUserId(user);
 		if (userId) data.updatedBy = userId;
-		const existing = await this.accessControl.fetchWithAccessControl(id, req, this.repository);
-		if (!existing) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		const { doc: existing, reason: updateReason } = await this.accessControl.fetchDetailed(id, req, this.repository);
+		if (!existing) return this.notFoundResponse(updateReason);
 		if (!this.accessControl.checkOwnership(existing, req)) return {
 			success: false,
 			error: "You do not have permission to modify this resource",
@@ -791,11 +868,7 @@ var BaseController = class {
 				}
 			});
 		} else item = await repoUpdate();
-		if (!item) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		if (!item) return this.notFoundResponse("NOT_FOUND");
 		return {
 			success: true,
 			data: item,
@@ -812,12 +885,8 @@ var BaseController = class {
 		};
 		const arcContext = this.meta(req);
 		const user = req.user;
-		const existing = await this.accessControl.fetchWithAccessControl(id, req, this.repository);
-		if (!existing) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		const { doc: existing, reason: deleteReason } = await this.accessControl.fetchDetailed(id, req, this.repository);
+		if (!existing) return this.notFoundResponse(deleteReason);
 		if (!this.accessControl.checkOwnership(existing, req)) return {
 			success: false,
 			error: "You do not have permission to delete this resource",
@@ -862,11 +931,7 @@ var BaseController = class {
 			if (typeof r.success === "boolean") return r.success;
 			if (typeof r.deletedCount === "number") return r.deletedCount > 0;
 			return true;
-		})()) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		})()) return this.notFoundResponse("NOT_FOUND");
 		if (hooks && this.resourceName) await hooks.executeAfter(this.resourceName, "delete", existing, {
 			user,
 			context: arcContext,
@@ -901,11 +966,7 @@ var BaseController = class {
 			error: "Slug lookup not implemented — repository needs getBySlug() or getOne()",
 			status: 501
 		};
-		if (!this.accessControl.validateItemAccess(item, req)) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		if (!this.accessControl.validateItemAccess(item, req)) return this.notFoundResponse(item ? "POLICY_FILTERED" : "NOT_FOUND");
 		return {
 			success: true,
 			data: item,
@@ -958,11 +1019,7 @@ var BaseController = class {
 			status: 400
 		};
 		const existing = await this.accessControl.fetchWithAccessControl(id, req, repo, { includeDeleted: true });
-		if (!existing) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		if (!existing) return this.notFoundResponse("NOT_FOUND");
 		if (!this.accessControl.checkOwnership(existing, req)) return {
 			success: false,
 			error: "You do not have permission to restore this resource",
@@ -998,11 +1055,7 @@ var BaseController = class {
 			meta: { id }
 		});
 		else item = await repoRestore();
-		if (!item) return {
-			success: false,
-			error: "Resource not found",
-			status: 404
-		};
+		if (!item) return this.notFoundResponse("NOT_FOUND");
 		if (hooks && this.resourceName) await hooks.executeAfter(this.resourceName, "restore", item, {
 			user,
 			context: arcContext,
@@ -1052,13 +1105,15 @@ var BaseController = class {
 			error: "Repository does not support createMany",
 			status: 501
 		};
-		const items = req.body?.items;
-		if (!items || items.length === 0) return {
+		const rawItems = req.body?.items;
+		if (!Array.isArray(rawItems) || rawItems.length === 0) return {
 			success: false,
 			error: "Bulk create requires a non-empty items array",
 			status: 400
 		};
+		const items = rawItems;
 		const arcContext = this.meta(req);
+		const user = req.user;
 		const sanitizedItems = items.map((item) => this.bodySanitizer.sanitize(item ?? {}, "create", req, arcContext));
 		let scopedItems = sanitizedItems;
 		if (this.tenantField) {
@@ -1086,7 +1141,10 @@ var BaseController = class {
 				}
 			}
 		}
-		const created = await repo.createMany(scopedItems);
+		const created = await repo.createMany(scopedItems, {
+			user,
+			context: arcContext
+		});
 		const requested = items.length;
 		const inserted = created.length;
 		const skipped = requested - inserted;
@@ -1157,13 +1215,23 @@ var BaseController = class {
 	*/
 	sanitizeBulkUpdateData(data, req, arcContext) {
 		const stripped = /* @__PURE__ */ new Set();
-		if (!Object.keys(data).some((k) => k.startsWith("$"))) {
+		const keys = Object.keys(data);
+		const operatorKeys = keys.filter((k) => k.startsWith("$"));
+		const flatKeys = keys.filter((k) => !k.startsWith("$"));
+		const isOperatorShape = operatorKeys.length > 0;
+		if (isOperatorShape && flatKeys.length > 0) return {
+			sanitized: {},
+			stripped: [],
+			mixedShape: true
+		};
+		if (!isOperatorShape) {
 			const before = new Set(Object.keys(data));
 			const sanitized = this.bodySanitizer.sanitize(data, "update", req, arcContext);
 			for (const key of before) if (!(key in sanitized)) stripped.add(key);
 			return {
 				sanitized,
-				stripped: [...stripped]
+				stripped: [...stripped],
+				mixedShape: false
 			};
 		}
 		const sanitized = {};
@@ -1180,7 +1248,8 @@ var BaseController = class {
 		}
 		return {
 			sanitized,
-			stripped: [...stripped]
+			stripped: [...stripped],
+			mixedShape: false
 		};
 	}
 	async bulkUpdate(req) {
@@ -1209,7 +1278,14 @@ var BaseController = class {
 			status: 403
 		};
 		const arcContext = this.meta(req);
-		const { sanitized, stripped } = this.sanitizeBulkUpdateData(body.data, req, arcContext);
+		const user = req.user;
+		const { sanitized, stripped, mixedShape } = this.sanitizeBulkUpdateData(body.data, req, arcContext);
+		if (mixedShape) return {
+			success: false,
+			error: "Bulk update payload cannot mix operator keys ($set, $inc, ...) with flat fields. Pick one shape.",
+			details: { code: "MIXED_UPDATE_SHAPE" },
+			status: 400
+		};
 		if (Object.keys(sanitized).length === 0) return {
 			success: false,
 			error: "Bulk update payload contained only protected fields",
@@ -1221,7 +1297,10 @@ var BaseController = class {
 		};
 		return {
 			success: true,
-			data: await repo.updateMany(scopedFilter, sanitized),
+			data: await repo.updateMany(scopedFilter, sanitized, {
+				user,
+				context: arcContext
+			}),
 			status: 200,
 			...stripped.length > 0 && { meta: { stripped } }
 		};
@@ -1272,9 +1351,16 @@ var BaseController = class {
 			details: { code: "ORG_CONTEXT_REQUIRED" },
 			status: 403
 		};
+		const hardHint = req.query?.hard === "true" || req.query?.hard === true || body.mode === "hard";
+		const arcContext = this.meta(req);
+		const options = {
+			user: req.user,
+			context: arcContext
+		};
+		if (hardHint) options.mode = "hard";
 		return {
 			success: true,
-			data: req.query?.hard === "true" || req.query?.hard === true || body.mode === "hard" ? await repo.deleteMany(scopedFilter, { mode: "hard" }) : await repo.deleteMany(scopedFilter),
+			data: await repo.deleteMany(scopedFilter, options),
 			status: 200
 		};
 	}