Manthan OS — Deterministic Decision Infrastructure

Every decision is traceable, auditable, and built for trust.

Manthan is a Deterministic Decision Operating System that enforces decisions as infrastructure, not opinion.

It ensures that:

• Decisions are contract-defined
• Evaluation is deterministic
• Enforcement is automated
• Every outcome is fully traceable

---

What Manthan Does

Manthan sits in your development workflow (via PR Gate) and:

• Evaluates changes against explicit contracts
• Ignores declared intent if it conflicts with actual diff
• Produces a deterministic decision
• Blocks or allows changes based on rules
• Generates a full trace + explanation

---

Core Principles

1. Determinism is Absolute

• Same input → same output
• No randomness, no hidden state, no timestamps
• No external calls inside decision engine

2. Contract is Source of Truth

• Contracts define all rules
• No runtime mutation
• Full contract flows into decision trace

3. Intent is NOT Truth

“Intent is a claim, not truth.”

• PR description is ignored if it conflicts with diff
• filesChanged always overrides intent
• Mismatch → BLOCK

4. Fail Fast Execution

Strict evaluation order:

contract_validation
→ determinism_check
→ boundary_check
→ intent_alignment
→ base_rules

• First failure stops execution
• All executed steps are recorded in trace

---

System Architecture (Locked)

manthan/
├── packages/core       # engine, validator, explanation
├── registry            # contract loading
├── api                 # webhook server (GitHub integration)
├── enforcement         # PR enforcement logic
├── contracts           # JSON contracts (source of truth)
├── cli                 # local execution interface
├── tests               # deterministic test cases

⚠️ No architecture drift allowed.

---

Decision Output Format

Every decision follows a strict structure:

{
  "decision": {
    "decisionId": "string",
    "status": "PASS | BLOCKED",
    "failedStep": "string | null"
  },
  "trace": {
    "decisionId": "string",
    "pr": {},
    "contract": {},
    "evaluationSteps": []
  }
}

---

Explanation Format

Derived strictly from trace:

{
  "summary": "PASS | BLOCKED",
  "why": "Exact failure reason",
  "actions": ["Clear corrective steps"]
}

No inferred reasoning. No assumptions.

---

Getting Started

Install

npm install

---

Run Locally (CLI)

node cli/run.js --pr ./payload.json --contract sample-contract

---

Run Tests

npm test

---

Start API (Webhook Server)

node api/server.js

---

GitHub PR Gate

Manthan integrates as a GitHub App and:

• Listens to PR webhooks

• Extracts:

  • filesChanged
  • PR metadata

• Runs deterministic evaluation

• Enforces decision via:

  • Check Runs
  • Commit Status
  • PR Comments

---

Contracts

Located in:

/contracts

Contracts define:

• Intent
• Inputs
• Rules
• Boundaries
• Error model

Example:

{
  "intent": "Restrict changes to UI layer",
  "boundaries": {
    "allowedPaths": ["ui/"]
  }
}

---

CLI Capabilities

• Run decision locally
• Test contracts
• Generate explanations
• Debug traces

---

Current Version

v0.2 — Deterministic PR Gate (LOCKED)

Includes:

• Deterministic engine
• Contract validation
• Full trace generation
• GitHub PR enforcement
• CLI interface

No changes allowed without version upgrade.

---

Allowed Changes

• Bug fixes
• Logging (debug only)
• Missing wiring fixes
• CLI UX improvements (non-breaking)
• Documentation

---

Not Allowed

• AI/LLM decision making
• Dynamic rule execution
• Contract mutation
• Hidden logic
• Architecture changes

---

Philosophy

Manthan is not a tool.

It is Decision Infrastructure.

Where:

• Decisions are systems
• Enforcement is automatic
• Trust is verifiable

---