@classytic/primitives 0.19.0 → 0.21.0

package/dist/currency.mjs

@@ -26,11 +26,20 @@ const CURRENCIES = {
 	IDR: "IDR"
 };
 /**
-* Number of minor units per major unit for common currencies.
+* Number of minor units per major unit, by ISO 4217 code.
 *
-* ISO 4217 defines most currencies with 2 decimal places (cents). A few are
-* zero-decimal (JPY, KRW) or three-decimal (BHD, KWD, JOD). When a currency
-* isn't in this table, {@link minorUnitFactor} returns 100 as the safe default.
+* **This table must list EVERY currency whose exponent is not 2.** ISO 4217
+* defaults to 2 decimals, and {@link minorUnitFactor} falls back to 100 for a
+* code it does not know — which is correct for the ~150 two-decimal currencies
+* and catastrophically wrong for the others. A missing zero-decimal entry does
+* not throw: it makes `fromMajor(1500, 'GNF')` store 150 000 minor units, a
+* 100× error that reads as a plausible number all the way to the gateway.
+*
+* So the exceptions are enumerated EXHAUSTIVELY (all 0-, 3- and 4-decimal
+* codes), leaving the `?? 100` fallback reachable only by a code that is not a
+* real ISO 4217 currency — a typo, a lowercased code, or a placeholder. The
+* two-decimal entries below are redundant with the default and kept only as
+* documentation of the common set.
 */
 const MINOR_UNIT_FACTOR = {
 	USD: 100,
@@ -53,13 +62,31 @@ const MINOR_UNIT_FACTOR = {
 	HKD: 100,
 	THB: 100,
 	IDR: 100,
+	BIF: 1,
+	CLP: 1,
+	DJF: 1,
+	GNF: 1,
+	ISK: 1,
+	KMF: 1,
 	KRW: 1,
+	PYG: 1,
+	RWF: 1,
+	UGX: 1,
+	UYI: 1,
 	VND: 1,
+	VUV: 1,
+	XAF: 1,
+	XOF: 1,
+	XPF: 1,
 	BHD: 1e3,
-	KWD: 1e3,
+	IQD: 1e3,
 	JOD: 1e3,
+	KWD: 1e3,
+	LYD: 1e3,
 	OMR: 1e3,
-	TND: 1e3
+	TND: 1e3,
+	CLF: 1e4,
+	UYW: 1e4
 };
 /**
 * ISO 4217 format — 3 uppercase letters. Exported so consumers can embed
@@ -78,26 +105,107 @@ const CURRENCY_PATTERN = /^[A-Z]{3}$/;
 function toCurrencyCode(value) {
 	return CURRENCY_PATTERN.test(value) ? value : null;
 }
+/**
+* Validate + brand, or throw. The constructor form — same relationship to
+* {@link toCurrencyCode} that `civilDate` has to `isCivilDate`.
+*
+* `Money` carries a {@link CurrencyCode}, not a bare string, and this is where
+* an untrusted value earns the brand. Rejecting `'jpy'` here matters: lowercase
+* misses {@link MINOR_UNIT_FACTOR}, so it silently becomes a 2-decimal currency
+* and every JPY amount is off by 100×.
+*/
+function currencyCode(value) {
+	const code = toCurrencyCode(value);
+	if (code === null) throw new InvalidCurrencyCodeError(value);
+	return code;
+}
+var InvalidCurrencyCodeError = class extends Error {
+	name = "InvalidCurrencyCodeError";
+	value;
+	constructor(value) {
+		super(`Invalid ISO 4217 currency code '${value}' — expected three uppercase letters. A code that misses the minor-unit table is assumed to have two decimals, which is a 100× error for JPY-style currencies.`);
+		this.value = value;
+	}
+};
+/**
+* Raised when an operation combines two currencies.
+*
+* Declared HERE rather than in `/money` so the FX seam below can throw it
+* without a runtime import back into `/money` (which imports
+* {@link minorUnitFactor} from this file). `/money` re-exports it, so
+* `import { CurrencyMismatchError } from '@classytic/primitives/money'` still
+* resolves.
+*/
+var CurrencyMismatchError = class extends Error {
+	name = "CurrencyMismatchError";
+	left;
+	right;
+	constructor(left, right) {
+		super(`Currency mismatch: ${left} vs ${right}`);
+		this.left = left;
+		this.right = right;
+	}
+};
 /** Type predicate for `unknown` input. */
 function isCurrencyCode(value) {
 	return typeof value === "string" && CURRENCY_PATTERN.test(value);
 }
 /**
-* Minor units per major unit (e.g. 100 for USD, 1 for JPY, 1000 for KWD).
-* Falls back to 100 when the currency is unknown — matches the ISO 4217 default.
+* Minor units per major unit (100 for USD, 1 for JPY, 1000 for KWD, 10 000 for CLF).
+*
+* Falls back to 100 for an unlisted code — the ISO 4217 default exponent. Because
+* {@link MINOR_UNIT_FACTOR} enumerates every non-2-decimal currency, that fallback
+* is now only reached by codes that are not ISO 4217 currencies at all; use
+* {@link isKnownCurrency} at a config/boot boundary if you need to reject those
+* rather than assume two decimals for them.
 */
 function minorUnitFactor(currency) {
 	return MINOR_UNIT_FACTOR[currency] ?? 100;
 }
 /**
-* Apply an {@link FxSnapshot} to a source-currency amount. Returns the
-* equivalent base-currency amount. No rounding — callers that persist into
-* an integer minor-unit column must round explicitly with a deterministic
-* rule (`Math.round`, banker's rounding, floor for duty-conservative
-* postings, etc.).
+* Does {@link MINOR_UNIT_FACTOR} carry an explicit exponent for this code?
+*
+* `false` means {@link minorUnitFactor} would ASSUME two decimals. That
+* assumption is right for an ordinary ISO 4217 code and wrong by 100× for a
+* mistyped or lowercased one (`'jpy'`), so a boot-time config validator that
+* accepts an operator-supplied currency should gate on this instead of letting
+* the default answer for it.
 */
-function convertWithSnapshot(sourceAmount, fx) {
-	return sourceAmount * fx.rate;
+function isKnownCurrency(currency) {
+	return Object.hasOwn(MINOR_UNIT_FACTOR, currency);
+}
+function roundMinor(raw, mode) {
+	if (mode === "floor") return Math.floor(raw);
+	if (mode === "ceil") return Math.ceil(raw);
+	return Math.round(Math.abs(raw)) * (raw < 0 ? -1 : 1);
+}
+/**
+* Apply an {@link FxSnapshot} to a source-currency amount.
+*
+* ## Why this takes `Money` and not a number
+*
+* It used to take a bare `number`, which meant nothing could check the amount
+* was denominated in `fx.sourceCurrency`. Applying a USD→BDT snapshot to a EUR
+* amount type-checked, ran, and returned a plausible wrong number — the
+* arithmetic is identical, only the meaning is wrong, so no test that asserts a
+* total would notice. Taking `Money` lets the seam enforce its own
+* precondition: a mismatch throws {@link CurrencyMismatchError}.
+*
+* ## Minor-unit exponents are handled
+*
+* The rate is quoted in MAJOR units (1 source = `rate` base), while `Money`
+* holds minor units, and the two currencies need not share an exponent
+* (USD has 2, JPY has 0). The conversion therefore goes
+* `minor → major → ×rate → base minor`, not a naive `amount × rate`, which is
+* off by 100× for any pair whose exponents differ.
+*/
+function convertWithSnapshot(source, fx, options = {}) {
+	if (source.currency !== fx.sourceCurrency) throw new CurrencyMismatchError(source.currency, fx.sourceCurrency);
+	if (!Number.isFinite(fx.rate)) throw new TypeError(`FxSnapshot.rate must be finite, got ${fx.rate}`);
+	return {
+		amount: roundMinor(source.amount / minorUnitFactor(fx.sourceCurrency) * fx.rate * minorUnitFactor(fx.baseCurrency), options.rounding ?? "half-away-from-zero"),
+		currency: currencyCode(fx.baseCurrency)
+	};
 }
 /**
 * Reverse an {@link FxSnapshot} — reconstruct the source-currency amount
@@ -105,10 +213,17 @@ function convertWithSnapshot(sourceAmount, fx) {
 * currency". Not round-trip safe under rounding; prefer storing the
 * original source amount alongside the base amount when audit fidelity
 * matters.
+*
+* Symmetrically guarded: a base amount that is not in `fx.baseCurrency` throws
+* rather than dividing by a rate that does not describe it.
 */
-function reverseWithSnapshot(baseAmount, fx) {
-	if (fx.rate === 0) throw new Error("FxSnapshot.rate must be non-zero");
-	return baseAmount / fx.rate;
+function reverseWithSnapshot(base, fx, options = {}) {
+	if (base.currency !== fx.baseCurrency) throw new CurrencyMismatchError(base.currency, fx.baseCurrency);
+	if (fx.rate === 0 || !Number.isFinite(fx.rate)) throw new TypeError(`FxSnapshot.rate must be a non-zero finite number, got ${fx.rate}`);
+	return {
+		amount: roundMinor(base.amount / minorUnitFactor(fx.baseCurrency) / fx.rate * minorUnitFactor(fx.sourceCurrency), options.rounding ?? "half-away-from-zero"),
+		currency: currencyCode(fx.sourceCurrency)
+	};
 }
 /**
 * Structural validation — checks shape only. Does NOT verify the rate is
@@ -121,4 +236,4 @@ function isFxSnapshot(value) {
 	return typeof v.sourceCurrency === "string" && typeof v.baseCurrency === "string" && typeof v.rate === "number" && Number.isFinite(v.rate) && v.rate > 0 && v.snapshotAt instanceof Date;
 }
 //#endregion
-export { CURRENCIES, CURRENCY_PATTERN, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };
+export { CURRENCIES, CURRENCY_PATTERN, CurrencyMismatchError, InvalidCurrencyCodeError, MINOR_UNIT_FACTOR, convertWithSnapshot, currencyCode, isCurrencyCode, isFxSnapshot, isKnownCurrency, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };

package/dist/environment.d.mts

@@ -0,0 +1,85 @@
+//#region src/composition/environment.d.ts
+/**
+ * `NODE_ENV` classification — the ONE answer to "which environment is this?".
+ *
+ * ## Why this is a primitive and not four copies
+ *
+ * `NODE_ENV` has two accepted spellings per bucket in practice — `production` OR `prod`, `test` OR
+ * `qa` — so a local comparison against one literal is wrong for the other, and it is wrong in the
+ * expensive direction. Almost every call site computes a NEGATIVE (`!== 'production'`,
+ * `isProduction === false`), so a missed spelling does not close a gate, it OPENS one.
+ *
+ * That is not hypothetical. Every item below was found in shipped code, and **not one of them
+ * threw**:
+ *
+ * | site | what `NODE_ENV=prod` did |
+ * |---|---|
+ * | `arc/plugins/errorHandler.ts` | returned the RAW thrown message of a 500 to the client |
+ * | `arc/auth/sessionManager.ts` | issued session cookies **without `Secure`** |
+ * | gym: pos / revenue / membership / order / catalog / attendance | permitted NON-TRANSACTIONAL money writes in production |
+ * | gym `app.ts` | selected arc's DEVELOPMENT preset in production |
+ * | be-prod `media.engine.ts` | enabled the in-memory media driver fallback — uploads 200, files gone on restart |
+ * | be-prod `contract.ports.ts`, `crm.module.ts` | non-atomic receivable / lead-conversion writes |
+ * | be-prod `logger.ts` | pino's pretty TRANSPORT in production |
+ * | be-prod `guest-order.resource.ts` | rate limiter armed under `qa` and nowhere else |
+ *
+ * `qa` had the mirror problem: classified as development by one host and test by another, so
+ * multi-boot support silently vanished on a QA run.
+ *
+ * **This logic already existed four times** — be-prod `classifyEnv`, gym `businessMode()`, arc's own
+ * CLI config template (as a `z.preprocess`), and implicitly in arc's four raw comparison sites. All
+ * four agreed on the spellings and the buckets, which is exactly why collapsing them is mechanical
+ * rather than a behaviour change. A fifth copy was one new vertical away.
+ *
+ * ## Why primitives owns it
+ *
+ * arc's own ownership rule: *primitives owns pure cross-package contracts, arc owns runtime.* This
+ * is a pure total function with no dependencies, and its consumers are not all arc apps — kernels,
+ * workers, CLIs and the spine need the same answer without pulling in a web framework. primitives
+ * is already a required peer of arc, so every arc host has it at no additional cost.
+ *
+ * ## Prefer an EXPLICIT signal where one exists
+ *
+ * If a caller already has a declared environment — arc's `preset`, a `deployment.config`, an
+ * injected flag — **use that instead**. It is a specific instruction, and this function reads an
+ * ambient default. A specific setting must never be overridden by a general one.
+ */
+/** The three buckets everything downstream reasons about. Mutually exclusive and total. */
+type EnvClass = 'development' | 'test' | 'production';
+/**
+ * Classify a raw `NODE_ENV` value.
+ *
+ * Total by construction — every input yields exactly one bucket, so a caller can never observe a
+ * fourth state or `undefined`.
+ *
+ * ## Whitespace IS trimmed, and that is a deliberate divergence from the four copies
+ *
+ * None of the previous implementations trimmed. A value carrying a trailing space or newline —
+ * routine from a `.env` file, a Docker `ENV` line, or a CI variable pasted with a line ending —
+ * therefore matched nothing and fell through to `development`. That is the dangerous direction: a
+ * genuine production deployment classified as development, which is precisely the failure this
+ * function exists to prevent. Trimming can only ever move a value TOWARD the bucket its author
+ * plainly intended.
+ *
+ * ## An unrecognised value falls back to `development`
+ *
+ * Preserved from all four prior implementations, so adopting this changes no existing behaviour.
+ *
+ * Be aware of what it costs: a typo (`prodction`) classifies as development and therefore OPENS the
+ * gates a production deployment wanted shut. The stricter alternative — normalise known aliases and
+ * THROW on anything else — is more defensible ("an input you do not understand must fail, not
+ * widen"), but it is a breaking operational change for any deployment currently running an
+ * unrecognised value and belongs in its own release with its own test. Do not change it here
+ * silently.
+ */
+declare function classifyEnv(env: string | undefined | null): EnvClass;
+/**
+ * `true` when the value classifies as production.
+ *
+ * A named predicate rather than a `classifyEnv(x) === 'production'` at each call site: the raw
+ * comparison is the shape that caused every defect listed above, so the codebase should not contain
+ * one — even a correct one — for a reader to copy.
+ */
+declare function isProductionEnv(env: string | undefined | null): boolean;
+//#endregion
+export { EnvClass, classifyEnv, isProductionEnv };

package/dist/environment.mjs

@@ -0,0 +1,48 @@
+//#region src/composition/environment.ts
+/**
+* Classify a raw `NODE_ENV` value.
+*
+* Total by construction — every input yields exactly one bucket, so a caller can never observe a
+* fourth state or `undefined`.
+*
+* ## Whitespace IS trimmed, and that is a deliberate divergence from the four copies
+*
+* None of the previous implementations trimmed. A value carrying a trailing space or newline —
+* routine from a `.env` file, a Docker `ENV` line, or a CI variable pasted with a line ending —
+* therefore matched nothing and fell through to `development`. That is the dangerous direction: a
+* genuine production deployment classified as development, which is precisely the failure this
+* function exists to prevent. Trimming can only ever move a value TOWARD the bucket its author
+* plainly intended.
+*
+* ## An unrecognised value falls back to `development`
+*
+* Preserved from all four prior implementations, so adopting this changes no existing behaviour.
+*
+* Be aware of what it costs: a typo (`prodction`) classifies as development and therefore OPENS the
+* gates a production deployment wanted shut. The stricter alternative — normalise known aliases and
+* THROW on anything else — is more defensible ("an input you do not understand must fail, not
+* widen"), but it is a breaking operational change for any deployment currently running an
+* unrecognised value and belongs in its own release with its own test. Do not change it here
+* silently.
+*/
+function classifyEnv(env) {
+	switch ((env ?? "").trim().toLowerCase()) {
+		case "production":
+		case "prod": return "production";
+		case "test":
+		case "qa": return "test";
+		default: return "development";
+	}
+}
+/**
+* `true` when the value classifies as production.
+*
+* A named predicate rather than a `classifyEnv(x) === 'production'` at each call site: the raw
+* comparison is the shape that caused every defect listed above, so the codebase should not contain
+* one — even a correct one — for a reader to copy.
+*/
+function isProductionEnv(env) {
+	return classifyEnv(env) === "production";
+}
+//#endregion
+export { classifyEnv, isProductionEnv };

package/dist/event-infra.d.mts

@@ -1,6 +1,4 @@
 import { DomainEvent, EventHandler, EventTransport, PublishManyResult } from "./events.mjs";
-import { OutboxAcknowledgeOptions, OutboxStore, OutboxWriteOptions } from "./outbox.mjs";
-
 //#region src/events/event-infra.d.ts
 /** Minimal error-only logger — assignable from `console`, pino, fastify.log. */
 interface ErrorLogger {
@@ -87,36 +85,22 @@ declare class InProcessEventBus implements EventTransport {
 /** Factory form of {@link InProcessEventBus} for hosts that prefer functions. */
 declare function createInProcessBus(options?: InProcessEventBusOptions): InProcessEventBus;
 /**
- * In-memory {@link OutboxStore} for tests and local dev. Not for production —
- * hosts wire arc's `MongoOutboxStore`, a mongokit repo via
- * `repositoryAsOutboxStore`, or any durable implementation.
+ * `MemoryOutboxStore` does NOT live here. It is exported from exactly one
+ * place: `@classytic/primitives/memory-outbox`.
  *
- * Implements the required trio (`save` / `getPending` / `acknowledge`) plus
- * optional `purge`. Lease-based methods (`claimPending` / `fail` /
- * `getDeadLettered`) are intentionally omitted — single-process tests don't
- * need them, and kernels only call `save()` themselves. `all()` / `clear()`
- * are test-inspection helpers (not part of the contract).
+ * This module used to also export it — first as a second, MINIMAL
+ * implementation (save / getPending / acknowledge / purge, no leases, no
+ * retry, no dead-lettering, no dedupe, no validation), then briefly as a
+ * back-compat re-export. Both are gone.
+ *
+ * The re-export was tempting: seven kernels imported it from here, and one
+ * line would have spared seven rebuilds. It was still the wrong call. Two live
+ * import paths for one class means new code picks either, the migration stays
+ * permanently half-done, and the next person has to learn which path is
+ * "real". The cost of the move is seven rebuilds; paying it once is cheaper
+ * than carrying a shim forever.
+ *
+ * This subpath is the in-process BUS. The outbox is its own subpath.
  */
-declare class MemoryOutboxStore implements OutboxStore {
-  /**
-   * Deliberately NOT transactional — and saying so is the point.
-   *
-   * This store pushes onto an in-process array, which no database transaction
-   * can roll back. If a caller's Mongo write aborts after `save`, the event
-   * SURVIVES here and describes something that never happened. Declaring
-   * `false` lets a caller that needs real atomicity (`@classytic/access`) refuse
-   * at boot instead of silently inheriting a ghost-event path.
-   */
-  readonly transactionalSave = false;
-  private events;
-  save(event: DomainEvent, _options?: OutboxWriteOptions): Promise<void>;
-  getPending(limit: number): Promise<DomainEvent[]>;
-  acknowledge(eventId: string, _options?: OutboxAcknowledgeOptions): Promise<void>;
-  purge(olderThanMs: number): Promise<number>;
-  /** Every saved event (acknowledged or not) — test inspection helper. */
-  all(): ReadonlyArray<DomainEvent>;
-  /** Reset the store — test helper. */
-  clear(): void;
-}
 //#endregion
-export { ErrorLogger, InProcessEventBus, InProcessEventBusOptions, MemoryOutboxStore, createInProcessBus };
+export { ErrorLogger, InProcessEventBus, InProcessEventBusOptions, createInProcessBus };

package/dist/event-infra.mjs

@@ -78,52 +78,22 @@ function createInProcessBus(options) {
 	return new InProcessEventBus(options);
 }
 /**
-* In-memory {@link OutboxStore} for tests and local dev. Not for production —
-* hosts wire arc's `MongoOutboxStore`, a mongokit repo via
-* `repositoryAsOutboxStore`, or any durable implementation.
+* `MemoryOutboxStore` does NOT live here. It is exported from exactly one
+* place: `@classytic/primitives/memory-outbox`.
 *
-* Implements the required trio (`save` / `getPending` / `acknowledge`) plus
-* optional `purge`. Lease-based methods (`claimPending` / `fail` /
-* `getDeadLettered`) are intentionally omitted — single-process tests don't
-* need them, and kernels only call `save()` themselves. `all()` / `clear()`
-* are test-inspection helpers (not part of the contract).
+* This module used to also export it — first as a second, MINIMAL
+* implementation (save / getPending / acknowledge / purge, no leases, no
+* retry, no dead-lettering, no dedupe, no validation), then briefly as a
+* back-compat re-export. Both are gone.
+*
+* The re-export was tempting: seven kernels imported it from here, and one
+* line would have spared seven rebuilds. It was still the wrong call. Two live
+* import paths for one class means new code picks either, the migration stays
+* permanently half-done, and the next person has to learn which path is
+* "real". The cost of the move is seven rebuilds; paying it once is cheaper
+* than carrying a shim forever.
+*
+* This subpath is the in-process BUS. The outbox is its own subpath.
 */
-var MemoryOutboxStore = class {
-	/**
-	* Deliberately NOT transactional — and saying so is the point.
-	*
-	* This store pushes onto an in-process array, which no database transaction
-	* can roll back. If a caller's Mongo write aborts after `save`, the event
-	* SURVIVES here and describes something that never happened. Declaring
-	* `false` lets a caller that needs real atomicity (`@classytic/access`) refuse
-	* at boot instead of silently inheriting a ghost-event path.
-	*/
-	transactionalSave = false;
-	events = [];
-	async save(event, _options) {
-		this.events.push({ event });
-	}
-	async getPending(limit) {
-		return this.events.filter((e) => !e.acknowledgedAt).slice(0, limit).map((e) => e.event);
-	}
-	async acknowledge(eventId, _options) {
-		const entry = this.events.find((e) => e.event.meta.id === eventId);
-		if (entry) entry.acknowledgedAt = /* @__PURE__ */ new Date();
-	}
-	async purge(olderThanMs) {
-		const cutoff = Date.now() - olderThanMs;
-		const before = this.events.length;
-		this.events = this.events.filter((e) => !e.acknowledgedAt || e.acknowledgedAt.getTime() >= cutoff);
-		return before - this.events.length;
-	}
-	/** Every saved event (acknowledged or not) — test inspection helper. */
-	all() {
-		return this.events.map((e) => e.event);
-	}
-	/** Reset the store — test helper. */
-	clear() {
-		this.events = [];
-	}
-};
 //#endregion
-export { InProcessEventBus, MemoryOutboxStore, createInProcessBus };
+export { InProcessEventBus, createInProcessBus };