@cullet/erp-core 1.0.9 → 1.0.11

package/dist/policy-service.js

@@ -191,6 +191,15 @@ var PolicyCatalogEntry = class PolicyCatalogEntry {
 * The catalog defines the universe of policies; the database cannot invent new ones.
 */
 var PolicyCatalog = class {
+	/**
+	* 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) {
 		const families = /* @__PURE__ */ new Map();
 		const versionedMap = /* @__PURE__ */ new Map();
@@ -208,6 +217,14 @@ var PolicyCatalog = class {
 		this.versionedEntries = versionedMap;
 		this.entriesByKey = families;
 	}
+	/**
+	* 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) {
 		const familyResult = this.getFamily(key);
 		if (familyResult.isErr()) return Result.err(familyResult.errorOrNull());
@@ -217,11 +234,28 @@ var PolicyCatalog = class {
 		if (!entry) return Result.err(`Policy not found in catalog: "${key}"`);
 		return Result.ok(entry);
 	}
+	/**
+	* 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) {
 		const family = this.entriesByKey.get(key);
 		if (!family) return Result.err(`Policy not found in catalog: "${key}"`);
 		return Result.ok(family);
 	}
+	/**
+	* 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) {
 		const family = this.entriesByKey.get(params.key);
 		if (!family || family.length === 0) return Result.err(`Policy not found in catalog: "${params.key}"`);
@@ -236,9 +270,11 @@ var PolicyCatalog = class {
 		].filter((part) => part !== null).join(", ");
 		return Result.err(`Policy variant not found in catalog: "${params.key}" (${versionDetails})`);
 	}
+	/** Lists every registered variant across all keys — useful for introspection and diagnostics. */
 	list() {
 		return Array.from(this.versionedEntries.values());
 	}
+	/** Returns whether any variant is registered under the given key. */
 	has(key) {
 		return this.entriesByKey.has(key);
 	}
@@ -734,6 +770,16 @@ var PolicyAsOfResolver = class PolicyAsOfResolver {
 *   5. policyVersion descending (semver — final deterministic tiebreaker)
 */
 var PolicyResolver = class {
+	/**
+	* 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) {
 		if (candidates.length === 0) return Result.err("No matching policy definition found (candidates list is empty)");
 		const sorted = [...candidates].sort((a, b) => {
@@ -815,6 +861,18 @@ var PolicyEvaluationErrors = class {
 };
 //#endregion
 //#region src/core/policies/service/policy-service.ts
+/**
+* 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.
+*/
 var PolicyService = class {
 	#reporter;
 	constructor(params) {
@@ -838,6 +896,21 @@ var PolicyService = class {
 		if (!isValidDate(candidate)) return Result.err("seed.fields.now must be a valid Date when provided");
 		return Result.ok(candidate);
 	}
+	/**
+	* 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.
+	*/
 	async evaluate(input) {
 		const result = await this.#evaluate(input);
 		if (result.isErr()) {