Decision Ledger

A strict, deterministic decision engine for recordable, replayable logic.

Decision Ledger allows you to define policies in a structured Intermediate Representation (IR) and evaluate them against input contexts. Every decision returned is a record of exactly why a result was reached, allowing for perfect auditability and replayability.

Features

• Strict Validation: Policies and contexts are validated against schemas before evaluation.
• Deterministic: Given the same policy and context, the engine always produces the same outcome and trace.
• Auditable: Every decision returns a full trace of which rules were evaluated and why.
• Replayable: Includes built-in support for verifying decisions after the fact.
• TypeScript First: Full type safety for policies, contexts, and results.

Installation

npm i @shaevon/decision-ledger

Quick Start

import { 
  evaluateDecision, 
  InMemoryDecisionRecordStore, 
  PolicyIR,
  ComparisonOperator 
} from 'decision-ledger';

const store = new InMemoryDecisionRecordStore();

const policy: PolicyIR = {
  policy_id: "fraud-prevention-v1",
  namespace: "payments",
  decision_type: "fraud-check",
  input_schema: {
    transaction_amount: { kind: "int" },
    is_international: { kind: "int" } // 0 or 1
  },
  rules: [
    {
      id: "high-value-international",
      when: { 
        all: [
          { field: "transaction_amount", op: ComparisonOperator.GT, value: 10000 },
          { field: "is_international", op: ComparisonOperator.EQ, value: 1 }
        ]
      },
      then: { outcome: "FLAG_FOR_REVIEW", reason: "High-value international transaction" }
    },
    {
      id: "low-value-safe",
      when: { field: "transaction_amount", op: ComparisonOperator.LT, value: 50 },
      then: { outcome: "AUTO_ALLOW", reason: "Transaction value below threshold" }
    }
  ],
  default: { outcome: "ALLOW", reason: "Standard transaction" }
};

const result = evaluateDecision({
  decision_id: "tx-7890",
  namespace: "payments",
  decision_type: "fraud-check",
  policy_hash: "hash-v1",
  raw_context: { 
    transaction_amount: 15000, 
    is_international: 1 
  },
  created_at: new Date().toISOString(),
  store,
  policy
});

console.log(result.outcome); // "FLAG_FOR_REVIEW"

Advanced Usage

Replaying Decisions

Decision Ledger provides a verifyReplay utility to ensure that stored decisions are still valid against the policies that created them.

import { verifyReplay } from 'decision-ledger';

const result = verifyReplay(decision_id, recordStore, policyStore);
if (result.ok) {
  console.log("Decision is valid and consistent.");
}

License

ISC