@criterionx/core 0.1.2 → 0.3.0

package/README.md

@@ -1,69 +1,100 @@
-# Criterion
+# @criterionx/core
 
-Criterion is a **universal decision engine** for defining and executing business-critical decisions with:
+Universal decision engine for business-critical decisions.
 
-- **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)
+## Installation
 
-> 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**.
+```bash
+npm install @criterionx/core zod
+```
 
-A decision is a small, explicit unit of business logic:
-- inputs (schema)
-- outputs (schema)
-- rules (ordered)
-- explanations (trace)
+## Quick Start
+
+```typescript
+import { Engine, defineDecision } from "@criterionx/core";
+import { z } from "zod";
+
+const riskDecision = defineDecision({
+  id: "transaction-risk",
+  version: "1.0.0",
+  inputSchema: z.object({ amount: z.number() }),
+  outputSchema: z.object({ risk: z.enum(["HIGH", "LOW"]) }),
+  profileSchema: z.object({ threshold: z.number() }),
+  rules: [
+    {
+      id: "high-risk",
+      when: (input, profile) => input.amount > profile.threshold,
+      emit: () => ({ risk: "HIGH" }),
+      explain: (input, profile) =>
+        `Amount ${input.amount} exceeds threshold ${profile.threshold}`,
+    },
+    {
+      id: "low-risk",
+      when: () => true,
+      emit: () => ({ risk: "LOW" }),
+      explain: () => "Amount within acceptable range",
+    },
+  ],
+});
+
+const engine = new Engine();
+const result = engine.run(
+  riskDecision,
+  { amount: 15000 },
+  { profile: { threshold: 10000 } }
+);
+
+console.log(result.data); // { risk: "HIGH" }
+```
 
-## What Criterion is not
+---
 
-Criterion is **not**:
-- a workflow/BPMN engine
-- an enterprise rules platform
-- a plugin marketplace
-- a data pipeline
-- a forecasting system
+## Architectural Invariants
 
-Criterion is a **micro engine**: small core, strict boundaries.
+> **This package is HTTP-agnostic. It must never depend on server concerns.**
 
-## Decision Profiles (key idea)
+### Non-Negotiable Principles
 
-Criterion supports **Decision Profiles**: the same decision, different thresholds/sensitivity.
+1. **Pure and Deterministic**
+   - Same input + same profile = same output, always
+   - No hidden state, no side effects
 
-Profiles are injected explicitly at runtime:
+2. **No I/O in Rules**
+   - Rules cannot fetch data
+   - Rules cannot make network calls
+   - Rules cannot read from filesystem
+   - All data must be passed in as context
 
-```ts
-engine.run(decision, context, { profile: "high-inflation" })
-```
+3. **Explicit Dependencies**
+   - No auto-discovery
+   - No magic imports
+   - Decisions are explicitly passed to consumers
 
-Profiles are not data. They are interpretation settings.
+4. **Validation at Boundaries**
+   - Input validated via Zod schema
+   - Output validated via Zod schema
+   - Profile validated via Zod schema
 
-## Repository structure
+5. **Explainability**
+   - Every rule has an `explain` function
+   - Every result includes full audit trace
 
-- `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)
+### What This Package Does NOT Do
 
-## Examples (domain-agnostic)
+- HTTP/REST handling (use `@criterionx/server`)
+- Database operations
+- File system access
+- Network requests
+- Caching
+- Authentication/Authorization
 
-Finance:
-- `examples/finance/currency-exposure-risk/` — generic currency risk using profiles
+This is intentional. The core is a knife, not a Swiss Army knife.
 
-Non-financial:
-- `examples/eligibility/user-tier-eligibility/` — user tier eligibility decision
+---
 
-## Start here
+## Documentation
 
-- `docs/00-manifesto.md`
-- `docs/04-decision-profiles.md`
-- `examples/finance/currency-exposure-risk/decision.xml`
-- `examples/eligibility/user-tier-eligibility/decision.xml`
+Full documentation: [https://tomymaritano.github.io/criterionx/](https://tomymaritano.github.io/criterionx/)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@criterionx/core",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Universal decision engine for business-critical decisions",
   "type": "module",
   "main": "dist/index.js",
@@ -16,14 +16,6 @@
     "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",
@@ -42,12 +34,16 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tomymaritano/criterion.git"
+    "url": "https://github.com/tomymaritano/criterionx.git",
+    "directory": "packages/core"
   },
   "bugs": {
-    "url": "https://github.com/tomymaritano/criterion/issues"
+    "url": "https://github.com/tomymaritano/criterionx/issues"
+  },
+  "homepage": "https://github.com/tomymaritano/criterionx#readme",
+  "peerDependencies": {
+    "zod": "^3.22.0"
   },
-  "homepage": "https://github.com/tomymaritano/criterion#readme",
   "devDependencies": {
     "@vitest/coverage-v8": "^2.0.0",
     "tsup": "^8.0.0",
@@ -55,10 +51,14 @@
     "vitest": "^2.0.0",
     "zod": "^3.22.0"
   },
-  "peerDependencies": {
-    "zod": "^3.22.0"
-  },
   "engines": {
     "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
   }
-}
+}