@criterionx/core 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tomas Maritano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# Criterion
+
+Criterion is a **universal decision engine** for defining and executing business-critical decisions with:
+
+- **Mandatory contracts** (validated inputs & outputs)
+- **Deterministic evaluation** (same inputs → same result)
+- **Explainability first-class** (every result has a reason + trace)
+- **Zero side effects** (no DB, no fetch, no IO inside decisions)
+
+> If it's not in Criterion, it's not a decision.
+
+## What Criterion is
+
+Criterion is **not** a web framework and it does **not** fetch data.
+It runs decisions against a provided **Context**.
+
+A decision is a small, explicit unit of business logic:
+- inputs (schema)
+- outputs (schema)
+- rules (ordered)
+- explanations (trace)
+
+## What Criterion is not
+
+Criterion is **not**:
+- a workflow/BPMN engine
+- an enterprise rules platform
+- a plugin marketplace
+- a data pipeline
+- a forecasting system
+
+Criterion is a **micro engine**: small core, strict boundaries.
+
+## Decision Profiles (key idea)
+
+Criterion supports **Decision Profiles**: the same decision, different thresholds/sensitivity.
+
+Profiles are injected explicitly at runtime:
+
+```ts
+engine.run(decision, context, { profile: "high-inflation" })
+```
+
+Profiles are not data. They are interpretation settings.
+
+## Repository structure
+
+- `docs/` — foundational documentation
+- `examples/` — decision specs in declarative formats (no code required)
+- `diagrams/` — Mermaid diagrams for architecture (optional early)
+- `src/` — future minimal TS implementation (later)
+
+## Examples (domain-agnostic)
+
+Finance:
+- `examples/finance/currency-exposure-risk/` — generic currency risk using profiles
+
+Non-financial:
+- `examples/eligibility/user-tier-eligibility/` — user tier eligibility decision
+
+## Start here
+
+- `docs/00-manifesto.md`
+- `docs/04-decision-profiles.md`
+- `examples/finance/currency-exposure-risk/decision.xml`
+- `examples/eligibility/user-tier-eligibility/decision.xml`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import { ZodSchema } from 'zod';
+
+/**
+ * Result status codes
+ */
+type ResultStatus = "OK" | "NO_MATCH" | "INVALID_INPUT" | "INVALID_OUTPUT";
+/**
+ * Trace entry for rule evaluation
+ */
+interface RuleTrace {
+    ruleId: string;
+    matched: boolean;
+    explanation?: string;
+}
+/**
+ * Result metadata
+ */
+interface ResultMeta {
+    decisionId: string;
+    decisionVersion: string;
+    profileId?: string;
+    matchedRule?: string;
+    evaluatedRules: RuleTrace[];
+    explanation: string;
+    evaluatedAt: string;
+}
+/**
+ * Decision result
+ */
+interface Result<TOutput = unknown> {
+    status: ResultStatus;
+    data: TOutput | null;
+    meta: ResultMeta;
+}
+/**
+ * Rule definition
+ */
+interface Rule<TContext, TProfile, TOutput> {
+    id: string;
+    when: (context: TContext, profile: TProfile) => boolean;
+    emit: (context: TContext, profile: TProfile) => TOutput;
+    explain: (context: TContext, profile: TProfile) => string;
+}
+/**
+ * Decision metadata
+ */
+interface DecisionMeta {
+    owner?: string;
+    tags?: string[];
+    tier?: string;
+    description?: string;
+}
+/**
+ * Decision definition
+ */
+interface Decision<TInput = unknown, TOutput = unknown, TProfile = unknown> {
+    id: string;
+    version: string;
+    inputSchema: ZodSchema<TInput>;
+    outputSchema: ZodSchema<TOutput>;
+    profileSchema: ZodSchema<TProfile>;
+    rules: Rule<TInput, TProfile, TOutput>[];
+    meta?: DecisionMeta;
+}
+/**
+ * Profile registry interface
+ */
+interface ProfileRegistry<TProfile = unknown> {
+    get(id: string): TProfile | undefined;
+    register(id: string, profile: TProfile): void;
+    has(id: string): boolean;
+}
+/**
+ * Engine run options
+ */
+type RunOptions<TProfile> = {
+    profile: string;
+} | {
+    profile: TProfile;
+};
+/**
+ * Helper to check if profile is inline or ID
+ */
+declare function isInlineProfile<TProfile>(options: RunOptions<TProfile>): options is {
+    profile: TProfile;
+};
+/**
+ * Create a simple in-memory profile registry
+ */
+declare function createProfileRegistry<TProfile>(): ProfileRegistry<TProfile>;
+/**
+ * Define a decision with type inference
+ */
+declare function defineDecision<TInput, TOutput, TProfile>(definition: Decision<TInput, TOutput, TProfile>): Decision<TInput, TOutput, TProfile>;
+/**
+ * Create a rule with type inference
+ */
+declare function createRule<TContext, TProfile, TOutput>(rule: Rule<TContext, TProfile, TOutput>): Rule<TContext, TProfile, TOutput>;
+
+/**
+ * Criterion Engine
+ *
+ * Evaluates decisions against context with profile support.
+ * Pure, deterministic, and explainable.
+ */
+declare class Engine {
+    /**
+     * Run a decision against a context
+     */
+    run<TInput, TOutput, TProfile>(decision: Decision<TInput, TOutput, TProfile>, context: TInput, options: RunOptions<TProfile>, registry?: ProfileRegistry<TProfile>): Result<TOutput>;
+    /**
+     * Format explanation for display (helper utility)
+     */
+    explain<TOutput>(result: Result<TOutput>): string;
+    private createErrorResult;
+    private formatZodError;
+}
+/**
+ * Default engine instance
+ */
+declare const engine: Engine;
+
+export { type Decision, type DecisionMeta, Engine, type ProfileRegistry, type Result, type ResultMeta, type ResultStatus, type Rule, type RuleTrace, type RunOptions, createProfileRegistry, createRule, defineDecision, engine, isInlineProfile };

package/dist/index.js

@@ -0,0 +1,211 @@
+// src/types.ts
+function isInlineProfile(options) {
+  return typeof options.profile !== "string";
+}
+function createProfileRegistry() {
+  const profiles = /* @__PURE__ */ new Map();
+  return {
+    get(id) {
+      return profiles.get(id);
+    },
+    register(id, profile) {
+      profiles.set(id, profile);
+    },
+    has(id) {
+      return profiles.has(id);
+    }
+  };
+}
+function defineDecision(definition) {
+  return definition;
+}
+function createRule(rule) {
+  return rule;
+}
+
+// src/engine.ts
+var Engine = class {
+  /**
+   * Run a decision against a context
+   */
+  run(decision, context, options, registry) {
+    const evaluatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const evaluatedRules = [];
+    let profile;
+    let profileId;
+    if (isInlineProfile(options)) {
+      profile = options.profile;
+    } else {
+      profileId = options.profile;
+      if (!registry) {
+        return this.createErrorResult(
+          "INVALID_INPUT",
+          decision,
+          evaluatedRules,
+          evaluatedAt,
+          "Profile ID provided but no registry supplied",
+          profileId
+        );
+      }
+      const resolved = registry.get(profileId);
+      if (!resolved) {
+        return this.createErrorResult(
+          "INVALID_INPUT",
+          decision,
+          evaluatedRules,
+          evaluatedAt,
+          `Profile not found: ${profileId}`,
+          profileId
+        );
+      }
+      profile = resolved;
+    }
+    const inputResult = decision.inputSchema.safeParse(context);
+    if (!inputResult.success) {
+      return this.createErrorResult(
+        "INVALID_INPUT",
+        decision,
+        evaluatedRules,
+        evaluatedAt,
+        this.formatZodError(inputResult.error, "Input"),
+        profileId
+      );
+    }
+    const profileResult = decision.profileSchema.safeParse(profile);
+    if (!profileResult.success) {
+      return this.createErrorResult(
+        "INVALID_INPUT",
+        decision,
+        evaluatedRules,
+        evaluatedAt,
+        this.formatZodError(profileResult.error, "Profile"),
+        profileId
+      );
+    }
+    const validatedInput = inputResult.data;
+    const validatedProfile = profileResult.data;
+    for (const rule of decision.rules) {
+      let matched = false;
+      let explanation;
+      try {
+        matched = rule.when(validatedInput, validatedProfile);
+        if (matched) {
+          explanation = rule.explain(validatedInput, validatedProfile);
+        }
+      } catch (error) {
+        return this.createErrorResult(
+          "INVALID_INPUT",
+          decision,
+          evaluatedRules,
+          evaluatedAt,
+          `Rule evaluation error in ${rule.id}: ${String(error)}`,
+          profileId
+        );
+      }
+      evaluatedRules.push({
+        ruleId: rule.id,
+        matched,
+        explanation
+      });
+      if (matched) {
+        let output;
+        try {
+          output = rule.emit(validatedInput, validatedProfile);
+        } catch (error) {
+          return this.createErrorResult(
+            "INVALID_OUTPUT",
+            decision,
+            evaluatedRules,
+            evaluatedAt,
+            `Rule emit error in ${rule.id}: ${String(error)}`,
+            profileId
+          );
+        }
+        const outputResult = decision.outputSchema.safeParse(output);
+        if (!outputResult.success) {
+          return this.createErrorResult(
+            "INVALID_OUTPUT",
+            decision,
+            evaluatedRules,
+            evaluatedAt,
+            this.formatZodError(outputResult.error, "Output"),
+            profileId
+          );
+        }
+        return {
+          status: "OK",
+          data: outputResult.data,
+          meta: {
+            decisionId: decision.id,
+            decisionVersion: decision.version,
+            profileId,
+            matchedRule: rule.id,
+            evaluatedRules,
+            explanation: explanation ?? "",
+            evaluatedAt
+          }
+        };
+      }
+    }
+    return this.createErrorResult(
+      "NO_MATCH",
+      decision,
+      evaluatedRules,
+      evaluatedAt,
+      "No rule matched the given context",
+      profileId
+    );
+  }
+  /**
+   * Format explanation for display (helper utility)
+   */
+  explain(result) {
+    const { meta } = result;
+    const lines = [];
+    lines.push(`Decision: ${meta.decisionId} v${meta.decisionVersion}`);
+    if (meta.profileId) {
+      lines.push(`Profile: ${meta.profileId}`);
+    }
+    lines.push(`Status: ${result.status}`);
+    if (result.status === "OK" && meta.matchedRule) {
+      lines.push(`Matched: ${meta.matchedRule}`);
+      lines.push(`Reason: ${meta.explanation}`);
+    } else if (result.status !== "OK") {
+      lines.push(`Error: ${meta.explanation}`);
+    }
+    lines.push("");
+    lines.push("Evaluation trace:");
+    for (const trace of meta.evaluatedRules) {
+      const status = trace.matched ? "\u2713" : "\u2717";
+      lines.push(`  ${status} ${trace.ruleId}`);
+    }
+    return lines.join("\n");
+  }
+  createErrorResult(status, decision, evaluatedRules, evaluatedAt, explanation, profileId) {
+    return {
+      status,
+      data: null,
+      meta: {
+        decisionId: decision.id,
+        decisionVersion: decision.version,
+        profileId,
+        evaluatedRules,
+        explanation,
+        evaluatedAt
+      }
+    };
+  }
+  formatZodError(error, prefix) {
+    const issues = error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ");
+    return `${prefix} validation failed: ${issues}`;
+  }
+};
+var engine = new Engine();
+export {
+  Engine,
+  createProfileRegistry,
+  createRule,
+  defineDecision,
+  engine,
+  isInlineProfile
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@criterionx/core",
+  "version": "0.1.1",
+  "description": "Universal decision engine for business-critical decisions",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "decision-engine",
+    "rules-engine",
+    "business-logic",
+    "deterministic",
+    "explainable",
+    "declarative",
+    "pure",
+    "audit",
+    "compliance"
+  ],
+  "author": {
+    "name": "Tomas Maritano",
+    "url": "https://github.com/tomymaritano"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tomymaritano/criterion.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tomymaritano/criterion/issues"
+  },
+  "homepage": "https://github.com/tomymaritano/criterion#readme",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0",
+    "zod": "^3.22.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.22.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}