@criterionx/core 0.2.0 → 0.3.0

package/README.md

@@ -1,30 +1,6 @@
-<p align="center">
-  <img src="criterion.jpg" alt="Criterion" width="100%" />
-</p>
+# @criterionx/core
 
-<p align="center">
-  <strong>A universal, deterministic, and explainable decision engine for business-critical systems.</strong>
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@criterionx/core"><img src="https://img.shields.io/npm/v/@criterionx/core.svg" alt="npm version"></a>
-  <a href="https://github.com/tomymaritano/criterionx/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@criterionx/core.svg" alt="license"></a>
-  <a href="https://tomymaritano.github.io/criterionx/"><img src="https://img.shields.io/badge/docs-vitepress-brightgreen.svg" alt="docs"></a>
-</p>
-
----
-
-## What is Criterion?
-
-Criterion helps you encode business decisions as **pure, testable functions** with built-in validation and explainability.
-
-Instead of scattering `if/else` statements across your codebase, you define decisions declaratively:
-
-- **"Should this transaction be flagged as high-risk?"**
-- **"Is this user eligible for a premium tier?"**
-- **"What discount applies to this order?"**
-
-Every decision returns not just a result, but a complete explanation of *why* that result was reached — perfect for audits, debugging, and compliance.
+Universal decision engine for business-critical decisions.
 
 ## Installation
 
@@ -42,14 +18,15 @@ const riskDecision = defineDecision({
   id: "transaction-risk",
   version: "1.0.0",
   inputSchema: z.object({ amount: z.number() }),
-  outputSchema: z.object({ risk: z.enum(["HIGH", "MEDIUM", "LOW"]) }),
+  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} > ${profile.threshold}`,
+      explain: (input, profile) =>
+        `Amount ${input.amount} exceeds threshold ${profile.threshold}`,
     },
     {
       id: "low-risk",
@@ -67,77 +44,58 @@ const result = engine.run(
   { profile: { threshold: 10000 } }
 );
 
-console.log(result.data);  // { risk: "HIGH" }
-console.log(engine.explain(result));
-// Decision: transaction-risk v1.0.0
-// Status: OK
-// Matched: high-risk
-// Reason: Amount 15000 > 10000
+console.log(result.data); // { risk: "HIGH" }
 ```
 
-## Features
-
-- **Pure & Deterministic** — Same input always produces the same output
-- **Fully Explainable** — Every decision includes a complete audit trail
-- **Contract-First** — Zod schemas validate inputs, outputs, and profiles
-- **Profile-Driven** — Parameterize decisions by region, tier, or environment
-- **Zero Side Effects** — No I/O, no database, no external calls
-- **Testable by Design** — Pure functions are trivial to test
-
-## Documentation
+---
 
-Full documentation available at **[tomymaritano.github.io/criterion](https://tomymaritano.github.io/criterionx/)**
+## Architectural Invariants
 
-- [Getting Started](https://tomymaritano.github.io/criterionx/guide/getting-started)
-- [Core Concepts](https://tomymaritano.github.io/criterionx/guide/core-concepts)
-- [API Reference](https://tomymaritano.github.io/criterionx/api/engine)
-- [Examples](https://tomymaritano.github.io/criterionx/examples/currency-risk)
+> **This package is HTTP-agnostic. It must never depend on server concerns.**
 
-## Core Concepts
+### Non-Negotiable Principles
 
-### Decisions
+1. **Pure and Deterministic**
+   - Same input + same profile = same output, always
+   - No hidden state, no side effects
 
-A decision is a unit of business logic with:
-- **Input schema** — What data is required
-- **Output schema** — What the decision returns
-- **Profile schema** — What can be parameterized
-- **Rules** — The evaluation logic
+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
 
-### Rules
+3. **Explicit Dependencies**
+   - No auto-discovery
+   - No magic imports
+   - Decisions are explicitly passed to consumers
 
-Rules are evaluated in order. First match wins:
+4. **Validation at Boundaries**
+   - Input validated via Zod schema
+   - Output validated via Zod schema
+   - Profile validated via Zod schema
 
-```typescript
-rules: [
-  { id: "rule-1", when: (i) => i.x > 100, emit: ..., explain: ... },
-  { id: "rule-2", when: (i) => i.x > 50, emit: ..., explain: ... },
-  { id: "default", when: () => true, emit: ..., explain: ... },
-]
-```
+5. **Explainability**
+   - Every rule has an `explain` function
+   - Every result includes full audit trace
 
-### Profiles
+### What This Package Does NOT Do
 
-Profiles parameterize decisions without changing logic:
+- HTTP/REST handling (use `@criterionx/server`)
+- Database operations
+- File system access
+- Network requests
+- Caching
+- Authentication/Authorization
 
-```typescript
-// Same decision, different thresholds
-engine.run(decision, input, { profile: usProfile });
-engine.run(decision, input, { profile: euProfile });
-```
+This is intentional. The core is a knife, not a Swiss Army knife.
 
-## What Criterion Is NOT
+---
 
-- A workflow/BPMN engine
-- A machine learning framework
-- A data pipeline
-- A plugin marketplace
+## Documentation
 
-Criterion is a **micro engine**: small core, strict boundaries.
+Full documentation: [https://tomymaritano.github.io/criterionx/](https://tomymaritano.github.io/criterionx/)
 
 ## License
 
-[MIT](LICENSE)
-
-## Author
-
-**Tomas Maritano** — [@tomymaritano](https://github.com/tomymaritano)
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@criterionx/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Universal decision engine for business-critical decisions",
   "type": "module",
   "main": "dist/index.js",
@@ -16,18 +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",
-    "benchmark": "tsx benchmarks/run.ts",
-    "prepublishOnly": "npm run build",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
-  },
   "keywords": [
     "decision-engine",
     "rules-engine",
@@ -46,25 +34,31 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tomymaritano/criterionx.git"
+    "url": "https://github.com/tomymaritano/criterionx.git",
+    "directory": "packages/core"
   },
   "bugs": {
     "url": "https://github.com/tomymaritano/criterionx/issues"
   },
   "homepage": "https://github.com/tomymaritano/criterionx#readme",
+  "peerDependencies": {
+    "zod": "^3.22.0"
+  },
   "devDependencies": {
     "@vitest/coverage-v8": "^2.0.0",
     "tsup": "^8.0.0",
-    "tsx": "^4.7.0",
     "typescript": "^5.3.0",
-    "vitepress": "^1.6.4",
     "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"
   }
-}
+}