@cullet/erp-core 1.0.0

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

@@ -0,0 +1,220 @@
+import { UnexpectedError } from "../../errors";
+
+import type {
+  AsOfSource,
+  PolicyKind,
+  PolicyOwner,
+  PolicyScopeLevel,
+} from "./catalog-types";
+import type { PolicyKey } from "./policy-key";
+
+/**
+ * Properties for creating a PolicyCatalogEntry.
+ */
+export interface PolicyCatalogEntryProps {
+  readonly key: PolicyKey;
+  readonly kind: PolicyKind;
+  readonly gateEngineVersion?: number;
+  readonly computeEngineVersion?: number;
+  readonly payloadSchemaVersion?: number;
+  readonly owner: PolicyOwner;
+  readonly allowedScopes: readonly PolicyScopeLevel[];
+  readonly asOfSource: AsOfSource;
+  /** Paths the context must contain for this policy to be evaluable. */
+  readonly contextRequirements: readonly string[];
+  readonly tags?: readonly string[];
+  readonly description: string;
+}
+
+/**
+ * Represents a single entry in the Policy Catalog.
+ * Encapsulates metadata and validation logic for a policy.
+ */
+export class PolicyCatalogEntry {
+  public readonly key: PolicyKey;
+  public readonly kind: PolicyKind;
+
+  public readonly gateEngineVersion?: number;
+  public readonly computeEngineVersion?: number;
+  public readonly payloadSchemaVersion?: number;
+
+  public readonly owner: PolicyOwner;
+  public readonly allowedScopes: readonly PolicyScopeLevel[];
+  public readonly asOfSource: AsOfSource;
+  public readonly contextRequirements: readonly string[];
+  public readonly tags: readonly string[];
+  public readonly description: string;
+
+  constructor(props: PolicyCatalogEntryProps) {
+    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: readonly PolicyCatalogEntry[]): void {
+    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: PolicyCatalogEntry | PolicyCatalogEntryProps,
+  ): PolicyCatalogEntry {
+    return entry instanceof PolicyCatalogEntry
+      ? entry
+      : new PolicyCatalogEntry(entry);
+  }
+
+  isGate(): boolean {
+    return this.kind === "GATE";
+  }
+
+  isCompute(): boolean {
+    return this.kind === "COMPUTE";
+  }
+
+  allowsScope(scope: PolicyScopeLevel): boolean {
+    return this.allowedScopes.includes(scope);
+  }
+
+  hasExplicitVersionSelector(): boolean {
+    return (
+      this.gateEngineVersion !== undefined ||
+      this.computeEngineVersion !== undefined ||
+      this.payloadSchemaVersion !== undefined
+    );
+  }
+
+  matchesVersion(params: {
+    readonly kind: PolicyKind;
+    readonly gateEngineVersion?: number;
+    readonly computeEngineVersion?: number;
+    readonly payloadSchemaVersion?: number;
+  }): boolean {
+    if (this.kind !== params.kind) {
+      return false;
+    }
+
+    if (
+      this.gateEngineVersion !== undefined &&
+      this.gateEngineVersion !== params.gateEngineVersion
+    ) {
+      return false;
+    }
+
+    if (
+      this.computeEngineVersion !== undefined &&
+      this.computeEngineVersion !== params.computeEngineVersion
+    ) {
+      return false;
+    }
+
+    if (
+      this.payloadSchemaVersion !== undefined &&
+      this.payloadSchemaVersion !== params.payloadSchemaVersion
+    ) {
+      return false;
+    }
+
+    return true;
+  }
+
+  toVariantKey(): string {
+    return [
+      this.key.toString(),
+      this.kind,
+      this.gateEngineVersion ?? "gate:any",
+      this.computeEngineVersion ?? "compute:any",
+      this.payloadSchemaVersion ?? "schema:any",
+    ].join("::");
+  }
+
+  usesNowAsOf(): boolean {
+    return this.asOfSource === "NOW";
+  }
+
+  usesCallerProvidedAsOf(): boolean {
+    return this.asOfSource === "CALLER_PROVIDED";
+  }
+
+  requiresContext(path: string): boolean {
+    return this.contextRequirements.includes(path);
+  }
+
+  requiresAllContexts(paths: readonly string[]): boolean {
+    return paths.every((path) => this.requiresContext(path));
+  }
+
+  hasTag(tag: string): boolean {
+    return this.tags.includes(tag);
+  }
+
+  equals(other: PolicyCatalogEntry): boolean {
+    return this.key.equals(other.key);
+  }
+
+  toJSON(): PolicyCatalogEntryProps {
+    return {
+      key: this.key,
+      kind: this.kind,
+      ...(this.gateEngineVersion !== undefined
+        ? { gateEngineVersion: this.gateEngineVersion }
+        : {}),
+      ...(this.computeEngineVersion !== undefined
+        ? { computeEngineVersion: this.computeEngineVersion }
+        : {}),
+      ...(this.payloadSchemaVersion !== undefined
+        ? { payloadSchemaVersion: this.payloadSchemaVersion }
+        : {}),
+      owner: this.owner,
+      allowedScopes: [...this.allowedScopes],
+      asOfSource: this.asOfSource,
+      contextRequirements: [...this.contextRequirements],
+      tags: this.tags.length > 0 ? [...this.tags] : undefined,
+      description: this.description,
+    };
+  }
+}

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

@@ -0,0 +1,124 @@
+import { UnexpectedError } from "../../errors";
+import { Result } from "../../result/result";
+
+import { PolicyCatalogEntry } from "./policy-catalog-entry";
+
+/**
+ * In-code catalog of all known policies.
+ * The catalog defines the universe of policies; the database cannot invent new ones.
+ */
+export class PolicyCatalog {
+  private readonly versionedEntries: ReadonlyMap<string, PolicyCatalogEntry>;
+  private readonly entriesByKey: ReadonlyMap<
+    string,
+    readonly PolicyCatalogEntry[]
+  >;
+
+  constructor(entries: readonly PolicyCatalogEntry[]) {
+    const families = new Map<string, PolicyCatalogEntry[]>();
+    const versionedMap = new Map<string, PolicyCatalogEntry>();
+
+    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: string): Result<PolicyCatalogEntry, string> {
+    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: string): Result<readonly PolicyCatalogEntry[], string> {
+    const family = this.entriesByKey.get(key);
+    if (!family) {
+      return Result.err(`Policy not found in catalog: "${key}"`);
+    }
+
+    return Result.ok(family);
+  }
+
+  getVersioned(params: {
+    readonly key: string;
+    readonly kind: "GATE" | "COMPUTE";
+    readonly gateEngineVersion?: number;
+    readonly computeEngineVersion?: number;
+    readonly payloadSchemaVersion?: number;
+  }): Result<PolicyCatalogEntry, string> {
+    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 !== undefined
+        ? `gateEngineVersion=${params.gateEngineVersion}`
+        : null,
+      params.computeEngineVersion !== undefined
+        ? `computeEngineVersion=${params.computeEngineVersion}`
+        : null,
+      params.payloadSchemaVersion !== undefined
+        ? `payloadSchemaVersion=${params.payloadSchemaVersion}`
+        : null,
+    ]
+      .filter((part): part is string => part !== null)
+      .join(", ");
+
+    return Result.err(
+      `Policy variant not found in catalog: "${params.key}" (${versionDetails})`,
+    );
+  }
+
+  list(): readonly PolicyCatalogEntry[] {
+    return Array.from(this.versionedEntries.values());
+  }
+
+  has(key: string): boolean {
+    return this.entriesByKey.has(key);
+  }
+}

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

@@ -0,0 +1,78 @@
+import { Result } from "../../result/result";
+
+/**
+ * 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;
+
+export class PolicyKey {
+  public readonly module: string;
+  public readonly area: string;
+  public readonly name: string;
+
+  private constructor(module: string, area: string, name: string) {
+    this.module = module;
+    this.area = area;
+    this.name = name;
+    Object.freeze(this);
+  }
+
+  static parse(raw: string): Result<PolicyKey, string> {
+    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(): string {
+    return `${this.module}.${this.area}.${this.name}`;
+  }
+
+  equals(other: PolicyKey): boolean {
+    return this.toString() === other.toString();
+  }
+}