# Observability
This doc is the single entry point for the 3 high-level "what is the
state of this project right now?" commands. Each command is
informational (exits 0 even when reporting blockers), greppable, and
sourced from a single Rust file under `src/verify/`.
All 3 commands touch only the CPU reference path. They do not require
the `rocm-hip` feature; they do not modify any file; they do not
flip any of the 8 `*_claim_allowed` flags in `CLAIMS.md`.
## 1. Claim-status report (P366)
**Command**
```bash
cargo run --offline --example claim_status_report
```
**What it does**
Reads `CLAIMS.md`, parses the 8 `*_claim_allowed` flags from the
fenced `tokitai-claim-status-v1` status block, and prints a one-page
summary: each flag's current value, the P-number that introduced it
(where known), the external-evidence precondition required to flip
it, and the nearest artifact in the repo that documents the
rationale. Source: `examples/claim_status_report.rs` (calls
`tokitai_operator::verify::claim_status::*`).
**Sample output excerpt**
```
== Tokitai claim-status report (P366) ==
BY VALUE PRECONDITION
------------------------------------------------------------------------------------------------------------
P248 primary_claim_allowed=true core paper claim (C10) is supported by code+tests
P257 production_speedup_claim_allowed=false reviewed external baseline + profiler capture + ...
P270 submission_readiness_claim_allowed=false all 7 flags addressed + CITATION.cff + LICENSE + ...
summary: total=8, enabled_flags=1, blocked_flags=7
artifacts referenced:
[ok ] primary_claim_allowed -> src/verify/release_gate.rs
[ok ] production_speedup_claim_allowed -> target/paper-results/baseline-scale-comparison.csv
[MISS] full_formalization_claim_allowed -> lean/Tokitai/Ultrametric.lean (P372 skeleton only)
```
**What it greps for**
- `claim_allowed=true` and `claim_allowed=false` lines: count of each.
- `summary: total=8, enabled_flags=1, blocked_flags=7`: invariant
(must hold for the primary-claim state).
- `[ok ]` vs `[MISS]` artifact markers: surfaces evidence-chain gaps.
**Failure mode**
- `no status block in CLAIMS.md` → the `tokitai-claim-status-v1`
fenced block is missing or was corrupted. The verifier cannot
parse the claim flags.
- `unterminated status block` → the closing ``` fence is missing.
- Any `[MISS]` artifact line means the rationale doc for that flag
is absent; the claim is still blocked, but the paper reviewer
cannot see *why*.
## 2. Submission-readiness verdict (P373)
**Command**
```bash
cargo run --offline --example submission_readiness
```
**What it does**
Runs the 9 release-gate checks that are pure-software (no
external-evidence dependency) and prints a single
`submission_readiness: YES|NO` line followed by a list of blockers.
The 9 checks are: CLAIMS.md flag counts, LICENSE, CITATION.cff,
CHANGELOG.md, CONTRIBUTING.md, `target/paper-results/{json,csv}`,
`src/verify/support_matrix.rs`, `lean/Tokitai/Ultrametric.lean`, and
`tests/` directory. Source: `examples/submission_readiness.rs`.
**Sample output excerpt**
```
== Tokitai submission-readiness verdict (P373) ==
[PASS] CLAIMS.md flags are 7 false + 1 true (true=1, false=7)
[PASS] LICENSE present (LICENSE)
[PASS] CITATION.cff present (CITATION.cff)
...
[PASS] tests/ directory present (tests/)
submission_readiness: NO
blockers (claim flags + missing artifacts):
- full_formalization_claim_allowed=false (see docs/paper/final_submission_readiness.md)
- portable_rocm_claim_allowed=false (see docs/paper/final_submission_readiness.md)
- ...
summary: 9 of 9 checks passed, 1/8 claim flags are true
```
**What it greps for**
- `submission_readiness: YES|NO` → single-line verdict.
- `[PASS]` / `[FAIL]` markers: count of 9.
- The `summary: 9 of 9 checks passed` line: invariant.
- The blockers list: every line starting with `- <flag>=false` is a
claim that is still blocked; these all need external-evidence
work (P374-P380) and cannot be flipped from inside the repo.
**Failure mode**
- The example always exits 0 (informational).
- A `[FAIL]` line means a paper-hygiene artifact is missing
(LICENSE, CITATION.cff, etc.); the claim flags themselves are
not affected.
- If `submission_readiness: NO` is reported even when all 9 checks
pass, the blockers list is exclusively the 7 claim flags that
require external evidence (P374-P380).
## 3. Proof-replay witnesses section (P347/P348)
**Command**
```bash
cargo run --offline --example proof_replay_witnesses
```
P440 added this dedicated example (the witnesses section was
previously only available as a library function and as a side-effect
of `cargo run --offline --example audit_traces`). The example
prints the P347 witness-type listing and runs P348 cover-glue
inference on a small cover side-by-side so a reviewer can see the
output without grepping for it. The library entry points are still:
```rust
use tokitai_operator::verify::proof_replay_witnesses_section;
println!("{}", proof_replay_witnesses_section());
```
For cover-glue inference:
```rust
use tokitai_operator::object::sheaf::{Cover, SectionTable};
use tokitai_operator::verify::proof_replay_cover_glue_section;
let cover = Cover::new("U", ["A", "B"]);
let sections = SectionTable::<i64>::new();
println!("{}", proof_replay_cover_glue_section(&cover, §ions));
```
**What it does**
`proof_replay_witnesses_section()` returns a static listing of the
P347 witness types (`ValuationAdditivityWitness`,
`UltrametricWitness`, `PrecisionPreservationWitness`) and their
purpose. `proof_replay_cover_glue_section(cover, sections)` runs
the P348 cover-glue inference report and summarizes passed/failed
counts. Sources: `src/verify/proof_replay_witnesses.rs`,
`src/verify/cover_glue_inference.rs`.
**Sample output excerpt**
```
witnesses:
witness: kind=ValuationAdditivityWitness, purpose=observed samples of v(x*y) == v(x) + v(y)
witness: kind=UltrametricWitness, purpose=observed samples of v(x+y) >= min(v(x), v(y))
witness: kind=PrecisionPreservationWitness, purpose=observed samples of precision labels preserved
source: src/verify/witnesses.rs (P347)
cover_glue_inference:
cover_glue_inference_attempts: total=2, inferred=0, resolved=0, failed=0
cover_glue_inference_succeeded: true
source: src/verify/cover_glue_inference.rs (P348)
```
**What it greps for**
- `witnesses:` → header for the witness listing.
- `witness: kind=...` lines: one per witness type (must list 3).
- `cover_glue_inference_attempts: total=N, ...`: counts.
- `cover_glue_inference_succeeded: true|false`: pass/fail flag.
**Failure mode**
- The functions are pure and infallible; they always return
`String`. A future refactor that adds fallibility would surface
as a compile error at the call site, not at runtime.
- The cover-glue section is content-sensitive: it runs the
inference over the cover + section table you pass in, so a
*false* `cover_glue_inference_succeeded: false` means the
cover sections do not glue together — the inference layer
found a missing or overlapping section. This is not a bug in
the verifier; it is the verifier correctly reporting that
the cover is not a valid sheaf for the given sections.
## How the 3 commands compose
The 3 commands answer 3 different questions:
| `claim_status_report` (P366) | Which `*_claim_allowed` flags are enabled, and why not? |
| `submission_readiness` (P373) | Is the paper-submission package structurally complete? |
| `proof_replay_witnesses_section` (P347/P348) | What witnesses does the verifier record, and do my cover/sections glue? |
A reviewer running all 3 in sequence can answer:
"Which of the 8 claim flags are blocked, what is blocking the
paper-submission package, and is the evidence chain (witnesses +
cover-glue inference) consistent?"
None of the 3 commands modify the repo. All 3 exit 0 on the
current state; the "NO" verdict in `submission_readiness` is the
intended answer (it reflects the 7 blocked claim flags that
require external evidence, not a project defect).