@classytic/primitives 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+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.1.0]
+
+Initial release. Framework-agnostic TypeScript primitives shared across
+Classytic packages. Zero runtime dependencies. Node 22+. ESM only.
+260 tests (unit + integration) across 20 files.
+
+All subpaths are importable independently; there is **no root barrel
+re-export** — consumers must use subpath imports (`@classytic/primitives/money`,
+`/events`, `/tenant`, …) to keep the Node ESM loader + TypeScript compiler
+from walking the full module graph on any convenience import.
+
+### Subpaths
+
+- **`/money`** — `Money` type + integer-minor-unit arithmetic (`money`,
+  `addMoney`, `subtractMoney`, `multiplyMoney`, `sumMoney`, `negateMoney`,
+  `absMoney`, `compareMoney`, `equalsMoney`, `isZeroMoney`, `isPositiveMoney`,
+  `isNegativeMoney`, `isMoney`, `fromMajor`, `toMajor`); `CurrencyMismatchError`.
+- **`/currency`** — `CurrencyCode` brand; `CURRENCIES` table; `MINOR_UNIT_FACTOR`,
+  `minorUnitFactor`, `isCurrencyCode`, `toCurrencyCode`.
+- **`/address`** — `Address`, `ContactAddress`, `GeoPoint`, `GeoJsonPoint`;
+  `toGeoJsonPoint`, `fromGeoJsonPoint`.
+- **`/period`** — `DateRange`, `Period`; `isDateRange`, `isWithin`,
+  `rangeDurationMs`.
+- **`/pagination`** — `PageParams`, `OffsetPage<T>`, `KeysetPage<T>`,
+  `AggregatePage`, `KeysetParams`, `SortSpec`, `SortDirection`;
+  `emptyOffsetPage`, `emptyKeysetPage`.
+- **`/reference`** — `ExternalRef`, `DocumentRef`, `ObjectIdLike`, `IdLike`;
+  `idToString`, `isExternalRef`.
+- **`/context`** — `OperationContext` (the identity + tracing bag every
+  Classytic package accepts); `ActorRef`.
+- **`/events`** — `EventMeta` (arc v2.9-aligned — 13 fields including
+  `schemaVersion`, `causationId`, `partitionKey`, `source`, `idempotencyKey`,
+  `aggregate`), `DomainEvent<T>`, `EventTransport`, `EventHandler`,
+  `EventLogger`, `DeadLetteredEvent<T>`, `PublishManyResult`; `createEvent`,
+  `createChildEvent` (auto-chains `causationId`, inherits `correlationId` /
+  `userId` / `organizationId` / `source` / `idempotencyKey` — NOT
+  `aggregate`), `matchEventPattern`.
+- **`/outbox`** — transactional outbox **contract** mirrored from arc v2.9:
+  `OutboxStore`, `OutboxWriteOptions`, `OutboxClaimOptions`,
+  `OutboxAcknowledgeOptions`, `OutboxFailOptions`, `OutboxErrorInfo`,
+  `OutboxFailureContext`, `OutboxFailureDecision`, `OutboxFailurePolicy`;
+  `OutboxOwnershipError`, `InvalidOutboxEventError`. **Contract only** —
+  runtime (`EventOutbox`, `MemoryOutboxStore`, `MongoOutboxStore`,
+  `exponentialBackoff`) ships in `@classytic/arc/events` and
+  `@classytic/arc/events/mongo`. Domain packages implement `OutboxStore`
+  without peer-depping arc.
+- **`/tenant`** — `TenantConfig` (with `strategy: 'field' | 'none' | 'custom'`
+  and optional `resolve(ctx)` for custom strategy), `TenantFieldType`,
+  `TenantStrategy`, `ResolvedTenantConfig`; `DEFAULT_TENANT_CONFIG`,
+  `resolveTenantConfig`. Field names match `@classytic/mongokit`'s
+  `MultiTenantOptions` so a resolved config threads into
+  `multiTenantPlugin({ ... })` without translation.
+- **`/result`** — `Result<T, E>`; `ok`, `err`, `isOk`, `isErr`, `unwrap`,
+  `mapResult`, `mapError`.
+- **`/brand`** — `Brand<T, B>`, `Prettify`, `DeepPartial`, `DeepReadonly`,
+  `RequireKeys`, `OptionalKeys`, `NonEmptyArray`.
+- **`/errors`** — `ErrorContract`, `ErrorDetail`, `ErrorCode`, `ERROR_CODES`.
+- **`/split-allocation`** — `allocate(total, subjects, method)` returns a
+  `SplitResult` whose parts sum exactly to `total` via the largest-remainder
+  method. Methods: `equal`, `by-qty`, `by-weight`, `by-volume`, `by-value`,
+  `by-percent`. Deterministic — identical inputs produce identical outputs;
+  ties broken by input order. Handles negative totals by sign-flipping.
+  Exports: `allocate`, `isBalanced`, `SplitAllocationError`, types
+  `SplitMethod`, `SplitSubject`, `SplitPart`, `SplitResult`,
+  `SplitAllocationErrorCode`.
+- **`/approval`** — `ApprovalChain` value object with pure FSM helpers.
+  Supports sequential and parallel chains, per-step quorum
+  (`requiredApprovals`), threshold-gated skips. Any step-level rejection
+  rejects the chain; all steps `approved`|`skipped` approves it. Exports:
+  `createChain`, `applyDecision`, `skipStep`, `nextPendingStep`,
+  `pendingSteps`, `isApproved`, `isRejected`, `isPending`, `decisionCount`,
+  `ApprovalError`, types `ApprovalChain`, `ApprovalStep`, `ApprovalDecision`,
+  `Approver`, `ApprovalStatus`, `ChainOrder`, `ApprovalThreshold`,
+  `CreateChainInput`, `CreateStepInput`, `DecisionInput`, `ApprovalErrorCode`.
+- **`/cadence`** — recurrence spec with pure UTC date arithmetic. Kinds:
+  `daily`, `weekly`, `monthly`, `yearly`, `cron` (opaque — host parses).
+  `dayOfMonth: 31` snaps to the last day of shorter months; Feb 29 snaps
+  to Feb 28 in non-leap years. Exports: `nextOccurrence`,
+  `occurrencesBetween`, `validateCadence`, `CadenceError`, types `Cadence`,
+  `DailyCadence`, `WeeklyCadence`, `MonthlyCadence`, `YearlyCadence`,
+  `CronCadence`, `CadenceKind`, `IsoWeekday`, `CadenceErrorCode`.
+- **`/hold`** — `HoldReason` + collection helpers. Host embeds
+  `HoldReason[]` on documents. Exports: `addHold`, `resolveHold`,
+  `activeHolds`, `resolvedHolds`, `isOnHold`, `hasActiveHoldOfCode`,
+  `HoldError`, types `HoldReason`, `HoldActor`, `HoldActorKind`,
+  `AddHoldInput`, `ResolveHoldInput`, `HoldErrorCode`.
+- **`/sla`** — target duration + breach-detection arithmetic. Policy is
+  carried but not executed — host reads `breachPolicy` (`warn` | `escalate`
+  | `block`) and acts. Exports: `breachedAt`, `remainingMs`, `elapsedMs`,
+  `isBreached`, `consumedFraction`, `validateSLA`, `SLAError`, types
+  `SLA`, `BreachPolicy`, `SLAErrorCode`.
+- **`/person`** — person/contact shapes shared across order, crm, hr.
+  `PersonName`, `ContactInfo`, `EmergencyContact`, `Gender`; formatters
+  `formatFullName`, `formatDisplayName`.
+
+### Design principles
+
+- Pure functions on plain data. No I/O, no Mongo, no events.
+- Immutable return values. Helpers return new collections; originals are never mutated.
+- Deterministic. Same inputs → same outputs. Clock sources injected
+  explicitly so tests don't flake.
+- Errors are typed. Every module ships an `<Name>Error` class with a
+  discriminated `code: <Name>ErrorCode` string union.
+- Subpath-imports only — no root barrel.
+
+### Ownership direction
+
+Arc is the source of truth for event types. Primitives **mirrors** arc
+(`@classytic/arc/events/EventTransport.ts`, `@classytic/arc/events/outbox.ts`)
+verbatim for `EventMeta`, `DomainEvent`, `EventTransport`,
+`DeadLetteredEvent`, `EventLogger`, `PublishManyResult`, and the full
+`OutboxStore` contract surface. Helpers (`createEvent`, `createChildEvent`)
+are allowed to be more defensive but match arc's signatures.
+
+Packages that peer-dep `@classytic/primitives` can write
+`class FooOutboxRepository implements OutboxStore` without pulling arc into
+their dependency graph; hosts import `EventOutbox` + `MongoOutboxStore` from
+arc and wire them against package-provided stores.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Classytic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# @classytic/primitives
+
+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.
+
+## Install
+
+```bash
+npm install @classytic/primitives
+```
+
+## Use
+
+Prefer **subpath imports** — each concern is its own entry point, types erase
+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';
+```
+
+There is intentionally **no root barrel** — a barrel forces the Node ESM
+loader and TypeScript compiler to walk every module on a single convenience
+import, which slows CI and pulls unused code into the consumer's graph. Use
+subpath imports only.
+
+## What's inside
+
+| Subpath | Ships |
+|---|---|
+| `/money` | `Money`, `fromMajor`, `toMajor`, `addMoney`, `subtractMoney`, `multiplyMoney`, `sumMoney`, `equalsMoney`, `compareMoney`, `negateMoney`, `absMoney`, `isMoney`, `CurrencyMismatchError` |
+| `/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` |
+| `/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` |
+| `/hold` | `addHold`, `resolveHold`, `activeHolds`, `resolvedHolds`, `isOnHold`, `hasActiveHoldOfCode`, `HoldError`, `HoldReason`, `HoldActor` |
+| `/sla` | `breachedAt`, `remainingMs`, `elapsedMs`, `isBreached`, `consumedFraction`, `validateSLA`, `SLAError`, `SLA`, `BreachPolicy` |
+
+## Design
+
+### Money — integer minor units, always
+
+```ts
+import { fromMajor, addMoney, toMajor } from '@classytic/primitives/money';
+
+const subtotal = fromMajor(19.99, 'USD');     // { amount: 1999, currency: 'USD' }
+const shipping = fromMajor(5.00,  'USD');     // { amount: 500,  currency: 'USD' }
+const total    = addMoney(subtotal, shipping); // { amount: 2499, currency: 'USD' }
+toMajor(total);                                // 24.99
+```
+
+`Money.amount` is always an integer in the currency's minor unit — `1` = one
+cent for USD, one yen for JPY, one fils for KWD. Mixing currencies throws
+`CurrencyMismatchError`. This eliminates the float-rounding drift that happens
+when every package rolls its own `{ amount: number, currency: string }`.
+
+### DomainEvent — structurally identical to Arc
+
+```ts
+import { createEvent, type EventTransport } from '@classytic/primitives/events';
+
+const event = createEvent('order:placed', { orderId: 'ord_123' }, {
+  organizationId: ctx.organizationId,
+  userId: ctx.actorId,
+  correlationId: ctx.correlationId,
+});
+
+await transport.publish(event);
+```
+
+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
+
+```ts
+import { resolveTenantConfig } from '@classytic/primitives/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 }`.
+
+### ExternalRef — polymorphic, framework-free
+
+```ts
+interface ExternalRef {
+  sourceId: string;
+  sourceModel: string;
+}
+```
+
+For references that cross trust boundaries (another package, another service,
+Stripe, Postgres) — paired with a host-implemented `SourceBridge`. Works for
+ObjectId, UUID, Stripe ID, anything. See PACKAGE_RULES.md §7.
+
+## What's not here (on purpose)
+
+- **Mongoose types** — use `ObjectIdLike` from `/reference`. Any Mongoose
+  `Types.ObjectId` satisfies it structurally.
+- **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.
+- **Runtime currency database** — ship a whitelist at the app layer if you
+  need one. `MINOR_UNIT_FACTOR` covers common cases.
+
+## License
+
+MIT © Classytic

package/dist/address.d.mts

@@ -0,0 +1,38 @@
+//#region src/address.d.ts
+/**
+ * Postal address.
+ *
+ * Kept deliberately generic — international postal formats vary too much to
+ * enforce per-country rules in a shared type. Consumers can extend or narrow
+ * as needed (e.g. a BD-specific schema might add `district`, `upazila`).
+ */
+interface Address {
+  line1: string;
+  line2?: string;
+  city: string;
+  /** State / province / region. Optional for countries without subdivisions. */
+  state?: string;
+  postalCode?: string;
+  /** ISO 3166-1 alpha-2 country code (e.g. 'BD', 'US', 'GB'). */
+  country: string;
+}
+interface ContactAddress extends Address {
+  name?: string;
+  phone?: string;
+  email?: string;
+}
+/** WGS84 geographic coordinates. */
+interface GeoPoint {
+  latitude: number;
+  longitude: number;
+}
+/** A GeoJSON-flavoured point — convenient when storing in Mongo `2dsphere` indexes. */
+interface GeoJsonPoint {
+  type: 'Point';
+  /** [longitude, latitude] — note the GeoJSON ordering. */
+  coordinates: readonly [number, number];
+}
+declare function toGeoJsonPoint(p: GeoPoint): GeoJsonPoint;
+declare function fromGeoJsonPoint(g: GeoJsonPoint): GeoPoint;
+//#endregion
+export { Address, ContactAddress, GeoJsonPoint, GeoPoint, fromGeoJsonPoint, toGeoJsonPoint };

package/dist/address.mjs

@@ -0,0 +1,16 @@
+//#region src/address.ts
+function toGeoJsonPoint(p) {
+	return {
+		type: "Point",
+		coordinates: [p.longitude, p.latitude]
+	};
+}
+function fromGeoJsonPoint(g) {
+	const [longitude, latitude] = g.coordinates;
+	return {
+		longitude,
+		latitude
+	};
+}
+//#endregion
+export { fromGeoJsonPoint, toGeoJsonPoint };

package/dist/approval.d.mts

@@ -0,0 +1,133 @@
+//#region src/approval.d.ts
+/**
+ * Approval chain value object and pure state-transition helpers.
+ *
+ * Hosts embed an `ApprovalChain` on domain documents (quotation, return,
+ * high-value transaction, etc.) as a subdocument — this primitive is
+ * purely data + pure functions; no persistence, no I/O, no events.
+ *
+ * Supports:
+ *   - sequential chains (step 2 activates only after step 1 approves)
+ *   - parallel chains (all pending steps active at once)
+ *   - per-step quorum (requiredApprovals out of N approvers)
+ *   - skipping steps when a host-evaluated condition fails
+ *
+ * Chain status is computed from step statuses:
+ *   - any step `rejected`                    → chain `rejected`
+ *   - all required steps `approved`|`skipped` → chain `approved`
+ *   - otherwise                               → chain `pending`
+ *
+ * @example
+ * import { createChain, applyDecision, isApproved } from '@classytic/primitives/approval';
+ *
+ * let chain = createChain({
+ *   order: 'sequential',
+ *   steps: [
+ *     { id: 'sales',   approvers: [{ id: 'rep1' }] },
+ *     { id: 'finance', approvers: [{ id: 'cfo1' }, { id: 'cfo2' }], requiredApprovals: 1 },
+ *   ],
+ * });
+ * chain = applyDecision(chain, { stepId: 'sales',   approverId: 'rep1', decision: 'approved' });
+ * chain = applyDecision(chain, { stepId: 'finance', approverId: 'cfo1', decision: 'approved' });
+ * isApproved(chain); // → true
+ */
+type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'skipped';
+type ChainOrder = 'sequential' | 'parallel';
+interface Approver {
+  readonly id: string;
+  readonly name?: string;
+  readonly role?: string;
+}
+interface ApprovalDecision {
+  readonly approverId: string;
+  readonly decision: 'approved' | 'rejected';
+  readonly note?: string;
+  readonly decidedAt: Date;
+}
+/**
+ * Optional threshold gate. The primitive does not evaluate this — it's
+ * metadata the host reads when deciding whether to mark a step `skipped`
+ * (via {@link skipStep}). Captures the intent in structured form so the
+ * reason for the skip is auditable.
+ */
+interface ApprovalThreshold {
+  readonly field: string;
+  readonly op: 'gt' | 'gte' | 'lt' | 'lte' | 'eq';
+  readonly value: number;
+}
+interface ApprovalStep {
+  readonly id: string;
+  readonly name?: string;
+  readonly approvers: readonly Approver[];
+  /** How many distinct approver decisions of `approved` are needed. Default: 1. */
+  readonly requiredApprovals: number;
+  readonly threshold?: ApprovalThreshold;
+  readonly status: ApprovalStatus;
+  readonly decisions: readonly ApprovalDecision[];
+  /** Populated when status transitions to `skipped`. */
+  readonly skippedReason?: string;
+}
+interface ApprovalChain {
+  readonly order: ChainOrder;
+  readonly steps: readonly ApprovalStep[];
+  readonly status: ApprovalStatus;
+}
+interface CreateChainInput {
+  readonly order: ChainOrder;
+  readonly steps: readonly CreateStepInput[];
+}
+interface CreateStepInput {
+  readonly id: string;
+  readonly name?: string;
+  readonly approvers: readonly Approver[];
+  readonly requiredApprovals?: number;
+  readonly threshold?: ApprovalThreshold;
+}
+type ApprovalErrorCode = 'EMPTY_STEPS' | 'DUPLICATE_STEP_ID' | 'EMPTY_APPROVERS' | 'DUPLICATE_APPROVER_ID' | 'INVALID_QUORUM' | 'UNKNOWN_STEP' | 'UNAUTHORIZED_APPROVER' | 'STEP_NOT_ACTIVE' | 'STEP_ALREADY_DECIDED_BY_APPROVER';
+declare class ApprovalError extends Error {
+  readonly name = "ApprovalError";
+  readonly code: ApprovalErrorCode;
+  constructor(code: ApprovalErrorCode, message: string);
+}
+/** Build a fresh chain in `pending` state. Validates inputs. */
+declare function createChain(input: CreateChainInput): ApprovalChain;
+/**
+ * Returns the next step awaiting a decision — or `null` if none.
+ *
+ * For `sequential` chains: the first `pending` step in order; later steps
+ * remain inactive until earlier ones finalise.
+ *
+ * For `parallel` chains: returns the first pending step (all pending steps
+ * are active simultaneously; host typically iterates with {@link pendingSteps}).
+ */
+declare function nextPendingStep(chain: ApprovalChain): ApprovalStep | null;
+/** All steps currently eligible to receive a decision. */
+declare function pendingSteps(chain: ApprovalChain): readonly ApprovalStep[];
+interface DecisionInput {
+  readonly stepId: string;
+  readonly approverId: string;
+  readonly decision: 'approved' | 'rejected';
+  readonly note?: string;
+  readonly decidedAt?: Date;
+}
+/**
+ * Apply a decision to a step. Returns a new chain — original is not mutated.
+ * Throws if the step is unknown, not active, the approver isn't listed, or
+ * the approver has already decided.
+ */
+declare function applyDecision(chain: ApprovalChain, input: DecisionInput): ApprovalChain;
+/**
+ * Mark a step as skipped — for when a host-evaluated condition determines
+ * the step is not required (e.g., amount < threshold). Skipped steps count
+ * as "completed" for chain approval.
+ */
+declare function skipStep(chain: ApprovalChain, stepId: string, reason?: string): ApprovalChain;
+declare function isApproved(chain: ApprovalChain): boolean;
+declare function isRejected(chain: ApprovalChain): boolean;
+declare function isPending(chain: ApprovalChain): boolean;
+/**
+ * Count total decisions across all steps. Useful for audit summaries.
+ */
+declare function decisionCount(chain: ApprovalChain): number;
+//#endregion
+export { ApprovalChain, ApprovalDecision, ApprovalError, ApprovalErrorCode, ApprovalStatus, ApprovalStep, ApprovalThreshold, Approver, ChainOrder, CreateChainInput, CreateStepInput, DecisionInput, applyDecision, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };

package/dist/approval.mjs

@@ -0,0 +1,146 @@
+//#region src/approval.ts
+var ApprovalError = class extends Error {
+	name = "ApprovalError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/** Build a fresh chain in `pending` state. Validates inputs. */
+function createChain(input) {
+	if (input.steps.length === 0) throw new ApprovalError("EMPTY_STEPS", "chain must have at least one step");
+	const seenStepIds = /* @__PURE__ */ new Set();
+	const steps = input.steps.map((s) => {
+		if (seenStepIds.has(s.id)) throw new ApprovalError("DUPLICATE_STEP_ID", `duplicate step id: ${s.id}`);
+		seenStepIds.add(s.id);
+		if (s.approvers.length === 0) throw new ApprovalError("EMPTY_APPROVERS", `step ${s.id} has no approvers`);
+		const seenApproverIds = /* @__PURE__ */ new Set();
+		for (const a of s.approvers) {
+			if (seenApproverIds.has(a.id)) throw new ApprovalError("DUPLICATE_APPROVER_ID", `step ${s.id} has duplicate approver id: ${a.id}`);
+			seenApproverIds.add(a.id);
+		}
+		const quorum = s.requiredApprovals ?? 1;
+		if (!Number.isInteger(quorum) || quorum < 1 || quorum > s.approvers.length) throw new ApprovalError("INVALID_QUORUM", `step ${s.id}: requiredApprovals must be integer in [1, ${s.approvers.length}], got ${quorum}`);
+		return {
+			id: s.id,
+			...s.name !== void 0 ? { name: s.name } : {},
+			approvers: s.approvers,
+			requiredApprovals: quorum,
+			...s.threshold !== void 0 ? { threshold: s.threshold } : {},
+			status: "pending",
+			decisions: []
+		};
+	});
+	return {
+		order: input.order,
+		steps,
+		status: "pending"
+	};
+}
+/**
+* Returns the next step awaiting a decision — or `null` if none.
+*
+* For `sequential` chains: the first `pending` step in order; later steps
+* remain inactive until earlier ones finalise.
+*
+* For `parallel` chains: returns the first pending step (all pending steps
+* are active simultaneously; host typically iterates with {@link pendingSteps}).
+*/
+function nextPendingStep(chain) {
+	for (const step of chain.steps) if (step.status === "pending") return step;
+	return null;
+}
+/** All steps currently eligible to receive a decision. */
+function pendingSteps(chain) {
+	if (chain.order === "sequential") {
+		const next = nextPendingStep(chain);
+		return next ? [next] : [];
+	}
+	return chain.steps.filter((s) => s.status === "pending");
+}
+/**
+* Apply a decision to a step. Returns a new chain — original is not mutated.
+* Throws if the step is unknown, not active, the approver isn't listed, or
+* the approver has already decided.
+*/
+function applyDecision(chain, input) {
+	const stepIndex = chain.steps.findIndex((s) => s.id === input.stepId);
+	if (stepIndex === -1) throw new ApprovalError("UNKNOWN_STEP", `no step with id ${input.stepId}`);
+	const step = chain.steps[stepIndex];
+	if (!step) throw new ApprovalError("UNKNOWN_STEP", `no step with id ${input.stepId}`);
+	if (!pendingSteps(chain).some((s) => s.id === input.stepId)) throw new ApprovalError("STEP_NOT_ACTIVE", `step ${input.stepId} is not currently active (status=${step.status})`);
+	if (!step.approvers.some((a) => a.id === input.approverId)) throw new ApprovalError("UNAUTHORIZED_APPROVER", `approver ${input.approverId} is not listed on step ${input.stepId}`);
+	if (step.decisions.some((d) => d.approverId === input.approverId)) throw new ApprovalError("STEP_ALREADY_DECIDED_BY_APPROVER", `approver ${input.approverId} has already decided on step ${input.stepId}`);
+	const decision = {
+		approverId: input.approverId,
+		decision: input.decision,
+		...input.note !== void 0 ? { note: input.note } : {},
+		decidedAt: input.decidedAt ?? /* @__PURE__ */ new Date()
+	};
+	const updatedStep = computeStepStatus({
+		...step,
+		decisions: [...step.decisions, decision]
+	});
+	const updatedSteps = chain.steps.map((s, i) => i === stepIndex ? updatedStep : s);
+	return {
+		order: chain.order,
+		steps: updatedSteps,
+		status: computeChainStatus(updatedSteps)
+	};
+}
+/**
+* Mark a step as skipped — for when a host-evaluated condition determines
+* the step is not required (e.g., amount < threshold). Skipped steps count
+* as "completed" for chain approval.
+*/
+function skipStep(chain, stepId, reason) {
+	const stepIndex = chain.steps.findIndex((s) => s.id === stepId);
+	if (stepIndex === -1) throw new ApprovalError("UNKNOWN_STEP", `no step with id ${stepId}`);
+	const step = chain.steps[stepIndex];
+	if (!step) throw new ApprovalError("UNKNOWN_STEP", `no step with id ${stepId}`);
+	if (step.status !== "pending") throw new ApprovalError("STEP_NOT_ACTIVE", `step ${stepId} cannot be skipped (status=${step.status})`);
+	const updatedStep = {
+		...step,
+		status: "skipped",
+		...reason !== void 0 ? { skippedReason: reason } : {}
+	};
+	const updatedSteps = chain.steps.map((s, i) => i === stepIndex ? updatedStep : s);
+	return {
+		order: chain.order,
+		steps: updatedSteps,
+		status: computeChainStatus(updatedSteps)
+	};
+}
+function isApproved(chain) {
+	return chain.status === "approved";
+}
+function isRejected(chain) {
+	return chain.status === "rejected";
+}
+function isPending(chain) {
+	return chain.status === "pending";
+}
+/**
+* Count total decisions across all steps. Useful for audit summaries.
+*/
+function decisionCount(chain) {
+	return chain.steps.reduce((n, s) => n + s.decisions.length, 0);
+}
+function computeStepStatus(step) {
+	if (step.decisions.some((d) => d.decision === "rejected")) return {
+		...step,
+		status: "rejected"
+	};
+	if (step.decisions.filter((d) => d.decision === "approved").length >= step.requiredApprovals) return {
+		...step,
+		status: "approved"
+	};
+	return step;
+}
+function computeChainStatus(steps) {
+	if (steps.some((s) => s.status === "rejected")) return "rejected";
+	return steps.every((s) => s.status === "approved" || s.status === "skipped") ? "approved" : "pending";
+}
+//#endregion
+export { ApprovalError, applyDecision, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };

package/dist/brand-DApaegoR.d.mts

@@ -0,0 +1,37 @@
+//#region src/brand.d.ts
+/**
+ * Type utilities for building nominal types and transforming shapes.
+ *
+ * These have zero runtime cost — all erase at compile time.
+ */
+declare const __brand: unique symbol;
+/**
+ * Nominal typing via an intersection brand.
+ *
+ * @example
+ * type UserId = Brand<string, 'UserId'>;
+ * type OrderId = Brand<string, 'OrderId'>;
+ * const u: UserId = 'abc' as UserId;
+ * const o: OrderId = u; // type error — brands differ
+ */
+type Brand<T, B extends string> = T & {
+  readonly [__brand]: B;
+};
+/** Flattens intersection types for nicer IDE hover output. */
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+/** Recursive partial — every leaf becomes optional. */
+type DeepPartial<T> = T extends ((...args: readonly unknown[]) => unknown) ? T : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
+/** Recursive readonly — every leaf becomes immutable. */
+type DeepReadonly<T> = T extends ((...args: readonly unknown[]) => unknown) ? T : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepReadonly<U>> : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;
+/** Make specific keys required while leaving the rest as-is. */
+type RequireKeys<T, K extends keyof T> = T & { [P in K]-?: T[P] };
+/** Make specific keys optional while leaving the rest as-is. */
+type OptionalKeys<T, K extends keyof T> = Omit<T, K> & { [P in K]?: T[P] };
+/** A value that may be absent in three flavours — `T | null | undefined`. */
+type Nullable<T> = T | null | undefined;
+/** Keys of T whose value type is assignable to V. */
+type KeysMatching<T, V> = { [K in keyof T]-?: T[K] extends V ? K : never }[keyof T];
+/** Non-empty array guard type. */
+type NonEmptyArray<T> = readonly [T, ...T[]];
+//#endregion
+export { NonEmptyArray as a, Prettify as c, KeysMatching as i, RequireKeys as l, DeepPartial as n, Nullable as o, DeepReadonly as r, OptionalKeys as s, Brand as t };

package/dist/brand.d.mts

@@ -0,0 +1,2 @@
+import { a as NonEmptyArray, c as Prettify, i as KeysMatching, l as RequireKeys, n as DeepPartial, o as Nullable, r as DeepReadonly, s as OptionalKeys, t as Brand } from "./brand-DApaegoR.mjs";
+export { Brand, DeepPartial, DeepReadonly, KeysMatching, NonEmptyArray, Nullable, OptionalKeys, Prettify, RequireKeys };

package/dist/brand.mjs

@@ -0,0 +1 @@
+export {};