@classytic/arc 2.32.0 → 2.34.0

package/dist/{BaseController-Dk34dxhI.mjs → BaseController-CbkuhNI2.mjs}

@@ -1,15 +1,17 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-J99LGTJI.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-BxCoxmiN.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { a as conjoinPolicyFilters } from "./authorizationDecision-__T3EJDA.mjs";
-import { d as createDomainError, f as createError, i as NotFoundError, p as isArcError, r as ForbiddenError } from "./errors-Bh1KK5ps.mjs";
-import { n as getUserRoles, t as getUserId } from "./userHelpers-BNsOXzOd.mjs";
-import { b as isElevated, c as getOrgId, n as PUBLIC_SCOPE, x as isMember } from "./types-DXYX7dIR.mjs";
-import { t as simpleEqualityMatcher } from "./simpleEqualityMatcher-C4KiMWUa.mjs";
-import { t as toRepositoryFilter } from "./repositoryFilter-DotlxG3L.mjs";
-import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-DEi65pGj.mjs";
-import { g as ArcQueryParser, n as scheduleBackground } from "./utils-BtOha_Sp.mjs";
-import { t as buildQueryKey } from "./keys-B-HBTGXl.mjs";
+import { a as conjoinPolicyFilters } from "./authorizationDecision-CMMLWmuZ.mjs";
+import { d as createDomainError, f as createError, i as NotFoundError, p as isArcError, r as ForbiddenError } from "./errors-Cd_yy7aW.mjs";
+import { n as getUserRoles, t as getUserId } from "./userHelpers-CWF5pbZD.mjs";
+import { b as isElevated, c as getOrgId, n as PUBLIC_SCOPE, x as isMember } from "./types-CoqIRrkY.mjs";
+import { t as simpleEqualityMatcher } from "./simpleEqualityMatcher-Se8VrsaP.mjs";
+import { n as toRepositoryFilter } from "./repositoryFilter-BANpz6BX.mjs";
+import { i as resolveEffectiveRoles, n as applyFieldWritePermissions } from "./fields-CojeUkS4.mjs";
+import { g as ArcQueryParser, n as scheduleBackground } from "./utils-h1V_sT-t.mjs";
+import { t as buildQueryKey } from "./keys-WeKvY1dE.mjs";
+import { retryingTransaction } from "@classytic/repo-core/repository";
+import { isProductionEnv } from "@classytic/primitives/environment";
 //#region src/core/AccessControl.ts
 const log$1 = arcLog("access-control");
 var AccessControl = class {
@@ -259,9 +261,11 @@ const DEFAULT_FIELD_WRITE_DENIAL_POLICY = "reject";
 var BodySanitizer = class {
 	schemaOptions;
 	onFieldWriteDenied;
+	onImmutableWrite;
 	constructor(config) {
 		this.schemaOptions = config.schemaOptions;
 		this.onFieldWriteDenied = config.onFieldWriteDenied ?? "reject";
+		this.onImmutableWrite = config.onImmutableWrite ?? (process.env.ARC_STRICT_IMMUTABLE_WRITES === "true" ? "reject" : "strip");
 	}
 	/**
 	* Strip readonly and system-managed fields from request body.
@@ -276,11 +280,16 @@ var BodySanitizer = class {
 		const scopeForRules = req ? (meta ?? req.metadata)?._scope ?? PUBLIC_SCOPE : void 0;
 		const scopeIsElevated = scopeForRules ? isElevated(scopeForRules) : false;
 		const fieldRules = this.schemaOptions.fieldRules ?? {};
+		const immutableAttempts = [];
 		for (const [field, rules] of Object.entries(fieldRules)) {
 			const bypass = Boolean(rules.preserveForElevated) && scopeIsElevated;
 			if ((rules.systemManaged || rules.readonly) && !bypass) delete sanitized[field];
-			if (_operation === "update" && (rules.immutable || rules.immutableAfterCreate) && !bypass) delete sanitized[field];
+			if (_operation === "update" && (rules.immutable || rules.immutableAfterCreate) && !bypass) {
+				if (Object.hasOwn(sanitized, field)) immutableAttempts.push(field);
+				delete sanitized[field];
+			}
 		}
+		if (immutableAttempts.length > 0 && this.onImmutableWrite === "reject") throw new ForbiddenError(`Cannot modify immutable field${immutableAttempts.length === 1 ? "" : "s"}: ${immutableAttempts.join(", ")}`);
 		if (req) {
 			const arcContext = meta ?? req.metadata;
 			const scope = arcContext?._scope ?? PUBLIC_SCOPE;
@@ -363,6 +372,73 @@ function buildTenantRepoOptions(req, tenantField, arcContext) {
 	return out;
 }
 /**
+* Marks a write method ARC installed.
+*
+* The constructor binds `create`/`update`/`delete`, so EVERY controller owns
+* all three and the bound function is a fresh object per instance —
+* `Object.hasOwn` and identity comparison both say nothing about overrides.
+* Provenance does: a class field initialises after `super()` and REPLACES the
+* bound method, mark and all.
+*
+* `Symbol.for` so it still matches across two arc copies in one graph.
+*/
+const ARC_BOUND_WRITE = Symbol.for("arc.boundWriteMethod");
+/**
+* Marks a controller PROTOTYPE whose write methods dispatch declared verbs.
+* `defineResource` refuses `writes` without it: a duck-typed `configure()`
+* proves an options channel exists, not that anything dispatches from it.
+* Lives on the prototype — one mark per class, zero per-instance cost.
+*/
+const ARC_WRITE_VERB_CAPABLE = Symbol.for("arc.writeVerbCapable");
+/** Tag a bound write method as arc's own. Returns the same function. */
+function markArcBoundWrite(fn) {
+	Object.defineProperty(fn, ARC_BOUND_WRITE, {
+		value: true,
+		enumerable: false,
+		configurable: true
+	});
+	return fn;
+}
+/** Did arc install this write method, as opposed to the host replacing it? */
+function isArcBoundWrite(fn) {
+	return typeof fn === "function" && Reflect.get(fn, ARC_BOUND_WRITE) === true;
+}
+/** Tag a controller class's prototype as write-verb capable. */
+function markWriteVerbCapable(prototype) {
+	Object.defineProperty(prototype, ARC_WRITE_VERB_CAPABLE, {
+		value: true,
+		enumerable: false,
+		configurable: true
+	});
+}
+/** Do this controller's write methods dispatch declared write verbs? */
+function isWriteVerbCapable(controller) {
+	return typeof controller === "object" && controller !== null && Reflect.get(controller, ARC_WRITE_VERB_CAPABLE) === true;
+}
+/**
+* Which of `ops` did the host override?
+*
+* THE single implementation — the boot-fatal reachability check and the
+* field-protection warn both consume it, so they cannot disagree.
+*
+* Two shapes: a prototype method (found by walking to the capability-marked
+* prototype — every layer between is host-authored) and a class field / ctor
+* assignment (found by provenance, since arc owns an own-property for all
+* three regardless). Arc's own mixins define no write methods; a test pins it.
+*/
+function detectOverriddenWriteSlots(controller, ops) {
+	const instance = controller;
+	return ops.filter((op) => {
+		if (typeof instance[op] === "function" && !isArcBoundWrite(instance[op])) return true;
+		let proto = Object.getPrototypeOf(controller);
+		while (proto && !Object.hasOwn(proto, ARC_WRITE_VERB_CAPABLE)) {
+			if (Object.hasOwn(proto, op)) return true;
+			proto = Object.getPrototypeOf(proto);
+		}
+		return false;
+	});
+}
+/**
 * Resolve the repository primary key for mutation calls.
 *
 * When the resource declares a custom `idField` (slug, jobId, UUID), the
@@ -634,23 +710,44 @@ const log = arcLog("query");
 */
 let notedDeniedJoins = false;
 function noteDeniedJoins(kind) {
-	if (notedDeniedJoins || process.env.NODE_ENV === "production") return;
+	if (notedDeniedJoins || isProductionEnv(process.env.NODE_ENV)) return;
 	notedDeniedJoins = true;
 	log.warn(`client requested ${kind} but no allowlist is configured — DENIED (2.24 default flip; it was allow-all). Set schemaOptions.query.allowedPopulate / allowedLookups to enable client-driven joins. (dev-only note, shown once)`);
 }
 var QueryResolver = class {
 	queryParser;
 	maxLimit;
+	/** Set only when the HOST passed one — it outranks any parser's cap, at any time. */
+	explicitMaxLimit;
 	defaultLimit;
 	/** `undefined` means "no default sort" (caller passed `false`). */
 	defaultSort;
+	explicitDefaultSort;
 	schemaOptions;
 	tenantField;
 	constructor(config = {}) {
 		this.queryParser = config.queryParser ?? getDefaultQueryParser();
-		this.maxLimit = config.maxLimit ?? 100;
+		/**
+		* Precedence: explicit config → the PARSER's own cap → framework default.
+		*
+		* The middle term is the fix. A resource that writes
+		* `new QueryParser({ maxLimit: 1000 })` has already answered "how large may a page
+		* be?", and arc previously ignored that and applied 100 anyway. Three layers each
+		* capping independently, lowest wins, no signal — a chart-of-accounts picker
+		* returned 100 of 696 rows and rendered "No accounts found", while the resource
+		* AND the repository were both configured for 1000.
+		*
+		* Note it reads `config.queryParser`, NOT `this.queryParser`. The fallback default
+		* parser declares its own generous cap, so deferring to it would silently raise the
+		* ceiling from 100 to 1000 on every endpoint that never configured one — a widening
+		* nobody asked for. Only a parser the resource EXPLICITLY supplied counts as an
+		* answer; a test pins exactly this.
+		*/
+		this.explicitMaxLimit = config.maxLimit;
+		this.maxLimit = config.maxLimit ?? config.queryParser?.maxLimit ?? 100;
 		this.defaultLimit = config.defaultLimit ?? 20;
 		this.defaultSort = config.defaultSort === false ? void 0 : config.defaultSort ?? "-createdAt";
+		this.explicitDefaultSort = config.defaultSort !== void 0 && config.defaultSort !== false;
 		this.schemaOptions = config.schemaOptions ?? {};
 		this.tenantField = config.tenantField !== void 0 ? config.tenantField : DEFAULT_TENANT_FIELD;
 	}
@@ -662,18 +759,88 @@ var QueryResolver = class {
 	*/
 	setParser(parser) {
 		this.queryParser = parser;
+		/**
+		* The swapped-in parser's cap applies too — swapping is how most resources supply
+		* theirs.
+		*
+		* Deferring only in the constructor was not enough: `setQueryParser()` mutates the
+		* resolver in place so captured references stay valid, so a resource that declares
+		* `new QueryParser({ maxLimit: 1000 })` arrives HERE, not through `config`. The
+		* constructor-only version of this fix looked right, passed its unit tests, and
+		* changed nothing at runtime — the chart of accounts still served 100 of 696.
+		*
+		* An explicit `config.maxLimit` still wins; that is a host decision and outranks a
+		* package default either way.
+		*/
+		if (this.explicitMaxLimit === void 0 && parser.maxLimit !== void 0) this.maxLimit = parser.maxLimit;
+	}
+	/**
+	* The default sort, but only when the parser permits the field.
+	*
+	* A resource declaring `allowedSortFields` has stated exactly what may be
+	* sorted on. Arc then applied its OWN default of `-createdAt` on top, and
+	* mongokit 3.31 REJECTS a sort outside the allowlist rather than dropping it —
+	* so every list call on such a resource answered 400, `Blocked sort field not
+	* in allowlist: createdAt`. REST and MCP alike; the endpoint was unusable, and
+	* nothing the caller sent could avoid it.
+	*
+	* A general default must never outrank a specific declaration, so the
+	* FRAMEWORK default withdraws. A HOST-declared `defaultSort` is left alone —
+	* that contradiction is its author's to resolve, and `defineResource` reports
+	* it as a boot diagnostic instead of arc silently picking a winner.
+	*/
+	permittedDefaultSort() {
+		const sort = this.defaultSort;
+		if (sort === void 0 || this.explicitDefaultSort) return sort;
+		const allowed = this.queryParser.allowedSortFields;
+		if (!allowed || allowed.length === 0) return sort;
+		return sort.split(",").map((s) => s.trim().replace(/^-/, "")).filter(Boolean).every((f) => allowed.includes(f)) ? sort : void 0;
 	}
 	/**
 	* Resolve a request into parsed query options -- ONE parse per request.
 	* Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
 	*/
 	resolve(req, meta) {
-		const parsed = this.queryParser.parse(req.query);
+		/**
+		* Strip `_policyFilters` BEFORE the parse, not after.
+		*
+		* **Reachable only when a CLIENT puts it in the URL.** Trusted policy is a
+		* request DECORATION (`request._policyFilters`, set by the permission
+		* middleware) that `createRequestContext` lifts into `metadata` — it never
+		* enters `req.query`, which is Fastify's parsed querystring. So the key
+		* arriving here is always user-supplied, always inert (the authoritative
+		* copy is read from `arcContext` below), and must simply not reach the
+		* parser.
+		*
+		* The previous `delete` ran on `parsed.filters` — AFTER
+		* `queryParser.parse()` — so on the one path that needed it, it could
+		* never run: a KIT parser validates every key against the resource's
+		* `allowedFilterFields` and throws during the parse, before the cleanup
+		* line. Arc's own parser skips the key via `RESERVED_QUERY_PARAMS`, so the
+		* two parsers disagreed on the same request: arc ignored a probe, kits
+		* 400'd it.
+		*
+		* Stripping here makes them agree, and agrees with arc. Nothing is
+		* weakened — the client's value was already inert — but note the trade:
+		* under a kit parser `?_policyFilters=…` used to be a loud 400 and is now
+		* silently dropped. The alternative, teaching every kit's reserved-key list
+		* about an arc-internal key, spreads one framework's leak across the
+		* ecosystem for the same outcome.
+		*
+		* Copy only when present: the hot path allocates nothing, and `req.query`
+		* is never mutated (it is shared with the rest of the request).
+		*/
+		const rawQuery = req.query;
+		let query = rawQuery;
+		if (rawQuery && "_policyFilters" in rawQuery) {
+			const { _policyFilters: _ignored, ...rest } = rawQuery;
+			query = rest;
+		}
+		const parsed = this.queryParser.parse(query);
 		const arcContext = meta ?? req.metadata;
-		delete parsed.filters?._policyFilters;
 		const limit = Math.min(Math.max(1, parsed.limit || this.defaultLimit), this.maxLimit);
 		const page = parsed.after ? void 0 : parsed.page ? Math.max(1, parsed.page) : 1;
-		const sortString = parsed.sort ? Object.entries(parsed.sort).map(([k, v]) => v === -1 ? `-${k}` : k).join(",") : this.defaultSort;
+		const sortString = parsed.sort ? Object.entries(parsed.sort).map(([k, v]) => v === -1 ? `-${k}` : k).join(",") : this.permittedDefaultSort();
 		const rawSelect = parsed.select ?? req.query?.select;
 		const policyFilters = arcContext?._policyFilters;
 		let filters = conjoinPolicyFilters(parsed.filters, policyFilters);
@@ -838,11 +1005,38 @@ var BaseCrudController = class {
 	*/
 	_defaultSort;
 	_onFieldWriteDenied;
+	_onImmutableWrite;
+	/**
+	* Domain commands bound to the write slots (`ResourceWrites`). Consulted at
+	* the PERSISTENCE step only — everything upstream of it (sanitizer, tenant
+	* injection, actor stamp, hook sandwich) runs exactly as it does without
+	* one, which is the entire point of the seam.
+	*/
+	_writes;
+	/** Transactional write envelope — see `ResourceConfig.transactional`. */
+	_transactional = false;
 	constructor(repository, options = {}) {
 		this.repository = repository;
 		this.schemaOptions = options.schemaOptions ?? {};
 		this.queryParser = options.queryParser ?? getDefaultQueryParser();
-		this.maxLimit = options.maxLimit ?? 100;
+		/**
+		* The parser's cap is consulted BEFORE the framework default.
+		*
+		* A resource that hands us a parser has already stated how large a page it
+		* can serve — a bounded catalog like a chart of accounts declares 1000 so
+		* pickers can read it whole. Defaulting straight to 100 here silently
+		* overrode that: the resource asked for 1000, `QueryResolver` received a
+		* `maxLimit` of 100 that was indistinguishable from a host deliberately
+		* choosing 100, and the list came back truncated with a `200`. be-prod
+		* served 100 of 696 accounts that way, and every account picker in the
+		* product was short by 85% with nothing anywhere to report it.
+		*
+		* Order matters and is the whole point: an explicit `options.maxLimit` from
+		* the host still wins over the parser, and the parser wins over this
+		* framework floor. A general default must only ever fill a gap — never
+		* outrank something specific that was actually stated.
+		*/
+		this.maxLimit = options.maxLimit ?? this.queryParser?.maxLimit ?? 100;
 		this.defaultLimit = options.defaultLimit ?? 20;
 		this.resourceName = options.resourceName;
 		this.tenantField = options.tenantField !== void 0 ? options.tenantField : DEFAULT_TENANT_FIELD;
@@ -852,6 +1046,9 @@ var BaseCrudController = class {
 		if (options.presetFields) this._presetFields = options.presetFields;
 		this._defaultSort = options.defaultSort;
 		this._onFieldWriteDenied = options.onFieldWriteDenied;
+		this._onImmutableWrite = options.onImmutableWrite;
+		this._writes = options.writes;
+		this._transactional = options.transactional === true;
 		this.accessControl = new AccessControl({
 			tenantField: this.tenantField,
 			idField: this.idField,
@@ -859,7 +1056,8 @@ var BaseCrudController = class {
 		});
 		this.bodySanitizer = new BodySanitizer({
 			schemaOptions: this.schemaOptions,
-			onFieldWriteDenied: this._onFieldWriteDenied
+			onFieldWriteDenied: this._onFieldWriteDenied,
+			onImmutableWrite: this._onImmutableWrite
 		});
 		this.queryResolver = new QueryResolver({
 			queryParser: this.queryParser,
@@ -871,9 +1069,21 @@ var BaseCrudController = class {
 		});
 		this.list = this.list.bind(this);
 		this.get = this.get.bind(this);
-		this.create = this.create.bind(this);
-		this.update = this.update.bind(this);
-		this.delete = this.delete.bind(this);
+		/**
+		* The write methods are bound here, which means EVERY instance carries an
+		* own `create`/`update`/`delete` property — so "does it have an own
+		* property" cannot distinguish arc's binding from a host's override.
+		*
+		* Marking what arc installed makes the difference observable. A class-field
+		* override (`update = async (req) => …`) initialises AFTER `super()`
+		* returns and therefore REPLACES this bound method outright — the mark goes
+		* with it, which is exactly the signal `warnOnWriteMethodOverride` needs.
+		* A prototype-method override binds through here and stays marked; that
+		* shape is caught by the prototype comparison instead.
+		*/
+		this.create = markArcBoundWrite(this.create.bind(this));
+		this.update = markArcBoundWrite(this.update.bind(this));
+		this.delete = markArcBoundWrite(this.delete.bind(this));
 	}
 	/**
 	* Swap the controller's query parser. Mutates the existing `QueryResolver`
@@ -939,6 +1149,10 @@ var BaseCrudController = class {
 			rebuildBodySanitizer = true;
 			rebuildQueryResolver = true;
 		}
+		if (options.onImmutableWrite !== void 0) {
+			this._onImmutableWrite = options.onImmutableWrite;
+			rebuildBodySanitizer = true;
+		}
 		if (options.onFieldWriteDenied !== void 0) {
 			this._onFieldWriteDenied = options.onFieldWriteDenied;
 			rebuildBodySanitizer = true;
@@ -958,6 +1172,8 @@ var BaseCrudController = class {
 		}
 		if (options.cache !== void 0) this._cacheConfig = options.cache;
 		if (options.presetFields !== void 0) this._presetFields = options.presetFields;
+		if (options.writes !== void 0) this._writes = options.writes;
+		if (options.transactional !== void 0) this._transactional = options.transactional === true;
 		if (rebuildAccessControl) this.accessControl = new AccessControl({
 			tenantField: this.tenantField,
 			idField: this.idField,
@@ -965,7 +1181,8 @@ var BaseCrudController = class {
 		});
 		if (rebuildBodySanitizer) this.bodySanitizer = new BodySanitizer({
 			schemaOptions: this.schemaOptions,
-			onFieldWriteDenied: this._onFieldWriteDenied
+			onFieldWriteDenied: this._onFieldWriteDenied,
+			onImmutableWrite: this._onImmutableWrite
 		});
 		if (rebuildQueryResolver) this.queryResolver = new QueryResolver({
 			queryParser: this.queryParser,
@@ -1105,6 +1322,52 @@ var BaseCrudController = class {
 		return executeHookedOp(this.hookOpContext(req), args, executor);
 	}
 	/**
+	* Run a write's PERSISTENCE step, transactionally when the resource asked.
+	*
+	* Plain mode hands `fn` the live repository. Transactional mode runs it
+	* through repo-core's `retryingTransaction`: the callback receives the
+	* TX-BOUND repository (so declared verbs and repository calls join the same
+	* transaction), transient conflicts re-run `fn` with jittered bounded
+	* backoff, everything else — including `VersionConflictError` — surfaces
+	* once. Hooks stay OUTSIDE: before/around ran already and must not re-run;
+	* after-hooks run post-commit, which they already do by running after this.
+	*/
+	runWritePersistence(fn) {
+		if (!this._transactional) return fn(this.repository);
+		return retryingTransaction(this.repository, (txRepo, uow) => fn(txRepo, uow));
+	}
+	/** Assemble the `WriteContext` a `create` verb receives. */
+	writeContext(req, repo = this.repository, uow) {
+		return {
+			req,
+			repository: repo,
+			...uow !== void 0 ? { uow } : {}
+		};
+	}
+	/**
+	* Assemble the `MutationWriteContext` an `update` / `delete` verb receives.
+	*
+	* `existing` is the document arc ALREADY loaded to run its permission and
+	* tenant checks — `loadMutableTarget` throws before any verb runs when it
+	* cannot produce one, which is why the context types it required. Handing
+	* it over rather than letting the verb re-fetch is deliberate: a second
+	* read can observe a different document than the one the request was
+	* authorised against.
+	*
+	* `id` is the REPOSITORY PRIMARY KEY (`repoId`), never the raw route param —
+	* see the note on `MutationWriteContext.id`. Callers pass `resolveRepoId`'s
+	* output.
+	*/
+	mutationWriteContext(req, id, existing, repo = this.repository, uow) {
+		return {
+			req,
+			repository: repo,
+			id,
+			existing,
+			...uow !== void 0 ? { uow } : {}
+		};
+	}
+	/**
 	* Run `executeAfter` for the given op + data. No-op when hooks aren't
 	* wired or `resourceName` isn't set. Caller passes the data shape it
 	* wants downstream after-handlers to receive — typically the result for
@@ -1340,11 +1603,21 @@ var BaseCrudController = class {
 		const item = await this.runHookedOpUntilResult(req, {
 			op: "create",
 			input: data
-		}, async (processed) => this.repository.create(processed, {
+		}, async (processed) => this.runWritePersistence((repo, uow) => this._writes?.create ? this._writes.create(processed, this.writeContext(req, repo, uow)) : repo.create(processed, {
 			user,
 			context: arcContext,
 			...this.tenantRepoOptions(req)
-		}));
+		})));
+		/**
+		* A create COMMAND must return the created document — enforced, because
+		* the alternative is quietly worse than any failure: a `201` carrying
+		* `undefined` data, after-hooks (audit, events, cache invalidation) fed a
+		* non-document, and a client that believes the write happened with no way
+		* to address what it created. TypeScript types the contract, but arc is a
+		* JavaScript runtime framework and a JS command returning nothing is one
+		* missing `return` away.
+		*/
+		if (this._writes?.create && item == null) throw createError(500, `writes.create for resource "${this.resourceName ?? "unknown"}" returned ${item === null ? "null" : "undefined"} — a create command must return the created document. Signal failure by throwing a typed error; a nullish return would otherwise answer 201 with no document.`, { code: "WRITE_VERB_CONTRACT_VIOLATION" });
 		await this.runAfterHook(req, "create", item);
 		return {
 			data: item,
@@ -1367,15 +1640,27 @@ var BaseCrudController = class {
 			op: "update",
 			input: data,
 			meta: hookMeta
-		}, async (processed) => this.repository.update(repoId, processed, {
+		}, async (processed) => this.runWritePersistence((repo, uow) => this._writes?.update ? this._writes.update(repoId, processed, this.mutationWriteContext(req, repoId, existing, repo, uow)) : repo.update(repoId, processed, {
 			user,
 			context: arcContext,
 			...this.tenantRepoOptions(req)
-		}));
-		if (!item) this.throwNotFound("NOT_FOUND");
-		await this.runAfterHook(req, "update", item, hookMeta);
+		})));
+		/**
+		* A declared verb signals "not found" by THROWING, so reaching this line
+		* means the command succeeded. Translating its `void` return into a 404
+		* would report failure for a write that happened — the repository's
+		* `null`-means-miss contract is the repository's, not a domain command's.
+		* Re-read so the response still carries the document.
+		*/
+		const resolved = this._writes?.update ? item ?? await this.repository.getById(repoId, {
+			user,
+			context: arcContext,
+			...this.tenantRepoOptions(req)
+		}) : item;
+		if (!resolved) this.throwNotFound("NOT_FOUND");
+		await this.runAfterHook(req, "update", resolved, hookMeta);
 		return {
-			data: item,
+			data: resolved,
 			status: 200,
 			meta: { message: "Updated successfully" }
 		};
@@ -1391,15 +1676,15 @@ var BaseCrudController = class {
 			input: existing,
 			meta: hookMeta,
 			pipeProcessedData: false
-		}, async () => this.repository.delete(repoId, {
+		}, async () => this.runWritePersistence((repo, uow) => this._writes?.delete ? this._writes.delete(repoId, this.mutationWriteContext(req, repoId, existing, repo, uow)) : repo.delete(repoId, {
 			user,
 			context: arcContext,
 			...this.tenantRepoOptions(req),
 			...deleteMode ? { mode: deleteMode } : {}
-		}));
-		if (!result) this.throwNotFound("NOT_FOUND");
+		})));
+		if (!result && !this._writes?.delete) this.throwNotFound("NOT_FOUND");
 		await this.runAfterHook(req, "delete", existing, hookMeta);
-		const deleteResult = result;
+		const deleteResult = result ?? {};
 		return {
 			data: {
 				message: deleteResult.message || "Deleted successfully",
@@ -1410,6 +1695,15 @@ var BaseCrudController = class {
 		};
 	}
 };
+/**
+* This class's write methods dispatch declared write verbs (`_writes`), so
+* `defineResource` may accept a `writes` declaration for controllers built on
+* it. One mark on the prototype — inherited by every subclass and mixin
+* composition, zero per-instance cost. A duck-typed `configure()` is NOT this
+* proof: it shows an options channel exists, not that anything dispatches
+* `writes` out of it.
+*/
+markWriteVerbCapable(BaseCrudController.prototype);
 //#endregion
 //#region src/core/mixins/bulk.ts
 /**
@@ -1752,4 +2046,4 @@ function TreeMixin(Base) {
 */
 var BaseController = class extends SoftDeleteMixin(TreeMixin(SlugMixin(BulkMixin(BaseCrudController)))) {};
 //#endregion
-export { BulkMixin as a, collectReadBlockedFields as c, DEFAULT_FIELD_WRITE_DENIAL_POLICY as d, AccessControl as f, SlugMixin as i, isFieldReadable as l, TreeMixin as n, BaseCrudController as o, SoftDeleteMixin as r, QueryResolver as s, BaseController as t, BodySanitizer as u };
+export { BulkMixin as a, collectReadBlockedFields as c, isWriteVerbCapable as d, BodySanitizer as f, SlugMixin as i, isFieldReadable as l, AccessControl as m, TreeMixin as n, BaseCrudController as o, DEFAULT_FIELD_WRITE_DENIAL_POLICY as p, SoftDeleteMixin as r, QueryResolver as s, BaseController as t, detectOverriddenWriteSlots as u };

package/dist/{EventTransport-2uVV34WU.d.mts → EventTransport-BEVP50ka.d.mts}

@@ -4,6 +4,21 @@ import { DeadLetteredEvent, DomainEvent, DomainEvent as DomainEvent$1, EventHand
 interface MemoryEventTransportOptions {
   /** Logger for error/warning messages (default: console) */
   logger?: EventLogger;
+  /**
+   * What a THROWING subscriber does to `publish()`.
+   *
+   * - `'log'` (default) — logged, `publish()` still resolves. The
+   *   fire-and-forget bus contract: one broken analytics subscriber must not
+   *   fail a publisher's request.
+   * - `'throw'` — REJECTS with an `AggregateError` after running every
+   *   handler. Required for at-least-once PROCESSING: with this transport
+   *   `publish()` IS the handling, so a swallowed error reads to an outbox
+   *   relay as delivery and the row is acknowledged, never retried.
+   *
+   * Retry redelivers to ALL matching handlers (no per-handler cursor), so
+   * handlers must be idempotent. Every handler runs before the rejection.
+   */
+  onHandlerError?: "log" | "throw";
 }
 /**
  * In-memory event transport (default).
@@ -16,6 +31,7 @@ declare class MemoryEventTransport implements EventTransport {
   readonly name = "memory";
   private handlers;
   private logger;
+  private onHandlerError;
   constructor(options?: MemoryEventTransportOptions);
   publish(event: DomainEvent): Promise<void>;
   /**

package/dist/{EventTransport-BV10D0oG.mjs → EventTransport-tq4CEB-q.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
 import { createEvent, matchEventPattern } from "@classytic/primitives/events";
 //#region src/events/EventTransport.ts
 /**
@@ -45,6 +45,29 @@ import { createEvent, matchEventPattern } from "@classytic/primitives/events";
 * public `events/index.ts` barrel stays clean.
 */
 /**
+* Decorator key holding the RAW `EventTransport` an app registered.
+*
+* `fastify.events` is a request-facing FACADE — different signature
+* (`publish(type, payload, meta?)`) and fail-open by design — so machinery
+* that must observe publish failure (the outbox relay) resolves the transport
+* through this key instead. `Symbol.for` so it still matches across two arc
+* copies in one dependency graph; deliberately NOT on the public
+* `EventsDecorator` surface.
+*/
+const ARC_EVENT_TRANSPORT = Symbol.for("arc.eventTransport");
+/**
+* Read the raw transport an app registered, or `undefined` when the events
+* plugin was never registered (or predates this key).
+*
+* Callers decide what absence means: the outbox treats it as "no transport",
+* which is a boot-time error rather than a silent no-op relay.
+*/
+function resolveEventTransport(fastify) {
+	if (typeof fastify !== "object" || fastify === null) return void 0;
+	const found = Reflect.get(fastify, ARC_EVENT_TRANSPORT);
+	return typeof found === "object" && found !== null ? found : void 0;
+}
+/**
 * In-memory event transport (default).
 *
 * Events are delivered synchronously within the process. Not suitable for
@@ -55,17 +78,31 @@ var MemoryEventTransport = class {
 	name = "memory";
 	handlers = /* @__PURE__ */ new Map();
 	logger;
+	onHandlerError;
 	constructor(options) {
 		this.logger = options?.logger ?? console;
+		this.onHandlerError = options?.onHandlerError ?? "log";
 	}
 	async publish(event) {
 		const allHandlers = /* @__PURE__ */ new Set();
 		for (const [pattern, handlers] of this.handlers) if (matchEventPattern(pattern, event.type)) for (const h of handlers) allHandlers.add(h);
+		const failures = [];
 		for (const handler of allHandlers) try {
 			await handler(event);
 		} catch (err) {
 			this.logger.error(`[EventTransport] Handler error for ${event.type}:`, err);
+			failures.push(err);
 		}
+		/**
+		* Rejecting is what lets an OUTBOX see the failure. With this transport,
+		* `publish()` IS the handling — synchronous and in-process — so resolving
+		* after a handler threw tells the relay the event was delivered, and the
+		* row is acknowledged and never retried. Measured: handler throws once,
+		* `relayBatch()` reports `relayed: 1, publishFailed: 0`, and the next tick
+		* finds nothing. A broker-backed transport has no such ambiguity — publish
+		* means "durably handed off" and redelivery is the consumer group's job.
+		*/
+		if (failures.length > 0 && this.onHandlerError === "throw") throw new AggregateError(failures, `[EventTransport] ${failures.length} handler(s) failed for ${event.type}`);
 	}
 	/**
 	* Reference `publishMany` implementation — delegates to `publish()` in order.
@@ -101,4 +138,4 @@ var MemoryEventTransport = class {
 	}
 };
 //#endregion
-export { createEvent as n, MemoryEventTransport as t };
+export { resolveEventTransport as i, MemoryEventTransport as n, createEvent as r, ARC_EVENT_TRANSPORT as t };

package/dist/{HookSystem-vimw5D7Z.mjs → HookSystem-DqXkMXkB.mjs}

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import { t as buildRequestScopeProjection } from "./projection-CjHhM5W1.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { t as buildRequestScopeProjection } from "./projection-BKM0Ui-s.mjs";
 //#region src/hooks/HookSystem.ts
 /**
 * Hook System

package/dist/{ResourceRegistry-BVr7PgA0.mjs → ResourceRegistry-DoALUlOO.mjs}

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import "./constants-J99LGTJI.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import "./constants-BxCoxmiN.mjs";
 //#region src/registry/ResourceRegistry.ts
 /**
 * Resource Registry
@@ -60,6 +60,7 @@ var ResourceRegistry = class {
 				summary: r.summary,
 				description: r.description,
 				permissions: r.permissions,
+				capability: r.capability,
 				raw: r.rawHandler !== void 0,
 				schema: r.schema
 			})),

package/dist/{actionPermissions-Dti7ebyv.mjs → actionPermissions-CUeCmpUd.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
 //#region src/core/actionPermissions.ts
 /**
 * Return the effective `PermissionCheck` for a single action, or `undefined`