@cullet/erp-core 1.0.0

package/dist/gate-types.d.ts

@@ -0,0 +1,307 @@
+//#region src/core/result/result.d.ts
+/**
+ * Represents the outcome of an operation that may succeed or fail.
+ * Useful for avoiding excessive exceptions and making error flows explicit.
+ */
+declare abstract class Result<T, E> {
+  protected constructor();
+  /**
+   * Creates a success result containing a value.
+   */
+  static ok<T>(value: T): Result<T, never>;
+  /**
+   * Creates an error result containing an error object.
+   */
+  static err<E>(error: E): Result<never, E>;
+  /**
+   * Returns true when this is a success result.
+   */
+  abstract isOk(): this is Ok<T>;
+  /**
+   * Returns true when this is an error result.
+   */
+  abstract isErr(): this is Err<E>;
+  /**
+   * Runs a handler based on the result state (similar to pattern matching).
+   */
+  abstract match<R>(handlers: {
+    ok: (value: T) => R;
+    err: (error: E) => R;
+  }): R;
+  /**
+   * Returns the value when this is success, or null when this is an error.
+   */
+  getOrNull(): T | null;
+  /**
+   * Returns the error when this is a failure, or null when this is a success.
+   */
+  errorOrNull(): E | null;
+  /**
+   * Returns the value when this is a success, or throws the error when this is a failure.
+   */
+  getOrThrow(): T;
+  /**
+   * Transforms the success value using the provided function. Keeps the error when this is a failure.
+   */
+  map<R>(transform: (value: T) => R): Result<R, E>;
+  /**
+   * Transforms the error using the provided function. Keeps the value when this is a success.
+   */
+  mapError<F>(transform: (error: E) => F): Result<T, F>;
+  /**
+   * Chains another operation that returns a Result when this result is a success.
+   */
+  flatMap<R>(transform: (value: T) => Result<R, E>): Result<R, E>;
+}
+/**
+ * Success variant of Result.
+ */
+declare class Ok<T> extends Result<T, never> {
+  readonly value: T;
+  constructor(value: T);
+  isOk(): this is Ok<T>;
+  isErr(): this is Err<never>;
+  match<R>(handlers: {
+    ok: (value: T) => R;
+    err: (error: never) => R;
+  }): R;
+}
+/**
+ * Error variant of Result.
+ */
+declare class Err<E> extends Result<never, E> {
+  readonly error: E;
+  constructor(error: E);
+  isOk(): this is Ok<never>;
+  isErr(): this is Err<E>;
+  match<R>(handlers: {
+    ok: (value: never) => R;
+    err: (error: E) => R;
+  }): R;
+}
+//#endregion
+//#region src/core/policies/engines/condition-evaluator-reporter.d.ts
+interface ConditionEvaluationCause {
+  readonly name: string;
+  readonly message: string;
+}
+type ConditionEvaluationReportLevel = "warn" | "error";
+type ConditionEvaluationReportTag = "MISSING_CONTEXT_FIELD" | "NULLISH_NUMERIC_OPERAND_NOT_ALLOWED" | "NULLISH_DATE_OPERAND_NOT_ALLOWED" | "INVALID_DATE_OPERAND" | "CONDITION_EVAL_THREW";
+interface ConditionEvaluationReport {
+  readonly occurredAt: Date;
+  readonly level: ConditionEvaluationReportLevel;
+  readonly tag: ConditionEvaluationReportTag;
+  readonly message: string;
+  readonly engineVersion: number;
+  readonly details: Readonly<Record<string, unknown>>;
+}
+interface ConditionEvaluatorReporter {
+  warn(report: ConditionEvaluationReport): void;
+  error(report: ConditionEvaluationReport): void;
+}
+type ConditionEvaluationOptions = {
+  readonly reporter: ConditionEvaluatorReporter;
+  readonly engineVersion: number;
+};
+//#endregion
+//#region src/core/policies/policy-ids.d.ts
+type Brand<TValue, TBrand extends string> = TValue & {
+  readonly __brand: TBrand;
+};
+type PolicyDefinitionId = Brand<string, "PolicyDefinitionId">;
+type PolicyDecisionId = Brand<string, "PolicyDecisionId">;
+type TenantId = Brand<string, "TenantId">;
+type SchoolId = Brand<string, "SchoolId">;
+declare function asPolicyDefinitionId(value: string): PolicyDefinitionId;
+declare function asPolicyDecisionId(value: string): PolicyDecisionId;
+declare function asTenantId(value: string): TenantId;
+declare function asSchoolId(value: string): SchoolId;
+//#endregion
+//#region src/core/config/policy-reporter.d.ts
+type ConditionEvalEvent = ConditionEvaluationReport & {
+  readonly kind: "condition-eval";
+};
+interface PolicyResolutionEvent {
+  readonly kind: "policy-resolution";
+  readonly level: "info";
+  readonly policyKey: string;
+  readonly definitionId: PolicyDefinitionId;
+  readonly policyVersion: string;
+  readonly engineKind: "GATE" | "COMPUTE";
+  readonly engineVersion: number;
+  readonly occurredAt: Date;
+}
+interface PolicyEvaluationFailedEvent {
+  readonly kind: "policy-evaluation-failed";
+  readonly level: "error";
+  readonly policyKey: string | undefined;
+  readonly errorKind: string;
+  readonly message: string;
+  readonly cause: string;
+  readonly occurredAt: Date;
+}
+interface PolicyEvaluationCompletedEvent {
+  readonly kind: "policy-evaluation-completed";
+  readonly level: "info";
+  readonly policyKey: string;
+  readonly decisionId: PolicyDecisionId;
+  readonly engineKind: "GATE" | "COMPUTE";
+  readonly occurredAt: Date;
+}
+type PolicyEvent = ConditionEvalEvent | PolicyResolutionEvent | PolicyEvaluationFailedEvent | PolicyEvaluationCompletedEvent;
+interface PolicyReporter {
+  report(event: PolicyEvent): void;
+}
+//#endregion
+//#region src/core/config/core-config.d.ts
+interface CoreObservabilityConfig {
+  readonly reporter?: PolicyReporter;
+}
+interface CoreConfigOptions {
+  readonly observability?: CoreObservabilityConfig;
+}
+/**
+ * Centraliza a configuracao pura do core sem depender de implementacoes
+ * concretas de logging, tracing ou report.
+ */
+declare class CoreConfig {
+  #private;
+  constructor(options?: CoreConfigOptions);
+  configure(options: CoreConfigOptions): this;
+  reset(): this;
+  getPolicyReporter(): PolicyReporter;
+  getConditionEvaluationOptions(engineVersion: number): ConditionEvaluationOptions;
+}
+//#endregion
+//#region src/core/result/outcome.d.ts
+/**
+ * Outcome — Business decision abstraction.
+ *
+ * Represents the semantic result of a domain decision, policy evaluation,
+ * or business rule. NOT for technical success/failure — use Result for that.
+ *
+ * Mental model:
+ *   "What was the business decision?"
+ *   NOT "Did the operation succeed?"
+ *
+ * The status axis represents valid business outcomes (APPROVED, REJECTED,
+ * ALLOW, DENY, NO_OP, etc.), never technical Ok/Err.
+ *
+ * @typeParam S - Union of valid status literals for this outcome
+ * @typeParam D - Shape of the decision data carried by this outcome
+ */
+declare class Outcome<S extends string, D = undefined> {
+  readonly status: S;
+  readonly data: D;
+  readonly reason: string | undefined;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  private constructor();
+  static of<S extends string, D = undefined>(status: S, data: D, reason?: string, metadata?: Record<string, unknown>): Outcome<S, D>;
+  static approved<D = undefined>(data: D, reason?: string): Outcome<"APPROVED", D>;
+  static rejected<D = undefined>(data: D, reason: string): Outcome<"REJECTED", D>;
+  static noOp<D = undefined>(data: D, reason?: string): Outcome<"NO_OP", D>;
+  static deferred<D = undefined>(data: D, reason: string): Outcome<"DEFERRED", D>;
+  static requiresReview<D = undefined>(data: D, reason: string): Outcome<"REQUIRES_REVIEW", D>;
+  /**
+   * Narrows this Outcome to a specific status.
+   *
+   * @example
+   * if (outcome.is('DENY')) {
+   *   outcome.data.violations // TS knows status is 'DENY'
+   * }
+   */
+  is<T extends S>(status: T): this is Outcome<T, D>;
+  /**
+   * Exhaustive pattern match over all possible statuses.
+   * TypeScript enforces that every status has a handler.
+   *
+   * @example
+   * outcome.match({
+   *   ALLOW: (o) => handleAllow(o.data),
+   *   DENY:  (o) => handleDeny(o.data.violations),
+   * })
+   */
+  match<THandlers extends { [K in S]: (outcome: Outcome<K, D>) => unknown }>(handlers: THandlers): ReturnType<THandlers[S]>;
+  withMetadata(extra: Record<string, unknown>): Outcome<S, D>;
+  withReason(reason: string): Outcome<S, D>;
+  toString(): string;
+}
+/** Common business outcome statuses. Extend per domain as needed. */
+type CommonOutcomeStatus = "APPROVED" | "REJECTED" | "NO_OP" | "DEFERRED" | "REQUIRES_REVIEW";
+//#endregion
+//#region src/core/policies/engines/v1/condition-types.d.ts
+type ConditionOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "isNull" | "isNotNull";
+interface ConditionLeafNode {
+  readonly field: string;
+  readonly op: ConditionOp;
+  readonly value: unknown;
+  readonly allowNull?: true;
+}
+interface ConditionAndNode {
+  readonly and: readonly ConditionNode[];
+}
+interface ConditionOrNode {
+  readonly or: readonly ConditionNode[];
+}
+interface ConditionNotNode {
+  readonly not: ConditionNode;
+}
+type ConditionNode = ConditionLeafNode | ConditionAndNode | ConditionOrNode | ConditionNotNode;
+//#endregion
+//#region src/core/policies/engines/v1/gate/gate-types-v1.d.ts
+type GatePayloadV1 = {
+  readonly condition: ConditionNode;
+} | {
+  readonly allowIf: ConditionNode;
+  readonly defaultOutcome: "ALLOW" | "DENY";
+};
+//#endregion
+//#region src/core/policies/engines/gate-payload.d.ts
+type GatePayload = GatePayloadV1;
+//#endregion
+//#region src/core/policies/engines/gate-types.d.ts
+type PolicyContext = Record<string, unknown>;
+interface GateTraceLeafSnapshot {
+  readonly kind: "LEAF";
+  readonly field: string;
+  readonly op: string;
+  readonly allowNull?: true;
+}
+type GateTraceNodeSnapshot = GateTraceLeafSnapshot | {
+  readonly kind: "AND" | "OR";
+  readonly childCount: number;
+} | {
+  readonly kind: "NOT";
+};
+interface GateViolationTrace {
+  readonly conditionPath: string;
+  readonly decisiveNode: GateTraceNodeSnapshot;
+  readonly lastEvaluatedLeaf: GateTraceLeafSnapshot;
+  readonly lastEvaluatedLeafPath: string;
+  readonly lastEvaluatedLeafResult: boolean;
+  readonly field: string;
+  readonly op: string;
+}
+interface PolicyViolation {
+  readonly code: string;
+  readonly message: string;
+  readonly trace?: GateViolationTrace;
+}
+type GateStatus = "ALLOW" | "DENY";
+interface GateOutcomeData {
+  readonly violations: readonly PolicyViolation[];
+}
+/** Semantic outcome of a GATE policy evaluation. */
+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`.
+ */
+interface VersionedGateEngine {
+  readonly version: number;
+  evaluate(payload: GatePayload, context: PolicyContext): Result<GateOutcome, string>;
+}
+//#endregion
+export { ConditionEvaluationReport as A, TenantId as C, asTenantId as D, asSchoolId as E, Ok as F, Result as I, ConditionEvaluationReportTag as M, ConditionEvaluatorReporter as N, ConditionEvaluationCause as O, Err as P, SchoolId as S, asPolicyDefinitionId as T, CoreConfigOptions as _, GateTraceNodeSnapshot as a, PolicyDecisionId as b, PolicyViolation as c, GatePayloadV1 as d, ConditionLeafNode as f, CoreConfig as g, Outcome as h, GateTraceLeafSnapshot as i, ConditionEvaluationReportLevel as j, ConditionEvaluationOptions as k, VersionedGateEngine as l, CommonOutcomeStatus as m, GateOutcomeData as n, GateViolationTrace as o, ConditionNode as p, GateStatus as r, PolicyContext as s, GateOutcome as t, GatePayload as u, CoreObservabilityConfig as v, asPolicyDecisionId as w, PolicyDefinitionId as x, PolicyReporter as y };
+//# sourceMappingURL=gate-types.d.ts.map