Docs / Record features

Recording which onedoor decision allowed an action

A step that takes an action can record which onedoor decision allowed it, and the record proves it: anyone can check, with no network calls, that the decision exists unaltered, that it permitted this step, and, where a bound permit was used, that the permit covered exactly the action the step recorded. onetrace never imports onedoor — the small, stable pieces it needs are vendored as standard-library code (onetrace.onedoor_ref) and tested against onedoor's own published vectors.

Declaring the gated steps

A run declares which of its steps must be gated:

@ot.run(stages=["approve_payment"], gated_stages=["approve_payment"])
def main():
    ...

Recorder(..., gated_stages=[...]) does the same. Each gated stage must be a declared stage. The declaration is written into the run's manifest. A gated step that records no decision is a finding the verifier names, not a silence. A step not declared gated may still cite a decision.

Recording the decision inside the step

Inside a decorated step, after onedoor answers and before the action:

ot.decision(ref, permit=None, action=None)

These go in the receipt's optional authorization block. A run that records no decision writes receipts byte-identical to 0.4.0.

What onetrace-verify checks

Five rows, each PASS, FAIL or NOT-RUN, never guessed. They appear only when a run declares gated stages or cites a decision; a run verified without any is read exactly as before.

row PASS FAIL NOT-RUN
gated steps cite a decision every declared gated step cited one a gated step cited none no gated_stages declared
references are well formed each is onedoor-decision-ref/1 one is malformed no references
a step that acted cites a permitting decision its last reference's verdict is permit it acted on a deny or propose no references on an acting step
the permit covers the recorded action the signature is valid for an issuer in --permit-issuers, the action digest equals the step's recorded action, and the step ran within the permit's lifetime any of these fails no permit recorded, or no issuer key given
the decision is in the export --decisions <export.jsonl> (with its .sha256 sidecar) given, and every reference matches a row by digest a digest mismatch, not in the export, or the export is damaged no export given

The last row reuses onedoor's own five outcomes. With no export and no permit, the record can still show that a gated step cited a permitting decision; the rows that need more read NOT-RUN, so nothing reads as checked that was not.

onetrace-verify --decisions decisions.jsonl --permit-issuers issuers.json runs/<run_id>

The permit issuer's Ed25519 public key is read from --permit-issuers, an onedoor-issuer-trust/1 file, separate from the run-signing --trust file: the permit issuer is a different trust domain from the run's signer, and the onetrace-trust/0.1 file carries key fingerprints, not public keys. The run-signing --trust file is never read for an issuer, and an issuer key is never read from the run. The file names each issuer and its 64-hex Ed25519 public key:

{
  "format": "onedoor-issuer-trust/1",
  "issuers": [
    {"issuer": "https://onedoor.example/payments-issuer",
     "alg": "ed25519",
     "public_key": "03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc866412553..."}
  ]
}

When --decisions is given without --permit-issuers, the permit row reads NOT-RUN, naming the missing --permit-issuers file, so a permit is never read as checked when its issuer key is absent.

What this does not claim