@cullet/erp-core 1.4.0 → 2.0.0

package/dist/core-config.d.cts

@@ -2,7 +2,8 @@ import { r as Result } from "./result.cjs";
 import { n as Outcome } from "./outcome.cjs";
 
 //#region src/core/policies/engines/v1/condition-types.d.ts
-type ConditionOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "isNull" | "isNotNull";
+declare const CONDITION_OPS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "in", "notIn", "isNull", "isNotNull"];
+type ConditionOp = (typeof CONDITION_OPS)[number];
 interface ConditionLeafNode {
   readonly field: string;
   readonly op: ConditionOp;
@@ -143,7 +144,39 @@ interface PolicyEvaluationCompletedEvent {
   readonly engineKind: "GATE" | "COMPUTE";
   readonly occurredAt: Date;
 }
-type PolicyEvent = ConditionEvalEvent | PolicyResolutionEvent | PolicyEvaluationFailedEvent | PolicyEvaluationCompletedEvent;
+/**
+ * A resolved ABAC decision (both PERMIT and DENY). Emitted best-effort by the
+ * `AbacAuthorizer` so a host can build an authorization audit trail without an
+ * adapter of its own; silent by default like every other event. Types are kept
+ * self-contained (no import from `core/abac`) to avoid a config→abac cycle.
+ */
+interface AbacDecisionEvent {
+  readonly kind: "abac-decision";
+  readonly level: "info";
+  readonly action: string;
+  readonly resource?: {
+    readonly type: string;
+    readonly id?: string;
+  };
+  readonly actorId: string;
+  readonly effect: "PERMIT" | "DENY";
+  /** Deciding rule id, or `"<default>"` / `"<default-deny>"` when the set's default decided. */
+  readonly decidingRuleId: string;
+  readonly decidingRuleVersion?: number;
+  readonly algorithm: string;
+  readonly occurredAt: Date;
+}
+type PolicyEvent = ConditionEvalEvent | PolicyResolutionEvent | PolicyEvaluationFailedEvent | PolicyEvaluationCompletedEvent | AbacDecisionEvent;
+/**
+ * Sink for policy telemetry. The core never logs on its own — it hands typed
+ * events here and a host implementation decides what to do with them.
+ *
+ * Redaction is the host's responsibility: a `condition-eval` event carries the
+ * evaluated field path and value in `details` (e.g. `student.flags.*`), so in
+ * an ERP those payloads can contain PII. Sanitize before persisting or shipping
+ * events off-box; the core deliberately keeps no redaction seam so it stays
+ * pure and unopinionated about your logging stack.
+ */
 interface PolicyReporter {
   report(event: PolicyEvent): void;
 }
@@ -156,17 +189,31 @@ interface CoreConfigOptions {
   readonly observability?: CoreObservabilityConfig;
 }
 /**
- * Centraliza a configuracao pura do core sem depender de implementacoes
- * concretas de logging, tracing ou report.
+ * The core's config namespace. Today it holds a single section —
+ * `observability` — whose whole job is to decide *where policy telemetry goes*
+ * while guaranteeing telemetry is best-effort (a throwing reporter can never
+ * abort a domain flow). App config (env, settings, feature flags) is
+ * deliberately absent for now: when the core needs it, it joins here as a
+ * sibling section rather than a new module — which is why this is `config`,
+ * not `observability`. It holds the active {@link PolicyReporter} (silent by
+ * default, so the core carries no logging dependency), bridges it to the
+ * engines' {@link ConditionEvaluatorReporter}, and offers `reportSafely` as
+ * the single guarded emit path shared with {@link PolicyService}.
  */
 declare class CoreConfig {
   #private;
   constructor(options?: CoreConfigOptions);
+  /**
+   * Swaps the active reporter. Pass `observability.reporter` to enable
+   * telemetry, or set it explicitly to `undefined` to go silent again.
+   * Omitting `observability` (or its `reporter` key) is a no-op.
+   */
   configure(options: CoreConfigOptions): this;
   reset(): this;
-  getPolicyReporter(): PolicyReporter;
+  /** Emits a policy event through the active reporter, best-effort. */
+  reportSafely(event: PolicyEvent): void;
   getConditionEvaluationOptions(engineVersion: number): ConditionEvaluationOptions;
 }
 //#endregion
-export { ConditionLeafNode as A, GateTraceNodeSnapshot as C, VersionedGateEngine as D, PolicyViolation as E, GatePayload as O, GateTraceLeafSnapshot as S, PolicyContext as T, ConditionEvaluationReportTag as _, PolicyDecisionId as a, GateOutcomeData as b, TenantId as c, asSchoolId as d, asTenantId as f, ConditionEvaluationReportLevel as g, ConditionEvaluationReport as h, PolicyReporter as i, ConditionNode as j, GatePayloadV1 as k, asPolicyDecisionId as l, ConditionEvaluationOptions as m, CoreConfigOptions as n, PolicyDefinitionId as o, ConditionEvaluationCause as p, CoreObservabilityConfig as r, SchoolId as s, CoreConfig as t, asPolicyDefinitionId as u, ConditionEvaluatorReporter as v, GateViolationTrace as w, GateStatus as x, GateOutcome as y };
+export { ConditionNode as A, GateViolationTrace as C, GatePayload as D, VersionedGateEngine as E, GatePayloadV1 as O, GateTraceNodeSnapshot as S, PolicyViolation as T, ConditionEvaluatorReporter as _, PolicyDefinitionId as a, GateStatus as b, asPolicyDecisionId as c, asTenantId as d, ConditionEvaluationCause as f, ConditionEvaluationReportTag as g, ConditionEvaluationReportLevel as h, PolicyDecisionId as i, ConditionLeafNode as k, asPolicyDefinitionId as l, ConditionEvaluationReport as m, CoreConfigOptions as n, SchoolId as o, ConditionEvaluationOptions as p, CoreObservabilityConfig as r, TenantId as s, CoreConfig as t, asSchoolId as u, GateOutcome as v, PolicyContext as w, GateTraceLeafSnapshot as x, GateOutcomeData as y };
 //# sourceMappingURL=core-config.d.cts.map

package/dist/core-config.d.ts

@@ -2,7 +2,8 @@ import { r as Result } from "./result.js";
 import { n as Outcome } from "./outcome.js";
 
 //#region src/core/policies/engines/v1/condition-types.d.ts
-type ConditionOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "isNull" | "isNotNull";
+declare const CONDITION_OPS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "in", "notIn", "isNull", "isNotNull"];
+type ConditionOp = (typeof CONDITION_OPS)[number];
 interface ConditionLeafNode {
   readonly field: string;
   readonly op: ConditionOp;
@@ -143,7 +144,39 @@ interface PolicyEvaluationCompletedEvent {
   readonly engineKind: "GATE" | "COMPUTE";
   readonly occurredAt: Date;
 }
-type PolicyEvent = ConditionEvalEvent | PolicyResolutionEvent | PolicyEvaluationFailedEvent | PolicyEvaluationCompletedEvent;
+/**
+ * A resolved ABAC decision (both PERMIT and DENY). Emitted best-effort by the
+ * `AbacAuthorizer` so a host can build an authorization audit trail without an
+ * adapter of its own; silent by default like every other event. Types are kept
+ * self-contained (no import from `core/abac`) to avoid a config→abac cycle.
+ */
+interface AbacDecisionEvent {
+  readonly kind: "abac-decision";
+  readonly level: "info";
+  readonly action: string;
+  readonly resource?: {
+    readonly type: string;
+    readonly id?: string;
+  };
+  readonly actorId: string;
+  readonly effect: "PERMIT" | "DENY";
+  /** Deciding rule id, or `"<default>"` / `"<default-deny>"` when the set's default decided. */
+  readonly decidingRuleId: string;
+  readonly decidingRuleVersion?: number;
+  readonly algorithm: string;
+  readonly occurredAt: Date;
+}
+type PolicyEvent = ConditionEvalEvent | PolicyResolutionEvent | PolicyEvaluationFailedEvent | PolicyEvaluationCompletedEvent | AbacDecisionEvent;
+/**
+ * Sink for policy telemetry. The core never logs on its own — it hands typed
+ * events here and a host implementation decides what to do with them.
+ *
+ * Redaction is the host's responsibility: a `condition-eval` event carries the
+ * evaluated field path and value in `details` (e.g. `student.flags.*`), so in
+ * an ERP those payloads can contain PII. Sanitize before persisting or shipping
+ * events off-box; the core deliberately keeps no redaction seam so it stays
+ * pure and unopinionated about your logging stack.
+ */
 interface PolicyReporter {
   report(event: PolicyEvent): void;
 }
@@ -156,17 +189,31 @@ interface CoreConfigOptions {
   readonly observability?: CoreObservabilityConfig;
 }
 /**
- * Centraliza a configuracao pura do core sem depender de implementacoes
- * concretas de logging, tracing ou report.
+ * The core's config namespace. Today it holds a single section —
+ * `observability` — whose whole job is to decide *where policy telemetry goes*
+ * while guaranteeing telemetry is best-effort (a throwing reporter can never
+ * abort a domain flow). App config (env, settings, feature flags) is
+ * deliberately absent for now: when the core needs it, it joins here as a
+ * sibling section rather than a new module — which is why this is `config`,
+ * not `observability`. It holds the active {@link PolicyReporter} (silent by
+ * default, so the core carries no logging dependency), bridges it to the
+ * engines' {@link ConditionEvaluatorReporter}, and offers `reportSafely` as
+ * the single guarded emit path shared with {@link PolicyService}.
  */
 declare class CoreConfig {
   #private;
   constructor(options?: CoreConfigOptions);
+  /**
+   * Swaps the active reporter. Pass `observability.reporter` to enable
+   * telemetry, or set it explicitly to `undefined` to go silent again.
+   * Omitting `observability` (or its `reporter` key) is a no-op.
+   */
   configure(options: CoreConfigOptions): this;
   reset(): this;
-  getPolicyReporter(): PolicyReporter;
+  /** Emits a policy event through the active reporter, best-effort. */
+  reportSafely(event: PolicyEvent): void;
   getConditionEvaluationOptions(engineVersion: number): ConditionEvaluationOptions;
 }
 //#endregion
-export { ConditionLeafNode as A, GateTraceNodeSnapshot as C, VersionedGateEngine as D, PolicyViolation as E, GatePayload as O, GateTraceLeafSnapshot as S, PolicyContext as T, ConditionEvaluationReportTag as _, PolicyDecisionId as a, GateOutcomeData as b, TenantId as c, asSchoolId as d, asTenantId as f, ConditionEvaluationReportLevel as g, ConditionEvaluationReport as h, PolicyReporter as i, ConditionNode as j, GatePayloadV1 as k, asPolicyDecisionId as l, ConditionEvaluationOptions as m, CoreConfigOptions as n, PolicyDefinitionId as o, ConditionEvaluationCause as p, CoreObservabilityConfig as r, SchoolId as s, CoreConfig as t, asPolicyDefinitionId as u, ConditionEvaluatorReporter as v, GateViolationTrace as w, GateStatus as x, GateOutcome as y };
+export { ConditionNode as A, GateViolationTrace as C, GatePayload as D, VersionedGateEngine as E, GatePayloadV1 as O, GateTraceNodeSnapshot as S, PolicyViolation as T, ConditionEvaluatorReporter as _, PolicyDefinitionId as a, GateStatus as b, asPolicyDecisionId as c, asTenantId as d, ConditionEvaluationCause as f, ConditionEvaluationReportTag as g, ConditionEvaluationReportLevel as h, PolicyDecisionId as i, ConditionLeafNode as k, asPolicyDefinitionId as l, ConditionEvaluationReport as m, CoreConfigOptions as n, SchoolId as o, ConditionEvaluationOptions as p, CoreObservabilityConfig as r, TenantId as s, CoreConfig as t, asSchoolId as u, GateOutcome as v, PolicyContext as w, GateTraceLeafSnapshot as x, GateOutcomeData as y };
 //# sourceMappingURL=core-config.d.ts.map

package/dist/decorate.cjs

@@ -0,0 +1,14 @@
+//#region \0@oxc-project+runtime@0.132.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+Object.defineProperty(exports, "__decorate", {
+	enumerable: true,
+	get: function() {
+		return __decorate;
+	}
+});

package/dist/decorate.js

@@ -0,0 +1,9 @@
+//#region \0@oxc-project+runtime@0.132.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+export { __decorate as t };

package/dist/domain/index.cjs

@@ -1,11 +1,105 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity = require("../entity.cjs");
+const require_invariant_violation_exception = require("../invariant-violation-exception.cjs");
+const require_temporal_guards = require("../temporal-guards.cjs");
+const require_immutable = require("../immutable.cjs");
 const require_value_object = require("../value-object.cjs");
 const require_uuid_identifier = require("../uuid-identifier.cjs");
+//#region src/core/domain/temporal/half-open-interval.ts
+/**
+* Shared core of the bitemporal primitives: a half-open interval
+* `[start, end)` whose end, when present, must be strictly later than its
+* start. `ValidTime` and `TransactionTime` are the same shape under different
+* (deliberate) vocabularies — the invariant lives here once so the two files
+* cannot drift apart.
+*
+* Internal to `domain/temporal`; not exported from the barrel.
+*/
+function assertHalfOpenInterval(startLabel, start, endLabel, end) {
+	require_temporal_guards.assertValidDate(startLabel, start);
+	if (end === void 0) return;
+	require_temporal_guards.assertValidDate(endLabel, end);
+	if (end.getTime() <= start.getTime()) throw new require_invariant_violation_exception.InvariantViolationException(`${endLabel} must be later than ${startLabel}`);
+}
+//#endregion
+//#region src/core/domain/temporal/transaction-time.ts
+function assertTransactionTime(txTime, fieldName = "txTime") {
+	assertHalfOpenInterval(`${fieldName}.recordedAt`, txTime.recordedAt, `${fieldName}.supersededAt`, txTime.supersededAt);
+}
+function createTransactionTime(input) {
+	assertTransactionTime(input, "txTime");
+	if (input.supersededAt === void 0) return require_immutable.makeImmutable({ recordedAt: input.recordedAt });
+	return require_immutable.makeImmutable({
+		recordedAt: input.recordedAt,
+		supersededAt: input.supersededAt
+	});
+}
+//#endregion
+//#region src/core/domain/temporal/valid-time.ts
+function assertValidTime(validTime, fieldName = "validTime") {
+	assertHalfOpenInterval(`${fieldName}.from`, validTime.from, `${fieldName}.to`, validTime.to);
+}
+function createValidTime(input) {
+	assertValidTime(input, "validTime");
+	if (input.to === void 0) return require_immutable.makeImmutable({ from: input.from });
+	return require_immutable.makeImmutable({
+		from: input.from,
+		to: input.to
+	});
+}
+//#endregion
+//#region src/core/domain/temporal/temporal-range.ts
+/**
+* Checks whether a temporal range is "open" (has no end date).
+* Useful for identifying information that is still in effect / active.
+*/
+function isOpen(range) {
+	assertValidTime(range, "range");
+	return range.to === void 0;
+}
+/**
+* Checks whether a temporal range is "closed" (has a defined end date).
+*/
+function isClosed(range) {
+	return !isOpen(range);
+}
+/**
+* Checks whether a specific date is contained within the temporal range.
+* The lower bound (`from`) is inclusive, while the upper bound (`to`) is exclusive.
+*/
+function contains(range, date) {
+	assertValidTime(range, "range");
+	require_temporal_guards.assertValidDate("date", date);
+	const fromTime = range.from.getTime();
+	const toTime = range.to?.getTime() ?? Number.POSITIVE_INFINITY;
+	const targetTime = date.getTime();
+	return targetTime >= fromTime && targetTime < toTime;
+}
+/**
+* Checks whether two temporal ranges overlap at any point.
+* Useful for validating whether a new rule conflicts with an existing one.
+*/
+function overlaps(left, right) {
+	assertValidTime(left, "left");
+	assertValidTime(right, "right");
+	const leftFrom = left.from.getTime();
+	const leftTo = left.to?.getTime() ?? Number.POSITIVE_INFINITY;
+	const rightFrom = right.from.getTime();
+	return leftFrom < (right.to?.getTime() ?? Number.POSITIVE_INFINITY) && rightFrom < leftTo;
+}
+//#endregion
+//#region src/core/domain/temporal/temporal-snapshot.ts
+function createTemporalSnapshot(input) {
+	return Object.freeze({
+		data: require_immutable.makeImmutable(input.data),
+		validTime: createValidTime(input.validTime),
+		txTime: createTransactionTime(input.txTime)
+	});
+}
+//#endregion
 Object.defineProperty(exports, "Entity", {
 	enumerable: true,
 	get: function() {
-		return require_entity.Entity;
+		return require_uuid_identifier.Entity;
 	}
 });
 exports.UuidIdentifier = require_uuid_identifier.UuidIdentifier;
@@ -15,3 +109,14 @@ Object.defineProperty(exports, "ValueObject", {
 		return require_value_object.ValueObject;
 	}
 });
+exports.assertTransactionTime = assertTransactionTime;
+exports.assertValidTime = assertValidTime;
+exports.contains = contains;
+exports.createTemporalSnapshot = createTemporalSnapshot;
+exports.createTransactionTime = createTransactionTime;
+exports.createValidTime = createValidTime;
+exports.isClosed = isClosed;
+exports.isOpen = isOpen;
+exports.overlaps = overlaps;
+
+//# sourceMappingURL=index.cjs.map

package/dist/domain/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["InvariantViolationException","makeImmutable","makeImmutable","makeImmutable"],"sources":["../../src/core/domain/temporal/half-open-interval.ts","../../src/core/domain/temporal/transaction-time.ts","../../src/core/domain/temporal/valid-time.ts","../../src/core/domain/temporal/temporal-range.ts","../../src/core/domain/temporal/temporal-snapshot.ts"],"sourcesContent":["import { InvariantViolationException } from \"../../exceptions/invariant-violation-exception.js\";\nimport { assertValidDate } from \"../../shared/temporal-guards.js\";\n\n/**\n * Shared core of the bitemporal primitives: a half-open interval\n * `[start, end)` whose end, when present, must be strictly later than its\n * start. `ValidTime` and `TransactionTime` are the same shape under different\n * (deliberate) vocabularies — the invariant lives here once so the two files\n * cannot drift apart.\n *\n * Internal to `domain/temporal`; not exported from the barrel.\n */\nfunction assertHalfOpenInterval(\n    startLabel: string,\n    start: Date,\n    endLabel: string,\n    end: Date | undefined,\n): void {\n    assertValidDate(startLabel, start);\n\n    if (end === undefined) {\n        return;\n    }\n\n    assertValidDate(endLabel, end);\n\n    if (end.getTime() <= start.getTime()) {\n        throw new InvariantViolationException(\n            `${endLabel} must be later than ${startLabel}`,\n        );\n    }\n}\n\nexport { assertHalfOpenInterval };\n","import { makeImmutable } from \"../../shared/immutable.js\";\n\nimport { assertHalfOpenInterval } from \"./half-open-interval.js\";\n\n/**\n * Represents transaction time (Transaction Time).\n * Defines when the system learned about or recorded a piece of information.\n * Useful for auditing and reconstructing system state at a specific past moment.\n *\n * The window is half-open — `recordedAt` inclusive, `supersededAt` exclusive —\n * and strictly non-empty: `supersededAt` must be later than `recordedAt`, so a\n * record superseded in the same instant it was written is not representable.\n *\n * One caveat mirrors {@link ValueObject}: `createTransactionTime` clones the\n * input dates (no aliasing) but the inner `Date`s are NOT frozen —\n * `Object.freeze` cannot block `setTime`/`setFullYear`, so a caller can still\n * mutate `recordedAt` in place and corrupt the audit record after creation.\n * `readonly` only prevents reassignment. Treat the dates as read-only, or keep\n * instants as ISO/epoch in your own state when that guarantee matters.\n */\ninterface TransactionTime {\n    /** When the information was first recorded in the system. */\n    readonly recordedAt: Date;\n    /** When this information was superseded or invalidated by a newer version. */\n    readonly supersededAt?: Date;\n}\n\ntype CreateTransactionTimeInput = TransactionTime;\n\nfunction assertTransactionTime(\n    txTime: TransactionTime,\n    fieldName: string = \"txTime\",\n): void {\n    assertHalfOpenInterval(\n        `${fieldName}.recordedAt`,\n        txTime.recordedAt,\n        `${fieldName}.supersededAt`,\n        txTime.supersededAt,\n    );\n}\n\nfunction createTransactionTime(\n    input: CreateTransactionTimeInput,\n): TransactionTime {\n    assertTransactionTime(input, \"txTime\");\n\n    if (input.supersededAt === undefined) {\n        return makeImmutable({\n            recordedAt: input.recordedAt,\n        });\n    }\n\n    return makeImmutable({\n        recordedAt: input.recordedAt,\n        supersededAt: input.supersededAt,\n    });\n}\n\nexport {\n    assertTransactionTime,\n    createTransactionTime,\n    type CreateTransactionTimeInput,\n    type TransactionTime,\n};\n","import { makeImmutable } from \"../../shared/immutable.js\";\n\nimport { assertHalfOpenInterval } from \"./half-open-interval.js\";\n\n/**\n * Represents business time (Valid Time).\n * Defines when a piece of information is considered true or in effect in the real world.\n *\n * The window is half-open — `from` inclusive, `to` exclusive — and strictly\n * non-empty: `to` must be later than `from`, so a zero-duration range `[t, t)`\n * is deliberately not representable. Model an instantaneous event as an open\n * range closed by the next fact, not as an empty window.\n *\n * One caveat mirrors {@link ValueObject}: `createValidTime` clones the input\n * dates (no aliasing) but the inner `Date`s are NOT frozen — `Object.freeze`\n * cannot block `setTime`/`setFullYear`, so a caller can still mutate `from`\n * in place and corrupt the range after creation. `readonly` only prevents\n * reassignment. Treat the dates as read-only, or keep instants as ISO/epoch in\n * your own state when that guarantee matters.\n */\ninterface ValidTime {\n    /** Start of the validity window (inclusive). */\n    readonly from: Date;\n    /** End of the validity window (exclusive). When absent, the information is still in effect. */\n    readonly to?: Date;\n}\n\ntype CreateValidTimeInput = ValidTime;\n\nfunction assertValidTime(\n    validTime: ValidTime,\n    fieldName: string = \"validTime\",\n): void {\n    assertHalfOpenInterval(\n        `${fieldName}.from`,\n        validTime.from,\n        `${fieldName}.to`,\n        validTime.to,\n    );\n}\n\nfunction createValidTime(input: CreateValidTimeInput): ValidTime {\n    assertValidTime(input, \"validTime\");\n\n    if (input.to === undefined) {\n        return makeImmutable({\n            from: input.from,\n        });\n    }\n\n    return makeImmutable({\n        from: input.from,\n        to: input.to,\n    });\n}\n\nexport {\n    assertValidTime,\n    createValidTime,\n    type CreateValidTimeInput,\n    type ValidTime,\n};\n","import { assertValidDate } from \"../../shared/temporal-guards.js\";\n\nimport { assertValidTime, type ValidTime } from \"./valid-time.js\";\n\n/**\n * Checks whether a temporal range is \"open\" (has no end date).\n * Useful for identifying information that is still in effect / active.\n */\nfunction isOpen(range: ValidTime): boolean {\n    assertValidTime(range, \"range\");\n\n    return range.to === undefined;\n}\n\n/**\n * Checks whether a temporal range is \"closed\" (has a defined end date).\n */\nfunction isClosed(range: ValidTime): boolean {\n    return !isOpen(range);\n}\n\n/**\n * Checks whether a specific date is contained within the temporal range.\n * The lower bound (`from`) is inclusive, while the upper bound (`to`) is exclusive.\n */\nfunction contains(range: ValidTime, date: Date): boolean {\n    assertValidTime(range, \"range\");\n    assertValidDate(\"date\", date);\n\n    const fromTime = range.from.getTime();\n    const toTime = range.to?.getTime() ?? Number.POSITIVE_INFINITY;\n    const targetTime = date.getTime();\n\n    return targetTime >= fromTime && targetTime < toTime;\n}\n\n/**\n * Checks whether two temporal ranges overlap at any point.\n * Useful for validating whether a new rule conflicts with an existing one.\n */\nfunction overlaps(left: ValidTime, right: ValidTime): boolean {\n    assertValidTime(left, \"left\");\n    assertValidTime(right, \"right\");\n\n    const leftFrom = left.from.getTime();\n    const leftTo = left.to?.getTime() ?? Number.POSITIVE_INFINITY;\n    const rightFrom = right.from.getTime();\n    const rightTo = right.to?.getTime() ?? Number.POSITIVE_INFINITY;\n\n    return leftFrom < rightTo && rightFrom < leftTo;\n}\n\nexport { contains, isClosed, isOpen, overlaps };\n","import { type DeepReadonly, makeImmutable } from \"../../shared/immutable.js\";\n\nimport {\n    createTransactionTime,\n    type CreateTransactionTimeInput,\n    type TransactionTime,\n} from \"./transaction-time.js\";\nimport {\n    createValidTime,\n    type CreateValidTimeInput,\n    type ValidTime,\n} from \"./valid-time.js\";\n\n/**\n * Pairs a domain datum with its time dimensions (Business and Transaction).\n * It is the representation of an entry in the append-only (historical) table.\n *\n * `data` must be plain, structured-cloneable state — the primitive shape of an\n * aggregate, not the aggregate itself. `createTemporalSnapshot` deep-clones it\n * via `structuredClone`: functions and symbols inside `data` throw an\n * `InvariantViolationException`, and class instances (a `ValueObject`, an\n * `Entity`) are NOT rejected — they are silently flattened to plain objects,\n * losing their prototype (and with it `equals`/`toPrimitive`). Project rich\n * objects down first, e.g. with `toPrimitive()`.\n */\ninterface TemporalSnapshot<T> {\n    /** The data or state captured by the snapshot. */\n    readonly data: DeepReadonly<T>;\n    /** Period during which this datum was valid in the real world. */\n    readonly validTime: ValidTime;\n    /** Period during which this record was the state known to the system. */\n    readonly txTime: TransactionTime;\n}\n\ninterface CreateTemporalSnapshotInput<T> {\n    readonly data: T;\n    readonly validTime: CreateValidTimeInput;\n    readonly txTime: CreateTransactionTimeInput;\n}\n\nfunction createTemporalSnapshot<T>(\n    input: CreateTemporalSnapshotInput<T>,\n): TemporalSnapshot<T> {\n    // The time dimensions come out of their factories already cloned and\n    // frozen; only `data` still needs the clone+freeze. Freezing the shell by\n    // hand avoids a second structuredClone pass over the whole snapshot.\n    return Object.freeze({\n        data: makeImmutable(input.data),\n        validTime: createValidTime(input.validTime),\n        txTime: createTransactionTime(input.txTime),\n    });\n}\n\nexport {\n    createTemporalSnapshot,\n    type CreateTemporalSnapshotInput,\n    type TemporalSnapshot,\n};\n"],"mappings":";;;;;;;;;;;;;;;;AAYA,SAAS,uBACL,YACA,OACA,UACA,KACI;CACJ,wBAAA,gBAAgB,YAAY,KAAK;CAEjC,IAAI,QAAQ,KAAA,GACR;CAGJ,wBAAA,gBAAgB,UAAU,GAAG;CAE7B,IAAI,IAAI,QAAQ,KAAK,MAAM,QAAQ,GAC/B,MAAM,IAAIA,sCAAAA,4BACN,GAAG,SAAS,sBAAsB,YACtC;AAER;;;ACFA,SAAS,sBACL,QACA,YAAoB,UAChB;CACJ,uBACI,GAAG,UAAU,cACb,OAAO,YACP,GAAG,UAAU,gBACb,OAAO,YACX;AACJ;AAEA,SAAS,sBACL,OACe;CACf,sBAAsB,OAAO,QAAQ;CAErC,IAAI,MAAM,iBAAiB,KAAA,GACvB,OAAOC,kBAAAA,cAAc,EACjB,YAAY,MAAM,WACtB,CAAC;CAGL,OAAOA,kBAAAA,cAAc;EACjB,YAAY,MAAM;EAClB,cAAc,MAAM;CACxB,CAAC;AACL;;;AC3BA,SAAS,gBACL,WACA,YAAoB,aAChB;CACJ,uBACI,GAAG,UAAU,QACb,UAAU,MACV,GAAG,UAAU,MACb,UAAU,EACd;AACJ;AAEA,SAAS,gBAAgB,OAAwC;CAC7D,gBAAgB,OAAO,WAAW;CAElC,IAAI,MAAM,OAAO,KAAA,GACb,OAAOC,kBAAAA,cAAc,EACjB,MAAM,MAAM,KAChB,CAAC;CAGL,OAAOA,kBAAAA,cAAc;EACjB,MAAM,MAAM;EACZ,IAAI,MAAM;CACd,CAAC;AACL;;;;;;;AC9CA,SAAS,OAAO,OAA2B;CACvC,gBAAgB,OAAO,OAAO;CAE9B,OAAO,MAAM,OAAO,KAAA;AACxB;;;;AAKA,SAAS,SAAS,OAA2B;CACzC,OAAO,CAAC,OAAO,KAAK;AACxB;;;;;AAMA,SAAS,SAAS,OAAkB,MAAqB;CACrD,gBAAgB,OAAO,OAAO;CAC9B,wBAAA,gBAAgB,QAAQ,IAAI;CAE5B,MAAM,WAAW,MAAM,KAAK,QAAQ;CACpC,MAAM,SAAS,MAAM,IAAI,QAAQ,KAAK,OAAO;CAC7C,MAAM,aAAa,KAAK,QAAQ;CAEhC,OAAO,cAAc,YAAY,aAAa;AAClD;;;;;AAMA,SAAS,SAAS,MAAiB,OAA2B;CAC1D,gBAAgB,MAAM,MAAM;CAC5B,gBAAgB,OAAO,OAAO;CAE9B,MAAM,WAAW,KAAK,KAAK,QAAQ;CACnC,MAAM,SAAS,KAAK,IAAI,QAAQ,KAAK,OAAO;CAC5C,MAAM,YAAY,MAAM,KAAK,QAAQ;CAGrC,OAAO,YAFS,MAAM,IAAI,QAAQ,KAAK,OAAO,sBAEjB,YAAY;AAC7C;;;ACVA,SAAS,uBACL,OACmB;CAInB,OAAO,OAAO,OAAO;EACjB,MAAMC,kBAAAA,cAAc,MAAM,IAAI;EAC9B,WAAW,gBAAgB,MAAM,SAAS;EAC1C,QAAQ,sBAAsB,MAAM,MAAM;CAC9C,CAAC;AACL"}

package/dist/domain/index.d.cts

@@ -1,4 +1,28 @@
 import { t as DeepReadonly } from "../immutable.cjs";
 import { n as ValueObjectPluginContract, t as ValueObject } from "../value-object.cjs";
+import { a as ValidTime, c as CreateTransactionTimeInput, d as createTransactionTime, i as CreateValidTimeInput, l as TransactionTime, n as TemporalSnapshot, o as assertValidTime, r as createTemporalSnapshot, s as createValidTime, t as CreateTemporalSnapshotInput, u as assertTransactionTime } from "../temporal-snapshot.cjs";
 import { n as Entity, r as EntityState, t as UuidIdentifier } from "../uuid-identifier.cjs";
-export { type DeepReadonly, Entity, type EntityState, UuidIdentifier, ValueObject, type ValueObjectPluginContract };
+
+//#region src/core/domain/temporal/temporal-range.d.ts
+/**
+ * Checks whether a temporal range is "open" (has no end date).
+ * Useful for identifying information that is still in effect / active.
+ */
+declare function isOpen(range: ValidTime): boolean;
+/**
+ * Checks whether a temporal range is "closed" (has a defined end date).
+ */
+declare function isClosed(range: ValidTime): boolean;
+/**
+ * Checks whether a specific date is contained within the temporal range.
+ * The lower bound (`from`) is inclusive, while the upper bound (`to`) is exclusive.
+ */
+declare function contains(range: ValidTime, date: Date): boolean;
+/**
+ * Checks whether two temporal ranges overlap at any point.
+ * Useful for validating whether a new rule conflicts with an existing one.
+ */
+declare function overlaps(left: ValidTime, right: ValidTime): boolean;
+//#endregion
+export { CreateTemporalSnapshotInput, CreateTransactionTimeInput, CreateValidTimeInput, type DeepReadonly, Entity, type EntityState, TemporalSnapshot, TransactionTime, UuidIdentifier, ValidTime, ValueObject, type ValueObjectPluginContract, assertTransactionTime, assertValidTime, contains, createTemporalSnapshot, createTransactionTime, createValidTime, isClosed, isOpen, overlaps };
+//# sourceMappingURL=index.d.cts.map

package/dist/domain/index.d.ts

@@ -1,4 +1,28 @@
 import { t as DeepReadonly } from "../immutable.js";
 import { n as ValueObjectPluginContract, t as ValueObject } from "../value-object.js";
+import { a as ValidTime, c as CreateTransactionTimeInput, d as createTransactionTime, i as CreateValidTimeInput, l as TransactionTime, n as TemporalSnapshot, o as assertValidTime, r as createTemporalSnapshot, s as createValidTime, t as CreateTemporalSnapshotInput, u as assertTransactionTime } from "../temporal-snapshot.js";
 import { n as Entity, r as EntityState, t as UuidIdentifier } from "../uuid-identifier.js";
-export { type DeepReadonly, Entity, type EntityState, UuidIdentifier, ValueObject, type ValueObjectPluginContract };
+
+//#region src/core/domain/temporal/temporal-range.d.ts
+/**
+ * Checks whether a temporal range is "open" (has no end date).
+ * Useful for identifying information that is still in effect / active.
+ */
+declare function isOpen(range: ValidTime): boolean;
+/**
+ * Checks whether a temporal range is "closed" (has a defined end date).
+ */
+declare function isClosed(range: ValidTime): boolean;
+/**
+ * Checks whether a specific date is contained within the temporal range.
+ * The lower bound (`from`) is inclusive, while the upper bound (`to`) is exclusive.
+ */
+declare function contains(range: ValidTime, date: Date): boolean;
+/**
+ * Checks whether two temporal ranges overlap at any point.
+ * Useful for validating whether a new rule conflicts with an existing one.
+ */
+declare function overlaps(left: ValidTime, right: ValidTime): boolean;
+//#endregion
+export { CreateTemporalSnapshotInput, CreateTransactionTimeInput, CreateValidTimeInput, type DeepReadonly, Entity, type EntityState, TemporalSnapshot, TransactionTime, UuidIdentifier, ValidTime, ValueObject, type ValueObjectPluginContract, assertTransactionTime, assertValidTime, contains, createTemporalSnapshot, createTransactionTime, createValidTime, isClosed, isOpen, overlaps };
+//# sourceMappingURL=index.d.ts.map

package/dist/domain/index.js

@@ -1,4 +1,100 @@
-import { t as Entity } from "../entity.js";
+import { t as InvariantViolationException } from "../invariant-violation-exception.js";
+import { t as assertValidDate } from "../temporal-guards.js";
+import { n as makeImmutable } from "../immutable.js";
 import { t as ValueObject } from "../value-object.js";
-import { t as UuidIdentifier } from "../uuid-identifier.js";
-export { Entity, UuidIdentifier, ValueObject };
+import { n as Entity, t as UuidIdentifier } from "../uuid-identifier.js";
+//#region src/core/domain/temporal/half-open-interval.ts
+/**
+* Shared core of the bitemporal primitives: a half-open interval
+* `[start, end)` whose end, when present, must be strictly later than its
+* start. `ValidTime` and `TransactionTime` are the same shape under different
+* (deliberate) vocabularies — the invariant lives here once so the two files
+* cannot drift apart.
+*
+* Internal to `domain/temporal`; not exported from the barrel.
+*/
+function assertHalfOpenInterval(startLabel, start, endLabel, end) {
+	assertValidDate(startLabel, start);
+	if (end === void 0) return;
+	assertValidDate(endLabel, end);
+	if (end.getTime() <= start.getTime()) throw new InvariantViolationException(`${endLabel} must be later than ${startLabel}`);
+}
+//#endregion
+//#region src/core/domain/temporal/transaction-time.ts
+function assertTransactionTime(txTime, fieldName = "txTime") {
+	assertHalfOpenInterval(`${fieldName}.recordedAt`, txTime.recordedAt, `${fieldName}.supersededAt`, txTime.supersededAt);
+}
+function createTransactionTime(input) {
+	assertTransactionTime(input, "txTime");
+	if (input.supersededAt === void 0) return makeImmutable({ recordedAt: input.recordedAt });
+	return makeImmutable({
+		recordedAt: input.recordedAt,
+		supersededAt: input.supersededAt
+	});
+}
+//#endregion
+//#region src/core/domain/temporal/valid-time.ts
+function assertValidTime(validTime, fieldName = "validTime") {
+	assertHalfOpenInterval(`${fieldName}.from`, validTime.from, `${fieldName}.to`, validTime.to);
+}
+function createValidTime(input) {
+	assertValidTime(input, "validTime");
+	if (input.to === void 0) return makeImmutable({ from: input.from });
+	return makeImmutable({
+		from: input.from,
+		to: input.to
+	});
+}
+//#endregion
+//#region src/core/domain/temporal/temporal-range.ts
+/**
+* Checks whether a temporal range is "open" (has no end date).
+* Useful for identifying information that is still in effect / active.
+*/
+function isOpen(range) {
+	assertValidTime(range, "range");
+	return range.to === void 0;
+}
+/**
+* Checks whether a temporal range is "closed" (has a defined end date).
+*/
+function isClosed(range) {
+	return !isOpen(range);
+}
+/**
+* Checks whether a specific date is contained within the temporal range.
+* The lower bound (`from`) is inclusive, while the upper bound (`to`) is exclusive.
+*/
+function contains(range, date) {
+	assertValidTime(range, "range");
+	assertValidDate("date", date);
+	const fromTime = range.from.getTime();
+	const toTime = range.to?.getTime() ?? Number.POSITIVE_INFINITY;
+	const targetTime = date.getTime();
+	return targetTime >= fromTime && targetTime < toTime;
+}
+/**
+* Checks whether two temporal ranges overlap at any point.
+* Useful for validating whether a new rule conflicts with an existing one.
+*/
+function overlaps(left, right) {
+	assertValidTime(left, "left");
+	assertValidTime(right, "right");
+	const leftFrom = left.from.getTime();
+	const leftTo = left.to?.getTime() ?? Number.POSITIVE_INFINITY;
+	const rightFrom = right.from.getTime();
+	return leftFrom < (right.to?.getTime() ?? Number.POSITIVE_INFINITY) && rightFrom < leftTo;
+}
+//#endregion
+//#region src/core/domain/temporal/temporal-snapshot.ts
+function createTemporalSnapshot(input) {
+	return Object.freeze({
+		data: makeImmutable(input.data),
+		validTime: createValidTime(input.validTime),
+		txTime: createTransactionTime(input.txTime)
+	});
+}
+//#endregion
+export { Entity, UuidIdentifier, ValueObject, assertTransactionTime, assertValidTime, contains, createTemporalSnapshot, createTransactionTime, createValidTime, isClosed, isOpen, overlaps };
+
+//# sourceMappingURL=index.js.map

package/dist/domain/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/core/domain/temporal/half-open-interval.ts","../../src/core/domain/temporal/transaction-time.ts","../../src/core/domain/temporal/valid-time.ts","../../src/core/domain/temporal/temporal-range.ts","../../src/core/domain/temporal/temporal-snapshot.ts"],"sourcesContent":["import { InvariantViolationException } from \"../../exceptions/invariant-violation-exception.js\";\nimport { assertValidDate } from \"../../shared/temporal-guards.js\";\n\n/**\n * Shared core of the bitemporal primitives: a half-open interval\n * `[start, end)` whose end, when present, must be strictly later than its\n * start. `ValidTime` and `TransactionTime` are the same shape under different\n * (deliberate) vocabularies — the invariant lives here once so the two files\n * cannot drift apart.\n *\n * Internal to `domain/temporal`; not exported from the barrel.\n */\nfunction assertHalfOpenInterval(\n    startLabel: string,\n    start: Date,\n    endLabel: string,\n    end: Date | undefined,\n): void {\n    assertValidDate(startLabel, start);\n\n    if (end === undefined) {\n        return;\n    }\n\n    assertValidDate(endLabel, end);\n\n    if (end.getTime() <= start.getTime()) {\n        throw new InvariantViolationException(\n            `${endLabel} must be later than ${startLabel}`,\n        );\n    }\n}\n\nexport { assertHalfOpenInterval };\n","import { makeImmutable } from \"../../shared/immutable.js\";\n\nimport { assertHalfOpenInterval } from \"./half-open-interval.js\";\n\n/**\n * Represents transaction time (Transaction Time).\n * Defines when the system learned about or recorded a piece of information.\n * Useful for auditing and reconstructing system state at a specific past moment.\n *\n * The window is half-open — `recordedAt` inclusive, `supersededAt` exclusive —\n * and strictly non-empty: `supersededAt` must be later than `recordedAt`, so a\n * record superseded in the same instant it was written is not representable.\n *\n * One caveat mirrors {@link ValueObject}: `createTransactionTime` clones the\n * input dates (no aliasing) but the inner `Date`s are NOT frozen —\n * `Object.freeze` cannot block `setTime`/`setFullYear`, so a caller can still\n * mutate `recordedAt` in place and corrupt the audit record after creation.\n * `readonly` only prevents reassignment. Treat the dates as read-only, or keep\n * instants as ISO/epoch in your own state when that guarantee matters.\n */\ninterface TransactionTime {\n    /** When the information was first recorded in the system. */\n    readonly recordedAt: Date;\n    /** When this information was superseded or invalidated by a newer version. */\n    readonly supersededAt?: Date;\n}\n\ntype CreateTransactionTimeInput = TransactionTime;\n\nfunction assertTransactionTime(\n    txTime: TransactionTime,\n    fieldName: string = \"txTime\",\n): void {\n    assertHalfOpenInterval(\n        `${fieldName}.recordedAt`,\n        txTime.recordedAt,\n        `${fieldName}.supersededAt`,\n        txTime.supersededAt,\n    );\n}\n\nfunction createTransactionTime(\n    input: CreateTransactionTimeInput,\n): TransactionTime {\n    assertTransactionTime(input, \"txTime\");\n\n    if (input.supersededAt === undefined) {\n        return makeImmutable({\n            recordedAt: input.recordedAt,\n        });\n    }\n\n    return makeImmutable({\n        recordedAt: input.recordedAt,\n        supersededAt: input.supersededAt,\n    });\n}\n\nexport {\n    assertTransactionTime,\n    createTransactionTime,\n    type CreateTransactionTimeInput,\n    type TransactionTime,\n};\n","import { makeImmutable } from \"../../shared/immutable.js\";\n\nimport { assertHalfOpenInterval } from \"./half-open-interval.js\";\n\n/**\n * Represents business time (Valid Time).\n * Defines when a piece of information is considered true or in effect in the real world.\n *\n * The window is half-open — `from` inclusive, `to` exclusive — and strictly\n * non-empty: `to` must be later than `from`, so a zero-duration range `[t, t)`\n * is deliberately not representable. Model an instantaneous event as an open\n * range closed by the next fact, not as an empty window.\n *\n * One caveat mirrors {@link ValueObject}: `createValidTime` clones the input\n * dates (no aliasing) but the inner `Date`s are NOT frozen — `Object.freeze`\n * cannot block `setTime`/`setFullYear`, so a caller can still mutate `from`\n * in place and corrupt the range after creation. `readonly` only prevents\n * reassignment. Treat the dates as read-only, or keep instants as ISO/epoch in\n * your own state when that guarantee matters.\n */\ninterface ValidTime {\n    /** Start of the validity window (inclusive). */\n    readonly from: Date;\n    /** End of the validity window (exclusive). When absent, the information is still in effect. */\n    readonly to?: Date;\n}\n\ntype CreateValidTimeInput = ValidTime;\n\nfunction assertValidTime(\n    validTime: ValidTime,\n    fieldName: string = \"validTime\",\n): void {\n    assertHalfOpenInterval(\n        `${fieldName}.from`,\n        validTime.from,\n        `${fieldName}.to`,\n        validTime.to,\n    );\n}\n\nfunction createValidTime(input: CreateValidTimeInput): ValidTime {\n    assertValidTime(input, \"validTime\");\n\n    if (input.to === undefined) {\n        return makeImmutable({\n            from: input.from,\n        });\n    }\n\n    return makeImmutable({\n        from: input.from,\n        to: input.to,\n    });\n}\n\nexport {\n    assertValidTime,\n    createValidTime,\n    type CreateValidTimeInput,\n    type ValidTime,\n};\n","import { assertValidDate } from \"../../shared/temporal-guards.js\";\n\nimport { assertValidTime, type ValidTime } from \"./valid-time.js\";\n\n/**\n * Checks whether a temporal range is \"open\" (has no end date).\n * Useful for identifying information that is still in effect / active.\n */\nfunction isOpen(range: ValidTime): boolean {\n    assertValidTime(range, \"range\");\n\n    return range.to === undefined;\n}\n\n/**\n * Checks whether a temporal range is \"closed\" (has a defined end date).\n */\nfunction isClosed(range: ValidTime): boolean {\n    return !isOpen(range);\n}\n\n/**\n * Checks whether a specific date is contained within the temporal range.\n * The lower bound (`from`) is inclusive, while the upper bound (`to`) is exclusive.\n */\nfunction contains(range: ValidTime, date: Date): boolean {\n    assertValidTime(range, \"range\");\n    assertValidDate(\"date\", date);\n\n    const fromTime = range.from.getTime();\n    const toTime = range.to?.getTime() ?? Number.POSITIVE_INFINITY;\n    const targetTime = date.getTime();\n\n    return targetTime >= fromTime && targetTime < toTime;\n}\n\n/**\n * Checks whether two temporal ranges overlap at any point.\n * Useful for validating whether a new rule conflicts with an existing one.\n */\nfunction overlaps(left: ValidTime, right: ValidTime): boolean {\n    assertValidTime(left, \"left\");\n    assertValidTime(right, \"right\");\n\n    const leftFrom = left.from.getTime();\n    const leftTo = left.to?.getTime() ?? Number.POSITIVE_INFINITY;\n    const rightFrom = right.from.getTime();\n    const rightTo = right.to?.getTime() ?? Number.POSITIVE_INFINITY;\n\n    return leftFrom < rightTo && rightFrom < leftTo;\n}\n\nexport { contains, isClosed, isOpen, overlaps };\n","import { type DeepReadonly, makeImmutable } from \"../../shared/immutable.js\";\n\nimport {\n    createTransactionTime,\n    type CreateTransactionTimeInput,\n    type TransactionTime,\n} from \"./transaction-time.js\";\nimport {\n    createValidTime,\n    type CreateValidTimeInput,\n    type ValidTime,\n} from \"./valid-time.js\";\n\n/**\n * Pairs a domain datum with its time dimensions (Business and Transaction).\n * It is the representation of an entry in the append-only (historical) table.\n *\n * `data` must be plain, structured-cloneable state — the primitive shape of an\n * aggregate, not the aggregate itself. `createTemporalSnapshot` deep-clones it\n * via `structuredClone`: functions and symbols inside `data` throw an\n * `InvariantViolationException`, and class instances (a `ValueObject`, an\n * `Entity`) are NOT rejected — they are silently flattened to plain objects,\n * losing their prototype (and with it `equals`/`toPrimitive`). Project rich\n * objects down first, e.g. with `toPrimitive()`.\n */\ninterface TemporalSnapshot<T> {\n    /** The data or state captured by the snapshot. */\n    readonly data: DeepReadonly<T>;\n    /** Period during which this datum was valid in the real world. */\n    readonly validTime: ValidTime;\n    /** Period during which this record was the state known to the system. */\n    readonly txTime: TransactionTime;\n}\n\ninterface CreateTemporalSnapshotInput<T> {\n    readonly data: T;\n    readonly validTime: CreateValidTimeInput;\n    readonly txTime: CreateTransactionTimeInput;\n}\n\nfunction createTemporalSnapshot<T>(\n    input: CreateTemporalSnapshotInput<T>,\n): TemporalSnapshot<T> {\n    // The time dimensions come out of their factories already cloned and\n    // frozen; only `data` still needs the clone+freeze. Freezing the shell by\n    // hand avoids a second structuredClone pass over the whole snapshot.\n    return Object.freeze({\n        data: makeImmutable(input.data),\n        validTime: createValidTime(input.validTime),\n        txTime: createTransactionTime(input.txTime),\n    });\n}\n\nexport {\n    createTemporalSnapshot,\n    type CreateTemporalSnapshotInput,\n    type TemporalSnapshot,\n};\n"],"mappings":";;;;;;;;;;;;;;;AAYA,SAAS,uBACL,YACA,OACA,UACA,KACI;CACJ,gBAAgB,YAAY,KAAK;CAEjC,IAAI,QAAQ,KAAA,GACR;CAGJ,gBAAgB,UAAU,GAAG;CAE7B,IAAI,IAAI,QAAQ,KAAK,MAAM,QAAQ,GAC/B,MAAM,IAAI,4BACN,GAAG,SAAS,sBAAsB,YACtC;AAER;;;ACFA,SAAS,sBACL,QACA,YAAoB,UAChB;CACJ,uBACI,GAAG,UAAU,cACb,OAAO,YACP,GAAG,UAAU,gBACb,OAAO,YACX;AACJ;AAEA,SAAS,sBACL,OACe;CACf,sBAAsB,OAAO,QAAQ;CAErC,IAAI,MAAM,iBAAiB,KAAA,GACvB,OAAO,cAAc,EACjB,YAAY,MAAM,WACtB,CAAC;CAGL,OAAO,cAAc;EACjB,YAAY,MAAM;EAClB,cAAc,MAAM;CACxB,CAAC;AACL;;;AC3BA,SAAS,gBACL,WACA,YAAoB,aAChB;CACJ,uBACI,GAAG,UAAU,QACb,UAAU,MACV,GAAG,UAAU,MACb,UAAU,EACd;AACJ;AAEA,SAAS,gBAAgB,OAAwC;CAC7D,gBAAgB,OAAO,WAAW;CAElC,IAAI,MAAM,OAAO,KAAA,GACb,OAAO,cAAc,EACjB,MAAM,MAAM,KAChB,CAAC;CAGL,OAAO,cAAc;EACjB,MAAM,MAAM;EACZ,IAAI,MAAM;CACd,CAAC;AACL;;;;;;;AC9CA,SAAS,OAAO,OAA2B;CACvC,gBAAgB,OAAO,OAAO;CAE9B,OAAO,MAAM,OAAO,KAAA;AACxB;;;;AAKA,SAAS,SAAS,OAA2B;CACzC,OAAO,CAAC,OAAO,KAAK;AACxB;;;;;AAMA,SAAS,SAAS,OAAkB,MAAqB;CACrD,gBAAgB,OAAO,OAAO;CAC9B,gBAAgB,QAAQ,IAAI;CAE5B,MAAM,WAAW,MAAM,KAAK,QAAQ;CACpC,MAAM,SAAS,MAAM,IAAI,QAAQ,KAAK,OAAO;CAC7C,MAAM,aAAa,KAAK,QAAQ;CAEhC,OAAO,cAAc,YAAY,aAAa;AAClD;;;;;AAMA,SAAS,SAAS,MAAiB,OAA2B;CAC1D,gBAAgB,MAAM,MAAM;CAC5B,gBAAgB,OAAO,OAAO;CAE9B,MAAM,WAAW,KAAK,KAAK,QAAQ;CACnC,MAAM,SAAS,KAAK,IAAI,QAAQ,KAAK,OAAO;CAC5C,MAAM,YAAY,MAAM,KAAK,QAAQ;CAGrC,OAAO,YAFS,MAAM,IAAI,QAAQ,KAAK,OAAO,sBAEjB,YAAY;AAC7C;;;ACVA,SAAS,uBACL,OACmB;CAInB,OAAO,OAAO,OAAO;EACjB,MAAM,cAAc,MAAM,IAAI;EAC9B,WAAW,gBAAgB,MAAM,SAAS;EAC1C,QAAQ,sBAAsB,MAAM,MAAM;CAC9C,CAAC;AACL"}

package/dist/domain-event-contracts.cjs

@@ -1,17 +1,21 @@
-const require_use_case = require("./use-case.cjs");
-const require_entity = require("./entity.cjs");
-const require_value_object = require("./value-object.cjs");
+const require_immutable = require("./immutable.cjs");
+const require_aggregate_version = require("./aggregate-version.cjs");
 //#region src/core/versioning/domain-event-contracts.ts
 function buildDomainEventContractVersions(selection) {
 	const contractVersions = {};
-	if (selection.entity) contractVersions.entity_contract = require_entity.Entity.CONTRACT_VERSION;
-	if (selection.valueObject) contractVersions.value_object_contract = require_value_object.ValueObject.CONTRACT_VERSION;
-	if (selection.useCase) contractVersions.use_case_contract = require_use_case.UseCase.CONTRACT_VERSION;
+	if (selection.entity) contractVersions.entity_contract = selection.entity.CONTRACT_VERSION;
+	if (selection.valueObject) contractVersions.value_object_contract = selection.valueObject.CONTRACT_VERSION;
+	if (selection.useCase) contractVersions.use_case_contract = selection.useCase.CONTRACT_VERSION;
 	return Object.freeze(contractVersions);
 }
+/**
+* Builds a frozen domain-event envelope. The whole envelope is deep-frozen,
+* so the `payload` handed in becomes immutable too — an event is an immutable
+* fact, and the caller must not mutate the payload after wrapping it.
+*/
 function createDomainEventEnvelope(input) {
-	require_entity.assertValidAggregateVersion(input.aggregateVersion);
-	return Object.freeze({
+	require_aggregate_version.assertValidAggregateVersion(input.aggregateVersion);
+	return require_immutable.deepFreeze({
 		aggregate_version: input.aggregateVersion,
 		payload: input.payload,
 		...buildDomainEventContractVersions(input.contracts)

package/dist/domain-event-contracts.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"domain-event-contracts.cjs","names":["Entity","ValueObject","UseCase"],"sources":["../src/core/versioning/domain-event-contracts.ts"],"sourcesContent":["import { UseCase } from \"../application/use-case.js\";\nimport { Entity } from \"../domain/entity.js\";\nimport { ValueObject } from \"../domain/value-object.js\";\nimport { assertValidAggregateVersion } from \"../shared/aggregate-version.js\";\nimport { type ContractVersion } from \"./version.js\";\n\ninterface DomainEventContractSelection {\n    readonly entity?: boolean;\n    readonly valueObject?: boolean;\n    readonly useCase?: boolean;\n}\n\ninterface DomainEventContractVersions {\n    readonly entity_contract?: ContractVersion;\n    readonly value_object_contract?: ContractVersion;\n    readonly use_case_contract?: ContractVersion;\n}\n\ninterface CreateDomainEventEnvelopeInput<TPayload> {\n    readonly aggregateVersion: number;\n    readonly payload: TPayload;\n    readonly contracts: DomainEventContractSelection;\n}\n\ninterface DomainEventEnvelope<TPayload> extends DomainEventContractVersions {\n    readonly aggregate_version: number;\n    readonly payload: TPayload;\n}\n\nfunction buildDomainEventContractVersions(\n    selection: DomainEventContractSelection,\n): DomainEventContractVersions {\n    const contractVersions: {\n        entity_contract?: ContractVersion;\n        value_object_contract?: ContractVersion;\n        use_case_contract?: ContractVersion;\n    } = {};\n\n    if (selection.entity) {\n        contractVersions.entity_contract = Entity.CONTRACT_VERSION;\n    }\n\n    if (selection.valueObject) {\n        contractVersions.value_object_contract = ValueObject.CONTRACT_VERSION;\n    }\n\n    if (selection.useCase) {\n        contractVersions.use_case_contract = UseCase.CONTRACT_VERSION;\n    }\n\n    return Object.freeze(contractVersions);\n}\n\nfunction createDomainEventEnvelope<TPayload>(\n    input: CreateDomainEventEnvelopeInput<TPayload>,\n): DomainEventEnvelope<TPayload> {\n    assertValidAggregateVersion(input.aggregateVersion);\n\n    return Object.freeze({\n        aggregate_version: input.aggregateVersion,\n        payload: input.payload,\n        ...buildDomainEventContractVersions(input.contracts),\n    });\n}\n\nexport {\n    buildDomainEventContractVersions,\n    createDomainEventEnvelope,\n    type CreateDomainEventEnvelopeInput,\n    type DomainEventContractSelection,\n    type DomainEventContractVersions,\n    type DomainEventEnvelope,\n};\n"],"mappings":";;;;AA6BA,SAAS,iCACL,WAC2B;CAC3B,MAAM,mBAIF,CAAC;CAEL,IAAI,UAAU,QACV,iBAAiB,kBAAkBA,eAAAA,OAAO;CAG9C,IAAI,UAAU,aACV,iBAAiB,wBAAwBC,qBAAAA,YAAY;CAGzD,IAAI,UAAU,SACV,iBAAiB,oBAAoBC,iBAAAA,QAAQ;CAGjD,OAAO,OAAO,OAAO,gBAAgB;AACzC;AAEA,SAAS,0BACL,OAC6B;CAC7B,eAAA,4BAA4B,MAAM,gBAAgB;CAElD,OAAO,OAAO,OAAO;EACjB,mBAAmB,MAAM;EACzB,SAAS,MAAM;EACf,GAAG,iCAAiC,MAAM,SAAS;CACvD,CAAC;AACL"}
+{"version":3,"file":"domain-event-contracts.cjs","names":["deepFreeze"],"sources":["../src/core/versioning/domain-event-contracts.ts"],"sourcesContent":["import { assertValidAggregateVersion } from \"../shared/aggregate-version.js\";\nimport { deepFreeze } from \"../shared/immutable.js\";\nimport { type ContractVersion } from \"./version.js\";\n\n/** Anything carrying a `CONTRACT_VERSION` — a class decorated with `@version`. */\ninterface ContractVersioned {\n    readonly CONTRACT_VERSION: ContractVersion;\n}\n\n/**\n * The classes whose contract version should be recorded on the envelope.\n *\n * Pass the **concrete** aggregate/value-object/use-case class (not the base),\n * so the envelope records the version the caller actually annotated with\n * `@version`. A base class handed here would report only the framework's\n * version, not the concrete shape that produced the event.\n */\ninterface DomainEventContractSelection {\n    readonly entity?: ContractVersioned;\n    readonly valueObject?: ContractVersioned;\n    readonly useCase?: ContractVersioned;\n}\n\n// Wire-format shape: `snake_case` keys, deliberately distinct from the\n// `camelCase` builder input above — these travel in the serialized event.\ninterface DomainEventContractVersions {\n    readonly entity_contract?: ContractVersion;\n    readonly value_object_contract?: ContractVersion;\n    readonly use_case_contract?: ContractVersion;\n}\n\ntype MutableContractVersions = {\n    -readonly [K in keyof DomainEventContractVersions]: DomainEventContractVersions[K];\n};\n\ninterface CreateDomainEventEnvelopeInput<TPayload> {\n    readonly aggregateVersion: number;\n    readonly payload: TPayload;\n    readonly contracts: DomainEventContractSelection;\n}\n\n/**\n * A deliberately minimal domain-event envelope: it carries only the aggregate\n * version and the structural contract versions needed for state/event\n * migration. It intentionally omits `eventId`, `eventType`, `occurredAt` and\n * correlation ids — those require a clock/id source and belong to the\n * consumer's event infrastructure. Treat this as a versioning core to extend,\n * not a complete event record.\n */\ninterface DomainEventEnvelope<TPayload> extends DomainEventContractVersions {\n    readonly aggregate_version: number;\n    readonly payload: TPayload;\n}\n\nfunction buildDomainEventContractVersions(\n    selection: DomainEventContractSelection,\n): DomainEventContractVersions {\n    const contractVersions: MutableContractVersions = {};\n\n    if (selection.entity) {\n        contractVersions.entity_contract = selection.entity.CONTRACT_VERSION;\n    }\n\n    if (selection.valueObject) {\n        contractVersions.value_object_contract =\n            selection.valueObject.CONTRACT_VERSION;\n    }\n\n    if (selection.useCase) {\n        contractVersions.use_case_contract = selection.useCase.CONTRACT_VERSION;\n    }\n\n    return Object.freeze(contractVersions);\n}\n\n/**\n * Builds a frozen domain-event envelope. The whole envelope is deep-frozen,\n * so the `payload` handed in becomes immutable too — an event is an immutable\n * fact, and the caller must not mutate the payload after wrapping it.\n */\nfunction createDomainEventEnvelope<TPayload>(\n    input: CreateDomainEventEnvelopeInput<TPayload>,\n): DomainEventEnvelope<TPayload> {\n    assertValidAggregateVersion(input.aggregateVersion);\n\n    return deepFreeze({\n        aggregate_version: input.aggregateVersion,\n        payload: input.payload,\n        ...buildDomainEventContractVersions(input.contracts),\n    });\n}\n\nexport {\n    buildDomainEventContractVersions,\n    createDomainEventEnvelope,\n    type ContractVersioned,\n    type CreateDomainEventEnvelopeInput,\n    type DomainEventContractSelection,\n    type DomainEventContractVersions,\n    type DomainEventEnvelope,\n};\n"],"mappings":";;;AAsDA,SAAS,iCACL,WAC2B;CAC3B,MAAM,mBAA4C,CAAC;CAEnD,IAAI,UAAU,QACV,iBAAiB,kBAAkB,UAAU,OAAO;CAGxD,IAAI,UAAU,aACV,iBAAiB,wBACb,UAAU,YAAY;CAG9B,IAAI,UAAU,SACV,iBAAiB,oBAAoB,UAAU,QAAQ;CAG3D,OAAO,OAAO,OAAO,gBAAgB;AACzC;;;;;;AAOA,SAAS,0BACL,OAC6B;CAC7B,0BAAA,4BAA4B,MAAM,gBAAgB;CAElD,OAAOA,kBAAAA,WAAW;EACd,mBAAmB,MAAM;EACzB,SAAS,MAAM;EACf,GAAG,iCAAiC,MAAM,SAAS;CACvD,CAAC;AACL"}