Pharos Framework

← Back

App Runtime Path Parity Contract

This contract keeps the shell/runtime and native runtime path resolution rules aligned for app targets.

Phase 2 now also declares shared declarative runtime metadata as the ownership surface for these path/default behaviors, while shell and native remain the executable adapters. pharos build app may emit a companion artifact (pharos-runtime-io.runtime.link) that records the active app build's linkage back to that metadata.

Parity behaviors to preserve

1. Base path resolution

Shell and native should both preserve the same precedence order:

  1. explicit base-path override
  2. explicit app-local base_path
  3. manifest-declared base_path
  4. default empty base path

Relative manifest paths should resolve relative to the app root.

2. State path resolution

Shell and native should both preserve the same precedence order:

  1. explicit state-path override
  2. explicit state-dir override or local state-dir setting
  3. manifest-declared runtime.state_path
  4. default build_dir/<app_id>/runtime-state.json

Relative manifest paths should resolve relative to the app root.

The native direct-build/runtime path uses the same effective state-path helpers as the shell path.

3. Build dir selection

Shell and native should both preserve:

  • explicit build-dir override when provided
  • otherwise app-local build_dir if present
  • otherwise default to <app_root>/dist

The native direct-build/runtime path uses the same effective build-dir helpers as the shell path.

4. Log/debug defaults

Shell and native should both preserve:

  • explicit log_path override when provided
  • otherwise app-local log_path when configured
  • otherwise /var/log/pharos/<app_id>.log
  • explicit debug override when provided
  • otherwise app-local debug when configured
  • otherwise false

The native direct-build/runtime path uses the same effective log and debug helpers as the shell path.

Allowed divergence rule

If shell and native intentionally diverge for one of these behaviors, that divergence must be:

  • documented explicitly
  • justified by platform/runtime constraints
  • reflected in checked contracts, tests, and docs

Silent drift is out of contract.