@classytic/repo-core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,126 @@ All notable changes to `@classytic/repo-core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-04-29
+
+### Added — Aggregate pagination shapes
+
+- `AggregatePaginationResultCore<TDoc>` and `AggregatePaginationResult<TDoc, TExtra>` join `Offset*` / `Keyset*` as the third pagination shape every kit reports. Mirrors offset (page / total / pages / hasNext / hasPrev) with `method: 'aggregate'` discriminant. Mongokit's existing local `AggregatePaginationResult` (3.10.x) becomes redundant — to be deleted in mongokit 4.0.
+- `AnyPaginationResult<TDoc, TExtra>` — union over the three result shapes. Use as the input type to anything that converts repo results into HTTP envelopes.
+
+### Added — HTTP wire envelopes
+
+The repository result shapes (`OffsetPaginationResult`, etc.) carry the `method` discriminant, so the corresponding HTTP wire envelope is just `{ success: true } & Result`. Adding the literal here closes the **server/client envelope mismatch** — arc's HTTP server was emitting flattened paginated responses without the `method` field while arc-next's typed responses required it.
+
+- `OffsetPaginationResponse<TDoc, TExtra>` = `{ success: true } & OffsetPaginationResult<TDoc, TExtra>`
+- `KeysetPaginationResponse<TDoc, TExtra>` = same for keyset
+- `AggregatePaginationResponse<TDoc, TExtra>` = same for aggregate
+- `BareListResponse<TDoc>` = `{ success: true; docs: TDoc[] }` for endpoints that don't paginate
+- `PaginatedResponse<TDoc, TExtra>` = union over all four. The discriminated-union contract is `success: true` literal first, `method` second — typed clients (arc-next, SDKs) narrow with `if (res.success && 'method' in res && res.method === 'offset')`.
+
+### Added — `toCanonicalList()` runtime normalizer
+
+```ts
+import { toCanonicalList } from '@classytic/repo-core/pagination';
+
+const result = await userRepo.getAll(query);
+reply.send(toCanonicalList(result));   // → PaginatedResponse<User>
+
+reply.send(toCanonicalList([u1, u2])); // → BareListResponse<User>
+```
+
+The single point where an internal `Result` becomes an external `Response`. Three overloads route bare arrays / paginated results to the right wire shape; `TExtra` fields (mongokit's `warning?: string`, etc.) flow through.
+
+**Subtle behavior**: `success: true` is stamped *after* the spread, so a stale `success: false` accidentally present on the input cannot override the literal — paginated success path is always `success: true`. Tested.
+
+### Added — `isPaginatedResult()` type guard
+
+Branches on the `method` discriminant rather than `Array.isArray`, so an empty paginated result still routes through the paginated branch. Used internally by `toCanonicalList`; exported for consumers writing custom envelope logic.
+
+### Test delta
+
+230 → 303 tests across 0.3.0. New coverage includes `tests/unit/pagination/canonical.test.ts` and the type-level coverage extensions in `result-types.test.ts` (35 tests landed with the aggregate / wire-envelope / `toCanonicalList` work), plus `tests/unit/repository/base-plugin-validation.test.ts` (6 tests for the `assertValidPlugin` guard).
+
+### Added — `SchemaGenerator<TModel>` interface in `/schema`
+
+Canonical contract for repository kits' CRUD-schema generators. Mongokit's `buildCrudSchemasFromModel` and sqlitekit's `buildCrudSchemasFromTable` (and any future kit's equivalent) `satisfies SchemaGenerator<TKitModel>` at the call site, so arc's `MongooseAdapter.schemaGenerator` / `DrizzleAdapter.schemaGenerator` accept them by structural typing — no glue, no inheritance, no inline function signatures duplicated in every adapter.
+
+- `SchemaGenerator<TModel = unknown>` — `(model, options?, context?) => CrudSchemas | Record<string, unknown>`.
+- `SchemaGeneratorContext` — resource-level context threaded at boot (`idField`, `resourceName`).
+- `isSchemaGenerator(value)` — runtime predicate (arity 1-3 functions). Conservative — doesn't invoke.
+
+Each kit ships a compile-time conformance check (same playbook as mongokit's `RepositoryLike` conformance gate):
+
+```ts
+const _conformance: SchemaGenerator<Model<unknown>> = buildCrudSchemasFromModel;
+```
+
+Drift surfaces in the kit's typecheck immediately, before any consumer sees it.
+
+10 new tests in `tests/unit/schema/generator.test.ts`. Total repo-core: 293 → 303.
+
+### Added — `errors` module: canonical wire + throwable error contract
+
+`@classytic/repo-core/errors` is now the single source of truth for error contracts across the org. Two complementary shapes:
+
+- **`HttpError extends Error`** — the *throwable* shape. Plain `Error` with `status`, optional `code`, `meta`, `validationErrors`, `duplicate`. Kits classify their driver-specific errors into this shape; framework layers (arc) catch and serialize. Existing `HttpError` extended in 0.3 with `code?: string` and `meta?: Record<string, unknown>` (mongokit had these locally pre-3.12).
+- **`ErrorContract`** — the *wire* shape (RFC 7807 / Stripe-style). What gets serialized to JSON responses, dead-letter records, audit trails, inter-service envelopes. Flat top-level `code` / `message` / `status` matches the org-wide `{ success, ... }` envelope convention.
+- **`ErrorDetail`** — single field-scoped error (path / code / message). `ErrorContract.details` is `ReadonlyArray<ErrorDetail>`.
+- **`ERROR_CODES` + `ErrorCode`** — canonical lowercase + snake_case codes (`'validation_error'`, `'not_found'`, `'conflict'`, `'unauthorized'`, `'forbidden'`, `'rate_limited'`, `'idempotency_conflict'`, `'precondition_failed'`, `'internal_error'`, `'service_unavailable'`, `'timeout'`). Domain packages extend hierarchically (`'order.validation.missing_line'`).
+- **`toErrorContract(error)`** — converts any `Error` / `HttpError` / non-`Error` value to the canonical wire `ErrorContract`. `code` cascade: explicit `error.code` → status-derived → `'internal_error'`. Flattens mongokit-shaped `validationErrors` and `duplicate.fields` into the canonical `details[]` array.
+- **`statusToErrorCode(status)`** — well-known HTTP status → canonical code. Conservative mapping; unknown statuses fall through to `'internal_error'` so domain handlers explicitly opt in.
+
+Consumed by mongokit (drops local `HttpError`), arc (`ArcError implements HttpError` with `status` getter), and any future kit / service. Relocated from `@classytic/primitives/errors` (which had `ErrorContract` + `ERROR_CODES` but not the throwable contract) — same playbook as the pagination, tenant, and events relocations: errors are infrastructure-shaped, not domain primitives.
+
+14 new tests in `tests/unit/errors/contract.test.ts`. Total repo-core: 279 → 293.
+
+### Added — `tenant` subpath (canonical home for tenant scope contract)
+
+New subpath `@classytic/repo-core/tenant` ships:
+- `TenantConfig` — static config (`strategy`, `enabled`, `tenantField`, `fieldType`, `ref`, `contextKey`, `required`, `resolve`).
+- `TenantStrategy = 'field' | 'none' | 'custom'`, `TenantFieldType = 'objectId' | 'string'`.
+- `ResolvedTenantConfig` — the resolved-with-defaults shape returned by `resolveTenantConfig`.
+- `DEFAULT_TENANT_CONFIG` — sensible org-wide defaults (`tenantField: 'organizationId'`, `fieldType: 'objectId'`, `ref: 'organization'`, `required: true`).
+- `resolveTenantConfig(config?)` — normaliser; validates `'custom'` strategy requires `resolve`.
+
+Relocated from `@classytic/primitives/tenant` (which has been removed in primitives 0.3 cleanup). Tenant scope is **infrastructure-shaped** — describes how queries get scoped, not a domain primitive like Money or Address. Repo-core is its proper home: it sits next to `context`, `filter`, `hooks`, `schema`, `cache` — every other repository contract — and lets mongokit / sqlitekit / future kits consume it through the existing `@classytic/repo-core` peer dep without pulling primitives just for one type.
+
+**Custom tenancy escape hatch** unchanged: `strategy: 'custom'` + `resolve: (ctx) => filterShape` covers multi-field composites, region+partner shards, hash-derived filters, anything that doesn't fit `field === id`.
+
+14 new tests in `tests/unit/tenant/resolve.test.ts` (ported from primitives' suite). Total repo-core: 265 → 279 tests.
+
+### Added — schema-builder vocabulary
+
+- **`SchemaBuilderOptions.excludeFields`** — global field exclusion. Fields listed here are dropped from create / update / response schemas in one place. Equivalent to setting `create.omitFields`, `update.omitFields`, AND `response.omitFields` to the same list. Use for fields that should never appear in any HTTP-facing schema.
+- **`SchemaBuilderOptions.response`** with `omitFields?: string[]` — response-schema overrides. Drops extra fields from the response shape without marking them globally hidden.
+- **`CrudSchemas.response?: JsonSchema`** — optional response-shape schema. Includes server-set fields (`createdAt`, `updatedAt`, `_id`, immutable / readonly / systemManaged) since those ARE returned to clients. Only `fieldRules[field].hidden: true` strips automatically. Set `additionalProperties: true` so virtuals / computed fields pass through.
+- **`FieldRule.hidden?: boolean`** — strips the field from the response shape. Distinct from `systemManaged` (request-body concern). Use for passwords, secrets, internal scoring.
+- **`collectFieldsToOmit(options, 'response')`** — third purpose alongside `'create'` / `'update'`. Implements the response policy (only `hidden` + `excludeFields` + `response.omitFields`).
+
+These are the contracts mongokit 3.12 implements, arc 2.12's MongooseAdapter consumes, and any future kit (sqlitekit, prismakit) inherits for free.
+
+### Hardened — `RepositoryBase` plugin-shape validation
+
+`RepositoryBase.use()` and the constructor's plugin loop now reject malformed plugin entries up front via `assertValidPlugin()`. The motivating field bug: `new Repository(Model, ['organizationId'], opts)` — passing a tenant-field string array where the constructor expected `plugins[]` — used to crash deep in the call site with `TypeError: plugin.apply is not a function`, cascade-failing every test that booted the app. The validator now throws a single descriptive `TypeError` at construction with the offending index and a hint about the common `tenantField`-in-the-wrong-slot mistake:
+
+```
+[repo-core] Repository "Foo": plugin at index 0 has wrong type.
+Expected a function or { name, apply(repo) } object — got string 'organizationId'.
+Common cause: `new Repository(Model, [tenantField], opts)` — second argument must be a plugins array.
+```
+
+Lock-in: `tests/unit/repository/base-plugin-validation.test.ts` (6 cases covering string/null/object-without-apply/function/object/post-construction `use()` paths).
+
+### Migration — mongokit 4.0, arc 2.12, arc-next 0.6
+
+Three downstream changes drop their local copies and import directly:
+
+1. **mongokit 4.0** — deletes its local `AggregatePaginationResult` declaration and `PaginationResult` union; consumers that imported them from `@classytic/mongokit` must switch to `@classytic/repo-core/pagination`. (Breaking.)
+2. **arc 2.12** — `fastifyAdapter` calls `toCanonicalList()` once instead of inline-flattening offset and falling through keyset/aggregate as nested `data`. Closes a real wire-envelope-mismatch bug.
+3. **arc-next 0.6** — adds `@classytic/repo-core` as peer dep, deletes its local `OffsetPaginationResponse` / `KeysetPaginationResponse` / `AggregatePaginationResponse` / `PaginatedResponse` types. Server and client now share one declaration — the `method` field asymmetry is impossible by construction.
+
+No breaking changes inside `@classytic/repo-core` itself — purely additive.
+
 ## [0.2.0] - 2026-04-22
 
 ### Added — Update IR (portable write-side primitive)

package/README.md

@@ -28,14 +28,34 @@ import { and, eq, gte, in_, like, buildTenantScope, matchFilter } from '@classyt
 // URL → ParsedQuery grammar. Backend frameworks (Express/Arc/Fastify) parse req.query here.
 import { parseUrl } from '@classytic/repo-core/query-parser';
 
-// Pagination primitives — cursor codec, keyset helpers, offset math.
-import { encodeCursor, decodeCursor, validateKeysetSort } from '@classytic/repo-core/pagination';
+// Pagination primitives — cursor codec, keyset helpers, offset math, the canonical
+// result types (`OffsetPaginationResult`, `KeysetPaginationResult`,
+// `AggregatePaginationResult`, `PaginationResult`) and the wire helper
+// `toCanonicalList()`. Single source of truth — primitives' duplicate dropped,
+// mongokit/sqlitekit re-export from here.
+import { encodeCursor, decodeCursor, validateKeysetSort, toCanonicalList } from '@classytic/repo-core/pagination';
+import type { OffsetPaginationResult, KeysetPaginationResult, AggregatePaginationResult, PaginationResult } from '@classytic/repo-core/pagination';
+
+// Tenant config — the canonical `TenantConfig`, `TenantStrategy`, `TenantFieldType`,
+// `resolveTenantConfig`, `DEFAULT_TENANT_CONFIG`, `ResolvedTenantConfig`. Kits'
+// `MultiTenantOptions extends Pick<TenantConfig, ...>`.
+import { resolveTenantConfig, DEFAULT_TENANT_CONFIG } from '@classytic/repo-core/tenant';
+import type { TenantConfig, ResolvedTenantConfig } from '@classytic/repo-core/tenant';
 
 // Cache plumbing — the CacheAdapter interface every kit's cachePlugin writes against.
 import { type CacheAdapter, stableStringify, createMemoryCacheAdapter } from '@classytic/repo-core/cache';
 
-// HTTP error envelope + duplicate-key contract.
-import { createError, conservativeMongoIsDuplicateKey } from '@classytic/repo-core/errors';
+// Error contracts — `HttpError` throwable + `ErrorContract` wire shape +
+// `ErrorDetail` + `ErrorCode` + `ERROR_CODES` + `toErrorContract()` +
+// `statusToErrorCode()`. Single source of truth — primitives' errors module dropped,
+// mongokit's local `HttpError` dropped, `ArcError implements HttpError`.
+import { toErrorContract, statusToErrorCode, ERROR_CODES, createError, conservativeMongoIsDuplicateKey } from '@classytic/repo-core/errors';
+import type { HttpError, ErrorContract, ErrorDetail, ErrorCode } from '@classytic/repo-core/errors';
+
+// Schema generator interface — kits ship `SchemaGenerator<TModel>` + the
+// compile-time conformance assertion; arc adapters are typed against it.
+import type { SchemaGenerator, SchemaGeneratorContext } from '@classytic/repo-core/schema';
+import { isSchemaGenerator } from '@classytic/repo-core/schema';
 
 // Operation registry (for arc-level policy dispatch + doc generation).
 import { CORE_OP_REGISTRY, describe } from '@classytic/repo-core/operations';
@@ -141,11 +161,12 @@ Default `TExtra` is `Record<string, never>` — `OffsetPaginationResult<User>` b
 
 ## Status
 
-**v0.1.0 — initial release.**
+**v0.3.0 — canonical contracts release.** Pagination types + wire envelope, tenant config, error contracts, and the `SchemaGenerator<TModel>` interface relocated from primitives / mongokit / arc to single sources of truth here.
 
 Consumed by:
-- `@classytic/mongokit` ≥ 3.10 — `Repository extends RepositoryBase`; hook engine, plugin-order validator, `HOOK_PRIORITY` sourced from repo-core. Mongokit's own `QueryParser` remains standalone (emits Mongo `$`-objects) but implements the same URL grammar by convention.
-- `@classytic/sqlitekit` (in development) — `SqliteRepository extends RepositoryBase`; Filter IR compiled to Drizzle / raw SQL natively. Uses `parseUrl` directly for URL parsing.
+- `@classytic/mongokit` ≥ 3.12 — `Repository extends RepositoryBase`; hook engine, plugin-order validator, `HOOK_PRIORITY` sourced from repo-core. Pagination + `HttpError` types now flow from repo-core (mongokit's local copies dropped). `MultiTenantOptions extends Pick<TenantConfig, ...>`. `buildCrudSchemasFromModel` ships a compile-time `SchemaGenerator<TModel>` conformance assertion. Mongokit's own `QueryParser` remains standalone.
+- `@classytic/sqlitekit` ≥ 0.2 — `SqliteRepository extends RepositoryBase`; Filter IR compiled to Drizzle / raw SQL natively. `MultiTenantOptions extends Pick<TenantConfig, ...>`. `buildCrudSchemasFromTable` ships the same `SchemaGenerator` conformance assertion.
+- `@classytic/arc` ≥ 2.12 — adapters typed against `SchemaGenerator<TModel>`; `ArcError implements HttpError`; pagination wire envelope (`method` discriminant) emitted via `toCanonicalList()` with `reply.sendList()`.
 
 See [INFRA.md](./INFRA.md) for the architectural principles, subpath map, build/tooling decisions, and the roadmap for pgkit / prismakit.
 

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,5 @@
-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 };
+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 };

package/dist/errors/index.mjs

@@ -1,3 +1,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 { conservativeMongoIsDuplicateKey, createError, isHttpError, toDuplicateKeyHttpError };
+export { ERROR_CODES, conservativeMongoIsDuplicateKey, createError, isHttpError, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };

package/dist/errors/types.d.mts

@@ -1,12 +1,28 @@
 //#region src/errors/types.d.ts
 /**
- * HTTP-shaped error contract used across every driver kit.
+ * HTTP-shaped error contracts used across every driver kit, integrator,
+ * and HTTP-emitting service in the org.
  *
- * An `HttpError` is a plain `Error` with a `status` field and optional
- * structured fields for duplicate-key and validation conflicts. Kits
- * classify their driver-specific errors into this shape at the boundary,
- * so the framework layer (arc) never needs to know whether the error
- * originated from MongoDB `E11000`, Postgres `23505`, or Prisma `P2002`.
+ * **`@classytic/repo-core/errors` is the canonical home for the wire +
+ * throwable error contract.** Two complementary shapes live here:
+ *
+ *   - {@link HttpError} — the *throwable* shape. Plain `Error` with
+ *     `status` and optional structured fields. Kits classify their
+ *     driver-specific errors into this shape at the boundary; framework
+ *     layers (arc) catch and serialize.
+ *   - {@link ErrorContract} — the *wire* shape (RFC 7807 / Stripe-style).
+ *     What gets serialized into JSON responses, queue dead-letter records,
+ *     audit logs, and inter-service error envelopes.
+ *
+ * Throwable classes (arc's `ArcError` family, future `BillingError` etc.)
+ * `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
+ * can extend (`'order.validation.missing_line'`, `'payment.gateway.timeout'`).
+ * The canonical codes cover cross-cutting concerns; domain extensions
+ * hierarchically narrow.
  */
 /** Structured metadata for duplicate-key (unique-constraint) errors. */
 interface DuplicateKeyMeta {
@@ -24,14 +40,103 @@ interface ValidationErrorMeta {
   validator: string;
   error: string;
 }
-/** HTTP-shaped error — the envelope every repository error resolves to. */
+/**
+ * HTTP-shaped error — the throwable envelope every repository error and
+ * arc handler resolves to.
+ *
+ * Note: `code` and `meta` are optional but every long-lived production
+ * handler should populate them. `code` lets clients switch on
+ * machine-readable identifiers without grepping `message`; `meta` carries
+ * structured diagnostics safe for logs.
+ */
 interface HttpError extends Error {
   /** HTTP status code (400, 404, 409, 500, ...). */
   status: number;
+  /**
+   * Stable machine-readable error code. Use one of {@link ErrorCode} for
+   * cross-cutting cases or extend hierarchically with a domain prefix
+   * (`'order.validation.missing_line'`, `'payment.gateway.timeout'`).
+   * Hosts switch on this in catch blocks instead of regex-matching
+   * `message`.
+   */
+  code?: string;
+  /**
+   * Free-form structured metadata for diagnostics. Pairs with `code` so
+   * hosts can render a clearer message in their own UI without parsing
+   * `message`. Safe for logs (don't include PII).
+   */
+  meta?: Record<string, unknown>;
   /** Structured validation failures when `status` is 400. */
   validationErrors?: ValidationErrorMeta[];
   /** Structured duplicate-key metadata when `status` is 409. */
   duplicate?: DuplicateKeyMeta;
 }
+/**
+ * Standard error contract — a framework-agnostic JSON shape that maps
+ * cleanly to HTTP responses, worker failure logs, and inter-service
+ * errors. Loosely matches RFC 7807 (`application/problem+json`); shape
+ * matches Stripe / Shopify / Slack API conventions.
+ *
+ * Packages throw `HttpError` instances. Hosts (HTTP adapters, workers)
+ * serialize those errors into this shape on the wire via
+ * {@link toErrorContract}. Wire shape is FLAT (top-level `code` /
+ * `message` / `status`), not nested under `{ error: { ... } }` — matches
+ * the existing org-wide envelope convention. Hosts that need a
+ * Stripe-style nested envelope wrap once at the edge.
+ */
+interface ErrorContract {
+  /** Machine-readable, hierarchical code — e.g. `'order.validation.missing_line'`. */
+  code: string;
+  /** Human-readable, safe-for-client message. */
+  message: string;
+  /** Suggested HTTP status code — hosts may override. */
+  status?: number;
+  /**
+   * Field-scoped structured details. Populated for validation failures
+   * (one entry per offending field) or domain errors that map to multiple
+   * sub-codes. Distinct from `HttpError.validationErrors` (which is a
+   * mongokit-shaped throwable field) — the wire form is canonical.
+   */
+  details?: readonly ErrorDetail[];
+  /** Correlation / trace identifier for support lookups. */
+  correlationId?: string;
+  /** Non-PII metadata (safe to log, safe to return to clients). */
+  meta?: Readonly<Record<string, unknown>>;
+}
+/** A single field-scoped error detail. */
+interface ErrorDetail {
+  /** Dot-path pointer to the offending field, e.g. `'lines.0.quantity'`. */
+  path?: string;
+  code: string;
+  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, HttpError, ValidationErrorMeta };
+export { DuplicateKeyMeta, ERROR_CODES, ErrorCode, ErrorContract, ErrorDetail, HttpError, ValidationErrorMeta };

package/dist/errors/types.mjs

@@ -0,0 +1,29 @@
+//#region src/errors/types.ts
+/**
+* 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.
+*/
+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"
+};
+//#endregion
+export { ERROR_CODES };

package/dist/pagination/canonical.d.mts

@@ -0,0 +1,35 @@
+import { AnyPaginationResult, BareListResponse, PaginatedResponse } from "./types.mjs";
+
+//#region src/pagination/canonical.d.ts
+/**
+ * Type guard: is this value a paginated result envelope (vs a bare array
+ * or some other shape)?
+ *
+ * Checks for the `method` discriminant rather than `Array.isArray` so a
+ * paginated result whose `docs` field happens to contain zero items still
+ * routes through the paginated branch.
+ *
+ * Accepts `unknown` (rather than `T[] | AnyPaginationResult<T>`) so wire-
+ * boundary callers can guard arbitrary inputs without pre-narrowing — the
+ * arc / arc-next response pipeline routinely sees `{ docs: unknown[] }`
+ * shapes that are neither a bare array nor a paginated result, and forcing
+ * those callers to cast first defeats the guard's purpose.
+ */
+declare function isPaginatedResult<TDoc>(input: unknown): input is AnyPaginationResult<TDoc>;
+/**
+ * Normalise a list-shaped value into the canonical wire envelope.
+ *
+ * Overloads keep the return type tight:
+ *   - bare array  → {@link BareListResponse}
+ *   - paginated   → {@link PaginatedResponse} (preserves method discriminant)
+ *
+ * The mutable-array overload widens to `TDoc[]` because that's the most
+ * common server input (kit results return `TDoc[]` for `docs`); the
+ * readonly overload covers callers passing `readonly TDoc[]`.
+ */
+declare function toCanonicalList<TDoc>(input: TDoc[]): BareListResponse<TDoc>;
+declare function toCanonicalList<TDoc>(input: readonly TDoc[]): BareListResponse<TDoc>;
+declare function toCanonicalList<TDoc, TExtra extends Record<string, unknown>>(input: AnyPaginationResult<TDoc, TExtra>): PaginatedResponse<TDoc, TExtra>;
+declare function toCanonicalList<TDoc>(input: readonly TDoc[] | AnyPaginationResult<TDoc>): PaginatedResponse<TDoc>;
+//#endregion
+export { isPaginatedResult, toCanonicalList };

package/dist/pagination/canonical.mjs

@@ -0,0 +1,32 @@
+//#region src/pagination/canonical.ts
+/**
+* Type guard: is this value a paginated result envelope (vs a bare array
+* or some other shape)?
+*
+* Checks for the `method` discriminant rather than `Array.isArray` so a
+* paginated result whose `docs` field happens to contain zero items still
+* routes through the paginated branch.
+*
+* Accepts `unknown` (rather than `T[] | AnyPaginationResult<T>`) so wire-
+* boundary callers can guard arbitrary inputs without pre-narrowing — the
+* arc / arc-next response pipeline routinely sees `{ docs: unknown[] }`
+* shapes that are neither a bare array nor a paginated result, and forcing
+* those callers to cast first defeats the guard's purpose.
+*/
+function isPaginatedResult(input) {
+	if (typeof input !== "object" || input === null || Array.isArray(input)) return false;
+	const method = input.method;
+	return method === "offset" || method === "keyset" || method === "aggregate";
+}
+function toCanonicalList(input) {
+	if (isPaginatedResult(input)) return {
+		...input,
+		success: true
+	};
+	return {
+		success: true,
+		docs: [...input]
+	};
+}
+//#endregion
+export { isPaginatedResult, toCanonicalList };

package/dist/pagination/index.d.mts

@@ -1,5 +1,6 @@
-import { CursorPayload, DecodedCursor, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResult, OffsetPaginationResultCore, PaginationConfig, SortDirection, SortSpec, ValueType } from "./types.mjs";
+import { AggregatePaginationResponse, AggregatePaginationResult, AggregatePaginationResultCore, AnyPaginationResult, BareListResponse, CursorPayload, DecodedCursor, KeysetPaginationResponse, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResponse, OffsetPaginationResult, OffsetPaginationResultCore, PaginatedResponse, PaginationConfig, SortDirection, SortSpec, ValueType } from "./types.mjs";
+import { isPaginatedResult, toCanonicalList } from "./canonical.mjs";
 import { decodeCursor, encodeCursor, validateCursorSort, validateCursorVersion } from "./cursor.mjs";
 import { getPrimaryField, invertSort, normalizeSort, validateKeysetSort } from "./keyset.mjs";
 import { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./offset.mjs";
-export { type CursorPayload, type DecodedCursor, type KeysetPaginationResult, type KeysetPaginationResultCore, type OffsetPaginationResult, type OffsetPaginationResultCore, type PaginationConfig, type SortDirection, type SortSpec, type ValueType, calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, normalizeSort, shouldWarnDeepPagination, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };
+export { type AggregatePaginationResponse, type AggregatePaginationResult, type AggregatePaginationResultCore, type AnyPaginationResult, type BareListResponse, type CursorPayload, type DecodedCursor, type KeysetPaginationResponse, type KeysetPaginationResult, type KeysetPaginationResultCore, type OffsetPaginationResponse, type OffsetPaginationResult, type OffsetPaginationResultCore, type PaginatedResponse, type PaginationConfig, type SortDirection, type SortSpec, type ValueType, calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, isPaginatedResult, normalizeSort, shouldWarnDeepPagination, toCanonicalList, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };

package/dist/pagination/index.mjs

@@ -1,4 +1,5 @@
+import { isPaginatedResult, toCanonicalList } from "./canonical.mjs";
 import { decodeCursor, encodeCursor, validateCursorSort, validateCursorVersion } from "./cursor.mjs";
 import { getPrimaryField, invertSort, normalizeSort, validateKeysetSort } from "./keyset.mjs";
 import { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./offset.mjs";
-export { calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, normalizeSort, shouldWarnDeepPagination, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };
+export { calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, isPaginatedResult, normalizeSort, shouldWarnDeepPagination, toCanonicalList, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };