@classytic/primitives 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,103 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-04-29
+
+### Removed — `/errors` subpath (BREAKING)
+
+- Deleted `@classytic/primitives/errors` (`ErrorContract`, `ErrorDetail`, `ErrorCode`, `ERROR_CODES`).
+- Errors are infrastructure-shaped (HTTP-coupled, repository-coupled, RFC 7807-shaped). Moved to `@classytic/repo-core/errors` where they sit next to `pagination`, `tenant`, `cache`, `hooks`, `schema` — every other repository contract — and join the existing `HttpError` throwable contract there. Single canonical home for both the wire (`ErrorContract`) and throwable (`HttpError`) shapes.
+
+#### Migration
+
+```diff
+- import type { ErrorContract, ErrorDetail, ErrorCode } from '@classytic/primitives/errors';
+- import { ERROR_CODES } from '@classytic/primitives/errors';
++ import type { ErrorContract, ErrorDetail, ErrorCode } from '@classytic/repo-core/errors';
++ import { ERROR_CODES } from '@classytic/repo-core/errors';
+```
+
+Field shapes and code values are unchanged — pure relocation.
+
+### Removed — `/tenant` subpath (BREAKING)
+
+- Deleted `@classytic/primitives/tenant` (`TenantConfig`, `TenantStrategy`, `TenantFieldType`, `DEFAULT_TENANT_CONFIG`, `resolveTenantConfig`, `ResolvedTenantConfig`).
+- Tenant scope is **infrastructure-shaped** (describes how queries get scoped to a database / repository), not a domain primitive like Money or Address. Moved to `@classytic/repo-core/tenant` where it sits next to `context`, `filter`, `hooks`, `schema`, `cache` — every other repository contract.
+- Mongokit and sqlitekit already peer-dep `@classytic/repo-core`, so consuming `TenantConfig` from there costs zero extra peer deps for those kits.
+
+#### Migration
+
+```diff
+- import type { TenantConfig } from '@classytic/primitives/tenant';
+- import { resolveTenantConfig, DEFAULT_TENANT_CONFIG } from '@classytic/primitives/tenant';
++ import type { TenantConfig } from '@classytic/repo-core/tenant';
++ import { resolveTenantConfig, DEFAULT_TENANT_CONFIG } from '@classytic/repo-core/tenant';
+```
+
+Field shapes, runtime semantics, and defaults are unchanged. The custom-strategy escape hatch (`strategy: 'custom'` + `resolve: (ctx) => filterShape`) works identically.
+
+### Removed — `/pagination` subpath (BREAKING)
+
+- Deleted `@classytic/primitives/pagination` (`PageParams`, `KeysetParams`, `SortSpec`, `SortDirection`, `OffsetPage<T>`, `KeysetPage<T>`, `AggregatePage<T>`, `emptyOffsetPage`, `emptyKeysetPage`).
+- Pagination shapes are owned by **`@classytic/repo-core/pagination`** — that package ships both the types AND the cursor encoding/skip-math/keyset-validation algorithms. Primitives' duplicate type-only declarations existed before the contract was canonised in repo-core; keeping them invited drift.
+
+### Migration
+
+```diff
+- import type { OffsetPage, KeysetPage, AggregatePage, SortSpec } from '@classytic/primitives/pagination';
++ import type {
++   OffsetPaginationResult,
++   KeysetPaginationResult,
++   AggregatePaginationResult,
++   SortSpec,
++ } from '@classytic/repo-core/pagination';
+```
+
+Note: shape names also changed (`OffsetPage` → `OffsetPaginationResult`, etc.) to match repo-core's naming. Field names align with what mongokit, sqlitekit, and arc already produced — those packages always returned repo-core shapes; primitives' types were a parallel, never-quite-aligned vocabulary.
+
+If you also need HTTP wire envelopes (`{ success: true } & Result`), repo-core 0.3.0 ships `OffsetPaginationResponse`, `KeysetPaginationResponse`, `AggregatePaginationResponse`, `BareListResponse`, `PaginatedResponse`, plus a `toCanonicalList()` runtime normalizer.
+
+### Why now (and why this is the only breaking change in this release)
+
+Two layers of pagination shapes drifted across the org: primitives declared one set, repo-core declared a different set, mongokit + sqlitekit + arc all consumed repo-core's. Removing primitives' set is purely subtractive — nobody internally imports from `@classytic/primitives/pagination`, and external consumers get a clear migration path to repo-core. No new ground to break later.
+
+## [0.2.0]
+
+### Added
+
+- **`/state-machine` subpath** — `defineStateMachine<TStatus>({ name, transitions, errorFactory? })`
+  declarative state-transition primitive. Replaces hand-rolled
+  `if (status === 'X') throw` blocks across kernels:
+
+  ```typescript
+  import { defineStateMachine } from '@classytic/primitives/state-machine';
+
+  const ORDER_MACHINE = defineStateMachine<OrderStatus>({
+    name: 'Order',
+    transitions: {
+      draft: ['approved', 'cancelled'],
+      approved: ['shipped', 'cancelled'],
+      shipped: [],
+      cancelled: [],
+    },
+  });
+
+  ORDER_MACHINE.assertTransition('order-1', 'draft', 'approved'); // OK
+  ORDER_MACHINE.assertTransition('order-1', 'shipped', 'draft');  // throws
+  ORDER_MACHINE.canTransition('draft', 'shipped');                // false
+  ORDER_MACHINE.isTerminal('shipped');                            // true
+  ```
+
+  Generic over the status string-union — `Record<TStatus, readonly TStatus[]>`
+  on `transitions` enforces exhaustiveness at the call site. Kernels with their
+  own typed transition error class (e.g. flow's `InvalidTransitionError`) wire
+  it via `errorFactory` so the thrown type stays domain-consistent. Standalone
+  callers get the bundled `IllegalTransitionError` (carries `entityType` /
+  `entityId` / `from` / `to` + `code: 'illegal_transition'` + `status: 422`).
+
+  First consumer: `@classytic/flow` `PROCUREMENT_MACHINE` (procurement-order
+  approve / cancel transitions).
+
 ## [0.1.1]
 
 ### Added

package/README.md

@@ -4,9 +4,30 @@ Framework-agnostic TypeScript primitives shared across Classytic packages.
 Zero runtime dependencies. ESM only. Node 22+.
 
 These are the building blocks every Classytic package speaks in common:
-`Money`, `DomainEvent`, `TenantConfig`, `OperationContext`, pagination shapes,
-polymorphic references. When a package duplicates one of these shapes, it
-drifts — this package exists so it doesn't.
+`Money`, `DomainEvent`, `OperationContext`, polymorphic references. When a
+package duplicates one of these shapes, it drifts — this package exists so it
+doesn't.
+
+> **Canonical-contract relocations in 0.3.0.** Three modules moved out to
+> `@classytic/repo-core` so kits and arc see one source of truth instead of
+> two:
+> - **Pagination** (`OffsetPaginationResult`, `KeysetPaginationResult`,
+>   `AggregatePaginationResult`, `PaginationResult`, `toCanonicalList()`) →
+>   `@classytic/repo-core/pagination`.
+> - **Tenant config** (`TenantConfig`, `TenantStrategy`, `TenantFieldType`,
+>   `resolveTenantConfig`, `DEFAULT_TENANT_CONFIG`, `ResolvedTenantConfig`) →
+>   `@classytic/repo-core/tenant`. Mongokit and sqlitekit's
+>   `MultiTenantOptions extends Pick<TenantConfig, ...>`.
+> - **Error contracts** (`HttpError` throwable, `ErrorContract` wire shape,
+>   `ErrorDetail`, `ErrorCode`, `ERROR_CODES`, `toErrorContract()`,
+>   `statusToErrorCode()`) → `@classytic/repo-core/errors`.
+>   `ArcError implements HttpError`.
+>
+> Events stay here. `@classytic/primitives/events` remains the canonical
+> source for `EventMeta`, `DomainEvent`, `EventHandler`, `EventLogger`,
+> `EventTransport`, `DeadLetteredEvent`, `PublishManyResult`, `createEvent`,
+> `createChildEvent`, `matchEventPattern`. Arc 2.12 re-exports only the
+> runtime `MemoryEventTransport`.
 
 ## Install
 
@@ -22,10 +43,14 @@ at compile time, runtime helpers are tiny.
 ```ts
 import { addMoney, fromMajor, type Money } from '@classytic/primitives/money';
 import { createEvent, type DomainEvent, type EventTransport } from '@classytic/primitives/events';
-import { resolveTenantConfig, type TenantConfig } from '@classytic/primitives/tenant';
 import type { OperationContext } from '@classytic/primitives/context';
-import type { OffsetPage, PageParams } from '@classytic/primitives/pagination';
 import { allocate, type SplitResult } from '@classytic/primitives/split-allocation';
+// Tenant config, error contracts, and pagination now live in repo-core:
+import { resolveTenantConfig, type TenantConfig } from '@classytic/repo-core/tenant';
+import type { HttpError, ErrorContract } from '@classytic/repo-core/errors';
+import type {
+  OffsetPaginationResult, KeysetPaginationResult, AggregatePaginationResult,
+} from '@classytic/repo-core/pagination';
 ```
 
 There is intentionally **no root barrel** — a barrel forces the Node ESM
@@ -41,14 +66,11 @@ subpath imports only.
 | `/currency` | `CurrencyCode` brand, `CURRENCIES`, `MINOR_UNIT_FACTOR`, `minorUnitFactor`, `toCurrencyCode`, `isCurrencyCode` |
 | `/address` | `Address`, `ContactAddress`, `GeoPoint`, `GeoJsonPoint`, `toGeoJsonPoint`, `fromGeoJsonPoint` |
 | `/period` | `DateRange`, `Period`, `isDateRange`, `isWithin`, `rangeDurationMs` |
-| `/pagination` | `PageParams`, `KeysetParams`, `SortSpec`, `SortDirection`, `OffsetPage<T>`, `KeysetPage<T>`, `AggregatePage<T>`, `emptyOffsetPage`, `emptyKeysetPage` |
 | `/reference` | `ExternalRef`, `ObjectIdLike`, `IdLike`, `DocumentRef`, `idToString`, `isExternalRef` |
 | `/context` | `OperationContext`, `ActorRef` |
-| `/events` | `DomainEvent`, `EventMeta`, `EventHandler`, `EventTransport`, `createEvent`, `matchEventPattern` |
-| `/tenant` | `TenantConfig`, `TenantFieldType`, `DEFAULT_TENANT_CONFIG`, `resolveTenantConfig` |
+| `/events` | `DomainEvent`, `EventMeta`, `EventHandler`, `EventLogger`, `EventTransport`, `DeadLetteredEvent`, `PublishManyResult`, `createEvent`, `createChildEvent`, `matchEventPattern` |
 | `/result` | `Result<T, E>`, `ok`, `err`, `isOk`, `isErr`, `mapResult`, `mapError`, `unwrap` |
 | `/brand` | `Brand<T, B>`, `Prettify`, `DeepPartial`, `DeepReadonly`, `RequireKeys`, `OptionalKeys`, `Nullable`, `KeysMatching`, `NonEmptyArray` |
-| `/errors` | `ErrorContract`, `ErrorDetail`, `ErrorCode`, `ERROR_CODES` |
 | `/split-allocation` | `allocate`, `isBalanced`, `SplitAllocationError`, `SplitMethod`, `SplitSubject`, `SplitPart`, `SplitResult` |
 | `/approval` | `createChain`, `applyDecision`, `skipStep`, `nextPendingStep`, `pendingSteps`, `isApproved`, `isRejected`, `isPending`, `decisionCount`, `ApprovalError`, `ApprovalChain`, `ApprovalStep`, `ApprovalDecision`, `Approver`, `ApprovalThreshold` |
 | `/cadence` | `nextOccurrence`, `occurrencesBetween`, `validateCadence`, `CadenceError`, `Cadence`, `DailyCadence`, `WeeklyCadence`, `MonthlyCadence`, `YearlyCadence`, `CronCadence`, `IsoWeekday` |
@@ -91,21 +113,19 @@ Shape matches `@classytic/arc`'s `DomainEvent` exactly — any Arc transport
 (memory, Redis pub/sub, Redis Streams, Kafka) plugs into a package expecting
 this interface without adapters. See PACKAGE_RULES.md §11.
 
-### TenantConfig — one shape, every package
+### TenantConfig — moved to `@classytic/repo-core/tenant`
 
 ```ts
-import { resolveTenantConfig } from '@classytic/primitives/tenant';
+import { resolveTenantConfig } from '@classytic/repo-core/tenant';
 
 const tenant = resolveTenantConfig(config.tenant);
 // { enabled: true, tenantField: 'organizationId', fieldType: 'objectId',
 //   ref: 'organization', contextKey: 'organizationId', required: true }
 ```
 
-Field names match `@classytic/mongokit`'s `MultiTenantOptions` so you can
-forward the resolved config straight into `multiTenantPlugin(resolved)`.
-
-Packages stop rolling five flavours of `{ field, type, ref, contextKey,
-enabled }`.
+Mongokit's `MultiTenantOptions` and sqlitekit's equivalent both
+`extends Pick<TenantConfig, ...>` from repo-core — pass the resolved config
+straight into `multiTenantPlugin(resolved)`.
 
 ### ExternalRef — polymorphic, framework-free
 
@@ -127,7 +147,8 @@ ObjectId, UUID, Stripe ID, anything. See PACKAGE_RULES.md §7.
 - **Transaction / Order / Cart shapes** — those are domain types, not
   primitives. They live in their respective packages.
 - **Error subclasses** — throw plain `Error`s; hosts serialize them into
-  `ErrorContract` at the HTTP boundary.
+  `ErrorContract` (from `@classytic/repo-core/errors`) at the HTTP boundary
+  via `toErrorContract(err)`.
 - **Runtime currency database** — ship a whitelist at the app layer if you
   need one. `MINOR_UNIT_FACTOR` covers common cases.
 

package/dist/person.mjs

@@ -10,7 +10,7 @@ function formatFullName(name) {
 }
 function formatDisplayName(name) {
 	if (name.preferred?.trim()) return name.preferred;
-	return `${name.given} ${name.family}`.trim();
+	return [name.given, name.family].filter((p) => Boolean(p?.trim())).join(" ");
 }
 //#endregion
 export { formatDisplayName, formatFullName };

package/dist/state-machine.d.mts

@@ -0,0 +1,103 @@
+//#region src/state-machine.d.ts
+/**
+ * Declarative state-machine primitive.
+ *
+ * Replaces hand-rolled `if (status === 'X') throw` blocks scattered
+ * across domain services. Each aggregate declares one transition table;
+ * the helper provides `canTransition` / `assertTransition` / `isTerminal`
+ * accessors that the services share.
+ *
+ * Generic over the status string-union so calls stay type-safe:
+ *   `defineStateMachine<ProcurementStatus>({ name: 'ProcurementOrder', transitions: { … } })`
+ * The TS compiler enforces exhaustiveness — every status string in the
+ * union MUST have an entry in `transitions` (terminal statuses map to `[]`).
+ *
+ * @example
+ * import { defineStateMachine } from '@classytic/primitives/state-machine';
+ *
+ * type OrderStatus = 'draft' | 'approved' | 'shipped' | 'cancelled';
+ * const ORDER_MACHINE = defineStateMachine<OrderStatus>({
+ *   name: 'Order',
+ *   transitions: {
+ *     draft: ['approved', 'cancelled'],
+ *     approved: ['shipped', 'cancelled'],
+ *     shipped: [],
+ *     cancelled: [],
+ *   },
+ * });
+ *
+ * ORDER_MACHINE.assertTransition('order-1', 'draft', 'approved'); // OK
+ * ORDER_MACHINE.assertTransition('order-1', 'shipped', 'draft');  // throws
+ * ORDER_MACHINE.canTransition('draft', 'shipped');                // false
+ * ORDER_MACHINE.isTerminal('shipped');                            // true
+ *
+ * Hosts that already have their own typed transition error can swap it
+ * in via `errorFactory`:
+ *
+ * @example
+ * import { InvalidTransitionError } from './errors.js';
+ * const FLOW_MACHINE = defineStateMachine<MoveStatus>({
+ *   name: 'StockMove',
+ *   transitions: { … },
+ *   errorFactory: ({ entityType, entityId, from, to }) =>
+ *     new InvalidTransitionError(entityType, entityId, from, to),
+ * });
+ */
+/**
+ * Default error thrown by `assertTransition` when no `errorFactory` is
+ * supplied. Carries the structured fields (`entityType`, `entityId`,
+ * `from`, `to`) plus a stable `code` so hosts can pattern-match on
+ * either `instanceof` or `error.code === 'illegal_transition'`.
+ */
+declare class IllegalTransitionError extends Error {
+  readonly code: "illegal_transition";
+  readonly status = 422;
+  readonly entityType: string;
+  readonly entityId: string;
+  readonly from: string;
+  readonly to: string;
+  constructor(entityType: string, entityId: string, from: string, to: string);
+}
+interface TransitionErrorContext {
+  readonly entityType: string;
+  readonly entityId: string;
+  readonly from: string;
+  readonly to: string;
+}
+interface StateMachineDefinition<TStatus extends string> {
+  /** Aggregate name surfaced in the thrown error's `entityType`. */
+  name: string;
+  /**
+   * Adjacency list — for each status, the set of statuses you can
+   * legally transition TO. Terminal statuses map to an empty array.
+   * `Record<TStatus, …>` enforces exhaustiveness at the call site.
+   */
+  transitions: Record<TStatus, readonly TStatus[]>;
+  /**
+   * Optional custom error factory. When omitted, `assertTransition`
+   * throws `IllegalTransitionError`. Hosts that own a domain error
+   * (e.g. flow's `InvalidTransitionError`) wire their own here so the
+   * thrown type stays consistent with the rest of the package.
+   */
+  errorFactory?: (ctx: TransitionErrorContext) => Error;
+}
+interface StateMachine<TStatus extends string> {
+  /** The aggregate name (`StockMove`, `ProcurementOrder`, etc.). */
+  readonly name: string;
+  /** All terminal statuses (no outgoing transitions). */
+  readonly terminal: ReadonlySet<TStatus>;
+  /** True when `from → to` is in the transition table. */
+  canTransition(from: TStatus, to: TStatus): boolean;
+  /** True when `status` is terminal. */
+  isTerminal(status: TStatus): boolean;
+  /**
+   * Throw a transition error when `from → to` isn't allowed.
+   * `entityId` is included in the error for traceability.
+   */
+  assertTransition(entityId: string, from: TStatus, to: TStatus): void;
+  /** The raw transition table — exposed read-only for advanced callers. */
+  readonly transitions: Readonly<Record<TStatus, readonly TStatus[]>>;
+}
+declare function defineStateMachine<TStatus extends string>(definition: StateMachineDefinition<TStatus>): StateMachine<TStatus>;
+//#endregion
+export { IllegalTransitionError, StateMachine, StateMachineDefinition, TransitionErrorContext, defineStateMachine };

package/dist/state-machine.mjs

@@ -0,0 +1,94 @@
+//#region src/state-machine.ts
+/**
+* Declarative state-machine primitive.
+*
+* Replaces hand-rolled `if (status === 'X') throw` blocks scattered
+* across domain services. Each aggregate declares one transition table;
+* the helper provides `canTransition` / `assertTransition` / `isTerminal`
+* accessors that the services share.
+*
+* Generic over the status string-union so calls stay type-safe:
+*   `defineStateMachine<ProcurementStatus>({ name: 'ProcurementOrder', transitions: { … } })`
+* The TS compiler enforces exhaustiveness — every status string in the
+* union MUST have an entry in `transitions` (terminal statuses map to `[]`).
+*
+* @example
+* import { defineStateMachine } from '@classytic/primitives/state-machine';
+*
+* type OrderStatus = 'draft' | 'approved' | 'shipped' | 'cancelled';
+* const ORDER_MACHINE = defineStateMachine<OrderStatus>({
+*   name: 'Order',
+*   transitions: {
+*     draft: ['approved', 'cancelled'],
+*     approved: ['shipped', 'cancelled'],
+*     shipped: [],
+*     cancelled: [],
+*   },
+* });
+*
+* ORDER_MACHINE.assertTransition('order-1', 'draft', 'approved'); // OK
+* ORDER_MACHINE.assertTransition('order-1', 'shipped', 'draft');  // throws
+* ORDER_MACHINE.canTransition('draft', 'shipped');                // false
+* ORDER_MACHINE.isTerminal('shipped');                            // true
+*
+* Hosts that already have their own typed transition error can swap it
+* in via `errorFactory`:
+*
+* @example
+* import { InvalidTransitionError } from './errors.js';
+* const FLOW_MACHINE = defineStateMachine<MoveStatus>({
+*   name: 'StockMove',
+*   transitions: { … },
+*   errorFactory: ({ entityType, entityId, from, to }) =>
+*     new InvalidTransitionError(entityType, entityId, from, to),
+* });
+*/
+/**
+* Default error thrown by `assertTransition` when no `errorFactory` is
+* supplied. Carries the structured fields (`entityType`, `entityId`,
+* `from`, `to`) plus a stable `code` so hosts can pattern-match on
+* either `instanceof` or `error.code === 'illegal_transition'`.
+*/
+var IllegalTransitionError = class extends Error {
+	code = "illegal_transition";
+	status = 422;
+	entityType;
+	entityId;
+	from;
+	to;
+	constructor(entityType, entityId, from, to) {
+		super(`Invalid transition for ${entityType} ${entityId}: ${from} → ${to}`);
+		this.name = "IllegalTransitionError";
+		this.entityType = entityType;
+		this.entityId = entityId;
+		this.from = from;
+		this.to = to;
+	}
+};
+function defineStateMachine(definition) {
+	const { name, transitions, errorFactory } = definition;
+	const terminal = /* @__PURE__ */ new Set();
+	for (const [status, allowed] of Object.entries(transitions)) if (allowed.length === 0) terminal.add(status);
+	const buildError = errorFactory ? errorFactory : (ctx) => new IllegalTransitionError(ctx.entityType, ctx.entityId, ctx.from, ctx.to);
+	return {
+		name,
+		terminal,
+		transitions,
+		canTransition(from, to) {
+			return transitions[from]?.includes(to) ?? false;
+		},
+		isTerminal(status) {
+			return terminal.has(status);
+		},
+		assertTransition(entityId, from, to) {
+			if (!transitions[from]?.includes(to)) throw buildError({
+				entityType: name,
+				entityId,
+				from,
+				to
+			});
+		}
+	};
+}
+//#endregion
+export { IllegalTransitionError, defineStateMachine };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -37,10 +37,6 @@
       "types": "./dist/period.d.mts",
       "default": "./dist/period.mjs"
     },
-    "./pagination": {
-      "types": "./dist/pagination.d.mts",
-      "default": "./dist/pagination.mjs"
-    },
     "./reference": {
       "types": "./dist/reference.d.mts",
       "default": "./dist/reference.mjs"
@@ -57,10 +53,6 @@
       "types": "./dist/outbox.d.mts",
       "default": "./dist/outbox.mjs"
     },
-    "./tenant": {
-      "types": "./dist/tenant.d.mts",
-      "default": "./dist/tenant.mjs"
-    },
     "./result": {
       "types": "./dist/result.d.mts",
       "default": "./dist/result.mjs"
@@ -69,10 +61,6 @@
       "types": "./dist/brand.d.mts",
       "default": "./dist/brand.mjs"
     },
-    "./errors": {
-      "types": "./dist/errors.d.mts",
-      "default": "./dist/errors.mjs"
-    },
     "./split-allocation": {
       "types": "./dist/split-allocation.d.mts",
       "default": "./dist/split-allocation.mjs"
@@ -97,6 +85,10 @@
       "types": "./dist/person.d.mts",
       "default": "./dist/person.mjs"
     },
+    "./state-machine": {
+      "types": "./dist/state-machine.d.mts",
+      "default": "./dist/state-machine.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [

package/dist/errors.d.mts

@@ -1,50 +0,0 @@
-//#region src/errors.d.ts
-/**
- * Standard error contract — a framework-agnostic JSON shape that maps cleanly
- * to HTTP responses, worker failure logs, and inter-service errors. Matches
- * RFC 7807 (`application/problem+json`) loosely.
- *
- * Packages should throw `Error` instances. Hosts (HTTP adapters, workers)
- * serialize those errors into this shape on the wire.
- */
-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 validation errors. */
-  details?: ReadonlyArray<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>>;
-}
-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>>;
-}
-/**
- * Canonical error codes. Packages add their own (`order.validation.*`,
- * `payment.gateway.*`) — these are the cross-cutting ones.
- */
-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 { ERROR_CODES, ErrorCode, ErrorContract, ErrorDetail };

package/dist/errors.mjs

@@ -1,20 +0,0 @@
-//#region src/errors.ts
-/**
-* Canonical error codes. Packages add their own (`order.validation.*`,
-* `payment.gateway.*`) — these are the cross-cutting ones.
-*/
-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.d.mts

@@ -1,57 +0,0 @@
-//#region src/pagination.d.ts
-/**
- * Pagination and sorting primitives shared between repositories, HTTP
- * controllers, and SDKs. Shapes mirror `@classytic/mongokit`'s result types so
- * adapters can flow through without translation.
- */
-type SortDirection = 'asc' | 'desc' | 1 | -1;
-/**
- * Sort specification — accepts any of:
- *  - `'field'` / `'-field'` (Mongoose-style prefix)
- *  - `['field1', '-field2']`
- *  - `{ field1: 1, field2: -1 }`
- */
-type SortSpec = string | ReadonlyArray<string> | Readonly<Record<string, SortDirection>>;
-interface PageParams {
-  page?: number;
-  limit?: number;
-  sort?: SortSpec;
-}
-interface KeysetParams {
-  cursor?: string;
-  limit?: number;
-  sort?: SortSpec;
-}
-/**
- * Offset-paginated response. Mirrors `mongokit.OffsetPaginationResult<T>`.
- */
-interface OffsetPage<T> {
-  docs: ReadonlyArray<T>;
-  total: number;
-  page: number;
-  limit: number;
-  pages: number;
-  hasNext: boolean;
-  hasPrev: boolean;
-}
-/**
- * Cursor-paginated response. Mirrors `mongokit.KeysetPaginationResult<T>`.
- */
-interface KeysetPage<T> {
-  docs: ReadonlyArray<T>;
-  nextCursor: string | null;
-  prevCursor: string | null;
-  limit: number;
-}
-/** Aggregation-based pagination response. */
-interface AggregatePage<T> {
-  docs: ReadonlyArray<T>;
-  total: number;
-  page: number;
-  limit: number;
-  pages: number;
-}
-declare function emptyOffsetPage<T>(limit?: number): OffsetPage<T>;
-declare function emptyKeysetPage<T>(limit?: number): KeysetPage<T>;
-//#endregion
-export { AggregatePage, KeysetPage, KeysetParams, OffsetPage, PageParams, SortDirection, SortSpec, emptyKeysetPage, emptyOffsetPage };

package/dist/pagination.mjs

@@ -1,22 +0,0 @@
-//#region src/pagination.ts
-function emptyOffsetPage(limit = 20) {
-	return {
-		docs: [],
-		total: 0,
-		page: 1,
-		limit,
-		pages: 0,
-		hasNext: false,
-		hasPrev: false
-	};
-}
-function emptyKeysetPage(limit = 20) {
-	return {
-		docs: [],
-		nextCursor: null,
-		prevCursor: null,
-		limit
-	};
-}
-//#endregion
-export { emptyKeysetPage, emptyOffsetPage };

package/dist/tenant.d.mts

@@ -1,129 +0,0 @@
-//#region src/tenant.d.ts
-/**
- * Tenant / scope configuration primitives.
- *
- * Every multi-tenant-capable package accepts a config block shaped like
- * {@link TenantConfig}. It controls how the package stores and casts the
- * tenant identifier on its models, and which key on
- * `OperationContext` to read the tenant value from.
- *
- * Field names match `@classytic/mongokit`'s `MultiTenantOptions` so the
- * resolved config can be forwarded straight into `multiTenantPlugin(...)`.
- *
- * Three strategies are supported:
- * - `'field'` (default) — filter every query by a scalar field on documents.
- *   The common case; used by `multiTenantPlugin`.
- * - `'none'` — disable scoping entirely (single-tenant app). Equivalent to
- *   `enabled: false`; `strategy: 'none'` is the explicit form.
- * - `'custom'` — caller supplies a `resolve(ctx)` function that returns the
- *   filter shape to inject. Covers multi-field composite tenants, context-
- *   derived filters (region + partner id), or non-scalar scope keys.
- *
- * See PACKAGE_RULES.md §9 for the full pattern.
- */
-/**
- * Mongo storage type for the tenant identifier.
- *
- * - `'objectId'` (recommended for new packages) — `Schema.Types.ObjectId` with
- *   `ref`. Enables `$lookup`, `.populate()`, QueryParser `?lookup=...`.
- * - `'string'` — plain string. Use when the host auth system issues UUIDs or
- *   slugs rather than ObjectIds.
- */
-type TenantFieldType = 'objectId' | 'string';
-/** Scope resolution strategy. */
-type TenantStrategy = 'field' | 'none' | 'custom';
-interface TenantConfig {
-  /**
-   * Scope strategy. Omit for the common `'field'` case — explicit `'none'`
-   * / `'custom'` lets packages collapse what used to live in a separate
-   * `ScopeConfig` type.
-   *
-   * @default 'field'
-   */
-  strategy?: TenantStrategy;
-  /**
-   * Whether tenant scoping is active. When `false`, the package runs in
-   * single-tenant mode — no filter injection, no tenant field on documents.
-   * Equivalent to `strategy: 'none'`.
-   *
-   * @default true
-   */
-  enabled?: boolean;
-  /**
-   * Document field name that stores the tenant id. Matches mongokit's
-   * `MultiTenantOptions.tenantField`. Used when `strategy === 'field'`.
-   *
-   * @default 'organizationId'
-   */
-  tenantField?: string;
-  /**
-   * How to store / cast the tenant id. Matches mongokit's `fieldType`.
-   *
-   * @default 'objectId'
-   */
-  fieldType?: TenantFieldType;
-  /**
-   * Mongoose ref for `'objectId'` types. Ignored when `fieldType === 'string'`.
-   *
-   * @default 'organization'
-   */
-  ref?: string;
-  /**
-   * Which key on `OperationContext` to read the tenant id from.
-   *
-   * Defaults cascade: if omitted, falls back to the caller's `tenantField`
-   * (if supplied), else to `'organizationId'`. Rationale: when a host renames
-   * `tenantField` to e.g. `'branchId'`, their `OperationContext` almost always
-   * carries the value under the same key — so mirroring `tenantField` is the
-   * least-surprise behavior. Override explicitly if the context key diverges
-   * from the document field (e.g. `tenantField: 'branchId'`, `contextKey: 'organizationId'`).
-   *
-   * @default tenantField ?? 'organizationId'
-   */
-  contextKey?: string;
-  /**
-   * Whether the field is required. When `false`, the package permits
-   * unscoped / cross-tenant reads (typically only for admin paths).
-   *
-   * @default true
-   */
-  required?: boolean;
-  /**
-   * Custom resolver — called when `strategy === 'custom'` to produce the
-   * filter object injected into queries. Packages pass the request context;
-   * the resolver returns the filter shape.
-   *
-   * Example:
-   * ```ts
-   * {
-   *   strategy: 'custom',
-   *   resolve: (ctx) => ({
-   *     organizationId: ctx.organizationId,
-   *     region: ctx.region,
-   *   }),
-   * }
-   * ```
-   */
-  resolve?: (ctx: Record<string, unknown>) => Record<string, unknown>;
-}
-/** Sensible defaults for a freshly-built package (field strategy). */
-declare const DEFAULT_TENANT_CONFIG: Required<Pick<TenantConfig, 'strategy' | 'enabled' | 'tenantField' | 'fieldType' | 'ref' | 'contextKey' | 'required'>>;
-/**
- * Resolved shape returned by {@link resolveTenantConfig}. Always includes the
- * field defaults (so packages can inspect field names even when `enabled:
- * false`) and threads `resolve` when `strategy === 'custom'`.
- */
-type ResolvedTenantConfig = typeof DEFAULT_TENANT_CONFIG & {
-  resolve?: TenantConfig['resolve'];
-};
-/**
- * Resolve a possibly-partial {@link TenantConfig} against the defaults.
- *
- * - `false` → `enabled: false`, `strategy: 'none'`.
- * - `true` / `undefined` → default field strategy.
- * - Object with `strategy: 'custom'` → `resolve` is required; throws otherwise.
- * - Object with `strategy: 'none'` → `enabled: false`.
- */
-declare function resolveTenantConfig(config?: TenantConfig | boolean): ResolvedTenantConfig;
-//#endregion
-export { DEFAULT_TENANT_CONFIG, ResolvedTenantConfig, TenantConfig, TenantFieldType, TenantStrategy, resolveTenantConfig };

package/dist/tenant.mjs

@@ -1,58 +0,0 @@
-//#region src/tenant.ts
-/** Sensible defaults for a freshly-built package (field strategy). */
-const DEFAULT_TENANT_CONFIG = {
-	strategy: "field",
-	enabled: true,
-	tenantField: "organizationId",
-	fieldType: "objectId",
-	ref: "organization",
-	contextKey: "organizationId",
-	required: true
-};
-/**
-* Resolve a possibly-partial {@link TenantConfig} against the defaults.
-*
-* - `false` → `enabled: false`, `strategy: 'none'`.
-* - `true` / `undefined` → default field strategy.
-* - Object with `strategy: 'custom'` → `resolve` is required; throws otherwise.
-* - Object with `strategy: 'none'` → `enabled: false`.
-*/
-function resolveTenantConfig(config) {
-	if (config === false) return {
-		...DEFAULT_TENANT_CONFIG,
-		strategy: "none",
-		enabled: false,
-		required: false
-	};
-	if (config === true || config === void 0) return { ...DEFAULT_TENANT_CONFIG };
-	const strategy = config.strategy ?? (config.enabled === false ? "none" : "field");
-	const contextKey = config.contextKey ?? config.tenantField ?? DEFAULT_TENANT_CONFIG.contextKey;
-	if (strategy === "none") return {
-		...DEFAULT_TENANT_CONFIG,
-		...config,
-		contextKey,
-		strategy: "none",
-		enabled: false,
-		required: false
-	};
-	if (strategy === "custom") {
-		if (typeof config.resolve !== "function") throw new Error("[primitives] TenantConfig.strategy 'custom' requires a 'resolve' function");
-		return {
-			...DEFAULT_TENANT_CONFIG,
-			...config,
-			contextKey,
-			strategy: "custom",
-			enabled: config.enabled ?? true,
-			resolve: config.resolve
-		};
-	}
-	return {
-		...DEFAULT_TENANT_CONFIG,
-		...config,
-		contextKey,
-		strategy: "field",
-		enabled: config.enabled ?? true
-	};
-}
-//#endregion
-export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };