@classytic/repo-core 0.3.0 → 0.4.0

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

@@ -0,0 +1,96 @@
+import { HOOK_PRIORITY } from "../../hooks/priority.mjs";
+import { buildCacheKey, extractScopeTags, mergeTags, scopeKeyFromTags } from "../keys.mjs";
+import { ctx, extractCallCacheOptions, extractShapeFields } from "./context.mjs";
+import { resolveCacheOptions } from "../options.mjs";
+import { scheduleSwrRefresh } from "./swr.mjs";
+//#region src/cache/plugin/read-hooks.ts
+/**
+* Read-side hook registration: `before:<op>` (cache check + single-
+* flight claim), `after:<op>` (cache write + resolve waiters), and
+* `error:<op>` (reject waiters fail-fast).
+*
+* All three hooks coordinate via typed slots on the shared context bag
+* (see `./context.ts`). The kit's read method short-circuits when
+* `_cacheHit === true` via `RepositoryBase._cachedValue<T>(context)`.
+*/
+function registerReadHooks(repo, op, engine, hookCtx) {
+	repo.on(`before:${op}`, registerBefore(op, engine, hookCtx), { priority: HOOK_PRIORITY.CACHE });
+	repo.on(`after:${op}`, registerAfter(op, engine, hookCtx), { priority: HOOK_PRIORITY.CACHE });
+	repo.on(`error:${op}`, registerError(engine), { priority: HOOK_PRIORITY.CACHE });
+}
+function registerBefore(op, engine, hookCtx) {
+	return async (rawContext) => {
+		const context = ctx(rawContext);
+		const resolved = resolveCacheOptions(extractCallCacheOptions(context, op), hookCtx.perOpDefaults, hookCtx.defaults);
+		if (!resolved.enabled) return;
+		const scopeTags = hookCtx.autoTagsFromScope ? extractScopeTags(context) : [];
+		const allTags = mergeTags(resolved.tags, scopeTags);
+		const key = resolved.key ?? await deriveKey(engine, op, context, scopeTags, hookCtx);
+		context._cacheKey = key;
+		context._cacheResolved = {
+			...resolved,
+			tags: allTags
+		};
+		const result = await engine.get(key, resolved);
+		if (result.status === "fresh" || result.status === "stale") {
+			context._cacheHit = true;
+			context._cachedResult = result.data;
+			context._cacheStatus = result.status;
+			if (result.status === "fresh") hookCtx.log.onHit?.(key, op, result.age ?? 0);
+			else hookCtx.log.onStale?.(key, op, result.age ?? 0);
+			return;
+		}
+		hookCtx.log.onMiss?.(key, op);
+		if (resolved.bypass) return;
+		const claim = engine.claimPending(key);
+		if (claim.status === "wait") try {
+			const data = await claim.promise;
+			context._cacheHit = true;
+			context._cachedResult = data;
+			context._cacheStatus = "fresh";
+			context._cacheCoalesced = true;
+			hookCtx.log.onCoalesce?.(key, op);
+		} catch {}
+	};
+}
+function registerAfter(op, engine, hookCtx) {
+	return async (rawPayload) => {
+		const payload = rawPayload;
+		const context = ctx(payload.context);
+		if (context._cacheHit === true && context._cacheStatus === "stale") {
+			scheduleSwrRefresh(op, hookCtx.repo, context);
+			return;
+		}
+		if (context._cacheHit === true && context._cacheStatus === "fresh") return;
+		const key = context._cacheKey;
+		const resolved = context._cacheResolved;
+		if (!key || !resolved) return;
+		await engine.set(key, payload.result, resolved);
+		engine.resolvePending(key, payload.result);
+		hookCtx.log.onWrite?.(key, op, resolved.tags);
+	};
+}
+function registerError(engine) {
+	return async (rawPayload) => {
+		const payload = rawPayload;
+		const key = ctx(payload.context)._cacheKey;
+		if (!key) return;
+		engine.rejectPending(key, payload.error);
+	};
+}
+async function deriveKey(engine, op, context, scopeTags, hookCtx) {
+	const model = context["model"] ?? "unknown";
+	const scopeKey = scopeKeyFromTags(scopeTags);
+	const version = await engine.getVersion(model, scopeKey);
+	const params = extractShapeFields(context, op, hookCtx.shapeKeysByOp);
+	return buildCacheKey({
+		prefix: engine.keyPrefix,
+		operation: op,
+		model,
+		version,
+		params: params ?? {},
+		scopeTags
+	});
+}
+//#endregion
+export { registerReadHooks };

package/dist/cache/plugin/swr.mjs

@@ -0,0 +1,20 @@
+import { AGGREGATE_OPS } from "./context.mjs";
+import { scheduleBackground } from "../runtime.mjs";
+//#region src/cache/plugin/swr.ts
+function scheduleSwrRefresh(op, repo, context) {
+	if (!AGGREGATE_OPS.has(op)) return;
+	const aggReq = context["aggRequest"];
+	if (!aggReq) return;
+	const refreshReq = {
+		...aggReq,
+		cache: {
+			...aggReq.cache ?? {},
+			bypass: true
+		}
+	};
+	scheduleBackground(() => {
+		repo[op]?.(refreshReq).catch(() => {});
+	});
+}
+//#endregion
+export { scheduleSwrRefresh };

package/dist/cache/runtime.d.mts

@@ -0,0 +1,43 @@
+//#region src/cache/runtime.d.ts
+/**
+ * Cross-runtime scheduling primitives.
+ *
+ * The cache layer targets every JS runtime kits + arc + Express/Nest
+ * hosts run on — Node, Bun, Deno Deploy, Cloudflare Workers, edge
+ * functions. Most Web-style APIs (`Map`, `Promise`, `setTimeout`,
+ * `BigInt`, `queueMicrotask`) are available across all of them, but
+ * `setImmediate` is Node-specific — Workers / Deno / browsers throw a
+ * `ReferenceError` if you call it.
+ *
+ * `scheduleBackground` resolves the right primitive at module load and
+ * exposes a single API the rest of the cache layer uses.
+ *
+ * **Semantics:**
+ *
+ * | Runtime     | Mechanism            | When the callback fires             |
+ * | ----------- | -------------------- | ----------------------------------- |
+ * | Node / Bun  | `setImmediate(fn)`   | After current I/O phase             |
+ * | Workers     | `setTimeout(fn, 0)`  | After current task (min 0ms)        |
+ * | Deno Deploy | `setTimeout(fn, 0)`  | After current task                  |
+ * | Browser     | `setTimeout(fn, 0)`  | After current task (clamped 4ms)    |
+ *
+ * Every runtime guarantees the callback runs AFTER the current sync
+ * block + any pending microtasks of the current task — which is the
+ * actual contract callers rely on (don't run the bg work synchronously
+ * in the response path).
+ *
+ * **Why not `queueMicrotask`?** Microtasks flush BEFORE the current
+ * I/O phase completes. For SWR, that means the bg refresh's first
+ * `await` could delay the user's HTTP response write. `setImmediate`
+ * (or `setTimeout(0)` on edge runtimes) defers past the I/O phase.
+ */
+/**
+ * Schedule a fire-and-forget callback to run after the current task.
+ *
+ * Used by SWR background refresh + (potentially) any future hook that
+ * wants "run after response" semantics. Caller is responsible for
+ * error handling — this helper does NOT add a default `.catch`.
+ */
+declare const scheduleBackground: (fn: () => void) => void;
+//#endregion
+export { scheduleBackground };

package/dist/cache/runtime.mjs

@@ -0,0 +1,14 @@
+/**
+* Schedule a fire-and-forget callback to run after the current task.
+*
+* Used by SWR background refresh + (potentially) any future hook that
+* wants "run after response" semantics. Caller is responsible for
+* error handling — this helper does NOT add a default `.catch`.
+*/
+const scheduleBackground = typeof globalThis.setImmediate === "function" ? (fn) => {
+	globalThis.setImmediate(fn);
+} : (fn) => {
+	setTimeout(fn, 0);
+};
+//#endregion
+export { scheduleBackground };

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/index.d.mts

@@ -2,4 +2,5 @@ import { DuplicateKeyMeta, ERROR_CODES, ErrorCode, ErrorContract, ErrorDetail, H
 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, ERROR_CODES, type ErrorCode, type ErrorContract, type ErrorDetail, type HttpError, type IsDuplicateKeyErrorFn, type ToDuplicateKeyHttpErrorOptions, type ValidationErrorMeta, conservativeMongoIsDuplicateKey, createError, isHttpError, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };
+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

@@ -2,4 +2,5 @@ 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 { ERROR_CODES, conservativeMongoIsDuplicateKey, createError, isHttpError, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };
+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 };