@classytic/arc 2.32.0 → 2.33.0

package/README.md

@@ -147,7 +147,7 @@ defineResource({
 defineResource({ name: 'pipeline', adapter, defaultLimit: 200, maxLimit: 500 });
 ```
 
-`?limit=` violations respond 400 with a cap-aware envelope: `message: "Query parameter 'limit' must be <= 500 (got 800) (cap is 500)"` plus `meta: { field: 'limit', cap: 500 }` so callers can self-correct without scraping the message.
+A `?limit=` above the cap is **clamped to it** and served, not rejected (changed in 2.33). Rejecting made the documented clamp unreachable and turned a benign over-ask into a 400 that callers commonly render as an empty list. The effective cap is carried in the OpenAPI parameter description, and the response's own `limit` reports what was applied.
 
 ---
 

package/bin/arc.js

@@ -42,17 +42,11 @@ const VERSION = getPackageVersion();
 
 const args = process.argv.slice(2);
 
-// Version flag
-if (args.includes('--version') || args.includes('-v')) {
-  console.log(`Arc CLI v${VERSION}`);
-  process.exit(0);
-}
-
-// Help flag or no args
-if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
-  printHelp();
-  process.exit(0);
-}
+// Version / help are GLOBAL only in the leading position. Scanning the whole
+// argv made `arc init --help` print the global help and exit, which left the
+// per-command usage in COMMAND_HELP unreachable — a user asking how to use
+// one command got the manual for all of them.
+const leading = args[0];
 
 // ============================================================================
 // Command Routing
@@ -64,7 +58,7 @@ const [command, subcommand, ...rest] = args;
 // through to the command (where `--help` was mistaken for an argument).
 const COMMAND_ALIASES = { new: 'init', g: 'generate', i: 'introspect', desc: 'describe', d: 'docs' };
 const COMMAND_HELP = {
-  init: 'Usage: arc init [name] [--jwt|--better-auth] [--mongokit|--custom] [--api-key]\n            [--multi|--single] [--js] [--edge] [--docker|--no-docker] [--skip-install] [--force]\n  Scaffold a new arc project (prompts when run in a TTY without a name).',
+  init: 'Usage: arc init [name] [--jwt|--better-auth] [--mongokit|--custom] [--api-key|--no-api-key] [--session cookie|bearer|both]\n            [--multi|--single] [--js] [--edge] [--docker|--no-docker] [--skip-install] [--force]\n  Scaffold a new arc project (prompts when run in a TTY without a name).',
   generate: 'Usage: arc generate <resource|controller|model|repository|schemas|mcp> <name> [--mcp]\n  Aliases: g; types r/c/m/repo/s. Name must be kebab-case (letters, digits, hyphens).',
   introspect: 'Usage: arc introspect <entry-file>\n  Print a human-readable summary of the resources an entry file exports.',
   describe: 'Usage: arc describe <entry-file> [--json] [--pretty] [--entry <file>]\n  Describe resources; --json emits machine output for AI agents.',
@@ -72,8 +66,27 @@ const COMMAND_HELP = {
   doctor: 'Usage: arc doctor\n  Diagnose common arc setup issues (exit 1 on hard failures).',
 };
 
+/**
+ * `process.exitCode` + return, never `process.exit()`.
+ *
+ * `process.exit()` tears the process down immediately; on POSIX a `stdout`
+ * that is a PIPE (`arc --help | less`, `arc describe --json > out.json`)
+ * writes asynchronously, so an exit racing the flush TRUNCATES output. Arc's
+ * own `doctor` already sets `exitCode`; this file is the one that did not.
+ * Setting the code and returning lets Node drain stdout and exit on its own.
+ */
 async function main() {
   try {
+    // Global help/version are the LEADING argument only — see `leading`.
+    if (leading === '--version' || leading === '-v') {
+      console.log(`Arc CLI v${VERSION}`);
+      return;
+    }
+    if (args.length === 0 || leading === '--help' || leading === '-h') {
+      printHelp();
+      return;
+    }
+
     // `arc <command> --help` / `-h` → command-specific usage, exit 0.
     const canonicalCommand = COMMAND_ALIASES[command] ?? command;
     if (
@@ -117,7 +130,8 @@ async function main() {
       default:
         console.error(`Unknown command: ${command}`);
         console.error('Run "arc --help" for usage');
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -125,7 +139,7 @@ async function main() {
     if (process.env.DEBUG) {
       console.error(err instanceof Error ? err.stack : err);
     }
-    process.exit(1);
+    process.exitCode = 1;
   }
 }
 
@@ -148,7 +162,8 @@ async function handleGenerate(type, args) {
     console.log('  arc generate resource product --mcp');
     console.log('  arc generate mcp product');
     console.log('  arc g r invoice');
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
 
   // Normalize type shortcuts
@@ -170,14 +185,16 @@ async function handleGenerate(type, args) {
   if (!normalizedType) {
     console.error(`Unknown type: ${type}`);
     console.log('Available types: resource (r), controller (c), model (m), repository (repo), schemas (s)');
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
 
   const name = args[0];
   if (!name) {
     console.error('Missing name argument');
     console.log(`\nUsage: arc generate ${normalizedType} <name>`);
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
 
   // Import and run
@@ -250,6 +267,11 @@ function parseInitOptions(rawArgs) {
     adapter: undefined,
     auth: undefined,
     tenant: undefined,
+    // Better Auth-specific. `undefined` (not a default) is load-bearing:
+    // options.ts prompts ONLY when the field is undefined, so defaulting
+    // here would silently skip the interactive question.
+    apiKey: undefined,
+    session: undefined,
     typescript: undefined,
     edge: undefined,
     skipInstall: false,
@@ -309,6 +331,21 @@ function parseInitOptions(rawArgs) {
         opts.auth = 'jwt';
         break;
 
+      case '--api-key':
+        opts.apiKey = true;
+        break;
+
+      case '--no-api-key':
+        opts.apiKey = false;
+        break;
+
+      case '--session':
+        // cookie | bearer | both — options.ts falls back to the documented
+        // default for anything else.
+        opts.session = next;
+        i++;
+        break;
+
       case '--edge':
       case '--serverless':
         opts.edge = true;
@@ -380,6 +417,7 @@ GLOBAL OPTIONS
   --help, -h               Show this help
 
 INIT OPTIONS
+  --name, -n <name>        Project name (alternative to the positional argument)
   --mongokit               Use MongoKit adapter (default, recommended)
   --custom                 Use custom / Drizzle-ready adapter template
   --better-auth            Use Better Auth (default, recommended)
@@ -388,6 +426,9 @@ INIT OPTIONS
   --single-tenant, --single Single-tenant mode (default)
   --ts, --typescript       Generate TypeScript (default)
   --js, --javascript       Generate JavaScript
+  --api-key                Enable Better Auth's apiKey plugin (machine-to-machine)
+  --no-api-key             Skip it without being prompted
+  --session <mode>         Better Auth session strategy: cookie | bearer | both
   --edge, --serverless     Target Edge/Serverless environments
   --docker                 Emit Dockerfile + docker-compose.yml (opt-in, 2.16)
   --no-docker              Skip Docker scaffolding even in interactive mode

package/dist/{BaseController-Dk34dxhI.mjs → BaseController-CaQC5EXX.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-B3mP_QTy.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 { t as toRepositoryFilter } from "./repositoryFilter-DKny7PDn.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,6 +759,42 @@ 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.
@@ -673,7 +806,7 @@ var QueryResolver = class {
 		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 +971,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 +1012,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 +1022,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 +1035,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 +1115,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 +1138,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 +1147,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 +1288,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 +1569,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 +1606,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 +1642,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 +1661,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 +2012,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 };