@cullet/erp-core 1.0.0

package/src/core/policies/engines/v1/gate/gate-engine-v1.ts

@@ -0,0 +1,157 @@
+import { type CoreConfig, coreConfig } from "../../../../config";
+import { Outcome } from "../../../../result/outcome";
+import { Result } from "../../../../result/result";
+
+import {
+  ConditionEvaluatorV1,
+  type TracedConditionEvaluation,
+} from "../condition-evaluator";
+import type { ConditionLeafNode, ConditionNode } from "../condition-types";
+import type { GatePayload } from "../../gate-payload";
+import type {
+  GateOutcome,
+  GateStatus,
+  GateTraceLeafSnapshot,
+  GateTraceNodeSnapshot,
+  PolicyContext,
+  PolicyViolation,
+  VersionedGateEngine,
+} from "../../gate-types";
+
+// ─── Gate engine v1 ─────────────────────────────────────────────────────────
+
+export class GateEngineV1 implements VersionedGateEngine {
+  public readonly version = 1;
+  private readonly coreConfig: CoreConfig;
+
+  constructor(params: { readonly coreConfig?: CoreConfig } = {}) {
+    this.coreConfig = params.coreConfig ?? coreConfig;
+  }
+
+  private allow(): Result<GateOutcome, string> {
+    return Result.ok(Outcome.of("ALLOW", { violations: [] }));
+  }
+
+  private deny(violation: PolicyViolation): Result<GateOutcome, string> {
+    return Result.ok(
+      Outcome.of("DENY", {
+        violations: [violation],
+      }),
+    );
+  }
+
+  private outcomeFromStatus(
+    status: GateStatus,
+    violation: PolicyViolation,
+  ): Result<GateOutcome, string> {
+    return status === "ALLOW" ? this.allow() : this.deny(violation);
+  }
+
+  private isLeafNode(node: ConditionNode): node is ConditionLeafNode {
+    return "field" in node && "op" in node;
+  }
+
+  private toLeafSnapshot(node: ConditionLeafNode): GateTraceLeafSnapshot {
+    return {
+      kind: "LEAF",
+      field: node.field,
+      op: node.op,
+      ...(node.allowNull === true ? { allowNull: true } : {}),
+    };
+  }
+
+  private toNodeSnapshot(node: ConditionNode): GateTraceNodeSnapshot {
+    if (this.isLeafNode(node)) {
+      return this.toLeafSnapshot(node);
+    }
+
+    if ("and" in node) {
+      return {
+        kind: "AND",
+        childCount: node.and.length,
+      };
+    }
+
+    if ("or" in node) {
+      return {
+        kind: "OR",
+        childCount: node.or.length,
+      };
+    }
+
+    return {
+      kind: "NOT",
+    };
+  }
+
+  private buildDenyViolation(
+    conditionResult: TracedConditionEvaluation,
+  ): PolicyViolation {
+    return {
+      code: "DENY_CONDITION_MET",
+      message: `Gate denied at ${conditionResult.trace.conditionPath}`,
+      trace: {
+        conditionPath: conditionResult.trace.conditionPath,
+        decisiveNode: this.toNodeSnapshot(conditionResult.trace.decisiveNode),
+        lastEvaluatedLeaf: this.toLeafSnapshot(
+          conditionResult.trace.lastEvaluatedLeaf,
+        ),
+        lastEvaluatedLeafPath: conditionResult.trace.lastEvaluatedLeafPath,
+        lastEvaluatedLeafResult: conditionResult.trace.lastEvaluatedLeafResult,
+        field: conditionResult.trace.lastEvaluatedLeaf.field,
+        op: conditionResult.trace.lastEvaluatedLeaf.op,
+      },
+    };
+  }
+
+  private normalizePayload(payload: GatePayload): {
+    readonly allowIf: ConditionNode;
+    readonly defaultOutcome: "ALLOW" | "DENY";
+  } {
+    if ("condition" in payload) {
+      return {
+        allowIf: payload.condition,
+        defaultOutcome: "DENY",
+      };
+    }
+
+    return payload;
+  }
+
+  /**
+   * Evaluates a GATE payload against a context object.
+   * Pure function — no side effects.
+   *
+   * Receives an already-parsed `GatePayload`; the registry is responsible
+   * for parsing from raw `unknown` before calling this method.
+   * Returns Result for technical failures (condition evaluation errors).
+   * The Outcome inside carries the business decision (ALLOW/DENY).
+   */
+  evaluate(
+    payload: GatePayload,
+    context: PolicyContext,
+  ): Result<GateOutcome, string> {
+    const gatePayload = this.normalizePayload(payload);
+    const conditionEvaluator = new ConditionEvaluatorV1(
+      context,
+      this.coreConfig.getConditionEvaluationOptions(this.version),
+    );
+
+    const isAllowedResult = conditionEvaluator.evaluateWithTrace(
+      gatePayload.allowIf,
+    );
+    if (isAllowedResult.isErr()) {
+      return Result.err(isAllowedResult.errorOrNull()!);
+    }
+
+    const isAllowed = isAllowedResult.getOrNull()!;
+    if (isAllowed.matched) {
+      return this.allow();
+    }
+
+    return this.outcomeFromStatus(
+      gatePayload.defaultOutcome,
+      this.buildDenyViolation(isAllowed),
+    );
+  }
+}

package/src/core/policies/engines/v1/gate/gate-types-v1.ts

@@ -0,0 +1,12 @@
+// ─── Gate v1 payload types ───────────────────────────────────────────────────
+// The condition-tree DSL types are shared across the v1 engine family and live
+// in engines/v1. Imported here for the GatePayloadV1 definition only — not
+// re-exported; consumers should import condition types from engines/v1.
+import type { ConditionNode } from "../condition-types";
+
+export type GatePayloadV1 =
+  | { readonly condition: ConditionNode }
+  | {
+      readonly allowIf: ConditionNode;
+      readonly defaultOutcome: "ALLOW" | "DENY";
+    };

package/src/core/policies/engines/v1/gate/gate-v1-payload.schema.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+
+import { Result } from "../../../../result/result";
+
+import type { GatePayloadV1 } from "./gate-types-v1";
+import {
+  conditionLeafNodeSchema,
+  conditionNodeSchema,
+} from "../condition-schema";
+
+// Re-export so gate/v1 public API remains unchanged.
+export { conditionLeafNodeSchema, conditionNodeSchema };
+
+export class GatePayloadSchemaV1 {
+  static readonly schema = z.union([
+    z
+      .object({
+        condition: conditionNodeSchema,
+      })
+      .strict(),
+    z
+      .object({
+        allowIf: conditionNodeSchema,
+        defaultOutcome: z.enum(["ALLOW", "DENY"]),
+      })
+      .strict(),
+  ]);
+
+  static parse(payload: unknown): Result<GatePayloadV1, string> {
+    const parsed = GatePayloadSchemaV1.schema.safeParse(payload);
+    if (!parsed.success) {
+      const details = parsed.error.issues
+        .map((issue) => {
+          const path = issue.path.join(".");
+          return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+        })
+        .join("; ");
+
+      return Result.err(`Invalid gate payload: ${details}`);
+    }
+
+    return Result.ok(parsed.data as GatePayloadV1);
+  }
+}
+
+export const gatePayloadSchema = GatePayloadSchemaV1.schema;

package/src/core/policies/engines/v1/gate/index.ts

@@ -0,0 +1,9 @@
+export { ConditionEvaluatorV1 } from "../condition-evaluator";
+export { GateEngineV1 } from "./gate-engine-v1";
+export type { GatePayloadV1 } from "./gate-types-v1";
+export {
+  conditionLeafNodeSchema,
+  conditionNodeSchema,
+  gatePayloadSchema,
+  GatePayloadSchemaV1,
+} from "./gate-v1-payload.schema";

package/src/core/policies/engines/v1/index.ts

@@ -0,0 +1,13 @@
+export { ConditionEvaluatorV1 } from "./condition-evaluator";
+export {
+  conditionLeafNodeSchema,
+  conditionNodeSchema,
+} from "./condition-schema";
+export type {
+  ConditionAndNode,
+  ConditionLeafNode,
+  ConditionNode,
+  ConditionNotNode,
+  ConditionOp,
+  ConditionOrNode,
+} from "./condition-types";

package/src/core/policies/index.ts

@@ -0,0 +1,132 @@
+// Policy Engine — Pure Core
+// Re-exports all public types, classes and utilities.
+
+// ─── Core Config ────────────────────────────────────────────────────────────
+export type { CoreConfigOptions, CoreObservabilityConfig } from "../config";
+export { CoreConfig, coreConfig } from "../config";
+
+// ─── Result (technical execution) ───────────────────────────────────────────
+export { Err, Ok, Result } from "../result/result";
+
+// ─── Outcome (business decision) ───────────────────────────────────────────
+export type { CommonOutcomeStatus } from "../result/outcome";
+export { Outcome } from "../result/outcome";
+
+// ─── Utils ──────────────────────────────────────────────────────────────────
+export { PolicyHashing } from "./utils";
+export type {
+  PolicyDecisionId,
+  PolicyDefinitionId,
+  SchoolId,
+  TenantId,
+} from "./policy-ids";
+export {
+  asPolicyDecisionId,
+  asPolicyDefinitionId,
+  asSchoolId,
+  asTenantId,
+} from "./policy-ids";
+
+// ─── Catalog ────────────────────────────────────────────────────────────────
+export type {
+  AsOfSource,
+  PolicyCatalogEntryProps,
+  PolicyKind,
+  PolicyOwner,
+  PolicyScopeLevel,
+} from "./catalog";
+export { PolicyCatalog, PolicyCatalogFactory, PolicyKey } from "./catalog";
+
+// ─── Definitions ────────────────────────────────────────────────────────────
+export type {
+  BasePolicyDefinitionProps,
+  ComputePolicyDefinitionProps,
+  FindCandidatesParams,
+  GatePolicyDefinitionProps,
+  PolicyDefinitionProps,
+  PolicyDefinitionStatus,
+  PolicyScope,
+  ScopeChain,
+} from "./defs";
+export {
+  InMemoryPolicyDefinitionRepository,
+  PolicyDefinition,
+  PolicyScopeMatcher,
+} from "./defs";
+
+// ─── Context ────────────────────────────────────────────────────────────────
+export type {
+  ContextResolverCircuitBreakerOptions,
+  ContextResolverResilienceOptions,
+  ContextResolverRetryOptions,
+  ContextSeed,
+  ContextValueResolver,
+  PolicyContextBuilderOptions,
+} from "./context";
+export {
+  ContextSeedValidator,
+  ContextResolverRegistry,
+  contextResolverRegistry,
+  PolicyContextBuilder,
+  PolicyContextPath,
+  registerNamespacedContextResolvers,
+  registerNamespacedContextResolversIn,
+} from "./context";
+
+// ─── AsOf ───────────────────────────────────────────────────────────────────
+export type { DeriveAsOfOptions } from "./asof";
+export { PolicyAsOfResolver } from "./asof";
+
+// ─── Engines ────────────────────────────────────────────────────────────────
+export type {
+  ConditionEvaluationCause,
+  ConditionEvaluationOptions,
+  ConditionEvaluationReport,
+  ConditionEvaluationReportLevel,
+  ConditionEvaluationReportTag,
+  ConditionEvaluatorReporter,
+  GateOutcome,
+  GateOutcomeData,
+  GatePayload,
+  GateStatus,
+  GateTraceLeafSnapshot,
+  GateTraceNodeSnapshot,
+  GateViolationTrace,
+  PolicyContext,
+  PolicyViolation,
+  VersionedGateEngine,
+} from "./engines";
+export type {
+  ComputeEvaluator,
+  ComputeEvaluatorRegistration,
+  ComputeOutcome,
+  ComputeOutcomeData,
+  ComputeStatus,
+  VersionedComputeEngine,
+} from "./engines";
+export {
+  ComputeEngineRegistry,
+  ComputeEvaluatorRegistry,
+  ComputePayloadParsers,
+  ComputePayloadParserRegistry,
+  ComputeRegistry,
+  GateEngineRegistry,
+  GatePayloadParsers,
+} from "./engines";
+
+// ─── Resolver ───────────────────────────────────────────────────────────────
+export { PolicyResolver } from "./resolver";
+
+// ─── Service ────────────────────────────────────────────────────────────────
+export type {
+  EvaluateInput,
+  PolicyDecision,
+  PolicyEvaluationError,
+  PolicyEvaluationResult,
+  PolicyServiceParams,
+  PolicyServiceOptions,
+} from "./service";
+export { PolicyEvaluationErrors, PolicyService } from "./service";
+
+// ─── Package (contribution protocol) ────────────────────────────────────────
+export type { PolicyPackage } from "./package/policy-package";

package/src/core/policies/package/policy-package.ts

@@ -0,0 +1,17 @@
+import type { PolicyCatalogEntryProps } from "../catalog";
+import type { PolicyDefinition } from "../defs";
+import type { ComputeEvaluatorRegistration } from "../engines";
+
+/**
+ * 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.
+ */
+export interface PolicyPackage {
+  readonly catalogEntries: readonly PolicyCatalogEntryProps[];
+  readonly definitions: readonly PolicyDefinition[];
+  readonly evaluators: readonly ComputeEvaluatorRegistration[];
+}

package/src/core/policies/policy-ids.ts

@@ -0,0 +1,60 @@
+import { ValidationCode } from "../exceptions/validation-code";
+import { InvalidValueException } from "../exceptions/validation-exception";
+import { ValidationField } from "../exceptions/validation-field";
+
+type Brand<TValue, TBrand extends string> = TValue & {
+  readonly __brand: TBrand;
+};
+
+export type PolicyDefinitionId = Brand<string, "PolicyDefinitionId">;
+export type PolicyDecisionId = Brand<string, "PolicyDecisionId">;
+export type TenantId = Brand<string, "TenantId">;
+export type SchoolId = Brand<string, "SchoolId">;
+
+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: unknown, field: ValidationField): string {
+  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<TBrand extends string>(
+  value: unknown,
+  field: ValidationField,
+): Brand<string, TBrand> {
+  return assertIdString(value, field) as Brand<string, TBrand>;
+}
+
+export function asPolicyDefinitionId(value: string): PolicyDefinitionId {
+  return brandId<"PolicyDefinitionId">(value, POLICY_DEFINITION_ID_FIELD);
+}
+
+export function asPolicyDecisionId(value: string): PolicyDecisionId {
+  return brandId<"PolicyDecisionId">(value, POLICY_DECISION_ID_FIELD);
+}
+
+export function asTenantId(value: string): TenantId {
+  return brandId<"TenantId">(value, TENANT_ID_FIELD);
+}
+
+export function asSchoolId(value: string): SchoolId {
+  return brandId<"SchoolId">(value, SCHOOL_ID_FIELD);
+}

package/src/core/policies/resolver/index.ts

@@ -0,0 +1 @@
+export { PolicyResolver } from "./policy-resolver";

package/src/core/policies/resolver/policy-resolver.ts

@@ -0,0 +1,57 @@
+import type { PolicyDefinition } from "../defs";
+import { PolicyScopeMatcher } from "../defs";
+import { comparePolicySemver } from "../defs/policy-semver";
+import { Result } from "../../result/result";
+
+/**
+ * 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)
+ */
+export class PolicyResolver {
+  resolveBest(
+    candidates: readonly PolicyDefinition[],
+  ): Result<PolicyDefinition, string> {
+    if (candidates.length === 0) {
+      return Result.err(
+        "No matching policy definition found (candidates list is empty)",
+      );
+    }
+
+    const sorted = [...candidates].sort((a, b) => {
+      // 1) Scope specificity (higher weight = more specific)
+      const scopeDiff =
+        PolicyScopeMatcher.weight(b.scope.level) -
+        PolicyScopeMatcher.weight(a.scope.level);
+      if (scopeDiff !== 0) return scopeDiff;
+
+      // 2) Priority DESC
+      const priorityDiff = b.priority - a.priority;
+      if (priorityDiff !== 0) return priorityDiff;
+
+      // 3) publishedAt DESC (fallback createdAt)
+      const aDate = a.publishedAt ?? a.createdAt;
+      const bDate = b.publishedAt ?? b.createdAt;
+      const dateDiff = bDate.getTime() - aDate.getTime();
+      if (dateDiff !== 0) return dateDiff;
+
+      // 4) Engine version DESC — prefers the definition running on the most
+      //    capable engine when scope/priority/date are identical.
+      const aEngine = a.gateEngineVersion ?? a.computeEngineVersion ?? 0;
+      const bEngine = b.gateEngineVersion ?? b.computeEngineVersion ?? 0;
+      const engineDiff = bEngine - aEngine;
+      if (engineDiff !== 0) return engineDiff;
+
+      // 5) policyVersion DESC (semver) — final deterministic tiebreaker so
+      //    the winner never depends on repository return order.
+      return comparePolicySemver(b.policyVersion, a.policyVersion);
+    });
+
+    return Result.ok(sorted[0]);
+  }
+}

package/src/core/policies/service/index.ts

@@ -0,0 +1,10 @@
+export { PolicyService } from "./policy-service";
+export { PolicyEvaluationErrors } from "./policy-evaluation-error";
+export type {
+  EvaluateInput,
+  PolicyDecision,
+  PolicyEvaluationError,
+  PolicyEvaluationResult,
+  PolicyServiceOptions,
+  PolicyServiceParams,
+} from "./policy-service";

package/src/core/policies/service/policy-evaluation-error.ts

@@ -0,0 +1,148 @@
+import type { PolicyKind } from "../catalog";
+
+// ─── Error Union ─────────────────────────────────────────────────────────────
+
+export type PolicyEvaluationError =
+  | {
+      readonly kind: "INVALID_CONTEXT";
+      readonly stage: "SEED_VALIDATION" | "AS_OF_DERIVATION" | "CONTEXT_BUILD";
+      readonly policyKey: string;
+      readonly message: string;
+      readonly cause: string;
+    }
+  | {
+      readonly kind: "INVALID_POLICY_KEY";
+      readonly rawPolicyKey: string;
+      readonly message: string;
+      readonly cause: string;
+    }
+  | {
+      readonly kind: "POLICY_NOT_FOUND";
+      readonly policyKey: string;
+      readonly message: string;
+      readonly cause: string;
+    }
+  | {
+      readonly kind: "POLICY_DEFINITION_NOT_FOUND";
+      readonly policyKey: string;
+      readonly contextVersion: number;
+      readonly asOf: Date;
+      readonly message: string;
+      readonly cause: string;
+    }
+  | {
+      readonly kind: "POLICY_VARIANT_NOT_FOUND";
+      readonly policyKey: string;
+      readonly policyKind: PolicyKind;
+      readonly payloadSchemaVersion: number;
+      readonly gateEngineVersion?: number;
+      readonly computeEngineVersion?: number;
+      readonly message: string;
+      readonly cause: string;
+    }
+  | {
+      readonly kind: "ENGINE_FAILURE";
+      readonly policyKey: string;
+      readonly engine: PolicyKind;
+      readonly engineVersion: number;
+      readonly message: string;
+      readonly cause: string;
+    };
+
+// ─── Factory object ─────────────────────────────────────────────────────────
+
+export class PolicyEvaluationErrors {
+  static invalidContext(
+    stage: Extract<PolicyEvaluationError, { kind: "INVALID_CONTEXT" }>["stage"],
+    policyKey: string,
+    cause: string,
+  ): PolicyEvaluationError {
+    return {
+      kind: "INVALID_CONTEXT",
+      stage,
+      policyKey,
+      message: "Policy evaluation context is invalid",
+      cause,
+    };
+  }
+
+  static invalidPolicyKey(
+    rawPolicyKey: string,
+    cause: string,
+  ): PolicyEvaluationError {
+    return {
+      kind: "INVALID_POLICY_KEY",
+      rawPolicyKey,
+      message: "Policy key is invalid",
+      cause,
+    };
+  }
+
+  static policyNotFound(
+    policyKey: string,
+    cause: string,
+  ): PolicyEvaluationError {
+    return {
+      kind: "POLICY_NOT_FOUND",
+      policyKey,
+      message: "Policy is not registered in the catalog",
+      cause,
+    };
+  }
+
+  static policyDefinitionNotFound(
+    policyKey: string,
+    asOf: Date,
+    contextVersion: number,
+    cause: string,
+  ): PolicyEvaluationError {
+    return {
+      kind: "POLICY_DEFINITION_NOT_FOUND",
+      policyKey,
+      contextVersion,
+      asOf,
+      message: "No published policy definition matched the evaluation inputs",
+      cause,
+    };
+  }
+
+  static policyVariantNotFound(params: {
+    readonly policyKey: string;
+    readonly policyKind: PolicyKind;
+    readonly payloadSchemaVersion: number;
+    readonly gateEngineVersion?: number;
+    readonly computeEngineVersion?: number;
+    readonly cause: string;
+  }): PolicyEvaluationError {
+    return {
+      kind: "POLICY_VARIANT_NOT_FOUND",
+      policyKey: params.policyKey,
+      policyKind: params.policyKind,
+      payloadSchemaVersion: params.payloadSchemaVersion,
+      ...(params.gateEngineVersion !== undefined
+        ? { gateEngineVersion: params.gateEngineVersion }
+        : {}),
+      ...(params.computeEngineVersion !== undefined
+        ? { computeEngineVersion: params.computeEngineVersion }
+        : {}),
+      message: "No catalog variant matched the selected policy definition",
+      cause: params.cause,
+    };
+  }
+
+  static engineFailure(
+    policyKey: string,
+    engine: PolicyKind,
+    engineVersion: number,
+    cause: string,
+  ): PolicyEvaluationError {
+    return {
+      kind: "ENGINE_FAILURE",
+      policyKey,
+      engine,
+      engineVersion,
+      message: "Policy engine evaluation failed",
+      cause,
+    };
+  }
+}