Skip to content

LOCAL_VERIFICATION.md

Latest commit

 

History

History
87 lines (68 loc) · 6.39 KB

LOCAL_VERIFICATION.md

File metadata and controls

87 lines (68 loc) · 6.39 KB
Raw

Local Verification Contract

The canonical local verification family is exposed through root pnpm scripts and matching Make targets:

For documentation-only iteration, pnpm docs:check validates active Markdown file targets and GitHub-style anchors without contacting the network. The change/full verification profiles invoke the same check through the always-on workspace-quality lane.

Profile Command Contract
Fast pnpm verify:fast Runs the verification-orchestrator tests, whitespace check, and managed-version check.
Change pnpm verify or pnpm verify:change Runs strict common checks plus every deterministic lane selected by changed paths relative to origin/main. Override the base with WAP_VERIFY_BASE=<ref> or --base <ref>.
Full pnpm verify:full Runs every deterministic offline lane, including compliance/status drift, graph drift, native and WASM engine checks, contracts, stories, transport, browser host/frontend unit/rendered accessibility, Atlas, marketing, Go WML origin, and backend-disabled OpenTofu checks.
Extended pnpm verify:extended Runs the full profile, then requires the already-running live Kannel/WML stack and runs the browser baseline as a non-blocking stability signal.

Equivalent Make targets are verify-fast, verify-change, verify-full, and verify-extended. make ci-local is retained only as a deprecated compatibility alias. It prints an advisory and runs make verify-full; it is not described as CI-equivalent because GitHub-hosted coverage, security, OS packaging, and service topology are separate environments.

Outcome vocabulary

Every known lane is reported with one of these explicit outcomes:

  • PASS: every required command in the selected lane passed.
  • INTENTIONAL EXCLUSION: the profile or changed paths deliberately did not select the lane.
  • UNAVAILABLE PREREQUISITE: a selected required tool or dependency is missing. This makes the command fail and includes a remediation hint.
  • ADVISORY: the lane is intentionally non-blocking, whether its evidence passed or failed.
  • FAILURE: a selected required command failed. The overall command exits nonzero.

There is no successful skip for a missing prerequisite in a selected required lane. Run ./scripts/init-refresh.sh to refresh workspace dependencies. Install the repository Node/pnpm versions first when absent; use AUTO_INSTALL_RUST_TOOLS=1 ./scripts/init-refresh.sh when the pinned wasm-pack or Tauri CLI must be installed. Go 1.25 or newer is required when the selected lane includes wml-server/. OpenTofu 1.12.5 and actionlint 1.7.12 are required when the selected lane includes infra/network-preview/; install actionlint with go install github.com/rhysd/actionlint/cmd/actionlint@v1.7.12. Its static lane validates the three OpenTofu workflow definitions semantically, never receives cloud credentials, and never enables the R2 backend.

Selection and evidence boundaries

The change profile combines committed branch changes, staged changes, unstaged changes, and untracked files. Root verification surfaces such as package.json, pnpm-lock.yaml, the CI workflow, or the orchestrator itself select all ordinary deterministic lanes because they can change every lane's behavior. Layer paths select only their affected commands.

The full profile is the ordinary pre-PR command. It deliberately excludes:

  • the live Kannel/browser smoke, which requires Docker services and is run by pnpm verify:extended or the manual Transport WAP Smoke (Kannel) workflow;
  • scheduled/advisory performance trends beyond the bounded five-run extended baseline;
  • fuzz campaigns, which remain explicit time-bounded commands;
  • GitHub-hosted dependency, CodeQL, coverage-threshold, release, deployment, and OS-packaging jobs.
  • protected R2 locking and DigitalOcean speculative planning, which remain unavailable until PRE-001 and PRE-003 are completed.

Passing actionlint proves that the checked expression contexts and workflow structure satisfy the pinned offline validator. It does not create the PRE-003 protected environments or prove live R2 locking, provider planning, exact-plan apply, or state-recovery behavior.

These exclusions are visible in command output and do not imply conformance or release readiness. The full compliance wrapper proves that canonical compliance inputs, the family-wide WML evidence ledger, successor-delta crosswalk, and generated projections are synchronized. It validates Rust, TypeScript/Vitest, and executable-story evidence according to their supported runners; implementation conformance still depends on those direct fixtures and the release evidence named by the selected profile.

The extended live-Kannel lane expects the stack to advertise WML 1.3 explicitly at its test boundary. Start it with WML_DTD_VERSION=1.3 docker compose up -d --build kannel wml-server, run pnpm verify:extended, and always finish with docker compose down. The transport itself sends the matching WSP Encoding-Version: 1.3 request header; neither setting relaxes the production network policy or the strict WBXML 1.3 decoder.

Automated contract tests

Run the orchestration tests directly with:

pnpm verify:test

They cover profile selection, path selection, required failure propagation, advisory behavior, unavailable prerequisites, intentional exclusions, and the CI/compliance-wrapper wiring.