@cullet/erp-core 1.5.0 → 2.0.0

package/dist/policy-service.cjs

@@ -1,11 +1,11 @@
+const require_invariant_violation_exception = require("./invariant-violation-exception.cjs");
+const require_temporal_guards = require("./temporal-guards.cjs");
 const require_stable_stringify = require("./stable-stringify.cjs");
 const require_hashing = require("./hashing.cjs");
 const require_unexpected_error = require("./unexpected-error.cjs");
 const require_validation_code = require("./validation-code.cjs");
 const require_validation_field = require("./validation-field.cjs");
-const require_invariant_violation_exception = require("./invariant-violation-exception.cjs");
 const require_validation_exception = require("./validation-exception.cjs");
-const require_temporal_guards = require("./temporal-guards.cjs");
 const require_result = require("./result.cjs");
 const require_condition_evaluator = require("./condition-evaluator.cjs");
 //#region src/core/policies/context/context-builder.ts
@@ -154,6 +154,13 @@ var PolicyContextBuilder = class PolicyContextBuilder {
 	/**
 	* Resolves all required context paths and returns a flat context object.
 	* If any required path cannot be resolved, returns an error.
+	*
+	* Resolution is deliberately sequential and fail-fast: paths resolve in
+	* order and the first failure returns immediately, so later resolvers never
+	* run once one path fails. This trades the latency-hiding of parallel
+	* resolution for skipping downstream (potentially expensive) lookups on a
+	* doomed evaluation. It is a tested contract, not an oversight — flip it to
+	* `Promise.all` only if you also accept that every resolver always runs.
 	*/
 	async build(requirements, seed) {
 		const context = {};
@@ -251,6 +258,8 @@ var ContextSeedValidator = class ContextSeedValidator {
 * Array item order is preserved on purpose; callers that treat arrays as sets
 * must normalize or sort them before hashing.
 *
+* The strict canonical form is owned by `shared/stable-stringify`
+* ({@link canonicalStringify}); this class just composes it with SHA-256.
 * Values that JSON.stringify would silently drop or coerce (undefined,
 * non-finite numbers, functions, symbols, bigint) are rejected up-front to
 * prevent semantically different payloads from collapsing to the same hash.
@@ -259,28 +268,8 @@ var PolicyHashing = class PolicyHashing {
 	static sha256(input) {
 		return require_hashing.sha256Hex(input);
 	}
-	static assertHashable(value, path, seen) {
-		if (value === null) return;
-		const type = typeof value;
-		if (type === "undefined") throw new TypeError(`canonicalJson does not accept undefined values (at ${path})`);
-		if (type === "number" && !Number.isFinite(value)) throw new TypeError(`canonicalJson does not accept non-finite numbers (at ${path}, value: ${String(value)})`);
-		if (type === "bigint" || type === "function" || type === "symbol") throw new TypeError(`canonicalJson does not accept ${type} values (at ${path})`);
-		if (type !== "object") return;
-		if (value instanceof Date) {
-			if (!require_temporal_guards.isValidDate(value)) throw new TypeError(`canonicalJson does not accept Invalid Date (at ${path})`);
-			return;
-		}
-		if (seen.has(value)) throw new TypeError(`canonicalJson does not accept circular references (at ${path})`);
-		seen.add(value);
-		if (Array.isArray(value)) value.forEach((item, index) => {
-			PolicyHashing.assertHashable(item, `${path}[${index}]`, seen);
-		});
-		else for (const [key, nested] of Object.entries(value)) PolicyHashing.assertHashable(nested, `${path}.${key}`, seen);
-		seen.delete(value);
-	}
 	static canonicalJson(value) {
-		PolicyHashing.assertHashable(value, "$", /* @__PURE__ */ new WeakSet());
-		return require_stable_stringify.stableStringify(value);
+		return require_stable_stringify.canonicalStringify(value);
 	}
 	static computePayloadHash(payload, policyKey, policyVersion) {
 		const canonical = PolicyHashing.canonicalJson({
@@ -395,7 +384,7 @@ var PolicyCatalogEntry = class PolicyCatalogEntry {
 		return this.tags.includes(tag);
 	}
 	equals(other) {
-		return this.key.equals(other.key);
+		return this.toVariantKey() === other.toVariantKey();
 	}
 	toJSON() {
 		return {
@@ -490,7 +479,7 @@ var PolicyCatalog = class {
 		if (!family || family.length === 0) return require_result.Result.err(`Policy not found in catalog: "${params.key}"`);
 		const exactMatch = family.find((entry) => entry.matchesVersion(params));
 		if (exactMatch) return require_result.Result.ok(exactMatch);
-		if (family.length === 1 && !family[0].hasExplicitVersionSelector()) return require_result.Result.ok(family[0]);
+		if (family.length === 1 && family[0].kind === params.kind && !family[0].hasExplicitVersionSelector()) return require_result.Result.ok(family[0]);
 		const versionDetails = [
 			params.kind,
 			params.gateEngineVersion !== void 0 ? `gateEngineVersion=${params.gateEngineVersion}` : null,
@@ -582,7 +571,6 @@ var PolicyScopeMatcher = class PolicyScopeMatcher {
 //#region src/core/policies/defs/in-memory-policy-definition-repo.ts
 var InMemoryPolicyDefinitionRepository = class {
 	constructor(definitions) {
-		this.definitions = definitions;
 		this.definitionsByPolicyKey = definitions.reduce((index, definition) => {
 			const existingDefinitions = index.get(definition.policyKey) ?? [];
 			existingDefinitions.push(definition);
@@ -726,6 +714,18 @@ var PolicyDefinition = class PolicyDefinition {
 //#endregion
 //#region src/core/policies/asof/asof.ts
 const DEFAULT_MAX_AS_OF_FUTURE_YEARS = 10;
+/**
+* Derives the `asOf` instant an evaluation is pinned to.
+*
+* With `asOfSource: "CALLER_PROVIDED"` the instant comes from the reserved
+* `seed.fields.asOf` key (a `Date`); with `"NOW"` it is the evaluation clock.
+*
+* The bound is intentionally asymmetric: a caller-provided `asOf` may be at
+* most `maxFutureYears` in the future (a fat-finger / clock-skew guard against
+* selecting a not-yet-in-force policy), but is unbounded in the past — querying
+* how a policy stood at any historical instant is a first-class use of a
+* temporal engine, so back-dating is never capped.
+*/
 var PolicyAsOfResolver = class PolicyAsOfResolver {
 	static resolveMaxFutureYears(options) {
 		const maxFutureYears = options.maxFutureYears ?? DEFAULT_MAX_AS_OF_FUTURE_YEARS;
@@ -867,7 +867,6 @@ var PolicyEvaluationErrors = class {
 * evaluation — which keeps observability strictly side-band.
 */
 var PolicyService = class {
-	#reporter;
 	constructor(params) {
 		this.catalog = params.catalog;
 		this.contextBuilder = params.contextBuilder;
@@ -876,12 +875,7 @@ var PolicyService = class {
 		this.gateEngines = params.gateEngines;
 		this.computeRegistry = params.computeRegistry;
 		this.options = params.options ?? {};
-		this.#reporter = this.options.reporter ?? new require_condition_evaluator.SilentPolicyReporter();
-	}
-	#reportSafely(event) {
-		try {
-			this.#reporter.report(event);
-		} catch {}
+		this.coreConfig = params.coreConfig ?? require_condition_evaluator.coreConfig;
 	}
 	resolveEvaluationNow(seed) {
 		const candidate = seed.fields["now"];
@@ -905,10 +899,10 @@ var PolicyService = class {
 	* @returns A `Result` carrying the decision or the evaluation error.
 	*/
 	async evaluate(input) {
-		const result = await this.#evaluate(input);
+		const result = await this.runEvaluation(input);
 		if (result.isErr()) {
 			const error = result.errorOrNull();
-			this.#reportSafely({
+			this.coreConfig.reportSafely({
 				kind: "policy-evaluation-failed",
 				level: "error",
 				policyKey: "policyKey" in error ? error.policyKey : void 0,
@@ -919,7 +913,7 @@ var PolicyService = class {
 			});
 		} else {
 			const ok = result.getOrNull();
-			this.#reportSafely({
+			this.coreConfig.reportSafely({
 				kind: "policy-evaluation-completed",
 				level: "info",
 				policyKey: ok.ref.policyKey,
@@ -930,11 +924,11 @@ var PolicyService = class {
 		}
 		return result;
 	}
-	async #evaluate(input) {
+	async runEvaluation(input) {
 		const seedResult = ContextSeedValidator.validate(input.seed);
 		if (seedResult.isErr()) return require_result.Result.err(PolicyEvaluationErrors.invalidContext("SEED_VALIDATION", input.policyKey, seedResult.errorOrNull()));
 		const seed = seedResult.getOrNull();
-		const catalogFamilyResult = this.#resolveCatalogFamily(input.policyKey);
+		const catalogFamilyResult = this.resolveCatalogFamily(input.policyKey);
 		if (catalogFamilyResult.isErr()) return require_result.Result.err(catalogFamilyResult.errorOrNull());
 		const { key: policyKey, family } = catalogFamilyResult.getOrNull();
 		const familyEntry = family[0];
@@ -944,10 +938,10 @@ var PolicyService = class {
 		const asOfResult = PolicyAsOfResolver.derive(familyEntry.asOfSource, seed, now, this.options.asOf);
 		if (asOfResult.isErr()) return require_result.Result.err(PolicyEvaluationErrors.invalidContext("AS_OF_DERIVATION", policyKey, asOfResult.errorOrNull()));
 		const asOf = asOfResult.getOrNull();
-		const definitionResult = this.#findCandidates(policyKey, familyEntry.kind, asOf, input);
+		const definitionResult = this.findCandidates(policyKey, familyEntry.kind, asOf, input);
 		if (definitionResult.isErr()) return require_result.Result.err(definitionResult.errorOrNull());
 		const { definition: policyDefinition, catalogEntry: versionedCatalogEntry } = definitionResult.getOrNull();
-		this.#reportSafely({
+		this.coreConfig.reportSafely({
 			kind: "policy-resolution",
 			level: "info",
 			policyKey,
@@ -960,7 +954,7 @@ var PolicyService = class {
 		const ctxResult = await this.contextBuilder.build(versionedCatalogEntry.contextRequirements, seed);
 		if (ctxResult.isErr()) return require_result.Result.err(PolicyEvaluationErrors.invalidContext("CONTEXT_BUILD", policyKey, ctxResult.errorOrNull()));
 		const context = ctxResult.getOrNull();
-		const decisionResult = this.#executeEngine(policyKey, policyDefinition, context);
+		const decisionResult = this.executeEngine(policyKey, policyDefinition, context);
 		if (decisionResult.isErr()) return require_result.Result.err(decisionResult.errorOrNull());
 		const decision = decisionResult.getOrNull();
 		const result = {
@@ -980,7 +974,7 @@ var PolicyService = class {
 		};
 		return require_result.Result.ok(result);
 	}
-	#resolveCatalogVariant(definition) {
+	resolveCatalogVariant(definition) {
 		return this.catalog.getVersioned({
 			key: definition.policyKey,
 			kind: definition.kind,
@@ -988,7 +982,7 @@ var PolicyService = class {
 			payloadSchemaVersion: definition.payloadSchemaVersion
 		});
 	}
-	#resolveCatalogFamily(rawKey) {
+	resolveCatalogFamily(rawKey) {
 		const keyResult = PolicyKey.parse(rawKey);
 		if (keyResult.isErr()) return require_result.Result.err(PolicyEvaluationErrors.invalidPolicyKey(rawKey, keyResult.errorOrNull()));
 		const policyKey = keyResult.getOrNull().toString();
@@ -999,7 +993,7 @@ var PolicyService = class {
 			family: catalogFamilyResult.getOrNull()
 		});
 	}
-	#findCandidates(policyKey, policyKind, asOf, input) {
+	findCandidates(policyKey, policyKind, asOf, input) {
 		const candidates = this.defRepo.findCandidates({
 			policyKey,
 			kind: policyKind,
@@ -1011,7 +1005,7 @@ var PolicyService = class {
 		const compatibleCandidatesByDefinitionId = /* @__PURE__ */ new Map();
 		const incompatibleVariantErrorsByDefinitionId = /* @__PURE__ */ new Map();
 		for (const candidate of candidates) {
-			const compatibilityResult = this.#resolveCatalogVariant(candidate);
+			const compatibilityResult = this.resolveCatalogVariant(candidate);
 			if (compatibilityResult.isErr()) {
 				incompatibleVariantErrorsByDefinitionId.set(candidate.id, compatibilityResult.errorOrNull());
 				continue;
@@ -1043,7 +1037,7 @@ var PolicyService = class {
 		if (resolvedCandidate === void 0) return require_result.Result.err(PolicyEvaluationErrors.policyDefinitionNotFound(policyKey, asOf, input.contextVersion, `Resolved definition "${bestDefinition.id}" is not present among compatible catalog variants`));
 		return require_result.Result.ok(resolvedCandidate);
 	}
-	#executeEngine(policyKey, definition, context) {
+	executeEngine(policyKey, definition, context) {
 		if (definition.isGate()) {
 			const gateResult = this.gateEngines.evaluate(definition.gateEngineVersion, definition.payloadJson, context);
 			if (gateResult.isErr()) return require_result.Result.err(PolicyEvaluationErrors.engineFailure(policyKey, "GATE", definition.gateEngineVersion, gateResult.errorOrNull()));