Skip to content
The CNA BibleCNA 0.1.0-alpha.1 Edition

Appendix G Verification Tiers and Oracles

This appendix is a claim-decoding key for the rest of the book. It does not rank every test on one line from weak to strong: a compile probe, a hostile-input test, a pixel comparison, and a native-host run answer different questions. The useful record is therefore an evidence vector that names the subject, execution environment, observation point, oracle, result, and retained artifact. Chapters 6873 explain the machinery; the tables below make its vocabulary quick to apply.

G.1 Canonical claim labels

The edition uses a small set of labels consistently. They describe what was established; they are not interchangeable synonyms for “supported.”

Label Minimum evidence
Source-proven A pinned implementation, fallback, refusal, or absence was inspected along a reachable source route.
Compile-proven The named declarations, includes, templates, and link closure compiled in the recorded configuration.
Runtime-observed The named path executed and yielded the recorded state, value, file, trace, or lifecycle event.
Renderer-engaged The intended renderer family and native or translation API were identified during execution.
Oracle-compared An observation was compared with an identified authority under a stated policy.
Pixel-verified Selected pixels or a complete frame were compared at a named readback boundary, renderer, host, and tolerance.
Manually observed A human inspected the output without a retained discriminating oracle.
Historically recorded A dated artifact reports the result, but this edition did not rerun it.
Blocked A named external precondition prevented the attempted route from reaching its subject.
Unsupported The pinned implementation has an explicit refusal, absent factory, or documented lack of the named path.
Not attempted No execution claim is made. Source or compile evidence may still exist.

G.2 Evidence forms are not interchangeable

Evidence form What a green result establishes What it does not establish
Header or compile probe Names, signatures, templates, includes, and link closure are usable in the selected build. Runtime semantics, resource creation, rendering, or host engagement.
Strict-XNA positive probe Code restricted to the intended XNA surface compiles with CNA_STRICT_XNA_API. That the negative guard catches a leaked extension.
Strict-XNA negative probe A deliberate CNAEXT call fails compilation, proving the guard itself is sensitive. Coverage of every unmarked or incorrectly classified declaration.
Pure deterministic test A value, state transition, parser result, or exception matches its asserted oracle on that host. Renderer, window system, driver, or external runtime engagement.
Hostile-input test A named malformed boundary rejects, contains, or reports the input as asserted. Correct behavior for valid data or completeness of the malformed corpus.
Trace / HEADLESS test Routing, validation, counters, or state order reached the trace implementation. Rasterization, GPU work, visible pixels, or real occlusion samples.
Source-path audit At the pinned revision, a reachable implementation, refusal, fallback, or parameter loss is visible in source. Successful compilation or execution on a required host.
Readback / small-pixel test The exercised renderer produced the asserted value at the selected readback boundary. Whole-scene fidelity, a different renderer, or a path bypassed by readback.
Golden-image comparison A complete captured frame matches a retained reference under the recorded tolerance and environment. That the reference itself is authoritative or portable.
Differential run CNA agrees with a named independent implementation or real XNA for the exercised inputs and observation. General parity beyond that corpus; two implementations can share a defect.
Native-host artifact The requested executable, API/runtime, device or browser, and observation point all engaged on the named host. Other hosts, other identities, or long-duration behavior.
CI workflow success The workflow trigger reached every recorded step and its gates passed for that matrix leg. Jobs excluded by filters, dispatch-only workflows, dead configure legs, or tests never registered in that configuration.

“Test exists”, “test was registered”, “test ran”, and “oracle discriminated” are four separate statements. A skipped test is not a pass, a dry-run mutation is not a killed mutation, and an uploaded log is useful only when it identifies the binary, configuration, host, and observation that produced it.

G.3 Oracle authority depends on the question

For API shape, CNA’s policy names Microsoft XNA reference assemblies/XML as the target surface; xna4-spec is a searchable converted documentation corpus, not a live CNA gate and not an infallible substitute for the original assembly. For behavior, CNA’s checklist names FNA as the ordinary reference, while real XNA, a format specification, or a renderer API can outrank it for a narrower question. A project-authored expected value is an oracle only when its derivation is reviewable and independent of the code under test.

Question Preferred authority and control
Public API shape XNA reference assembly/documentation; normalize C#–C++ idioms explicitly, then compile positive and negative probes.
Managed behavior Real XNA where executable; otherwise pinned FNA plus independently chosen edge cases and documented intentional deviations.
File-format semantics The owning specification and independently generated fixtures; compare production output with a separate decoder or digest where practical.
GPU/API behavior The native API contract plus renderer-owned execution evidence; use another renderer only as a localization control, not as the sole truth source.
Project extension A written CNA contract, negative cases, and a discriminating test; XNA/FNA cannot define semantics for a CNA-only feature.
Historical reconstruction Original executable/source/data and versioned captures; decompiled code is evidence to audit, not automatically a behavioral specification.

G.4 Renderer and platform claims need a complete vector

A useful renderer result records all of the following fields. Omitting one often changes the meaning of the claim.

Field Record
Source identity CNA SHA, sibling SHAs, local-diff status, and generated shader/table revision.
Build identity Public renderer selector, implementation family/profile, build type, toolchain, feature options, and exact configure/build command.
Host identity OS/architecture, native API or translation runtime, device/driver, display mode, browser/emulator/physical-hardware identity, and relevant environment variables.
Subject Exact test, demo, asset, API operation, malformed case, or renderer route.
Engagement proof A log, marker, API/device identity, browser verdict, screenshot, readback, or lifecycle trace proving the intended path rather than a substitute path ran.
Oracle Expected value/image/exception and its authority; tolerance and normalization rules.
Outcome Pass, fail, expected fail, skip, unsupported, blocked, or not attempted—never one overloaded “supported” bit.
Artifact Retained log, image, trace, manifest, digest, or CI record with a reproducible locator.

This vector distinguishes, for example, a MinGW binary running through Wine and DXVK from a native MSVC/Direct3D run; a browser page loaded from an HTTP server from one opened as a local file; an Android APK that installs and presents a frame from its selected renderer; and an iOS source path from an actual signed device build. Those are all useful milestones, but they are not synonyms.

G.5 Automation at the pinned revision

The tag contains 21 workflow files: 19 react to push or pull-request events, usually under path filters, and the Direct3D/GDI routes are dispatch-only. New source-level gates cover compatible native and Emscripten multi-renderer sets, platform/audio tuples, glTF, TinyGL, NanoVG, Apple and five C API records. The records do not build the final C library; a local exact-tag build reaches the adapter’s 49-versus-50 renderer-identity invariant and stops. Three automatic general/Input legs still stop during configuration because they pass the retired family token EASYGL instead of a public selector. Sanitizer, mutation, fuzz-named, and validation mechanisms exist, but their mere presence does not prove a tag workflow ran or enlarge the set of engaged routes. Chapter 73 is the dated path-by-path account.

The safe summary at this pin is therefore neither “CI absent” nor “CI complete”. Automatic browser harnesses, a Devices UBSan route, platform-specific jobs, and several narrow gates are declared; dead configure legs, dispatch-only Windows coverage, no code-coverage measurement, no continuous coverage-guided fuzzer, and a Direct2D mutation dry-run remain real too.

G.6 A minimum claim recipe

Before writing “works”, write a narrower sentence that answers six questions:

  1. 1.

    What exact subject and revision were examined?

  2. 2.

    Which build, renderer, platform, and host actually engaged?

  3. 3.

    Where was behavior observed—return value, trace, readback, frame, file, or peer?

  4. 4.

    What independent authority supplied the expected result?

  5. 5.

    Which negative or perturbed case proves the check can fail?

  6. 6.

    What artifact lets the next auditor reproduce or falsify the claim?

A claim that cannot yet answer all six can still be useful. Label it source-proven, compile-proven, runtime-observed, renderer-engaged, oracle-compared, pixel-verified, manually observed, historically recorded, blocked, unsupported, or not attempted. Do not silently promote one state to behavioral parity.

Type at least three characters. Results are ranked by how often and where the words occur.