@classytic/primitives 0.18.0 → 0.20.0

package/README.md

@@ -1,159 +1,160 @@
-# @classytic/primitives
-
-[![Sponsor](https://img.shields.io/github/sponsors/classytic?style=flat-square&label=Sponsor&logo=GitHub&color=EA4AAA)](https://github.com/sponsors/classytic)
-
-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`, `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
-
-```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 type { OperationContext } from '@classytic/primitives/context';
-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
-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` |
-| `/reference` | `ExternalRef`, `ObjectIdLike`, `IdLike`, `DocumentRef`, `idToString`, `isExternalRef` |
-| `/context` | `OperationContext`, `ActorRef` |
-| `/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` |
-| `/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 — moved to `@classytic/repo-core/tenant`
-
-```ts
-import { resolveTenantConfig } from '@classytic/repo-core/tenant';
-
-const tenant = resolveTenantConfig(config.tenant);
-// { enabled: true, tenantField: 'organizationId', fieldType: 'objectId',
-//   ref: 'organization', contextKey: 'organizationId', required: true }
-```
-
-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
-
-```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` (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.
-
-## License
-
-MIT © Classytic
+# @classytic/primitives
+
+[![Sponsor](https://img.shields.io/github/sponsors/classytic?style=flat-square&label=Sponsor&logo=GitHub&color=EA4AAA)](https://github.com/sponsors/classytic)
+
+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`, `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
+
+```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 type { OperationContext } from '@classytic/primitives/context';
+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
+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`, `isKnownCurrency`, `toCurrencyCode`, `currencyCode`, `isCurrencyCode`, `InvalidCurrencyCodeError`, `CurrencyMismatchError`, `FxSnapshot`, `convertWithSnapshot`, `reverseWithSnapshot`, `FxRounding` |
+| `/address` | `Address`, `ContactAddress`, `GeoPoint`, `GeoJsonPoint`, `toGeoJsonPoint`, `fromGeoJsonPoint` |
+| `/period` | `DateRange`, `Period`, `isDateRange`, `isWithin`, `rangeDurationMs`, `rangesOverlap`, `DateRangeError` — **plus timezone-aware resolution**: `resolvePeriod`, `resolveDay`, `resolveMonth`, `resolveQuarter`, `resolveYear`, `resolveDateSpan`, `dayStart`, `periodOf`, `parsePeriod`, `formatPeriod`, `granularityOf`, `periodTimeZone`, `inclusiveEnd`, `PeriodError` |
+| `/reference` | `ExternalRef`, `ObjectIdLike`, `IdLike`, `DocumentRef`, `idToString`, `isExternalRef` |
+| `/context` | `OperationContext`, `ActorRef` |
+| `/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` |
+| `/split-allocation` | `allocate`, `isBalanced`, `SplitAllocationError`, `SplitMethod`, `SplitSubject`, `SplitPart`, `SplitResult` |
+| `/idempotency` | `decideClaim`, `completeClaim`, `renewLease`, `identityKey`, `sameIdentity`, `fingerprintRequest`, `newLeaseToken`, `isLeaseExpired`, `holdsLease`, `isInFlight`, `DEFAULT_LEASE_MS`, `IdempotencyClaim`, `ClaimOutcome`, `ClaimResult`, `ClaimState`, `IdempotencyIdentity`, `IdempotencyError` |
+| `/approval` | `createChain`, `applyDecision`, `skipStep`, `nextPendingStep`, `pendingSteps`, `isApproved`, `assertApproved`, `assertApprovedIfPresent`, `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 — moved to `@classytic/repo-core/tenant`
+
+```ts
+import { resolveTenantConfig } from '@classytic/repo-core/tenant';
+
+const tenant = resolveTenantConfig(config.tenant);
+// { enabled: true, tenantField: 'organizationId', fieldType: 'objectId',
+//   ref: 'organization', contextKey: 'organizationId', required: true }
+```
+
+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
+
+```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` (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.
+
+## License
+
+MIT © Classytic

package/dist/approval.d.mts

@@ -88,7 +88,12 @@ type ApprovalErrorCode = 'EMPTY_STEPS' | 'DUPLICATE_STEP_ID' | 'EMPTY_APPROVERS'
  *  `approved` (still `pending`, or `rejected`). The single canonical
  *  "not yet approved" gate — hosts route it through arc-approval's
  *  `rethrowApprovalError` to the `approval.chain_incomplete` wire code. */
-| 'CHAIN_INCOMPLETE';
+| 'CHAIN_INCOMPLETE'
+/** A finalize/commit was attempted with NO chain at all. Distinct from
+ *  `CHAIN_INCOMPLETE`: the chain is not unfinished, it is absent — the
+ *  document never carried one, or a schema that never declared the field
+ *  stripped it on write. See {@link assertApproved}. */
+| 'CHAIN_MISSING';
 declare class ApprovalError extends Error {
   readonly name = "ApprovalError";
   readonly code: ApprovalErrorCode;
@@ -128,16 +133,50 @@ declare function applyDecision(chain: ApprovalChain, input: DecisionInput): Appr
  */
 declare function skipStep(chain: ApprovalChain, stepId: string, reason?: string): ApprovalChain;
 declare function isApproved(chain: ApprovalChain): boolean;
+interface AssertApprovedOptions {
+  /** Override the thrown message. */
+  readonly message?: string;
+}
 /**
- * The canonical finalize-time gate: assert `chain` has reached `approved`,
- * else throw `ApprovalError('CHAIN_INCOMPLETE')`. Use this at every
- * commit/post/finalize boundary that must not proceed on an unapproved chain
- * (journal-entry post, PO approve, transfer dispatch, …) so they all raise the
- * SAME error instead of hand-rolling divergent codes. A `null`/absent chain is
- * treated as "no chain required" and passes — callers that require a chain
- * check presence separately.
+ * The canonical finalize-time gate: assert a chain EXISTS and has reached
+ * `approved`, else throw. Use it at every commit/post/finalize boundary that
+ * must not proceed unapproved (journal-entry post, PO approve, transfer
+ * dispatch, payment release) so they all raise the same two codes instead of
+ * hand-rolling divergent ones.
+ *
+ * ## Absence is not approval
+ *
+ * This function used to PASS on `null`/`undefined`, documented as "no chain
+ * required", with only prose telling callers to check presence separately. That
+ * is the permissive default with the widest blast radius: the gate reads as
+ * enforced at every call site while doing nothing for the one input most likely
+ * to occur by accident.
+ *
+ * And it occurs by accident routinely — a mongoose schema that never declared
+ * `approvalChain` **strips it on write**, so a document that carried a chain in
+ * memory reads back without one. The gate then passes, the money moves, and
+ * nothing anywhere says so. The flag has to survive the write; a gate that
+ * cannot tell "no approval configured" from "approval silently lost" must
+ * assume the dangerous one.
+ *
+ * A caller that genuinely permits an absent chain must say so by name —
+ * {@link assertApprovedIfPresent} — which is greppable in review, unlike a
+ * `null` that never got checked.
+ *
+ * @throws ApprovalError `CHAIN_MISSING` when `chain` is null/undefined.
+ * @throws ApprovalError `CHAIN_INCOMPLETE` when it exists but is not `approved`.
+ */
+declare function assertApproved(chain: ApprovalChain | null | undefined, options?: AssertApprovedOptions): void;
+/**
+ * The EXPLICIT opt-out: enforce the chain when one is present, allow the
+ * operation when none is.
+ *
+ * Only correct where "no chain" is a configured state the host can distinguish
+ * from a lost one — e.g. a policy engine that decided this document needs no
+ * approval and recorded that decision elsewhere. If you cannot tell the two
+ * apart, use {@link assertApproved}.
  */
-declare function assertApproved(chain: ApprovalChain | null | undefined, message?: string): void;
+declare function assertApprovedIfPresent(chain: ApprovalChain | null | undefined, options?: AssertApprovedOptions): void;
 declare function isRejected(chain: ApprovalChain): boolean;
 declare function isPending(chain: ApprovalChain): boolean;
 /**
@@ -145,4 +184,4 @@ declare function isPending(chain: ApprovalChain): boolean;
  */
 declare function decisionCount(chain: ApprovalChain): number;
 //#endregion
-export { ApprovalChain, ApprovalDecision, ApprovalError, ApprovalErrorCode, ApprovalStatus, ApprovalStep, ApprovalThreshold, Approver, ChainOrder, CreateChainInput, CreateStepInput, DecisionInput, applyDecision, assertApproved, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };
+export { ApprovalChain, ApprovalDecision, ApprovalError, ApprovalErrorCode, ApprovalStatus, ApprovalStep, ApprovalThreshold, Approver, AssertApprovedOptions, ChainOrder, CreateChainInput, CreateStepInput, DecisionInput, applyDecision, assertApproved, assertApprovedIfPresent, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };

package/dist/approval.mjs

@@ -116,16 +116,50 @@ function isApproved(chain) {
 	return chain.status === "approved";
 }
 /**
-* The canonical finalize-time gate: assert `chain` has reached `approved`,
-* else throw `ApprovalError('CHAIN_INCOMPLETE')`. Use this at every
-* commit/post/finalize boundary that must not proceed on an unapproved chain
-* (journal-entry post, PO approve, transfer dispatch, …) so they all raise the
-* SAME error instead of hand-rolling divergent codes. A `null`/absent chain is
-* treated as "no chain required" and passes — callers that require a chain
-* check presence separately.
+* The canonical finalize-time gate: assert a chain EXISTS and has reached
+* `approved`, else throw. Use it at every commit/post/finalize boundary that
+* must not proceed unapproved (journal-entry post, PO approve, transfer
+* dispatch, payment release) so they all raise the same two codes instead of
+* hand-rolling divergent ones.
+*
+* ## Absence is not approval
+*
+* This function used to PASS on `null`/`undefined`, documented as "no chain
+* required", with only prose telling callers to check presence separately. That
+* is the permissive default with the widest blast radius: the gate reads as
+* enforced at every call site while doing nothing for the one input most likely
+* to occur by accident.
+*
+* And it occurs by accident routinely — a mongoose schema that never declared
+* `approvalChain` **strips it on write**, so a document that carried a chain in
+* memory reads back without one. The gate then passes, the money moves, and
+* nothing anywhere says so. The flag has to survive the write; a gate that
+* cannot tell "no approval configured" from "approval silently lost" must
+* assume the dangerous one.
+*
+* A caller that genuinely permits an absent chain must say so by name —
+* {@link assertApprovedIfPresent} — which is greppable in review, unlike a
+* `null` that never got checked.
+*
+* @throws ApprovalError `CHAIN_MISSING` when `chain` is null/undefined.
+* @throws ApprovalError `CHAIN_INCOMPLETE` when it exists but is not `approved`.
+*/
+function assertApproved(chain, options = {}) {
+	if (chain == null) throw new ApprovalError("CHAIN_MISSING", options.message ?? "no approval chain present at a gate that requires one — an absent chain is not an approved one. If this boundary legitimately runs without approval, call assertApprovedIfPresent() so the exemption is explicit.");
+	if (!isApproved(chain)) throw new ApprovalError("CHAIN_INCOMPLETE", options.message ?? `approval chain has not reached 'approved' (status='${chain.status}')`);
+}
+/**
+* The EXPLICIT opt-out: enforce the chain when one is present, allow the
+* operation when none is.
+*
+* Only correct where "no chain" is a configured state the host can distinguish
+* from a lost one — e.g. a policy engine that decided this document needs no
+* approval and recorded that decision elsewhere. If you cannot tell the two
+* apart, use {@link assertApproved}.
 */
-function assertApproved(chain, message) {
-	if (chain != null && !isApproved(chain)) throw new ApprovalError("CHAIN_INCOMPLETE", message ?? `approval chain has not reached 'approved' (status='${chain.status}')`);
+function assertApprovedIfPresent(chain, options = {}) {
+	if (chain == null) return;
+	assertApproved(chain, options);
 }
 function isRejected(chain) {
 	return chain.status === "rejected";
@@ -155,4 +189,4 @@ function computeChainStatus(steps) {
 	return steps.every((s) => s.status === "approved" || s.status === "skipped") ? "approved" : "pending";
 }
 //#endregion
-export { ApprovalError, applyDecision, assertApproved, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };
+export { ApprovalError, applyDecision, assertApproved, assertApprovedIfPresent, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };

package/dist/bank-transaction.d.mts

@@ -1,4 +1,4 @@
-import { Money } from "./money.mjs";
+import { n as Money } from "./money-DPo9fLBi.mjs";
 
 //#region src/money/bank-transaction.d.ts
 /**

package/dist/cadence-BFQVC1Qp.d.mts

@@ -0,0 +1,107 @@
+//#region src/scheduling/cadence.d.ts
+/**
+ * Recurrence spec + pure date arithmetic.
+ *
+ * Describes "every N days", "every weekday", "on the 15th of each month", etc.
+ * Consumed by `@classytic/order` (blanket / recurring orders, subscription
+ * renewal), `@classytic/flow` (replenishment schedules), and
+ * `@classytic/commission` (vesting periods, statement close).
+ *
+ * No cron parser dep — the `cron` kind stores an opaque string that the host
+ * parses with its own library (node-cron, croner, etc.). This keeps primitives
+ * zero-dep and lets hosts pick whatever cron dialect they want.
+ *
+ * @example
+ * const monthly: Cadence = {
+ *   kind: 'monthly',
+ *   interval: 1,
+ *   dayOfMonth: 15,
+ *   startAt: new Date('2026-01-15T00:00:00Z'),
+ * };
+ * nextOccurrence(monthly, new Date('2026-02-20T00:00:00Z'));
+ * // → 2026-03-15T00:00:00Z
+ */
+type CadenceKind = 'daily' | 'weekly' | 'monthly' | 'yearly' | 'cron';
+/** ISO weekday — 1=Mon … 7=Sun. Matches Temporal + ISO 8601. */
+type IsoWeekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+interface CadenceBase {
+  readonly interval: number;
+  readonly startAt: Date;
+  readonly endAt?: Date;
+  /**
+   * IANA zone the recurrence's WALL CLOCK is anchored to (e.g. `Asia/Dhaka`).
+   * **Authoritative, not decorative.**
+   *
+   * When set, occurrence math runs on that zone's calendar: `dayOfMonth: 1`
+   * lands on local midnight-relative wall time of the local 1st, weekday
+   * filters read the local weekday, and daily steps advance local calendar
+   * days (23h or 25h across a DST transition, not a flat 24h).
+   *
+   * When ABSENT, everything is UTC — the right default for a schedule that
+   * genuinely has no locale.
+   *
+   * History worth keeping: this field used to be documented as display-only
+   * while `stepMonthly` / `stepYearly` read `getUTCMonth()` / `getUTCDate()`.
+   * With `timezone: 'Asia/Dhaka'` and `dayOfMonth: 1` that placed every
+   * occurrence on the UTC 1st — 06:00 on the local 1st, or with a midnight
+   * anchor, the local **2nd at 00:00**. The field said one thing and the math
+   * did another, and nothing failed. A field that lies is worse than no field.
+   */
+  readonly timezone?: string;
+}
+interface DailyCadence extends CadenceBase {
+  readonly kind: 'daily';
+}
+interface WeeklyCadence extends CadenceBase {
+  readonly kind: 'weekly';
+  /**
+   * If provided, only these ISO weekdays count as occurrences; the earliest
+   * matching weekday on or after `startAt` is the first occurrence. If omitted,
+   * the weekday of `startAt` is used.
+   */
+  readonly daysOfWeek?: readonly IsoWeekday[];
+}
+interface MonthlyCadence extends CadenceBase {
+  readonly kind: 'monthly';
+  /**
+   * Day of month, 1–31. If the target month has fewer days (e.g. 31st → Feb),
+   * occurrence snaps to the last day of the month.
+   */
+  readonly dayOfMonth: number;
+}
+interface YearlyCadence extends CadenceBase {
+  readonly kind: 'yearly';
+  /** Calendar month 1–12. */
+  readonly month: number;
+  /** Day of month 1–31. Snaps to last day of month if needed (e.g. Feb 29 → Feb 28 in non-leap years). */
+  readonly dayOfMonth: number;
+}
+interface CronCadence extends CadenceBase {
+  readonly kind: 'cron';
+  /** Opaque cron expression — caller parses with its own cron library. */
+  readonly expression: string;
+}
+type Cadence = DailyCadence | WeeklyCadence | MonthlyCadence | YearlyCadence | CronCadence;
+type CadenceErrorCode = 'INVALID_INTERVAL' | 'INVALID_DAY_OF_MONTH' | 'INVALID_MONTH' | 'INVALID_DAYS_OF_WEEK' | 'INVALID_START_AT' | 'INVALID_END_AT' | 'INVALID_TIMEZONE' | 'UNSUPPORTED_CRON';
+declare class CadenceError extends Error {
+  readonly name = "CadenceError";
+  readonly code: CadenceErrorCode;
+  constructor(code: CadenceErrorCode, message: string);
+}
+/** Validate a Cadence spec. Call this before storing host-side. */
+declare function validateCadence(c: Cadence): void;
+/**
+ * Next occurrence strictly after `from`. Returns `null` if the cadence has
+ * ended (endAt passed) or the first occurrence is still in the future.
+ *
+ * Cron cadences return `null` — hosts must parse the expression themselves.
+ */
+declare function nextOccurrence(cadence: Cadence, from: Date): Date | null;
+/**
+ * Enumerate occurrences in `[from, to)` inclusive at `from`, exclusive at `to`.
+ * Returns up to `limit` results (default 10_000) to guard against runaway
+ * misconfigured cadences. Cron returns an empty array.
+ */
+declare function occurrencesBetween(cadence: Cadence, from: Date, to: Date, limit?: number): Date[];
+//#endregion
+export { CronCadence as a, MonthlyCadence as c, nextOccurrence as d, occurrencesBetween as f, CadenceKind as i, WeeklyCadence as l, CadenceError as n, DailyCadence as o, validateCadence as p, CadenceErrorCode as r, IsoWeekday as s, Cadence as t, YearlyCadence as u };