Pharos Framework

← Back

Pharos Runtime Surface Ownership

This document records the current shared runtime surface split used by Pharos.

It is intentionally descriptive of the repo as it exists today so refactors can reduce overlap without losing the current execution contract.

Dispatcher boundary

The canonical shared dispatcher is:

  • scripts/pharos_runtime.sh

That script currently sources the shared runtime layer files directly and remains the stable public shell/bootstrap dispatcher during the EPY/C refactor.

Shared runtime layer files

The inventory below is grouped by the current dominant ownership area in each layer rather than trying to list every helper one-by-one. The goal is to make the refactor boundary visible enough that future extraction work can move deliberately instead of by accident.

1. runtime/pharos_app_runtime_layer.sh

Owns the higher-level app/runtime shell surface, including:

  • app discovery through pharos.app.json
  • app root lookup and app-local config resolution
  • runtime state/base-path/log-path/debug/socket-path resolution
  • app artifact cleanup and build/runtime path coordination
  • request-line parsing, header extraction, and fail-closed request handling for shell listener paths
  • compiled-host wrapper assembly and shared runtime dispatch into app-owned hosts
  • generated shell host emission for static, dynamic, and templated app targets

Representative helper clusters currently in this file:

  • app discovery/config helpers such as find_app_root, resolve_app_state_path, resolve_app_base_path, and related local/effective path helpers
  • request parsing/normalization helpers such as request_line_method, request_line_target, request_line_is_valid, content_length_is_valid, and header parsing helpers
  • app host/runtime bridge helpers such as capture_app_host_runtime, runtime_dispatch_request, handle_runtime_connection, and build/runtime entrypoint generation helpers

This file is the current shell-side home of shared app assembly behavior, but it is also the biggest mixed-ownership file in the runtime stack.

The highest-value shell/native comparison surface for this layer is recorded in ../contracts/app-runtime-path-parity.md.

2. runtime/pharos_data_runtime_layer.sh

Owns framework-level data and migration helpers, including:

  • checksums and JSON fixture helpers
  • migration record and migration file resolution
  • schema/seed drift inputs and expected checksum logic
  • backend selection defaults
  • PostgreSQL client/config helpers
  • relational runtime bridge helpers used by framework-owned data flows
  • SQL/identifier/string safety helpers consumed by workflow and ops surfaces

Representative helper clusters currently in this file:

  • migration fixture readers such as migration_record_json, migration_backend_*_paths_json, and checksum/drift helpers
  • backend selection and DB access helpers such as app_database_selected_backend_default, sqlite path helpers, and PostgreSQL client wrappers
  • migration/apply/verify support that other runtime layers depend on transitively

This file is the current shell-side home of migration, seed, verify, and relational bridge support.

3. runtime/pharos_generated_surface_layer.sh

Owns generated surface and state-shaping helpers, including:

  • generated helper block emission
  • form decoding helpers
  • JSON merge and path-template helpers
  • generated surface lookup, context binding, filtering, sorting, and projection helpers
  • validation, uniqueness, relation, and constraint report helpers for generated submissions

Representative helper clusters currently in this file:

  • surface lookup/context helpers such as pharos_generated_surface_lookup_json and pharos_generated_surface_context_json
  • collection shaping helpers such as pharos_generated_surface_filter_items_json, pharos_generated_surface_sort_items_json, and pharos_generated_surface_project_items_json
  • submission/validation helpers for generated form input and relation/constraint checks

This file is the current shell-side home of generated admin/API/public surface transformation logic.

4. runtime/pharos_integration_runtime_layer.sh

Owns outbound integration and webhook delivery helpers, including:

  • integration fixture lookup
  • signing and secret-env resolution helpers
  • delivery queue/state mutation helpers
  • retry timing and delivery result update helpers
  • audit event emission for integration delivery work
  • webhook receipt/state persistence helpers

Representative helper clusters currently in this file:

  • fixture/signing helpers such as pharos_integration_fixture_*, pharos_integration_hmac_sha256_hex, and signature-header shaping
  • delivery queue/state helpers such as pharos_integration_create_delivery, pharos_integration_next_due_delivery_ids, and delivery result mutation helpers
  • integration audit/event helpers used by framework-managed delivery and receipt flows

This file is the current shell-side home of framework-owned integration delivery behavior.

5. runtime/pharos_ops_runtime_layer.sh

Owns operator-facing config/probe/report helpers, including:

  • environment validation and env-ref inspection
  • output-path and file-path checks
  • DB config inspection
  • app probe and deploy/doctor-style report shaping
  • backup/restore and drift-check preflight/report helpers

Representative helper clusters currently in this file:

  • environment/config inspection helpers such as pharos_ops_required_env_refs_json, pharos_ops_env_ref_checks_json, and DB/file check helpers
  • report assembly helpers such as pharos_ops_config_report_json, pharos_ops_runtime_probe_report_json, and HTTP probe response shaping
  • operational action helpers such as backup/restore and drift/deploy readiness report generation

This file is the current shell-side home of runtime operational reporting and preflight inspection.

6. runtime/pharos_workflow_runtime_layer.sh

Owns workflow/runtime execution helpers, including:

  • workflow fixture lookup
  • workflow table readiness checks
  • workflow/job idempotency key helpers
  • SQL generation helpers for workflow execution, audit events, and state projection
  • workflow job handling and replay-related helper logic

Representative helper clusters currently in this file:

  • fixture/lookup helpers such as workflow_fixture_* readers
  • deterministic identity helpers such as pharos_workflow_default_idempotency_key and pharos_job_default_idempotency_key
  • SQL generation/execution helpers for workflow events, audit rows, projections, and replay/job mutation paths

This file is the current shell-side home of framework-owned workflow execution support.

Current overlap and cleanup candidates

The inventory shows a few current overlap seams that matter for future refactor work:

  • App vs data: pharos_app_runtime_layer.sh still owns path/runtime dispatch glue that depends directly on DB/state helpers from pharos_data_runtime_layer.sh.
  • App vs generated-surface: app/runtime dispatch owns request entry and compiled-host bridging while generated-surface owns a large amount of request-independent shaping logic that could be isolated more clearly.
  • App vs integration/workflow: the app layer is still the orchestration entrypoint for runtime request flows that later invoke integration/workflow behavior from other layers.
  • Ops vs data/workflow: ops reporting reads deep backend and workflow readiness state rather than staying purely presentation/report oriented.

Highest-value cleanup candidates from the current tree:

  1. keep request parsing + runtime dispatch in pharos_app_runtime_layer.sh, but avoid letting unrelated build/materialization helpers keep growing there
  2. keep DB/backend selection and relational helpers in pharos_data_runtime_layer.sh, and treat that file as the canonical lower layer used by workflow/ops
  3. keep generated-surface transforms request-independent where possible so they remain strong candidates for later declarative source modules extraction
  4. keep integration and workflow state mutation helpers domain-local instead of re-homing them in the app layer
  5. keep ops focused on validation/report shaping instead of accumulating more runtime mutation logic

Current ownership rules

The current expected boundary is:

  • keep scripts/pharos_runtime.sh as the canonical dispatcher during refactor work
  • keep shared framework behavior in these shared runtime files rather than app-local shells
  • keep app-specific behavior in the app bundle that owns it
  • keep shell/runtime changes and native runtime changes synchronized when the behavior is expected in native release artifacts

Refactor implication

This split does not mean the current shell surface is the final architecture.

It means any EPY/C refactor should:

  • start from these six explicit ownership buckets
  • reduce overlap carefully
  • avoid inventing new runtime assumptions that the current bootstrap/native packaging path does not yet support
  • preserve the existing dispatcher contract until a replacement path is proven