@classytic/primitives 0.1.0

package/dist/result.d.mts

@@ -0,0 +1,32 @@
+//#region src/result.d.ts
+/**
+ * A discriminated-union result type — an alternative to throwing for expected
+ * domain failures. Zero-cost: use it where failure is a first-class outcome
+ * (validation, pre-conditions), keep `throw` for truly exceptional paths
+ * (infra, programmer error).
+ */
+type Result<T, E = Error> = {
+  readonly ok: true;
+  readonly value: T;
+} | {
+  readonly ok: false;
+  readonly error: E;
+};
+declare function ok<T>(value: T): Result<T, never>;
+declare function err<E>(error: E): Result<never, E>;
+declare function isOk<T, E>(r: Result<T, E>): r is {
+  ok: true;
+  value: T;
+};
+declare function isErr<T, E>(r: Result<T, E>): r is {
+  ok: false;
+  error: E;
+};
+/** Transform a successful value; pass-through on error. */
+declare function mapResult<T, U, E>(r: Result<T, E>, fn: (v: T) => U): Result<U, E>;
+/** Transform an error value; pass-through on success. */
+declare function mapError<T, E, F>(r: Result<T, E>, fn: (e: E) => F): Result<T, F>;
+/** Unwrap — returns the value or throws the error. Convenience only. */
+declare function unwrap<T, E>(r: Result<T, E>): T;
+//#endregion
+export { Result, err, isErr, isOk, mapError, mapResult, ok, unwrap };

package/dist/result.mjs

@@ -0,0 +1,34 @@
+//#region src/result.ts
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function err(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+function isOk(r) {
+	return r.ok;
+}
+function isErr(r) {
+	return !r.ok;
+}
+/** Transform a successful value; pass-through on error. */
+function mapResult(r, fn) {
+	return r.ok ? ok(fn(r.value)) : r;
+}
+/** Transform an error value; pass-through on success. */
+function mapError(r, fn) {
+	return r.ok ? r : err(fn(r.error));
+}
+/** Unwrap — returns the value or throws the error. Convenience only. */
+function unwrap(r) {
+	if (r.ok) return r.value;
+	throw r.error;
+}
+//#endregion
+export { err, isErr, isOk, mapError, mapResult, ok, unwrap };

package/dist/sla.d.mts

@@ -0,0 +1,71 @@
+//#region src/sla.d.ts
+/**
+ * Service-Level Agreement value object + breach-detection helpers.
+ *
+ * Describes a target duration a task must complete within, along with what
+ * to do when the deadline lapses. Consumers: `@classytic/flow` (wave picking,
+ * shipment), `@classytic/order` (fulfillment), `@classytic/commission`
+ * (statement close).
+ *
+ * Pure data + pure helpers. No scheduler, no events — hosts schedule the
+ * check (cron, Temporal activity, webhook) and call {@link isBreached} at
+ * evaluation time.
+ *
+ * @example
+ * import { type SLA, isBreached, remainingMs, breachedAt } from '@classytic/primitives/sla';
+ *
+ * const sla: SLA = { targetDurationMs: 2 * 60 * 60 * 1000, breachPolicy: 'escalate' };
+ * const startedAt = new Date('2026-04-17T10:00:00Z');
+ * isBreached(sla, startedAt, new Date('2026-04-17T11:00:00Z')); // false (1h elapsed of 2h)
+ * isBreached(sla, startedAt, new Date('2026-04-17T13:00:00Z')); // true
+ * breachedAt(sla, startedAt); // → Date('2026-04-17T12:00:00Z')
+ */
+/**
+ * Policy describing what a host should do when the SLA is breached. The
+ * primitive does *not* execute the policy — the host reads this field and
+ * decides (log a warn, page oncall, block the workflow, etc.).
+ */
+type BreachPolicy = 'warn' | 'escalate' | 'block';
+interface SLA {
+  /** Target duration in milliseconds. Must be a positive integer. */
+  readonly targetDurationMs: number;
+  readonly breachPolicy: BreachPolicy;
+  /**
+   * Optional stable reference to a host-defined action (webhook URL, workflow
+   * name, alert route). The primitive just carries the string — host resolves.
+   */
+  readonly breachActionRef?: string;
+  /** Optional human label — useful for dashboards and audit logs. */
+  readonly label?: string;
+}
+type SLAErrorCode = 'INVALID_TARGET' | 'INVALID_START';
+declare class SLAError extends Error {
+  readonly name = "SLAError";
+  readonly code: SLAErrorCode;
+  constructor(code: SLAErrorCode, message: string);
+}
+/** Validate an SLA spec. Call this before storing host-side. */
+declare function validateSLA(sla: SLA): void;
+/**
+ * The timestamp at which the SLA will be (or was) breached — `startedAt +
+ * targetDurationMs`.
+ */
+declare function breachedAt(sla: SLA, startedAt: Date): Date;
+/**
+ * Milliseconds remaining before breach. Negative if already breached.
+ * Clock source is passed explicitly so tests remain deterministic and
+ * hosts can evaluate against any reference time.
+ */
+declare function remainingMs(sla: SLA, startedAt: Date, now?: Date): number;
+/** Elapsed milliseconds since `startedAt`. */
+declare function elapsedMs(startedAt: Date, now?: Date): number;
+/** True if `now` is at or past the deadline. */
+declare function isBreached(sla: SLA, startedAt: Date, now?: Date): boolean;
+/**
+ * Elapsed-fraction of the SLA window (0 = just started, 1 = exactly at
+ * deadline, > 1 = breached). Useful for progress bars and early-warning
+ * thresholds (e.g., warn at 80% consumed).
+ */
+declare function consumedFraction(sla: SLA, startedAt: Date, now?: Date): number;
+//#endregion
+export { BreachPolicy, SLA, SLAError, SLAErrorCode, breachedAt, consumedFraction, elapsedMs, isBreached, remainingMs, validateSLA };

package/dist/sla.mjs

@@ -0,0 +1,57 @@
+//#region src/sla.ts
+var SLAError = class extends Error {
+	name = "SLAError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/** Validate an SLA spec. Call this before storing host-side. */
+function validateSLA(sla) {
+	if (!Number.isInteger(sla.targetDurationMs) || sla.targetDurationMs <= 0 || !Number.isFinite(sla.targetDurationMs)) throw new SLAError("INVALID_TARGET", `targetDurationMs must be a positive integer, got ${sla.targetDurationMs}`);
+}
+/**
+* The timestamp at which the SLA will be (or was) breached — `startedAt +
+* targetDurationMs`.
+*/
+function breachedAt(sla, startedAt) {
+	validateSLA(sla);
+	assertValidDate(startedAt);
+	return new Date(startedAt.getTime() + sla.targetDurationMs);
+}
+/**
+* Milliseconds remaining before breach. Negative if already breached.
+* Clock source is passed explicitly so tests remain deterministic and
+* hosts can evaluate against any reference time.
+*/
+function remainingMs(sla, startedAt, now = /* @__PURE__ */ new Date()) {
+	validateSLA(sla);
+	assertValidDate(startedAt);
+	assertValidDate(now);
+	return startedAt.getTime() + sla.targetDurationMs - now.getTime();
+}
+/** Elapsed milliseconds since `startedAt`. */
+function elapsedMs(startedAt, now = /* @__PURE__ */ new Date()) {
+	assertValidDate(startedAt);
+	assertValidDate(now);
+	return now.getTime() - startedAt.getTime();
+}
+/** True if `now` is at or past the deadline. */
+function isBreached(sla, startedAt, now = /* @__PURE__ */ new Date()) {
+	return remainingMs(sla, startedAt, now) <= 0;
+}
+/**
+* Elapsed-fraction of the SLA window (0 = just started, 1 = exactly at
+* deadline, > 1 = breached). Useful for progress bars and early-warning
+* thresholds (e.g., warn at 80% consumed).
+*/
+function consumedFraction(sla, startedAt, now = /* @__PURE__ */ new Date()) {
+	validateSLA(sla);
+	return elapsedMs(startedAt, now) / sla.targetDurationMs;
+}
+function assertValidDate(d) {
+	if (Number.isNaN(d.getTime())) throw new SLAError("INVALID_START", "date is not a valid Date");
+}
+//#endregion
+export { SLAError, breachedAt, consumedFraction, elapsedMs, isBreached, remainingMs, validateSLA };

package/dist/split-allocation.d.mts

@@ -0,0 +1,84 @@
+//#region src/split-allocation.d.ts
+/**
+ * Deterministic integer allocation across N subjects.
+ *
+ * Given a `total` and a set of `subjects`, distribute the total across the
+ * subjects in integer minor units using a chosen `method`. The sum of the
+ * returned parts is *exactly* equal to `total` — no drift, no lost pennies —
+ * via the largest-remainder method.
+ *
+ * Designed for landed-cost allocation (flow), commission payout splits
+ * (commission), tax allocation (bd-tax), and payment splits (revenue).
+ *
+ * @example
+ * // Allocate 1000 cents of freight across 3 line items by weight.
+ * allocate(1000, [
+ *   { id: 'L1', weight: 2 },
+ *   { id: 'L2', weight: 3 },
+ *   { id: 'L3', weight: 5 },
+ * ], 'by-weight');
+ * // → { total: 1000, method: 'by-weight', parts: [
+ * //     { id: 'L1', amount: 200, weight: 2 },
+ * //     { id: 'L2', amount: 300, weight: 3 },
+ * //     { id: 'L3', amount: 500, weight: 5 },
+ * //   ] }
+ *
+ * @example
+ * // Residue goes to the largest fractional remainder, deterministic.
+ * allocate(100, [
+ *   { id: 'A', weight: 1 },
+ *   { id: 'B', weight: 1 },
+ *   { id: 'C', weight: 1 },
+ * ], 'by-weight');
+ * // → parts sum to 100: [34, 33, 33] (first-order tie-break on residue)
+ */
+/**
+ * Allocation method. Proportional methods (`by-qty` | `by-weight` | `by-volume`
+ * | `by-value`) share the same algorithm — the label carries *semantic* meaning
+ * for downstream audit trails ("this cost was split by volume, not by value").
+ * `by-percent` validates the weights sum to 100. `equal` ignores weights.
+ */
+type SplitMethod = 'equal' | 'by-qty' | 'by-weight' | 'by-volume' | 'by-value' | 'by-percent';
+interface SplitSubject {
+  /** Caller-supplied identifier, preserved on the matching part. */
+  readonly id: string;
+  /** Non-negative numeric weight for proportional methods. Required unless `method === 'equal'` or `'by-percent'`. */
+  readonly weight?: number;
+  /** Percent in [0, 100] for `method === 'by-percent'`. Sum across subjects must equal 100 (± 0.001). */
+  readonly percent?: number;
+}
+interface SplitPart {
+  readonly id: string;
+  /** Integer in the same unit as `total`. */
+  readonly amount: number;
+  /** The effective weight used for this subject (for audit trails). */
+  readonly weight: number;
+}
+interface SplitResult {
+  /** Echoes the input total. Always equals `sum(parts[i].amount)` exactly. */
+  readonly total: number;
+  readonly method: SplitMethod;
+  readonly parts: readonly SplitPart[];
+}
+type SplitAllocationErrorCode = 'INVALID_TOTAL' | 'EMPTY_SUBJECTS' | 'INVALID_WEIGHT' | 'INVALID_PERCENT' | 'ZERO_WEIGHT_SUM' | 'DUPLICATE_SUBJECT_ID';
+declare class SplitAllocationError extends Error {
+  readonly name = "SplitAllocationError";
+  readonly code: SplitAllocationErrorCode;
+  constructor(code: SplitAllocationErrorCode, message: string);
+}
+/**
+ * Allocate `total` across `subjects` using `method`. Returns one part per
+ * subject, in input order. `sum(parts[i].amount) === total` is guaranteed.
+ *
+ * Rounding residue is distributed via the largest-remainder method: the
+ * subjects with the largest fractional share get +1 (or -1 for negative
+ * totals) until the residue is exhausted. Ties are broken by input order —
+ * identical inputs always produce identical outputs.
+ *
+ * @throws SplitAllocationError — see {@link SplitAllocationErrorCode} for cases.
+ */
+declare function allocate(total: number, subjects: readonly SplitSubject[], method: SplitMethod): SplitResult;
+/** True if `sum(parts[i].amount) === result.total`. Useful as an assertion in host code. */
+declare function isBalanced(result: SplitResult): boolean;
+//#endregion
+export { SplitAllocationError, SplitAllocationErrorCode, SplitMethod, SplitPart, SplitResult, SplitSubject, allocate, isBalanced };

package/dist/split-allocation.mjs

@@ -0,0 +1,115 @@
+//#region src/split-allocation.ts
+var SplitAllocationError = class extends Error {
+	name = "SplitAllocationError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/** Tolerance for `by-percent` sum validation — accommodates floating-point drift on typical inputs. */
+const PERCENT_TOLERANCE = .001;
+/**
+* Allocate `total` across `subjects` using `method`. Returns one part per
+* subject, in input order. `sum(parts[i].amount) === total` is guaranteed.
+*
+* Rounding residue is distributed via the largest-remainder method: the
+* subjects with the largest fractional share get +1 (or -1 for negative
+* totals) until the residue is exhausted. Ties are broken by input order —
+* identical inputs always produce identical outputs.
+*
+* @throws SplitAllocationError — see {@link SplitAllocationErrorCode} for cases.
+*/
+function allocate(total, subjects, method) {
+	if (!Number.isFinite(total) || !Number.isInteger(total)) throw new SplitAllocationError("INVALID_TOTAL", `total must be a finite integer, got ${total}`);
+	if (subjects.length === 0) {
+		if (total === 0) return {
+			total: 0,
+			method,
+			parts: []
+		};
+		throw new SplitAllocationError("EMPTY_SUBJECTS", `cannot allocate non-zero total (${total}) across zero subjects`);
+	}
+	const seenIds = /* @__PURE__ */ new Set();
+	for (const s of subjects) {
+		if (seenIds.has(s.id)) throw new SplitAllocationError("DUPLICATE_SUBJECT_ID", `duplicate subject id: ${s.id}`);
+		seenIds.add(s.id);
+	}
+	const weights = resolveWeights(subjects, method);
+	const sign = total < 0 ? -1 : 1;
+	return {
+		total,
+		method,
+		parts: distribute(Math.abs(total), weights).map((amount, i) => {
+			const subj = subjects[i];
+			const w = weights[i];
+			if (subj === void 0 || w === void 0) throw new Error("split-allocation invariant: parts, subjects, and weights out of sync");
+			return {
+				id: subj.id,
+				amount: amount * sign,
+				weight: w
+			};
+		})
+	};
+}
+/**
+* Resolve the effective numeric weight per subject based on method.
+* Validates inputs and throws on bad data.
+*/
+function resolveWeights(subjects, method) {
+	if (method === "equal") return subjects.map(() => 1);
+	if (method === "by-percent") {
+		const percents = subjects.map((s, i) => {
+			const p = s.percent;
+			if (p === void 0) throw new SplitAllocationError("INVALID_PERCENT", `subject[${i}] (id=${s.id}) missing percent for method='by-percent'`);
+			if (!Number.isFinite(p) || p < 0 || p > 100) throw new SplitAllocationError("INVALID_PERCENT", `subject[${i}] (id=${s.id}) percent must be in [0, 100], got ${p}`);
+			return p;
+		});
+		const sum = percents.reduce((a, b) => a + b, 0);
+		if (Math.abs(sum - 100) > PERCENT_TOLERANCE) throw new SplitAllocationError("INVALID_PERCENT", `percents must sum to 100 (±${PERCENT_TOLERANCE}), got ${sum}`);
+		return percents;
+	}
+	const weights = subjects.map((s, i) => {
+		const w = s.weight;
+		if (w === void 0) throw new SplitAllocationError("INVALID_WEIGHT", `subject[${i}] (id=${s.id}) missing weight for method='${method}'`);
+		if (!Number.isFinite(w) || w < 0) throw new SplitAllocationError("INVALID_WEIGHT", `subject[${i}] (id=${s.id}) weight must be finite and non-negative, got ${w}`);
+		return w;
+	});
+	if (weights.reduce((a, b) => a + b, 0) === 0) throw new SplitAllocationError("ZERO_WEIGHT_SUM", `sum of weights is zero — cannot allocate proportionally`);
+	return weights;
+}
+/**
+* Core largest-remainder distributor. Operates on non-negative `total` and
+* non-negative `weights` with `sum(weights) > 0`. Guarantees:
+*   sum(result) === total
+*   result.length === weights.length
+*   determinism (ties broken by input order).
+*/
+function distribute(total, weights) {
+	const weightSum = weights.reduce((a, b) => a + b, 0);
+	if (weightSum === 0) return weights.map(() => 0);
+	const raw = weights.map((w) => total * w / weightSum);
+	const floored = raw.map((r) => Math.floor(r));
+	const residue = total - floored.reduce((a, b) => a + b, 0);
+	if (residue === 0) return floored;
+	const order = raw.map((r, i) => ({
+		i,
+		frac: r - Math.floor(r)
+	})).sort((a, b) => {
+		if (b.frac !== a.frac) return b.frac - a.frac;
+		return a.i - b.i;
+	});
+	const result = floored.slice();
+	for (let k = 0; k < residue; k++) {
+		const entry = order[k];
+		if (entry === void 0) break;
+		result[entry.i] = (result[entry.i] ?? 0) + 1;
+	}
+	return result;
+}
+/** True if `sum(parts[i].amount) === result.total`. Useful as an assertion in host code. */
+function isBalanced(result) {
+	return result.parts.reduce((acc, p) => acc + p.amount, 0) === result.total;
+}
+//#endregion
+export { SplitAllocationError, allocate, isBalanced };

package/dist/tenant.d.mts

@@ -0,0 +1,122 @@
+//#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.
+   *
+   * @default '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

@@ -0,0 +1,54 @@
+//#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");
+	if (strategy === "none") return {
+		...DEFAULT_TENANT_CONFIG,
+		...config,
+		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,
+			strategy: "custom",
+			enabled: config.enabled ?? true,
+			resolve: config.resolve
+		};
+	}
+	return {
+		...DEFAULT_TENANT_CONFIG,
+		...config,
+		strategy: "field",
+		enabled: config.enabled ?? true
+	};
+}
+//#endregion
+export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };