@classytic/repo-core 0.2.0 → 0.4.0

package/dist/cache/tag-index.mjs

@@ -0,0 +1,84 @@
+import { tagIndexKey } from "./keys.mjs";
+//#region src/cache/tag-index.ts
+/**
+* Tag side-index — non-pattern-dependent tag invalidation.
+*
+* Adapters that don't support `clear(pattern)` (most plain KV stores,
+* Upstash REST, in-memory `Map` adapters) can still implement
+* tag-based group invalidation via this side-index: every `set` adds
+* the entry's key to each tag's index list; `invalidateByTags` reads
+* the index, deletes the listed keys, and clears the index.
+*
+* **TTL hygiene.** The index entry's TTL tracks the longest-lived
+* cached entry under that tag. When the data behind every key under
+* a tag has expired, the index naturally evicts too — preventing
+* unbounded growth on hot tags.
+*
+* **Parallelization.** Both `appendKeyToTags` and `invalidateByTags`
+* fan out adapter operations via `Promise.all` — for Redis-backed
+* adapters this means N tags / M keys complete in 1 RTT (pipelined)
+* instead of N+M sequential RTTs. Single-key paths bypass the
+* scheduling overhead.
+*
+* **Non-transactional.** A crash between writing the entry and
+* appending to the index — or between deleting entries and clearing
+* the index — leaves stale references. Stale references resolve to
+* `undefined` on next read (treated as miss); the TTL is the safety
+* net for orphaned index entries.
+*/
+/**
+* Append `cacheKey` to each tag's index in parallel. Uses
+* `adapter.addToSet` when available (Redis SADD, in-memory mutation)
+* for `O(M)` appends; falls back to GET+SET-array otherwise.
+*
+* **Performance note.** The benchmark suite measured `O(N²)` overhead
+* on the GET+SET fallback (178× slower than no-tags writes at hot-tag
+* sizes). The fast path eliminates the per-write array copy entirely.
+*
+* The index is set with a TTL matching the entry's own TTL — when the
+* entry naturally expires, its index reference does too, bounding
+* index growth. Dedups same-key writes (SWR refresh re-writes the
+* same key) so the index doesn't grow unboundedly under SWR.
+*/
+async function appendKeyToTags(adapter, prefix, cacheKey, tags, ttlSeconds) {
+	if (tags.length === 0) return;
+	const indexTtl = Math.min(Math.max(ttlSeconds, 60), 1440 * 60);
+	if (adapter.addToSet) {
+		const fn = adapter.addToSet.bind(adapter);
+		await Promise.all(tags.map((tag) => fn(tagIndexKey(prefix, tag), [cacheKey], indexTtl)));
+		return;
+	}
+	await Promise.all(tags.map(async (tag) => {
+		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];
+		await adapter.set(idxKey, next, indexTtl);
+	}));
+}
+/**
+* Read each tag's index in parallel, delete every listed cache entry
+* + each index in parallel, and return the count of distinct cache
+* entries removed.
+*
+* For a Redis-backed adapter pipelining these operations, this is
+* effectively 2 RTTs (read-fan-out + delete-fan-out) regardless of
+* tag/entry count — vs N+M sequential RTTs in the prior impl.
+*
+* Returns `0` when no tags were provided or no entries matched.
+*/
+async function invalidateByTags(adapter, prefix, tags) {
+	if (tags.length === 0) return 0;
+	const indexKeys = tags.map((t) => tagIndexKey(prefix, t));
+	const indices = await Promise.all(indexKeys.map((k) => adapter.get(k)));
+	const cacheKeys = /* @__PURE__ */ new Set();
+	for (const idx of indices) if (Array.isArray(idx)) for (const k of idx) cacheKeys.add(k);
+	const deletions = [];
+	for (const k of cacheKeys) deletions.push(adapter.delete(k));
+	for (const k of indexKeys) deletions.push(adapter.delete(k));
+	await Promise.all(deletions);
+	return cacheKeys.size;
+}
+//#endregion
+export { appendKeyToTags, invalidateByTags };

package/dist/cache/timeout-adapter.d.mts

@@ -0,0 +1,30 @@
+import { CacheAdapter } from "./types.mjs";
+
+//#region src/cache/timeout-adapter.d.ts
+declare class CacheTimeoutError extends Error {
+  readonly op: string;
+  readonly key?: string;
+  readonly ms: number;
+  constructor(op: string, ms: number, key?: string);
+}
+interface TimeoutAdapterOptions {
+  /** Per-operation deadline in milliseconds. Default: `250`. */
+  ms?: number;
+  /**
+   * What to do when an operation exceeds `ms`:
+   *   - `'miss'`  — `get` returns `undefined` (cache miss); writes
+   *                 swallow the timeout. Default.
+   *   - `'throw'` — throw `CacheTimeoutError` on every timeout.
+   */
+  onTimeout?: 'miss' | 'throw';
+  /** Optional callback fired on every timeout (observability). */
+  onSlow?: (op: string, ms: number, key?: string) => void;
+}
+/**
+ * Wrap a `CacheAdapter` with per-op timeouts. The returned adapter
+ * matches the original's contract (sync-or-async returns); ops that
+ * complete before the deadline pass through unchanged.
+ */
+declare function withTimeout(adapter: CacheAdapter, options?: TimeoutAdapterOptions): CacheAdapter;
+//#endregion
+export { CacheTimeoutError, TimeoutAdapterOptions, withTimeout };

package/dist/cache/timeout-adapter.mjs

@@ -0,0 +1,58 @@
+//#region src/cache/timeout-adapter.ts
+var CacheTimeoutError = class extends Error {
+	op;
+	key;
+	ms;
+	constructor(op, ms, key) {
+		super(`Cache adapter timed out after ${ms}ms during ${op}${key ? ` for key "${key}"` : ""}`);
+		this.name = "CacheTimeoutError";
+		this.op = op;
+		this.ms = ms;
+		if (key !== void 0) this.key = key;
+	}
+};
+/**
+* Wrap a `CacheAdapter` with per-op timeouts. The returned adapter
+* matches the original's contract (sync-or-async returns); ops that
+* complete before the deadline pass through unchanged.
+*/
+function withTimeout(adapter, options = {}) {
+	const ms = options.ms ?? 250;
+	const onTimeout = options.onTimeout ?? "miss";
+	const onSlow = options.onSlow;
+	/** Race a possibly-async value against a timeout. */
+	function withDeadline(op, fallback, fn, key) {
+		const result = fn();
+		if (!(result instanceof Promise)) return result;
+		return Promise.race([result, new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				onSlow?.(op, ms, key);
+				if (onTimeout === "throw") reject(new CacheTimeoutError(op, ms, key));
+				else resolve(fallback());
+			}, ms);
+			result.then(() => clearTimeout(timer), () => clearTimeout(timer));
+			if (typeof timer === "object" && timer !== null && "unref" in timer) timer.unref?.();
+		})]);
+	}
+	return {
+		get(key) {
+			return withDeadline("get", () => void 0, () => adapter.get(key), key);
+		},
+		set(key, value, ttlSeconds) {
+			return withDeadline("set", () => void 0, () => adapter.set(key, value, ttlSeconds), key);
+		},
+		delete(key) {
+			return withDeadline("delete", () => void 0, () => adapter.delete(key), key);
+		},
+		...adapter.clear ? { clear(pattern) {
+			const fn = adapter.clear;
+			return withDeadline("clear", () => void 0, () => fn.call(adapter, pattern));
+		} } : {},
+		...adapter.increment ? { increment(key, by, ttlSeconds) {
+			const fn = adapter.increment;
+			return withDeadline("increment", () => 0, () => fn.call(adapter, key, by, ttlSeconds), key);
+		} } : {}
+	};
+}
+//#endregion
+export { CacheTimeoutError, withTimeout };

package/dist/cache/types.d.mts

@@ -54,6 +54,51 @@ interface CacheAdapter {
    * one interface flows across every layer.
    */
   clear?(pattern?: string): Promise<void> | void;
+  /**
+   * Atomic add-to-set — append `members` to the set at `key`,
+   * creating it when absent. Existing members are no-ops (idempotent).
+   * Returns the count of newly-added members.
+   *
+   * **Why optional.** The cache engine's tag side-index uses this
+   * for `O(M)` appends instead of the GET+SET-array fallback (which
+   * is `O(N²)` per write — read the whole list, copy, append, write
+   * back). At scale (hot tags with thousands of entries) the
+   * difference is the 178× slowdown the in-memory benchmark surfaced.
+   *
+   * **Implementation guidance:**
+   *   - Redis: `SADD key m1 m2 ...` + `EXPIRE key ttlSeconds NX`
+   *   - 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).
+   */
+  addToSet?(key: string, members: readonly string[], ttlSeconds?: number): Promise<number> | number;
+  /**
+   * Atomic increment — adds `by` (default 1) to the integer at `key`,
+   * creating the key with value `by` when absent. Returns the NEW
+   * value. `ttlSeconds` is applied only when the key is created (most
+   * implementations match Redis SETEX-on-INCR semantics).
+   *
+   * **Why optional.** Pure KV stores without atomic counters
+   * (Cloudflare Workers KV, file-backed stores) can't implement this
+   * without external coordination. The cache engine falls back to a
+   * `get → max → set` pattern when `increment` is absent, accepting
+   * the (rare, multi-pod) race condition where two simultaneous bumps
+   * collide and only one increment records.
+   *
+   * **Implementation guidance:**
+   *   - Redis: `INCRBY key by` + `EXPIRE key ttlSeconds NX`
+   *     (NX so existing TTLs aren't reset on every increment)
+   *   - Memory: synchronous via JS single-thread guarantee
+   *   - DynamoDB / Mongo `$inc`: native atomic update
+   *
+   * Used by the cache engine's per-scope `bumpModelVersion` to ensure
+   * concurrent writes to the same model never lose bumps — every
+   * write is reflected in the next read's cache key.
+   */
+  increment?(key: string, by?: number, ttlSeconds?: number): Promise<number> | number;
 }
 //#endregion
 export { CacheAdapter };

package/dist/cache/version-store.mjs

@@ -0,0 +1,57 @@
+import { versionKey } from "./keys.mjs";
+//#region src/cache/version-store.ts
+/**
+* Collection-version store — O(1) bulk invalidation by bumping a
+* counter that's embedded in every cache key.
+*
+* **Per-scope sharding** (TanStack-style targeted invalidation).
+* Without scope, a write to the model bumps ONE counter and orphans
+* every cached read for that model — including OTHER tenants' caches.
+* With a `scopeKey` (e.g. `'org:abc'`), the version key becomes
+* `<prefix>:ver:<model>:<scopeKey>` so the write only invalidates the
+* writing tenant's cache.
+*
+* **Atomic-when-supported.** The adapter MAY ship `increment(key, by,
+* ttl)` for atomic counter bumps. When present, concurrent writes
+* from multiple pods produce strictly-monotonic versions (no lost
+* bumps). When absent, falls back to `get → max → set` — correct in
+* single-pod, racy in multi-pod (rare bump-loss; mitigated by the
+* `Date.now()` floor below).
+*
+* **Strict monotonicity** — fallback path uses
+* `max(Date.now(), previous + 1)` so same-millisecond writes still
+* advance the counter (atomic path is naturally monotonic via
+* adapter.increment).
+*/
+const VERSION_TTL_SECONDS = 1440 * 60;
+/**
+* Read the current version for a `model` (optionally per-scope). Returns
+* `0` when no version has been set yet — the initial value before any
+* writes have hit.
+*/
+async function getModelVersion(adapter, prefix, model, scopeKey) {
+	const value = await adapter.get(versionKey(prefix, model, scopeKey));
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	return 0;
+}
+/**
+* Bump the model's version (per-scope when `scopeKey` is supplied) to
+* a strictly-monotonic value. Returns the new value.
+*
+* Atomic when the adapter supports `increment` — concurrent multi-pod
+* writes produce distinct versions. Falls back to `get → max → set`
+* otherwise; under concurrent multi-pod load, two writes may collide
+* on the same `previous` and one bump is lost — accepted trade-off
+* for adapters without atomic counters (Cloudflare KV, etc.).
+*/
+async function bumpModelVersion(adapter, prefix, model, scopeKey) {
+	const key = versionKey(prefix, model, scopeKey);
+	if (adapter.increment) return await adapter.increment(key, 1, VERSION_TTL_SECONDS);
+	const previous = await adapter.get(key);
+	const previousNum = typeof previous === "number" && Number.isFinite(previous) ? previous : 0;
+	const next = Math.max(Date.now(), previousNum + 1);
+	await adapter.set(key, next, VERSION_TTL_SECONDS);
+	return next;
+}
+//#endregion
+export { bumpModelVersion, getModelVersion };

package/dist/errors/contract.d.mts

@@ -0,0 +1,37 @@
+import { ErrorCode, ErrorContract } from "./types.mjs";
+
+//#region src/errors/contract.d.ts
+/**
+ * Map an HTTP status code to the canonical {@link ErrorCode}. Used as a
+ * fallback when a thrown `HttpError` lacks an explicit `code` field.
+ *
+ * The mapping is conservative: only well-known status codes get a
+ * canonical code; unmapped statuses (406, 422, 410, ...) flow through as
+ * `'internal_error'` because there's no portable HTTP-Spec mapping
+ * everyone agrees on. Domain handlers should set `code` explicitly for
+ * any non-default status.
+ */
+declare function statusToErrorCode(status: number): ErrorCode;
+/**
+ * Convert a throwable {@link HttpError} (or any `Error` with a `status`
+ * field) into the canonical {@link ErrorContract} wire shape.
+ *
+ * `code` cascade:
+ *   1. `error.code` (explicit machine code on the throwable) — preferred.
+ *   2. {@link statusToErrorCode}(`error.status`) — derived from status.
+ *   3. `'internal_error'` — fallback for plain `Error` without status.
+ *
+ * `validationErrors` (mongokit-shaped throwable field) is mapped into the
+ * canonical `details` array so wire consumers see one shape regardless
+ * of which kit threw the error. Each `validationErrors[i]` becomes an
+ * `ErrorDetail` with `code: validator`, `message: error`, `path` left
+ * unset (kits that have field paths set them in their own ErrorDetail
+ * mapping).
+ *
+ * `duplicate.fields` is similarly flattened into `details` with the
+ * duplicate-key code so unique-constraint failures look uniform on the
+ * wire.
+ */
+declare function toErrorContract(error: unknown): ErrorContract;
+//#endregion
+export { statusToErrorCode, toErrorContract };

package/dist/errors/contract.mjs

@@ -0,0 +1,75 @@
+import { ERROR_CODES } from "./types.mjs";
+//#region src/errors/contract.ts
+/**
+* Map an HTTP status code to the canonical {@link ErrorCode}. Used as a
+* fallback when a thrown `HttpError` lacks an explicit `code` field.
+*
+* The mapping is conservative: only well-known status codes get a
+* canonical code; unmapped statuses (406, 422, 410, ...) flow through as
+* `'internal_error'` because there's no portable HTTP-Spec mapping
+* everyone agrees on. Domain handlers should set `code` explicitly for
+* any non-default status.
+*/
+function statusToErrorCode(status) {
+	switch (status) {
+		case 400: return ERROR_CODES.VALIDATION;
+		case 401: return ERROR_CODES.UNAUTHORIZED;
+		case 403: return ERROR_CODES.FORBIDDEN;
+		case 404: return ERROR_CODES.NOT_FOUND;
+		case 409: return ERROR_CODES.CONFLICT;
+		case 412: return ERROR_CODES.PRECONDITION_FAILED;
+		case 429: return ERROR_CODES.RATE_LIMITED;
+		case 503: return ERROR_CODES.UNAVAILABLE;
+		case 504: return ERROR_CODES.TIMEOUT;
+		default: return ERROR_CODES.INTERNAL;
+	}
+}
+/**
+* Convert a throwable {@link HttpError} (or any `Error` with a `status`
+* field) into the canonical {@link ErrorContract} wire shape.
+*
+* `code` cascade:
+*   1. `error.code` (explicit machine code on the throwable) — preferred.
+*   2. {@link statusToErrorCode}(`error.status`) — derived from status.
+*   3. `'internal_error'` — fallback for plain `Error` without status.
+*
+* `validationErrors` (mongokit-shaped throwable field) is mapped into the
+* canonical `details` array so wire consumers see one shape regardless
+* of which kit threw the error. Each `validationErrors[i]` becomes an
+* `ErrorDetail` with `code: validator`, `message: error`, `path` left
+* unset (kits that have field paths set them in their own ErrorDetail
+* mapping).
+*
+* `duplicate.fields` is similarly flattened into `details` with the
+* duplicate-key code so unique-constraint failures look uniform on the
+* wire.
+*/
+function toErrorContract(error) {
+	if (!(error instanceof Error)) return {
+		code: "internal_error",
+		message: typeof error === "string" ? error : "Internal error",
+		status: 500
+	};
+	const e = error;
+	const status = typeof e.status === "number" ? e.status : 500;
+	const contract = {
+		code: e.code ?? statusToErrorCode(status),
+		message: e.message || "Internal error",
+		status
+	};
+	const details = [];
+	if (Array.isArray(e.validationErrors)) for (const v of e.validationErrors) details.push({
+		code: v.validator,
+		message: v.error
+	});
+	if (e.duplicate?.fields?.length) for (const field of e.duplicate.fields) details.push({
+		path: field,
+		code: "duplicate_key",
+		message: `Duplicate value for "${field}"`
+	});
+	if (details.length > 0) contract.details = details;
+	if (e.meta) contract.meta = e.meta;
+	return contract;
+}
+//#endregion
+export { statusToErrorCode, toErrorContract };

package/dist/errors/index.d.mts

@@ -1,4 +1,6 @@
-import { DuplicateKeyMeta, HttpError, ValidationErrorMeta } from "./types.mjs";
+import { DuplicateKeyMeta, ERROR_CODES, ErrorCode, 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";
-export { type DuplicateKeyMeta, type HttpError, type IsDuplicateKeyErrorFn, type ToDuplicateKeyHttpErrorOptions, type ValidationErrorMeta, conservativeMongoIsDuplicateKey, createError, isHttpError, toDuplicateKeyHttpError };
+import { errorContractSchema, errorDetailSchema } from "./schema.mjs";
+export { type DuplicateKeyMeta, ERROR_CODES, type ErrorCode, type ErrorContract, type ErrorDetail, type HttpError, type IsDuplicateKeyErrorFn, type ToDuplicateKeyHttpErrorOptions, type ValidationErrorMeta, conservativeMongoIsDuplicateKey, createError, errorContractSchema, errorDetailSchema, isHttpError, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };

package/dist/errors/index.mjs

@@ -1,3 +1,6 @@
+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";
-export { conservativeMongoIsDuplicateKey, createError, isHttpError, toDuplicateKeyHttpError };
+import { errorContractSchema, errorDetailSchema } from "./schema.mjs";
+export { ERROR_CODES, conservativeMongoIsDuplicateKey, createError, errorContractSchema, errorDetailSchema, isHttpError, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };

package/dist/errors/schema.d.mts

@@ -0,0 +1,101 @@
+//#region src/errors/schema.d.ts
+/**
+ * Canonical JSON Schema constants for `ErrorContract` + `ErrorDetail`.
+ *
+ * The runtime wire spec for the `ErrorContract` and `ErrorDetail`
+ * TypeScript interfaces in `./types.ts`. Lives next to the interface so
+ * downstream packages (arc, every kit, host apps) consume from one place
+ * and the JSON Schema cannot drift away from the TS shape.
+ *
+ * Plain JSON-Schema objects — no runtime dependency on AJV, TypeBox,
+ * Zod, or any validator. Anything that consumes JSON Schema can use
+ * these (Fastify schema validator, OpenAPI generators, AJV directly,
+ * `Type.Unsafe<ErrorContract>(errorContractSchema)` for TypeBox).
+ */
+/**
+ * Single field-scoped error detail. Mirrors `ErrorDetail` in
+ * {@link ./types.ts}.
+ */
+declare const errorDetailSchema: {
+  readonly type: "object";
+  readonly properties: {
+    readonly path: {
+      readonly type: "string";
+      readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
+    };
+    readonly code: {
+      readonly type: "string";
+    };
+    readonly message: {
+      readonly type: "string";
+    };
+    readonly meta: {
+      readonly type: "object";
+      readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
+    };
+  };
+  readonly required: readonly ["code", "message"];
+};
+/**
+ * Canonical error response. Mirrors `ErrorContract` in {@link ./types.ts}.
+ *
+ * `code` and `message` are the only required fields. `status` is a
+ * *suggested* HTTP status hosts may override at the edge. `details` is
+ * an array of structured `ErrorDetail` objects (validation failures,
+ * duplicate-key surfaces, etc.). `meta` is a non-PII object.
+ *
+ * Wire shape every 4xx/5xx response in the org follows. Errors live on
+ * a separate path from success — HTTP status discriminates.
+ */
+declare const errorContractSchema: {
+  readonly type: "object";
+  readonly properties: {
+    readonly code: {
+      readonly type: "string";
+      readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
+    };
+    readonly message: {
+      readonly type: "string";
+      readonly description: "Human-readable, safe-for-client message.";
+    };
+    readonly status: {
+      readonly type: "integer";
+      readonly description: "Suggested HTTP status code (hosts may override).";
+    };
+    readonly details: {
+      readonly type: "array";
+      readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
+      readonly items: {
+        readonly type: "object";
+        readonly properties: {
+          readonly path: {
+            readonly type: "string";
+            readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
+          };
+          readonly code: {
+            readonly type: "string";
+          };
+          readonly message: {
+            readonly type: "string";
+          };
+          readonly meta: {
+            readonly type: "object";
+            readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
+          };
+        };
+        readonly required: readonly ["code", "message"];
+      };
+    };
+    readonly correlationId: {
+      readonly type: "string";
+      readonly description: "Request id for support lookups.";
+    };
+    readonly meta: {
+      readonly type: "object";
+      readonly description: "Non-PII diagnostics (safe to log + return).";
+    };
+  };
+  readonly required: readonly ["code", "message"];
+};
+//#endregion
+export { errorContractSchema, errorDetailSchema };

package/dist/errors/schema.mjs

@@ -0,0 +1,78 @@
+//#region src/errors/schema.ts
+/**
+* Canonical JSON Schema constants for `ErrorContract` + `ErrorDetail`.
+*
+* The runtime wire spec for the `ErrorContract` and `ErrorDetail`
+* TypeScript interfaces in `./types.ts`. Lives next to the interface so
+* downstream packages (arc, every kit, host apps) consume from one place
+* and the JSON Schema cannot drift away from the TS shape.
+*
+* Plain JSON-Schema objects — no runtime dependency on AJV, TypeBox,
+* Zod, or any validator. Anything that consumes JSON Schema can use
+* these (Fastify schema validator, OpenAPI generators, AJV directly,
+* `Type.Unsafe<ErrorContract>(errorContractSchema)` for TypeBox).
+*/
+/**
+* Single field-scoped error detail. Mirrors `ErrorDetail` in
+* {@link ./types.ts}.
+*/
+const errorDetailSchema = {
+	type: "object",
+	properties: {
+		path: {
+			type: "string",
+			description: "Dot-path to the offending field, e.g. 'lines.0.quantity'."
+		},
+		code: { type: "string" },
+		message: { type: "string" },
+		meta: {
+			type: "object",
+			description: "Non-PII per-detail diagnostics (safe to log + return)."
+		}
+	},
+	required: ["code", "message"]
+};
+/**
+* Canonical error response. Mirrors `ErrorContract` in {@link ./types.ts}.
+*
+* `code` and `message` are the only required fields. `status` is a
+* *suggested* HTTP status hosts may override at the edge. `details` is
+* an array of structured `ErrorDetail` objects (validation failures,
+* duplicate-key surfaces, etc.). `meta` is a non-PII object.
+*
+* Wire shape every 4xx/5xx response in the org follows. Errors live on
+* a separate path from success — HTTP status discriminates.
+*/
+const errorContractSchema = {
+	type: "object",
+	properties: {
+		code: {
+			type: "string",
+			description: "Hierarchical machine-readable code (e.g. 'arc.not_found')."
+		},
+		message: {
+			type: "string",
+			description: "Human-readable, safe-for-client message."
+		},
+		status: {
+			type: "integer",
+			description: "Suggested HTTP status code (hosts may override)."
+		},
+		details: {
+			type: "array",
+			description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).",
+			items: errorDetailSchema
+		},
+		correlationId: {
+			type: "string",
+			description: "Request id for support lookups."
+		},
+		meta: {
+			type: "object",
+			description: "Non-PII diagnostics (safe to log + return)."
+		}
+	},
+	required: ["code", "message"]
+};
+//#endregion
+export { errorContractSchema, errorDetailSchema };