@classytic/primitives 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.25.0] - 2026-08-24
+
+### Added
+
+- **`@classytic/primitives/item-identity` subpath** — `SkuFields`, `stockKeyOf`, `skuDisplay`. `sku` is a label; `skuRef` is the stock identity — the two fall back in opposite directions and getting one backwards type-checks while returning a plausible wrong string. `stockKeyOf` resolves `skuRef ?? sku ?? fallback` (the key to reserve, decrement and post against); `skuDisplay` resolves `skuLabel ?? sku ?? skuRef` (what a human reads). Canonicalises the per-package `variantSku || String(productId)` derivations into one place.
+
+## [0.24.0] - 2026-08-24
+
+### Added — `@classytic/primitives/address`: capture-format system
+
+`AddressFormat`, `AddressFieldDescriptor`, `AddressFieldKey`, `PartialAddress`, `AddressFieldError` — a description of HOW a country collects a `ContactAddress`: field labels, order, requiredness, subdivision taxonomy hooks, and postal code pattern. Country packs (e.g. `@classytic/bd-areas/address-format`) live beside their taxonomies; this subpath owns only the generic shape.
+
+`validateAddress(address, format)` — validates a partial address against a format; returns `AddressFieldError[]`. Enforces `required` on both canonical and extension fields identically, and checks `postalCodePattern` only when a value is given and a pattern is declared. `isAddressValid` and `describeAddressError` are convenience wrappers.
+
+Every `key` in a descriptor is a field of `ContactAddress`; co-location with the value object is what makes a mismatch obvious instead of invisible.
+
 ## [0.23.0] - 2026-08-15
 
 ### Added — `./approval`: `notRequiredChain(reason)` + `isNotRequired(chain)`

package/README.md

@@ -1,160 +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`, `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
+# @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/address.d.mts

@@ -5,6 +5,11 @@
  * Kept deliberately generic — international postal formats vary too much to
  * enforce per-country rules in a shared type. Consumers can extend or narrow
  * as needed (e.g. a BD-specific schema might add `district`, `upazila`).
+ *
+ * That still holds, and the CAPTURE FORMAT section below does not weaken it. A
+ * format constrains no type and adds no field: it is opt-in DATA describing how
+ * a country asks for the fields declared here. The type stays generic precisely
+ * so one canonical shape can be captured many ways.
  */
 interface Address {
   line1: string;
@@ -34,5 +39,269 @@ interface GeoJsonPoint {
 }
 declare function toGeoJsonPoint(p: GeoPoint): GeoJsonPoint;
 declare function fromGeoJsonPoint(g: GeoJsonPoint): GeoPoint;
+/**
+ * How a country's postal address is CAPTURED — labels, order, requiredness, and
+ * which fields come from a subdivision taxonomy rather than free text.
+ *
+ * ## Why this lives HERE, beside the value object
+ *
+ * Storage was already standardised: an address is `ContactAddress` above. What
+ * varied — and varied by being hardcoded — is CAPTURE. The checkout form asked
+ * for "Division", "District" and "Delivery Area" because the deployment is
+ * Bangladeshi, so selling in a second country meant editing the form. That is
+ * the defect `@classytic/ledger` already solved for charts of accounts: the
+ * ENGINE was generic and the BINDING was not.
+ *
+ * This first went into a separate `@classytic/address` package. Wrong, for the
+ * reason this codebase has just paid for twice: a description of a shape that
+ * lives away from the shape DRIFTS from it. `Order`'s Mongoose schema said
+ * `addressLine1` while the type it declared said `line1`, and nothing could see
+ * the contradiction because they were in different files. Every `key` below is
+ * a field of `ContactAddress`; putting them in the same file is what makes a
+ * mismatch obvious instead of invisible.
+ *
+ * The COUNTRY PACKS do not live here — they are localizations, and they follow
+ * the `ledger` / `ledger-bd` precedent: Bangladesh's is
+ * `@classytic/bd-areas/address-format`, beside the taxonomy it selects from.
+ * Nothing in this file knows what a division is.
+ *
+ * ## What a format does NOT do
+ *
+ * It does not introduce new stored fields. Every descriptor's `key` is a field
+ * of `ContactAddress`, so a format is a VIEW over one canonical shape:
+ * Bangladesh labels `state` "Division", Japan labels it "Prefecture", the United
+ * States labels it "State". Same column, same value object, different word.
+ *
+ * A country that genuinely needs an extra datum (a thana, an upazila, a landmark)
+ * puts it in `metadata` — primitives' own guidance — never in a new top-level
+ * field, because that would make the stored shape country-dependent again.
+ */
+/** The `ContactAddress` fields a format may lay out. */
+type AddressFieldKey = 'name' | 'phone' | 'email' | 'company' | 'line1' | 'line2' | 'city' | 'state' | 'postalCode' | 'country';
+/**
+ * How a field is entered.
+ *
+ * `subdivision` is the interesting one: the value is still a plain string on the
+ * stored address, but it is CHOSEN from a taxonomy rather than typed. Bangladesh
+ * picks a division then a district; India picks a state; the US picks a state.
+ * The taxonomy itself is supplied by the host through `AddressTaxonomyPort` —
+ * this package ships no place names, so it stays country-agnostic and small.
+ */
+type AddressFieldInput = 'text' | 'tel' | 'email' | 'subdivision';
+interface AddressFieldSpec {
+  /** The canonical `ContactAddress` field this captures. */
+  key: AddressFieldKey;
+  /** Label in the deployment's language. */
+  label: string;
+  input: AddressFieldInput;
+  required?: boolean;
+  /** Spans the full row in a two-column form. */
+  wide?: boolean;
+  placeholder?: string;
+  /** Help text under the field. */
+  hint?: string;
+  /**
+   * For `input: 'subdivision'` — the taxonomy level this field selects, resolved
+   * through `AddressTaxonomyPort`. Opaque to this package: `'division'`,
+   * `'district'`, `'area'`, `'state'`, `'prefecture'` are all just strings.
+   */
+  taxonomy?: string;
+  /**
+   * The field whose value narrows this one's options — Bangladesh's district
+   * list depends on the chosen division. Must appear EARLIER in `fields`.
+   */
+  dependsOn?: string;
+}
+/**
+ * A field a country needs that `ContactAddress` does not model.
+ *
+ * ## Why this exists rather than growing the value object
+ *
+ * Bangladesh's checkout captures a **Delivery Area** — the locality couriers
+ * actually route and price on, finer than a district. It is required there and
+ * meaningless in most countries.
+ *
+ * The two obvious answers are both wrong. Adding `areaName` to `ContactAddress`
+ * puts one market's concept in the base type every country pays for; leaving it
+ * out entirely means the country that most needs a format cannot express its
+ * most important field, which is how the form ends up hardcoded again.
+ *
+ * So an extension field is DECLARED like any other — same labels, same
+ * requiredness, same taxonomy machinery — but its `name` is free-form and the
+ * consuming DOMAIN decides where the value lands. `@classytic/order` promotes
+ * `areaId` / `areaName` / `zoneId` to real columns because its carrier adapters
+ * read them; anything it does not recognise goes to `metadata`. Neither
+ * decision belongs in this package, and neither requires a release of it.
+ *
+ * Values live FLAT alongside the canonical ones, not in a nested bag — which is
+ * how `areaName` is already stored, and it means a form produces one object
+ * rather than two that can disagree.
+ */
+interface AddressExtensionFieldSpec {
+  /** Discriminant. */
+  extension: true;
+  /**
+   * Free-form key. Not validated against `ContactAddress` — that is the point.
+   * The domain maps it to a column or to `metadata`.
+   */
+  name: string;
+  label: string;
+  input: AddressFieldInput;
+  required?: boolean;
+  wide?: boolean;
+  placeholder?: string;
+  hint?: string;
+  taxonomy?: string;
+  /** May name a canonical key OR another extension. Must appear EARLIER. */
+  dependsOn?: string;
+}
+type AnyAddressFieldSpec = AddressFieldSpec | AddressExtensionFieldSpec;
+/** The key a spec writes to, canonical or extension. */
+declare function fieldName(spec: AnyAddressFieldSpec): string;
+/** Narrowing helper — `true` when the spec is an extension. */
+declare function isExtensionField(spec: AnyAddressFieldSpec): spec is AddressExtensionFieldSpec;
+interface AddressFormat {
+  /** ISO 3166-1 alpha-2, or `'*'` for the international fallback. */
+  country: string;
+  /** Display name of the country, for a read-only country field. */
+  countryLabel: string;
+  /** Ordered — this is the form layout. Canonical and extension fields interleave. */
+  fields: AnyAddressFieldSpec[];
+  /**
+   * Validate `postalCode` when present. Omit for countries where the code is
+   * free-form or absent; a wrong pattern is worse than none, because it refuses
+   * addresses that are perfectly valid.
+   */
+  postalCodePattern?: RegExp;
+}
+/**
+ * A taxonomy level's options, narrowed by the parent selection.
+ *
+ * A HOST PORT, not data in this package: Bangladesh's divisions live in
+ * `@classytic/bd-areas`, and a kernel that imported them would be a
+ * country-agnostic package with one country's place names compiled into it.
+ */
+interface AddressTaxonomyPort {
+  /**
+   * @param level    the `taxonomy` string from the field spec
+   * @param parentId the selected value of `dependsOn`, when the field has one
+   */
+  options(level: string, parentId?: string): Array<{
+    id: string;
+    label: string;
+    hint?: string;
+  }>;
+}
+/**
+ * The generic international format — the FALLBACK, and the proof the contract is
+ * not BD-shaped.
+ *
+ * Deliberately conservative. `state` is present but optional because many
+ * countries have no meaningful subdivision in a postal address (Singapore,
+ * Vatican City), and `postalCode` is optional because several have no postal
+ * code at all (Ireland pre-Eircode, Hong Kong, UAE). Requiring either would make
+ * the DEFAULT refuse valid addresses — the failure mode a fallback must not have.
+ *
+ * The required set is exactly what `Fulfillment` needs to be deliverable:
+ * `line1`, `city`, `country`.
+ */
+declare const INTERNATIONAL_ADDRESS_FORMAT: AddressFormat;
+/** Look a CANONICAL field up by its key. Extension fields have no `key`. */
+declare function fieldSpec(format: AddressFormat, key: AddressFieldKey): AddressFieldSpec | undefined;
+/**
+ * The CANONICAL keys a format marks required.
+ *
+ * Canonical only, deliberately: callers use this to check that a format can
+ * produce a deliverable address (`line1` + `city` + `country`), and an extension
+ * name has no meaning in that question. Use `requiredFieldNames` for everything
+ * a form must collect.
+ */
+declare function requiredKeys(format: AddressFormat): AddressFieldKey[];
+/** Every field name a format requires, canonical and extension alike. */
+declare function requiredFieldNames(format: AddressFormat): string[];
+/**
+ * A capture in progress.
+ *
+ * Extension values sit FLAT beside the canonical ones — `areaName` alongside
+ * `city` — because that is how the order kernel already stores them, and a
+ * nested bag would be a second place for the same address to disagree with
+ * itself. The index signature is what lets a format declare a field this
+ * package has never heard of.
+ */
+type PartialAddress = Partial<Record<AddressFieldKey, string>> & Partial<Pick<ContactAddress, 'line1' | 'city' | 'country'>> & {
+  [extension: string]: unknown;
+};
+/**
+ * Country code → capture format. The host builds this, exactly as it builds the
+ * ledger's `REGISTRY` (`be-prod/.../accounting/country-pack.ts`).
+ */
+type AddressFormatRegistry = Readonly<Record<string, AddressFormat>>;
+/**
+ * Resolve the format for a country, falling back to the international one.
+ *
+ * ## Falling back is the point, not a concession
+ *
+ * A deployment that has not authored a pack for Norway must still be able to
+ * ship to Norway. The fallback captures the deliverable minimum with neutral
+ * labels, which is strictly better than either refusing the address or showing
+ * a Bangladeshi form to a Norwegian.
+ *
+ * The lookup is case-insensitive because `country` reaches this from three
+ * directions — a form, a stored order, an API payload — and ISO codes get
+ * written `bd` about as often as `BD`. Normalising here beats a `?.toUpperCase()`
+ * at every call site, one of which will be forgotten and will silently fall back
+ * to international for its own home country.
+ */
+declare function resolveAddressFormat(country: string | null | undefined, registry: AddressFormatRegistry): AddressFormat;
+/**
+ * The countries a deployment has packs for — for a country picker.
+ *
+ * A deployment that ships internationally should offer every ISO country and let
+ * unlisted ones resolve to the fallback; this is for the common case of an
+ * operator choosing among the markets actually configured.
+ */
+declare function supportedCountries(registry: AddressFormatRegistry): Array<{
+  code: string;
+  label: string;
+}>;
+interface AddressFieldError {
+  /**
+   * The field's write key — a canonical `AddressFieldKey` or an extension name.
+   * Typed `string` because a format may declare fields this package does not
+   * know; a form matches it against `fieldName(spec)`.
+   */
+  key: string;
+  /** A closed code — callers map it to their own copy. */
+  code: 'required' | 'postal_code_format';
+  /** The field's own label, so a default message reads correctly per country. */
+  label: string;
+}
+/**
+ * Validate a captured address against its country's format.
+ *
+ * ## Returns errors; does not throw, and does not "clean"
+ *
+ * A form needs every failure at once to mark every field, so this returns a
+ * list. It also never mutates or drops anything: a validator that silently
+ * repaired input would make the stored value differ from what the operator
+ * typed, and they would have no way to see it.
+ *
+ * ## Codes, not sentences
+ *
+ * `code` is closed and stable so a host can translate. `label` rides along
+ * because the same `state` field is "Division" in Bangladesh and "Prefecture"
+ * in Japan, and a default message assembled from the code alone would say the
+ * wrong word in one of them.
+ *
+ * ## Whitespace is absence
+ *
+ * `'   '` satisfies a naive truthiness check and then prints as a blank line on
+ * a courier label. Required means a value, not a character.
+ */
+declare function validateAddress(address: PartialAddress | null | undefined, format: AddressFormat): AddressFieldError[];
+/** Convenience for a submit gate. */
+declare function isAddressValid(address: PartialAddress | null | undefined, format: AddressFormat): boolean;
+/** A readable default message, in the country's own vocabulary. */
+declare function describeAddressError(error: AddressFieldError): string;
 //#endregion
-export { Address, ContactAddress, GeoJsonPoint, GeoPoint, fromGeoJsonPoint, toGeoJsonPoint };
+export { Address, AddressExtensionFieldSpec, AddressFieldError, AddressFieldInput, AddressFieldKey, AddressFieldSpec, AddressFormat, AddressFormatRegistry, AddressTaxonomyPort, AnyAddressFieldSpec, ContactAddress, GeoJsonPoint, GeoPoint, INTERNATIONAL_ADDRESS_FORMAT, PartialAddress, describeAddressError, fieldName, fieldSpec, fromGeoJsonPoint, isAddressValid, isExtensionField, requiredFieldNames, requiredKeys, resolveAddressFormat, supportedCountries, toGeoJsonPoint, validateAddress };

package/dist/address.mjs

@@ -12,5 +12,194 @@ function fromGeoJsonPoint(g) {
 		latitude
 	};
 }
+/** The key a spec writes to, canonical or extension. */
+function fieldName(spec) {
+	return "extension" in spec ? spec.name : spec.key;
+}
+/** Narrowing helper — `true` when the spec is an extension. */
+function isExtensionField(spec) {
+	return "extension" in spec;
+}
+/**
+* The generic international format — the FALLBACK, and the proof the contract is
+* not BD-shaped.
+*
+* Deliberately conservative. `state` is present but optional because many
+* countries have no meaningful subdivision in a postal address (Singapore,
+* Vatican City), and `postalCode` is optional because several have no postal
+* code at all (Ireland pre-Eircode, Hong Kong, UAE). Requiring either would make
+* the DEFAULT refuse valid addresses — the failure mode a fallback must not have.
+*
+* The required set is exactly what `Fulfillment` needs to be deliverable:
+* `line1`, `city`, `country`.
+*/
+const INTERNATIONAL_ADDRESS_FORMAT = {
+	country: "*",
+	countryLabel: "Country",
+	fields: [
+		{
+			key: "name",
+			label: "Recipient Name",
+			input: "text",
+			required: true
+		},
+		{
+			key: "phone",
+			label: "Phone",
+			input: "tel",
+			required: true
+		},
+		{
+			key: "line1",
+			label: "Address Line 1",
+			input: "text",
+			required: true,
+			wide: true
+		},
+		{
+			key: "line2",
+			label: "Address Line 2",
+			input: "text",
+			wide: true
+		},
+		{
+			key: "city",
+			label: "City",
+			input: "text",
+			required: true
+		},
+		{
+			key: "state",
+			label: "State / Province / Region",
+			input: "text"
+		},
+		{
+			key: "postalCode",
+			label: "Postal Code",
+			input: "text"
+		},
+		{
+			key: "country",
+			label: "Country",
+			input: "text",
+			required: true
+		}
+	]
+};
+/** Look a CANONICAL field up by its key. Extension fields have no `key`. */
+function fieldSpec(format, key) {
+	return format.fields.find((f) => !isExtensionField(f) && f.key === key);
+}
+/**
+* The CANONICAL keys a format marks required.
+*
+* Canonical only, deliberately: callers use this to check that a format can
+* produce a deliverable address (`line1` + `city` + `country`), and an extension
+* name has no meaning in that question. Use `requiredFieldNames` for everything
+* a form must collect.
+*/
+function requiredKeys(format) {
+	return format.fields.filter((f) => !isExtensionField(f) && !!f.required).map((f) => f.key);
+}
+/** Every field name a format requires, canonical and extension alike. */
+function requiredFieldNames(format) {
+	return format.fields.filter((f) => f.required).map(fieldName);
+}
+/**
+* Resolve the format for a country, falling back to the international one.
+*
+* ## Falling back is the point, not a concession
+*
+* A deployment that has not authored a pack for Norway must still be able to
+* ship to Norway. The fallback captures the deliverable minimum with neutral
+* labels, which is strictly better than either refusing the address or showing
+* a Bangladeshi form to a Norwegian.
+*
+* The lookup is case-insensitive because `country` reaches this from three
+* directions — a form, a stored order, an API payload — and ISO codes get
+* written `bd` about as often as `BD`. Normalising here beats a `?.toUpperCase()`
+* at every call site, one of which will be forgotten and will silently fall back
+* to international for its own home country.
+*/
+function resolveAddressFormat(country, registry) {
+	if (!country) return INTERNATIONAL_ADDRESS_FORMAT;
+	return registry[country.trim().toUpperCase()] ?? INTERNATIONAL_ADDRESS_FORMAT;
+}
+/**
+* The countries a deployment has packs for — for a country picker.
+*
+* A deployment that ships internationally should offer every ISO country and let
+* unlisted ones resolve to the fallback; this is for the common case of an
+* operator choosing among the markets actually configured.
+*/
+function supportedCountries(registry) {
+	return Object.entries(registry).map(([code, format]) => ({
+		code,
+		label: format.countryLabel
+	})).sort((a, b) => a.label.localeCompare(b.label));
+}
+/**
+* Validate a captured address against its country's format.
+*
+* ## Returns errors; does not throw, and does not "clean"
+*
+* A form needs every failure at once to mark every field, so this returns a
+* list. It also never mutates or drops anything: a validator that silently
+* repaired input would make the stored value differ from what the operator
+* typed, and they would have no way to see it.
+*
+* ## Codes, not sentences
+*
+* `code` is closed and stable so a host can translate. `label` rides along
+* because the same `state` field is "Division" in Bangladesh and "Prefecture"
+* in Japan, and a default message assembled from the code alone would say the
+* wrong word in one of them.
+*
+* ## Whitespace is absence
+*
+* `'   '` satisfies a naive truthiness check and then prints as a blank line on
+* a courier label. Required means a value, not a character.
+*/
+function validateAddress(address, format) {
+	const errors = [];
+	const value = (k) => String(address?.[k] ?? "").trim();
+	/**
+	* Canonical and extension fields are checked IDENTICALLY, keyed by
+	* `fieldName`. A required Delivery Area is enforced exactly as a required
+	* city is — an extension that validated more weakly than a core field would
+	* be an optional field wearing a required label.
+	*/
+	for (const field of format.fields) {
+		const name = fieldName(field);
+		if (field.required && !value(name)) errors.push({
+			key: name,
+			code: "required",
+			label: field.label
+		});
+	}
+	/**
+	* Only when a pattern is declared AND a value was given. An absent optional
+	* postal code is not a format error, and a country with no declared pattern
+	* must not have one invented for it — see `AddressFormat.postalCodePattern`.
+	*/
+	const postal = value("postalCode");
+	if (format.postalCodePattern && postal && !format.postalCodePattern.test(postal)) errors.push({
+		key: "postalCode",
+		code: "postal_code_format",
+		label: fieldSpec(format, "postalCode")?.label ?? "Postal Code"
+	});
+	return errors;
+}
+/** Convenience for a submit gate. */
+function isAddressValid(address, format) {
+	return validateAddress(address, format).length === 0;
+}
+/** A readable default message, in the country's own vocabulary. */
+function describeAddressError(error) {
+	switch (error.code) {
+		case "required": return `${error.label} is required`;
+		case "postal_code_format": return `${error.label} is not in the expected format`;
+	}
+}
 //#endregion
-export { fromGeoJsonPoint, toGeoJsonPoint };
+export { INTERNATIONAL_ADDRESS_FORMAT, describeAddressError, fieldName, fieldSpec, fromGeoJsonPoint, isAddressValid, isExtensionField, requiredFieldNames, requiredKeys, resolveAddressFormat, supportedCountries, toGeoJsonPoint, validateAddress };

package/dist/item-identity.d.mts

@@ -0,0 +1,71 @@
+//#region src/identity/item-identity.d.ts
+/**
+ * `sku` is a LABEL; `skuRef` is the stock IDENTITY. Never one field.
+ *
+ * | field | mutable? | job |
+ * |---|---|---|
+ * | `skuRef` | never | keys quants, moves and ledger rows |
+ * | `sku` | operator edits it | what a human reads, types, searches |
+ *
+ * Use `stockKeyOf` for anything that reserves or moves stock, `skuDisplay` for
+ * anything a human reads. Never hand-roll either: both fall back, in OPPOSITE
+ * directions, and getting one backwards type-checks and returns a plausible
+ * string.
+ *
+ * - stock key = `skuRef ?? sku` — absent `skuRef` means a pre-split producer
+ *   whose `sku` still IS the key.
+ * - display = `skuLabel ?? sku ?? skuRef` — the ref last, and flagged, because
+ *   it can be an opaque id with no merchandising meaning.
+ *
+ * Pinned by `tests/unit/item-identity.test.ts`.
+ */
+/** Identifier fields a record may carry — each shape populates a different subset. */
+interface SkuFields {
+  /** Merchandising label — mutable, human-facing. */
+  sku?: string | undefined;
+  /** Stock/ledger identity — immutable, keys quants and moves. */
+  skuRef?: string | undefined;
+  /** Label resolved server-side for a read model keyed by `skuRef`. */
+  skuLabel?: string | undefined;
+}
+/**
+ * The STOCK key to reserve, decrement and post against: `skuRef ?? sku`,
+ * falling back to `fallback` (typically the owning entity's `_id`) when the
+ * record carries neither — the shape every "variant, else the product"
+ * ledger key already re-derives by hand across three packages.
+ *
+ * `undefined` = the record carries neither AND no `fallback` was given —
+ * malformed, not untracked. Use {@link requireStockKey} where that must stop
+ * the write.
+ */
+declare function stockKeyOf(item: SkuFields, fallback?: string | {
+  toString(): string;
+}): string | undefined;
+/**
+ * {@link stockKeyOf} that THROWS. Use wherever the key feeds a stock movement:
+ * a reservation on `undefined` returns "out of stock" instead of failing.
+ */
+declare function requireStockKey(item: SkuFields, context?: string): string;
+/** What a surface should render for an item, and whether it had a real label. */
+interface SkuDisplay {
+  /** Best human-facing value. `undefined` = no identifier at all; render a dash. */
+  label: string | undefined;
+  /** The stock identity, for subtext or copy-to-clipboard. */
+  ref: string | undefined;
+  /**
+   * TRUE when `label` is really the `ref` (nothing resolved). Style it as an id
+   * — monospace, muted — never as a SKU.
+   */
+  isRefFallback: boolean;
+}
+/** What to SHOW: `skuLabel ?? sku ?? skuRef`. The ref is returned alongside,
+ * never dropped — it is the join key an operator quotes. */
+declare function skuDisplay(item: SkuFields): SkuDisplay;
+/**
+ * Looks like an opaque id (24-char hex) rather than a merchandising code.
+ * PRESENTATION HINT ONLY — never branch stock logic on it; a deployment may key
+ * quants by any stable string.
+ */
+declare function looksLikeOpaqueId(value: string | undefined): boolean;
+//#endregion
+export { SkuDisplay, SkuFields, looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyOf };

package/dist/item-identity.mjs

@@ -0,0 +1,50 @@
+//#region src/identity/item-identity.ts
+const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0 ? value : void 0;
+/**
+* The STOCK key to reserve, decrement and post against: `skuRef ?? sku`,
+* falling back to `fallback` (typically the owning entity's `_id`) when the
+* record carries neither — the shape every "variant, else the product"
+* ledger key already re-derives by hand across three packages.
+*
+* `undefined` = the record carries neither AND no `fallback` was given —
+* malformed, not untracked. Use {@link requireStockKey} where that must stop
+* the write.
+*/
+function stockKeyOf(item, fallback) {
+	return nonEmpty(item.skuRef) ?? nonEmpty(item.sku) ?? (fallback !== void 0 ? String(fallback) : void 0);
+}
+/**
+* {@link stockKeyOf} that THROWS. Use wherever the key feeds a stock movement:
+* a reservation on `undefined` returns "out of stock" instead of failing.
+*/
+function requireStockKey(item, context) {
+	const key = stockKeyOf(item);
+	if (key === void 0) throw new Error(`stock key missing: neither skuRef nor sku is set${context ? ` (${context})` : ""}`);
+	return key;
+}
+/** What to SHOW: `skuLabel ?? sku ?? skuRef`. The ref is returned alongside,
+* never dropped — it is the join key an operator quotes. */
+function skuDisplay(item) {
+	const ref = nonEmpty(item.skuRef);
+	const label = nonEmpty(item.skuLabel) ?? nonEmpty(item.sku);
+	if (label !== void 0) return {
+		label,
+		ref,
+		isRefFallback: false
+	};
+	return {
+		label: ref,
+		ref,
+		isRefFallback: ref !== void 0
+	};
+}
+/**
+* Looks like an opaque id (24-char hex) rather than a merchandising code.
+* PRESENTATION HINT ONLY — never branch stock logic on it; a deployment may key
+* quants by any stable string.
+*/
+function looksLikeOpaqueId(value) {
+	return typeof value === "string" && /^[0-9a-f]{24}$/i.test(value);
+}
+//#endregion
+export { looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyOf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -209,6 +209,10 @@
     "./subject": {
       "types": "./dist/subject.d.mts",
       "default": "./dist/subject.mjs"
+    },
+    "./item-identity": {
+      "types": "./dist/item-identity.d.mts",
+      "default": "./dist/item-identity.mjs"
     }
   },
   "files": [