# oracle7-deepspace

A self-maintaining, low-compute autonomy core for fault response on deep-space spacecraft, built from Oracle7
(warrant-first reasoning, honest abstention, a self-improvement gate) and oracle7-trafficcop (precondition-checked
decisions with receipts). Python standard library only, about 1,100 lines, no learned weights, no GPU.

- Paper: `paper/oracle7-deepspace.pdf` (source `paper/main.tex`, arXiv bundle `paper/arxiv-source.tar.gz`)
- Live simulation of Voyager 1, New Horizons, Juno and Europa Clipper: https://prometheus7.com/DeepSpace7/ (evidence page `/DeepSpace7/evidence`)
- Code version for every number below: SHA-256 of `deepspace/*.py`
  `b936ec011372fd9860c748b39b5117c7b8b1296f85d169ccfc8a9b6f8e394408` (recipe: `eval/eval_final.py:code_sha256`)

## What it does

| Layer | Module | Behaviour |
|---|---|---|
| Spacecraft + digital twin | `deepspace/sim.py` | four mission profiles (RTG + thrusters; solar + thrusters; solar + reaction wheels): power, thermal (3 zones, primary/backup heaters, A/B sensors), attitude; 10 fault classes incl. two traps (biased sensor, single-tick radiation upset) |
| Fault response | `deepspace/fdir.py` | telemetry -> confirmed facts (persistence) -> fault hypotheses -> admissible responses (preconditions) -> admitted rule OR worst-case lookahead on a twin built from telemetry only; a receipt per decision; decisions to wait expire |
| Self-maintenance | `deepspace/selfmaint.py` | proposes "fact signature -> response" rules only from its own verified episodes; admits a rule only if the validation suite loses no correct response, adds no harmful one and costs less compute; versioned, rollback, ground veto |
| Self-report | `deepspace/report.py` | answers operator questions from telemetry frames and receipts, with citations; declines anything without a record |

## Results (final code)

Single faults, fresh held-out seeds 5000-5049 (1,700 scenarios, 95% Wilson intervals):

| System | Correct | Harmful | Safe modes | Damage |
|---|---|---|---|---|
| oracle7-deepspace | 98.9% [98.3, 99.3] | 0 | 100 | 0 |
| + rules it learned itself | 100.0% [99.8, 100] | 0 | 100 | 0 |
| expert fault table (upper bound) | 100.0% [99.8, 100] | 0 | 100 | 0 |
| simplified limit -> safe mode baseline | 29.4% [27.3, 31.6] | 200 | 1,300 | 218 |
| random admissible response | 43.5% | 117 | 403 | 133 |
| no action | 23.5% | 0 | 0 | 163 |

The safe-mode baseline enters safe mode on any confirmed fact and has no fault-specific responses. It is not a model
of real flight fault protection (which pairs fault-specific responses with safe mode as a fallback); it measures what
safe mode alone achieves. The expert table is the fairer comparator.

- Compound faults (two faults 30 min apart, 240 fresh cases): 99.2% both remedied, 0 harmful; expert 100%; baseline 0% (102 damage).
- Self-maintenance gate: 9 rules admitted (suite 101/102 -> 102/102, twin simulations 406 -> 0); 4/4 planted wrong rules rejected.
- Twin constant mismatch 0 -> +-30%: 99.3% -> 98.1%, no harmful action. Persistence 1 tick: 80 harmful; 2+ ticks: none.
- Self-report: 14/14 (fakes: echo 0, canned "all nominal" 0, always-decline 4).
- Compute: 0.22-0.43 ms per 60 s tick, worst decision 11-31 ms, 106-109 KiB; an earlier build made the same decisions capped at 5% of one core / 64 MB.

Structural mismatch and out-of-range faults (seeds 7000-7049, flight code unchanged; `eval/truth.py` defines physics the twin
does not model). Strict = designed response; outcome = craft unharmed:

| Condition | oracle7 strict / outcome | expert strict / outcome | safe-mode baseline strict / outcome |
|---|---|---|---|
| base physics | 99.0 / 100.0 | 100.0 / 100.0 | 29.4 / 68.2 |
| all mismatch terms + 2% telemetry dropout | 93.3 / 97.7 | 94.7 / 98.0 | 29.2 / 72.3 |
| weak faults, base / all terms | 83.1 / 100.0, 93.4 / 98.7 | 100.0 / 100.0, 99.7 / 98.7 | 14.3 / 71.4 |
| strong faults, base / all terms | 85.7 / 100.0, 81.7 / 88.7 | 100.0 / 100.0, 100.0 / 84.7 | 14.3 / 71.4 |

Beyond what it was built on (seeds 8000-8049, flight code unchanged; `eval/eval_generalization.py`):

- **Spacecraft added after the freeze** (`eval/new_craft.py`): Voyager 2, OSIRIS-APEX, MRO - 1,300/1,300 correct, 0 harmful,
  rules learned on the original four transfer without loss. Parker Solar Probe (hot environment) - 67.1%, 198 harmful, 0 damage,
  identical to the expert table: the facts layer reads passive heating as a stuck heater.
- **Faults with no hypothesis** (`eval/novel.py`, 400 runs each, all eight craft): weakened heater, flickering star tracker and slow
  source decay handled without harm; a frozen temperature sensor is never recognised (damage in 45/400) and a load-current sensor
  reading 3.2 A high causes a false safe mode every time. The expert table behaves identically: the gaps are in the facts layer.
- **Determinism:** 690/690 recorded missions replay to identical receipts; three processes with different hash seeds agree.
- **Endurance:** 8 craft x 60 simulated days: 52/53 faults remedied, 0 harmful, 0 damage; tick time flat (~0.2 ms), worst 27 ms;
  flight-code memory grows only with the receipt log (<= 140 KiB).

Real telemetry (NASA SMAP/MSL, pre-registered): the simple detection front end is not competitive with the published
LSTM (event-level F0.5 0.42 vs 0.71). The decision, self-maintenance and explanation layers can consume facts from any
validated detector.

## Reproduce

```
python3 eval/eval_fresh.py        # single + compound faults      -> results/fresh_eval.json
python3 eval/eval_final.py        # gate, ablations, self-report, compute -> results/final_supporting.json
python3 eval/eval_structural.py   # structural mismatch, out-of-range     -> results/structural_eval.json
python3 eval/eval_generalization.py  # new craft, unknown faults, replay, soak -> results/generalization_eval.json
python3 eval/eval_smap_msl.py     # real SMAP/MSL telemetry (data in data/smap_msl) -> results/smap_msl_eval.json
python3 eval/eval_paper.py        # the pre-registered first held-out run (pre-fix code) -> results/paper_eval.json
```

## Test it yourself

`eval/run_scenarios.py` flies scenarios someone else wrote, as a JSON file (craft, physics variant, faults with onset,
target and optional strength beyond the design range), against the frozen flight code and both baselines, and stamps the
report with the SHA-256 of the scenario file and the code. See `eval/example_scenarios.json`.

```
python3 eval/run_scenarios.py eval/example_scenarios.json --baselines --out report.json
```

## Honest limits

- The spacecraft models are simplified physics written for this work; the profiles decide which subsystems and faults
  exist, not engineering fidelity. Structural mismatch was tested only with the terms in `eval/truth.py`.
- Every scenario so far was written by the author; the harness above exists so that an independent evaluator can change that.
- The facts layer has identified gaps: a healthy but under-powered heater looks like a failed one; it assumes a cold spacecraft
  (Parker Solar Probe); it cannot recognise a frozen sensor; it trusts current sensors; and a handled fact is not re-armed if
  the ground reverses the response.
- Two fixes were made after the first held-out run (handled-by-own-response; expiring waits). Its pre-registered results
  (96.5% single, 92.5% compound) are kept in `results/paper_eval.json`; every other number comes from the final code.
- Not yet run on flight-like hardware, inside F Prime, or ported to C.