Pharos Framework

← Back

Native Convergence Testing Contract

This contract defines the preferred native-first local validation flow for reducing drift between:

  • the native Pharos listener/runtime binary
  • the compiled app host binaries it builds and executes

Preferred local commands

Default developer wrapper:

scripts/check.sh default [build-dir] [native-out-root] [port] [site-root]

Direct convergence check:

scripts/check.sh native-compiled-flow [target-id] [out-root] [port] [site-root]

The default wrapper should materialize the checked dev_docs build and then run the native-first convergence path.

If target-id is omitted, Pharos should infer a host-compatible native target where possible.

Current default inference behavior:

  • Linux x86_64 → linux-x86_64-gnu
  • Linux aarch64|arm64 → linux-aarch64-gnu
  • macOS → macos-universal
  • Windows-ish shells → matching windows-*-msvc target when inference is possible

Current required flow

The command should currently:

  1. ensure Zig is available for the native build path
  2. build the selected native target
  3. run native CLI smoke for that target
  4. run native target verification
  5. run native server smoke when a local route-contract wrapper exists for the selected target
  6. run the deep native route-contract check when the selected target has a supported local execution wrapper

Current deep route-contract wrapper support is intentionally narrower than the general build target matrix.

Current server-smoke behavior

Today, local server-smoke verification is required by this flow for:

  • linux-x86_64-gnu
  • linux-x86_64-musl
  • macos-universal

For other inferred or provided targets, the command may skip the deep route-contract check explicitly while still requiring build, CLI smoke, target verification, and any supported server smoke.

Current deep route-contract wrapper support is:

  • local Linux executable targets: linux-x86_64-gnu, linux-x86_64-musl
  • macos-universal when the host is Darwin

That skip must be explicit rather than silent.

Runner authority default

Unless the caller overrides it explicitly, this flow should default:

  • PHAROS_RUNNER_AUTHORITY=release_authority

This keeps the native-first local flow aligned with the release-authority posture already used by the native verification path.

Intent

This contract does not claim that the native runtime and compiled host are already one implementation.

It does require that local testing stop treating the native listener / compiled-host boundary as an afterthought. The preferred validation flow should exercise that combined path as early as possible on supported hosts so semantic drift trends toward zero.