@cullet/erp-core 1.0.10 → 1.1.0

package/dist/policy-service.d.ts

@@ -1,36 +1,6 @@
-import { C as TenantId, I as Result, S as SchoolId, b as PolicyDecisionId, g as CoreConfig, t as GateOutcome, u as GatePayload, x as PolicyDefinitionId, y as PolicyReporter } from "./gate-types.js";
-import { _ as ComputePayload, c as ComputeRegistry, f as ComputeEvaluatorRegistration, p as ComputeOutcome, s as GateEngineRegistry } from "./parse-gate-payload.js";
+import { C as TenantId, I as Result, S as SchoolId, b as PolicyDecisionId, t as GateOutcome, u as GatePayload, x as PolicyDefinitionId, y as PolicyReporter } from "./gate-types.js";
+import { a as ComputeOutcome, l as ComputePayload, n as ComputeRegistry, t as GateEngineRegistry } from "./gate-engine-registry.js";
 
-//#region src/core/config/core-config.instance.d.ts
-
-/**
- * Shared instance for the application composition root.
- * Use `new CoreConfig()` for isolated runtimes, tests, or multi-tenant hosts.
- *
- * The default reporter is silent so the core has no runtime logging dependency.
- * Hosts can swap in their own `PolicyReporter` via
- * `coreConfig.configure({ observability: { reporter } })`.
- */
-declare const coreConfig: CoreConfig;
-//#endregion
-//#region src/core/policies/utils/hash.d.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.
- */
-declare class PolicyHashing {
-  static sha256(input: string): string;
-  private static assertHashable;
-  static canonicalJson(value: unknown): string;
-  static computePayloadHash(payload: unknown, policyKey: string, policyVersion: string): string;
-}
-//#endregion
 //#region src/core/policies/catalog/catalog-types.d.ts
 type PolicyKind = "GATE" | "COMPUTE";
 type PolicyOwner = "PLATFORM_OWNER" | "TENANT_ADMIN" | "SCHOOL_ADMIN";
@@ -116,9 +86,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 +130,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
@@ -253,39 +259,6 @@ interface PolicyDefinitionRepository {
   findCandidates(params: FindCandidatesParams): PolicyDefinition[];
 }
 //#endregion
-//#region src/core/policies/defs/in-memory-policy-definition-repo.d.ts
-declare class InMemoryPolicyDefinitionRepository implements PolicyDefinitionRepository {
-  private readonly definitions;
-  private readonly definitionsByPolicyKey;
-  constructor(definitions: readonly PolicyDefinition[]);
-  findCandidates(params: FindCandidatesParams): PolicyDefinition[];
-}
-//#endregion
-//#region src/core/policies/package/policy-package.d.ts
-/**
- * Protocol of contribution: a module declares what it wants to add to the
- * policy system without the core knowing which module it is.
- *
- * - catalogEntries: static policy descriptors the catalog will register.
- * - definitions:   default policy definitions (rules/parameters) to seed.
- * - evaluators:    compute evaluator registrations keyed by policy/version.
- */
-interface PolicyPackage {
-  readonly catalogEntries: readonly PolicyCatalogEntryProps[];
-  readonly definitions: readonly PolicyDefinition[];
-  readonly evaluators: readonly ComputeEvaluatorRegistration[];
-}
-//#endregion
-//#region src/core/policies/catalog/catalog.instance.d.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.
- */
-declare class PolicyCatalogFactory {
-  static build(packages: readonly PolicyPackage[]): PolicyCatalog;
-}
-//#endregion
 //#region src/core/policies/context/context-seed.d.ts
 /**
  * Seed data provided by the use case / caller.
@@ -381,26 +354,6 @@ declare class PolicyContextBuilder {
   build(requirements: readonly string[], seed: ContextSeed): Promise<Result<Record<string, unknown>, string>>;
 }
 //#endregion
-//#region src/core/policies/context/context-registry.instance.d.ts
-/**
- * Official instance of the ContextResolverRegistry.
- * Use `new ContextResolverRegistry()` plus `registerNamespacedContextResolversIn`
- * when each runtime/composition root needs its own isolated resolver graph.
- */
-declare const contextResolverRegistry: ContextResolverRegistry;
-declare function registerNamespacedContextResolvers(namespace: string, resolvers: readonly ContextValueResolver[]): Result<ContextResolverRegistry, string>;
-//#endregion
-//#region src/core/policies/context/path.d.ts
-declare class PolicyContextPath {
-  private static readonly FORBIDDEN_SEGMENTS;
-  private static resolve;
-  private static parseSegments;
-  private static isPlainRecord;
-  static getOrAbsent(obj: Record<string, unknown>, path: string): Result<unknown, "absent">;
-  static has(obj: Record<string, unknown>, path: string): boolean;
-  static set(obj: Record<string, unknown>, path: string, value: unknown): Result<void, string>;
-}
-//#endregion
 //#region src/core/policies/asof/asof.d.ts
 interface DeriveAsOfOptions {
   readonly maxFutureYears?: number;
@@ -422,6 +375,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 +448,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 +462,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 +489,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 +513,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,8 +536,23 @@ 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
-export { FindCandidatesParams as A, PolicyKey as B, ContextSeed as C, InMemoryPolicyDefinitionRepository as D, PolicyPackage as E, PolicyScope as F, PolicyHashing as G, PolicyKind as H, PolicyScopeMatcher as I, coreConfig as K, ScopeChain as L, PolicyDefinition as M, PolicyDefinitionProps as N, BasePolicyDefinitionProps as O, PolicyDefinitionStatus as P, PolicyCatalog as R, ContextValueResolver as S, PolicyCatalogFactory as T, PolicyOwner as U, AsOfSource as V, PolicyScopeLevel as W, ContextResolverRegistry as _, PolicyServiceOptions as a, ContextResolverResilienceOptions as b, PolicyEvaluationErrors as c, PolicyAsOfResolver as d, PolicyContextPath as f, PolicyContextBuilderOptions as g, PolicyContextBuilder as h, PolicyService as i, GatePolicyDefinitionProps as j, ComputePolicyDefinitionProps as k, PolicyResolver as l, registerNamespacedContextResolvers as m, PolicyDecision as n, PolicyServiceParams as o, contextResolverRegistry as p, PolicyEvaluationResult as r, PolicyEvaluationError as s, EvaluateInput as t, DeriveAsOfOptions as u, registerNamespacedContextResolversIn as v, ContextSeedValidator as w, ContextResolverRetryOptions as x, ContextResolverCircuitBreakerOptions as y, PolicyCatalogEntryProps as z };
+export { PolicyScope as A, BasePolicyDefinitionProps as C, PolicyDefinition as D, GatePolicyDefinitionProps as E, PolicyKey as F, AsOfSource as I, PolicyKind as L, ScopeChain as M, PolicyCatalog as N, PolicyDefinitionProps as O, PolicyCatalogEntryProps as P, PolicyOwner as R, PolicyDefinitionRepository as S, FindCandidatesParams as T, ContextResolverResilienceOptions as _, PolicyServiceOptions as a, ContextSeed as b, PolicyEvaluationErrors as c, PolicyAsOfResolver as d, PolicyContextBuilder as f, ContextResolverCircuitBreakerOptions as g, registerNamespacedContextResolversIn as h, PolicyService as i, PolicyScopeMatcher as j, PolicyDefinitionStatus as k, PolicyResolver as l, ContextResolverRegistry as m, PolicyDecision as n, PolicyServiceParams as o, PolicyContextBuilderOptions as p, PolicyEvaluationResult as r, PolicyEvaluationError as s, EvaluateInput as t, DeriveAsOfOptions as u, ContextResolverRetryOptions as v, ComputePolicyDefinitionProps as w, ContextSeedValidator as x, ContextValueResolver as y, PolicyScopeLevel as z };
 //# sourceMappingURL=policy-service.d.ts.map

package/dist/policy-service.js

@@ -1,6 +1,9 @@
-import { a as stableStringify, i as sha256Hex, n as UnexpectedError, t as ValidationCode } from "./validation-code.js";
+import { n as UnexpectedError, t as ValidationCode } from "./validation-code.js";
+import { n as sha256Hex, r as stableStringify } from "./hashing.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";
+import { i as InvariantViolationException, r as isValidDate } from "./temporal-guards.js";
+import { t as InvalidValueException } from "./validation-exception.js";
+import { f as SilentPolicyReporter, 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.
@@ -49,20 +52,6 @@ var PolicyHashing = class PolicyHashing {
 	}
 };
 //#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");
@@ -191,6 +180,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 +206,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 +223,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 +259,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 +759,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 +850,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 +885,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()) {