@cullet/erp-core 1.0.0

package/dist/policy-service.js

@@ -0,0 +1,992 @@
+import { a as stableStringify, i as sha256Hex, n as UnexpectedError, t as ValidationCode } from "./validation-code.js";
+import { t as ValidationField } from "./validation-field.js";
+import { _ as DomainException, f as SilentPolicyReporter, g as InvariantViolationException, h as isValidDate, l as Result, o as PolicyContextPath } from "./gate-v1-payload.schema.js";
+//#region src/core/policies/utils/hash.ts
+/**
+* Produces a deterministic SHA-256 hex digest of a canonical JSON representation.
+* Object keys are sorted recursively so key order does not affect the hash.
+* Array item order is preserved on purpose; callers that treat arrays as sets
+* must normalize or sort them before hashing.
+*
+* 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.
+*/
+var PolicyHashing = class PolicyHashing {
+	static sha256(input) {
+		return sha256Hex(input);
+	}
+	static assertHashable(value, path) {
+		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 (!isValidDate(value)) throw new TypeError(`canonicalJson does not accept Invalid Date (at ${path})`);
+			return;
+		}
+		if (Array.isArray(value)) {
+			value.forEach((item, index) => {
+				PolicyHashing.assertHashable(item, `${path}[${index}]`);
+			});
+			return;
+		}
+		for (const [key, nested] of Object.entries(value)) PolicyHashing.assertHashable(nested, `${path}.${key}`);
+	}
+	static canonicalJson(value) {
+		PolicyHashing.assertHashable(value, "$");
+		return stableStringify(value);
+	}
+	static computePayloadHash(payload, policyKey, policyVersion) {
+		const canonical = PolicyHashing.canonicalJson({
+			policyKey,
+			policyVersion,
+			payload
+		});
+		return PolicyHashing.sha256(canonical);
+	}
+};
+//#endregion
+//#region src/core/exceptions/validation-exception.ts
+var ValidationException = class extends DomainException {
+	constructor(field, code, message) {
+		super(message);
+		this.field = field;
+		this.code = code;
+	}
+};
+var InvalidValueException = class extends ValidationException {
+	constructor(field, code, message) {
+		super(field, code, message);
+	}
+};
+//#endregion
+//#region src/core/policies/policy-ids.ts
+const POLICY_DEFINITION_ID_FIELD = ValidationField.of("policyDefinitionId");
+const POLICY_DECISION_ID_FIELD = ValidationField.of("policyDecisionId");
+const TENANT_ID_FIELD = ValidationField.of("tenantId");
+const SCHOOL_ID_FIELD = ValidationField.of("schoolId");
+function assertIdString(value, field) {
+	if (typeof value !== "string") throw new InvalidValueException(field, ValidationCode.INVALID_FORMAT, `${field.value} must be a string, got ${typeof value}`);
+	if (value.trim().length === 0) throw new InvalidValueException(field, ValidationCode.BLANK, `${field.value} must be a non-empty string`);
+	return value;
+}
+function brandId(value, field) {
+	return assertIdString(value, field);
+}
+function asPolicyDefinitionId(value) {
+	return brandId(value, POLICY_DEFINITION_ID_FIELD);
+}
+function asPolicyDecisionId(value) {
+	return brandId(value, POLICY_DECISION_ID_FIELD);
+}
+function asTenantId(value) {
+	return brandId(value, TENANT_ID_FIELD);
+}
+function asSchoolId(value) {
+	return brandId(value, SCHOOL_ID_FIELD);
+}
+//#endregion
+//#region src/core/policies/catalog/policy-catalog-entry.ts
+/**
+* Represents a single entry in the Policy Catalog.
+* Encapsulates metadata and validation logic for a policy.
+*/
+var PolicyCatalogEntry = class PolicyCatalogEntry {
+	constructor(props) {
+		this.key = props.key;
+		this.kind = props.kind;
+		this.gateEngineVersion = props.gateEngineVersion;
+		this.computeEngineVersion = props.computeEngineVersion;
+		this.payloadSchemaVersion = props.payloadSchemaVersion;
+		this.owner = props.owner;
+		this.allowedScopes = [...props.allowedScopes];
+		this.asOfSource = props.asOfSource;
+		this.contextRequirements = [...props.contextRequirements];
+		this.tags = [...props.tags ?? []];
+		this.description = props.description;
+	}
+	static assertFamilyConsistency(entries) {
+		if (entries.length === 0) throw new UnexpectedError("Cannot validate an empty PolicyCatalogEntry family");
+		const [first, ...rest] = entries;
+		for (const entry of rest) {
+			if (!first.key.equals(entry.key)) throw new UnexpectedError("Cannot merge PolicyCatalog entries with different keys");
+			if (first.kind !== entry.kind) throw new UnexpectedError(`PolicyCatalog entries for key "${first.key.toString()}" must share the same kind`);
+			if (first.owner !== entry.owner) throw new UnexpectedError(`PolicyCatalog entries for key "${first.key.toString()}" must share the same owner`);
+			if (first.asOfSource !== entry.asOfSource) throw new UnexpectedError(`PolicyCatalog entries for key "${first.key.toString()}" must share the same asOfSource`);
+			if (first.description !== entry.description) throw new UnexpectedError(`PolicyCatalog entries for key "${first.key.toString()}" must share the same description`);
+		}
+	}
+	static from(entry) {
+		return entry instanceof PolicyCatalogEntry ? entry : new PolicyCatalogEntry(entry);
+	}
+	isGate() {
+		return this.kind === "GATE";
+	}
+	isCompute() {
+		return this.kind === "COMPUTE";
+	}
+	allowsScope(scope) {
+		return this.allowedScopes.includes(scope);
+	}
+	hasExplicitVersionSelector() {
+		return this.gateEngineVersion !== void 0 || this.computeEngineVersion !== void 0 || this.payloadSchemaVersion !== void 0;
+	}
+	matchesVersion(params) {
+		if (this.kind !== params.kind) return false;
+		if (this.gateEngineVersion !== void 0 && this.gateEngineVersion !== params.gateEngineVersion) return false;
+		if (this.computeEngineVersion !== void 0 && this.computeEngineVersion !== params.computeEngineVersion) return false;
+		if (this.payloadSchemaVersion !== void 0 && this.payloadSchemaVersion !== params.payloadSchemaVersion) return false;
+		return true;
+	}
+	toVariantKey() {
+		return [
+			this.key.toString(),
+			this.kind,
+			this.gateEngineVersion ?? "gate:any",
+			this.computeEngineVersion ?? "compute:any",
+			this.payloadSchemaVersion ?? "schema:any"
+		].join("::");
+	}
+	usesNowAsOf() {
+		return this.asOfSource === "NOW";
+	}
+	usesCallerProvidedAsOf() {
+		return this.asOfSource === "CALLER_PROVIDED";
+	}
+	requiresContext(path) {
+		return this.contextRequirements.includes(path);
+	}
+	requiresAllContexts(paths) {
+		return paths.every((path) => this.requiresContext(path));
+	}
+	hasTag(tag) {
+		return this.tags.includes(tag);
+	}
+	equals(other) {
+		return this.key.equals(other.key);
+	}
+	toJSON() {
+		return {
+			key: this.key,
+			kind: this.kind,
+			...this.gateEngineVersion !== void 0 ? { gateEngineVersion: this.gateEngineVersion } : {},
+			...this.computeEngineVersion !== void 0 ? { computeEngineVersion: this.computeEngineVersion } : {},
+			...this.payloadSchemaVersion !== void 0 ? { payloadSchemaVersion: this.payloadSchemaVersion } : {},
+			owner: this.owner,
+			allowedScopes: [...this.allowedScopes],
+			asOfSource: this.asOfSource,
+			contextRequirements: [...this.contextRequirements],
+			tags: this.tags.length > 0 ? [...this.tags] : void 0,
+			description: this.description
+		};
+	}
+};
+//#endregion
+//#region src/core/policies/catalog/policy-catalog.ts
+/**
+* In-code catalog of all known policies.
+* The catalog defines the universe of policies; the database cannot invent new ones.
+*/
+var PolicyCatalog = class {
+	constructor(entries) {
+		const families = /* @__PURE__ */ new Map();
+		const versionedMap = /* @__PURE__ */ new Map();
+		for (const rawEntry of entries) {
+			const entry = PolicyCatalogEntry.from(rawEntry);
+			const key = entry.key.toString();
+			const variantKey = entry.toVariantKey();
+			if (versionedMap.has(variantKey)) throw new UnexpectedError(`Duplicate PolicyCatalog entry for key "${key}" and variant "${variantKey}"`);
+			const family = families.get(key) ?? [];
+			family.push(entry);
+			families.set(key, family);
+			versionedMap.set(variantKey, entry);
+		}
+		for (const family of families.values()) PolicyCatalogEntry.assertFamilyConsistency(family);
+		this.versionedEntries = versionedMap;
+		this.entriesByKey = families;
+	}
+	get(key) {
+		const familyResult = this.getFamily(key);
+		if (familyResult.isErr()) return Result.err(familyResult.errorOrNull());
+		const family = familyResult.getOrNull();
+		if (family.length > 1) return Result.err(`Policy key "${key}" has multiple catalog variants; use getVersioned(...) or getFamily(...)`);
+		const [entry] = family;
+		if (!entry) return Result.err(`Policy not found in catalog: "${key}"`);
+		return Result.ok(entry);
+	}
+	getFamily(key) {
+		const family = this.entriesByKey.get(key);
+		if (!family) return Result.err(`Policy not found in catalog: "${key}"`);
+		return Result.ok(family);
+	}
+	getVersioned(params) {
+		const family = this.entriesByKey.get(params.key);
+		if (!family || family.length === 0) return Result.err(`Policy not found in catalog: "${params.key}"`);
+		const exactMatch = family.find((entry) => entry.matchesVersion(params));
+		if (exactMatch) return Result.ok(exactMatch);
+		if (family.length === 1 && !family[0].hasExplicitVersionSelector()) return Result.ok(family[0]);
+		const versionDetails = [
+			params.kind,
+			params.gateEngineVersion !== void 0 ? `gateEngineVersion=${params.gateEngineVersion}` : null,
+			params.computeEngineVersion !== void 0 ? `computeEngineVersion=${params.computeEngineVersion}` : null,
+			params.payloadSchemaVersion !== void 0 ? `payloadSchemaVersion=${params.payloadSchemaVersion}` : null
+		].filter((part) => part !== null).join(", ");
+		return Result.err(`Policy variant not found in catalog: "${params.key}" (${versionDetails})`);
+	}
+	list() {
+		return Array.from(this.versionedEntries.values());
+	}
+	has(key) {
+		return this.entriesByKey.has(key);
+	}
+};
+//#endregion
+//#region src/core/policies/catalog/catalog.instance.ts
+/**
+* Aggregates catalog entries contributed by each module package into a single
+* PolicyCatalog. The core knows nothing about concrete modules — callers
+* are responsible for passing all relevant packages at composition time.
+*/
+var PolicyCatalogFactory = class {
+	static build(packages) {
+		return new PolicyCatalog(packages.flatMap((policyPackage) => Array.from(policyPackage.catalogEntries).map(PolicyCatalogEntry.from)));
+	}
+};
+//#endregion
+//#region src/core/policies/catalog/policy-key.ts
+/**
+* PolicyKey value object.
+*
+* Format: `module.area.policy_name` (exactly 3 dot-separated segments).
+* - module: structural segment (lowercase alphanumeric + underscore, starting with a letter)
+* - area:   structural segment (lowercase alphanumeric + underscore, starting with a letter)
+* - name:   specific policy identifier (lowercase alphanumeric + underscore, starting with a letter)
+*/
+const SEGMENT_PATTERN = /^[a-z][a-z0-9_]*$/;
+const MAX_POLICY_KEY_LENGTH = 255;
+var PolicyKey = class PolicyKey {
+	constructor(module, area, name) {
+		this.module = module;
+		this.area = area;
+		this.name = name;
+		Object.freeze(this);
+	}
+	static parse(raw) {
+		if (!raw || typeof raw !== "string") return Result.err("PolicyKey cannot be empty");
+		if (raw.length > MAX_POLICY_KEY_LENGTH) return Result.err(`PolicyKey cannot exceed ${MAX_POLICY_KEY_LENGTH} characters, got ${raw.length}`);
+		const segments = raw.split(".");
+		if (segments.length !== 3) return Result.err(`PolicyKey must have exactly 3 segments (module.area.name), got ${segments.length}: "${raw}"`);
+		const [rawModule, rawArea, name] = segments;
+		if (!SEGMENT_PATTERN.test(rawModule)) return Result.err(`PolicyKey segment "module" is invalid: "${rawModule}". Must start with a lowercase letter and contain only [a-z0-9_].`);
+		if (!SEGMENT_PATTERN.test(rawArea)) return Result.err(`PolicyKey segment "area" is invalid: "${rawArea}". Must start with a lowercase letter and contain only [a-z0-9_].`);
+		if (!SEGMENT_PATTERN.test(name)) return Result.err(`PolicyKey segment "name" is invalid: "${name}". Must start with a lowercase letter and contain only [a-z0-9_].`);
+		return Result.ok(new PolicyKey(rawModule, rawArea, name));
+	}
+	toString() {
+		return `${this.module}.${this.area}.${this.name}`;
+	}
+	equals(other) {
+		return this.toString() === other.toString();
+	}
+};
+//#endregion
+//#region src/core/policies/defs/policy-scope.ts
+/**
+* Numeric weight for scope specificity (higher = more specific).
+*/
+const SCOPE_WEIGHT = {
+	SCHOOL: 3,
+	TENANT: 2,
+	GLOBAL: 1
+};
+var PolicyScopeMatcher = class PolicyScopeMatcher {
+	static weight(level) {
+		return SCOPE_WEIGHT[level];
+	}
+	static matchesChain(defScope, chain) {
+		return chain.some((scope) => PolicyScopeMatcher.equals(defScope, scope));
+	}
+	static equals(a, b) {
+		return a.level === b.level && a.tenantId === b.tenantId && a.schoolId === b.schoolId;
+	}
+};
+//#endregion
+//#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);
+			index.set(definition.policyKey, existingDefinitions);
+			return index;
+		}, /* @__PURE__ */ new Map());
+	}
+	findCandidates(params) {
+		const { policyKey, kind, payloadSchemaVersion, asOf, contextVersion, scopeChain } = params;
+		return (this.definitionsByPolicyKey.get(policyKey) ?? []).filter((def) => {
+			if (def.kind !== kind) return false;
+			if (payloadSchemaVersion !== void 0 && def.payloadSchemaVersion !== payloadSchemaVersion) return false;
+			if (!def.enabled) return false;
+			if (def.status !== "PUBLISHED") return false;
+			if (def.effectiveFrom > asOf) return false;
+			if (def.effectiveTo !== null && def.effectiveTo <= asOf) return false;
+			if (contextVersion < def.contextVersionMin) return false;
+			if (contextVersion > def.contextVersionMax) return false;
+			if (!PolicyScopeMatcher.matchesChain(def.scope, scopeChain)) return false;
+			return true;
+		});
+	}
+};
+//#endregion
+//#region src/core/policies/defs/policy-semver.ts
+const POLICY_SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+function parseSemver(version) {
+	const [core, preRelease = null] = version.split("+")[0].split("-");
+	const [major, minor, patch] = core.split(".").map(Number);
+	return {
+		major,
+		minor,
+		patch,
+		preRelease: preRelease ?? null
+	};
+}
+function comparePreRelease(a, b) {
+	const aIds = a.split(".");
+	const bIds = b.split(".");
+	const len = Math.max(aIds.length, bIds.length);
+	for (let i = 0; i < len; i++) {
+		const ai = aIds[i];
+		const bi = bIds[i];
+		if (ai === void 0) return -1;
+		if (bi === void 0) return 1;
+		const aNum = Number(ai);
+		const bNum = Number(bi);
+		const aIsNum = !Number.isNaN(aNum);
+		const bIsNum = !Number.isNaN(bNum);
+		if (aIsNum && !bIsNum) return -1;
+		if (!aIsNum && bIsNum) return 1;
+		if (aIsNum && bIsNum) {
+			if (aNum !== bNum) return aNum - bNum;
+		} else {
+			if (ai < bi) return -1;
+			if (ai > bi) return 1;
+		}
+	}
+	return 0;
+}
+/**
+* Compares two valid semver strings.
+* Returns a negative number if a < b, 0 if a === b, positive if a > b.
+*
+* Callers are expected to pass only strings that already passed
+* `POLICY_SEMVER_PATTERN` validation (i.e. values stored in PolicyDefinition).
+*/
+function comparePolicySemver(a, b) {
+	const av = parseSemver(a);
+	const bv = parseSemver(b);
+	if (av.major !== bv.major) return av.major - bv.major;
+	if (av.minor !== bv.minor) return av.minor - bv.minor;
+	if (av.patch !== bv.patch) return av.patch - bv.patch;
+	if (av.preRelease === null && bv.preRelease !== null) return 1;
+	if (av.preRelease !== null && bv.preRelease === null) return -1;
+	if (av.preRelease !== null && bv.preRelease !== null) return comparePreRelease(av.preRelease, bv.preRelease);
+	return 0;
+}
+//#endregion
+//#region src/core/policies/defs/policy-definition.ts
+var PolicyDefinition = class PolicyDefinition {
+	static assertPolicyVersionIsSemver(policyVersion) {
+		if (!POLICY_SEMVER_PATTERN.test(policyVersion)) throw new InvariantViolationException(`PolicyDefinition.policyVersion must be a valid semver. Received: "${policyVersion}"`);
+	}
+	constructor(props) {
+		this.id = props.id;
+		this.policyKey = props.policyKey;
+		PolicyDefinition.assertPolicyVersionIsSemver(props.policyVersion);
+		this.policyVersion = props.policyVersion;
+		this.payloadSchemaVersion = props.payloadSchemaVersion;
+		this.contextVersionMin = props.contextVersionMin;
+		this.contextVersionMax = props.contextVersionMax;
+		this.enabled = props.enabled;
+		this.status = props.status;
+		this.scope = props.scope;
+		this.effectiveFrom = props.effectiveFrom;
+		this.effectiveTo = props.effectiveTo;
+		this.priority = props.priority;
+		this.payloadJson = props.payloadJson;
+		this.payloadHash = props.payloadHash;
+		this.createdAt = props.createdAt;
+		this.publishedAt = props.publishedAt;
+		this.kind = props.kind;
+		if (props.kind === "GATE") {
+			if (props.gateEngineVersion === void 0) throw new InvariantViolationException(`PolicyDefinition of kind 'GATE' must have a 'gateEngineVersion'. Policy key: ${props.policyKey}`);
+			this.gateEngineVersion = props.gateEngineVersion;
+		} else {
+			if (props.computeEngineVersion === void 0) throw new InvariantViolationException(`PolicyDefinition of kind 'COMPUTE' must have a 'computeEngineVersion'. Policy key: ${props.policyKey}`);
+			this.computeEngineVersion = props.computeEngineVersion;
+		}
+	}
+	static gate(props) {
+		return new PolicyDefinition({
+			...props,
+			enabled: props.enabled ?? true,
+			kind: "GATE"
+		});
+	}
+	static compute(props) {
+		return new PolicyDefinition({
+			...props,
+			enabled: props.enabled ?? true,
+			kind: "COMPUTE"
+		});
+	}
+	isGate() {
+		return this.kind === "GATE";
+	}
+	isCompute() {
+		return this.kind === "COMPUTE";
+	}
+};
+//#endregion
+//#region src/core/policies/context/context-builder.ts
+const DEFAULT_RESOLVER_RETRY_OPTIONS = {
+	maxAttempts: 1,
+	initialDelayMs: 25,
+	maxDelayMs: 1e3,
+	backoffMultiplier: 2
+};
+/**
+* Builds a context object by resolving required paths from a seed.
+*/
+var PolicyContextBuilder = class PolicyContextBuilder {
+	constructor(registry, options = {}) {
+		this.registry = registry;
+		this.circuitStates = /* @__PURE__ */ new Map();
+		this.defaultResolverResilience = options.defaultResolverResilience;
+		this.now = options.now ?? Date.now;
+		this.sleep = options.sleep ?? (async (delayMs) => {
+			if (delayMs <= 0) return;
+			await new Promise((resolve) => {
+				setTimeout(resolve, delayMs);
+			});
+		});
+	}
+	static clampPositiveInteger(value, fallback) {
+		if (value === void 0 || !Number.isFinite(value)) return fallback;
+		return Math.max(1, Math.trunc(value));
+	}
+	static clampNonNegativeInteger(value, fallback) {
+		if (value === void 0 || !Number.isFinite(value)) return fallback;
+		return Math.max(0, Math.trunc(value));
+	}
+	static normalizeTimeoutMs(value) {
+		if (value === void 0 || !Number.isFinite(value) || value <= 0) return null;
+		return Math.trunc(value);
+	}
+	static mergeRetryOptions(defaults, overrides) {
+		if (overrides === false) return false;
+		if (overrides !== void 0) return {
+			...defaults === false || defaults === void 0 ? {} : defaults,
+			...overrides
+		};
+		return defaults;
+	}
+	static mergeCircuitBreakerOptions(defaults, overrides) {
+		if (overrides === false) return false;
+		if (overrides !== void 0) return {
+			...defaults === false || defaults === void 0 ? {} : defaults,
+			...overrides
+		};
+		return defaults;
+	}
+	resolveResilienceOptions(resolver) {
+		const defaults = this.defaultResolverResilience;
+		const override = resolver.resilience;
+		const retry = PolicyContextBuilder.mergeRetryOptions(defaults?.retry, override?.retry);
+		const circuitBreaker = PolicyContextBuilder.mergeCircuitBreakerOptions(defaults?.circuitBreaker, override?.circuitBreaker);
+		const retryOptions = retry === false ? void 0 : retry;
+		const circuitBreakerOptions = circuitBreaker === false ? void 0 : circuitBreaker;
+		return {
+			timeoutMs: PolicyContextBuilder.normalizeTimeoutMs(override?.timeoutMs ?? defaults?.timeoutMs),
+			retry: {
+				maxAttempts: PolicyContextBuilder.clampPositiveInteger(retryOptions?.maxAttempts, DEFAULT_RESOLVER_RETRY_OPTIONS.maxAttempts),
+				initialDelayMs: PolicyContextBuilder.clampNonNegativeInteger(retryOptions?.initialDelayMs, DEFAULT_RESOLVER_RETRY_OPTIONS.initialDelayMs),
+				maxDelayMs: PolicyContextBuilder.clampNonNegativeInteger(retryOptions?.maxDelayMs, DEFAULT_RESOLVER_RETRY_OPTIONS.maxDelayMs),
+				backoffMultiplier: PolicyContextBuilder.clampPositiveInteger(retryOptions?.backoffMultiplier, DEFAULT_RESOLVER_RETRY_OPTIONS.backoffMultiplier)
+			},
+			circuitBreaker: circuitBreakerOptions === void 0 ? null : {
+				failureThreshold: PolicyContextBuilder.clampPositiveInteger(circuitBreakerOptions.failureThreshold, 5),
+				cooldownMs: PolicyContextBuilder.clampPositiveInteger(circuitBreakerOptions.cooldownMs, 3e4)
+			}
+		};
+	}
+	getRetryDelayMs(attempt, retry) {
+		return Math.min(retry.initialDelayMs * retry.backoffMultiplier ** (attempt - 1), retry.maxDelayMs);
+	}
+	resetCircuit(path) {
+		this.circuitStates.delete(path);
+	}
+	isCircuitOpen(path, circuitBreaker) {
+		if (circuitBreaker === null) return false;
+		const state = this.circuitStates.get(path);
+		if (state === void 0 || state.openUntilMs === null) return false;
+		if (state.openUntilMs <= this.now()) {
+			this.resetCircuit(path);
+			return false;
+		}
+		return true;
+	}
+	recordResolverFailure(path, circuitBreaker) {
+		if (circuitBreaker === null) return;
+		const nextFailureCount = (this.circuitStates.get(path)?.failureCount ?? 0) + 1;
+		if (nextFailureCount >= circuitBreaker.failureThreshold) {
+			this.circuitStates.set(path, {
+				failureCount: 0,
+				openUntilMs: this.now() + circuitBreaker.cooldownMs
+			});
+			return;
+		}
+		this.circuitStates.set(path, {
+			failureCount: nextFailureCount,
+			openUntilMs: null
+		});
+	}
+	static describeThrownResolverError(error) {
+		if (error instanceof Error) return `threw ${error.name}: ${error.message}`;
+		return `threw ${String(error)}`;
+	}
+	async resolveOnce(resolver, seed, timeoutMs) {
+		const execute = async () => {
+			try {
+				return await resolver.resolve(seed);
+			} catch (error) {
+				return Result.err(PolicyContextBuilder.describeThrownResolverError(error));
+			}
+		};
+		if (timeoutMs === null) return execute();
+		let timeoutId;
+		try {
+			return await Promise.race([execute(), new Promise((resolve) => {
+				timeoutId = setTimeout(() => {
+					resolve(Result.err(`timed out after ${timeoutMs}ms`));
+				}, timeoutMs);
+			})]);
+		} finally {
+			if (timeoutId !== void 0) clearTimeout(timeoutId);
+		}
+	}
+	async resolveWithResilience(path, resolver, seed) {
+		const resilience = this.resolveResilienceOptions(resolver);
+		if (this.isCircuitOpen(path, resilience.circuitBreaker)) return Result.err("circuit breaker is open");
+		let lastError = "resolver failed";
+		for (let attempt = 1; attempt <= resilience.retry.maxAttempts; attempt++) {
+			const result = await this.resolveOnce(resolver, seed, resilience.timeoutMs);
+			if (result.isOk()) {
+				this.resetCircuit(path);
+				return result;
+			}
+			lastError = result.errorOrNull() ?? lastError;
+			if (attempt < resilience.retry.maxAttempts) await this.sleep(this.getRetryDelayMs(attempt, resilience.retry));
+		}
+		this.recordResolverFailure(path, resilience.circuitBreaker);
+		return Result.err(lastError);
+	}
+	/**
+	* Resolves all required context paths and returns a flat context object.
+	* If any required path cannot be resolved, returns an error.
+	*/
+	async build(requirements, seed) {
+		const context = {};
+		for (const path of requirements) {
+			const resolver = this.registry.get(path);
+			if (!resolver) return Result.err(`Missing resolver for path "${path}"`);
+			const result = await this.resolveWithResilience(path, resolver, seed);
+			if (result.isErr()) return Result.err(`Resolver error for path "${path}": ${result.errorOrNull()}`);
+			const setPathResult = PolicyContextPath.set(context, path, result.getOrNull());
+			if (setPathResult.isErr()) return Result.err(setPathResult.errorOrNull());
+		}
+		const missing = requirements.filter((path) => {
+			const result = PolicyContextPath.getOrAbsent(context, path);
+			return result.isErr() || result.getOrNull() === void 0;
+		});
+		if (missing.length > 0) return Result.err(`Context missing required paths after resolution: ${missing.join(", ")}`);
+		return Result.ok(context);
+	}
+};
+//#endregion
+//#region src/core/policies/context/context-registry.ts
+const DEFAULT_CONTEXT_RESOLVER_NAMESPACE = "default";
+function normalizeNamespace(namespace) {
+	const normalized = namespace?.trim();
+	if (normalized === void 0 || normalized.length === 0) return DEFAULT_CONTEXT_RESOLVER_NAMESPACE;
+	return normalized;
+}
+/**
+* Registry of context value resolvers, keyed by path.
+*/
+var ContextResolverRegistry = class {
+	constructor() {
+		this.resolvers = /* @__PURE__ */ new Map();
+	}
+	register(resolver, options = {}) {
+		const namespace = normalizeNamespace(options.namespace);
+		const existing = this.resolvers.get(resolver.path);
+		if (existing !== void 0 && existing.namespace !== namespace) return Result.err(`Resolver path "${resolver.path}" is already registered by namespace "${existing.namespace}" and cannot be replaced by "${namespace}".`);
+		this.resolvers.set(resolver.path, {
+			namespace,
+			resolver
+		});
+		return Result.ok(void 0);
+	}
+	registerAll(resolvers, options = {}) {
+		for (const r of resolvers) {
+			const registrationResult = this.register(r, options);
+			if (registrationResult.isErr()) return registrationResult;
+		}
+		return Result.ok(void 0);
+	}
+	get(path) {
+		return this.resolvers.get(path)?.resolver;
+	}
+	has(path) {
+		return this.resolvers.has(path);
+	}
+	getNamespace(path) {
+		return this.resolvers.get(path)?.namespace;
+	}
+};
+function registerNamespacedContextResolversIn(registry, namespace, resolvers) {
+	const registrationResult = registry.registerAll(resolvers, { namespace });
+	if (registrationResult.isErr()) return Result.err(registrationResult.errorOrNull());
+	return Result.ok(registry);
+}
+//#endregion
+//#region src/core/policies/context/context-registry.instance.ts
+/**
+* Official instance of the ContextResolverRegistry.
+* Use `new ContextResolverRegistry()` plus `registerNamespacedContextResolversIn`
+* when each runtime/composition root needs its own isolated resolver graph.
+*/
+const contextResolverRegistry = new ContextResolverRegistry();
+function registerNamespacedContextResolvers(namespace, resolvers) {
+	return registerNamespacedContextResolversIn(contextResolverRegistry, namespace, resolvers);
+}
+//#endregion
+//#region src/core/policies/context/context-seed.ts
+var ContextSeedValidator = class ContextSeedValidator {
+	static isBlankSeedId(value) {
+		return value.trim().length === 0;
+	}
+	static validate(seed) {
+		if (ContextSeedValidator.isBlankSeedId(seed.tenantId)) return Result.err("ContextSeed tenantId must be a non-empty string");
+		if (ContextSeedValidator.isBlankSeedId(seed.schoolId)) return Result.err("ContextSeed schoolId must be a non-empty string");
+		return Result.ok(seed);
+	}
+};
+//#endregion
+//#region src/core/policies/asof/asof.ts
+const DEFAULT_MAX_AS_OF_FUTURE_YEARS = 10;
+var PolicyAsOfResolver = class PolicyAsOfResolver {
+	static resolveMaxFutureYears(options) {
+		const maxFutureYears = options.maxFutureYears ?? DEFAULT_MAX_AS_OF_FUTURE_YEARS;
+		if (!Number.isInteger(maxFutureYears) || maxFutureYears < 0) return Result.err(`deriveAsOf maxFutureYears must be a non-negative integer. Received: ${maxFutureYears}`);
+		return Result.ok(maxFutureYears);
+	}
+	static derive(source, seed, now, options = {}) {
+		const maxFutureYearsResult = PolicyAsOfResolver.resolveMaxFutureYears(options);
+		if (maxFutureYearsResult.isErr()) return Result.err(maxFutureYearsResult.errorOrNull());
+		const maxFutureYears = maxFutureYearsResult.getOrNull();
+		switch (source) {
+			case "NOW": return Result.ok(now);
+			case "CALLER_PROVIDED": {
+				const asOf = seed.fields["asOf"];
+				if (!isValidDate(asOf)) return Result.err("asOfSource \"CALLER_PROVIDED\" requires seed.fields.asOf to be a Date");
+				const maxFuture = new Date(now);
+				maxFuture.setFullYear(maxFuture.getFullYear() + maxFutureYears);
+				if (asOf > maxFuture) return Result.err(`asOf date is more than ${maxFutureYears} years in the future (received ${asOf.toISOString()})`);
+				return Result.ok(asOf);
+			}
+			default: return Result.err(`Unknown asOfSource: "${source}"`);
+		}
+	}
+};
+//#endregion
+//#region src/core/policies/resolver/policy-resolver.ts
+/**
+* Selects the best policy definition from a list of already-filtered candidates.
+*
+* Ordering criteria (highest priority first):
+*   1. Scope specificity: SCHOOL (3) > TENANT (2) > GLOBAL (1)
+*   2. Priority: higher number wins
+*   3. publishedAt descending (fallback to createdAt)
+*   4. Engine version descending (prefer-latest-engine-version — deterministic tiebreaker)
+*   5. policyVersion descending (semver — final deterministic tiebreaker)
+*/
+var PolicyResolver = class {
+	resolveBest(candidates) {
+		if (candidates.length === 0) return Result.err("No matching policy definition found (candidates list is empty)");
+		const sorted = [...candidates].sort((a, b) => {
+			const scopeDiff = PolicyScopeMatcher.weight(b.scope.level) - PolicyScopeMatcher.weight(a.scope.level);
+			if (scopeDiff !== 0) return scopeDiff;
+			const priorityDiff = b.priority - a.priority;
+			if (priorityDiff !== 0) return priorityDiff;
+			const aDate = a.publishedAt ?? a.createdAt;
+			const dateDiff = (b.publishedAt ?? b.createdAt).getTime() - aDate.getTime();
+			if (dateDiff !== 0) return dateDiff;
+			const aEngine = a.gateEngineVersion ?? a.computeEngineVersion ?? 0;
+			const engineDiff = (b.gateEngineVersion ?? b.computeEngineVersion ?? 0) - aEngine;
+			if (engineDiff !== 0) return engineDiff;
+			return comparePolicySemver(b.policyVersion, a.policyVersion);
+		});
+		return Result.ok(sorted[0]);
+	}
+};
+//#endregion
+//#region src/core/policies/service/policy-evaluation-error.ts
+var PolicyEvaluationErrors = class {
+	static invalidContext(stage, policyKey, cause) {
+		return {
+			kind: "INVALID_CONTEXT",
+			stage,
+			policyKey,
+			message: "Policy evaluation context is invalid",
+			cause
+		};
+	}
+	static invalidPolicyKey(rawPolicyKey, cause) {
+		return {
+			kind: "INVALID_POLICY_KEY",
+			rawPolicyKey,
+			message: "Policy key is invalid",
+			cause
+		};
+	}
+	static policyNotFound(policyKey, cause) {
+		return {
+			kind: "POLICY_NOT_FOUND",
+			policyKey,
+			message: "Policy is not registered in the catalog",
+			cause
+		};
+	}
+	static policyDefinitionNotFound(policyKey, asOf, contextVersion, cause) {
+		return {
+			kind: "POLICY_DEFINITION_NOT_FOUND",
+			policyKey,
+			contextVersion,
+			asOf,
+			message: "No published policy definition matched the evaluation inputs",
+			cause
+		};
+	}
+	static policyVariantNotFound(params) {
+		return {
+			kind: "POLICY_VARIANT_NOT_FOUND",
+			policyKey: params.policyKey,
+			policyKind: params.policyKind,
+			payloadSchemaVersion: params.payloadSchemaVersion,
+			...params.gateEngineVersion !== void 0 ? { gateEngineVersion: params.gateEngineVersion } : {},
+			...params.computeEngineVersion !== void 0 ? { computeEngineVersion: params.computeEngineVersion } : {},
+			message: "No catalog variant matched the selected policy definition",
+			cause: params.cause
+		};
+	}
+	static engineFailure(policyKey, engine, engineVersion, cause) {
+		return {
+			kind: "ENGINE_FAILURE",
+			policyKey,
+			engine,
+			engineVersion,
+			message: "Policy engine evaluation failed",
+			cause
+		};
+	}
+};
+//#endregion
+//#region src/core/policies/service/policy-service.ts
+var PolicyService = class {
+	#reporter;
+	constructor(params) {
+		this.catalog = params.catalog;
+		this.contextBuilder = params.contextBuilder;
+		this.defRepo = params.defRepo;
+		this.resolver = params.resolver;
+		this.gateEngines = params.gateEngines;
+		this.computeRegistry = params.computeRegistry;
+		this.options = params.options ?? {};
+		this.#reporter = this.options.reporter ?? new SilentPolicyReporter();
+	}
+	#reportSafely(event) {
+		try {
+			this.#reporter.report(event);
+		} catch {}
+	}
+	resolveEvaluationNow(seed) {
+		const candidate = seed.fields["now"];
+		if (candidate === void 0) return Result.ok(/* @__PURE__ */ new Date());
+		if (!isValidDate(candidate)) return Result.err("seed.fields.now must be a valid Date when provided");
+		return Result.ok(candidate);
+	}
+	async evaluate(input) {
+		const result = await this.#evaluate(input);
+		if (result.isErr()) {
+			const error = result.errorOrNull();
+			this.#reportSafely({
+				kind: "policy-evaluation-failed",
+				level: "error",
+				policyKey: "policyKey" in error ? error.policyKey : void 0,
+				errorKind: error.kind,
+				message: error.message,
+				cause: error.cause,
+				occurredAt: /* @__PURE__ */ new Date()
+			});
+		} else {
+			const ok = result.getOrNull();
+			this.#reportSafely({
+				kind: "policy-evaluation-completed",
+				level: "info",
+				policyKey: ok.ref.policyKey,
+				decisionId: ok.decisionId,
+				engineKind: ok.kind,
+				occurredAt: ok.evaluatedAt
+			});
+		}
+		return result;
+	}
+	async #evaluate(input) {
+		const seedResult = ContextSeedValidator.validate(input.seed);
+		if (seedResult.isErr()) return Result.err(PolicyEvaluationErrors.invalidContext("SEED_VALIDATION", input.policyKey, seedResult.errorOrNull()));
+		const seed = seedResult.getOrNull();
+		const catalogFamilyResult = this.#resolveCatalogFamily(input.policyKey);
+		if (catalogFamilyResult.isErr()) return Result.err(catalogFamilyResult.errorOrNull());
+		const { key: policyKey, family } = catalogFamilyResult.getOrNull();
+		const familyEntry = family[0];
+		const nowResult = this.resolveEvaluationNow(seed);
+		if (nowResult.isErr()) return Result.err(PolicyEvaluationErrors.invalidContext("AS_OF_DERIVATION", policyKey, nowResult.errorOrNull()));
+		const now = nowResult.getOrNull();
+		const asOfResult = PolicyAsOfResolver.derive(familyEntry.asOfSource, seed, now, this.options.asOf);
+		if (asOfResult.isErr()) return Result.err(PolicyEvaluationErrors.invalidContext("AS_OF_DERIVATION", policyKey, asOfResult.errorOrNull()));
+		const asOf = asOfResult.getOrNull();
+		const definitionResult = this.#findCandidates(policyKey, familyEntry.kind, asOf, input);
+		if (definitionResult.isErr()) return Result.err(definitionResult.errorOrNull());
+		const { definition: policyDefinition, catalogEntry: versionedCatalogEntry } = definitionResult.getOrNull();
+		this.#reportSafely({
+			kind: "policy-resolution",
+			level: "info",
+			policyKey,
+			definitionId: policyDefinition.id,
+			policyVersion: policyDefinition.policyVersion,
+			engineKind: policyDefinition.isGate() ? "GATE" : "COMPUTE",
+			engineVersion: policyDefinition.isGate() ? policyDefinition.gateEngineVersion : policyDefinition.computeEngineVersion,
+			occurredAt: now
+		});
+		const ctxResult = await this.contextBuilder.build(versionedCatalogEntry.contextRequirements, seed);
+		if (ctxResult.isErr()) return Result.err(PolicyEvaluationErrors.invalidContext("CONTEXT_BUILD", policyKey, ctxResult.errorOrNull()));
+		const context = ctxResult.getOrNull();
+		const decisionResult = this.#executeEngine(policyKey, policyDefinition, context);
+		if (decisionResult.isErr()) return Result.err(decisionResult.errorOrNull());
+		const decision = decisionResult.getOrNull();
+		const result = {
+			decisionId: input.decisionId,
+			ref: {
+				definitionId: policyDefinition.id,
+				policyKey: policyDefinition.policyKey,
+				policyVersion: policyDefinition.policyVersion,
+				payloadHash: policyDefinition.payloadHash,
+				...policyDefinition.isGate() ? { gateEngineVersion: policyDefinition.gateEngineVersion } : { computeEngineVersion: policyDefinition.computeEngineVersion }
+			},
+			kind: policyDefinition.kind,
+			asOf,
+			evaluatedAt: now,
+			contextVersion: input.contextVersion,
+			decision
+		};
+		return Result.ok(result);
+	}
+	#resolveCatalogVariant(definition) {
+		return this.catalog.getVersioned({
+			key: definition.policyKey,
+			kind: definition.kind,
+			...definition.isGate() ? { gateEngineVersion: definition.gateEngineVersion } : { computeEngineVersion: definition.computeEngineVersion },
+			payloadSchemaVersion: definition.payloadSchemaVersion
+		});
+	}
+	#resolveCatalogFamily(rawKey) {
+		const keyResult = PolicyKey.parse(rawKey);
+		if (keyResult.isErr()) return Result.err(PolicyEvaluationErrors.invalidPolicyKey(rawKey, keyResult.errorOrNull()));
+		const policyKey = keyResult.getOrNull().toString();
+		const catalogFamilyResult = this.catalog.getFamily(policyKey);
+		if (catalogFamilyResult.isErr()) return Result.err(PolicyEvaluationErrors.policyNotFound(policyKey, catalogFamilyResult.errorOrNull()));
+		return Result.ok({
+			key: policyKey,
+			family: catalogFamilyResult.getOrNull()
+		});
+	}
+	#findCandidates(policyKey, policyKind, asOf, input) {
+		const candidates = this.defRepo.findCandidates({
+			policyKey,
+			kind: policyKind,
+			asOf,
+			contextVersion: input.contextVersion,
+			scopeChain: input.scopeChain
+		});
+		const compatibleCandidates = [];
+		const compatibleCandidatesByDefinitionId = /* @__PURE__ */ new Map();
+		const incompatibleVariantErrorsByDefinitionId = /* @__PURE__ */ new Map();
+		for (const candidate of candidates) {
+			const compatibilityResult = this.#resolveCatalogVariant(candidate);
+			if (compatibilityResult.isErr()) {
+				incompatibleVariantErrorsByDefinitionId.set(candidate.id, compatibilityResult.errorOrNull());
+				continue;
+			}
+			const resolvedCandidate = {
+				definition: candidate,
+				catalogEntry: compatibilityResult.getOrNull()
+			};
+			compatibleCandidates.push(resolvedCandidate);
+			compatibleCandidatesByDefinitionId.set(candidate.id, resolvedCandidate);
+		}
+		if (compatibleCandidates.length === 0 && candidates.length > 0) {
+			const selectedCandidateResult = this.resolver.resolveBest(candidates);
+			if (selectedCandidateResult.isOk()) {
+				const selectedCandidate = selectedCandidateResult.getOrNull();
+				return Result.err(PolicyEvaluationErrors.policyVariantNotFound({
+					policyKey,
+					policyKind: selectedCandidate.kind,
+					payloadSchemaVersion: selectedCandidate.payloadSchemaVersion,
+					...selectedCandidate.isGate() ? { gateEngineVersion: selectedCandidate.gateEngineVersion } : { computeEngineVersion: selectedCandidate.computeEngineVersion },
+					cause: incompatibleVariantErrorsByDefinitionId.get(selectedCandidate.id) ?? "No compatible catalog variant matched the selected policy definition"
+				}));
+			}
+		}
+		const bestResult = this.resolver.resolveBest(compatibleCandidates.map((candidate) => candidate.definition));
+		if (bestResult.isErr()) return Result.err(PolicyEvaluationErrors.policyDefinitionNotFound(policyKey, asOf, input.contextVersion, bestResult.errorOrNull()));
+		const bestDefinition = bestResult.getOrNull();
+		const resolvedCandidate = compatibleCandidatesByDefinitionId.get(bestDefinition.id);
+		if (resolvedCandidate === void 0) return Result.err(PolicyEvaluationErrors.policyDefinitionNotFound(policyKey, asOf, input.contextVersion, `Resolved definition "${bestDefinition.id}" is not present among compatible catalog variants`));
+		return Result.ok(resolvedCandidate);
+	}
+	#executeEngine(policyKey, definition, context) {
+		if (definition.isGate()) {
+			const gateResult = this.gateEngines.evaluate(definition.gateEngineVersion, definition.payloadJson, context);
+			if (gateResult.isErr()) return Result.err(PolicyEvaluationErrors.engineFailure(policyKey, "GATE", definition.gateEngineVersion, gateResult.errorOrNull()));
+			return Result.ok(gateResult.getOrNull());
+		}
+		if (!definition.isCompute()) return Result.err(PolicyEvaluationErrors.policyVariantNotFound({
+			policyKey,
+			policyKind: definition.kind,
+			payloadSchemaVersion: definition.payloadSchemaVersion,
+			cause: `Unsupported policy kind "${definition.kind}"`
+		}));
+		const computeResult = this.computeRegistry.evaluate(policyKey, definition.computeEngineVersion, definition.payloadSchemaVersion, definition.payloadJson, context);
+		if (computeResult.isErr()) return Result.err(PolicyEvaluationErrors.engineFailure(policyKey, "COMPUTE", definition.computeEngineVersion, computeResult.errorOrNull()));
+		return Result.ok(computeResult.getOrNull());
+	}
+};
+//#endregion
+export { asPolicyDecisionId as _, ContextSeedValidator as a, asTenantId as b, ContextResolverRegistry as c, PolicyDefinition as d, InMemoryPolicyDefinitionRepository as f, PolicyCatalog as g, PolicyCatalogFactory as h, PolicyAsOfResolver as i, registerNamespacedContextResolversIn as l, PolicyKey as m, PolicyEvaluationErrors as n, contextResolverRegistry as o, PolicyScopeMatcher as p, PolicyResolver as r, registerNamespacedContextResolvers as s, PolicyService as t, PolicyContextBuilder as u, asPolicyDefinitionId as v, PolicyHashing as x, asSchoolId as y };
+
+//# sourceMappingURL=policy-service.js.map