@classytic/primitives 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,168 @@
 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.6.0] - 2026-05-17
+
+### Added — five new primitives for CRM / workflow domains
+
+These were extracted after deep-diving Twenty, Huly Platform, Frappe CRM,
+and NocoBase. Each fills a gap the existing primitives didn't cover, and
+each ships under its own flat subpath import (no breaking changes).
+
+- **`/phone`** — `PhoneNumber` value object + `parsePhone(input)` that
+  normalizes free-form input to E.164, captures the country calling code
+  as a discrete field, and reports failures via `Result<PhoneNumber,
+  PhoneError>`. Zero external deps; ITU-T E.164 prefixes inlined. Hosts
+  that want region-of-issue / line-type detection layer on top with
+  libphonenumber-js.
+
+- **`/status-history`** — Generic, immutable status-change log:
+  `StatusChangeEntry<TStatus>`, `appendStatus()`, `timeInStatus()`,
+  `lastTransitionTo()`. Captures `durationInPriorMs` at write time
+  (Frappe's "status change log" pattern), so funnel-velocity dashboards
+  ("avg time in Qualification") work without re-walking timestamps.
+  Pairs naturally with `/state-machine`.
+
+- **`/condition`** — Tiny JSON-serializable predicate DSL: `FieldCondition`
+  (`{ field, op, value }`) composed via `AllCondition` / `AnyCondition`
+  / `NotCondition`, plus a total `evaluate(condition, target)` and a
+  `validateCondition()` for boot-time schema checks. Powers SLA scope
+  filters, drip "if opened/clicked" branches, automation triggers, and
+  permission row-scopes — anywhere a predicate needs to round-trip
+  through a database.
+
+- **`/mixin`** — Additive type composition without subclassing:
+  `withMixin<T, K, M>()` / `getMixin()` / `hasMixin()` / `withoutMixin()`.
+  Lets a `Contact` carry per-domain payloads (`mixins.customer`,
+  `mixins.lead-fit`) on a typed `mixins` namespace without bloating the
+  base type. Distilled from Huly's mixin idea minus the decorators,
+  global hierarchy, and proxies.
+
+- **`/sla-policy`** — Higher-order SLA layered on the existing `/sla`:
+  priority matrix (`urgent` / `high` / `normal` → durations), first-
+  response vs rolling-response semantics, and working-hours window
+  (weekdays + start/end minute + holidays). `defineSLAPolicy()` validates
+  at boot; `evaluateSLAStatus()` produces `{ kind, responseBy,
+  remainingMs, breached }` from a policy + per-entity inputs. The
+  existing simple `/sla` interface is unchanged — `sla-policy` derives
+  concrete `SLA` instances from a policy + priority and delegates to it.
+
+### Changed — source-tree reorganization (no public-surface impact)
+
+The 24 primitive source files moved from a flat `src/*.ts` layout into
+six category folders so the package is self-documenting at the file
+system level:
+
+```
+src/
+  money/           money, currency, split-allocation, bank-transaction, payment-gateway
+  identity/        person, address, phone
+  scheduling/      period, cadence, sla, sla-policy
+  workflow/        state-machine, status-history, approval, hold, condition
+  events/          events, outbox
+  composition/     mixin, reference, context, brand, result
+```
+
+**Public subpath imports are unchanged** — `@classytic/primitives/money`,
+`@classytic/primitives/sla`, etc. still resolve. tsdown emits each entry
+to `dist/<name>.mjs` regardless of source nesting. Existing consumers
+upgrade with `npm install @classytic/primitives@^0.6.0` and a no-op
+diff.
+
+### Dependencies
+
+Still zero runtime deps. Node 22+.
+
+## [0.5.0] - 2026-05-05
+
+### Added — `/bank-transaction` subpath
+
+Canonical bank-feed shapes shared across `@classytic/fin-io` (parsers
+produce these), `@classytic/revenue` (`transactionRepository.import()`
+consumes them), and `@classytic/ledger` (`bankStatementMapper`
+consumes them). Single source of truth for the cross-package
+vocabulary; eliminates the structural mirrors fin-io and revenue
+were carrying.
+
+Exports: `BankTransaction`, `BankCounterparty`, `BankAccount`,
+`BankStatement`, `BankStatementSource`, `BankImportReport`,
+`BankImportRowError`. All anchored on `Money` from `/money` (integer
+minor units, `number`).
+
+### Added — `/payment-gateway` subpath
+
+Canonical payment-gateway data shapes. **Lets any provider package
+(Stripe, Razorpay, SSLCommerz, PayPal, bKash, Nagad, manual, …)
+implement against primitives' types without depending on revenue's
+heavyweight runtime.** Provider authors peer-dep on
+`@classytic/primitives` only.
+
+Exports: `CreateIntentParams`, `PaymentIntent`, `PaymentResult`,
+`RefundResult`, `WebhookEvent`, `ProviderCapabilities`. All `amount`
+fields are `Money` from `/money` (no flat `amount: number, currency:
+string` pairs — currency travels inside Money).
+
+The `PaymentProvider` abstract class — the *contract* every provider
+must satisfy — stays in `@classytic/revenue`. Revenue is the data
+engine that consumes providers; provider packages live elsewhere.
+
+### Architectural intent
+
+Revenue 3.0 + primitives 0.5 + fin-io 0.3 establish a clean
+three-tier seam:
+
+  1. **primitives** — pure data shapes (no runtime, no deps). Owns
+     `Money`, `BankTransaction`, `PaymentIntent`, every cross-
+     package vocabulary type.
+  2. **revenue** — the engine. Owns the abstract contracts
+     (`PaymentProvider`, `BankFeedProvider`), state machines, repos.
+     Consumes primitives shapes.
+  3. **provider packages** (`revenue-stripe`, `revenue-razorpay`,
+     `@classytic/fin-io/adapters/revenue`, …) — implementations.
+     Peer-dep on primitives. Optional peer-dep on revenue for the
+     abstract base class.
+
+This eliminates the cycle where every provider package transitively
+pulled mongoose + mongokit just to know what a `PaymentIntent`
+looked like. Tree-shaking, build times, and dep-graph honesty all
+improve.
+
+### Migration
+
+Consumers MUST import from primitives subpaths. No re-exports from
+revenue or fin-io (PACKAGE_RULES P2):
+
+```ts
+// Before
+import type { PaymentIntent, CreateIntentParams } from '@classytic/revenue';
+import type { CanonicalTransaction, Money } from '@classytic/fin-io';
+
+// After
+import type {
+  PaymentIntent,
+  CreateIntentParams,
+} from '@classytic/primitives/payment-gateway';
+import type { BankTransaction } from '@classytic/primitives/bank-transaction';
+import type { Money } from '@classytic/primitives/money';
+```
+
+Provider helper classes (`PaymentIntent`, `PaymentResult`,
+`RefundResult`, `WebhookEvent`) are deleted from revenue — they were
+trivial wrappers around plain objects. Provider implementations now
+return plain object literals matching the interface.
+
+`CreateIntentParams.amount` is now `Money` (`{ amount: number,
+currency: string }`), not the flat `amount + currency` pair. Revenue's
+repository wraps internally:
+
+```ts
+const intent = await provider.createIntent({
+  amount: { amount: params.amount, currency },
+  metadata: params.metadata,
+  ...params.paymentData,
+});
+```
+
 ## [0.3.1] - 2026-05-02
 
 ### Added — state-machine ↔ mongokit/sqlitekit integration

package/dist/address.d.mts

@@ -1,4 +1,4 @@
-//#region src/address.d.ts
+//#region src/identity/address.d.ts
 /**
  * Postal address.
  *

package/dist/address.mjs

@@ -1,4 +1,4 @@
-//#region src/address.ts
+//#region src/identity/address.ts
 function toGeoJsonPoint(p) {
 	return {
 		type: "Point",

package/dist/approval.d.mts

@@ -1,4 +1,4 @@
-//#region src/approval.d.ts
+//#region src/workflow/approval.d.ts
 /**
  * Approval chain value object and pure state-transition helpers.
  *

package/dist/approval.mjs

@@ -1,4 +1,4 @@
-//#region src/approval.ts
+//#region src/workflow/approval.ts
 var ApprovalError = class extends Error {
 	name = "ApprovalError";
 	code;

package/dist/bank-transaction.d.mts

@@ -0,0 +1,167 @@
+import { Money } from "./money.mjs";
+
+//#region src/money/bank-transaction.d.ts
+/**
+ * The other side of a bank transaction. All fields optional — different
+ * formats populate different subsets:
+ *   OFX     usually carries `name` only.
+ *   CAMT    carries IBAN + BIC + name (SEPA structured data).
+ *   Plaid   carries `merchant_name` mapped to `name`.
+ *   CSV     varies; usually `name` + maybe `accountNumber`.
+ */
+interface BankCounterparty {
+  /** Free-text name as the bank emits it. */
+  name?: string;
+  /**
+   * Vendor-stable identifier — bank's own customer ID, structured
+   * remittance reference (ISO 11649), etc. Distinct from the
+   * transaction-level `reference`.
+   */
+  identifier?: string;
+  /** International Bank Account Number (SEPA / EU). */
+  iban?: string;
+  /** Domestic account number. */
+  accountNumber?: string;
+  /** Bank / SWIFT BIC. */
+  bic?: string;
+  /** US ABA routing / Canadian transit. */
+  routingNumber?: string;
+}
+/**
+ * Identifies the account a statement / sync batch is for. Different
+ * formats populate different subsets — consumers should treat every
+ * field except `currency` as best-effort.
+ */
+interface BankAccount {
+  iban?: string;
+  accountNumber?: string;
+  /** US ABA / SWIFT BIC / domestic bank code. Generic — format-specific. */
+  bankCode?: string;
+  /** Human-readable bank name. */
+  bankName?: string;
+  /** Account holder name as the bank emits it. */
+  ownerName?: string;
+  /** Type as the bank classifies it: `'CHECKING'`, `'SAVINGS'`, `'CREDITLINE'`. */
+  accountType?: string;
+  /**
+   * ISO 4217 of the account itself. REQUIRED — synthesized from format
+   * defaults if absent (parsers MUST fill this in).
+   */
+  currency: string;
+}
+/**
+ * One row from a bank statement / accounting feed sync.
+ *
+ * `externalId` is REQUIRED — without it idempotent re-import is broken.
+ * Synthesize one from `(date | amount | description hash)` if the
+ * upstream format lacks a vendor-stable id.
+ */
+interface BankTransaction {
+  /**
+   * Vendor-stable unique identifier. REQUIRED.
+   *
+   *   OFX:    `<FITID>` from the source file.
+   *   CAMT:   `<NtryRef>` or `<AcctSvcrRef>`.
+   *   QBO:    `Id` from the QBO API.
+   *   Plaid:  `transaction_id`.
+   *   CSV:    synthesized as `sha256(date|amount|description)` truncated
+   *           to 16 hex chars; parser should emit a warning.
+   *
+   * Used by consumers to enforce idempotent re-import via
+   * `(orgId, bankAccountId, externalId)` partial-unique indexes.
+   * Distinct from any host-chosen request-scoped idempotency key.
+   */
+  externalId: string;
+  /** When the bank booked the entry. */
+  postedDate: Date;
+  /** When funds become available (cleared). May equal `postedDate`. */
+  valueDate?: Date;
+  /**
+   * Signed amount in integer minor units. Positive = inflow to the
+   * account holder, negative = outflow. Currency carried inside `Money`.
+   */
+  amount: Money;
+  /** Free-text description as the bank emitted it. */
+  description: string;
+  /** Counterparty (payer / payee) when the format provides one. */
+  counterparty?: BankCounterparty;
+  /** Bank-provided reference number, check number, end-to-end id. */
+  reference?: string;
+  /**
+   * Bank-provided category if any. Rare in OFX / CAMT, common in
+   * Plaid and consumer-finance CSV (Mint / YNAB).
+   */
+  category?: string;
+  /** Running balance on the account after this entry, if available. */
+  balanceAfter?: Money;
+  /** Format-specific entry-type code (`'DEBIT'`, `'CREDIT'`, `'CHECK'`, …). */
+  type?: string;
+  /**
+   * Format-specific raw record. Pass-through for audit / debugging.
+   * Consumers MUST NOT rely on this — schema may change between fin-io
+   * minor versions. Discard before persistence if size is a concern.
+   */
+  raw?: unknown;
+}
+/**
+ * Aggregate envelope produced by file-format parsers (OFX, CAMT.053,
+ * MT940, CSV, IIF). Sync providers (Plaid CDC, QBO CDC) emit
+ * `BankTransaction[]` directly without the statement wrapper because
+ * sync is continuous, not statement-scoped.
+ */
+interface BankStatement {
+  account: BankAccount;
+  /** Statement period the parser observed. */
+  period: {
+    from: Date;
+    to: Date;
+  };
+  /** Opening balance at `period.from`. */
+  openingBalance: Money;
+  /** Closing balance at `period.to`. */
+  closingBalance: Money;
+  /**
+   * Available balance at statement end (may differ from
+   * `closingBalance` for pending-but-not-cleared items).
+   */
+  availableBalance?: Money;
+  transactions: BankTransaction[];
+  /** Provenance metadata — which format produced this statement. */
+  source: BankStatementSource;
+}
+interface BankStatementSource {
+  /**
+   * Format the statement was parsed from. The set is closed —
+   * consumers can switch on it exhaustively. Add new variants here
+   * (and bump the package minor version) when adding a new parser.
+   */
+  format: 'ofx' | 'qfx' | 'camt053' | 'mt940' | 'csv' | 'iif' | 'xero-csv' | 'plaid' | 'qbo';
+  /** Format version — `'OFX 2.1.1'`, `'CAMT.053.001.08'`, etc. */
+  version?: string;
+  /** When the file was generated by the bank, if present. */
+  generatedAt?: Date;
+  /** Bank / vendor software fingerprint (e.g. OFX FI ORG). */
+  softwareId?: string;
+}
+/**
+ * Per-row failure during a bulk import. Consumers (revenue's `import()`)
+ * collect these without aborting the batch.
+ */
+interface BankImportRowError {
+  externalId: string;
+  reason: string;
+  row?: BankTransaction;
+}
+/**
+ * Outcome of a bulk import. Same shape ledger's `wireImport` reports
+ * for symmetry.
+ */
+interface BankImportReport {
+  inserted: number;
+  updated: number;
+  skipped: number;
+  errors: BankImportRowError[];
+  durationMs: number;
+}
+//#endregion
+export { BankAccount, BankCounterparty, BankImportReport, BankImportRowError, BankStatement, BankStatementSource, BankTransaction };

package/dist/bank-transaction.mjs

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

package/dist/{brand-DApaegoR.d.mts → brand-LLXqoh5J.d.mts}

@@ -1,4 +1,4 @@
-//#region src/brand.d.ts
+//#region src/composition/brand.d.ts
 /**
  * Type utilities for building nominal types and transforming shapes.
  *

package/dist/brand.d.mts

@@ -1,2 +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";
+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-LLXqoh5J.mjs";
 export { Brand, DeepPartial, DeepReadonly, KeysMatching, NonEmptyArray, Nullable, OptionalKeys, Prettify, RequireKeys };

package/dist/cadence.d.mts

@@ -1,4 +1,4 @@
-//#region src/cadence.d.ts
+//#region src/scheduling/cadence.d.ts
 /**
  * Recurrence spec + pure date arithmetic.
  *

package/dist/cadence.mjs

@@ -1,4 +1,4 @@
-//#region src/cadence.ts
+//#region src/scheduling/cadence.ts
 var CadenceError = class extends Error {
 	name = "CadenceError";
 	code;

package/dist/condition.d.mts

@@ -0,0 +1,76 @@
+//#region src/workflow/condition.d.ts
+/**
+ * Tiny JSON-serializable predicate DSL + evaluator.
+ *
+ * Hosts need to express "when this is true, do that" rules in places that
+ * can't carry code — SLA scope filters, drip-sequence branches ("if opened
+ * within 24h"), automation triggers, permission row-scopes. A 60-line
+ * predicate spec covers every realistic case better than a hand-rolled
+ * SQL-like grammar.
+ *
+ * Two layers:
+ *   1. `Condition` — pure data. JSON-safe. Round-trips through DB.
+ *   2. `evaluate(condition, value)` — pure function. Walks a dotted-path
+ *      expression on `value`, applies the comparator, returns boolean.
+ *
+ * No regex parsing, no AST tooling, no string interpolation — the grammar
+ * is structurally typed and the evaluator is a 30-line switch.
+ *
+ * @example Single comparison
+ *   evaluate({ field: 'status', op: 'eq', value: 'won' }, opportunity);
+ *
+ * @example Composite — drip "if opened in last 7d AND not clicked"
+ *   evaluate(
+ *     {
+ *       all: [
+ *         { field: 'lastOpenedAt', op: 'gte', value: sevenDaysAgo },
+ *         { field: 'lastClickedAt', op: 'isNull' },
+ *       ],
+ *     },
+ *     contactEngagement,
+ *   );
+ */
+/**
+ * Comparators. Kept small — every operator here has a single, unambiguous
+ * semantic across types. `in` accepts an array; `contains` accepts a single
+ * scalar against an array field; `startsWith`/`endsWith` are string-only;
+ * `isNull` / `isNotNull` have no `value`.
+ */
+type Comparator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith' | 'isNull' | 'isNotNull';
+/** Atomic predicate: extract `field` from the target, compare to `value`. */
+interface FieldCondition {
+  /** Dotted path: `'contact.email'`, `'metadata.utm.source'`, etc. */
+  readonly field: string;
+  readonly op: Comparator;
+  /** Comparand. Omitted for `isNull` / `isNotNull`. */
+  readonly value?: unknown;
+}
+/** All branches must be true. */
+interface AllCondition {
+  readonly all: readonly Condition[];
+}
+/** Any branch true short-circuits true. */
+interface AnyCondition {
+  readonly any: readonly Condition[];
+}
+/** Inverts the wrapped condition. */
+interface NotCondition {
+  readonly not: Condition;
+}
+type Condition = FieldCondition | AllCondition | AnyCondition | NotCondition;
+/** Evaluate a `Condition` against `target`. Total — never throws on shape. */
+declare function evaluate(condition: Condition, target: unknown): boolean;
+type ConditionErrorCode = 'EMPTY' | 'UNKNOWN_SHAPE' | 'INVALID_OP' | 'MISSING_VALUE' | 'EMPTY_GROUP';
+declare class ConditionError extends Error {
+  readonly name = "ConditionError";
+  readonly code: ConditionErrorCode;
+  constructor(code: ConditionErrorCode, message: string);
+}
+/**
+ * Validate a condition shape before persisting. Recurses through composites.
+ * Throws `ConditionError` so hosts get a stable code + message in API
+ * responses (`{ code: 'INVALID_OP', message: '...' }`).
+ */
+declare function validateCondition(condition: Condition): void;
+//#endregion
+export { AllCondition, AnyCondition, Comparator, Condition, ConditionError, ConditionErrorCode, FieldCondition, NotCondition, evaluate, validateCondition };

package/dist/condition.mjs

@@ -0,0 +1,131 @@
+//#region src/workflow/condition.ts
+function isFieldCondition(c) {
+	return typeof c.field === "string" && typeof c.op === "string";
+}
+function isAllCondition(c) {
+	return Array.isArray(c.all);
+}
+function isAnyCondition(c) {
+	return Array.isArray(c.any);
+}
+function isNotCondition(c) {
+	return typeof c.not === "object" && c.not !== null;
+}
+/**
+* Walk a dotted path on `target`. Returns `undefined` when any segment
+* doesn't exist. Treats `null` as a terminal (doesn't try to recurse on it).
+*/
+function getPath(target, path) {
+	if (path === "" || target === null || target === void 0) return void 0;
+	let cursor = target;
+	for (const segment of path.split(".")) {
+		if (cursor === null || cursor === void 0) return void 0;
+		if (typeof cursor !== "object") return void 0;
+		cursor = cursor[segment];
+	}
+	return cursor;
+}
+/** Evaluate a `Condition` against `target`. Total — never throws on shape. */
+function evaluate(condition, target) {
+	if (isAllCondition(condition)) return condition.all.every((c) => evaluate(c, target));
+	if (isAnyCondition(condition)) return condition.any.some((c) => evaluate(c, target));
+	if (isNotCondition(condition)) return !evaluate(condition.not, target);
+	if (isFieldCondition(condition)) return evaluateField(condition, target);
+	return false;
+}
+function evaluateField(c, target) {
+	const lhs = getPath(target, c.field);
+	const rhs = c.value;
+	switch (c.op) {
+		case "eq": return strictEqual(lhs, rhs);
+		case "neq": return !strictEqual(lhs, rhs);
+		case "gt": return compare(lhs, rhs) > 0;
+		case "gte": return compare(lhs, rhs) >= 0;
+		case "lt": return compare(lhs, rhs) < 0;
+		case "lte": return compare(lhs, rhs) <= 0;
+		case "in": return Array.isArray(rhs) && rhs.some((v) => strictEqual(lhs, v));
+		case "nin": return Array.isArray(rhs) && !rhs.some((v) => strictEqual(lhs, v));
+		case "contains": return Array.isArray(lhs) && lhs.some((v) => strictEqual(v, rhs));
+		case "startsWith": return typeof lhs === "string" && typeof rhs === "string" && lhs.startsWith(rhs);
+		case "endsWith": return typeof lhs === "string" && typeof rhs === "string" && lhs.endsWith(rhs);
+		case "isNull": return lhs === null || lhs === void 0;
+		case "isNotNull": return lhs !== null && lhs !== void 0;
+		default: return ((_) => false)(c.op);
+	}
+}
+/**
+* Equality with `Date` awareness. `===` on two `Date` objects with the same
+* millis returns `false`; this normalizes them. Plain primitives use `===`.
+*/
+function strictEqual(a, b) {
+	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+	if (a instanceof Date && typeof b === "string") return a.toISOString() === b;
+	if (typeof a === "string" && b instanceof Date) return a === b.toISOString();
+	return a === b;
+}
+/**
+* Numeric / chronological comparison. Returns `NaN` (which `compare()`
+* callers handle by returning false for gt/lt/gte/lte) when operands aren't
+* comparable. Dates are compared by their unix timestamp.
+*/
+function compare(a, b) {
+	const av = a instanceof Date ? a.getTime() : a;
+	const bv = b instanceof Date ? b.getTime() : b;
+	if (typeof av === "number" && typeof bv === "number") return av - bv;
+	if (typeof av === "string" && typeof bv === "string") return av < bv ? -1 : av > bv ? 1 : 0;
+	return NaN;
+}
+var ConditionError = class extends Error {
+	name = "ConditionError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+const COMPARATORS = new Set([
+	"eq",
+	"neq",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"in",
+	"nin",
+	"contains",
+	"startsWith",
+	"endsWith",
+	"isNull",
+	"isNotNull"
+]);
+const UNARY_OPS = new Set(["isNull", "isNotNull"]);
+/**
+* Validate a condition shape before persisting. Recurses through composites.
+* Throws `ConditionError` so hosts get a stable code + message in API
+* responses (`{ code: 'INVALID_OP', message: '...' }`).
+*/
+function validateCondition(condition) {
+	if (condition === null || typeof condition !== "object") throw new ConditionError("EMPTY", "condition is null or not an object");
+	if (isAllCondition(condition)) {
+		if (condition.all.length === 0) throw new ConditionError("EMPTY_GROUP", "all-group must have at least one branch");
+		condition.all.forEach(validateCondition);
+		return;
+	}
+	if (isAnyCondition(condition)) {
+		if (condition.any.length === 0) throw new ConditionError("EMPTY_GROUP", "any-group must have at least one branch");
+		condition.any.forEach(validateCondition);
+		return;
+	}
+	if (isNotCondition(condition)) {
+		validateCondition(condition.not);
+		return;
+	}
+	if (isFieldCondition(condition)) {
+		if (!COMPARATORS.has(condition.op)) throw new ConditionError("INVALID_OP", `unknown comparator: ${JSON.stringify(condition.op)}`);
+		if (!UNARY_OPS.has(condition.op) && condition.value === void 0) throw new ConditionError("MISSING_VALUE", `comparator '${condition.op}' requires a value`);
+		return;
+	}
+	throw new ConditionError("UNKNOWN_SHAPE", `condition must be a field/all/any/not — got: ${JSON.stringify(condition)}`);
+}
+//#endregion
+export { ConditionError, evaluate, validateCondition };

package/dist/context.d.mts

@@ -1,6 +1,6 @@
 import { IdLike } from "./reference.mjs";
 
-//#region src/context.d.ts
+//#region src/composition/context.d.ts
 /**
  * Operation context threaded through package APIs.
  *