@cullet/erp-core 1.0.0

package/src/core/policies/context/context-builder.ts

@@ -0,0 +1,391 @@
+import { Result } from "../../result/result";
+
+import type { ContextResolverRegistry } from "./context-registry";
+import type {
+  ContextResolverResilienceOptions,
+  ContextResolverRetryOptions,
+  ContextValueResolver,
+} from "./context-resolver";
+import type { ContextSeed } from "./context-seed";
+import { PolicyContextPath } from "./path";
+
+interface NormalizedContextResolverRetryOptions {
+  readonly maxAttempts: number;
+  readonly initialDelayMs: number;
+  readonly maxDelayMs: number;
+  readonly backoffMultiplier: number;
+}
+
+interface NormalizedContextResolverCircuitBreakerOptions {
+  readonly failureThreshold: number;
+  readonly cooldownMs: number;
+}
+
+interface NormalizedContextResolverResilienceOptions {
+  readonly timeoutMs: number | null;
+  readonly retry: NormalizedContextResolverRetryOptions;
+  readonly circuitBreaker: NormalizedContextResolverCircuitBreakerOptions | null;
+}
+
+interface ContextResolverCircuitState {
+  readonly failureCount: number;
+  readonly openUntilMs: number | null;
+}
+
+export interface PolicyContextBuilderOptions {
+  readonly defaultResolverResilience?: ContextResolverResilienceOptions;
+  readonly now?: () => number;
+  readonly sleep?: (delayMs: number) => Promise<void>;
+}
+
+const DEFAULT_RESOLVER_RETRY_OPTIONS: NormalizedContextResolverRetryOptions = {
+  maxAttempts: 1,
+  initialDelayMs: 25,
+  maxDelayMs: 1_000,
+  backoffMultiplier: 2,
+};
+
+/**
+ * Builds a context object by resolving required paths from a seed.
+ */
+export class PolicyContextBuilder {
+  private readonly circuitStates = new Map<
+    string,
+    ContextResolverCircuitState
+  >();
+  private readonly defaultResolverResilience?: ContextResolverResilienceOptions;
+  private readonly now: () => number;
+  private readonly sleep: (delayMs: number) => Promise<void>;
+
+  constructor(
+    private readonly registry: ContextResolverRegistry,
+    options: PolicyContextBuilderOptions = {},
+  ) {
+    this.defaultResolverResilience = options.defaultResolverResilience;
+    this.now = options.now ?? Date.now;
+    this.sleep =
+      options.sleep ??
+      (async (delayMs) => {
+        if (delayMs <= 0) {
+          return;
+        }
+
+        await new Promise<void>((resolve) => {
+          setTimeout(resolve, delayMs);
+        });
+      });
+  }
+
+  private static clampPositiveInteger(
+    value: number | undefined,
+    fallback: number,
+  ): number {
+    if (value === undefined || !Number.isFinite(value)) {
+      return fallback;
+    }
+
+    return Math.max(1, Math.trunc(value));
+  }
+
+  private static clampNonNegativeInteger(
+    value: number | undefined,
+    fallback: number,
+  ): number {
+    if (value === undefined || !Number.isFinite(value)) {
+      return fallback;
+    }
+
+    return Math.max(0, Math.trunc(value));
+  }
+
+  private static normalizeTimeoutMs(value: number | undefined): number | null {
+    if (value === undefined || !Number.isFinite(value) || value <= 0) {
+      return null;
+    }
+
+    return Math.trunc(value);
+  }
+
+  private static mergeRetryOptions(
+    defaults: ContextResolverRetryOptions | false | undefined,
+    overrides: ContextResolverRetryOptions | false | undefined,
+  ): ContextResolverRetryOptions | false | undefined {
+    if (overrides === false) {
+      return false;
+    }
+
+    if (overrides !== undefined) {
+      return {
+        ...(defaults === false || defaults === undefined ? {} : defaults),
+        ...overrides,
+      };
+    }
+
+    return defaults;
+  }
+
+  private static mergeCircuitBreakerOptions(
+    defaults: ContextResolverResilienceOptions["circuitBreaker"] | undefined,
+    overrides: ContextResolverResilienceOptions["circuitBreaker"] | undefined,
+  ): ContextResolverResilienceOptions["circuitBreaker"] | undefined {
+    if (overrides === false) {
+      return false;
+    }
+
+    if (overrides !== undefined) {
+      return {
+        ...(defaults === false || defaults === undefined ? {} : defaults),
+        ...overrides,
+      };
+    }
+
+    return defaults;
+  }
+
+  private resolveResilienceOptions(
+    resolver: ContextValueResolver,
+  ): NormalizedContextResolverResilienceOptions {
+    const defaults = this.defaultResolverResilience;
+    const override = resolver.resilience;
+    const retry = PolicyContextBuilder.mergeRetryOptions(
+      defaults?.retry,
+      override?.retry,
+    );
+    const circuitBreaker = PolicyContextBuilder.mergeCircuitBreakerOptions(
+      defaults?.circuitBreaker,
+      override?.circuitBreaker,
+    );
+    const retryOptions = retry === false ? undefined : retry;
+    const circuitBreakerOptions =
+      circuitBreaker === false ? undefined : circuitBreaker;
+
+    return {
+      timeoutMs: PolicyContextBuilder.normalizeTimeoutMs(
+        override?.timeoutMs ?? defaults?.timeoutMs,
+      ),
+      retry: {
+        maxAttempts: PolicyContextBuilder.clampPositiveInteger(
+          retryOptions?.maxAttempts,
+          DEFAULT_RESOLVER_RETRY_OPTIONS.maxAttempts,
+        ),
+        initialDelayMs: PolicyContextBuilder.clampNonNegativeInteger(
+          retryOptions?.initialDelayMs,
+          DEFAULT_RESOLVER_RETRY_OPTIONS.initialDelayMs,
+        ),
+        maxDelayMs: PolicyContextBuilder.clampNonNegativeInteger(
+          retryOptions?.maxDelayMs,
+          DEFAULT_RESOLVER_RETRY_OPTIONS.maxDelayMs,
+        ),
+        backoffMultiplier: PolicyContextBuilder.clampPositiveInteger(
+          retryOptions?.backoffMultiplier,
+          DEFAULT_RESOLVER_RETRY_OPTIONS.backoffMultiplier,
+        ),
+      },
+      circuitBreaker:
+        circuitBreakerOptions === undefined
+          ? null
+          : {
+              failureThreshold: PolicyContextBuilder.clampPositiveInteger(
+                circuitBreakerOptions.failureThreshold,
+                5,
+              ),
+              cooldownMs: PolicyContextBuilder.clampPositiveInteger(
+                circuitBreakerOptions.cooldownMs,
+                30_000,
+              ),
+            },
+    };
+  }
+
+  private getRetryDelayMs(
+    attempt: number,
+    retry: NormalizedContextResolverRetryOptions,
+  ): number {
+    return Math.min(
+      retry.initialDelayMs * retry.backoffMultiplier ** (attempt - 1),
+      retry.maxDelayMs,
+    );
+  }
+
+  private resetCircuit(path: string): void {
+    this.circuitStates.delete(path);
+  }
+
+  private isCircuitOpen(
+    path: string,
+    circuitBreaker: NormalizedContextResolverCircuitBreakerOptions | null,
+  ): boolean {
+    if (circuitBreaker === null) {
+      return false;
+    }
+
+    const state = this.circuitStates.get(path);
+    if (state === undefined || state.openUntilMs === null) {
+      return false;
+    }
+
+    if (state.openUntilMs <= this.now()) {
+      this.resetCircuit(path);
+      return false;
+    }
+
+    return true;
+  }
+
+  private recordResolverFailure(
+    path: string,
+    circuitBreaker: NormalizedContextResolverCircuitBreakerOptions | null,
+  ): void {
+    if (circuitBreaker === null) {
+      return;
+    }
+
+    const currentFailureCount = this.circuitStates.get(path)?.failureCount ?? 0;
+    const nextFailureCount = currentFailureCount + 1;
+
+    if (nextFailureCount >= circuitBreaker.failureThreshold) {
+      this.circuitStates.set(path, {
+        failureCount: 0,
+        openUntilMs: this.now() + circuitBreaker.cooldownMs,
+      });
+      return;
+    }
+
+    this.circuitStates.set(path, {
+      failureCount: nextFailureCount,
+      openUntilMs: null,
+    });
+  }
+
+  private static describeThrownResolverError(error: unknown): string {
+    if (error instanceof Error) {
+      return `threw ${error.name}: ${error.message}`;
+    }
+
+    return `threw ${String(error)}`;
+  }
+
+  private async resolveOnce(
+    resolver: ContextValueResolver,
+    seed: ContextSeed,
+    timeoutMs: number | null,
+  ): Promise<Result<unknown, string>> {
+    const execute = async (): Promise<Result<unknown, string>> => {
+      try {
+        return await resolver.resolve(seed);
+      } catch (error) {
+        return Result.err(
+          PolicyContextBuilder.describeThrownResolverError(error),
+        );
+      }
+    };
+
+    if (timeoutMs === null) {
+      return execute();
+    }
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+    try {
+      return await Promise.race([
+        execute(),
+        new Promise<Result<unknown, string>>((resolve) => {
+          timeoutId = setTimeout(() => {
+            resolve(Result.err(`timed out after ${timeoutMs}ms`));
+          }, timeoutMs);
+        }),
+      ]);
+    } finally {
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+
+  private async resolveWithResilience(
+    path: string,
+    resolver: ContextValueResolver,
+    seed: ContextSeed,
+  ): Promise<Result<unknown, string>> {
+    const resilience = this.resolveResilienceOptions(resolver);
+
+    if (this.isCircuitOpen(path, resilience.circuitBreaker)) {
+      return Result.err("circuit breaker is open");
+    }
+
+    let lastError = "resolver failed";
+
+    for (let attempt = 1; attempt <= resilience.retry.maxAttempts; attempt++) {
+      const result = await this.resolveOnce(
+        resolver,
+        seed,
+        resilience.timeoutMs,
+      );
+
+      if (result.isOk()) {
+        this.resetCircuit(path);
+        return result;
+      }
+
+      lastError = result.errorOrNull() ?? lastError;
+
+      if (attempt < resilience.retry.maxAttempts) {
+        await this.sleep(this.getRetryDelayMs(attempt, resilience.retry));
+      }
+    }
+
+    this.recordResolverFailure(path, resilience.circuitBreaker);
+    return Result.err(lastError);
+  }
+
+  /**
+   * Resolves all required context paths and returns a flat context object.
+   * If any required path cannot be resolved, returns an error.
+   */
+  async build(
+    requirements: readonly string[],
+    seed: ContextSeed,
+  ): Promise<Result<Record<string, unknown>, string>> {
+    const context: Record<string, unknown> = {};
+
+    for (const path of requirements) {
+      const resolver = this.registry.get(path);
+      if (!resolver) {
+        return Result.err(`Missing resolver for path "${path}"`);
+      }
+
+      const result = await this.resolveWithResilience(path, resolver, seed);
+      if (result.isErr()) {
+        return Result.err(
+          `Resolver error for path "${path}": ${result.errorOrNull()}`,
+        );
+      }
+
+      const setPathResult = PolicyContextPath.set(
+        context,
+        path,
+        result.getOrNull(),
+      );
+      if (setPathResult.isErr()) {
+        return Result.err(setPathResult.errorOrNull()!);
+      }
+    }
+
+    // Final validation: ensure every required path resolved to a defined value.
+    // `undefined` is rejected explicitly because resolvers that "succeed" with
+    // undefined indicate an unresolved field, not a present-but-empty one.
+    const missing = requirements.filter((path) => {
+      const result = PolicyContextPath.getOrAbsent(context, path);
+      return result.isErr() || result.getOrNull() === undefined;
+    });
+    if (missing.length > 0) {
+      return Result.err(
+        `Context missing required paths after resolution: ${missing.join(
+          ", ",
+        )}`,
+      );
+    }
+
+    return Result.ok(context);
+  }
+}

package/src/core/policies/context/context-registry.instance.ts

@@ -0,0 +1,26 @@
+import { Result } from "../../result/result";
+
+import {
+  ContextResolverRegistry,
+  registerNamespacedContextResolversIn,
+} from "./context-registry";
+
+import type { ContextValueResolver } from "./context-resolver";
+
+/**
+ * Official instance of the ContextResolverRegistry.
+ * Use `new ContextResolverRegistry()` plus `registerNamespacedContextResolversIn`
+ * when each runtime/composition root needs its own isolated resolver graph.
+ */
+export const contextResolverRegistry = new ContextResolverRegistry();
+
+export function registerNamespacedContextResolvers(
+  namespace: string,
+  resolvers: readonly ContextValueResolver[],
+): Result<ContextResolverRegistry, string> {
+  return registerNamespacedContextResolversIn(
+    contextResolverRegistry,
+    namespace,
+    resolvers,
+  );
+}

package/src/core/policies/context/context-registry.ts

@@ -0,0 +1,95 @@
+import { Result } from "../../result/result";
+
+import type { ContextValueResolver } from "./context-resolver";
+
+export interface ContextResolverRegistrationOptions {
+  readonly namespace?: string;
+}
+
+interface RegisteredContextResolver {
+  readonly namespace: string;
+  readonly resolver: ContextValueResolver;
+}
+
+const DEFAULT_CONTEXT_RESOLVER_NAMESPACE = "default";
+
+function normalizeNamespace(namespace?: string): string {
+  const normalized = namespace?.trim();
+
+  if (normalized === undefined || normalized.length === 0) {
+    return DEFAULT_CONTEXT_RESOLVER_NAMESPACE;
+  }
+
+  return normalized;
+}
+
+/**
+ * Registry of context value resolvers, keyed by path.
+ */
+export class ContextResolverRegistry {
+  private readonly resolvers = new Map<string, RegisteredContextResolver>();
+
+  register(
+    resolver: ContextValueResolver,
+    options: ContextResolverRegistrationOptions = {},
+  ): Result<void, string> {
+    const namespace = normalizeNamespace(options.namespace);
+    const existing = this.resolvers.get(resolver.path);
+
+    if (existing !== undefined && existing.namespace !== namespace) {
+      return Result.err(
+        `Resolver path "${resolver.path}" is already registered by namespace "${existing.namespace}" and cannot be replaced by "${namespace}".`,
+      );
+    }
+
+    this.resolvers.set(resolver.path, {
+      namespace,
+      resolver,
+    });
+
+    return Result.ok(undefined);
+  }
+
+  registerAll(
+    resolvers: readonly ContextValueResolver[],
+    options: ContextResolverRegistrationOptions = {},
+  ): Result<void, string> {
+    for (const r of resolvers) {
+      const registrationResult = this.register(r, options);
+      if (registrationResult.isErr()) {
+        return registrationResult;
+      }
+    }
+
+    return Result.ok(undefined);
+  }
+
+  get(path: string): ContextValueResolver | undefined {
+    return this.resolvers.get(path)?.resolver;
+  }
+
+  has(path: string): boolean {
+    return this.resolvers.has(path);
+  }
+
+  getNamespace(path: string): string | undefined {
+    return this.resolvers.get(path)?.namespace;
+  }
+}
+
+export function registerNamespacedContextResolversIn(
+  registry: ContextResolverRegistry,
+  namespace: string,
+  resolvers: readonly ContextValueResolver[],
+): Result<ContextResolverRegistry, string> {
+  const registrationResult = registry.registerAll(resolvers, {
+    namespace,
+  });
+  if (registrationResult.isErr()) {
+    return Result.err(registrationResult.errorOrNull()!);
+  }
+
+  return Result.ok(registry);
+}
+
+export { DEFAULT_CONTEXT_RESOLVER_NAMESPACE };

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

@@ -0,0 +1,31 @@
+import { Result } from "../../result/result";
+
+import type { ContextSeed } from "./context-seed";
+
+export interface ContextResolverRetryOptions {
+  readonly maxAttempts?: number;
+  readonly initialDelayMs?: number;
+  readonly maxDelayMs?: number;
+  readonly backoffMultiplier?: number;
+}
+
+export interface ContextResolverCircuitBreakerOptions {
+  readonly failureThreshold?: number;
+  readonly cooldownMs?: number;
+}
+
+export interface ContextResolverResilienceOptions {
+  readonly timeoutMs?: number;
+  readonly retry?: ContextResolverRetryOptions | false;
+  readonly circuitBreaker?: ContextResolverCircuitBreakerOptions | false;
+}
+
+/**
+ * A resolver that knows how to produce a value for a specific context path.
+ * Designed as async to allow future DB/API lookups without breaking the interface.
+ */
+export interface ContextValueResolver {
+  readonly path: string;
+  readonly resilience?: ContextResolverResilienceOptions;
+  resolve(seed: ContextSeed): Promise<Result<unknown, string>>;
+}

package/src/core/policies/context/context-seed.ts

@@ -0,0 +1,32 @@
+import { Result } from "../../result/result";
+
+import type { SchoolId, TenantId } from "../policy-ids";
+
+/**
+ * Seed data provided by the use case / caller.
+ * Contains raw IDs and inputs that the context system will resolve into paths.
+ * Each resolver is responsible for validating and extracting what it needs from fields.
+ */
+export interface ContextSeed {
+  readonly tenantId: TenantId;
+  readonly schoolId: SchoolId;
+  readonly fields: Record<string, unknown>;
+}
+
+export class ContextSeedValidator {
+  private static isBlankSeedId(value: string): boolean {
+    return value.trim().length === 0;
+  }
+
+  static validate(seed: ContextSeed): Result<ContextSeed, string> {
+    if (ContextSeedValidator.isBlankSeedId(seed.tenantId)) {
+      return Result.err("ContextSeed tenantId must be a non-empty string");
+    }
+
+    if (ContextSeedValidator.isBlankSeedId(seed.schoolId)) {
+      return Result.err("ContextSeed schoolId must be a non-empty string");
+    }
+
+    return Result.ok(seed);
+  }
+}

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

@@ -0,0 +1,21 @@
+export { PolicyContextBuilder } from "./context-builder";
+export {
+  ContextResolverRegistry,
+  DEFAULT_CONTEXT_RESOLVER_NAMESPACE,
+  registerNamespacedContextResolversIn,
+} from "./context-registry";
+export {
+  contextResolverRegistry,
+  registerNamespacedContextResolvers,
+} from "./context-registry.instance";
+export type { ContextResolverRegistrationOptions } from "./context-registry";
+export type {
+  ContextResolverCircuitBreakerOptions,
+  ContextResolverResilienceOptions,
+  ContextResolverRetryOptions,
+  ContextValueResolver,
+} from "./context-resolver";
+export type { PolicyContextBuilderOptions } from "./context-builder";
+export { ContextSeedValidator } from "./context-seed";
+export type { ContextSeed } from "./context-seed";
+export { PolicyContextPath } from "./path";