Developer validation tiers

tests/run.sh is the repository-level validation owner. The production gododin test command dispatches its quick and locked tiers here after resolving the required compiler explicitly; the shell entrypoint remains useful for focused developer invocation. Neither path finds Odin on PATH.

The implementation plan's C1–C5 checkpoints own when broad validation runs during active development. Use focused checks while implementing coherent changes, then batch SDK, native/editor/render/export, and benchmark evidence. Do not invoke overlapping tiers or repeat successful checks for unchanged artifacts. This document describes each tier's coverage; it does not require a complete run after every edit.

Checkout contributor entry

Consumer installation belongs in the usage guide. A checkout is the authority for repository tools, fixtures and validation; it is not required in an installed project's ancestry.

Copy .gododin/local.example.toml (repository: .gododin/local.example.toml) into the checkout's ignored .gododin/local.toml, fill canonical absolute paths and select exactly one first-CLI mode. For external Odin, build the initial CLI with the lock's version-matched compiler:

/absolute/exact/Odin/odin build /absolute/gododin/cmd/gododin \
  -vet -strict-style -warnings-as-errors \
  -out:/absolute/private/bin/gododin

For prebuilt entry, authenticate and extract the first-CLI archive named by gododin.lock into the configured cache. Both modes immediately hand off to toolchain ensure; neither finds a compiler on PATH or falls back to the other mode. A checkout-authority consumer names the checkout explicitly:

/absolute/authenticated/gododin init \
  --project-root /absolute/gododin/projects/my_subsystem \
  --authority-root /absolute/gododin --project-key my_subsystem

Its committed authority_root is relative; installed projects instead use an ignored SDK link. For routine validation use the version-matched local compiler explicitly:

tests/run.sh quick --odin /absolute/path/to/Odin/odin

The quick tier records development evidence and never promotes support. Installed projects refuse repository quick/locked, fixed qualification fixtures and authority update. Application tests use public run.

Evaluation frame pacing

Godot evaluations and benchmarks run with engine VSync disabled and no maximum FPS cap by default. Launch game evals with --disable-vsync --max-fps 0 before the user-argument separator. Directly launchable eval scenes also set and report the runtime values before measuring, and fail if the requested engine state is not established. A headless run reports VSync as not applicable; its dummy display server does not establish rendering throughput.

This rule applies to performance and visual evaluation games, not ordinary interactive play or editor use. A test specifically evaluating synchronized presentation must name that exception and its workload. Pure Odin and shim benchmarks have no display pacing. Engine-reported VSync off does not prove that the graphics driver or window compositor adds no presentation waits.

Retain earlier paced receipts unchanged. New uncapped measurements must record the pacing mode, build profile, renderer, workload and frame statistics separately; do not present earlier VSync-limited frame numbers as uncapped throughput.

Tier coverage

Every active tier uses the sole exact engine selected by gododin.lock (repository: gododin.lock) and the active-target record. Generation uses that target alone; retained receipts do not qualify a newer pin. Nothing here validates, generates, or projects against exact 4.7.2 or exact 4.6.2. Both are frozen history whose vendored corpora receive digest verification and nothing more; do not add a tier, case, harness, or projection that runs either.

The default quick tier uses an explicitly configured local Odin executable. It requires the locked version, records the executable hash and root, parses the portable and local TOML inputs, syntax-checks repository shell scripts, runs a small strict Odin compile/execute test, runs the focused engine-model cases, and normalizes only the complete selected Godot input corpus. The routine model check resolves every emitted source pointer, verifies exact category/member counts, and pins the canonical model digest while keeping that normalized model transient. The complete raw publication check projects that selected corpus once, reproduces the exact-target raw source and coverage twice from the same model, strictly compiles the staged package, and rejects any drift from bindings/raw or its generation receipt. The superseded partial raw vertical-slice generation is not repeated. The tier also validates the reviewed typed policy against only the selected target's API records, checks the locked publication hashes and derived direct-call classifications, compiles the checked-in typed plan/facade, and runs a fake-engine behavior test across all 11 operations, ownership commits, capability rejection, dynamic Variant cleanup, and final Ref destruction. Candidate-target regeneration and cross-version diffing do not exist any more: the projection has one target. They return only if a post-1.0 decision names a specific exact version and reinstates the comparison. The quick tier also runs four production command-authority tests, the 22-test shared/external/prebuilt first-CLI matrix, the six documentation-source tests, the six transactional update tests, four documentation-projection tests, selected-target exact-source verification, integrity of the frozen historical documentation snapshot, independent GDI regeneration, and ADR 0040's deterministic C/Odin ABI runner. Phase 2 adds the serialized 21-case strict Host unit suite (its stable trampoline router is intentionally process-global) and authenticated passive-image matrix to this tier. The completed Phase 3 gate strictly compiles the selected generated catalog projection, runs the catalog contract, projection, continuity, and project-input tests, the four pure-weather tests, validates the historical native evidence receipt, and syntax-checks the frozen two-target harness contract without launching Godot. Under the runner's additive convention this reports 24 Phase 3 cases in quick; locked adds one catalog drift check and eight catalog negative cases for 33. Phase 4 adds the 22-case standalone build-owner/protocol matrix to both active tiers. It uses a controlled six-stage child process to prove exact config/lock target/profile binding, relocation-stable source/build identities, six stage-failure cleanups, stale-source rejection, same-build concurrent coalescing, newer-build supersession, inherited-lock interruption recovery, orphaned-admission recovery, sealed no-replace publication, and separate current- accepted/last-known-good metadata without invoking a real project compiler or promoting support. The locked tier additionally retains the 22-case generalized target-neutral project generation matrix. These routine checks do not substitute for rerunning the exact live matrix. The tier then builds the production CLI, extracts and invokes the sealed prebuilt twice under hostile inherited state, and runs the public current-lock update --check path. It also runs three public gododin init cases: one initialization into a temporary root under the repository, which must copy the authority lock byte for byte; a build-state call on the result, whose unpublished-state failure is what proves the production project reader accepted the written configuration and lock; and a second initialization on the same root, which must refuse rather than replace. The locked tier adds two cases on that same project: its first public debug build must publish an accepted artifact, and build-state must expose that exact-target publication. It then publishes persistent generated output, verifies it, injects drift and requires check to refuse it without mutation, and repairs it through generate. It then holds the build owner lock the way an admitted build does and requires clean to refuse with CLEAN_BUILD_IN_FLIGHT without removing anything. With the lock released, clean removes generated and build state while preserving the managed toolchain, and the project rebuilds from a clean persistent state. The initializer's own strict-validation, rollback, and refusal matrix is in the cmd/gododin package tests. The CLI build check is host-relative (ADR 0065). The darwin recording host requires an arm64 Mach-O with a macOS 13.0 floor, a valid ad-hoc signature, and only /usr/lib/libSystem.B.dylib as a dynamic dependency; a Linux host requires an ELF64 x86-64 dynamic executable whose dynamic dependencies stay inside the recorded libc closure. Cases whose recorded evidence is a darwin binary — executing the sealed prebuilt, the managed-compiler behavior probe, the Mach-O passive-image and ABI fixtures, and the external-Odin live authority — run on a darwin host and print explicit skip sentinels on other hosts until those platforms record their own artifacts:

tests/run.sh
tests/run.sh quick --odin /absolute/path/to/Odin/odin

The matching public entrypoints are:

/absolute/path/to/gododin test quick --project-root /absolute/gododin/checkout
/absolute/path/to/gododin test locked --project-root /absolute/gododin/checkout
/absolute/path/to/gododin test native --project-root /absolute/gododin/checkout
/absolute/path/to/gododin test render --project-root /absolute/gododin/checkout/fixtures/compositor
/absolute/path/to/gododin test export --project-root /absolute/gododin/checkout/fixtures/compositor

The recording-host preflight and the clean-machine promotion sequence that use these entrypoints are owned by docs/releasing.md.

Installed projects deliberately refuse these repository and fixed-fixture test tiers. Phase 6 instead owns one packed unrelated-consumer gate:

tools/release/test_installed_sdk.sh \
  --project-root /absolute/gododin \
  --odin /absolute/exact/Odin/odin \
  --godot /absolute/exact/locked-Godot \
  --release <release-identity>

It packs the SDK twice byte-identically, authenticates every extracted member, initializes and builds outside checkout ancestry, exercises its negative substitution cases, relocates the SDK, attaches it without changing committed project files, and rebuilds. Its exact pass sentinel is owned by the Phase 6 exit criteria in docs/implementation-plan.md.

Phase 7 keeps the flagship example's heavier evidence separate from that minimal consumer gate:

examples/cavern_lab/test.sh \
  --sdk /absolute/extracted/sdk \
  --odin /absolute/exact/Odin/odin \
  --godot /absolute/exact/locked-Godot \
  --evidence-dir /absolute/new-cavern-evidence

That harness owns the exact installed debug verification and visual processes, the release benchmark, byte equality, separate generation/presentation timing, and zero-owner shutdown. Its current frozen qualification runs in both normal repository tiers without rerunning the live benchmark. The contract requires matching lock, catalog, authored/generated inputs and toolchain facts, and verifies the retained execution trace. The current installed-SDK receipt also requires cold editor startup without preparatory import and both exports without native image launcher variables. Missing, corrupt or stale evidence is a failure; the former engine-gated skip has been removed.

Both active tiers also run the native-components reload worker's package cases:

• pending promotion, with the displaced record released;
• active cancellation, with the token reset for the next request;
• a cancel admitted before pickup.

They also require the worker template used by the reload and restart harnesses to equal that tested package apart from its revision marker, so a worker fix cannot land in only one copy.

quick uses the authenticated sealed managed compiler. locked uses testing.locked_odin_executable from the authority checkout's ignored local configuration because its external-Odin behavior probe requires an owner-writable exact compiler root; pointing it at .gododin/tools is rejected. native runs the configured native-basic project through the production run gate. render runs the configured compositor under Forward+/Metal, while export drives the complete recovery-editor, accepted-editor, run, debug/release export, and exported-application matrix in disposable local evidence. The latter two are restricted to the authority checkout's configured compositor fixture.

The completed Phase 4 tiers also run seven checksum-addressed candidate- input cache cases: strict authority validation, fresh immutable fill and reuse, producer failure, wrong bytes, symlink rejection, corrupt-cache non-repair, and missing-producer cleanup, plus concurrent exact-winner revalidation. These prove only byte acquisition/cache ownership. They do not prove an Odin archive, source build, compiler identity, or managed toolchain publication by themselves. The separate managed-Odin adapter and public prebuilt integration validate the locked archive/member/root manifests, compiler/runtime hashes and behavior, immutable publication, and exact handoff before reporting toolchain readiness. The minimal behavior probe is intentionally compiled with one Odin worker: it is an identity check rather than a throughput workload, and the exact locked compiler can deadlock while joining idle workers after repeated sanitized checks.

Phase 5 adds the rendering, typed-surface, semantic-signature, and bulk-transfer cases to both active tiers: the render facade's ownership contracts, the compositor subsystem and its offline harness contract, the typedgen cases, the typed-surface demand and live receipt contracts, matching and mismatched Signal/Callable compiler cases, the pure density producer, the staging owner's compensating-control cases, the density-field-upload measurement, the typed-versus-raw render-cost measurement, the particle staging fixture's producer, compose, and counter cases, the order staging fixture's producer, choreography, and counter cases, the debug draw fixture's helper and scenario cases, and the configured-project authority check. Each measurement reruns its workload rather than reconstructing its figures. The bulk tier remeasures against the instrumented engine and requires fixtures/bulk_transfer/bulk-transfer-evidence.json to reproduce byte for byte, with the receipt's digest carried in the pinned pass sentinel. The render-cost tier likewise requires fixtures/render_cost/typed-raw-cost-evidence.json to reproduce byte for byte. The particle staging tier likewise reruns the three transports at three populations and requires fixtures/particle_staging/particle-staging-evidence.json to reproduce byte for byte; that fixture is not a gate pass, and the pin guards drift only. The order staging tier likewise reruns the draw-order-application workload and requires fixtures/order_staging/order-staging-evidence.json to reproduce byte for byte; the same boundary applies. The debug draw tier likewise reruns the debug-batch-frame scenario and requires fixtures/debug_draw/debug-draw-evidence.json to reproduce byte for byte; that fixture is the DevX consumer lane, and the pin guards its documented batch behavior only. The configured-project check binds fixtures/compositor/gododin.toml's Phase 4 composition, requires its lock to be byte-identical to the repository lock, and requires the fingerprint compiled into the generated compositor catalog to equal the one both compositor receipts record. The tier reports 80 Phase 5 cases in quick; locked adds the render-policy and typed-package drift checks for 82.

The Phase 5 harness contract is offline. Requalifying the Phase 4 editor/export matrix with the real compositor artifact is a live exact-target matrix and is not part of any tier. It needs a built CLI, the exact Godot executable, and a .gododin/local.toml inside fixtures/compositor naming the same Godot executable and export home as the repository's:

fixtures/compositor/live/phase4.sh --cli /absolute/built/gododin --godot /absolute/canonical/Godot-4.8-dev4 --godot-sha256 <sha256> --evidence-dir /absolute/new-directory

It publishes through gododin build, then drives the recovery editor, the accepted editor, gododin run, and both exports, executes both exported applications, and requires all three rendering processes to reproduce the frozen inspected PNG. Rerun it and rewrite fixtures/compositor/phase4-evidence.json whenever the compositor artifact, the configured project, or the build/editor/run/export path changes.

The Godot-free language protocol is deferred post-1.0 history and is intentionally absent from both active compiler tiers. Its focused legacy tier retains the 81 mechanically counted cases for broker-owned request identity, bounded ownership, revision/supersession behavior, cancellation and shutdown, and authenticated compiler-event provenance:

tests/run.sh legacy-language --odin /absolute/path/to/Odin/odin

The checked-in exact-target raw package is regenerated only through the same authenticated publication path used by the quick-tier drift check:

/absolute/path/to/Odin/odin run tools/apigen -- raw --odin /absolute/path/to/Odin/odin --write
/absolute/path/to/Odin/odin run tools/apigen -- raw --odin /absolute/path/to/Odin/odin --check

The typed fixture policy has a selected-target pre-1.0 check. The complete cross-target command remains available for explicitly scoped post-1.0 work:

/absolute/path/to/Odin/odin run tools/apigen -- fixture-policy --odin /absolute/path/to/Odin/odin --check-selected
/absolute/path/to/Odin/odin run tools/apigen -- fixture-policy --odin /absolute/path/to/Odin/odin --check

Both check the one target. --check-selected verifies the published facade against the selected target's API records; full --check additionally reprojects the policy and Host-compatibility publication from the selected semantic model. The compare-targets command that published a cross-target availability report is gone with the second target; reinstating a comparison is part of whatever post-1.0 decision names another exact version.

Exact official documentation and the reduced Host/image ABI have focused owners:

/absolute/path/to/Odin/odin test tools/docsource -vet -strict-style -warnings-as-errors
/absolute/path/to/Odin/odin test tools/docgen/tests -vet -strict-style -warnings-as-errors
/absolute/path/to/Odin/odin run tools/docsource/runner -- verify --repo-root /absolute/repository/root
/absolute/path/to/Odin/odin run tools/docgen/runner -- --repo-root /absolute/repository/root --output-root /new/empty/output
abi/image/run.sh --odin /absolute/path/to/Odin/odin
tools/cataloggen/run.sh check /absolute/path/to/exact/evidence/odin
tools/cataloggen/run.sh test /absolute/path/to/exact/evidence/odin
buildcoord/test.sh /absolute/path/to/exact/evidence/odin
fixtures/native_basic/live/test.sh

The documentation runner output must match docs/generated/engine.gdi and its receipt byte-for-byte. These checks are included in quick; the explicit commands are useful for focused diagnosis.

--allow-compiler-drift is available only for smoke testing. Its result is labelled unlocked-smoke and cannot update a receipt, accepted evidence, a generated baseline, or a support status.

The locked tier requires the exact project-image evidence compiler hash from gododin.lock. It runs the same active 1.0 cases with that exact compiler. Phase 2 additionally requires the exact pinned Godot snapshot and runs three clean Host lifecycle processes plus isolated registration, construction, and destroy-callback failure processes; all six must close with zero owned counters and restart-required evidence. The Phase 3 locked gate additionally regenerates the compiler-owned catalog in check mode and runs its determinism, relocation, corruption, provenance, and compiler-negative matrix. It authenticates the exact-target receipt but does not rerun that Godot process. Do not use the historical two-target live builder before 1.0. The tier also invokes the external-Odin path through the real public first command and requires exactly one shared handoff. Use it when compiler output or identity is part of the assertion:

tests/run.sh locked --odin /absolute/path/to/exact/evidence/odin --godot /absolute/path/to/exact/Godot

The raw-bottle product tiers are retired. Historical bootstrap probes remain under probes/ and are not routine validation inputs. The accepted prebuilt is the lock-bound ustar publication under releases/distributions/; quick extracts it to a private cache and proves checksum, metadata, permissions, hostile- environment containment, exact handoff, and repeated failure recovery.

Ignored .gododin/local.toml may make the explicit paths convenient:

format = 1

[first_cli]
mode = "external_odin"

[first_cli.external_odin]
executable_path = "/absolute/path/to/exact/Odin/odin"
odin_root = "/absolute/path/to/exact/Odin"
home_directory = "/absolute/private/gododin-home"
temporary_directory = "/absolute/private/gododin-tmp"

[testing]
odin_executable = "/absolute/path/to/local/Odin/odin"
locked_odin_executable = "/absolute/path/to/exact/evidence/odin"
godot_4_8_0_executable = "/absolute/path/to/exact/Godot"

Select prebuilt_gododin instead with a complete [first_cli.prebuilt_gododin] containing absolute cache_root, home_directory, and temporary_directory; never configure both mode sections. The testing paths select validation inputs only. Because the validation harness itself is Odin, every tier also needs the explicit or locally configured development compiler used to launch it.