@cullet/erp-core 1.0.0

package/src/core/policies/context/path.ts

@@ -0,0 +1,152 @@
+/**
+ * Utilities for reading/writing values at dot-separated paths
+ * in plain objects, e.g. "installment.dueDate".
+ */
+
+import { Result } from "../../result/result";
+
+export class PolicyContextPath {
+  private static readonly FORBIDDEN_SEGMENTS = new Set([
+    "__proto__",
+    "prototype",
+    "constructor",
+  ]);
+
+  private static resolve(
+    obj: Record<string, unknown>,
+    path: string,
+  ): Result<
+    {
+      readonly found: boolean;
+      readonly value: unknown;
+    },
+    string
+  > {
+    const segmentsResult = PolicyContextPath.parseSegments(path);
+    if (segmentsResult.isErr()) {
+      return Result.err(segmentsResult.errorOrNull()!);
+    }
+
+    const segments = segmentsResult.getOrNull()!;
+    let current: unknown = obj;
+
+    for (const segment of segments) {
+      if (
+        current === null ||
+        current === undefined ||
+        typeof current !== "object"
+      ) {
+        return Result.ok({ found: false, value: undefined });
+      }
+
+      const record = current as Record<string, unknown>;
+      if (!Object.prototype.hasOwnProperty.call(record, segment)) {
+        return Result.ok({ found: false, value: undefined });
+      }
+
+      current = record[segment];
+    }
+
+    return Result.ok({ found: true, value: current });
+  }
+
+  private static parseSegments(
+    path: string,
+  ): Result<readonly string[], string> {
+    if (path.trim().length === 0) {
+      return Result.err("Path cannot be empty");
+    }
+
+    const segments = path.split(".");
+    if (segments.some((segment) => segment.length === 0)) {
+      return Result.err(`Path "${path}" contains an empty segment`);
+    }
+
+    const forbiddenSegment = segments.find((segment) =>
+      PolicyContextPath.FORBIDDEN_SEGMENTS.has(segment),
+    );
+    if (forbiddenSegment !== undefined) {
+      return Result.err(
+        `Path "${path}" contains forbidden segment "${forbiddenSegment}"`,
+      );
+    }
+
+    return Result.ok(segments);
+  }
+
+  private static isPlainRecord(
+    value: unknown,
+  ): value is Record<string, unknown> {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return false;
+    }
+
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+  }
+
+  static getOrAbsent(
+    obj: Record<string, unknown>,
+    path: string,
+  ): Result<unknown, "absent"> {
+    const resolvedPath = PolicyContextPath.resolve(obj, path);
+    if (resolvedPath.isErr()) {
+      return Result.err("absent");
+    }
+
+    const { found, value } = resolvedPath.getOrNull()!;
+    if (!found) {
+      return Result.err("absent");
+    }
+
+    return Result.ok(value);
+  }
+
+  static has(obj: Record<string, unknown>, path: string): boolean {
+    const resolvedPath = PolicyContextPath.resolve(obj, path);
+    if (resolvedPath.isErr()) {
+      return false;
+    }
+
+    return resolvedPath.getOrNull()!.found;
+  }
+
+  static set(
+    obj: Record<string, unknown>,
+    path: string,
+    value: unknown,
+  ): Result<void, string> {
+    const segmentsResult = PolicyContextPath.parseSegments(path);
+    if (segmentsResult.isErr()) {
+      return Result.err(segmentsResult.errorOrNull()!);
+    }
+
+    const segments = segmentsResult.getOrNull()!;
+    let current: Record<string, unknown> = obj;
+
+    for (let i = 0; i < segments.length - 1; i++) {
+      const seg = segments[i];
+      const next = current[seg];
+
+      if (next === undefined) {
+        const container = Object.create(null) as Record<string, unknown>;
+        current[seg] = container;
+        current = container;
+        continue;
+      }
+
+      if (!PolicyContextPath.isPlainRecord(next)) {
+        return Result.err(
+          `Cannot create nested path "${path}" because "${segments
+            .slice(0, i + 1)
+            .join(".")}" already contains a non-plain object`,
+        );
+      }
+
+      current = next;
+    }
+
+    current[segments[segments.length - 1]] = value;
+    return Result.ok(undefined);
+  }
+}

package/src/core/policies/defs/in-memory-policy-definition-repo.ts

@@ -0,0 +1,73 @@
+import type {
+  FindCandidatesParams,
+  PolicyDefinition,
+} from "./policy-definition";
+import type { PolicyDefinitionRepository } from "./policy-definition-repository";
+import { PolicyScopeMatcher } from "./policy-scope";
+
+export class InMemoryPolicyDefinitionRepository implements PolicyDefinitionRepository {
+  private readonly definitions: readonly PolicyDefinition[];
+  private readonly definitionsByPolicyKey: ReadonlyMap<
+    string,
+    readonly PolicyDefinition[]
+  >;
+
+  constructor(definitions: readonly PolicyDefinition[]) {
+    this.definitions = definitions;
+    this.definitionsByPolicyKey = definitions.reduce<
+      Map<string, PolicyDefinition[]>
+    >((index, definition) => {
+      const existingDefinitions = index.get(definition.policyKey) ?? [];
+      existingDefinitions.push(definition);
+      index.set(definition.policyKey, existingDefinitions);
+      return index;
+    }, new Map<string, PolicyDefinition[]>());
+  }
+
+  findCandidates(params: FindCandidatesParams): PolicyDefinition[] {
+    const {
+      policyKey,
+      kind,
+      payloadSchemaVersion,
+      asOf,
+      contextVersion,
+      scopeChain,
+    } = params;
+
+    const candidatesForPolicyKey =
+      this.definitionsByPolicyKey.get(policyKey) ?? [];
+
+    const candidates = candidatesForPolicyKey.filter((def) => {
+      // Match kind
+      if (def.kind !== kind) return false;
+      if (
+        payloadSchemaVersion !== undefined &&
+        def.payloadSchemaVersion !== payloadSchemaVersion
+      ) {
+        return false;
+      }
+
+      if (!def.enabled) return false;
+
+      // Only PUBLISHED
+      if (def.status !== "PUBLISHED") return false;
+
+      // Effective date range (effectiveFrom <= asOf, and effectiveTo is null or > asOf)
+      if (def.effectiveFrom > asOf) return false;
+      if (def.effectiveTo !== null && def.effectiveTo <= asOf) return false;
+
+      // Context version compatibility
+      if (contextVersion < def.contextVersionMin) return false;
+      if (contextVersion > def.contextVersionMax) return false;
+
+      // Scope must match one of the chain entries
+      if (!PolicyScopeMatcher.matchesChain(def.scope, scopeChain)) {
+        return false;
+      }
+
+      return true;
+    });
+
+    return candidates;
+  }
+}

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

@@ -0,0 +1,20 @@
+export { InMemoryPolicyDefinitionRepository } from "./in-memory-policy-definition-repo";
+export type {
+  BasePolicyDefinitionProps,
+  ComputePolicyDefinitionInput,
+  ComputePolicyDefinitionProps,
+  FindCandidatesParams,
+  GatePolicyDefinitionInput,
+  GatePolicyDefinitionProps,
+  PolicyDefinitionProps,
+  PolicyDefinitionStatus,
+} from "./policy-definition";
+export { PolicyDefinition } from "./policy-definition";
+export type { PolicyDefinitionRepository } from "./policy-definition-repository";
+export type {
+  AnyPolicyPayload,
+  PayloadForKey,
+} from "./policy-payload.contracts";
+export { comparePolicySemver, POLICY_SEMVER_PATTERN } from "./policy-semver";
+export type { PolicyScope, ScopeChain } from "./policy-scope";
+export { PolicyScopeMatcher } from "./policy-scope";

package/src/core/policies/defs/policy-definition-repository.ts

@@ -0,0 +1,8 @@
+import type {
+  FindCandidatesParams,
+  PolicyDefinition,
+} from "./policy-definition";
+
+export interface PolicyDefinitionRepository {
+  findCandidates(params: FindCandidatesParams): PolicyDefinition[];
+}

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

@@ -0,0 +1,192 @@
+import { InvariantViolationException } from "../../exceptions/invariant-violation-exception";
+import type { PolicyKind } from "../catalog";
+import type { PolicyDefinitionId } from "../policy-ids";
+
+import type { AnyPolicyPayload } from "./policy-payload.contracts";
+import type { PolicyScope } from "./policy-scope";
+import { POLICY_SEMVER_PATTERN } from "./policy-semver";
+
+// ─── Status ────────────────────────────────────────────────────────────────
+
+export type PolicyDefinitionStatus = "DRAFT" | "PUBLISHED" | "RETIRED";
+
+// ─── Definition props ───────────────────────────────────────────────────────
+
+export interface BasePolicyDefinitionProps<
+  K extends string = string,
+  P extends AnyPolicyPayload = AnyPolicyPayload,
+> {
+  readonly id: PolicyDefinitionId;
+  readonly policyKey: K;
+  readonly policyVersion: string; // semver
+  readonly payloadSchemaVersion: number;
+  readonly contextVersionMin: number;
+  readonly contextVersionMax: number;
+  readonly enabled: boolean;
+  readonly status: PolicyDefinitionStatus;
+  readonly scope: PolicyScope;
+  readonly effectiveFrom: Date;
+  readonly effectiveTo: Date | null;
+  readonly priority: number;
+  readonly payloadJson: P;
+  readonly payloadHash: string;
+  readonly createdAt: Date;
+  readonly publishedAt: Date | null;
+}
+
+export interface GatePolicyDefinitionProps<
+  K extends string = string,
+  P extends AnyPolicyPayload = AnyPolicyPayload,
+> extends BasePolicyDefinitionProps<K, P> {
+  readonly kind: "GATE";
+  readonly gateEngineVersion: number;
+}
+
+export interface ComputePolicyDefinitionProps<
+  K extends string = string,
+  P extends AnyPolicyPayload = AnyPolicyPayload,
+> extends BasePolicyDefinitionProps<K, P> {
+  readonly kind: "COMPUTE";
+  readonly computeEngineVersion: number;
+}
+
+export type GatePolicyDefinitionInput<
+  K extends string = string,
+  P extends AnyPolicyPayload = AnyPolicyPayload,
+> = Omit<GatePolicyDefinitionProps<K, P>, "kind" | "enabled"> & {
+  readonly enabled?: boolean;
+};
+
+export type ComputePolicyDefinitionInput<
+  K extends string = string,
+  P extends AnyPolicyPayload = AnyPolicyPayload,
+> = Omit<ComputePolicyDefinitionProps<K, P>, "kind" | "enabled"> & {
+  readonly enabled?: boolean;
+};
+
+export type PolicyDefinitionProps<
+  K extends string = string,
+  P extends AnyPolicyPayload = AnyPolicyPayload,
+> = GatePolicyDefinitionProps<K, P> | ComputePolicyDefinitionProps<K, P>;
+
+// ─── Definition row (as if loaded from database) ────────────────────────────
+
+export class PolicyDefinition<
+  K extends string = string,
+  P extends AnyPolicyPayload = AnyPolicyPayload,
+> {
+  private static assertPolicyVersionIsSemver(policyVersion: string): void {
+    if (!POLICY_SEMVER_PATTERN.test(policyVersion)) {
+      throw new InvariantViolationException(
+        `PolicyDefinition.policyVersion must be a valid semver. Received: "${policyVersion}"`,
+      );
+    }
+  }
+
+  public readonly id: PolicyDefinitionId;
+  public readonly policyKey: K;
+
+  public readonly policyVersion: string;
+  public readonly payloadSchemaVersion: number;
+  public readonly contextVersionMin: number;
+  public readonly contextVersionMax: number;
+  public readonly gateEngineVersion?: number;
+  public readonly computeEngineVersion?: number;
+
+  public readonly enabled: boolean;
+  public readonly status: PolicyDefinitionStatus;
+  public readonly scope: PolicyScope;
+  public readonly effectiveFrom: Date;
+  public readonly effectiveTo: Date | null;
+  public readonly priority: number;
+  public readonly payloadJson: P;
+  public readonly payloadHash: string;
+  public readonly createdAt: Date;
+  public readonly publishedAt: Date | null;
+  public readonly kind: PolicyKind;
+
+  private constructor(props: PolicyDefinitionProps<K, P>) {
+    // The static factories are the supported API. This guard stays here because
+    // TypeScript privacy does not protect runtime-only construction paths.
+    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 === undefined) {
+        throw new InvariantViolationException(
+          `PolicyDefinition of kind 'GATE' must have a 'gateEngineVersion'. Policy key: ${props.policyKey}`,
+        );
+      }
+      this.gateEngineVersion = props.gateEngineVersion;
+    } else {
+      if (props.computeEngineVersion === undefined) {
+        throw new InvariantViolationException(
+          `PolicyDefinition of kind 'COMPUTE' must have a 'computeEngineVersion'. Policy key: ${props.policyKey}`,
+        );
+      }
+      this.computeEngineVersion = props.computeEngineVersion;
+    }
+  }
+
+  static gate<K extends string, P extends AnyPolicyPayload = AnyPolicyPayload>(
+    props: GatePolicyDefinitionInput<K, P>,
+  ): PolicyDefinition<K, P> {
+    return new PolicyDefinition<K, P>({
+      ...props,
+      enabled: props.enabled ?? true,
+      kind: "GATE",
+    });
+  }
+
+  static compute<
+    K extends string,
+    P extends AnyPolicyPayload = AnyPolicyPayload,
+  >(props: ComputePolicyDefinitionInput<K, P>): PolicyDefinition<K, P> {
+    return new PolicyDefinition<K, P>({
+      ...props,
+      enabled: props.enabled ?? true,
+      kind: "COMPUTE",
+    });
+  }
+
+  isGate(): this is PolicyDefinition<K, P> & {
+    readonly kind: "GATE";
+    readonly gateEngineVersion: number;
+  } {
+    return this.kind === "GATE";
+  }
+
+  isCompute(): this is PolicyDefinition<K, P> & {
+    readonly kind: "COMPUTE";
+    readonly computeEngineVersion: number;
+  } {
+    return this.kind === "COMPUTE";
+  }
+}
+
+// ─── Query parameters ───────────────────────────────────────────────────────
+
+export interface FindCandidatesParams {
+  readonly policyKey: string;
+  readonly kind: PolicyKind;
+  readonly payloadSchemaVersion?: number;
+  readonly asOf: Date;
+  readonly contextVersion: number;
+  readonly scopeChain: readonly PolicyScope[];
+}

package/src/core/policies/defs/policy-payload.contracts.ts

@@ -0,0 +1,13 @@
+import type { ComputePayload, GatePayload } from "../engines";
+
+export type AnyPolicyPayload = GatePayload | ComputePayload;
+
+/**
+ * Payload type associated with a policy key.
+ *
+ * Intentionally NOT backed by global module augmentation: two modules registering
+ * different shapes for the same literal key would silently override each other and
+ * the last `declare module` wins. Per-key payload typing must be expressed
+ * explicitly at the definition site (see {@link PolicyDefinition} type params).
+ */
+export type PayloadForKey<_K extends string> = AnyPolicyPayload;

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

@@ -0,0 +1,53 @@
+import type { PolicyScopeLevel } from "../catalog";
+import type { SchoolId, TenantId } from "../policy-ids";
+
+/**
+ * Scope attached to a PolicyDefinition — defines where it applies.
+ */
+export interface PolicyScope {
+  readonly level: PolicyScopeLevel;
+  readonly tenantId: TenantId | null;
+  readonly schoolId: SchoolId | null;
+}
+
+/**
+ * Ordered list of scopes from most-specific to least-specific.
+ * Used by the resolver to match definitions.
+ *
+ * Example:
+ * ```
+ * [
+ *   { level: 'SCHOOL',  tenantId: 't1', schoolId: 's1' },
+ *   { level: 'TENANT',  tenantId: 't1', schoolId: null },
+ *   { level: 'GLOBAL',  tenantId: null, schoolId: null },
+ * ]
+ * ```
+ */
+export type ScopeChain = readonly PolicyScope[];
+
+/**
+ * Numeric weight for scope specificity (higher = more specific).
+ */
+const SCOPE_WEIGHT: Record<PolicyScopeLevel, number> = {
+  SCHOOL: 3,
+  TENANT: 2,
+  GLOBAL: 1,
+};
+
+export class PolicyScopeMatcher {
+  static weight(level: PolicyScopeLevel): number {
+    return SCOPE_WEIGHT[level];
+  }
+
+  static matchesChain(defScope: PolicyScope, chain: ScopeChain): boolean {
+    return chain.some((scope) => PolicyScopeMatcher.equals(defScope, scope));
+  }
+
+  static equals(a: PolicyScope, b: PolicyScope): boolean {
+    return (
+      a.level === b.level &&
+      a.tenantId === b.tenantId &&
+      a.schoolId === b.schoolId
+    );
+  }
+}

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

@@ -0,0 +1,83 @@
+// Semver without build metadata: comparisons are defined only over
+// major.minor.patch and optional pre-release identifiers (semver §11).
+export 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-]+)*))?$/;
+
+interface ParsedSemver {
+  major: number;
+  minor: number;
+  patch: number;
+  preRelease: string | null;
+}
+
+function parseSemver(version: string): ParsedSemver {
+  const withoutBuild = version.split("+")[0];
+  const [core, preRelease = null] = withoutBuild.split("-") as [
+    string,
+    string | undefined,
+  ];
+  const [major, minor, patch] = core.split(".").map(Number) as [
+    number,
+    number,
+    number,
+  ];
+  return { major, minor, patch, preRelease: preRelease ?? null };
+}
+
+function comparePreRelease(a: string, b: string): number {
+  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];
+
+    // Shorter pre-release has lower precedence when prefix matches (semver §11.4.4)
+    if (ai === undefined) return -1;
+    if (bi === undefined) return 1;
+
+    const aNum = Number(ai);
+    const bNum = Number(bi);
+    const aIsNum = !Number.isNaN(aNum);
+    const bIsNum = !Number.isNaN(bNum);
+
+    // Numeric identifiers always have lower precedence than alphanumeric (semver §11.4.1)
+    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).
+ */
+export function comparePolicySemver(a: string, b: string): number {
+  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;
+
+  // Release > pre-release (semver §11.3)
+  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;
+}

package/src/core/policies/engines/compute-engine-registry.ts

@@ -0,0 +1,57 @@
+import { Result } from "../../result/result";
+
+import type { PolicyContext } from "./gate-types";
+import { ComputePayloadParsers } from "./parse-compute-payload";
+import type { ComputeEvaluatorRegistry } from "./compute-evaluator-registry";
+import type { ComputeOutcome, VersionedComputeEngine } from "./compute-types";
+
+export class ComputeEngineRegistry {
+  private readonly engines = new Map<number, VersionedComputeEngine>();
+
+  register(engine: VersionedComputeEngine): void {
+    this.engines.set(engine.version, engine);
+  }
+
+  get(version: number): VersionedComputeEngine | undefined {
+    return this.engines.get(version);
+  }
+
+  evaluate(
+    version: number,
+    params: {
+      readonly policyKey: string;
+      readonly payloadSchemaVersion: number;
+      readonly payload: unknown;
+      readonly context: PolicyContext;
+      readonly evaluators: ComputeEvaluatorRegistry;
+    },
+  ): Result<ComputeOutcome, string> {
+    const engine = this.get(version);
+    if (engine === undefined) {
+      return Result.err(
+        `No compute engine registered for version "${version}"`,
+      );
+    }
+
+    const evaluator = params.evaluators.get(params.policyKey, version);
+    if (evaluator === undefined) {
+      return Result.err(
+        `No compute evaluator registered for policy key "${params.policyKey}" and version "${version}"`,
+      );
+    }
+
+    const parsedPayloadResult = ComputePayloadParsers.parse(
+      params.payloadSchemaVersion,
+      params.payload,
+    );
+    if (parsedPayloadResult.isErr()) {
+      return Result.err(parsedPayloadResult.errorOrNull()!);
+    }
+
+    return engine.evaluate(
+      parsedPayloadResult.getOrNull()!,
+      params.context,
+      evaluator,
+    );
+  }
+}

package/src/core/policies/engines/compute-evaluator-registry.ts

@@ -0,0 +1,28 @@
+import type {
+  ComputeEvaluator,
+  ComputeEvaluatorRegistration,
+} from "./compute-types";
+
+export class ComputeEvaluatorRegistry {
+  private readonly evaluators = new Map<string, ComputeEvaluator>();
+
+  private static toRegistryKey(policyKey: string, version: number): string {
+    return `${policyKey}::${version}`;
+  }
+
+  register(registration: ComputeEvaluatorRegistration): void {
+    this.evaluators.set(
+      ComputeEvaluatorRegistry.toRegistryKey(
+        registration.policyKey,
+        registration.version,
+      ),
+      registration.evaluator,
+    );
+  }
+
+  get(policyKey: string, version: number): ComputeEvaluator | undefined {
+    return this.evaluators.get(
+      ComputeEvaluatorRegistry.toRegistryKey(policyKey, version),
+    );
+  }
+}

package/src/core/policies/engines/compute-payload.ts

@@ -0,0 +1,5 @@
+import type { ComputePayloadV1 } from "./v1/compute/compute-payload.schema";
+
+export type { ComputePayloadV1 };
+
+export type ComputePayload = ComputePayloadV1;