aura-pce — the "I CARE" self-test gate

An operational advisor for self-hosted infrastructure — a Mastodon instance, a mail server, a family cloud — run by someone with no SRE team. It runs four falsifiable self-tests before it speaks, and refuses to speak when it cannot verify itself. This repository is the open-mechanism half of AURA's Pattern Composition Engine (PCE) — the part you can install, run, read, and check today.

Most monitors and AI copilots answer whether or not they had grounds, and their reliability is asserted by their vendors rather than measured in the open. This engine inverts that. Before emitting any advice ("this is a real anomaly", "this recovery procedure applies") it pauses and runs the I CARE suite:

1. Axiom — is this advice backed by a verified rule?
2. Type fit — do the situation's input types actually match what the rule consumes?
3. Robustness — is the recognition stable when the input is perturbed with noise?
4. Non-discrimination — does the answer survive swapping only the identities in it?

If any check cannot pass, the gate stays silent — or defers out loud ("no verified rule"). Silence and deferral are first-class outputs, not failures.

Install

pip install aura-pce            # the core: pure standard library, zero dependencies
pip install "aura-pce[live]"    # + a sentence embedder + psutil, for `watch` on your box

The core needs nothing but Python ≥ 3.10 — the provenance proof, the self-tests and the earned-metric reports all run on the standard library alone. The [live] extra adds the one thing recognition needs (a sentence embedder) plus a cross-platform telemetry reader, so aura-pce watch can gate the real state of the machine you run it on.

Quick start

aura-pce prove                 # the provenance proof: the self-tests survive their own
                               # linter, and each of the four checks has a can-fail witness
aura-pce level                 # the two earned metrics — never conflated
aura-pce selftest              # run every self-test this install can run

aura-pce prove is the honest headline: it proves the self-tests are real and prints the validity level with its n. On a fresh install that level is unproven [n=0] for the advice gate — because no advice emissions have been graded here — which is the correct, non-inflated output. There is no code path that prints an unearned number.

Point it at your box

pip install "aura-pce[live]"
aura-pce init                          # write the sample registry + demo ledger
aura-pce watch --source auto           # gate REAL local telemetry (Ctrl-C to stop)
aura-pce watch --source psutil --log   # cross-platform; log gated EMITs for grading
aura-pce watch --source node_exporter:http://localhost:9100/metrics

watch samples a telemetry source, keeps a rolling per-metric baseline, and runs every anomaly through the same gate — a calm machine stays silent, a genuine spike is recognised, type-checked, and either EMITted (gated advice), WITHHELD (recognised but not verifiable) or DEFERred (no matching axiom). Grade what it emits:

aura-pce list                          # gated emits awaiting a human grade
aura-pce grade <hash> real|noise       # dispose each one; the precision earns its n

What this is, and is not

• It is the mechanism, and the mechanism is provably honest: the self-tests pass an independent linter over themselves (a self-test that cannot fail is not a self-test), and each of the four checks ships with a demonstrated can-fail witness.
• It is not a correctness oracle. A deterministic self-test verifies diligence (the engine checked itself in four ways), not correctness (that the advice is right). Advice can pass all four checks and still be wrong on unusual data — which is exactly what outcome grading captures.
• It does not ship a reliability percentage. Reliability is earned over graded outcomes and always reported with its sample size n; at n=0 the code prints unproven, never a naked 50%.

Two metrics, kept on separate axes and never conflated:

metric	question	today, on the sample
validity LEVEL	of gated advice, how often did it hold? (outcome-blind stop-to-think)	unproven [n=0]
mesh precision	of flagged anomalies, how many were real? (human-graded outcome)	0.6 [n=3] (demo ledger)

The sample vs. the real knowledge

This repository ships a small sample registry of six sysadmin axioms and a synthetic graded ledger — enough to run every command above and watch the mechanism work. They are clearly labelled demonstration data. Each sample axiom has a runnable reference implementation in axioms/; make_sample_data.py re-proves every one by executing it (python3 axioms/<id>.py) and only then stamps verified — so the registry's "proven by run" is reproducible by anyone, not asserted. (See CHANGELOG — this replaced an earlier version that hardcoded verified: true.)

They are not the AURA knowledge base. The full deployment recognises against sovereign registries of hundreds of machine-verified rules (verified by compiler or real execution, not by opinion), and earns its reliability number on live infrastructure. That knowledge and that earned number are the project's product; they are not in this repository. What is here is the honest machinery, open for anyone to audit.

Live recognition & the embedder

Recognition matches a free-text situation to an axiom by embedding. In the full deployment a private module supplies the embedder; here embedder.py is the public reference stand-in ([live] extra), exposing exactly embed(list[str]) -> ndarray of L2-normalised vectors. It uses sentence-transformers (or chromadb) — whichever is installed. The core never imports it, so the base install stays dependency-free.

Recognition calibration

The acceptance floor is measured, not guessed. calibrate.py runs a labelled in-domain / out-of-domain probe set through the real embedder and derives a floor (and a domain-confidence margin) that separates the two, then writes calibration.json into the data home. On the shipped sample the two clouds separate cleanly (strongest out-of-domain 0.164 < weakest in-domain 0.291); the margin gate is the knob that additionally curbs over-fire on a large registry. Re-run it for your own embedder or registry:

aura-pce calibrate --report            # measure + print the before/after, don't write
aura-pce calibrate                     # + write calibration.json into the data home

See docs/CALIBRATION.md for the method and the measured numbers.

Layout

File	Role
i_care.py	the four-check gate + the earned validity level
logic_lane.py	axiom recognition over a registry of verified rules (the embedder seam)
ontology.py	the noun type system used by the type-fit check
mesh_bridge.py	renders telemetry into typed situations and gates them (gate_typed)
mesh_grade.py	logs each emission, grades it, reports precision with n
sources/	telemetry adapters: proc, psutil, node_exporter, journal
embedder.py	the reference sentence embedder for live recognition ([live])
calibrate.py	derives the recognition floor from a measured distribution
outcomes.py	the Beta earned-frequency estimator (unproven at n=0)
wisdom.py	the append-only fire log the gate writes to
assert_linter.py	classifies assertions by strength; proves the self-tests real
cli.py	the aura-pce console entry point
paths.py	resolves the one data home (env → clone ./data → user data dir)
make_sample_data.py	generates the demonstration registry + ledger

More: docs/QUICKSTART.md · docs/API.md · docs/CALIBRATION.md.

How we hold ourselves to this

The project is built on one rule: a claim must not outrun its evidence. It applies to us first.

In September 2026 we re-derived the evidence behind our own knowledge base rather than trusting it. Of the 200 system-administration rules the advisor draws on:

how the claim is actually backed	rules
an independent oracle — a cross-language twin, or a chaos/metamorphic probe	14
cross-language agreement only (a soft tier: agreement is not correctness)	54
a green run only — the pattern's own self-test passes, and nothing independent	132

The previous registry called all 200 verified. It was not lying: each one really does pass its own self-test, and we re-ran every one of them to confirm it — 200/200 exit 0, plus a runtime evidence card on each (success, adversary, fuzz) — 200/200 VERIFIED. But a green run is not the same as being right, and 132 of them had nothing beyond it.

So we demoted those 132: is_axiom: false, basis: "green-run-candidate" — and we kept the old claim beside the new one (prior_is_axiom: true) rather than deleting it, because a correction should be readable as a correction.

Three things followed, and they are why this is in the README rather than in a changelog:

1. Nothing unverified is called verified anywhere now. Every rule carries its basis, the oracle kinds behind it, and the exit code of the run behind it. A rule that has only a green run says so — and the advisor still emits on it, labelled green-run-candidate and advisory, because silencing advice that carries a real constraint is the other failure mode, not a safer one.
2. The number went the wrong way, and we published it anyway. 200 verified became 68 backed and 132 candidates. A registry number that only ever rises is marketing; this one fell because the question changed from "does it run?" to "is it right?"
3. The measurement itself got sharper. Every emission now records what its advice stood on, so reliability is reported per tier with its own n — oracle-backed advice and green-run-only advice are different claims and are no longer blended into one figure.

What is public here, and what is not

Being precise matters more than sounding good:

• Public in this repository: the mechanism — the self-test gate, the refusals, the sample registry proven by real execution, and the tool that polices our claims (pip install whypass).
• Not public: the knowledge base itself. The 200 rules, their evidence records, and the pass that graded them are ours, and that is the part we sell.

So the sentence above is deliberately "we demoted 132 of our own rules, and here is the count" — checkable against what we publish — rather than "the code that did it is in this repository", which would have been false on the day it was written. A README that overstates by one clause is the defect this project exists to catch.

About

aura-pce is the public half of AURA's Pattern Composition Engine (PCE) — the engine whose job is to compose a decision out of a recognised operational pattern, a verified rule and a type fit, and to refuse to speak when it cannot. That refusal is the part that makes the rest trustworthy, so it is the part that ships first.

What is in this repository today is the half that makes refusal possible: the four-question I CARE self-test gate, the type ontology the rules are written against, a hand-written sample rule registry proven by real execution, and the sysadmin telemetry bridge. The composition half — the decomposer, the store, the pattern extractor and the composer itself — is in progress and will be published here as it lands, mechanism only, with the same discipline: a green run says what it is, and nothing is called verified that has not been independently checked.

Part of AURA, a research program in self-testing infrastructure by Reality Optimizer — realityoptimizer.app. Sibling open tools: folder-nature (semantic identity + signing for file trees), whypass (a claim-discipline linter), copresence.

AURA is developed by a small human–AI working group; AI collaborators are named contributors in its repositories, and every claim in its documentation is written to be checkable rather than believed.

License

Apache-2.0 from the first release. See LICENSE.