Deterministic, evidence-based verification framework for software systems.

Truth Core provides a verification platform featuring content-addressed caching, parallel execution, and comprehensive anomaly detection. All operations run without non-deterministic external dependencies.

• Deterministic Outputs - Same inputs always produce same outputs
• Content-Addressed Cache - Reuse previous results for identical inputs
• Parallel Execution - Multi-engine commands run in parallel
• Security Hardening - Protection against resource exhaustion and injection
• Run Manifests - Full provenance tracking with content hashes
• Static Dashboard - Offline-capable HTML dashboard for results
• Anomaly Detection - Deterministic scoring for historical analysis
• UI Geometry Checks - Verify actual clickability of UI elements
• Parquet History - High-performance optional storage
• HTTP Server - REST API and web GUI for remote access
• Replay/Simulation - Re-run and simulate changes for analysis

# Install
pip install truth-core

# Run verification
truthctl judge --inputs ./src --profile ui --out ./results

# View with dashboard
truthctl dashboard demo --out ./demo

# Open demo_out/dashboard/index.html in your browser

# Basic installation
pip install truth-core

# With development dependencies
pip install truth-core[dev]

# With Parquet support for history storage
pip install truth-core[parquet]

# All features
pip install truth-core[dev,parquet]

Copy .env.example to .env and configure at least:

• TRUTHCORE_API_KEY (enable API authentication)
• TRUTHCORE_CORS_ORIGINS
• TRUTHCORE_RATE_LIMIT_MAX, TRUTHCORE_RATE_LIMIT_WINDOW
• TRUTHCORE_CACHE_DIR, TRUTHCORE_CACHE_ENABLED

# Install deps
pip install -e '.[dev,parquet]'
pnpm install

# Lint and typecheck
pnpm run lint
pnpm run typecheck

# Tests
pnpm run test

Truth Core provides a deterministic rules engine that produces auditable evidence packets for all policy evaluations.

from truthcore.rules_engine import evaluate

# Evaluate input against a policy pack
result = evaluate("./src", "security")
print(f"Decision: {result['decision']}")  # "allow", "deny", or "conditional"
print(f"Evidence: {result['evidence']}")  # EvidencePacket object
print(result['summary'])  # Human-readable markdown summary

Every evaluation produces a machine-readable JSON evidence packet containing:

• Inputs: Content hash and summary of evaluated data
• Rules Evaluated: Detailed evaluation of each rule with match counts and thresholds
• Decisions: Final decision with reasoning
• Timestamps & Versions: For auditability
• Explain Why Not: For each rule, why alternatives didn't trigger

1. Define the rule in YAML under src/truthcore/policy/packs/:

   - id: YOUR_RULE_ID
     description: What this rule detects
     severity: HIGH  # BLOCKER, HIGH, MEDIUM, LOW
     category: security  # security, privacy, config, artifact
     target: files  # files, logs, json_fields, findings, traces
     matchers:
       - type: regex
         pattern: "your-pattern"
     suggestion: How to fix violations

2. Test locally with the new API:

   truthctl policy run --inputs ./test-data --pack base --out ./test-results

3. Add golden tests in tests/test_evidence_golden.py to ensure deterministic behavior

4. Update documentation - rules are self-documenting via evidence packets

• Decision = "allow": All checks passed, no violations found
• Decision = "conditional": Non-blocking findings found, review recommended
• Decision = "deny": Blocking violations detected, action required

Evidence packets include "Explain Why Not" for each rule, showing why alternatives didn't trigger (e.g., "No matches found for pattern", "Threshold not met").

- name: Truth Core Verification
  uses: your-org/truth-core/integrations/github-actions@main
  with:
    profile: readylayer        # Options: readylayer, settler, aias, keys
    inputs-path: ./src
    output-path: verdict.json

- name: Check Results
  run: |
    if [ "${{ steps.truthcore.outputs.verdict }}" = "FAIL" ]; then
      exit 1
    fi

Profiles:

• readylayer - PR/CI quality gates (threshold configurable)
• settler - Release readiness (threshold configurable)
• aias - AI agent trace validation (threshold configurable)
• keys - Security credential verification (threshold configurable)

npm install @truth-core/contract-sdk

import { loadVerdict, topFindings, filterBySeverity } from "@truth-core/contract-sdk";

// Load and validate
const verdict = loadVerdict(await fetch("/api/verdict").then(r => r.json()));

// Analyze
const blockers = filterBySeverity(verdict, "BLOCKER");
const topIssues = topFindings(verdict, 5);

console.log(`${verdict.verdict}: ${verdict.value}/100 with ${blockers.length} blockers`);

# Run verification
truthctl judge --inputs ./src --profile ui --out ./results

# Check output
cat ./results/verdict.json | jq '.verdict'

# View in dashboard
truthctl dashboard serve --runs ./results --port 8787

Truth Core includes a professional static dashboard for viewing results:

• Fully Offline - No external CDN dependencies
• GitHub Pages Ready - Build once, host anywhere
• Interactive Charts - SVG charts generated locally
• Dark/Light Theme - Automatic and manual switching
• Accessibility - Keyboard navigation, screen reader friendly

Truth Core artifacts remain with your organization. The dashboard is designed to integrate into existing operating models and internal controls.

# Build with embedded runs
truthctl dashboard build --runs ./my-runs --out ./dashboard-dist

# Serve locally
truthctl dashboard serve --runs ./my-runs --port 8787

# Create portable snapshot
truthctl dashboard snapshot --runs ./my-runs --out ./snapshot

# Run demo
truthctl dashboard demo --out ./demo-out

• truthctl judge - Run readiness engine with invariants
• truthctl recon - Reconcile financial transactions
• truthctl trace - Analyze agent execution traces
• truthctl index - Index knowledge base
• truthctl intel - Run intelligence analysis

• truthctl dashboard build - Build static dashboard
• truthctl dashboard serve - Serve dashboard locally
• truthctl dashboard snapshot - Create portable snapshot
• truthctl dashboard demo - Run demo with sample data

• truthctl cache-stats - Show cache statistics
• truthctl cache-compact - Remove old entries
• truthctl cache-clear - Clear all cache entries

• truthctl serve - Start HTTP server with REST API and web GUI
• truthctl serve --port 8080 - Start on custom port
• truthctl serve --reload - Development mode with auto-reload

• truthctl explain - Explain invariant rule evaluation

Immutable, signed artifacts produced by verification runs. Each piece of evidence includes content hashes for integrity verification. Evidence remains under your organization's custody.

Declarative rules that define "must always be true" conditions for your system. Invariants are checked automatically during verification. All rule evaluations are auditable.

Policy-as-code for security, privacy, and compliance checks. Define rules in YAML and run them against any codebase. Policies integrate with your existing approval structures.

Provable Rules Engine - All policy evaluations produce auditable evidence packets containing inputs, rules evaluated, decisions, and timestamps. Outputs are deterministic and verifiable.

Full chain of custody for all evidence. Know exactly when, how, and by whom each artifact was created. All provenance data is preserved in local artifacts.

The final decision: PASS, FAIL, or CONDITIONAL. Includes a score (0-100) and detailed findings.

Re-run past verifications with the same inputs, or simulate "what-if" scenarios by adjusting thresholds and rules. All simulation results are clearly labeled as projections and require human review.

Versioned schemas for all artifacts ensure backward compatibility. Migrate between versions through documented procedures. Schema versions are explicit in all artifacts.

Each command produces:

• run_manifest.json - Full provenance with content hashes
• verdict.json - Machine-readable verdict
• verdict.md - Human-readable report
• *.csv - Tabular data (where applicable)

All artifacts remain under your organization's control. No artifacts are transmitted to external services.

.truthcache/
├── index.json           # Cache index
├── <hash>/              # Cached outputs
│   ├── readiness.json
│   └── run_manifest.json

Truth Core implements defense in depth with the following controls:

• Path Traversal Protection - All paths validated before access
• Resource Limits - Configurable limits on file size, JSON depth
• Output Sanitization - Markdown outputs sanitized to prevent injection
• Safe Archive Extraction - Zip extraction with traversal checks
• Evidence Signing - Ed25519 signatures for tamper detection

All verification workflows include human-in-the-loop review points. Least privilege access is enforced through configurable permission boundaries.

See SECURITY.md for vulnerability reporting.

All operations are designed to be deterministic:

• Stable sorting of all collections
• Normalized UTC timestamps
• Canonical JSON serialization
• Content-addressed hashing (blake2b, sha256, sha3)
• No random sampling or probabilistic methods

Outputs are reproducible for verification and audit purposes.

• Contributing Guide - Development guidelines
• Code of Conduct - Community standards
• Security Policy - Security information
• Reality Map - Stack and flow overview
• Deployment Guide - Local and production deployment
• Security Notes - Threat model and controls
• Governance - Project governance
• Upgrade Notes - Version upgrade guide
• Changelog - Version history

Truth Core includes a shared Contract Kit (/contracts) that defines schemas for cross-repo integration. CI enforces these contracts on every push and PR.

Located in /contracts:

Artifact schemas (verdict, readiness) live in src/truthcore/schemas/.

# Validate all contracts, SDK exports, CLI entrypoints, and schema sync
pnpm contracts:check

# Verify environment: versions, dependencies, build tools, secret scan
pnpm doctor

# Run full CI pipeline (lint + typecheck + test + contracts:check + doctor)
pnpm ci

# Setup
pip install -e '.[dev,parquet]'
pnpm install

# Run tests
pytest -q

# Run linting
ruff check .
ruff format .

# Type checking
pyright src/truthcore

# Validate contracts
pnpm contracts:check

# Environment health check
pnpm doctor

# Build package
python -m build

# Dashboard development
cd dashboard
npm install
npm run dev

MIT License - see LICENSE for details.

Version: 0.2.0
Python: 3.11+