@cullet/erp-core 1.0.0

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

@@ -0,0 +1,67 @@
+import { type CoreConfig, coreConfig } from "../../config";
+import type { Result } from "../../result/result";
+
+import { ComputeEngineRegistry } from "./compute-engine-registry";
+import { ComputeEvaluatorRegistry } from "./compute-evaluator-registry";
+import type { PolicyContext } from "./gate-types";
+import type {
+  ComputeEvaluator,
+  ComputeEvaluatorRegistration,
+  ComputeOutcome,
+  VersionedComputeEngine,
+} from "./compute-types";
+import { ComputeEngineV1 } from "./v1/compute";
+
+export interface ComputeRegistryOptions {
+  readonly coreConfig?: CoreConfig;
+}
+
+export class ComputeRegistry {
+  private readonly engines = new ComputeEngineRegistry();
+  private readonly evaluators = new ComputeEvaluatorRegistry();
+
+  constructor(params: ComputeRegistryOptions = {}) {
+    const resolvedCoreConfig = params.coreConfig ?? coreConfig;
+
+    this.engines.register(
+      new ComputeEngineV1({
+        coreConfig: resolvedCoreConfig,
+      }),
+    );
+  }
+
+  register(registration: ComputeEvaluatorRegistration): void {
+    this.evaluators.register(registration);
+  }
+
+  registerEngine(engine: VersionedComputeEngine): void {
+    this.engines.register(engine);
+  }
+
+  getEngine(version: number): VersionedComputeEngine | undefined {
+    return this.engines.get(version);
+  }
+
+  getEvaluator(
+    policyKey: string,
+    version: number,
+  ): ComputeEvaluator | undefined {
+    return this.evaluators.get(policyKey, version);
+  }
+
+  evaluate(
+    policyKey: string,
+    computeEngineVersion: number,
+    payloadSchemaVersion: number,
+    payload: unknown,
+    context: PolicyContext,
+  ): Result<ComputeOutcome, string> {
+    return this.engines.evaluate(computeEngineVersion, {
+      policyKey,
+      payloadSchemaVersion,
+      payload,
+      context,
+      evaluators: this.evaluators,
+    });
+  }
+}

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

@@ -0,0 +1,51 @@
+import type { Outcome } from "../../result/outcome";
+import type { Result } from "../../result/result";
+
+import type { ComputePayload } from "./compute-payload";
+import type { PolicyContext, PolicyViolation } from "./gate-types";
+
+// ─── Compute outcome (business decision) ────────────────────────────────────
+
+export type ComputeStatus = "OK" | "NOT_APPLICABLE" | "ERROR";
+
+export interface ComputeOutcomeData {
+  readonly values: unknown | null;
+  readonly violations: readonly PolicyViolation[];
+}
+
+/** Semantic outcome of a COMPUTE policy evaluation. */
+export type ComputeOutcome = Outcome<ComputeStatus, ComputeOutcomeData>;
+
+/**
+ * Pure compute operation: receives a resolved value + context, returns a
+ * business decision. Registration metadata (policy key/version) lives outside
+ * this contract.
+ *
+ * The engine resolves the structural payload before calling the evaluator:
+ * - `params` -> `payload.data`
+ * - `decision-table` -> matching `rule.result` or `default`
+ *
+ * Result wraps technical failures (invalid value shape).
+ * Outcome carries the semantic business decision.
+ */
+export interface ComputeEvaluator {
+  evaluate(
+    resolvedValue: unknown,
+    context: Record<string, unknown>,
+  ): Result<ComputeOutcome, string>;
+}
+
+export interface ComputeEvaluatorRegistration {
+  readonly policyKey: string;
+  readonly version: number;
+  readonly evaluator: ComputeEvaluator;
+}
+
+export interface VersionedComputeEngine {
+  readonly version: number;
+  evaluate(
+    payload: ComputePayload,
+    context: PolicyContext,
+    evaluator: ComputeEvaluator,
+  ): Result<ComputeOutcome, string>;
+}

package/src/core/policies/engines/condition-evaluator-reporter.ts

@@ -0,0 +1,34 @@
+export interface ConditionEvaluationCause {
+  readonly name: string;
+  readonly message: string;
+}
+
+export type ConditionEvaluationReportLevel = "warn" | "error";
+
+export type ConditionEvaluationReportTag =
+  | "MISSING_CONTEXT_FIELD"
+  | "NULLISH_NUMERIC_OPERAND_NOT_ALLOWED"
+  | "NULLISH_DATE_OPERAND_NOT_ALLOWED"
+  | "INVALID_DATE_OPERAND"
+  | "CONDITION_EVAL_THREW";
+
+export interface ConditionEvaluationReport {
+  readonly occurredAt: Date;
+  readonly level: ConditionEvaluationReportLevel;
+  readonly tag: ConditionEvaluationReportTag;
+  readonly message: string;
+  readonly engineVersion: number;
+  readonly details: Readonly<Record<string, unknown>>;
+}
+
+export interface ConditionEvaluatorReporter {
+  warn(report: ConditionEvaluationReport): void;
+  error(report: ConditionEvaluationReport): void;
+}
+
+// Either fully silent (no reporter, no version stamp) or fully observable
+// (reporter paired with engineVersion so every report carries its origin).
+export type ConditionEvaluationOptions = {
+  readonly reporter: ConditionEvaluatorReporter;
+  readonly engineVersion: number;
+};

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

@@ -0,0 +1,38 @@
+import { Result } from "../../result/result";
+
+import type {
+  GateOutcome,
+  PolicyContext,
+  VersionedGateEngine,
+} from "./gate-types";
+import { GatePayloadParsers } from "./parse-gate-payload";
+
+export class GateEngineRegistry {
+  private readonly engines = new Map<number, VersionedGateEngine>();
+
+  register(engine: VersionedGateEngine): void {
+    this.engines.set(engine.version, engine);
+  }
+
+  get(version: number): VersionedGateEngine | undefined {
+    return this.engines.get(version);
+  }
+
+  evaluate(
+    version: number,
+    payload: unknown,
+    context: PolicyContext,
+  ): Result<GateOutcome, string> {
+    const engine = this.engines.get(version);
+    if (!engine) {
+      return Result.err(`No gate engine registered for version "${version}"`);
+    }
+
+    const parsedPayload = GatePayloadParsers.parse(version, payload);
+    if (parsedPayload.isErr()) {
+      return Result.err(parsedPayload.errorOrNull()!);
+    }
+
+    return engine.evaluate(parsedPayload.getOrNull()!, context);
+  }
+}

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

@@ -0,0 +1,5 @@
+import type { GatePayloadV1 } from "./v1/gate/gate-types-v1";
+
+export type { GatePayloadV1 };
+
+export type GatePayload = GatePayloadV1;

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

@@ -0,0 +1,63 @@
+import type { Outcome } from "../../result/outcome";
+import type { Result } from "../../result/result";
+
+import type { GatePayload } from "./gate-payload";
+
+// ─── Shared gate types (version-agnostic) ───────────────────────────────────
+
+export type PolicyContext = Record<string, unknown>;
+
+export interface GateTraceLeafSnapshot {
+  readonly kind: "LEAF";
+  readonly field: string;
+  readonly op: string;
+  readonly allowNull?: true;
+}
+
+export type GateTraceNodeSnapshot =
+  | GateTraceLeafSnapshot
+  | {
+      readonly kind: "AND" | "OR";
+      readonly childCount: number;
+    }
+  | {
+      readonly kind: "NOT";
+    };
+
+export interface GateViolationTrace {
+  readonly conditionPath: string;
+  readonly decisiveNode: GateTraceNodeSnapshot;
+  readonly lastEvaluatedLeaf: GateTraceLeafSnapshot;
+  readonly lastEvaluatedLeafPath: string;
+  readonly lastEvaluatedLeafResult: boolean;
+  readonly field: string;
+  readonly op: string;
+}
+
+export interface PolicyViolation {
+  readonly code: string;
+  readonly message: string;
+  readonly trace?: GateViolationTrace;
+}
+
+export type GateStatus = "ALLOW" | "DENY";
+
+export interface GateOutcomeData {
+  readonly violations: readonly PolicyViolation[];
+}
+
+/** Semantic outcome of a GATE policy evaluation. */
+export type GateOutcome = Outcome<GateStatus, GateOutcomeData>;
+
+/**
+ * Contract every versioned gate engine must satisfy.
+ * Receives an already-parsed `GatePayload`; parsing from raw `unknown` is
+ * the registry's responsibility via `parseGatePayload`.
+ */
+export interface VersionedGateEngine {
+  readonly version: number;
+  evaluate(
+    payload: GatePayload,
+    context: PolicyContext,
+  ): Result<GateOutcome, string>;
+}

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

@@ -0,0 +1,48 @@
+export type { ComputePayload, ComputePayloadV1 } from "./compute-payload";
+export type {
+  ComputeEvaluator,
+  ComputeEvaluatorRegistration,
+  ComputeOutcome,
+  ComputeOutcomeData,
+  ComputeStatus,
+  VersionedComputeEngine,
+} from "./compute-types";
+export type {
+  ConditionEvaluationCause,
+  ConditionEvaluationOptions,
+  ConditionEvaluationReport,
+  ConditionEvaluationReportLevel,
+  ConditionEvaluationReportTag,
+  ConditionEvaluatorReporter,
+} from "./condition-evaluator-reporter";
+export { ComputeEngineRegistry } from "./compute-engine-registry";
+export { ComputeEvaluatorRegistry } from "./compute-evaluator-registry";
+export { ComputeRegistry } from "./compute-registry";
+export { GateEngineRegistry } from "./gate-engine-registry";
+export type { GatePayload, GatePayloadV1 } from "./gate-payload";
+export type {
+  GateOutcome,
+  GateOutcomeData,
+  GateStatus,
+  GateTraceLeafSnapshot,
+  GateTraceNodeSnapshot,
+  GateViolationTrace,
+  PolicyContext,
+  PolicyViolation,
+  VersionedGateEngine,
+} from "./gate-types";
+export {
+  ComputePayloadParsers,
+  ComputePayloadParserRegistry,
+} from "./parse-compute-payload";
+export type { ComputePayloadParser } from "./parse-compute-payload";
+export {
+  GatePayloadParsers,
+  GatePayloadParserRegistry,
+} from "./parse-gate-payload";
+export type { GatePayloadParser } from "./parse-gate-payload";
+export type {
+  ComputeDecisionTablePayload,
+  ComputeDecisionTableRule,
+  ComputeParamsPayload,
+} from "./v1/compute";

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

@@ -0,0 +1,71 @@
+import type { Result as ResultType } from "../../result/result";
+import { Result } from "../../result/result";
+
+import type { ComputePayload } from "./compute-payload";
+import { ComputePayloadSchemaV1 } from "./v1/compute/compute-payload.schema";
+
+export type ComputePayloadParser = (
+  payload: unknown,
+) => ResultType<ComputePayload, string>;
+
+export class ComputePayloadParserRegistry {
+  private readonly parsers = new Map<number, ComputePayloadParser>();
+
+  register(payloadSchemaVersion: number, parser: ComputePayloadParser): void {
+    this.parsers.set(payloadSchemaVersion, parser);
+  }
+
+  get(payloadSchemaVersion: number): ComputePayloadParser | undefined {
+    return this.parsers.get(payloadSchemaVersion);
+  }
+
+  parse(payloadSchemaVersion: number, payload: unknown) {
+    const parser = this.parsers.get(payloadSchemaVersion);
+
+    if (parser === undefined) {
+      return Result.err(
+        `No compute payload parser registered for schema version "${payloadSchemaVersion}"`,
+      );
+    }
+
+    return parser(payload);
+  }
+}
+
+export class ComputePayloadParsers {
+  private static readonly registry = new ComputePayloadParserRegistry();
+  private static defaultsRegistered = false;
+
+  // Registers the built-in v1 parser lazily, the first time the default
+  // dispatcher is touched. Done here — rather than as a top-level module
+  // statement — so the package's `"sideEffects": false` flag stays honest and
+  // a tree-shaking bundler cannot drop the v1 registration and leave the
+  // compute engine unable to parse v1 payloads at runtime.
+  private static ensureDefaults(): void {
+    if (ComputePayloadParsers.defaultsRegistered) {
+      return;
+    }
+    ComputePayloadParsers.defaultsRegistered = true;
+    ComputePayloadParsers.registry.register(1, ComputePayloadSchemaV1.parse);
+  }
+
+  static register(
+    payloadSchemaVersion: number,
+    parser: ComputePayloadParser,
+  ): void {
+    ComputePayloadParsers.ensureDefaults();
+    ComputePayloadParsers.registry.register(payloadSchemaVersion, parser);
+  }
+
+  static get(payloadSchemaVersion: number): ComputePayloadParser | undefined {
+    ComputePayloadParsers.ensureDefaults();
+    return ComputePayloadParsers.registry.get(payloadSchemaVersion);
+  }
+
+  static parse(payloadSchemaVersion: number, payload: unknown) {
+    ComputePayloadParsers.ensureDefaults();
+    return ComputePayloadParsers.registry.parse(payloadSchemaVersion, payload);
+  }
+}
+
+export type { ComputePayload };

package/src/core/policies/engines/parse-gate-payload.ts

@@ -0,0 +1,68 @@
+import type { Result as ResultType } from "../../result/result";
+import { Result } from "../../result/result";
+
+import type { GatePayload } from "./gate-payload";
+import { GatePayloadSchemaV1 } from "./v1/gate/gate-v1-payload.schema";
+
+export type GatePayloadParser = (
+  payload: unknown,
+) => ResultType<GatePayload, string>;
+
+export class GatePayloadParserRegistry {
+  private readonly parsers = new Map<number, GatePayloadParser>();
+
+  register(engineVersion: number, parser: GatePayloadParser): void {
+    this.parsers.set(engineVersion, parser);
+  }
+
+  get(engineVersion: number): GatePayloadParser | undefined {
+    return this.parsers.get(engineVersion);
+  }
+
+  parse(engineVersion: number, payload: unknown) {
+    const parser = this.parsers.get(engineVersion);
+
+    if (parser === undefined) {
+      return Result.err(
+        `No gate payload parser registered for engine version "${engineVersion}"`,
+      );
+    }
+
+    return parser(payload);
+  }
+}
+
+export class GatePayloadParsers {
+  private static readonly registry = new GatePayloadParserRegistry();
+  private static defaultsRegistered = false;
+
+  // Registers the built-in v1 parser lazily, the first time the default
+  // dispatcher is touched. Done here — rather than as a top-level module
+  // statement — so the package's `"sideEffects": false` flag stays honest and
+  // a tree-shaking bundler cannot drop the v1 registration and leave the gate
+  // engine unable to parse v1 payloads at runtime.
+  private static ensureDefaults(): void {
+    if (GatePayloadParsers.defaultsRegistered) {
+      return;
+    }
+    GatePayloadParsers.defaultsRegistered = true;
+    GatePayloadParsers.registry.register(1, GatePayloadSchemaV1.parse);
+  }
+
+  static register(engineVersion: number, parser: GatePayloadParser): void {
+    GatePayloadParsers.ensureDefaults();
+    GatePayloadParsers.registry.register(engineVersion, parser);
+  }
+
+  static get(engineVersion: number): GatePayloadParser | undefined {
+    GatePayloadParsers.ensureDefaults();
+    return GatePayloadParsers.registry.get(engineVersion);
+  }
+
+  static parse(engineVersion: number, payload: unknown) {
+    GatePayloadParsers.ensureDefaults();
+    return GatePayloadParsers.registry.parse(engineVersion, payload);
+  }
+}
+
+export type { GatePayload };

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

@@ -0,0 +1,55 @@
+import { type CoreConfig, coreConfig } from "../../../../config";
+import { Result } from "../../../../result/result";
+
+import type { ComputePayloadV1 as ComputePayload } from "./compute-payload.schema";
+import { DecisionTableResolverV1 } from "./resolve-decision-table-v1";
+import type {
+  ComputeEvaluator,
+  ComputeOutcome,
+  VersionedComputeEngine,
+} from "../../compute-types";
+import type { PolicyContext } from "../../gate-types";
+
+// ─── Compute engine v1 ───────────────────────────────────────────────────────
+
+const COMPUTE_ENGINE_VERSION = 1;
+
+export class ComputeEngineV1 implements VersionedComputeEngine {
+  readonly version = COMPUTE_ENGINE_VERSION;
+  private readonly coreConfig: CoreConfig;
+
+  constructor(params: { readonly coreConfig?: CoreConfig } = {}) {
+    this.coreConfig = params.coreConfig ?? coreConfig;
+  }
+
+  /**
+   * Evaluates an already-parsed ComputePayload against a context.
+   * Pure function — no side effects.
+   *
+   * For `params`: forwards `payload.data` directly to the evaluator.
+   * For `decision-table`: evaluates the rules in order and passes the `result`
+   * of the first one that satisfies its conditions, or `default` if none match.
+   *
+   * The evaluator is responsible for validating and transforming the final value.
+   */
+  evaluate(
+    payload: ComputePayload,
+    context: PolicyContext,
+    evaluator: ComputeEvaluator,
+  ): Result<ComputeOutcome, string> {
+    if (payload.type === "params") {
+      return evaluator.evaluate(payload.data, context);
+    }
+
+    const resolvedResult = DecisionTableResolverV1.resolve(
+      payload,
+      context,
+      this.coreConfig.getConditionEvaluationOptions(COMPUTE_ENGINE_VERSION),
+    );
+    if (resolvedResult.isErr()) {
+      return Result.err(resolvedResult.errorOrNull()!);
+    }
+
+    return evaluator.evaluate(resolvedResult.getOrNull()!, context);
+  }
+}

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

@@ -0,0 +1,75 @@
+import { z } from "zod";
+
+import { Result } from "../../../../result/result";
+
+import { conditionNodeSchema } from "../condition-schema";
+import type { ConditionNode } from "../condition-types";
+
+// ─── Pattern 1: Params ──────────────────────────────────────────────────────
+
+export interface ComputeParamsPayload {
+  readonly type: "params";
+  readonly data: Readonly<Record<string, unknown>>;
+}
+
+// ─── Pattern 2: Decision table ──────────────────────────────────────────────
+
+export interface ComputeDecisionTableRule<R = unknown> {
+  readonly conditions: ConditionNode;
+  readonly result: R;
+}
+
+export interface ComputeDecisionTablePayload<R = unknown> {
+  readonly type: "decision-table";
+  readonly rules: readonly ComputeDecisionTableRule<R>[];
+  readonly default: R;
+}
+
+// ─── Union ──────────────────────────────────────────────────────────────────
+
+export type ComputePayloadV1 =
+  | ComputeDecisionTablePayload<unknown>
+  | ComputeParamsPayload;
+
+// ─── Zod schemas ────────────────────────────────────────────────────────────
+
+const computeDecisionTableRuleSchema = z.object({
+  conditions: conditionNodeSchema,
+  result: z.unknown(),
+});
+
+export class ComputePayloadSchemaV1 {
+  static readonly schema = z.union([
+    z
+      .object({
+        type: z.literal("decision-table"),
+        rules: z.array(computeDecisionTableRuleSchema).min(1),
+        default: z.unknown(),
+      })
+      .strict(),
+    z
+      .object({
+        type: z.literal("params"),
+        data: z.record(z.string(), z.unknown()),
+      })
+      .strict(),
+  ]);
+
+  static parse(payload: unknown): Result<ComputePayloadV1, string> {
+    const parsed = ComputePayloadSchemaV1.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 compute payload: ${details}`);
+    }
+
+    return Result.ok(parsed.data as ComputePayloadV1);
+  }
+}
+
+export const computePayloadSchema = ComputePayloadSchemaV1.schema;

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

@@ -0,0 +1,12 @@
+export { ComputeEngineV1 } from "./compute-engine-v1";
+export type {
+  ComputeDecisionTablePayload,
+  ComputeDecisionTableRule,
+  ComputeParamsPayload,
+  ComputePayloadV1,
+} from "./compute-payload.schema";
+export {
+  computePayloadSchema,
+  ComputePayloadSchemaV1,
+} from "./compute-payload.schema";
+export { DecisionTableResolverV1 } from "./resolve-decision-table-v1";

package/src/core/policies/engines/v1/compute/resolve-decision-table-v1.ts

@@ -0,0 +1,54 @@
+import { Result } from "../../../../result/result";
+
+import type { ConditionEvaluationOptions } from "../../condition-evaluator-reporter";
+
+import { ConditionEvaluatorV1 } from "../condition-evaluator";
+import type { ComputeDecisionTablePayload } from "./compute-payload.schema";
+
+const COMPUTE_CONDITION_EVAL_FAILED_TAG = "COMPUTE_CONDITION_EVAL_FAILED";
+
+export class DecisionTableResolverV1 {
+  constructor(
+    private readonly payload: ComputeDecisionTablePayload,
+    private readonly context: Record<string, unknown>,
+    private readonly conditionEvaluationOptions: ConditionEvaluationOptions,
+  ) {}
+
+  private wrapConditionEvaluationError(error: string): Result<unknown, string> {
+    return Result.err(`${COMPUTE_CONDITION_EVAL_FAILED_TAG}: ${error}`);
+  }
+
+  resolve(): Result<unknown, string> {
+    const evaluator = new ConditionEvaluatorV1(
+      this.context,
+      this.conditionEvaluationOptions,
+    );
+
+    for (const rule of this.payload.rules) {
+      const conditionResult = evaluator.evaluate(rule.conditions);
+      if (conditionResult.isErr()) {
+        return this.wrapConditionEvaluationError(
+          conditionResult.errorOrNull()!,
+        );
+      }
+
+      if (conditionResult.getOrNull()) {
+        return Result.ok(rule.result);
+      }
+    }
+
+    return Result.ok(this.payload.default);
+  }
+
+  static resolve(
+    payload: ComputeDecisionTablePayload,
+    context: Record<string, unknown>,
+    conditionEvaluationOptions: ConditionEvaluationOptions,
+  ): Result<unknown, string> {
+    return new DecisionTableResolverV1(
+      payload,
+      context,
+      conditionEvaluationOptions,
+    ).resolve();
+  }
+}