Decision Ledger

A strict, deterministic decision engine for recordable, replayable logic, backed by Neon (Postgres).

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.

Key Features

• Strict Validation: Policies and contexts are validated against schemas before evaluation.
• Neon Persistence: Transactional storage for decision records and policy bundles.
• Cryptographic Hashing: Every decision is part of a hash-chained ledger, preventing tampering.
• Deterministic: Given the same policy and context, the engine always produces the same outcome and trace.
• Policy CI/CD: Ingest and activate policies dynamically via GitHub Actions and secured API routes.
• Explainable: Every decision returns a full trace of which rules were evaluated and why.

Architecture

Decision Ledger operates as a standalone service with a Neon PostgreSQL backend.

• API Server: Fastify-based REST API for evaluation, retrieval, and policy management.
• Ledger: Hash-chained decision records stored in JSONB with raw string integrity.
• Policy Store: Immutable policy bundles stored in the database and cached in memory.

Quick Start

1. Initialize Database

bun scripts/init-db.ts

2. Start API Server

bun run dev

3. Evaluate a Decision

curl -X POST http://localhost:3000/decisions/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "decision_id": "tx-7890",
    "namespace": "payments",
    "decision_type": "fraud-check",
    "policy_hash": "v1",
    "context": { "amount": 150 }
  }'

Advanced Usage

Policy Management

Policies are managed as "Bundles". You can ingest a new set of policies and activate them without restarting the server:

# Ingest bundle
curl -X POST http://localhost:3000/policies/ingest \
  -H "x-api-key: your-secret-key" \
  -d @bundle.json

# Activate
curl -X POST http://localhost:3000/policies/<hash>/activate \
  -H "x-api-key: your-secret-key"

Replaying Decisions

Ensure integrity by re-running historical decisions against the original policy:

curl -X POST http://localhost:3000/decisions/<id>/replay

License

ISC