@classytic/repo-core 0.28.0 → 0.30.0

package/dist/cache/engine.d.mts

@@ -55,13 +55,13 @@ declare class CacheEngine {
   private readonly prefix;
   private readonly jitter;
   /**
-   * In-flight fetches keyed by cache-key. Process-local (lives in this
-   * engine instance) — server restart clears it; cross-pod fanout is
-   * fine because each pod runs its own single-flight, and downstream
-   * load is bounded to N-pods worst case (a huge improvement over
-   * unbounded burst).
+   * In-flight fetches, partitioned by the RESOLVED adapter, then keyed by cache-key. A scoped store
+   * (per request, per job) gets its own partition, so two scopes reading the same key never share a
+   * result — and a finished scope's partition is collected with its store. Process-local; cross-pod
+   * fanout is bounded to N pods.
    */
   private readonly pending;
+  private pendingTotal;
   constructor(adapter: CacheAdapterSource, options?: CacheEngineOptions);
   /**
    * Read a cache entry under SWR + TTL semantics. Returns a
@@ -91,6 +91,8 @@ declare class CacheEngine {
    * pending.
    */
   getPending<T = unknown>(key: string): Promise<T> | undefined;
+  /** This scope's in-flight partition; `undefined` when no store is in scope (never coalesce there). */
+  private pendingIn;
   /**
    * Atomically claim `key` for a fetch. Returns `'claimed'` when this
    * caller owns the fetch (it must call `resolvePending` or

package/dist/cache/engine.mjs

@@ -35,13 +35,13 @@ var CacheEngine = class {
 	prefix;
 	jitter;
 	/**
-	* In-flight fetches keyed by cache-key. Process-local (lives in this
-	* engine instance) — server restart clears it; cross-pod fanout is
-	* fine because each pod runs its own single-flight, and downstream
-	* load is bounded to N-pods worst case (a huge improvement over
-	* unbounded burst).
+	* In-flight fetches, partitioned by the RESOLVED adapter, then keyed by cache-key. A scoped store
+	* (per request, per job) gets its own partition, so two scopes reading the same key never share a
+	* result — and a finished scope's partition is collected with its store. Process-local; cross-pod
+	* fanout is bounded to N pods.
 	*/
-	pending = /* @__PURE__ */ new Map();
+	pending = /* @__PURE__ */ new WeakMap();
+	pendingTotal = 0;
 	constructor(adapter, options = {}) {
 		this.resolveAdapter = typeof adapter === "function" ? adapter : () => adapter;
 		this.prefix = options.prefix ?? "rc";
@@ -125,7 +125,18 @@ var CacheEngine = class {
 	* pending.
 	*/
 	getPending(key) {
-		return this.pending.get(key)?.promise;
+		return this.pendingIn(false)?.get(key)?.promise;
+	}
+	/** This scope's in-flight partition; `undefined` when no store is in scope (never coalesce there). */
+	pendingIn(create) {
+		const adapter = this.resolveAdapter();
+		if (!adapter) return void 0;
+		let partition = this.pending.get(adapter);
+		if (!partition && create) {
+			partition = /* @__PURE__ */ new Map();
+			this.pending.set(adapter, partition);
+		}
+		return partition;
 	}
 	/**
 	* Atomically claim `key` for a fetch. Returns `'claimed'` when this
@@ -135,21 +146,26 @@ var CacheEngine = class {
 	* with the first claimer's result.
 	*/
 	claimPending(key) {
-		const existing = this.pending.get(key);
+		const partition = this.pendingIn(true);
+		if (!partition) return { status: "claimed" };
+		const existing = partition.get(key);
 		if (existing) return {
 			status: "wait",
 			promise: existing.promise
 		};
 		const deferred = Promise.withResolvers();
 		deferred.promise.catch(() => {});
-		this.pending.set(key, deferred);
+		partition.set(key, deferred);
+		this.pendingTotal += 1;
 		return { status: "claimed" };
 	}
 	/** Resolve an in-flight claim with the fresh result + clear it. */
 	resolvePending(key, value) {
-		const deferred = this.pending.get(key);
-		if (!deferred) return;
-		this.pending.delete(key);
+		const partition = this.pendingIn(false);
+		const deferred = partition?.get(key);
+		if (!partition || !deferred) return;
+		partition.delete(key);
+		this.pendingTotal -= 1;
 		deferred.resolve(value);
 	}
 	/**
@@ -158,14 +174,16 @@ var CacheEngine = class {
 	* whether to retry on a higher level.
 	*/
 	rejectPending(key, error) {
-		const deferred = this.pending.get(key);
-		if (!deferred) return;
-		this.pending.delete(key);
+		const partition = this.pendingIn(false);
+		const deferred = partition?.get(key);
+		if (!partition || !deferred) return;
+		partition.delete(key);
+		this.pendingTotal -= 1;
 		deferred.reject(error);
 	}
 	/** Internal — number of in-flight fetches; observability hook. */
 	get pendingCount() {
-		return this.pending.size;
+		return this.pendingTotal;
 	}
 	/**
 	* Invalidate every entry tagged with ANY of the provided tags. Reads

package/dist/cache/memo.d.mts

@@ -7,6 +7,10 @@
  * only ever helped the caller after them. This is `CacheEngine.prefetch` over
  * the memory adapter: concurrent misses share one load, a thrown load caches
  * nothing, and a `null` result is an answer.
+ *
+ * `invalidate` is FENCED by a generation in the slot key: a load already in flight writes to the
+ * superseded slot, which nothing reads, so it can never repopulate the memo after an invalidation
+ * — and a `get` after the invalidation never joins that load either.
  */
 interface TtlMemoOptions<K> {
   /** Freshness window. `0` disables memoisation — every call loads. */

package/dist/cache/memo.mjs

@@ -9,6 +9,10 @@ import { createMemoryCacheAdapter } from "./memory-adapter.mjs";
 * only ever helped the caller after them. This is `CacheEngine.prefetch` over
 * the memory adapter: concurrent misses share one load, a thrown load caches
 * nothing, and a `null` result is an answer.
+*
+* `invalidate` is FENCED by a generation in the slot key: a load already in flight writes to the
+* superseded slot, which nothing reads, so it can never repopulate the memo after an invalidation
+* — and a `get` after the invalidation never joins that load either.
 */
 const PREFIX = "memo";
 function createTtlMemo(load, options) {
@@ -23,6 +27,11 @@ function createTtlMemo(load, options) {
 		swr: false,
 		enabled: ttlMs > 0
 	};
+	const limit = maxEntries ?? 1e4;
+	/** Bumped by a full `invalidate()`; per-key generations exist only for keys invalidated since. */
+	let epoch = 0;
+	const generations = /* @__PURE__ */ new Map();
+	const slot = (base) => `${base}#${epoch}.${generations.get(base) ?? 0}`;
 	const toKey = (key) => {
 		if (keyOf) return `${PREFIX}:${keyOf(key)}`;
 		const t = typeof key;
@@ -31,15 +40,19 @@ function createTtlMemo(load, options) {
 	};
 	return {
 		get(key) {
-			const k = toKey(key);
-			return engine.prefetch(k, resolved, () => load(key));
+			return engine.prefetch(slot(toKey(key)), resolved, () => load(key));
 		},
 		async invalidate(key) {
-			if (key === void 0) {
+			if (key === void 0 || generations.size >= limit) {
+				epoch += 1;
+				generations.clear();
 				await engine.clear();
 				return;
 			}
-			await adapter.delete(toKey(key));
+			const base = toKey(key);
+			const superseded = slot(base);
+			generations.set(base, (generations.get(base) ?? 0) + 1);
+			await adapter.delete(superseded);
 		}
 	};
 }

package/dist/cache/memory-adapter.mjs

@@ -62,13 +62,15 @@ function createMemoryCacheAdapter(options = {}) {
 		addToSet(key, members, ttlSeconds = 60) {
 			const existing = readUnexpired(key);
 			let set;
-			if (existing && existing.value instanceof Set) set = existing.value;
-			else {
+			const expiry = ttlSeconds === 0 ? 0 : now() + ttlSeconds * 1e3;
+			if (existing && existing.value instanceof Set) {
+				set = existing.value;
+				if (existing.expiresAt !== 0 && (expiry === 0 || expiry > existing.expiresAt)) existing.expiresAt = expiry;
+			} else {
 				set = /* @__PURE__ */ new Set();
-				const expiresAt = existing?.expiresAt ?? (ttlSeconds === 0 ? 0 : now() + ttlSeconds * 1e3);
 				store.set(key, {
 					value: set,
-					expiresAt
+					expiresAt: expiry
 				});
 				evictIfNeeded();
 			}

package/dist/cache/plugin/read-hooks.mjs

@@ -42,7 +42,7 @@ function registerBefore(op, engine, hookCtx) {
 			return;
 		}
 		hookCtx.log.onMiss?.(key, op);
-		if (resolved.bypass) return;
+		if (resolved.bypass || result.status === "disabled") return;
 		const claim = engine.claimPending(key);
 		if (claim.status === "wait") try {
 			const data = await claim.promise;

package/dist/cache/stable-stringify.d.mts

@@ -1,14 +1,13 @@
 //#region src/cache/stable-stringify.d.ts
 /**
- * Deterministic JSON stringify — equivalent values produce identical output.
+ * Deterministic JSON stringify — equivalent values produce identical output, different values
+ * never do. Every cache key and `contentHash` is built on it.
  *
- * Used by kits that build cache keys from hook contexts so
- * `{ b: 1, a: 2 }` and `{ a: 2, b: 1 }` hash to the same bucket. Arrays
- * preserve order (order is part of array identity).
- *
- * Extracted from the mongokit / sqlitekit cache plugins into repo-core so
- * every kit's cachePlugin uses the same keying rule — cross-kit caches
- * remain bucket-compatible.
+ * WIRE semantics, so a value built in memory serialises like the same value after a JSON round
+ * trip: `toJSON` is applied (a `Date` is its ISO string, an ObjectId its hex), an `undefined`
+ * property is absent and an `undefined` array slot is `null`. A `RegExp` — which JSON would render
+ * `{}`, colliding every pattern — is `{"$regex","$options"}`. Keys sort by code unit, never by
+ * locale: a key that moves with the server's ICU data changes every digest. Arrays keep order.
  */
 declare function stableStringify(value: unknown): string;
 //#endregion

package/dist/cache/stable-stringify.mjs

@@ -1,19 +1,22 @@
 //#region src/cache/stable-stringify.ts
 /**
-* Deterministic JSON stringify — equivalent values produce identical output.
+* Deterministic JSON stringify — equivalent values produce identical output, different values
+* never do. Every cache key and `contentHash` is built on it.
 *
-* Used by kits that build cache keys from hook contexts so
-* `{ b: 1, a: 2 }` and `{ a: 2, b: 1 }` hash to the same bucket. Arrays
-* preserve order (order is part of array identity).
-*
-* Extracted from the mongokit / sqlitekit cache plugins into repo-core so
-* every kit's cachePlugin uses the same keying rule — cross-kit caches
-* remain bucket-compatible.
+* WIRE semantics, so a value built in memory serialises like the same value after a JSON round
+* trip: `toJSON` is applied (a `Date` is its ISO string, an ObjectId its hex), an `undefined`
+* property is absent and an `undefined` array slot is `null`. A `RegExp` — which JSON would render
+* `{}`, colliding every pattern — is `{"$regex","$options"}`. Keys sort by code unit, never by
+* locale: a key that moves with the server's ICU data changes every digest. Arrays keep order.
 */
 function stableStringify(value) {
-	if (value === null || typeof value !== "object") return JSON.stringify(value);
-	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
-	return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (value instanceof RegExp) return `{"$options":${JSON.stringify(value.flags)},"$regex":${JSON.stringify(value.source)}}`;
+	const toJSON = value.toJSON;
+	if (typeof toJSON === "function") return stableStringify(toJSON.call(value));
+	if (Array.isArray(value)) return `[${value.map((v) => v === void 0 ? "null" : stableStringify(v)).join(",")}]`;
+	const record = value;
+	return `{${Object.keys(record).filter((k) => record[k] !== void 0).sort((a, b) => a < b ? -1 : a > b ? 1 : 0).map((k) => `${JSON.stringify(k)}:${stableStringify(record[k])}`).join(",")}}`;
 }
 //#endregion
 export { stableStringify };

package/dist/cache/tag-index.mjs

@@ -52,8 +52,7 @@ async function appendKeyToTags(adapter, prefix, cacheKey, tags, ttlSeconds) {
 		const idxKey = tagIndexKey(prefix, tag);
 		const existing = await adapter.get(idxKey);
 		const current = Array.isArray(existing) ? existing : [];
-		if (current.includes(cacheKey)) return;
-		const next = [...current, cacheKey];
+		const next = current.includes(cacheKey) ? current : [...current, cacheKey];
 		await adapter.set(idxKey, next, indexTtl);
 	}));
 }

package/dist/cache/types.d.mts

@@ -66,13 +66,14 @@ interface CacheAdapter {
    * difference is the 178× slowdown the in-memory benchmark surfaced.
    *
    * **Implementation guidance:**
-   *   - Redis: `SADD key m1 m2 ...` + `EXPIRE key ttlSeconds NX`
+   *   - Redis: `SADD key m1 m2 ...` + `EXPIRE key ttlSeconds GT` (Redis ≥ 7; `NX` is wrong, see below)
    *   - Memory: in-place push on the underlying array (no copy)
    *   - DynamoDB: `UpdateItem` with `ADD` action on a String Set
    *   - Cloudflare KV / pure GET-SET stores: omit; engine falls back.
    *
-   * `ttlSeconds` is applied only when the key is created — existing
-   * sets keep their original expiry (Redis NX semantics).
+   * `ttlSeconds` EXTENDS the set's expiry and never shortens it (Redis `GT` semantics). A set used
+   * as a tag index must outlive its newest member; keeping the creation-time expiry lets the index
+   * vanish while members live on, and invalidating the tag then misses them.
    */
   addToSet?(key: string, members: readonly string[], ttlSeconds?: number): Promise<number> | number;
   /**

package/dist/errors/codes.d.mts

@@ -0,0 +1,117 @@
+//#region src/errors/codes.d.ts
+/**
+ * The error-code vocabulary of the wire — every value a client may see in
+ * `ErrorContract.code`, in one place.
+ *
+ * Codes live here, in the contract package, rather than in the servers that
+ * emit them: a client SDK consumes the wire vocabulary by depending on
+ * repo-core, never on the server framework. The emitting side proves it only
+ * uses catalogued codes (arc's test suite fails on an uncatalogued `arc.*`
+ * literal); the consuming side spreads these constants instead of copying
+ * strings, so an addition reaches every client with a repo-core bump.
+ *
+ * Three families:
+ *
+ *   - {@link ERROR_CODES} — cross-cutting, lowercase snake_case (RFC 7807 /
+ *     Stripe style). What {@link statusToErrorCode} derives and any
+ *     HTTP-emitting package may use.
+ *   - {@link ARC_ERROR_CODES} — arc's `arc.`-namespaced codes: the
+ *     status-derived family, request validation, auth, tenancy, idempotency,
+ *     capacity, and per-feature codes. Values are wire-stable — never renamed.
+ *   - {@link ARC_REASON_CODES} — UPPER_SNAKE business reasons arc's mixins put
+ *     on `code` alongside the HTTP status (why a bulk write was refused, …).
+ *
+ * `ErrorContract.code` stays `string`: domain packages extend hierarchically
+ * (`'order.validation.missing_line'`) without registering here.
+ */
+declare const ERROR_CODES: {
+  readonly VALIDATION: 'validation_error';
+  readonly NOT_FOUND: 'not_found';
+  readonly CONFLICT: 'conflict';
+  readonly UNAUTHORIZED: 'unauthorized';
+  readonly FORBIDDEN: 'forbidden';
+  readonly RATE_LIMITED: 'rate_limited';
+  readonly IDEMPOTENCY_CONFLICT: 'idempotency_conflict';
+  readonly PRECONDITION_FAILED: 'precondition_failed';
+  readonly INTERNAL: 'internal_error';
+  readonly UNAVAILABLE: 'service_unavailable';
+  readonly TIMEOUT: 'timeout';
+};
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+declare const ARC_ERROR_CODES: {
+  readonly ERROR: 'arc.error';
+  readonly BAD_REQUEST: 'arc.bad_request';
+  readonly UNAUTHORIZED: 'arc.unauthorized';
+  readonly FORBIDDEN: 'arc.forbidden';
+  readonly NOT_FOUND: 'arc.not_found';
+  readonly CONFLICT: 'arc.conflict';
+  readonly PAYLOAD_TOO_LARGE: 'arc.payload_too_large';
+  readonly UNSUPPORTED_MEDIA_TYPE: 'arc.unsupported_media_type';
+  readonly UNPROCESSABLE_ENTITY: 'arc.unprocessable_entity';
+  readonly RATE_LIMITED: 'arc.rate_limited';
+  readonly INTERNAL_ERROR: 'arc.internal_error';
+  readonly NOT_IMPLEMENTED: 'arc.not_implemented';
+  readonly BAD_GATEWAY: 'arc.bad_gateway';
+  readonly SERVICE_UNAVAILABLE: 'arc.service_unavailable';
+  readonly GATEWAY_TIMEOUT: 'arc.gateway_timeout';
+  readonly VALIDATION_ERROR: 'arc.validation_error';
+  readonly INVALID_ID: 'arc.invalid_id';
+  readonly INVALID_ACTION: 'arc.invalid_action';
+  readonly UNSUPPORTED_API_VERSION: 'arc.unsupported_api_version';
+  /** A stale `If-Match` — re-read the document (its `ETag`) and retry. HTTP 412. */
+  readonly PRECONDITION_FAILED: 'arc.precondition_failed';
+  readonly AUTH_INVALID_TOKEN_TYPE: 'arc.auth.invalid_token_type';
+  readonly AUTH_TOKEN_REVOKED: 'arc.auth.token_revoked';
+  readonly AUTH_REVOCATION_CHECK_FAILED: 'arc.auth.revocation_check_failed';
+  readonly AUTH_MISCONFIGURED: 'arc.auth.misconfigured';
+  /** HTTP 500 — the auth provider itself failed (not a bad credential). */
+  readonly AUTH_SERVICE_ERROR: 'arc.auth.service_error';
+  /** HTTP 401 — `x-arc-scope: platform` without an authenticated user. */
+  readonly ELEVATION_AUTH_REQUIRED: 'arc.elevation.auth_required';
+  /** HTTP 403 — `x-arc-scope: platform` from a user without a platform role. */
+  readonly ELEVATION_FORBIDDEN: 'arc.elevation.forbidden';
+  readonly ORG_SELECTION_REQUIRED: 'arc.org.selection_required';
+  readonly ORG_ACCESS_DENIED: 'arc.org.access_denied';
+  /** Convention for host tier gates; arc surfaces it verbatim with `{ requiredMode, currentMode }`. */
+  readonly TIER_REQUIRED: 'arc.tier_required';
+  /** HTTP 400 — the route requires an `Idempotency-Key`. */
+  readonly IDEMPOTENCY_KEY_REQUIRED: 'arc.idempotency_key_required';
+  /** HTTP 422 — the key already named an operation with a different body. */
+  readonly IDEMPOTENCY_KEY_REUSED: 'arc.idempotency_key_reused';
+  /** HTTP 400 — the body could not be fingerprinted (too deep). */
+  readonly IDEMPOTENCY_BODY_UNFINGERPRINTABLE: 'arc.idempotency_body_unfingerprintable';
+  /** HTTP 409 — the same key is still executing; retry after `Retry-After`. */
+  readonly IDEMPOTENCY_CONFLICT: 'arc.idempotency_conflict';
+  readonly CIRCUIT_OPEN: 'arc.circuit_open';
+  readonly UNAVAILABLE: 'arc.unavailable';
+  /** HTTP 500 — a host write verb broke its contract (e.g. `create` returned nothing). */
+  readonly WRITE_VERB_CONTRACT_VIOLATION: 'arc.write_verb.contract_violation';
+  readonly ADAPTER_CAPABILITY_REQUIRED: 'arc.adapter.capability_required';
+  readonly NO_ADAPTER: 'arc.no_adapter';
+  readonly AGGREGATION_MAX_GROUPS_EXCEEDED: 'arc.aggregation.max_groups_exceeded';
+  readonly AGGREGATION_REQUIRED_FILTER_MISSING: 'arc.aggregation.required_filter_missing';
+  readonly AGGREGATION_REQUIRED_DATE_RANGE_MISSING: 'arc.aggregation.required_date_range_missing';
+  readonly AGGREGATION_DATE_RANGE_EXCEEDED: 'arc.aggregation.date_range_exceeded';
+  readonly EVENT_VALIDATION_ERROR: 'arc.event.validation_error';
+  readonly REALTIME_UNFILTERABLE: 'arc.realtime.unfilterable';
+  readonly JOBS_POLICY_UNSUPPORTED: 'arc.jobs.policy_unsupported';
+  readonly STREAMLINE_INVALID_BODY: 'arc.streamline.invalid_body';
+  readonly STREAMLINE_MISSING_INPUT_ENVELOPE: 'arc.streamline.missing_input_envelope';
+  readonly STREAMLINE_UNKNOWN_ENVELOPE_KEYS: 'arc.streamline.unknown_envelope_keys';
+  readonly PURGE_CHUNKED_REQUIRED: 'arc.purge.chunked_required';
+  readonly PURGE_UNSUPPORTED_STRATEGY: 'arc.purge.unsupported_strategy';
+  readonly PURGE_NO_BULK_OP: 'arc.purge.no_bulk_op';
+  readonly MCP_TOOL_NAME_COLLISION: 'arc.mcp.tool_name_collision';
+};
+type ArcErrorCode = (typeof ARC_ERROR_CODES)[keyof typeof ARC_ERROR_CODES];
+declare const ARC_REASON_CODES: {
+  readonly ORG_CONTEXT_REQUIRED: 'ORG_CONTEXT_REQUIRED';
+  readonly MIXED_UPDATE_SHAPE: 'MIXED_UPDATE_SHAPE';
+  readonly ALL_FIELDS_STRIPPED: 'ALL_FIELDS_STRIPPED';
+  readonly BEFORE_RESTORE_HOOK_ERROR: 'BEFORE_RESTORE_HOOK_ERROR';
+};
+type ArcReasonCode = (typeof ARC_REASON_CODES)[keyof typeof ARC_REASON_CODES];
+/** `details[].code` for a unique-constraint violation (see `toErrorContract`). */
+declare const DUPLICATE_KEY_DETAIL_CODE = "duplicate_key";
+//#endregion
+export { ARC_ERROR_CODES, ARC_REASON_CODES, ArcErrorCode, ArcReasonCode, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES, ErrorCode };

package/dist/errors/codes.mjs

@@ -0,0 +1,114 @@
+//#region src/errors/codes.ts
+/**
+* The error-code vocabulary of the wire — every value a client may see in
+* `ErrorContract.code`, in one place.
+*
+* Codes live here, in the contract package, rather than in the servers that
+* emit them: a client SDK consumes the wire vocabulary by depending on
+* repo-core, never on the server framework. The emitting side proves it only
+* uses catalogued codes (arc's test suite fails on an uncatalogued `arc.*`
+* literal); the consuming side spreads these constants instead of copying
+* strings, so an addition reaches every client with a repo-core bump.
+*
+* Three families:
+*
+*   - {@link ERROR_CODES} — cross-cutting, lowercase snake_case (RFC 7807 /
+*     Stripe style). What {@link statusToErrorCode} derives and any
+*     HTTP-emitting package may use.
+*   - {@link ARC_ERROR_CODES} — arc's `arc.`-namespaced codes: the
+*     status-derived family, request validation, auth, tenancy, idempotency,
+*     capacity, and per-feature codes. Values are wire-stable — never renamed.
+*   - {@link ARC_REASON_CODES} — UPPER_SNAKE business reasons arc's mixins put
+*     on `code` alongside the HTTP status (why a bulk write was refused, …).
+*
+* `ErrorContract.code` stays `string`: domain packages extend hierarchically
+* (`'order.validation.missing_line'`) without registering here.
+*/
+const ERROR_CODES = {
+	VALIDATION: "validation_error",
+	NOT_FOUND: "not_found",
+	CONFLICT: "conflict",
+	UNAUTHORIZED: "unauthorized",
+	FORBIDDEN: "forbidden",
+	RATE_LIMITED: "rate_limited",
+	IDEMPOTENCY_CONFLICT: "idempotency_conflict",
+	PRECONDITION_FAILED: "precondition_failed",
+	INTERNAL: "internal_error",
+	UNAVAILABLE: "service_unavailable",
+	TIMEOUT: "timeout"
+};
+const ARC_ERROR_CODES = {
+	ERROR: "arc.error",
+	BAD_REQUEST: "arc.bad_request",
+	UNAUTHORIZED: "arc.unauthorized",
+	FORBIDDEN: "arc.forbidden",
+	NOT_FOUND: "arc.not_found",
+	CONFLICT: "arc.conflict",
+	PAYLOAD_TOO_LARGE: "arc.payload_too_large",
+	UNSUPPORTED_MEDIA_TYPE: "arc.unsupported_media_type",
+	UNPROCESSABLE_ENTITY: "arc.unprocessable_entity",
+	RATE_LIMITED: "arc.rate_limited",
+	INTERNAL_ERROR: "arc.internal_error",
+	NOT_IMPLEMENTED: "arc.not_implemented",
+	BAD_GATEWAY: "arc.bad_gateway",
+	SERVICE_UNAVAILABLE: "arc.service_unavailable",
+	GATEWAY_TIMEOUT: "arc.gateway_timeout",
+	VALIDATION_ERROR: "arc.validation_error",
+	INVALID_ID: "arc.invalid_id",
+	INVALID_ACTION: "arc.invalid_action",
+	UNSUPPORTED_API_VERSION: "arc.unsupported_api_version",
+	/** A stale `If-Match` — re-read the document (its `ETag`) and retry. HTTP 412. */
+	PRECONDITION_FAILED: "arc.precondition_failed",
+	AUTH_INVALID_TOKEN_TYPE: "arc.auth.invalid_token_type",
+	AUTH_TOKEN_REVOKED: "arc.auth.token_revoked",
+	AUTH_REVOCATION_CHECK_FAILED: "arc.auth.revocation_check_failed",
+	AUTH_MISCONFIGURED: "arc.auth.misconfigured",
+	/** HTTP 500 — the auth provider itself failed (not a bad credential). */
+	AUTH_SERVICE_ERROR: "arc.auth.service_error",
+	/** HTTP 401 — `x-arc-scope: platform` without an authenticated user. */
+	ELEVATION_AUTH_REQUIRED: "arc.elevation.auth_required",
+	/** HTTP 403 — `x-arc-scope: platform` from a user without a platform role. */
+	ELEVATION_FORBIDDEN: "arc.elevation.forbidden",
+	ORG_SELECTION_REQUIRED: "arc.org.selection_required",
+	ORG_ACCESS_DENIED: "arc.org.access_denied",
+	/** Convention for host tier gates; arc surfaces it verbatim with `{ requiredMode, currentMode }`. */
+	TIER_REQUIRED: "arc.tier_required",
+	/** HTTP 400 — the route requires an `Idempotency-Key`. */
+	IDEMPOTENCY_KEY_REQUIRED: "arc.idempotency_key_required",
+	/** HTTP 422 — the key already named an operation with a different body. */
+	IDEMPOTENCY_KEY_REUSED: "arc.idempotency_key_reused",
+	/** HTTP 400 — the body could not be fingerprinted (too deep). */
+	IDEMPOTENCY_BODY_UNFINGERPRINTABLE: "arc.idempotency_body_unfingerprintable",
+	/** HTTP 409 — the same key is still executing; retry after `Retry-After`. */
+	IDEMPOTENCY_CONFLICT: "arc.idempotency_conflict",
+	CIRCUIT_OPEN: "arc.circuit_open",
+	UNAVAILABLE: "arc.unavailable",
+	/** HTTP 500 — a host write verb broke its contract (e.g. `create` returned nothing). */
+	WRITE_VERB_CONTRACT_VIOLATION: "arc.write_verb.contract_violation",
+	ADAPTER_CAPABILITY_REQUIRED: "arc.adapter.capability_required",
+	NO_ADAPTER: "arc.no_adapter",
+	AGGREGATION_MAX_GROUPS_EXCEEDED: "arc.aggregation.max_groups_exceeded",
+	AGGREGATION_REQUIRED_FILTER_MISSING: "arc.aggregation.required_filter_missing",
+	AGGREGATION_REQUIRED_DATE_RANGE_MISSING: "arc.aggregation.required_date_range_missing",
+	AGGREGATION_DATE_RANGE_EXCEEDED: "arc.aggregation.date_range_exceeded",
+	EVENT_VALIDATION_ERROR: "arc.event.validation_error",
+	REALTIME_UNFILTERABLE: "arc.realtime.unfilterable",
+	JOBS_POLICY_UNSUPPORTED: "arc.jobs.policy_unsupported",
+	STREAMLINE_INVALID_BODY: "arc.streamline.invalid_body",
+	STREAMLINE_MISSING_INPUT_ENVELOPE: "arc.streamline.missing_input_envelope",
+	STREAMLINE_UNKNOWN_ENVELOPE_KEYS: "arc.streamline.unknown_envelope_keys",
+	PURGE_CHUNKED_REQUIRED: "arc.purge.chunked_required",
+	PURGE_UNSUPPORTED_STRATEGY: "arc.purge.unsupported_strategy",
+	PURGE_NO_BULK_OP: "arc.purge.no_bulk_op",
+	MCP_TOOL_NAME_COLLISION: "arc.mcp.tool_name_collision"
+};
+const ARC_REASON_CODES = {
+	ORG_CONTEXT_REQUIRED: "ORG_CONTEXT_REQUIRED",
+	MIXED_UPDATE_SHAPE: "MIXED_UPDATE_SHAPE",
+	ALL_FIELDS_STRIPPED: "ALL_FIELDS_STRIPPED",
+	BEFORE_RESTORE_HOOK_ERROR: "BEFORE_RESTORE_HOOK_ERROR"
+};
+/** `details[].code` for a unique-constraint violation (see `toErrorContract`). */
+const DUPLICATE_KEY_DETAIL_CODE = "duplicate_key";
+//#endregion
+export { ARC_ERROR_CODES, ARC_REASON_CODES, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES };

package/dist/errors/contract.d.mts

@@ -1,4 +1,5 @@
-import { ErrorCode, ErrorContract } from "./types.mjs";
+import { ErrorCode } from "./codes.mjs";
+import { ErrorContract } from "./types.mjs";
 //#region src/errors/contract.d.ts
 /**
  * Map an HTTP status code to the canonical {@link ErrorCode}. Used as a

package/dist/errors/contract.mjs

@@ -1,6 +1,12 @@
-import { ERROR_CODES } from "./types.mjs";
+import { DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES } from "./codes.mjs";
 //#region src/errors/contract.ts
 /**
+* Wire-contract helpers — convert throwable {@link HttpError} into the
+* serializable {@link ErrorContract} shape, with a `code` cascade so any
+* thrown error produces a sensible wire envelope even when it's a plain
+* `Error` from third-party code.
+*/
+/**
 * Map an HTTP status code to the canonical {@link ErrorCode}. Used as a
 * fallback when a thrown `HttpError` lacks an explicit `code` field.
 *
@@ -47,7 +53,7 @@ function statusToErrorCode(status) {
 */
 function toErrorContract(error) {
 	if (!(error instanceof Error)) return {
-		code: "internal_error",
+		code: ERROR_CODES.INTERNAL,
 		message: typeof error === "string" ? error : "Internal error",
 		status: 500
 	};
@@ -67,7 +73,7 @@ function toErrorContract(error) {
 	});
 	if (e.duplicate?.fields?.length) for (const field of e.duplicate.fields) details.push({
 		path: field,
-		code: "duplicate_key",
+		code: DUPLICATE_KEY_DETAIL_CODE,
 		message: `Duplicate value for "${field}"`
 	});
 	if (details.length > 0) contract.details = details;

package/dist/errors/index.d.mts

@@ -1,7 +1,8 @@
 import { IsTransientConflictFn, VersionConflictError, conservativeMongoIsTransientConflict, isVersionConflictError, neverTransient } from "./conflict.mjs";
-import { DuplicateKeyMeta, ERROR_CODES, ErrorCode, ErrorContract, ErrorDetail, HttpError, ValidationErrorMeta } from "./types.mjs";
+import { ARC_ERROR_CODES, ARC_REASON_CODES, ArcErrorCode, ArcReasonCode, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES, ErrorCode } from "./codes.mjs";
+import { DuplicateKeyMeta, ErrorContract, ErrorDetail, HttpError, ValidationErrorMeta } from "./types.mjs";
 import { statusToErrorCode, toErrorContract } from "./contract.mjs";
 import { createError, isHttpError } from "./create-error.mjs";
 import { IsDuplicateKeyErrorFn, ToDuplicateKeyHttpErrorOptions, conservativeMongoIsDuplicateKey, toDuplicateKeyHttpError } from "./duplicate-key.mjs";
 import { errorContractSchema, errorDetailSchema } from "./schema.mjs";
-export { type DuplicateKeyMeta, ERROR_CODES, type ErrorCode, type ErrorContract, type ErrorDetail, type HttpError, type IsDuplicateKeyErrorFn, type IsTransientConflictFn, type ToDuplicateKeyHttpErrorOptions, type ValidationErrorMeta, VersionConflictError, conservativeMongoIsDuplicateKey, conservativeMongoIsTransientConflict, createError, errorContractSchema, errorDetailSchema, isHttpError, isVersionConflictError, neverTransient, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };
+export { ARC_ERROR_CODES, ARC_REASON_CODES, type ArcErrorCode, type ArcReasonCode, DUPLICATE_KEY_DETAIL_CODE, type DuplicateKeyMeta, ERROR_CODES, type ErrorCode, type ErrorContract, type ErrorDetail, type HttpError, type IsDuplicateKeyErrorFn, type IsTransientConflictFn, type ToDuplicateKeyHttpErrorOptions, type ValidationErrorMeta, VersionConflictError, conservativeMongoIsDuplicateKey, conservativeMongoIsTransientConflict, createError, errorContractSchema, errorDetailSchema, isHttpError, isVersionConflictError, neverTransient, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };

package/dist/errors/index.mjs

@@ -1,7 +1,7 @@
+import { ARC_ERROR_CODES, ARC_REASON_CODES, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES } from "./codes.mjs";
 import { VersionConflictError, conservativeMongoIsTransientConflict, isVersionConflictError, neverTransient } from "./conflict.mjs";
-import { ERROR_CODES } from "./types.mjs";
 import { statusToErrorCode, toErrorContract } from "./contract.mjs";
 import { createError, isHttpError } from "./create-error.mjs";
 import { conservativeMongoIsDuplicateKey, toDuplicateKeyHttpError } from "./duplicate-key.mjs";
 import { errorContractSchema, errorDetailSchema } from "./schema.mjs";
-export { ERROR_CODES, VersionConflictError, conservativeMongoIsDuplicateKey, conservativeMongoIsTransientConflict, createError, errorContractSchema, errorDetailSchema, isHttpError, isVersionConflictError, neverTransient, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };
+export { ARC_ERROR_CODES, ARC_REASON_CODES, DUPLICATE_KEY_DETAIL_CODE, ERROR_CODES, VersionConflictError, conservativeMongoIsDuplicateKey, conservativeMongoIsTransientConflict, createError, errorContractSchema, errorDetailSchema, isHttpError, isVersionConflictError, neverTransient, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };

package/dist/errors/types.d.mts

@@ -18,8 +18,8 @@
  * `implements HttpError` and serialize to `ErrorContract` for the wire.
  * One contract, one canonical home, every package follows the same shape.
  *
- * **Custom-domain escape hatch.** {@link ErrorCode} is a documented union
- * of canonical codes; `code: string` accepts ANY string so domain packages
+ * **Custom-domain escape hatch.** The catalogued codes live in `codes.ts`;
+ * `code: string` accepts ANY string so domain packages
  * can extend (`'order.validation.missing_line'`, `'payment.gateway.timeout'`).
  * The canonical codes cover cross-cutting concerns; domain extensions
  * hierarchically narrow.
@@ -124,32 +124,5 @@ interface ErrorDetail {
   message: string;
   meta?: Readonly<Record<string, unknown>>;
 }
-/**
- * Cross-cutting error codes used across the org. Every canonical code is
- * lowercase + snake_case to match RFC 7807, Stripe, and Shopify
- * conventions. Domain packages add their own hierarchical codes
- * (`'order.validation.*'`, `'payment.gateway.*'`); these cover the
- * universal cases every HTTP-emitting layer needs.
- *
- * **Arc compatibility note.** Arc's `ArcError` hierarchy historically
- * uses UPPER_SNAKE codes (`'NOT_FOUND'`, `'VALIDATION_ERROR'`) for
- * back-compat with hosts that switch on those values. New code should
- * prefer the canonical lowercase codes; arc keeps emitting its UPPER_SNAKE
- * codes on the wire so existing client switches keep working.
- */
-declare const ERROR_CODES: {
-  readonly VALIDATION: 'validation_error';
-  readonly NOT_FOUND: 'not_found';
-  readonly CONFLICT: 'conflict';
-  readonly UNAUTHORIZED: 'unauthorized';
-  readonly FORBIDDEN: 'forbidden';
-  readonly RATE_LIMITED: 'rate_limited';
-  readonly IDEMPOTENCY_CONFLICT: 'idempotency_conflict';
-  readonly PRECONDITION_FAILED: 'precondition_failed';
-  readonly INTERNAL: 'internal_error';
-  readonly UNAVAILABLE: 'service_unavailable';
-  readonly TIMEOUT: 'timeout';
-};
-type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
 //#endregion
-export { DuplicateKeyMeta, ERROR_CODES, ErrorCode, ErrorContract, ErrorDetail, HttpError, ValidationErrorMeta };
+export { DuplicateKeyMeta, ErrorContract, ErrorDetail, HttpError, ValidationErrorMeta };