@bernierllc/nevar-types 0.0.1 → 0.1.0

package/jest.config.cjs

@@ -0,0 +1,29 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: '<rootDir>/../../../jest-environment-node-fixed.cjs',
+  roots: ['<rootDir>/__tests__'],
+  testMatch: ['**/*.test.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/index.ts'
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 90,
+      functions: 90,
+      lines: 90,
+      statements: 90
+    }
+  },
+  coverageDirectory: 'coverage',
+  verbose: true
+};

package/package.json

@@ -1,10 +1,38 @@
 {
   "name": "@bernierllc/nevar-types",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @bernierllc/nevar-types",
+  "version": "0.1.0",
+  "description": "Shared type definitions, interfaces, error classes, and type guards for the Nevar rules engine suite",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "nevar",
+    "rules-engine",
+    "types",
+    "type-definitions",
+    "error-classes"
+  ],
+  "author": "Bernier LLC",
+  "license": "SEE LICENSE IN LICENSE",
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:run": "jest",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src __tests__ --ext .ts",
+    "clean": "rm -rf dist"
+  }
+}

package/proof-coverage.json

@@ -0,0 +1,41 @@
+{
+  "package": "@bernierllc/nevar-types",
+  "coverageType": "transitive",
+  "proofApp": "proof/nevar-engine",
+  "transitiveThrough": "@bernierllc/nevar-engine",
+  "lastVerified": "2026-03-27",
+  "lastVerifiedVersion": "0.1.0",
+  "features": {
+    "NevarConfig": { "status": "covered", "scenario": "registration" },
+    "Rule": { "status": "covered", "scenario": "rule-crud" },
+    "RuleGroup": { "status": "covered", "scenario": "rule-crud" },
+    "ConditionGroup": { "status": "covered", "scenario": "evaluation-pipeline" },
+    "ActionDefinition": { "status": "covered", "scenario": "rule-crud" },
+    "ActionHandlerDefinition": { "status": "covered", "scenario": "registration" },
+    "ActionResult": { "status": "covered", "scenario": "action-execution" },
+    "ActionIntent": { "status": "covered", "scenario": "evaluation-pipeline" },
+    "DeferredTrigger": { "status": "covered", "scenario": "action-execution" },
+    "EmitResult": { "status": "covered", "scenario": "evaluation-pipeline" },
+    "PreviewResult": { "status": "covered", "scenario": "evaluation-pipeline" },
+    "TriggerDefinition": { "status": "covered", "scenario": "registration" },
+    "OperatorDefinition": { "status": "covered", "scenario": "registration" },
+    "OperatorInfo": { "status": "covered", "scenario": "discovery" },
+    "ExecutionLogEntry": { "status": "covered", "scenario": "evaluation-pipeline" },
+    "NevarStorageAdapter": { "status": "covered", "scenario": "storage-conformance" },
+    "CircuitBreakerConfig": { "status": "covered", "scenario": "safety" },
+    "LoopHandle": { "status": "covered", "scenario": "safety" },
+    "isConditionGroup": { "status": "covered", "scenario": "evaluation-pipeline" },
+    "isCondition": { "status": "covered", "scenario": "evaluation-pipeline" },
+    "NevarValidationError": { "status": "covered", "scenario": "rule-crud" },
+    "NevarStorageError": { "status": "covered", "scenario": "rule-crud" },
+    "EvaluationTrace": { "status": "covered", "scenario": "evaluation-pipeline" },
+    "PaginatedResult": { "status": "covered", "scenario": "storage-conformance" },
+    "GroupFilters": { "status": "covered", "scenario": "storage-conformance" },
+    "RuleFilters": { "status": "covered", "scenario": "storage-conformance" },
+    "LogFilters": { "status": "covered", "scenario": "storage-conformance" },
+    "ActionFailureMode": { "status": "covered", "scenario": "registration" },
+    "ActionRetryConfig": { "status": "covered", "scenario": "action-retry" },
+    "LoopConfig": { "status": "uncovered", "reason": "type exists but engine constructor does not use it in current implementation" },
+    "AuditLoggerConfig": { "status": "uncovered", "reason": "nevar-audit-logger not exercised in proof app" }
+  }
+}

package/src/actions.ts

@@ -0,0 +1,91 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+/**
+ * Configuration for retrying a failed action with exponential backoff.
+ */
+export interface ActionRetryConfig {
+  maxAttempts: number;
+  backoffMs: number;
+  backoffMultiplier: number;
+  maxBackoffMs: number;
+  retryableErrors?: string[];
+}
+
+/**
+ * Defines an action to execute when a rule matches.
+ */
+export interface ActionDefinition {
+  actionType: string;
+  config: Record<string, unknown>;
+  executionOrder: number;
+  retry?: ActionRetryConfig;
+}
+
+/**
+ * An intent represents a planned action derived from a matched rule.
+ */
+export interface ActionIntent {
+  actionType: string;
+  config: Record<string, unknown>;
+  ruleId: string;
+  ruleName: string;
+  retry?: ActionRetryConfig;
+}
+
+/**
+ * A trigger that should be fired as a result of an action execution.
+ */
+export interface DeferredTrigger {
+  triggerKey: string;
+  payload: Record<string, unknown>;
+}
+
+/**
+ * The result of executing a single action.
+ */
+export interface ActionResult {
+  intent: ActionIntent;
+  status: 'success' | 'error';
+  output: Record<string, unknown>;
+  deferredTriggers?: DeferredTrigger[];
+  durationMs: number;
+  attempts: number;
+  lastError?: string;
+}
+
+/**
+ * Controls how action failures are handled within a rule's action list.
+ */
+export type ActionFailureMode = 'fail-fast' | 'best-effort';
+
+/**
+ * Defines an action handler that can be registered with the engine.
+ * Includes the handler function, metadata for discovery, and a config schema.
+ */
+export interface ActionHandlerDefinition {
+  label: string;
+  category: string;
+  canDefer: boolean;
+  configSchema: unknown;
+  handler: (
+    config: Record<string, unknown>,
+    context: Record<string, unknown>,
+    priorResults: ActionResult[]
+  ) => Promise<Record<string, unknown>>;
+}
+
+/**
+ * The aggregate result of executing a set of action intents.
+ */
+export interface ExecutionResult {
+  results: ActionResult[];
+  deferredTriggers: DeferredTrigger[];
+  durationMs: number;
+}
+

package/src/conditions.ts

@@ -0,0 +1,55 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+/**
+ * A group of conditions combined with a logical operator.
+ * NOT groups evaluate children as AND, then negate the result.
+ */
+export interface ConditionGroup {
+  operator: 'AND' | 'OR' | 'NOT';
+  conditions: (ConditionGroup | Condition)[];
+}
+
+/**
+ * A single condition that compares a field value using an operator.
+ */
+export interface Condition {
+  field: string;
+  op: string;
+  value: unknown;
+}
+
+/**
+ * Type guard: checks whether the given value is a ConditionGroup.
+ */
+export function isConditionGroup(value: unknown): value is ConditionGroup {
+  if (value === null || value === undefined || typeof value !== 'object') {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.operator === 'string' &&
+    (obj.operator === 'AND' || obj.operator === 'OR' || obj.operator === 'NOT') &&
+    Array.isArray(obj.conditions)
+  );
+}
+
+/**
+ * Type guard: checks whether the given value is a Condition.
+ */
+export function isCondition(value: unknown): value is Condition {
+  if (value === null || value === undefined || typeof value !== 'object') {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.field === 'string' &&
+    typeof obj.op === 'string' &&
+    'value' in obj
+  );
+}

package/src/config.ts

@@ -0,0 +1,78 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { LogLevel } from './models';
+import { ActionFailureMode } from './actions';
+import { NevarStorageAdapter } from './storage';
+
+/**
+ * Configuration for the circuit breaker that prevents cascading failures.
+ */
+export interface CircuitBreakerConfig {
+  enabled?: boolean;
+  maxFailures?: number;
+  resetTimeMs?: number;
+  halfOpenMaxAttempts?: number;
+  maxCascadeDepth?: number;
+  maxActionsPerChain?: number;
+  maxChainDurationMs?: number;
+  maxConcurrentChains?: number;
+}
+
+/**
+ * Configuration for loop detection and prevention.
+ */
+export interface LoopConfig {
+  maxDepth?: number;
+  maxExecutionsPerTrigger?: number;
+  windowMs?: number;
+  allowInfiniteLoops?: boolean;
+  maxConcurrentLoops?: number;
+  heartbeatIntervalMs?: number;
+  maxMissedHeartbeats?: number;
+}
+
+/**
+ * Configuration for the audit logger.
+ */
+/**
+ * Override structure for per-rule, per-trigger, and per-action log levels.
+ */
+export interface AuditLoggerOverrides {
+  byRule?: Record<string, LogLevel>;
+  byTrigger?: Record<string, LogLevel>;
+  byAction?: Record<string, LogLevel>;
+}
+
+export interface AuditLoggerConfig {
+  enabled?: boolean;
+  logLevel?: LogLevel;
+  retentionDays?: number;
+  defaultLevel?: LogLevel;
+  overrides?: AuditLoggerOverrides;
+}
+
+/**
+ * Strategy for seeding initial rules into storage.
+ */
+export type SeedStrategy = 'skip-existing' | 'overwrite' | 'error-on-conflict' | 'skip_existing' | 'update_existing' | 'replace_all';
+
+/**
+ * Top-level configuration for the Nevar engine.
+ */
+export interface NevarConfig {
+  storage: NevarStorageAdapter;
+  defaultGroupId?: string;
+  logLevel?: LogLevel;
+  failureMode?: ActionFailureMode;
+  actionFailureMode?: ActionFailureMode;
+  circuitBreaker?: CircuitBreakerConfig;
+  loop?: LoopConfig;
+  auditLogger?: AuditLoggerConfig;
+  seedStrategy?: SeedStrategy;
+}

package/src/context.ts

@@ -0,0 +1,16 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+/**
+ * Defines a context provider that enriches trigger payloads with additional data.
+ */
+export interface ContextProviderDefinition {
+  key: string;
+  description?: string;
+  resolve: (payload: Record<string, unknown>) => Promise<Record<string, unknown>>;
+}

package/src/errors.ts

@@ -0,0 +1,102 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+/**
+ * Options for constructing a NevarError.
+ */
+export interface NevarErrorOptions {
+  cause?: Error;
+  code?: string;
+  context?: Record<string, unknown>;
+}
+
+/**
+ * Base error class for all Nevar errors.
+ * Follows ES2022 Error.cause pattern for error chain propagation.
+ */
+export class NevarError extends Error {
+  readonly code: string;
+  readonly context?: Record<string, unknown>;
+
+  constructor(message: string, options?: NevarErrorOptions) {
+    super(message, { cause: options?.cause });
+    this.name = 'NevarError';
+    this.code = options?.code ?? 'NEVAR_ERROR';
+    this.context = options?.context;
+  }
+}
+
+/**
+ * Thrown when a trigger fails to fire or is invalid.
+ */
+export class NevarTriggerError extends NevarError {
+  constructor(message: string, options?: NevarErrorOptions) {
+    super(message, { ...options, code: options?.code ?? 'NEVAR_TRIGGER_ERROR' });
+    this.name = 'NevarTriggerError';
+  }
+}
+
+/**
+ * Thrown when condition evaluation fails.
+ */
+export class NevarEvaluationError extends NevarError {
+  constructor(message: string, options?: NevarErrorOptions) {
+    super(message, { ...options, code: options?.code ?? 'NEVAR_EVALUATION_ERROR' });
+    this.name = 'NevarEvaluationError';
+  }
+}
+
+/**
+ * Thrown when an action fails to execute.
+ */
+export class NevarActionError extends NevarError {
+  constructor(message: string, options?: NevarErrorOptions) {
+    super(message, { ...options, code: options?.code ?? 'NEVAR_ACTION_ERROR' });
+    this.name = 'NevarActionError';
+  }
+}
+
+/**
+ * Thrown when the circuit breaker trips due to too many failures.
+ */
+export class NevarCircuitBreakerError extends NevarError {
+  constructor(message: string, options?: NevarErrorOptions) {
+    super(message, { ...options, code: options?.code ?? 'NEVAR_CIRCUIT_BREAKER_ERROR' });
+    this.name = 'NevarCircuitBreakerError';
+  }
+}
+
+/**
+ * Thrown when a loop is detected in the evaluation chain.
+ */
+export class NevarLoopError extends NevarError {
+  constructor(message: string, options?: NevarErrorOptions) {
+    super(message, { ...options, code: options?.code ?? 'NEVAR_LOOP_ERROR' });
+    this.name = 'NevarLoopError';
+  }
+}
+
+/**
+ * Thrown when a storage operation fails.
+ */
+export class NevarStorageError extends NevarError {
+  constructor(message: string, options?: NevarErrorOptions) {
+    super(message, { ...options, code: options?.code ?? 'NEVAR_STORAGE_ERROR' });
+    this.name = 'NevarStorageError';
+  }
+}
+
+/**
+ * Thrown when input validation fails.
+ */
+export class NevarValidationError extends NevarError {
+  constructor(message: string, options?: NevarErrorOptions) {
+    super(message, { ...options, code: options?.code ?? 'NEVAR_VALIDATION_ERROR' });
+    this.name = 'NevarValidationError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,79 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+// Models
+export type { LogLevel, RuleGroup, Rule, EvaluationTrace } from './models';
+
+// Conditions
+export type { ConditionGroup, Condition } from './conditions';
+export { isConditionGroup, isCondition } from './conditions';
+
+// Actions
+export type {
+  ActionRetryConfig,
+  ActionDefinition,
+  ActionIntent,
+  DeferredTrigger,
+  ActionResult,
+  ActionFailureMode,
+  ActionHandlerDefinition,
+  ExecutionResult,
+} from './actions';
+
+// Triggers
+export type { TriggerDefinition } from './triggers';
+
+// Context
+export type { ContextProviderDefinition } from './context';
+
+// Operators
+export type { OperatorDefinition, OperatorInfo } from './operators';
+
+// Storage
+export type {
+  GroupFilters,
+  RuleFilters,
+  LogFilters,
+  PaginatedResult,
+  ExecutionLogEntry,
+  NevarStorageAdapter,
+} from './storage';
+
+// Config
+export type {
+  CircuitBreakerConfig,
+  LoopConfig,
+  AuditLoggerConfig,
+  AuditLoggerOverrides,
+  SeedStrategy,
+  NevarConfig,
+} from './config';
+
+// Results
+export type {
+  EvaluationResult,
+  EmitResult,
+  PreviewResult,
+  MatchedRule,
+  LoopHandle,
+  LoopAnalysis,
+  DetectedLoop,
+} from './results';
+
+// Errors
+export {
+  NevarError,
+  NevarTriggerError,
+  NevarEvaluationError,
+  NevarActionError,
+  NevarCircuitBreakerError,
+  NevarLoopError,
+  NevarStorageError,
+  NevarValidationError,
+} from './errors';
+export type { NevarErrorOptions } from './errors';

package/src/models.ts

@@ -0,0 +1,68 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { ConditionGroup } from './conditions';
+import { ActionDefinition } from './actions';
+
+/**
+ * Log level for rule evaluation and execution tracing.
+ */
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'all' | 'none' | 'matches_only' | 'errors_only';
+
+/**
+ * A rule group organizes rules under a shared context (e.g., tenant, environment).
+ */
+export interface RuleGroup {
+  id: string;
+  name: string;
+  slug: string;
+  isActive?: boolean;
+  isDefault: boolean;
+  rules?: Rule[];
+  metadata: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * A rule defines conditions that, when matched against a trigger, produce actions.
+ */
+export interface Rule {
+  id: string;
+  groupId: string;
+  name: string;
+  slug: string;
+  triggerType: string;
+  conditions: ConditionGroup;
+  actions: ActionDefinition[];
+  executionOrder: number;
+  isActive: boolean;
+  stopOnMatch: boolean;
+  allowLoop: boolean;
+  logLevel: LogLevel;
+  metadata: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * A single step in the evaluation trace, recording what was evaluated and the outcome.
+ */
+export interface EvaluationTrace {
+  type?: 'group' | 'condition';
+  operator?: 'AND' | 'OR' | 'NOT';
+  field?: string;
+  op?: string;
+  value?: unknown;
+  expected?: unknown;
+  actual?: unknown;
+  result?: boolean;
+  matched?: boolean;
+  children?: EvaluationTrace[];
+  durationMs?: number;
+}

package/src/operators.ts

@@ -0,0 +1,33 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+/**
+ * Full operator definition including the evaluate function.
+ * Used internally by the engine to evaluate conditions.
+ */
+export interface OperatorDefinition {
+  name?: string;
+  description?: string;
+  label?: string;
+  category?: string;
+  fieldTypes?: string[];
+  schema?: unknown;
+  evaluate: (fieldValue: unknown, conditionValue: unknown) => boolean;
+}
+
+/**
+ * Discovery subset of an operator — excludes the evaluate function.
+ * Used for listing available operators to consumers.
+ */
+export interface OperatorInfo {
+  name: string;
+  description?: string;
+  label?: string;
+  category?: string;
+  fieldTypes?: string[];
+}