@cullet/erp-core 1.0.9 → 1.0.11

package/dist/index.d.ts

@@ -43,45 +43,166 @@ interface TracerPort {
 declare function mapPolicyEvaluationError(err: PolicyEvaluationError): AppError;
 //#endregion
 //#region src/core/domain/entity.d.ts
+/**
+ * The minimal persisted shape needed to reconstitute an {@link Entity}.
+ *
+ * This is the contract between storage and the domain: a repository maps a row
+ * (or document) onto these four fields and hands them to a subclass constructor.
+ * `aggregateVersion` travels with the state so optimistic-concurrency checks
+ * survive a round-trip through the database.
+ */
 interface EntityState<TIdentifier> {
   readonly id: TIdentifier;
   readonly createdAt: Date;
   readonly updatedAt: Date;
   readonly aggregateVersion: number;
 }
+/**
+ * Base class for domain entities — objects defined by a stable identity rather
+ * than by their attributes. Two entities are "the same" when their `id`
+ * matches, even if every other field differs; this is the opposite of a
+ * {@link ValueObject}, which is defined entirely by its contents.
+ *
+ * The class owns the bookkeeping common to every aggregate root: a creation
+ * timestamp that never changes, a last-modified timestamp, and an
+ * `aggregateVersion` counter used for optimistic concurrency control. All three
+ * are validated on construction and the dates are defensively cloned, so an
+ * entity can never be built into — or leak — an inconsistent temporal state.
+ *
+ * @typeParam TIdentifier - The identity type (e.g. a branded string id or a VO).
+ */
 declare abstract class Entity<TIdentifier> {
   static readonly CONTRACT_VERSION: ContractVersion;
   private readonly _id;
   private readonly _createdAt;
   private _updatedAt;
   private _aggregateVersion;
+  /**
+   * Reconstitutes an entity from its persisted {@link EntityState}.
+   *
+   * Validates the temporal invariants up front so an invalid entity is
+   * impossible to construct: both dates must be valid, the aggregate version
+   * must be a non-negative integer, and `updatedAt` may not predate
+   * `createdAt`. Both dates are cloned on the way in so a later mutation of
+   * the caller's `Date` objects cannot reach into the entity's internal state.
+   *
+   * Declared `protected` because entities are reconstituted through a
+   * subclass factory, never instantiated directly by application code.
+   *
+   * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+   */
   protected constructor(state: EntityState<TIdentifier>);
+  /** The entity's stable identity — the basis for equality between entities. */
   get id(): TIdentifier;
+  /**
+   * When the entity was first created.
+   *
+   * Returns a clone so callers cannot mutate the entity's internal `Date`;
+   * the value is fixed at construction and never changes thereafter.
+   */
   get createdAt(): Date;
+  /**
+   * When the entity was last modified.
+   *
+   * Returns a clone for the same encapsulation reason as {@link createdAt};
+   * the underlying value advances only through {@link markAsModified}.
+   */
   get updatedAt(): Date;
+  /**
+   * Monotonic counter incremented on every mutation, used for optimistic
+   * concurrency control: a writer reads this value, and the persistence layer
+   * rejects the write if the stored version has moved on in the meantime.
+   */
   get aggregateVersion(): number;
+  /**
+   * The schema/contract version stamped on this entity type by the
+   * `@version` decorator — used to detect and migrate state persisted under
+   * an older shape.
+   */
   get contractVersion(): ContractVersion;
+  /**
+   * The single seam through which an entity records a mutation: it advances
+   * `updatedAt` and bumps {@link aggregateVersion} by one. Subclasses must
+   * call this from every state-changing method so the version counter stays
+   * an accurate optimistic-lock token.
+   *
+   * @param updatedAt - The modification instant; defaults to now. Validated
+   *   and required not to predate `createdAt`, preserving the same invariant
+   *   the constructor enforces.
+   * @returns The new aggregate version after the increment.
+   * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+   */
   protected markAsModified(updatedAt?: Date): number;
 }
 //#endregion
 //#region src/core/domain/value-object.d.ts
+/**
+ * Base class for value objects — domain concepts defined entirely by their
+ * contents, with no identity of their own. Two value objects are
+ * interchangeable when they hold equal data, which is the opposite of an
+ * {@link Entity} (compared by id). Money, a CPF, a date range: replacing one
+ * instance with an equal one changes nothing about the model.
+ *
+ * Immutability is the defining guarantee here. The wrapped `value` is
+ * deep-frozen on construction, so a value object can be shared freely without
+ * any risk of a consumer mutating shared state. Subclasses seal the instance
+ * itself with {@link finalize} once their own fields are set.
+ *
+ * @typeParam T - The shape of the wrapped data.
+ * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
+ */
 declare abstract class ValueObject<T, P> {
   static readonly CONTRACT_VERSION: ContractVersion;
+  /** The wrapped data, deep-frozen so it can never be mutated after construction. */
   readonly value: DeepReadonly<T>;
+  /**
+   * Wraps `value`, deep-freezing it so the value object is immutable from the
+   * moment it exists. Declared `protected` because value objects are built
+   * through a validating subclass factory, never instantiated directly.
+   */
   protected constructor(value: T);
+  /**
+   * The schema/contract version stamped on this value-object type by the
+   * `@version` decorator — used to detect state persisted under an older shape.
+   */
   get contractVersion(): ContractVersion;
+  /**
+   * Freezes the instance shell, blocking reassignment of any own field.
+   *
+   * `value` is already deep-frozen by the constructor, so the wrapped data is
+   * immutable regardless. The instance itself is NOT frozen automatically
+   * because a subclass may still need to assign its own fields after
+   * `super(value)` runs. Call `finalize()` at the very end of the subclass
+   * constructor (after all fields are set) to make the whole value object
+   * immutable.
+   */
   protected finalize(): void;
+  /**
+   * Hook for `JSON.stringify`. Delegates to {@link toPrimitive} so a value
+   * object serializes to its primitive form rather than exposing the internal
+   * `value` wrapper.
+   */
   toJSON(): P;
+  /**
+   * Compares this value object with another by content. Because value objects
+   * carry no identity, subclasses implement equality over the wrapped data
+   * (typically the primitive form), so two independently constructed instances
+   * holding the same data are considered equal.
+   */
   abstract equals(other: this): boolean;
+  /**
+   * Projects the value object down to a plain, serializable primitive form —
+   * the representation suitable for persistence, transport, or comparison.
+   */
   abstract toPrimitive(): P;
 }
 //#endregion
 //#region src/index.d.ts
 declare const ERP_CORE_NAME = "erp-core";
-declare const ERP_CORE_VERSION = "1.0.9";
+declare const ERP_CORE_VERSION = "1.0.11";
 declare const erpCoreRelease: {
   readonly name: "erp-core";
-  readonly version: "1.0.9";
+  readonly version: "1.0.11";
 };
 //#endregion
 export { AlreadyExistsError, AppError, AppErrorOptions, AsOfSource, AuthenticationError, AuthenticationErrorMetadata, AuthenticationErrorReason, AuthorizationError, AuthorizationErrorMetadata, AuthorizationErrorReason, AuthorizationRequirement, BasePolicyDefinitionProps, BusinessRuleViolationError, CommonOutcomeStatus, ComputeEngineRegistry, ComputeEvaluator, ComputeEvaluatorRegistration, ComputeEvaluatorRegistry, ComputeOutcome, ComputeOutcomeData, ComputePayloadParserRegistry, ComputePayloadParsers, ComputePolicyDefinitionProps, ComputeRegistry, ComputeStatus, ConditionEvaluationCause, ConditionEvaluationOptions, ConditionEvaluationReport, ConditionEvaluationReportLevel, ConditionEvaluationReportTag, ConditionEvaluatorReporter, ConflictError, ConflictErrorMetadata, ConflictKind, ContextResolverCircuitBreakerOptions, ContextResolverRegistry, ContextResolverResilienceOptions, ContextResolverRetryOptions, ContextSeed, ContextSeedValidator, ContextValueResolver, CoreConfig, CoreConfigOptions, CoreObservabilityConfig, type DeepReadonly, DeriveAsOfOptions, SerializationInError as DeserializationError, SerializationInError, DuplicateError, ERP_CORE_NAME, ERP_CORE_VERSION, Entity, type EntityState, Err, ErrorCodes, ErrorSeverity, EvaluateInput, ExpiredError, TemporalErrorMetadata as ExpiredErrorMetadata, TemporalErrorMetadata, TemporalPrecision as ExpiredErrorPrecision, TemporalPrecision, FindCandidatesParams, GateEngineRegistry, GateOutcome, GateOutcomeData, GatePayload, GatePayloadParsers, GatePolicyDefinitionProps, GateStatus, GateTraceLeafSnapshot, GateTraceNodeSnapshot, GateViolationTrace, IdempotencyError, IdempotencyErrorMetadata, IdempotencyFailureKind, IdempotencyInProgressError, IdempotencyKeyMissingError, IdempotencyPayloadMismatchError, IdempotencyReplayNotSupportedError, InMemoryPolicyDefinitionRepository, IntegrationError, IntegrationErrorMetadata, IntegrationErrorReason, JsonSafePrimitive, JsonSafeRecord, JsonSafeValue, LegacyIncompatibleError, type LogPayload, type LoggerPort, type MetricLabels, type MetricsPort, NotFoundError, NotYetValidError, Ok, Outcome, PolicyAsOfResolver, PolicyCatalog, PolicyCatalogEntryProps, PolicyCatalogFactory, PolicyContext, PolicyContextBuilder, PolicyContextBuilderOptions, PolicyContextPath, PolicyDecision, PolicyDecisionId, PolicyDefinition, PolicyDefinitionId, PolicyDefinitionProps, PolicyDefinitionStatus, PolicyEvaluationError, PolicyEvaluationErrors, PolicyEvaluationResult, PolicyHashing, PolicyKey, PolicyKind, PolicyOwner, PolicyPackage, PolicyResolver, PolicyScope, PolicyScopeLevel, PolicyScopeMatcher, PolicyService, PolicyServiceOptions, PolicyServiceParams, PolicyViolation, Result, SchoolId, ScopeChain, SerializationBoundary, SerializationCodes, SerializationDirection, SerializationError, SerializationErrorMetadata, SerializationFailureCategory, SerializationMessages, SerializationOutError, TemporalError, TemporalKind, TenantId, type TraceAttributeValue, type TraceSpan, type TracerPort, UnexpectedError, UniqueConstraintViolation, UniqueConstraintViolationError, ValidationError, ValidationField, ValueObject, VersionedComputeEngine, VersionedGateEngine, asPolicyDecisionId, asPolicyDefinitionId, asSchoolId, asTenantId, assertJsonSafeMetadata, contextResolverRegistry, coreConfig, erpCoreRelease, evaluateTemporalWindow, mapPolicyEvaluationError, payloadHash, registerNamespacedContextResolvers, registerNamespacedContextResolversIn, safePreview, serializationErrorCode, sha256Hex, stableStringify, translateUniqueViolationToDuplicate };

package/dist/index.js

@@ -6,7 +6,7 @@ import { t as Outcome } from "./outcome.js";
 import { _ as asPolicyDecisionId, a as ContextSeedValidator, b as asTenantId, c as ContextResolverRegistry, d as PolicyDefinition, f as InMemoryPolicyDefinitionRepository, g as PolicyCatalog, h as PolicyCatalogFactory, i as PolicyAsOfResolver, l as registerNamespacedContextResolversIn, m as PolicyKey, n as PolicyEvaluationErrors, o as contextResolverRegistry, p as PolicyScopeMatcher, r as PolicyResolver, s as registerNamespacedContextResolvers, t as PolicyService, u as PolicyContextBuilder, v as asPolicyDefinitionId, x as PolicyHashing, y as asSchoolId } from "./policy-service.js";
 import { a as ComputeEvaluatorRegistry, c as ComputePayloadParsers, i as ComputeRegistry, o as ComputeEngineRegistry, r as GatePayloadParsers, s as ComputePayloadParserRegistry, t as GateEngineRegistry } from "./gate-engine-registry.js";
 //#region src/version.ts
-const version$1 = "1.0.9";
+const version$1 = "1.0.11";
 //#endregion
 //#region src/core/application/policy-error-mapper.ts
 function mapPolicyEvaluationError(err) {
@@ -65,10 +65,38 @@ function __decorate(decorators, target, key, desc) {
 //#endregion
 //#region src/core/domain/entity.ts
 var _Entity;
+/**
+* Base class for domain entities — objects defined by a stable identity rather
+* than by their attributes. Two entities are "the same" when their `id`
+* matches, even if every other field differs; this is the opposite of a
+* {@link ValueObject}, which is defined entirely by its contents.
+*
+* The class owns the bookkeeping common to every aggregate root: a creation
+* timestamp that never changes, a last-modified timestamp, and an
+* `aggregateVersion` counter used for optimistic concurrency control. All three
+* are validated on construction and the dates are defensively cloned, so an
+* entity can never be built into — or leak — an inconsistent temporal state.
+*
+* @typeParam TIdentifier - The identity type (e.g. a branded string id or a VO).
+*/
 let Entity = class Entity {
 	static {
 		_Entity = this;
 	}
+	/**
+	* Reconstitutes an entity from its persisted {@link EntityState}.
+	*
+	* Validates the temporal invariants up front so an invalid entity is
+	* impossible to construct: both dates must be valid, the aggregate version
+	* must be a non-negative integer, and `updatedAt` may not predate
+	* `createdAt`. Both dates are cloned on the way in so a later mutation of
+	* the caller's `Date` objects cannot reach into the entity's internal state.
+	*
+	* Declared `protected` because entities are reconstituted through a
+	* subclass factory, never instantiated directly by application code.
+	*
+	* @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+	*/
 	constructor(state) {
 		assertValidDate("createdAt", state.createdAt);
 		assertValidDate("updatedAt", state.updatedAt);
@@ -79,21 +107,56 @@ let Entity = class Entity {
 		this._updatedAt = cloneDate(state.updatedAt);
 		this._aggregateVersion = state.aggregateVersion;
 	}
+	/** The entity's stable identity — the basis for equality between entities. */
 	get id() {
 		return this._id;
 	}
+	/**
+	* When the entity was first created.
+	*
+	* Returns a clone so callers cannot mutate the entity's internal `Date`;
+	* the value is fixed at construction and never changes thereafter.
+	*/
 	get createdAt() {
 		return cloneDate(this._createdAt);
 	}
+	/**
+	* When the entity was last modified.
+	*
+	* Returns a clone for the same encapsulation reason as {@link createdAt};
+	* the underlying value advances only through {@link markAsModified}.
+	*/
 	get updatedAt() {
 		return cloneDate(this._updatedAt);
 	}
+	/**
+	* Monotonic counter incremented on every mutation, used for optimistic
+	* concurrency control: a writer reads this value, and the persistence layer
+	* rejects the write if the stored version has moved on in the meantime.
+	*/
 	get aggregateVersion() {
 		return this._aggregateVersion;
 	}
+	/**
+	* The schema/contract version stamped on this entity type by the
+	* `@version` decorator — used to detect and migrate state persisted under
+	* an older shape.
+	*/
 	get contractVersion() {
 		return _Entity.CONTRACT_VERSION;
 	}
+	/**
+	* The single seam through which an entity records a mutation: it advances
+	* `updatedAt` and bumps {@link aggregateVersion} by one. Subclasses must
+	* call this from every state-changing method so the version counter stays
+	* an accurate optimistic-lock token.
+	*
+	* @param updatedAt - The modification instant; defaults to now. Validated
+	*   and required not to predate `createdAt`, preserving the same invariant
+	*   the constructor enforces.
+	* @returns The new aggregate version after the increment.
+	* @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+	*/
 	markAsModified(updatedAt = /* @__PURE__ */ new Date()) {
 		assertValidDate("updatedAt", updatedAt);
 		if (updatedAt.getTime() < this._createdAt.getTime()) throw new InvariantViolationException("updatedAt cannot be earlier than createdAt");
@@ -133,19 +196,58 @@ function makeImmutable(value) {
 //#endregion
 //#region src/core/domain/value-object.ts
 var _ValueObject;
+/**
+* Base class for value objects — domain concepts defined entirely by their
+* contents, with no identity of their own. Two value objects are
+* interchangeable when they hold equal data, which is the opposite of an
+* {@link Entity} (compared by id). Money, a CPF, a date range: replacing one
+* instance with an equal one changes nothing about the model.
+*
+* Immutability is the defining guarantee here. The wrapped `value` is
+* deep-frozen on construction, so a value object can be shared freely without
+* any risk of a consumer mutating shared state. Subclasses seal the instance
+* itself with {@link finalize} once their own fields are set.
+*
+* @typeParam T - The shape of the wrapped data.
+* @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
+*/
 let ValueObject = class ValueObject {
 	static {
 		_ValueObject = this;
 	}
+	/**
+	* Wraps `value`, deep-freezing it so the value object is immutable from the
+	* moment it exists. Declared `protected` because value objects are built
+	* through a validating subclass factory, never instantiated directly.
+	*/
 	constructor(value) {
 		this.value = makeImmutable(value);
 	}
+	/**
+	* The schema/contract version stamped on this value-object type by the
+	* `@version` decorator — used to detect state persisted under an older shape.
+	*/
 	get contractVersion() {
 		return _ValueObject.CONTRACT_VERSION;
 	}
+	/**
+	* Freezes the instance shell, blocking reassignment of any own field.
+	*
+	* `value` is already deep-frozen by the constructor, so the wrapped data is
+	* immutable regardless. The instance itself is NOT frozen automatically
+	* because a subclass may still need to assign its own fields after
+	* `super(value)` runs. Call `finalize()` at the very end of the subclass
+	* constructor (after all fields are set) to make the whole value object
+	* immutable.
+	*/
 	finalize() {
 		Object.freeze(this);
 	}
+	/**
+	* Hook for `JSON.stringify`. Delegates to {@link toPrimitive} so a value
+	* object serializes to its primitive form rather than exposing the internal
+	* `value` wrapper.
+	*/
 	toJSON() {
 		return this.toPrimitive();
 	}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["version","version"],"sources":["../src/version.ts","../src/core/application/policy-error-mapper.ts","../src/core/shared/aggregate-version.ts","../src/core/versioning/version.ts","../src/core/domain/entity.ts","../src/core/shared/immutable.ts","../src/core/domain/value-object.ts","../src/index.ts"],"sourcesContent":["// Versao do kit, sincronizada com package.json por scripts/sync-kit-version.mjs.\n// Nao edite a mao: rode `npm run sync-kit-version` (ou e regenerado no release).\n//\n// Mantemos a versao aqui, dentro de src/, para que a copia full-control seja\n// auto-contida: ao copiar so o conteudo de src/, o entry nao depende de um\n// `../package.json` que deixaria de existir no projeto consumidor.\nexport const version = \"1.0.9\";\n","import {\n    type AppError,\n    BusinessRuleViolationError,\n    NotFoundError,\n    UnexpectedError,\n} from \"../errors/index.js\";\nimport type { PolicyEvaluationError } from \"../policies/index.js\";\n\nexport function mapPolicyEvaluationError(err: PolicyEvaluationError): AppError {\n    switch (err.kind) {\n        case \"INVALID_CONTEXT\":\n            return new BusinessRuleViolationError(\n                `policy.${err.stage.toLowerCase()}`,\n                err.message,\n                { policyKey: err.policyKey, stage: err.stage },\n                { cause: err.cause },\n            );\n        case \"INVALID_POLICY_KEY\":\n            return new BusinessRuleViolationError(\n                \"policy.invalid_key\",\n                err.message,\n                { rawPolicyKey: err.rawPolicyKey },\n                { cause: err.cause },\n            );\n        case \"POLICY_NOT_FOUND\":\n            return new NotFoundError(\n                \"Policy\",\n                { policyKey: err.policyKey },\n                { cause: err.cause },\n            );\n        case \"POLICY_DEFINITION_NOT_FOUND\":\n            return new NotFoundError(\n                \"PolicyDefinition\",\n                {\n                    policyKey: err.policyKey,\n                    contextVersion: err.contextVersion,\n                    asOf: err.asOf.toISOString(),\n                },\n                { cause: err.cause },\n            );\n        case \"POLICY_VARIANT_NOT_FOUND\":\n            return new NotFoundError(\n                \"PolicyVariant\",\n                {\n                    policyKey: err.policyKey,\n                    policyKind: err.policyKind,\n                    payloadSchemaVersion: err.payloadSchemaVersion,\n                },\n                { cause: err.cause },\n            );\n        case \"ENGINE_FAILURE\":\n            return new UnexpectedError(err.message, err.cause, {\n                metadata: {\n                    policyKey: err.policyKey,\n                    engine: err.engine,\n                    engineVersion: err.engineVersion,\n                },\n            });\n    }\n}\n","import { InvariantViolationException } from \"../exceptions/invariant-violation-exception.js\";\n\nfunction assertValidAggregateVersion(aggregateVersion: number): void {\n    if (!Number.isInteger(aggregateVersion) || aggregateVersion < 0) {\n        throw new InvariantViolationException(\n            `aggregateVersion must be a non-negative integer. Received: ${aggregateVersion}`,\n        );\n    }\n}\n\nexport { assertValidAggregateVersion };\n","type ContractVersion = `${number}.${number}`;\n\ntype VersionedTarget = {\n    readonly prototype: object;\n};\n\nconst CONTRACT_VERSION_PROPERTY = \"CONTRACT_VERSION\" as const;\nconst CONTRACT_VERSION_PATTERN = /^\\d+\\.\\d+$/;\n\nfunction version<const TVersion extends ContractVersion>(\n    contractVersion: TVersion,\n) {\n    if (!CONTRACT_VERSION_PATTERN.test(contractVersion)) {\n        throw new TypeError(\n            `Invalid contract version \"${contractVersion}\". Expected MAJOR.MINOR.`,\n        );\n    }\n\n    return (target: VersionedTarget): void => {\n        Object.defineProperty(target, CONTRACT_VERSION_PROPERTY, {\n            value: contractVersion,\n            writable: false,\n            configurable: false,\n            enumerable: false,\n        });\n    };\n}\n\nexport {\n    CONTRACT_VERSION_PROPERTY,\n    type ContractVersion,\n    version,\n    type VersionedTarget,\n};\n","import { InvariantViolationException } from \"../exceptions/invariant-violation-exception.js\";\nimport { assertValidAggregateVersion } from \"../shared/aggregate-version.js\";\nimport { assertValidDate, cloneDate } from \"../shared/temporal-guards.js\";\nimport { type ContractVersion, version } from \"../versioning/version.js\";\n\ninterface EntityState<TIdentifier> {\n    readonly id: TIdentifier;\n    readonly createdAt: Date;\n    readonly updatedAt: Date;\n    readonly aggregateVersion: number;\n}\n\n@version(\"1.0\")\nabstract class Entity<TIdentifier> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    private readonly _id: TIdentifier;\n    private readonly _createdAt: Date;\n    private _updatedAt: Date;\n    private _aggregateVersion: number;\n\n    protected constructor(state: EntityState<TIdentifier>) {\n        assertValidDate(\"createdAt\", state.createdAt);\n        assertValidDate(\"updatedAt\", state.updatedAt);\n        assertValidAggregateVersion(state.aggregateVersion);\n\n        if (state.updatedAt.getTime() < state.createdAt.getTime()) {\n            throw new InvariantViolationException(\n                \"updatedAt cannot be earlier than createdAt\",\n            );\n        }\n\n        this._id = state.id;\n        this._createdAt = cloneDate(state.createdAt);\n        this._updatedAt = cloneDate(state.updatedAt);\n        this._aggregateVersion = state.aggregateVersion;\n    }\n\n    public get id(): TIdentifier {\n        return this._id;\n    }\n\n    public get createdAt(): Date {\n        return cloneDate(this._createdAt);\n    }\n\n    public get updatedAt(): Date {\n        return cloneDate(this._updatedAt);\n    }\n\n    public get aggregateVersion(): number {\n        return this._aggregateVersion;\n    }\n\n    public get contractVersion(): ContractVersion {\n        return Entity.CONTRACT_VERSION;\n    }\n\n    protected markAsModified(updatedAt: Date = new Date()): number {\n        assertValidDate(\"updatedAt\", updatedAt);\n\n        if (updatedAt.getTime() < this._createdAt.getTime()) {\n            throw new InvariantViolationException(\n                \"updatedAt cannot be earlier than createdAt\",\n            );\n        }\n\n        this._updatedAt = cloneDate(updatedAt);\n        this._aggregateVersion += 1;\n\n        return this._aggregateVersion;\n    }\n}\n\nexport { Entity, type EntityState };\n","import { InvariantViolationException } from \"../exceptions/invariant-violation-exception.js\";\n\ntype PrimitiveValue =\n    | bigint\n    | boolean\n    | null\n    | number\n    | string\n    | symbol\n    | undefined;\n\ntype DeepReadonly<T> = T extends PrimitiveValue | Date\n    ? T\n    : T extends readonly (infer TItem)[]\n      ? readonly DeepReadonly<TItem>[]\n      : { readonly [TKey in keyof T]: DeepReadonly<T[TKey]> };\n\nfunction deepFreeze<T>(value: T): T {\n    return deepFreezeInternal(value, new WeakSet<object>());\n}\n\nfunction deepFreezeInternal<T>(value: T, seen: WeakSet<object>): T {\n    // Primitives and `null` need no freezing. `Date` is intentionally returned\n    // as-is: `Object.freeze` cannot stop a Date's mutators (`setTime`,\n    // `setFullYear`, …) because they write an internal slot, not an own\n    // property — freezing it is a no-op against mutation. `makeImmutable`\n    // already hands us a `structuredClone` copy, so the caller's original Date\n    // is never aliased; deep-freezing of nested Dates is deliberately skipped.\n    if (typeof value !== \"object\" || value === null || value instanceof Date) {\n        return value;\n    }\n\n    // A value already on `seen` has been visited on this pass (cyclic graph or a\n    // shared reference); revisiting it would recurse forever.\n    if (seen.has(value)) {\n        return value;\n    }\n    seen.add(value);\n\n    if (Array.isArray(value)) {\n        for (const item of value) {\n            deepFreezeInternal(item, seen);\n        }\n\n        return Object.freeze(value);\n    }\n\n    const objectValue = value as Record<PropertyKey, object | PrimitiveValue>;\n\n    for (const propertyKey of Reflect.ownKeys(objectValue)) {\n        deepFreezeInternal(objectValue[propertyKey], seen);\n    }\n\n    return Object.freeze(value);\n}\n\nfunction makeImmutable<T>(value: T): DeepReadonly<T> {\n    if (typeof value !== \"object\" || value === null) {\n        return value as DeepReadonly<T>;\n    }\n\n    let snapshot: T;\n    try {\n        snapshot = structuredClone(value);\n    } catch (error) {\n        // `structuredClone` throws `DataCloneError` for functions, symbols and\n        // class instances. Surface it as a domain invariant instead of leaking\n        // a host-specific runtime error to callers building value objects.\n        throw new InvariantViolationException(\n            `makeImmutable requires a structured-cloneable value: ${\n                error instanceof Error ? error.message : String(error)\n            }`,\n        );\n    }\n\n    return deepFreeze(snapshot) as DeepReadonly<T>;\n}\n\nexport { deepFreeze, makeImmutable, type DeepReadonly };\n","import { type DeepReadonly, makeImmutable } from \"../shared/immutable.js\";\nimport { type ContractVersion, version } from \"../versioning/version.js\";\n\n@version(\"1.0\")\nabstract class ValueObject<T, P> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n    public readonly value: DeepReadonly<T>;\n\n    protected constructor(value: T) {\n        this.value = makeImmutable(value);\n    }\n\n    public get contractVersion(): ContractVersion {\n        return ValueObject.CONTRACT_VERSION;\n    }\n\n    protected finalize(): void {\n        Object.freeze(this);\n    }\n\n    public toJSON(): P {\n        return this.toPrimitive();\n    }\n\n    public abstract equals(other: this): boolean;\n\n    public abstract toPrimitive(): P;\n}\n\nexport { type DeepReadonly, ValueObject };\n","import { version } from \"./version.js\";\n\nexport * from \"./core/index.js\";\n\nexport const ERP_CORE_NAME = \"erp-core\";\nexport const ERP_CORE_VERSION = version;\n\nexport const erpCoreRelease = {\n    name: ERP_CORE_NAME,\n    version: ERP_CORE_VERSION,\n} as const;\n"],"mappings":";;;;;;;;AAMA,MAAaA,YAAU;;;ACEvB,SAAgB,yBAAyB,KAAsC;CAC3E,QAAQ,IAAI,MAAZ;EACI,KAAK,mBACD,OAAO,IAAI,2BACP,UAAU,IAAI,MAAM,YAAY,KAChC,IAAI,SACJ;GAAE,WAAW,IAAI;GAAW,OAAO,IAAI;EAAM,GAC7C,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,sBACD,OAAO,IAAI,2BACP,sBACA,IAAI,SACJ,EAAE,cAAc,IAAI,aAAa,GACjC,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,oBACD,OAAO,IAAI,cACP,UACA,EAAE,WAAW,IAAI,UAAU,GAC3B,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,+BACD,OAAO,IAAI,cACP,oBACA;GACI,WAAW,IAAI;GACf,gBAAgB,IAAI;GACpB,MAAM,IAAI,KAAK,YAAY;EAC/B,GACA,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,4BACD,OAAO,IAAI,cACP,iBACA;GACI,WAAW,IAAI;GACf,YAAY,IAAI;GAChB,sBAAsB,IAAI;EAC9B,GACA,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,kBACD,OAAO,IAAI,gBAAgB,IAAI,SAAS,IAAI,OAAO,EAC/C,UAAU;GACN,WAAW,IAAI;GACf,QAAQ,IAAI;GACZ,eAAe,IAAI;EACvB,EACJ,CAAC;CACT;AACJ;;;ACzDA,SAAS,4BAA4B,kBAAgC;CACjE,IAAI,CAAC,OAAO,UAAU,gBAAgB,KAAK,mBAAmB,GAC1D,MAAM,IAAI,4BACN,8DAA8D,kBAClE;AAER;;;ACFA,MAAM,4BAA4B;AAClC,MAAM,2BAA2B;AAEjC,SAAS,QACL,iBACF;CACE,IAAI,CAAC,yBAAyB,KAAK,eAAe,GAC9C,MAAM,IAAI,UACN,6BAA6B,gBAAgB,yBACjD;CAGJ,QAAQ,WAAkC;EACtC,OAAO,eAAe,QAAQ,2BAA2B;GACrD,OAAO;GACP,UAAU;GACV,cAAc;GACd,YAAY;EAChB,CAAC;CACL;AACJ;;;;;;;;;;;;ACdA,IAAA,SAAA,MACe,OAAoB;;;;CAQ/B,YAAsB,OAAiC;EACnD,gBAAgB,aAAa,MAAM,SAAS;EAC5C,gBAAgB,aAAa,MAAM,SAAS;EAC5C,4BAA4B,MAAM,gBAAgB;EAElD,IAAI,MAAM,UAAU,QAAQ,IAAI,MAAM,UAAU,QAAQ,GACpD,MAAM,IAAI,4BACN,4CACJ;EAGJ,KAAK,MAAM,MAAM;EACjB,KAAK,aAAa,UAAU,MAAM,SAAS;EAC3C,KAAK,aAAa,UAAU,MAAM,SAAS;EAC3C,KAAK,oBAAoB,MAAM;CACnC;CAEA,IAAW,KAAkB;EACzB,OAAO,KAAK;CAChB;CAEA,IAAW,YAAkB;EACzB,OAAO,UAAU,KAAK,UAAU;CACpC;CAEA,IAAW,YAAkB;EACzB,OAAO,UAAU,KAAK,UAAU;CACpC;CAEA,IAAW,mBAA2B;EAClC,OAAO,KAAK;CAChB;CAEA,IAAW,kBAAmC;EAC1C,OAAA,QAAc;CAClB;CAEA,eAAyB,4BAAkB,IAAI,KAAK,GAAW;EAC3D,gBAAgB,aAAa,SAAS;EAEtC,IAAI,UAAU,QAAQ,IAAI,KAAK,WAAW,QAAQ,GAC9C,MAAM,IAAI,4BACN,4CACJ;EAGJ,KAAK,aAAa,UAAU,SAAS;EACrC,KAAK,qBAAqB;EAE1B,OAAO,KAAK;CAChB;AACJ;+BA5DC,QAAQ,KAAK,CAAA,GAAA,MAAA;;;ACKd,SAAS,WAAc,OAAa;CAChC,OAAO,mBAAmB,uBAAO,IAAI,QAAgB,CAAC;AAC1D;AAEA,SAAS,mBAAsB,OAAU,MAA0B;CAO/D,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,iBAAiB,MAChE,OAAO;CAKX,IAAI,KAAK,IAAI,KAAK,GACd,OAAO;CAEX,KAAK,IAAI,KAAK;CAEd,IAAI,MAAM,QAAQ,KAAK,GAAG;EACtB,KAAK,MAAM,QAAQ,OACf,mBAAmB,MAAM,IAAI;EAGjC,OAAO,OAAO,OAAO,KAAK;CAC9B;CAEA,MAAM,cAAc;CAEpB,KAAK,MAAM,eAAe,QAAQ,QAAQ,WAAW,GACjD,mBAAmB,YAAY,cAAc,IAAI;CAGrD,OAAO,OAAO,OAAO,KAAK;AAC9B;AAEA,SAAS,cAAiB,OAA2B;CACjD,IAAI,OAAO,UAAU,YAAY,UAAU,MACvC,OAAO;CAGX,IAAI;CACJ,IAAI;EACA,WAAW,gBAAgB,KAAK;CACpC,SAAS,OAAO;EAIZ,MAAM,IAAI,4BACN,wDACI,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAE7D;CACJ;CAEA,OAAO,WAAW,QAAQ;AAC9B;;;;ACzEA,IAAA,cAAA,MACe,YAAkB;;;;CAI7B,YAAsB,OAAU;EAC5B,KAAK,QAAQ,cAAc,KAAK;CACpC;CAEA,IAAW,kBAAmC;EAC1C,OAAA,aAAmB;CACvB;CAEA,WAA2B;EACvB,OAAO,OAAO,IAAI;CACtB;CAEA,SAAmB;EACf,OAAO,KAAK,YAAY;CAC5B;AAKJ;yCAxBC,QAAQ,KAAK,CAAA,GAAA,WAAA;;;ACCd,MAAa,gBAAgB;AAC7B,MAAa,mBAAmBC;AAEhC,MAAa,iBAAiB;CAC1B,MAAM;CACN,SAAS;AACb"}
+{"version":3,"file":"index.js","names":["version","version"],"sources":["../src/version.ts","../src/core/application/policy-error-mapper.ts","../src/core/shared/aggregate-version.ts","../src/core/versioning/version.ts","../src/core/domain/entity.ts","../src/core/shared/immutable.ts","../src/core/domain/value-object.ts","../src/index.ts"],"sourcesContent":["// Versao do kit, sincronizada com package.json por scripts/sync-kit-version.mjs.\n// Nao edite a mao: rode `npm run sync-kit-version` (ou e regenerado no release).\n//\n// Mantemos a versao aqui, dentro de src/, para que a copia full-control seja\n// auto-contida: ao copiar so o conteudo de src/, o entry nao depende de um\n// `../package.json` que deixaria de existir no projeto consumidor.\nexport const version = \"1.0.11\";\n","import {\n    type AppError,\n    BusinessRuleViolationError,\n    NotFoundError,\n    UnexpectedError,\n} from \"../errors/index.js\";\nimport type { PolicyEvaluationError } from \"../policies/index.js\";\n\nexport function mapPolicyEvaluationError(err: PolicyEvaluationError): AppError {\n    switch (err.kind) {\n        case \"INVALID_CONTEXT\":\n            return new BusinessRuleViolationError(\n                `policy.${err.stage.toLowerCase()}`,\n                err.message,\n                { policyKey: err.policyKey, stage: err.stage },\n                { cause: err.cause },\n            );\n        case \"INVALID_POLICY_KEY\":\n            return new BusinessRuleViolationError(\n                \"policy.invalid_key\",\n                err.message,\n                { rawPolicyKey: err.rawPolicyKey },\n                { cause: err.cause },\n            );\n        case \"POLICY_NOT_FOUND\":\n            return new NotFoundError(\n                \"Policy\",\n                { policyKey: err.policyKey },\n                { cause: err.cause },\n            );\n        case \"POLICY_DEFINITION_NOT_FOUND\":\n            return new NotFoundError(\n                \"PolicyDefinition\",\n                {\n                    policyKey: err.policyKey,\n                    contextVersion: err.contextVersion,\n                    asOf: err.asOf.toISOString(),\n                },\n                { cause: err.cause },\n            );\n        case \"POLICY_VARIANT_NOT_FOUND\":\n            return new NotFoundError(\n                \"PolicyVariant\",\n                {\n                    policyKey: err.policyKey,\n                    policyKind: err.policyKind,\n                    payloadSchemaVersion: err.payloadSchemaVersion,\n                },\n                { cause: err.cause },\n            );\n        case \"ENGINE_FAILURE\":\n            return new UnexpectedError(err.message, err.cause, {\n                metadata: {\n                    policyKey: err.policyKey,\n                    engine: err.engine,\n                    engineVersion: err.engineVersion,\n                },\n            });\n    }\n}\n","import { InvariantViolationException } from \"../exceptions/invariant-violation-exception.js\";\n\nfunction assertValidAggregateVersion(aggregateVersion: number): void {\n    if (!Number.isInteger(aggregateVersion) || aggregateVersion < 0) {\n        throw new InvariantViolationException(\n            `aggregateVersion must be a non-negative integer. Received: ${aggregateVersion}`,\n        );\n    }\n}\n\nexport { assertValidAggregateVersion };\n","type ContractVersion = `${number}.${number}`;\n\ntype VersionedTarget = {\n    readonly prototype: object;\n};\n\nconst CONTRACT_VERSION_PROPERTY = \"CONTRACT_VERSION\" as const;\nconst CONTRACT_VERSION_PATTERN = /^\\d+\\.\\d+$/;\n\nfunction version<const TVersion extends ContractVersion>(\n    contractVersion: TVersion,\n) {\n    if (!CONTRACT_VERSION_PATTERN.test(contractVersion)) {\n        throw new TypeError(\n            `Invalid contract version \"${contractVersion}\". Expected MAJOR.MINOR.`,\n        );\n    }\n\n    return (target: VersionedTarget): void => {\n        Object.defineProperty(target, CONTRACT_VERSION_PROPERTY, {\n            value: contractVersion,\n            writable: false,\n            configurable: false,\n            enumerable: false,\n        });\n    };\n}\n\nexport {\n    CONTRACT_VERSION_PROPERTY,\n    type ContractVersion,\n    version,\n    type VersionedTarget,\n};\n","import { InvariantViolationException } from \"../exceptions/invariant-violation-exception.js\";\nimport { assertValidAggregateVersion } from \"../shared/aggregate-version.js\";\nimport { assertValidDate, cloneDate } from \"../shared/temporal-guards.js\";\nimport { type ContractVersion, version } from \"../versioning/version.js\";\n\n/**\n * The minimal persisted shape needed to reconstitute an {@link Entity}.\n *\n * This is the contract between storage and the domain: a repository maps a row\n * (or document) onto these four fields and hands them to a subclass constructor.\n * `aggregateVersion` travels with the state so optimistic-concurrency checks\n * survive a round-trip through the database.\n */\ninterface EntityState<TIdentifier> {\n    readonly id: TIdentifier;\n    readonly createdAt: Date;\n    readonly updatedAt: Date;\n    readonly aggregateVersion: number;\n}\n\n/**\n * Base class for domain entities — objects defined by a stable identity rather\n * than by their attributes. Two entities are \"the same\" when their `id`\n * matches, even if every other field differs; this is the opposite of a\n * {@link ValueObject}, which is defined entirely by its contents.\n *\n * The class owns the bookkeeping common to every aggregate root: a creation\n * timestamp that never changes, a last-modified timestamp, and an\n * `aggregateVersion` counter used for optimistic concurrency control. All three\n * are validated on construction and the dates are defensively cloned, so an\n * entity can never be built into — or leak — an inconsistent temporal state.\n *\n * @typeParam TIdentifier - The identity type (e.g. a branded string id or a VO).\n */\n@version(\"1.0\")\nabstract class Entity<TIdentifier> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    private readonly _id: TIdentifier;\n    private readonly _createdAt: Date;\n    private _updatedAt: Date;\n    private _aggregateVersion: number;\n\n    /**\n     * Reconstitutes an entity from its persisted {@link EntityState}.\n     *\n     * Validates the temporal invariants up front so an invalid entity is\n     * impossible to construct: both dates must be valid, the aggregate version\n     * must be a non-negative integer, and `updatedAt` may not predate\n     * `createdAt`. Both dates are cloned on the way in so a later mutation of\n     * the caller's `Date` objects cannot reach into the entity's internal state.\n     *\n     * Declared `protected` because entities are reconstituted through a\n     * subclass factory, never instantiated directly by application code.\n     *\n     * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.\n     */\n    protected constructor(state: EntityState<TIdentifier>) {\n        assertValidDate(\"createdAt\", state.createdAt);\n        assertValidDate(\"updatedAt\", state.updatedAt);\n        assertValidAggregateVersion(state.aggregateVersion);\n\n        if (state.updatedAt.getTime() < state.createdAt.getTime()) {\n            throw new InvariantViolationException(\n                \"updatedAt cannot be earlier than createdAt\",\n            );\n        }\n\n        this._id = state.id;\n        this._createdAt = cloneDate(state.createdAt);\n        this._updatedAt = cloneDate(state.updatedAt);\n        this._aggregateVersion = state.aggregateVersion;\n    }\n\n    /** The entity's stable identity — the basis for equality between entities. */\n    public get id(): TIdentifier {\n        return this._id;\n    }\n\n    /**\n     * When the entity was first created.\n     *\n     * Returns a clone so callers cannot mutate the entity's internal `Date`;\n     * the value is fixed at construction and never changes thereafter.\n     */\n    public get createdAt(): Date {\n        return cloneDate(this._createdAt);\n    }\n\n    /**\n     * When the entity was last modified.\n     *\n     * Returns a clone for the same encapsulation reason as {@link createdAt};\n     * the underlying value advances only through {@link markAsModified}.\n     */\n    public get updatedAt(): Date {\n        return cloneDate(this._updatedAt);\n    }\n\n    /**\n     * Monotonic counter incremented on every mutation, used for optimistic\n     * concurrency control: a writer reads this value, and the persistence layer\n     * rejects the write if the stored version has moved on in the meantime.\n     */\n    public get aggregateVersion(): number {\n        return this._aggregateVersion;\n    }\n\n    /**\n     * The schema/contract version stamped on this entity type by the\n     * `@version` decorator — used to detect and migrate state persisted under\n     * an older shape.\n     */\n    public get contractVersion(): ContractVersion {\n        return Entity.CONTRACT_VERSION;\n    }\n\n    /**\n     * The single seam through which an entity records a mutation: it advances\n     * `updatedAt` and bumps {@link aggregateVersion} by one. Subclasses must\n     * call this from every state-changing method so the version counter stays\n     * an accurate optimistic-lock token.\n     *\n     * @param updatedAt - The modification instant; defaults to now. Validated\n     *   and required not to predate `createdAt`, preserving the same invariant\n     *   the constructor enforces.\n     * @returns The new aggregate version after the increment.\n     * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.\n     */\n    protected markAsModified(updatedAt: Date = new Date()): number {\n        assertValidDate(\"updatedAt\", updatedAt);\n\n        if (updatedAt.getTime() < this._createdAt.getTime()) {\n            throw new InvariantViolationException(\n                \"updatedAt cannot be earlier than createdAt\",\n            );\n        }\n\n        this._updatedAt = cloneDate(updatedAt);\n        this._aggregateVersion += 1;\n\n        return this._aggregateVersion;\n    }\n}\n\nexport { Entity, type EntityState };\n","import { InvariantViolationException } from \"../exceptions/invariant-violation-exception.js\";\n\ntype PrimitiveValue =\n    | bigint\n    | boolean\n    | null\n    | number\n    | string\n    | symbol\n    | undefined;\n\ntype DeepReadonly<T> = T extends PrimitiveValue | Date\n    ? T\n    : T extends readonly (infer TItem)[]\n      ? readonly DeepReadonly<TItem>[]\n      : { readonly [TKey in keyof T]: DeepReadonly<T[TKey]> };\n\nfunction deepFreeze<T>(value: T): T {\n    return deepFreezeInternal(value, new WeakSet<object>());\n}\n\nfunction deepFreezeInternal<T>(value: T, seen: WeakSet<object>): T {\n    // Primitives and `null` need no freezing. `Date` is intentionally returned\n    // as-is: `Object.freeze` cannot stop a Date's mutators (`setTime`,\n    // `setFullYear`, …) because they write an internal slot, not an own\n    // property — freezing it is a no-op against mutation. `makeImmutable`\n    // already hands us a `structuredClone` copy, so the caller's original Date\n    // is never aliased; deep-freezing of nested Dates is deliberately skipped.\n    if (typeof value !== \"object\" || value === null || value instanceof Date) {\n        return value;\n    }\n\n    // A value already on `seen` has been visited on this pass (cyclic graph or a\n    // shared reference); revisiting it would recurse forever.\n    if (seen.has(value)) {\n        return value;\n    }\n    seen.add(value);\n\n    if (Array.isArray(value)) {\n        for (const item of value) {\n            deepFreezeInternal(item, seen);\n        }\n\n        return Object.freeze(value);\n    }\n\n    const objectValue = value as Record<PropertyKey, object | PrimitiveValue>;\n\n    for (const propertyKey of Reflect.ownKeys(objectValue)) {\n        deepFreezeInternal(objectValue[propertyKey], seen);\n    }\n\n    return Object.freeze(value);\n}\n\nfunction makeImmutable<T>(value: T): DeepReadonly<T> {\n    if (typeof value !== \"object\" || value === null) {\n        return value as DeepReadonly<T>;\n    }\n\n    let snapshot: T;\n    try {\n        snapshot = structuredClone(value);\n    } catch (error) {\n        // `structuredClone` throws `DataCloneError` for functions, symbols and\n        // class instances. Surface it as a domain invariant instead of leaking\n        // a host-specific runtime error to callers building value objects.\n        throw new InvariantViolationException(\n            `makeImmutable requires a structured-cloneable value: ${\n                error instanceof Error ? error.message : String(error)\n            }`,\n        );\n    }\n\n    return deepFreeze(snapshot) as DeepReadonly<T>;\n}\n\nexport { deepFreeze, makeImmutable, type DeepReadonly };\n","import { type DeepReadonly, makeImmutable } from \"../shared/immutable.js\";\nimport { type ContractVersion, version } from \"../versioning/version.js\";\n\n/**\n * Base class for value objects — domain concepts defined entirely by their\n * contents, with no identity of their own. Two value objects are\n * interchangeable when they hold equal data, which is the opposite of an\n * {@link Entity} (compared by id). Money, a CPF, a date range: replacing one\n * instance with an equal one changes nothing about the model.\n *\n * Immutability is the defining guarantee here. The wrapped `value` is\n * deep-frozen on construction, so a value object can be shared freely without\n * any risk of a consumer mutating shared state. Subclasses seal the instance\n * itself with {@link finalize} once their own fields are set.\n *\n * @typeParam T - The shape of the wrapped data.\n * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.\n */\n@version(\"1.0\")\nabstract class ValueObject<T, P> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    /** The wrapped data, deep-frozen so it can never be mutated after construction. */\n    public readonly value: DeepReadonly<T>;\n\n    /**\n     * Wraps `value`, deep-freezing it so the value object is immutable from the\n     * moment it exists. Declared `protected` because value objects are built\n     * through a validating subclass factory, never instantiated directly.\n     */\n    protected constructor(value: T) {\n        this.value = makeImmutable(value);\n    }\n\n    /**\n     * The schema/contract version stamped on this value-object type by the\n     * `@version` decorator — used to detect state persisted under an older shape.\n     */\n    public get contractVersion(): ContractVersion {\n        return ValueObject.CONTRACT_VERSION;\n    }\n\n    /**\n     * Freezes the instance shell, blocking reassignment of any own field.\n     *\n     * `value` is already deep-frozen by the constructor, so the wrapped data is\n     * immutable regardless. The instance itself is NOT frozen automatically\n     * because a subclass may still need to assign its own fields after\n     * `super(value)` runs. Call `finalize()` at the very end of the subclass\n     * constructor (after all fields are set) to make the whole value object\n     * immutable.\n     */\n    protected finalize(): void {\n        Object.freeze(this);\n    }\n\n    /**\n     * Hook for `JSON.stringify`. Delegates to {@link toPrimitive} so a value\n     * object serializes to its primitive form rather than exposing the internal\n     * `value` wrapper.\n     */\n    public toJSON(): P {\n        return this.toPrimitive();\n    }\n\n    /**\n     * Compares this value object with another by content. Because value objects\n     * carry no identity, subclasses implement equality over the wrapped data\n     * (typically the primitive form), so two independently constructed instances\n     * holding the same data are considered equal.\n     */\n    public abstract equals(other: this): boolean;\n\n    /**\n     * Projects the value object down to a plain, serializable primitive form —\n     * the representation suitable for persistence, transport, or comparison.\n     */\n    public abstract toPrimitive(): P;\n}\n\nexport { type DeepReadonly, ValueObject };\n","import { version } from \"./version.js\";\n\nexport * from \"./core/index.js\";\n\nexport const ERP_CORE_NAME = \"erp-core\";\nexport const ERP_CORE_VERSION = version;\n\nexport const erpCoreRelease = {\n    name: ERP_CORE_NAME,\n    version: ERP_CORE_VERSION,\n} as const;\n"],"mappings":"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"}

package/dist/policy-service.d.ts

@@ -116,9 +116,43 @@ declare class PolicyCatalogEntry {
 declare class PolicyCatalog {
   private readonly versionedEntries;
   private readonly entriesByKey;
+  /**
+   * Indexes the given entries up front into two lookups — one per exact
+   * variant, one per policy key (the "family") — and validates them eagerly:
+   * a duplicate variant or an internally inconsistent family throws here, at
+   * wiring time, so a malformed catalog fails fast at startup rather than on
+   * the first evaluation.
+   *
+   * @throws {UnexpectedError} When two entries resolve to the same variant key.
+   */
   constructor(entries: readonly PolicyCatalogEntry[]);
+  /**
+   * Returns the single entry for a key. Deliberately strict: if the key has
+   * more than one variant it errs rather than guessing, steering the caller to
+   * {@link getVersioned} or {@link getFamily}. Use this only when a key is
+   * known to be unambiguous.
+   *
+   * @returns `ok` with the entry, or `err` when the key is unknown or ambiguous.
+   */
   get(key: string): Result<PolicyCatalogEntry, string>;
+  /**
+   * Returns every variant registered under a key — the whole "family". This is
+   * the lookup the evaluation pipeline uses, since a single key may host
+   * several engine/schema variants that the resolver then chooses between.
+   *
+   * @returns `ok` with the family (always non-empty), or `err` when the key is unknown.
+   */
   getFamily(key: string): Result<readonly PolicyCatalogEntry[], string>;
+  /**
+   * Resolves the one entry matching an exact variant — kind plus engine and
+   * payload-schema versions. Falls back to the sole family member when a key
+   * has exactly one entry and that entry declares no explicit version
+   * selector, so unversioned single-variant policies "just work" without the
+   * caller spelling out versions.
+   *
+   * @param params - The key and the variant coordinates to match on.
+   * @returns `ok` with the matching entry, or `err` when no variant matches.
+   */
   getVersioned(params: {
     readonly key: string;
     readonly kind: "GATE" | "COMPUTE";
@@ -126,7 +160,9 @@ declare class PolicyCatalog {
     readonly computeEngineVersion?: number;
     readonly payloadSchemaVersion?: number;
   }): Result<PolicyCatalogEntry, string>;
+  /** Lists every registered variant across all keys — useful for introspection and diagnostics. */
   list(): readonly PolicyCatalogEntry[];
+  /** Returns whether any variant is registered under the given key. */
   has(key: string): boolean;
 }
 //#endregion
@@ -422,6 +458,16 @@ declare class PolicyAsOfResolver {
  *   5. policyVersion descending (semver — final deterministic tiebreaker)
  */
 declare class PolicyResolver {
+  /**
+   * Picks the single winning definition from an already-filtered candidate
+   * list by applying the class's ordering criteria in priority order. The sort
+   * runs over a copy, so the caller's array is left untouched, and the final
+   * semver tiebreaker guarantees the winner is fully deterministic — it never
+   * depends on the order the repository returned the candidates in.
+   *
+   * @param candidates - Definitions already filtered to match key, scope, and as-of.
+   * @returns `ok` with the highest-ranked definition, or `err` when the list is empty.
+   */
   resolveBest(candidates: readonly PolicyDefinition[]): Result<PolicyDefinition, string>;
 }
 //#endregion
@@ -485,6 +531,13 @@ declare class PolicyEvaluationErrors {
 }
 //#endregion
 //#region src/core/policies/service/policy-service.d.ts
+/**
+ * Everything a single policy evaluation needs. `policyKey` names the policy,
+ * `scopeChain` narrows the search from most-specific to least-specific scope,
+ * `contextVersion` pins which context schema applies, and `seed` carries the
+ * raw facts the context builder expands. `decisionId` is the caller's
+ * idempotency/audit handle, echoed back on the result.
+ */
 interface EvaluateInput {
   readonly decisionId: PolicyDecisionId;
   readonly policyKey: string;
@@ -492,10 +545,22 @@ interface EvaluateInput {
   readonly contextVersion: number;
   readonly seed: ContextSeed;
 }
+/**
+ * Cross-cutting knobs for a {@link PolicyService}: how the as-of instant is
+ * derived ({@link asOf}) and where evaluation telemetry is sent
+ * ({@link reporter}). Both are optional; the service defaults to a silent
+ * reporter so telemetry is opt-in.
+ */
 interface PolicyServiceOptions {
   readonly asOf?: DeriveAsOfOptions;
   readonly reporter?: PolicyReporter;
 }
+/**
+ * The collaborators a {@link PolicyService} is wired with. Each is an injected
+ * port so the service stays storage- and engine-agnostic: the catalog defines
+ * the universe of policies, `defRepo` supplies their versioned definitions, the
+ * `resolver` picks the winning definition, and the engine registries execute it.
+ */
 interface PolicyServiceParams {
   readonly catalog: PolicyCatalog;
   readonly contextBuilder: PolicyContextBuilder;
@@ -507,6 +572,13 @@ interface PolicyServiceParams {
 }
 /** Union of all possible policy decision Outcomes. */
 type PolicyDecision = GateOutcome | ComputeOutcome;
+/**
+ * The full record of one successful evaluation. Beyond the business
+ * {@link decision}, it pins the exact definition that produced it — id, key,
+ * version, payload hash, and engine version — together with the `asOf` instant
+ * the policy was selected for and the wall-clock `evaluatedAt`. That provenance
+ * is what makes a decision reproducible and auditable after the fact.
+ */
 interface PolicyEvaluationResult {
   readonly decisionId: PolicyDecisionId;
   readonly ref: {
@@ -524,6 +596,18 @@ interface PolicyEvaluationResult {
   /** Business decision expressed as an Outcome — not a technical Result. */
   readonly decision: PolicyDecision;
 }
+/**
+ * Orchestrates the end-to-end evaluation of a policy: it parses and validates
+ * the context seed, derives the as-of instant, resolves the best matching
+ * definition for the requested key/scope/version, builds the context the policy
+ * needs, and runs it through the right engine (gate or compute).
+ *
+ * The service never throws for an expected failure: every step returns a
+ * {@link Result}, and the failures are folded into a typed
+ * {@link PolicyEvaluationError} so callers branch on `isErr()` rather than
+ * catching. Telemetry is best-effort — a throwing reporter can never abort an
+ * evaluation — which keeps observability strictly side-band.
+ */
 declare class PolicyService {
   #private;
   private readonly catalog;
@@ -535,6 +619,21 @@ declare class PolicyService {
   private readonly options;
   constructor(params: PolicyServiceParams);
   private resolveEvaluationNow;
+  /**
+   * Evaluates a policy and returns its decision.
+   *
+   * This is the single public entry point. It delegates the actual work to the
+   * private pipeline and wraps it with telemetry: a completed or failed event
+   * is reported either way, but reporting is guarded so it can never change the
+   * outcome. The returned {@link Result} is `ok` with a
+   * {@link PolicyEvaluationResult} on success, or `err` with a typed
+   * {@link PolicyEvaluationError} describing which stage rejected the input —
+   * the method itself does not throw for expected failures.
+   *
+   * @param input - The policy key, scope chain, context version, and seed to
+   *   evaluate, plus the caller's `decisionId`.
+   * @returns A `Result` carrying the decision or the evaluation error.
+   */
   evaluate(input: EvaluateInput): Promise<Result<PolicyEvaluationResult, PolicyEvaluationError>>;
 }
 //#endregion