@classytic/primitives 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,130 @@
 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.1] - 2026-05-02
+
+### Added — state-machine ↔ mongokit/sqlitekit integration
+
+State-machine primitives now compose directly with the kit-level CAS surface shipped in mongokit 3.13 and the sqlitekit follow-up. Three additions:
+
+- **`StateMachine.validTargets(from)`** — every status the aggregate can move TO from `from`. Useful for UI dropdowns ("which actions are legal right now?") and for fanning a single source state into a multi-source CAS via a repo's `claim({ from: machine.validTargets(current), to })`.
+- **`StateMachine.validSources(to)`** — every status that can transition INTO `to` (reverse adjacency). Pair with a repo's multi-source `claim({ from: machine.validSources(to), to })` when the target is fixed but the caller doesn't yet know the current state — the canonical "cancel from any non-terminal" / "error from any in-flight" pattern. Pre-computed at definition time, O(1) lookup, frozen arrays safe to expose by reference.
+- **`assertAndClaim(machine, repo, id, args)`** — pairs `machine.assertTransition` (sync domain check) with `repo.claim()` (atomic CAS) in one call. The canonical state-machine-backed CAS pattern. Skipping either layer leaves a hole: skip `assertTransition` and bad transitions reach storage; skip `claim` and concurrent writers race.
+
+```ts
+import { defineStateMachine, assertAndClaim } from '@classytic/primitives/state-machine';
+
+const ORDER_MACHINE = defineStateMachine<OrderStatus>({
+  name: 'Order',
+  transitions: {
+    draft:     ['approved', 'cancelled'],
+    approved:  ['shipped', 'cancelled'],
+    shipped:   [],
+    cancelled: [],
+  },
+});
+
+// Single-source:
+const updated = await assertAndClaim(ORDER_MACHINE, orderRepo, orderId, {
+  from: 'draft',
+  to: 'approved',
+  patch: { approvedAt: new Date() },
+  options: { organizationId: ctx.organizationId, session },
+});
+
+// Multi-source via reverse adjacency — "cancel from any legal predecessor":
+await assertAndClaim(ORDER_MACHINE, orderRepo, orderId, {
+  from: ORDER_MACHINE.validSources('cancelled'), // ['draft', 'approved']
+  to: 'cancelled',
+  patch: { cancelledAt: new Date() },
+  options: { organizationId: ctx.organizationId },
+});
+```
+
+#### `ClaimableRepo<TDoc>` — structural dependency on the kit
+
+`assertAndClaim` accepts any object matching `ClaimableRepo<TDoc>` — a structural type that mirrors the mongokit 3.13 `Repository.claim()` signature. Primitives doesn't take a hard peer dep on mongokit; consumers wire the kit they want. Sqlitekit's `claim()` matches the same shape (verified by mongokit/sqlitekit cross-conformance).
+
+```ts
+export interface ClaimableRepo<TDoc> {
+  claim(
+    id: string,
+    transition: {
+      field?: string;
+      from: unknown | readonly unknown[];
+      to: unknown;
+      where?: Record<string, unknown>;
+    },
+    patch?: Record<string, unknown>,
+    options?: Record<string, unknown>,
+  ): Promise<TDoc | null>;
+}
+```
+
+#### Why a 0.3.1 (not 0.4.0)
+
+Purely additive — no removals, no signature changes. `defineStateMachine` callers from 0.3.0 see two new methods on the returned `StateMachine` (`validTargets`, `validSources`) and one new free function (`assertAndClaim`). Backwards-compatible.
+
+## [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

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

@@ -95,9 +95,89 @@ interface StateMachine<TStatus extends string> {
    * `entityId` is included in the error for traceability.
    */
   assertTransition(entityId: string, from: TStatus, to: TStatus): void;
+  /**
+   * Forward lookup — every status the aggregate can move TO from `from`.
+   * Useful for UI dropdowns ("which actions are legal right now?") and
+   * for fanning a single source state into a multi-source CAS via a
+   * repo's `claim({ from: machine.validTargets(current), to })`.
+   */
+  validTargets(from: TStatus): readonly TStatus[];
+  /**
+   * Reverse lookup — every status that can transition INTO `to`. Pair
+   * with a repo's multi-source `claim({ from: machine.validSources(to), to })`
+   * when the target is fixed but the caller doesn't yet know the
+   * current state (or wants to authorize ALL legal predecessors in one
+   * round-trip).
+   */
+  validSources(to: TStatus): readonly TStatus[];
   /** 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>;
+/**
+ * Minimal structural type for any kit's `claim()` operation. Lets
+ * `assertAndClaim` work against `@classytic/mongokit` (and future
+ * sqlitekit / pgkit) without primitives taking a hard peer dep.
+ *
+ * Mirrors the mongokit 3.13 `Repository.claim()` signature with
+ * `unknown`-typed values where the kit-specific shape (ObjectId, etc.)
+ * doesn't concern the state-machine layer.
+ */
+interface ClaimableRepo<TDoc> {
+  claim(id: string, transition: {
+    field?: string;
+    from: unknown | readonly unknown[];
+    to: unknown;
+    where?: Record<string, unknown>;
+  }, patch?: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc | null>;
+}
+/**
+ * Pair a state-machine `assertTransition()` (sync domain check) with a
+ * repo's `claim()` (runtime concurrency CAS) in one call. This is the
+ * canonical state-machine-backed CAS pattern documented in mongokit
+ * 3.13's CLAUDE.md.
+ *
+ *   - `assertTransition` rejects malformed transitions BEFORE we hit the
+ *     database (compile-time-typed targets, sync, fast).
+ *   - `claim` rejects concurrent writers AT the database (atomic
+ *     CAS, returns `null` on race-loss).
+ *
+ * Skipping either layer leaves a hole: skip `assertTransition` and bad
+ * transitions reach storage; skip `claim` and concurrent writers race.
+ *
+ * `from` accepts a single status OR an array of statuses (multi-source
+ * CAS). When the array form is used, `assertTransition` is asserted for
+ * EVERY listed source — a single illegal source aborts the call before
+ * the round-trip.
+ *
+ * @example Single-source
+ * ```ts
+ * const updated = await assertAndClaim(WAVE_MACHINE, repo, waveId, {
+ *   from: 'planned',
+ *   to: 'released',
+ *   patch: { releasedAt: new Date() },
+ *   options: { organizationId: ctx.organizationId, session },
+ * });
+ * if (!updated) throw new ConcurrencyError(); // race-loss
+ * ```
+ *
+ * @example Multi-source via `validSources`
+ * ```ts
+ * const updated = await assertAndClaim(WAVE_MACHINE, repo, waveId, {
+ *   from: WAVE_MACHINE.validSources('cancelled'), // every legal predecessor
+ *   to: 'cancelled',
+ *   patch: { cancelledAt: new Date() },
+ *   options: { organizationId: ctx.organizationId },
+ * });
+ * ```
+ */
+declare function assertAndClaim<TDoc, TStatus extends string>(machine: StateMachine<TStatus>, repo: ClaimableRepo<TDoc>, id: string, args: {
+  from: TStatus | readonly TStatus[];
+  to: TStatus;
+  field?: string;
+  patch?: Record<string, unknown>;
+  where?: Record<string, unknown>;
+  options?: Record<string, unknown>;
+}): Promise<TDoc | null>;
 //#endregion
-export { IllegalTransitionError, StateMachine, StateMachineDefinition, TransitionErrorContext, defineStateMachine };
+export { ClaimableRepo, IllegalTransitionError, StateMachine, StateMachineDefinition, TransitionErrorContext, assertAndClaim, defineStateMachine };

package/dist/state-machine.mjs

@@ -68,7 +68,18 @@ var IllegalTransitionError = class extends Error {
 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 reverse = /* @__PURE__ */ new Map();
+	for (const [status, allowed] of Object.entries(transitions)) {
+		if (allowed.length === 0) terminal.add(status);
+		for (const target of allowed) {
+			const sources = reverse.get(target);
+			if (sources) sources.push(status);
+			else reverse.set(target, [status]);
+		}
+	}
+	const frozenReverse = /* @__PURE__ */ new Map();
+	for (const [target, sources] of reverse) frozenReverse.set(target, Object.freeze(sources.slice()));
+	const EMPTY = Object.freeze([]);
 	const buildError = errorFactory ? errorFactory : (ctx) => new IllegalTransitionError(ctx.entityType, ctx.entityId, ctx.from, ctx.to);
 	return {
 		name,
@@ -87,8 +98,64 @@ function defineStateMachine(definition) {
 				from,
 				to
 			});
+		},
+		validTargets(from) {
+			return transitions[from] ?? EMPTY;
+		},
+		validSources(to) {
+			return frozenReverse.get(to) ?? EMPTY;
 		}
 	};
 }
+/**
+* Pair a state-machine `assertTransition()` (sync domain check) with a
+* repo's `claim()` (runtime concurrency CAS) in one call. This is the
+* canonical state-machine-backed CAS pattern documented in mongokit
+* 3.13's CLAUDE.md.
+*
+*   - `assertTransition` rejects malformed transitions BEFORE we hit the
+*     database (compile-time-typed targets, sync, fast).
+*   - `claim` rejects concurrent writers AT the database (atomic
+*     CAS, returns `null` on race-loss).
+*
+* Skipping either layer leaves a hole: skip `assertTransition` and bad
+* transitions reach storage; skip `claim` and concurrent writers race.
+*
+* `from` accepts a single status OR an array of statuses (multi-source
+* CAS). When the array form is used, `assertTransition` is asserted for
+* EVERY listed source — a single illegal source aborts the call before
+* the round-trip.
+*
+* @example Single-source
+* ```ts
+* const updated = await assertAndClaim(WAVE_MACHINE, repo, waveId, {
+*   from: 'planned',
+*   to: 'released',
+*   patch: { releasedAt: new Date() },
+*   options: { organizationId: ctx.organizationId, session },
+* });
+* if (!updated) throw new ConcurrencyError(); // race-loss
+* ```
+*
+* @example Multi-source via `validSources`
+* ```ts
+* const updated = await assertAndClaim(WAVE_MACHINE, repo, waveId, {
+*   from: WAVE_MACHINE.validSources('cancelled'), // every legal predecessor
+*   to: 'cancelled',
+*   patch: { cancelledAt: new Date() },
+*   options: { organizationId: ctx.organizationId },
+* });
+* ```
+*/
+async function assertAndClaim(machine, repo, id, args) {
+	const sources = Array.isArray(args.from) ? args.from : [args.from];
+	for (const from of sources) machine.assertTransition(id, from, args.to);
+	return repo.claim(id, {
+		from: Array.isArray(args.from) ? args.from : args.from,
+		to: args.to,
+		...args.field !== void 0 ? { field: args.field } : {},
+		...args.where !== void 0 ? { where: args.where } : {}
+	}, args.patch, args.options);
+}
 //#endregion
-export { IllegalTransitionError, defineStateMachine };
+export { IllegalTransitionError, assertAndClaim, defineStateMachine };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.2.0",
+  "version": "0.4.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"

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 };