Metadata-Version: 2.4
Name: solv-oracle
Version: 0.1.0
Summary: ORACLE by Solv Labs, Inc. PBC — governance infrastructure for autonomous agents. Ships the offline verifier: confirm a signed ORACLE decision with only a public key.
Project-URL: Homepage, https://solvrisk.xyz
Author: Solv Labs, Inc. PBC
License: MIT
License-File: LICENSE
Keywords: agent,attestation,audit,ed25519,governance,verification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# ORACLE — Solv Labs, Inc. PBC

**Offline verification of ORACLE governance records.**

An ORACLE deployment signs a record every time it makes a governance decision
about an agent action — whether the action was allowed to proceed, or blocked
before it executed. This package lets anyone check those records independently:
with a public key, a JSON file, and no network.

This package **verifies** records. It does not produce them; signing happens
inside an ORACLE deployment.

```bash
pip install solv-oracle
# save the record from the worked example below as demo_deny.json, then:
oracle-verify demo_deny.json \
  --pubkey 525021424ccfedfd75219311841e58794b9ff0a4a0a3388203b39451634e1e02
```

```
VALID  type=deny  id=pfx_doc0000000000ex
```

That is reproducible end to end. (A `pip install` places the library and the
`oracle-verify` command, not the example files; those ship in the source
distribution under `examples/`.)

Exit codes: `0` every record verified · `1` a record was found and its
signature did not verify · `2` usage error, unreadable input, or a record too
malformed to judge.

The `1`/`2` split is deliberate. "This signature is invalid" and "this is not a
well-formed record" are different claims, and a verifier that conflates them is
telling you something it does not know.

## Why offline matters

A governance claim you can only check by asking the party who made it is not a
governance claim. These records are signed, so the check is arithmetic: recompute
the canonical form, verify the Ed25519 signature, done. No server is contacted,
no vendor is trusted, and the two modules that do it are about 200 lines you can
read in a sitting.

## Two record types

**Run Manifest** — a decision about an action that executed. The signature covers
fields 0–13: the execution and policy identifiers, the input/output/observable
hashes, the violation vector, the risk signal, the confidence, the trust stage,
and the action taken.

**PREFLIGHT_DENY** — a decision about an action that was blocked *before*
execution. There is no run to describe, so the record carries the proposed
action, the policy it was checked against, the solver verdicts that rejected it,
and the variables extracted from the proposal.

`oracle-verify` detects which one it is from the record's contents. Records are
often stored inside a larger envelope — a run log, a session ledger — so the
document is searched to a bounded depth, through arrays as well as objects.

Every record found is verified and reported with the JSON path it was found at,
and the exit code reflects the worst result. Nothing is silently selected: if a
document holds several records you see all of them, so a decoy cannot hide a
genuine record behind it.

## As a library

```python
from solv_oracle.verify import verify_manifest, verify_deny

verify_manifest(manifest_dict, pubkey)   # -> True | False
verify_deny(deny_dict, pubkey)           # -> True | False
```

Public keys are accepted as a hex string, raw 32 bytes, PEM, or an
`Ed25519PublicKey`. Both functions return `False` for a bad signature and raise
`KeyError` for a record missing a signed field — a malformed record is a
different thing from a record that fails to verify.

## What is and isn't covered

`verify_deny` performs two independent checks: that `record_hash` recomputes
from the record's own attested fields, and that the signature over it is valid.
Editing any attested field breaks the first; forging the hash to match still
fails the second.

Fields deliberately **outside** the deny preimage are `timestamp`,
`preflight_latency_ms`, `preflight_llm_result`, `preflight_ar_detail`, and
`is_synthetic` — observational metadata, excluded so that the same governance
decision hashes identically across runs. That list is exhaustive, exported as
`UNATTESTED_FIELDS`, and asserted against a shipped signed record in the test
suite so it cannot drift from the code.

A valid signature vouches for none of them. `is_synthetic` in particular is
unsigned, so **an automated consumer must not use it to tell a demonstration
record from a production one.** Only signed fields carry that weight.

And be precise about what a signature is worth at all. It establishes that the
holder of the key issued this record and that it has not been altered since. It
does not establish that a solver ran, that a policy was formally verified, or
that the recorded verdicts are true — those are the issuer's assertions, and
the signature binds the issuer to them. That is the whole of what verification
proves, and it is worth a great deal, but it is not more than that.

For Run Manifests the signature covers the decision core, **not** the extended
pricing and diagnostic fields (`multiplier`, `alpha_L`, `loss_estimate`, and
similar). Those can be edited without invalidating the signature. If your use
case depends on them, they need a separate integrity mechanism. This is stated
plainly because a verifier that implies more coverage than it has is worse than
no verifier.

Manifest-level hash fields such as `manifest_hash` are **not** recomputed by
this package.

One further limit, on the manifest format itself. The signed preimage is the
fields joined by commas, with no escaping or length prefixing. A signature
therefore pins the *concatenation*, not the field boundaries: a value that
itself contains a comma can be re-split across adjacent fields to yield a
different manifest with the same valid signature. Deny records are unaffected —
their preimage is canonical JSON, where strings are quoted and escaped. If you
consume manifests programmatically, treat adjacent trailing fields as
unpinned.

## Where the public key comes from

Use a key you obtained independently of the record — published in a document of
record, registered on-chain, or handed to you out of band. The key in the worked
example below is published here for that purpose: it is the key that signed
Solv Labs' M3 pilot governance records, and the signed evidence in the M3
submission pack verifies against this same key.

Do **not** use a public key carried inside the record you are verifying. A
record that supplies its own key proves only that it is internally consistent,
which is not the question you are asking.

## Worked example

The record below was signed by the same ORACLE key that signed Solv Labs' M3
pilot governance records. Save it as `demo_deny.json` and check it yourself
(it ships in the source distribution as `examples/demo_deny.json`):

```json
{
  "record_id": "pfx_doc0000000000ex",
  "record_type": "PREFLIGHT_DENY",
  "schema_version": "1.1",
  "timestamp": "2026-07-27T00:00:00Z",
  "preflight_policy_id": "00000000-0000-0000-0000-000000000000",
  "preflight_action_description": "Pay 500.00 USDC to an unlisted payee on Base mainnet, chain eip155:8453. [DOCUMENTATION EXAMPLE \u2014 not a production decision]",
  "preflight_result": "UNSAT",
  "preflight_check_id": "00000000-0000-0000-0000-000000000000",
  "preflight_proof_id": "",
  "preflight_latency_ms": 0,
  "preflight_z3_result": "UNSAT",
  "preflight_ar_result": "UNSAT",
  "preflight_llm_result": "UNSAT",
  "preflight_ar_detail": "action violates policy rules",
  "agent_id": "",
  "policy_version": "",
  "trust_stage": 0,
  "is_synthetic": true,
  "extracted_variables": {
    "purchaseAmountUSD": 500.0
  },
  "record_hash": "0x077e45d4240fca0126bdf8b36951c48e6cfb85c72aa68b2555adb4b5168ea180",
  "signature": "f9a5c1061c48f208de6e2be46990c69fc1dc3a5b03ac36aea3195babbcc1f97694201004bb74dd04cdcb476389e8a95aaa0e65021571431ffb7baeceab003c0e"
}
```

```bash
oracle-verify demo_deny.json \
  --pubkey 525021424ccfedfd75219311841e58794b9ff0a4a0a3388203b39451634e1e02
```

```
VALID  type=deny  id=pfx_doc0000000000ex
```

The `[DOCUMENTATION EXAMPLE]` marker sits inside `preflight_action_description`,
which is part of the signed preimage — it cannot be stripped without breaking
the signature. That is the same technique ORACLE uses to bind a planned probe to
its own record.

Read that claim narrowly. The marker is what a *human* reads, and it is
protected. The `is_synthetic` flag, which is what a *program* would read, is
not signed and can be flipped without invalidating anything. If you are
consuming these records automatically, key off the signed description, not the
flag.

Try editing any attested field — `preflight_result`, the amount in the action
description, the policy id — and run it again. It will report `INVALID`.

## Requirements

Python 3.10+. One runtime dependency: `cryptography`.

`solv-oracle` is an umbrella distribution. Capabilities live in their own
subpackages and are imported explicitly, so installing one never pulls in the
dependencies of another. `solv_oracle.verify` is the only capability in this
release.

## Tests

The test suite ships in the source distribution (`.tar.gz`), not the wheel, so a
plain `pip install` does not put it on disk. Unpack the sdist, then:

```bash
# from inside the unpacked sdist directory
pip install -e ".[dev]"    # installs this copy of the package, plus pytest
python -m pytest tests/ -q
```

`pip install "solv-oracle[dev]"` would resolve from the package index instead,
which tests whatever is published rather than the source you are holding.

The suite runs standalone — no ORACLE deployment, no network, no credentials.
To check the package against your own signed evidence, point
`SOLV_ORACLE_VERIFY_VECTORS` at a directory of
`{"pubkey": "...", "record": {...}}` JSON files.

## License

MIT. Copyright (c) 2026 Solv Labs, Inc. PBC.
