ORPI Decision Vault

A reference implementation of the Operational Decision Standard (ODS) Core v2.0.0.

The vault records decisions so that they cannot be quietly rewritten, so that operational decisions carry the alternative they were weighed against, and so that the entire history can be verified by anyone. It is a small, faithful implementation of the standard published at github.com/ODS-Foundation/ods-specification, and records written by it validate against the standard's own JSON Schema using the standard's own validator.

Why this exists

ODS describes what a conformant decision record must be. A reference implementation shows that such a system can be built, and what it looks like in practice. If you are implementing ODS, this is a worked example you can read, run, and check your own work against.

Provenance

ODS was not designed in the abstract and then implemented. The implementation came first: the ORPI Decision Vault operated under three governing laws, and the standard was distilled from them afterward. This repository is the public, domain-neutral form of that original vault — the trading and strategy logic of the private system has been removed, and the records have been reconciled to the published ODS Core v2.0.0. The doctrinal core, the three laws, is preserved.

Two kinds of decision

• Governance-only — a record of a governance event with no operational action (for example, a policy attestation). No action section, no profile, and no counterfactual is required.
• Operational — a decision that takes an action. The action section requires a profile (ODS rule E4), and at least one counterfactual is required (Decision Vault Law I: no decision without a shadow).

What's here

ods_vault/
  decision_record.py   build a v2.0.0 DECISION record; canonical hashing; schema validation
  write_gate.py        the append-only gate: schema + temporal integrity + hash chain + write-once
  verify_integrity.py  verify the whole ledger (schema, order, tamper, chain continuity)
  outcome_record.py    OUTCOME records linked by parent_id (the decision is never mutated)
  audit.py             reconstruct a decision with its shadows, trail, and outcomes
schema/
  ods_record_v2.json   the published ODS Core v2 schema (verbatim copy from the spec)
examples/
  decision_neutral.json   a governance-only decision
  decision_finance.json   an operational decision (Core v2.0.0 + ODS-Finance/v1 profile)
  outcome_finance.json    an OUTCOME linked to the finance decision
tests/
  test_vault.py        end-to-end tests, including tamper detection
THREE_LAWS.md          the doctrine the standard was distilled from

Quick start

pip install jsonschema
python tests/test_vault.py

import hashlib
from ods_vault import build_decision, write_decision, verify_integrity

policy_hash = hashlib.sha256(b"my-policy-v1").hexdigest()

record = build_decision(
    model_version="v1.0.0",
    policy_hash=policy_hash,
    action_type="approve_request",
    profile="ODS-Governance/v1",
    confidence=0.78,
    rationale="Approved because the expected value exceeds the strongest alternative.",
    counterfactuals=[
        {"alternative_action": "deny_request", "expected_outcome": 0.45},
    ],
)

write_decision(record, vault_dir="./vault")   # validated, chained, written once
verify_integrity("./vault")                    # -> (verified_count, total_count)

Outcomes and immutability

Writing a result back into a decision record would edit an immutable record and violate Law II. So outcomes are recorded as separate OUTCOME records linked by parent_id; the decision record is never touched. An OUTCOME carries outcome_status (PARTIAL or FINAL) and a structured outcomes object (actual_result, realized_at, delta_from_expected). The audit view joins a decision to its outcomes at read time. See outcome_record.py.

Conformance

Records are validated against schema/ods_record_v2.json, a verbatim copy of the schema in the specification repository, using the same check the official validator performs. The implementation adds two integrity fields — record_hash and ledger_prev_hash — which the schema permits as additional properties.

License

Apache License 2.0. See LICENSE.