@classytic/primitives 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -3,83 +3,56 @@
 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.14.0] - 2026-07-23
-
-### Added — `/money`: scalar minor-unit helpers (ledger dialect)
-
-- **`majorToMinorUnits(major, minorUnitDecimals = 2)` /
-  `minorUnitsToMajor(minor, minorUnitDecimals = 2)` /
-  `percentOfMinor(minor, ratePercent)` / `formatMinorUnits(minor,
-  minorUnitDecimals = 2)`** — the currency-neutral, exponent-based scalar
-  dialect used by the double-entry ledger family, extracted from
-  `@classytic/ledger/money` (`fromDecimal`/`toDecimal`/`percentage`/
-  `formatPlain`) so the math has ONE owner (PACKAGE_RULES §8.2).
-  Deliberately different rounding from `fromMajor`: raw IEEE `Math.round`
-  (half-up toward +∞, no `toPrecision` cleaning) — the ledger's
-  characterization-tested wire behavior (`majorToMinorUnits(1.005) === 100`
-  where `fromMajor(1.005,'USD').amount === 101`; `-10.5 → -10`).
-  `percentOfMinor` is the EXACT multiply-then-round form (handles QST
-  9.975 % without bps loss); hosts that snap rates to basis points (be-prod
-  `#shared/money`) layer that policy on top before calling.
-
-### Added — `/event-infra`: shared in-process bus + memory outbox
-
-- **`@classytic/primitives/event-infra`** — the dependency-free reference
-  event RUNTIME every kernel previously copy-pasted (26 drifted
-  `in-process-bus.ts` copies + 15 `outbox-store.ts` copies across
-  `commerce/packages/`, ≈1,600 lines). New subpath (not `/events` or
-  `/outbox`, which stay contract-only per the settled ownership rule; arc
-  keeps the DURABLE runtime — relay, `MongoOutboxStore`, backoff). Exports:
-  - `InProcessEventBus` (+ `createInProcessBus`, `InProcessEventBusOptions`,
-    `ErrorLogger`) — in-process fan-out `EventTransport`, structurally
-    identical to arc's `MemoryEventTransport`. Union of all kernel variants:
-    glob matching via `matchEventPattern`, Set-dedup across patterns,
-    per-handler error isolation with injectable logger (`logger: null` =
-    silent swallow, the cart dialect), `publishMany`, idempotent `close()`.
-    Options: `name` (`'in-process-<kernel>'`), `logLabel` for the error line.
-  - `MemoryOutboxStore` — the test/dev outbox (`save`/`getPending`/
-    `acknowledge`/`purge` + `all()`/`clear()` inspection helpers). Kernels
-    re-export it; production durability stays host-wired.
-  - Kernels keep their public class names as thin subclasses
-    (`class InProcessPosBus extends InProcessEventBus`), so no kernel API
-    changes — the bus swap is internal.
-
-### Added — `/events`: standard context→meta mapping
-
-- **`scopedEventMeta(ctx)` + `createScopedEvent(source, type, payload, ctx?,
-  meta?)` + `EventScopeContext`** — THE context→meta mapping (PACKAGE_RULES
-  §8.3: `organizationId` rides META) extracted from 25 drifted per-kernel
-  `events/helpers.ts` copies. `userId` ← `String(actorId)` falling back to
-  `actorRef` (the commerce dialect), `organizationId` ← stringified,
-  `correlationId` pass-through; absent fields omitted
-  (`exactOptionalPropertyTypes`-safe). Kernel helpers become one-liners:
-  `createPurchaseEvent = (t, p, ctx?, m?) =>
-  createScopedEvent('@classytic/purchase', t, p, ctx, m)`.
-
-### Changed — `EventTransport.subscribe` is now optional
-
-- **`/events` `EventTransport.subscribe?`** — publish-only transports (outbox
-  bridge adapters, host wrappers around a `publish(type, payload, meta)`
-  helper, fire-and-forget pipes) now conform without casting. Hosts were
-  writing `subscribe: undefined as unknown as EventTransport['subscribe']`
-  literals or `as unknown as EventTransport` widenings to inject them into
-  kernels that never call `subscribe` on the injected transport. Consumers
-  that need in-process delivery must guard for an absent `subscribe` — the
-  same "detect and fall back" contract `publishMany` and `deadLetter`
-  already carry (flow's `createSettlementListener` is the reference guard;
-  it has guarded `?.subscribe` since flow 0.5). Kernels subscribing on
-  their OWN in-process bus are unaffected — concrete buses still implement
-  `subscribe`, and a concrete method satisfies an optional member.
-- Audited call sites before the change (`commerce/packages/*/src`,
-  `commerce/spine/packages/*/src`): the `.subscribe` uses on injected
-  transports are pass-through dispatcher methods hosts opt into (crm/party
-  `dispatch.ts`), an already-guarded listener (flow's
-  `createSettlementListener`), and invoice's audit bridge — which only
-  subscribes when `config.audit` is wired. Each of these sources picks up a
-  compile-time "possibly undefined" prompt on its NEXT rebuild against this
-  version, forcing the guard (or a documented throw) exactly where a
-  publish-only transport would have failed at runtime before. No published
-  dist behavior changes.
+## [0.16.0] - 2026-07-27
+
+### Added — `assertApproved` + `CHAIN_INCOMPLETE` (`/approval`)
+
+- **`ApprovalErrorCode` gains `'CHAIN_INCOMPLETE'`** — the single canonical
+  error code for "finalize/commit attempted before the chain reached `approved`".
+  Hosts route it through `rethrowApprovalError` to the `approval.chain_incomplete`
+  wire code so all commit/post/finalize boundaries raise the same structured error.
+- **`assertApproved(chain, message?)`** — canonical finalize-time gate: asserts
+  the chain has reached `approved`, else throws `ApprovalError('CHAIN_INCOMPLETE')`.
+  A `null`/absent chain passes (no chain required). Use at every journal-entry
+  post, PO approve, transfer dispatch, etc. to replace per-domain hand-rolled
+  divergent codes with one definition.
+
+Purely additive — no existing exports changed.
+
+## [0.15.0] - 2026-07-25
+
+### Added — `/retention`: `PurgeEvidence` value object
+
+- **New `@classytic/primitives/retention` subpath** exporting **`PurgeEvidence`**
+  — the persisted evidence record for a GDPR / data-retention purge operation
+  (proof of what was purged, over what scope, by whom, why, and whether
+  analytical measures were retained). Shape: `{ id, subject: { ref, model? },
+  scope, strategy: 'hard'|'soft'|'anonymize', measuresRetained, processed,
+  occurredAt, actor: { ref, kind: 'user'|'system'|'service' }, reason,
+  legalBasis?, status: 'completed'|'partial'|'failed', operationId?,
+  startedAt?, completedAt?, results?: PurgeResourceResult[],
+  verification?: PurgeVerificationSummary }`.
+- **`createPurgeEvidence(input)`** — pure builder (auto-fills `id` + `occurredAt`
+  when absent, defaults `status` to `'completed'`). **`isPurgeEvidence(value)`**
+  type guard + **`assertPurgeEvidence(value)`** throwing assertion.
+
+### Added — `/canonical`: strict deterministic JSON + integrity digest
+
+- **New `@classytic/primitives/canonical` subpath** — `canonicalJson(value)`
+  produces a deterministic string (keys sorted recursively, `Date` → `{"$date":"<iso>"}`,
+  strict rejection of `undefined`/`NaN`/`BigInt`/`Map`/`Set`/cycles with
+  `CanonicalizeError`). **`sha256Hex(input)`** and **`canonicalDigest(value)`**
+  (= `sha256Hex(canonicalJson(value))`) — integrity checksums, not tamper-proof
+  seals. Uses `node:crypto` directly (same precedent as `/otp`).
+
+### Added — `/event-infra`: `propagateHandlerErrors` option
+
+- **`InProcessEventBusOptions.propagateHandlerErrors?: boolean`** (default
+  `false` — existing error-isolating behavior unchanged). When `true`, `publish`
+  runs handlers sequentially and rethrows the first handler error to the
+  publisher — for single-consumer projection/relay lanes where a failed handler
+  must not be silently acked. `publishMany` maps each event's failure into its
+  `PublishManyResult` entry instead of rejecting the batch.
 
 ## [0.13.0] - 2026-07-22
 

package/README.md

@@ -1,5 +1,7 @@
 # @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+.
 

package/dist/approval.d.mts

@@ -83,7 +83,12 @@ interface CreateStepInput {
   readonly requiredApprovals?: number;
   readonly threshold?: ApprovalThreshold;
 }
-type ApprovalErrorCode = 'EMPTY_STEPS' | 'DUPLICATE_STEP_ID' | 'EMPTY_APPROVERS' | 'DUPLICATE_APPROVER_ID' | 'INVALID_QUORUM' | 'UNKNOWN_STEP' | 'UNAUTHORIZED_APPROVER' | 'STEP_NOT_ACTIVE' | 'STEP_ALREADY_DECIDED_BY_APPROVER';
+type ApprovalErrorCode = 'EMPTY_STEPS' | 'DUPLICATE_STEP_ID' | 'EMPTY_APPROVERS' | 'DUPLICATE_APPROVER_ID' | 'INVALID_QUORUM' | 'UNKNOWN_STEP' | 'UNAUTHORIZED_APPROVER' | 'STEP_NOT_ACTIVE' | 'STEP_ALREADY_DECIDED_BY_APPROVER'
+/** A finalize/commit was attempted while the chain has not reached
+ *  `approved` (still `pending`, or `rejected`). The single canonical
+ *  "not yet approved" gate — hosts route it through arc-approval's
+ *  `rethrowApprovalError` to the `approval.chain_incomplete` wire code. */
+| 'CHAIN_INCOMPLETE';
 declare class ApprovalError extends Error {
   readonly name = "ApprovalError";
   readonly code: ApprovalErrorCode;
@@ -123,6 +128,16 @@ declare function applyDecision(chain: ApprovalChain, input: DecisionInput): Appr
  */
 declare function skipStep(chain: ApprovalChain, stepId: string, reason?: string): ApprovalChain;
 declare function isApproved(chain: ApprovalChain): boolean;
+/**
+ * The canonical finalize-time gate: assert `chain` has reached `approved`,
+ * else throw `ApprovalError('CHAIN_INCOMPLETE')`. Use this at every
+ * commit/post/finalize boundary that must not proceed on an unapproved chain
+ * (journal-entry post, PO approve, transfer dispatch, …) so they all raise the
+ * SAME error instead of hand-rolling divergent codes. A `null`/absent chain is
+ * treated as "no chain required" and passes — callers that require a chain
+ * check presence separately.
+ */
+declare function assertApproved(chain: ApprovalChain | null | undefined, message?: string): void;
 declare function isRejected(chain: ApprovalChain): boolean;
 declare function isPending(chain: ApprovalChain): boolean;
 /**
@@ -130,4 +145,4 @@ declare function isPending(chain: ApprovalChain): boolean;
  */
 declare function decisionCount(chain: ApprovalChain): number;
 //#endregion
-export { ApprovalChain, ApprovalDecision, ApprovalError, ApprovalErrorCode, ApprovalStatus, ApprovalStep, ApprovalThreshold, Approver, ChainOrder, CreateChainInput, CreateStepInput, DecisionInput, applyDecision, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };
+export { ApprovalChain, ApprovalDecision, ApprovalError, ApprovalErrorCode, ApprovalStatus, ApprovalStep, ApprovalThreshold, Approver, ChainOrder, CreateChainInput, CreateStepInput, DecisionInput, applyDecision, assertApproved, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };

package/dist/approval.mjs

@@ -115,6 +115,18 @@ function skipStep(chain, stepId, reason) {
 function isApproved(chain) {
 	return chain.status === "approved";
 }
+/**
+* The canonical finalize-time gate: assert `chain` has reached `approved`,
+* else throw `ApprovalError('CHAIN_INCOMPLETE')`. Use this at every
+* commit/post/finalize boundary that must not proceed on an unapproved chain
+* (journal-entry post, PO approve, transfer dispatch, …) so they all raise the
+* SAME error instead of hand-rolling divergent codes. A `null`/absent chain is
+* treated as "no chain required" and passes — callers that require a chain
+* check presence separately.
+*/
+function assertApproved(chain, message) {
+	if (chain != null && !isApproved(chain)) throw new ApprovalError("CHAIN_INCOMPLETE", message ?? `approval chain has not reached 'approved' (status='${chain.status}')`);
+}
 function isRejected(chain) {
 	return chain.status === "rejected";
 }
@@ -143,4 +155,4 @@ function computeChainStatus(steps) {
 	return steps.every((s) => s.status === "approved" || s.status === "skipped") ? "approved" : "pending";
 }
 //#endregion
-export { ApprovalError, applyDecision, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };
+export { ApprovalError, applyDecision, assertApproved, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };

package/dist/canonical.d.mts

@@ -0,0 +1,41 @@
+//#region src/serialization/canonical.d.ts
+/**
+ * `@classytic/primitives/canonical` — strict, deterministic JSON canonicalization
+ * + a SHA-256 hex helper.
+ *
+ * Cross-domain vocabulary: any subsystem that needs a STABLE checksum of
+ * structured data (a cleanup plan/manifest, a financial-close evidence
+ * manifest, an audit seal) canonicalizes here so the digest is:
+ *
+ *   - invariant to object key insertion order (keys sorted recursively);
+ *   - explicit about `Date` (serialized as `{"$date":"<iso>"}`), so timestamps
+ *     actually participate in the digest instead of collapsing to `{}` the way
+ *     a naive `JSON.stringify` of a `Date`-bearing object would; and
+ *   - STRICT — ambiguous / non-portable values (`undefined`, `NaN`/`Infinity`,
+ *     `BigInt`, `function`, `symbol`, `Map`, `Set`, cyclic refs) are REJECTED
+ *     with a `CanonicalizeError` rather than silently mis-hashed.
+ *
+ * These are integrity CHECKSUMS (accidental-corruption + drift detection), NOT
+ * tamper-proof seals: plain SHA-256 does not stop an actor with write access
+ * from replacing a record and recomputing its digest. Pair with access control
+ * / keyed signatures where that matters.
+ *
+ * `node:crypto` is used directly (precedent: `@classytic/primitives/identity`
+ * OTP already imports `node:crypto`); the zero-runtime-dependency policy covers
+ * third-party deps, not Node built-ins.
+ */
+declare class CanonicalizeError extends Error {
+  constructor(message: string);
+}
+/**
+ * Strict canonical JSON string of any value. Deterministic (sorted keys),
+ * `Date`-explicit; throws {@link CanonicalizeError} on unsupported/ambiguous
+ * input. Arrays keep their order (semantically meaningful).
+ */
+declare function canonicalJson(value: unknown): string;
+/** `sha256(input)` as a lowercase hex digest. */
+declare function sha256Hex(input: string): string;
+/** Convenience: `sha256Hex(canonicalJson(value))` — the integrity digest of a value. */
+declare function canonicalDigest(value: unknown): string;
+//#endregion
+export { CanonicalizeError, canonicalDigest, canonicalJson, sha256Hex };

package/dist/canonical.mjs

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+//#region src/serialization/canonical.ts
+/**
+* `@classytic/primitives/canonical` — strict, deterministic JSON canonicalization
+* + a SHA-256 hex helper.
+*
+* Cross-domain vocabulary: any subsystem that needs a STABLE checksum of
+* structured data (a cleanup plan/manifest, a financial-close evidence
+* manifest, an audit seal) canonicalizes here so the digest is:
+*
+*   - invariant to object key insertion order (keys sorted recursively);
+*   - explicit about `Date` (serialized as `{"$date":"<iso>"}`), so timestamps
+*     actually participate in the digest instead of collapsing to `{}` the way
+*     a naive `JSON.stringify` of a `Date`-bearing object would; and
+*   - STRICT — ambiguous / non-portable values (`undefined`, `NaN`/`Infinity`,
+*     `BigInt`, `function`, `symbol`, `Map`, `Set`, cyclic refs) are REJECTED
+*     with a `CanonicalizeError` rather than silently mis-hashed.
+*
+* These are integrity CHECKSUMS (accidental-corruption + drift detection), NOT
+* tamper-proof seals: plain SHA-256 does not stop an actor with write access
+* from replacing a record and recomputing its digest. Pair with access control
+* / keyed signatures where that matters.
+*
+* `node:crypto` is used directly (precedent: `@classytic/primitives/identity`
+* OTP already imports `node:crypto`); the zero-runtime-dependency policy covers
+* third-party deps, not Node built-ins.
+*/
+var CanonicalizeError = class extends Error {
+	constructor(message) {
+		super(`canonicalize: ${message}`);
+		this.name = "CanonicalizeError";
+	}
+};
+function canonicalize(value, seen) {
+	if (value === null) return "null";
+	const t = typeof value;
+	if (t === "string") return JSON.stringify(value);
+	if (t === "boolean") return value ? "true" : "false";
+	if (t === "number") {
+		if (!Number.isFinite(value)) throw new CanonicalizeError(`non-finite number ${String(value)}`);
+		return JSON.stringify(value);
+	}
+	if (t === "undefined") throw new CanonicalizeError("undefined is not serializable");
+	if (t === "bigint") throw new CanonicalizeError("bigint is not serializable");
+	if (t === "function" || t === "symbol") throw new CanonicalizeError(`${t} is not serializable`);
+	if (value instanceof Date) {
+		const time = value.getTime();
+		if (Number.isNaN(time)) throw new CanonicalizeError("invalid Date");
+		return `{"$date":${JSON.stringify(value.toISOString())}}`;
+	}
+	if (value instanceof Map || value instanceof Set) throw new CanonicalizeError(`${value.constructor.name} is not supported — use a plain object/array`);
+	const obj = value;
+	if (seen.has(obj)) throw new CanonicalizeError("cyclic reference");
+	seen.add(obj);
+	try {
+		if (Array.isArray(value)) return `[${value.map((v) => canonicalize(v, seen)).join(",")}]`;
+		const rec = value;
+		return `{${Object.keys(rec).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(rec[k], seen)}`).join(",")}}`;
+	} finally {
+		seen.delete(obj);
+	}
+}
+/**
+* Strict canonical JSON string of any value. Deterministic (sorted keys),
+* `Date`-explicit; throws {@link CanonicalizeError} on unsupported/ambiguous
+* input. Arrays keep their order (semantically meaningful).
+*/
+function canonicalJson(value) {
+	return canonicalize(value, /* @__PURE__ */ new WeakSet());
+}
+/** `sha256(input)` as a lowercase hex digest. */
+function sha256Hex(input) {
+	return createHash("sha256").update(input).digest("hex");
+}
+/** Convenience: `sha256Hex(canonicalJson(value))` — the integrity digest of a value. */
+function canonicalDigest(value) {
+	return sha256Hex(canonicalJson(value));
+}
+//#endregion
+export { CanonicalizeError, canonicalDigest, canonicalJson, sha256Hex };

package/dist/event-infra.d.mts

@@ -23,6 +23,36 @@ interface InProcessEventBusOptions {
    * `[<logLabel>] handler error for <event.type>:`. Default: `name`.
    */
   logLabel?: string;
+  /**
+   * Rethrow handler errors from `publish` instead of isolating them
+   * (default: `false` — the historical catch-log-continue behavior).
+   *
+   * **When to use (`true`)** — single-consumer projection/relay lanes: the
+   * bus sits between an outbox relay (arc's `EventOutbox` or equivalent) and
+   * exactly ONE subscriber (a projector, read-model builder, or forwarder).
+   * There, a thrown handler error MUST propagate to the publisher so the
+   * delivery FAILS — the relay then retries with backoff / dead-letters the
+   * event instead of silently acknowledging work that was never processed.
+   * With the default isolation, the relay sees `publish` resolve, acks the
+   * outbox row, and the projection update is lost forever.
+   *
+   * **When NOT to use (leave `false`)** — shared operational buses with
+   * multiple independent subscribers (the normal kernel default bus). One
+   * misbehaving subscriber must never crash its siblings or the publishing
+   * code path; failures are logged via {@link logger} and the event is
+   * considered delivered.
+   *
+   * Strict-mode semantics: handlers run sequentially in subscription order
+   * and `publish` rethrows IMMEDIATELY on the first handler failure — later
+   * matching subscribers are SKIPPED for that event. That is the honest
+   * contract for a single-consumer lane; if you attach multiple subscribers
+   * to a strict bus, understand that a failure in an earlier one starves the
+   * later ones. Nothing is logged on the strict path (the propagated error
+   * is the publisher's to handle); `publishMany` maps each event's failure
+   * into its `PublishManyResult` entry (keyed by `meta.id`) instead of
+   * rejecting the batch.
+   */
+  propagateHandlerErrors?: boolean | undefined;
 }
 /**
  * In-process fan-out `EventTransport` — structurally identical to arc's
@@ -35,6 +65,8 @@ interface InProcessEventBusOptions {
  *    event (Set-dedup — the majority variant across kernels).
  *  - Per-handler error isolation: one failing subscriber never crashes
  *    siblings; the failure is logged (or swallowed with `logger: null`).
+ *    Opt out per-bus with `propagateHandlerErrors: true` (single-consumer
+ *    projection/relay lanes — see {@link InProcessEventBusOptions.propagateHandlerErrors}).
  *  - `publishMany` batches per-event outcomes keyed by `meta.id`.
  *  - `close()` clears all subscriptions; publish after close is a no-op;
  *    close is idempotent. NOT durable — engines own it under the fleet
@@ -45,6 +77,7 @@ declare class InProcessEventBus implements EventTransport {
   private handlers;
   private readonly logger;
   private readonly logLabel;
+  private readonly propagateHandlerErrors;
   constructor(options?: InProcessEventBusOptions);
   publish(event: DomainEvent): Promise<void>;
   publishMany(events: readonly DomainEvent[]): Promise<PublishManyResult>;

package/dist/event-infra.mjs

@@ -11,6 +11,8 @@ import { matchEventPattern } from "./events.mjs";
 *    event (Set-dedup — the majority variant across kernels).
 *  - Per-handler error isolation: one failing subscriber never crashes
 *    siblings; the failure is logged (or swallowed with `logger: null`).
+*    Opt out per-bus with `propagateHandlerErrors: true` (single-consumer
+*    projection/relay lanes — see {@link InProcessEventBusOptions.propagateHandlerErrors}).
 *  - `publishMany` batches per-event outcomes keyed by `meta.id`.
 *  - `close()` clears all subscriptions; publish after close is a no-op;
 *    close is idempotent. NOT durable — engines own it under the fleet
@@ -21,18 +23,26 @@ var InProcessEventBus = class {
 	handlers = /* @__PURE__ */ new Map();
 	logger;
 	logLabel;
+	propagateHandlerErrors;
 	constructor(options = {}) {
 		this.name = options.name ?? "in-process";
 		this.logger = options.logger === null ? null : options.logger ?? console;
 		this.logLabel = options.logLabel ?? this.name;
+		this.propagateHandlerErrors = options.propagateHandlerErrors ?? false;
 	}
 	async publish(event) {
 		const matched = /* @__PURE__ */ new Set();
 		for (const [pattern, set] of this.handlers.entries()) if (matchEventPattern(pattern, event.type)) for (const h of set) matched.add(h);
-		for (const handler of matched) try {
-			await handler(event);
-		} catch (err) {
-			this.logger?.error(`[${this.logLabel}] handler error for ${event.type}:`, err);
+		for (const handler of matched) {
+			if (this.propagateHandlerErrors) {
+				await handler(event);
+				continue;
+			}
+			try {
+				await handler(event);
+			} catch (err) {
+				this.logger?.error(`[${this.logLabel}] handler error for ${event.type}:`, err);
+			}
 		}
 	}
 	async publishMany(events) {

package/dist/retention.d.mts

@@ -0,0 +1,209 @@
+//#region src/retention/purge-evidence.d.ts
+/**
+ * `PurgeEvidence` — the persisted evidence record for a GDPR / data-retention
+ * purge operation.
+ *
+ * When a host redacts, soft-deletes, or hard-deletes a slice of data to
+ * satisfy a right-to-be-forgotten request or a retention window, it must be
+ * able to PROVE — to an auditor, a DPA, or a court — what was purged, over
+ * what scope, by whom, why, and whether analytical measures were retained.
+ * This value object is that proof. Hosts persist one record per purge op
+ * alongside the mutation.
+ *
+ * A **legal hold is the opposite of a purge trigger** — a hold PREVENTS the
+ * purge from running. It is never a reason recorded here; if a hold applies,
+ * no `PurgeEvidence` is produced for the held subject in the first place.
+ *
+ * Pure data + pure builder — no persistence, no I/O, no events. The
+ * `strategy` enum is a SUBSET of repo-core's `TenantPurgeStrategy['type']`
+ * (`hard` | `soft` | `anonymize`) — a purge that ran a `skip` strategy did
+ * nothing, so it produces no evidence, and there is no `custom` variant.
+ *
+ * **Validation convention.** `@classytic/primitives` is deliberately
+ * dependency-free (no Zod, no runtime schema library) so it stays a
+ * zero-footprint building block for ~73 downstream consumers. Structural
+ * validation is therefore a pure type-guard ({@link isPurgeEvidence}) plus a
+ * throwing assertion ({@link assertPurgeEvidence}), matching every other
+ * primitive (`isExternalRef`, `isBankTransaction`, ...). Hosts that need a
+ * Zod schema derive one at their edge from {@link PurgeEvidence}.
+ *
+ * @example
+ * import { createPurgeEvidence } from '@classytic/primitives/retention';
+ *
+ * const evidence = createPurgeEvidence({
+ *   subject: { ref: 'customer:c_123', model: 'Customer' },
+ *   scope: 'org:org_bd_dhaka',
+ *   strategy: 'anonymize',
+ *   measuresRetained: true,        // sales measures kept; PII dimension redacted
+ *   processed: 4210,
+ *   actor: { ref: 'user:admin_7', kind: 'user' },
+ *   reason: 'GDPR erasure request #4821',
+ *   legalBasis: 'GDPR Art. 17',
+ * });
+ * // evidence.id and evidence.occurredAt are auto-filled.
+ */
+/**
+ * Strategy that produced the evidence. SUBSET of repo-core's
+ * `TenantPurgeStrategy['type']` — `skip` is excluded (a skipped purge
+ * mutates nothing, so it has no evidence to record).
+ */
+type PurgeStrategyKind = 'hard' | 'soft' | 'anonymize';
+/** What the purge targeted — a reference plus an optional logical model. */
+interface PurgeSubject {
+  /**
+   * Opaque reference to the purged subject. Any stable string form —
+   * `'customer:c_123'`, a bare id, an ExternalRef-style `model:id`. The
+   * primitive does not parse it; it is round-tripped verbatim for audit.
+   */
+  readonly ref: string;
+  /** Optional logical model / type name — e.g. `'Customer'`, `'Lead'`. */
+  readonly model?: string;
+}
+/** Who ran the purge. */
+interface PurgeActor {
+  /** Opaque reference to the actor — `'user:admin_7'`, `'service:retention-cron'`. */
+  readonly ref: string;
+  /** Actor category, for filtering audit reports by human vs automated action. */
+  readonly kind: 'user' | 'system' | 'service';
+}
+/**
+ * Terminal outcome of the purge operation the evidence records.
+ *   - `completed` — every targeted resource succeeded.
+ *   - `partial`   — some resources succeeded, others failed (see {@link
+ *                   PurgeEvidence.results}); the operation is resumable.
+ *   - `failed`    — the operation did not achieve its intended effect.
+ * A `partial`/`failed` record is STILL evidence — "we attempted X, this is
+ * exactly how far it got" — never suppressed.
+ */
+type PurgeStatus = 'completed' | 'partial' | 'failed';
+/**
+ * Per-resource / per-provider breakdown of a multi-step purge — one entry
+ * per logical resource the operation touched. Optional: a single-resource
+ * purge needs only the top-level {@link PurgeEvidence.processed}.
+ */
+interface PurgeResourceResult {
+  /** Logical resource / module / provider name — NOT a collection name. */
+  readonly resource: string;
+  /** Rows this resource processed (non-negative integer). */
+  readonly processed: number;
+  /** Whether this resource's step succeeded. */
+  readonly ok: boolean;
+  /** Failure message when `ok` is false. */
+  readonly error?: string;
+}
+/**
+ * Compact verification summary — the recipe's own post-checks, not a raw
+ * delete count. `A successful Mongo delete count alone is not success.`
+ */
+interface PurgeVerificationSummary {
+  /** Whether every verification invariant held. */
+  readonly ok: boolean;
+  /** How many invariants were checked. */
+  readonly checks?: number;
+  /** Short human-readable note (e.g. `'trial balance clean; stock reseeded'`). */
+  readonly note?: string;
+}
+/**
+ * Persisted evidence for one purge operation.
+ */
+interface PurgeEvidence {
+  /** Unique evidence-record identifier (UUID v4 recommended). */
+  readonly id: string;
+  /**
+   * Optional stable operation id correlating this evidence with the run's
+   * logs, audit events, and (for a Cleanup Center) its durable run record.
+   * Distinct from {@link id} (the evidence-record id): many evidence rows
+   * can share one `operationId`.
+   */
+  readonly operationId?: string;
+  /** What was purged. */
+  readonly subject: PurgeSubject;
+  /**
+   * The scope the purge ran over — free-form but conventionally a
+   * `kind:value` tag so reports group cleanly. Examples:
+   * `'generation:5'` (retention generation), `'occurrence:<dedupeKey>'`
+   * (a specific event occurrence), `'org:<id>'` (a tenant/branch window).
+   */
+  readonly scope: string;
+  /** Strategy that ran — `hard` | `soft` | `anonymize`. */
+  readonly strategy: PurgeStrategyKind;
+  /** Terminal outcome. Defaults to `completed` from the builder. */
+  readonly status: PurgeStatus;
+  /**
+   * True when analytical MEASURES were retained (the anonymize/soft case
+   * where PII dimensions are redacted but aggregates survive); false for a
+   * hard deletion that removed the rows entirely.
+   */
+  readonly measuresRetained: boolean;
+  /** Rows actually processed by the purge (non-negative integer). */
+  readonly processed: number;
+  /**
+   * When the purge STARTED, if known. Distinct from {@link completedAt} /
+   * {@link occurredAt} so a report can show duration + ordering.
+   */
+  readonly startedAt?: Date;
+  /** When the purge finished, if distinguished from {@link occurredAt}. */
+  readonly completedAt?: Date;
+  /** When the evidence was recorded (canonical audit timestamp). */
+  readonly occurredAt: Date;
+  /** Who ran it. */
+  readonly actor: PurgeActor;
+  /** Human-readable justification — surfaces in audit reports. */
+  readonly reason: string;
+  /** Optional legal basis citation — e.g. `'GDPR Art. 17'`, `'CCPA §1798.105'`. */
+  readonly legalBasis?: string;
+  /** Optional per-resource breakdown of a multi-step purge. */
+  readonly results?: readonly PurgeResourceResult[];
+  /** Optional verification summary — the recipe's own post-checks. */
+  readonly verification?: PurgeVerificationSummary;
+}
+/**
+ * Input to {@link createPurgeEvidence}. `id` and `occurredAt` are optional —
+ * the builder fills them when absent. Everything else is caller-supplied.
+ */
+interface CreatePurgeEvidenceInput {
+  readonly id?: string;
+  readonly operationId?: string;
+  readonly subject: PurgeSubject;
+  readonly scope: string;
+  readonly strategy: PurgeStrategyKind;
+  /** Defaults to `'completed'` when omitted. */
+  readonly status?: PurgeStatus;
+  readonly measuresRetained: boolean;
+  readonly processed: number;
+  readonly startedAt?: Date;
+  readonly completedAt?: Date;
+  readonly occurredAt?: Date;
+  readonly actor: PurgeActor;
+  readonly reason: string;
+  readonly legalBasis?: string;
+  readonly results?: readonly PurgeResourceResult[];
+  readonly verification?: PurgeVerificationSummary;
+}
+/**
+ * Build a {@link PurgeEvidence} record with auto-filled `id` + `occurredAt`.
+ *
+ * Pure and side-effect-free at module scope — the id generator and the
+ * timestamp are only invoked when the function runs (mirrors
+ * `@classytic/primitives/events` `createEvent`), never at import time, so the
+ * module stays tree-shakeable and deterministic to load.
+ *
+ * Caller-supplied `id` / `occurredAt` win over the generated defaults.
+ */
+declare function createPurgeEvidence(input: CreatePurgeEvidenceInput): PurgeEvidence;
+/**
+ * Structural type guard — validates the full {@link PurgeEvidence} shape,
+ * including the nested `subject` / `actor` objects and the two closed enums.
+ * Zero-dependency stand-in for a runtime schema.
+ */
+declare function isPurgeEvidence(value: unknown): value is PurgeEvidence;
+/**
+ * Throwing assertion form of {@link isPurgeEvidence}. Use at trust
+ * boundaries (deserialized audit rows, cross-service payloads) where an
+ * invalid record must fail loudly rather than propagate.
+ *
+ * @throws {TypeError} when `value` is not a well-formed {@link PurgeEvidence}.
+ */
+declare function assertPurgeEvidence(value: unknown): asserts value is PurgeEvidence;
+//#endregion
+export { CreatePurgeEvidenceInput, PurgeActor, PurgeEvidence, PurgeResourceResult, PurgeStatus, PurgeStrategyKind, PurgeSubject, PurgeVerificationSummary, assertPurgeEvidence, createPurgeEvidence, isPurgeEvidence };

package/dist/retention.mjs

@@ -0,0 +1,126 @@
+//#region src/retention/purge-evidence.ts
+const STRATEGY_KINDS = new Set([
+	"hard",
+	"soft",
+	"anonymize"
+]);
+const ACTOR_KINDS = new Set([
+	"user",
+	"system",
+	"service"
+]);
+const STATUS_KINDS = new Set([
+	"completed",
+	"partial",
+	"failed"
+]);
+/** Non-empty string check — the guard's baseline for every required label. */
+function isNonEmptyString(v) {
+	return typeof v === "string" && v.length > 0;
+}
+function isValidDate(v) {
+	return v instanceof Date && !Number.isNaN(v.getTime());
+}
+/**
+* Build a {@link PurgeEvidence} record with auto-filled `id` + `occurredAt`.
+*
+* Pure and side-effect-free at module scope — the id generator and the
+* timestamp are only invoked when the function runs (mirrors
+* `@classytic/primitives/events` `createEvent`), never at import time, so the
+* module stays tree-shakeable and deterministic to load.
+*
+* Caller-supplied `id` / `occurredAt` win over the generated defaults.
+*/
+function createPurgeEvidence(input) {
+	return {
+		id: input.id ?? randomEvidenceId(),
+		subject: input.subject,
+		scope: input.scope,
+		strategy: input.strategy,
+		status: input.status ?? "completed",
+		measuresRetained: input.measuresRetained,
+		processed: input.processed,
+		occurredAt: input.occurredAt ?? /* @__PURE__ */ new Date(),
+		actor: input.actor,
+		reason: input.reason,
+		...input.operationId !== void 0 ? { operationId: input.operationId } : {},
+		...input.startedAt !== void 0 ? { startedAt: input.startedAt } : {},
+		...input.completedAt !== void 0 ? { completedAt: input.completedAt } : {},
+		...input.legalBasis !== void 0 ? { legalBasis: input.legalBasis } : {},
+		...input.results !== void 0 ? { results: input.results } : {},
+		...input.verification !== void 0 ? { verification: input.verification } : {}
+	};
+}
+/**
+* Structural type guard — validates the full {@link PurgeEvidence} shape,
+* including the nested `subject` / `actor` objects and the two closed enums.
+* Zero-dependency stand-in for a runtime schema.
+*/
+function isPurgeEvidence(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const v = value;
+	if (!isNonEmptyString(v.id)) return false;
+	if (v.operationId !== void 0 && !isNonEmptyString(v.operationId)) return false;
+	if (!isNonEmptyString(v.scope)) return false;
+	if (typeof v.strategy !== "string" || !STRATEGY_KINDS.has(v.strategy)) return false;
+	if (typeof v.status !== "string" || !STATUS_KINDS.has(v.status)) return false;
+	if (typeof v.measuresRetained !== "boolean") return false;
+	if (typeof v.processed !== "number" || !Number.isInteger(v.processed) || v.processed < 0) return false;
+	if (v.startedAt !== void 0 && !isValidDate(v.startedAt)) return false;
+	if (v.completedAt !== void 0 && !isValidDate(v.completedAt)) return false;
+	if (!isValidDate(v.occurredAt)) return false;
+	if (!isNonEmptyString(v.reason)) return false;
+	if (v.legalBasis !== void 0 && !isNonEmptyString(v.legalBasis)) return false;
+	const subject = v.subject;
+	if (typeof subject !== "object" || subject === null) return false;
+	if (!isNonEmptyString(subject.ref)) return false;
+	if (subject.model !== void 0 && !isNonEmptyString(subject.model)) return false;
+	const actor = v.actor;
+	if (typeof actor !== "object" || actor === null) return false;
+	if (!isNonEmptyString(actor.ref)) return false;
+	if (typeof actor.kind !== "string" || !ACTOR_KINDS.has(actor.kind)) return false;
+	if (v.results !== void 0) {
+		if (!Array.isArray(v.results)) return false;
+		for (const r of v.results) {
+			if (typeof r !== "object" || r === null) return false;
+			const rr = r;
+			if (!isNonEmptyString(rr.resource)) return false;
+			if (typeof rr.processed !== "number" || !Number.isInteger(rr.processed) || rr.processed < 0) return false;
+			if (typeof rr.ok !== "boolean") return false;
+			if (rr.error !== void 0 && typeof rr.error !== "string") return false;
+		}
+	}
+	if (v.verification !== void 0) {
+		if (typeof v.verification !== "object" || v.verification === null) return false;
+		const ver = v.verification;
+		if (typeof ver.ok !== "boolean") return false;
+		if (ver.checks !== void 0 && (!Number.isInteger(ver.checks) || ver.checks < 0)) return false;
+		if (ver.note !== void 0 && typeof ver.note !== "string") return false;
+	}
+	return true;
+}
+/**
+* Throwing assertion form of {@link isPurgeEvidence}. Use at trust
+* boundaries (deserialized audit rows, cross-service payloads) where an
+* invalid record must fail loudly rather than propagate.
+*
+* @throws {TypeError} when `value` is not a well-formed {@link PurgeEvidence}.
+*/
+function assertPurgeEvidence(value) {
+	if (!isPurgeEvidence(value)) throw new TypeError("Invalid PurgeEvidence: value does not satisfy the PurgeEvidence shape");
+}
+/**
+* UUID-v4-style identifier. Uses `crypto.randomUUID` when available; falls
+* back to an RFC-4122 v4 string only on very old runtimes without Web Crypto.
+* Mirrors the generator in `@classytic/primitives/events`.
+*/
+function randomEvidenceId() {
+	const g = globalThis;
+	if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+		const r = Math.random() * 16 | 0;
+		return (c === "x" ? r : r & 3 | 8).toString(16);
+	});
+}
+//#endregion
+export { assertPurgeEvidence, createPurgeEvidence, isPurgeEvidence };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -157,6 +157,14 @@
       "types": "./dist/sla-policy.d.mts",
       "default": "./dist/sla-policy.mjs"
     },
+    "./retention": {
+      "types": "./dist/retention.d.mts",
+      "default": "./dist/retention.mjs"
+    },
+    "./canonical": {
+      "types": "./dist/canonical.d.mts",
+      "default": "./dist/canonical.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [