Pharos Framework

← Back

Native Listener Lifecycle Contract

This contract defines the current Phase 1 listener lifecycle Pharos's native runtime must preserve while listener work remains below the Phase 2 connection seam.

Owned native surface

The current listener lifecycle owner is:

  • src/native_runtime/c/native_listener.c

The current native entrypoint/orchestrator using that surface is:

  • src/native_runtime/c/pharos_runtime.c

Current lifecycle states

The current native listener lifecycle is:

  1. idle
  2. configured
  3. opened
  4. accepting
  5. cleanup requested
  6. closed

Current lifecycle rules

1. Idle to configured

Before listener open:

  • serve config must already be resolved
  • runtime-conf-derived host, port, and socket path defaults must already be applied
  • Unix versus TCP mode selection must already be explicit

2. Configured to opened

When opening a Unix listener:

  • the socket directory must exist before bind
  • stale socket cleanup must remain listener-owned
  • cleanup must refuse to remove non-socket paths
  • socket group and mode policy must be applied after bind

When opening a TCP listener:

  • host and port binding remain listener-owned
  • socket option application remains listener-owned
  • TCP setup must stay structurally separate from Unix setup

3. Opened to accepting

After successful bind and listen:

  • active listener cleanup registration must be in place
  • the listener endpoint reported by the native serve path must match the active transport mode
  • accept-loop entry must remain below the HTTP request path

4. Accepting to cleanup requested

Cleanup may be requested by:

  • native shutdown signal handling
  • normal serve-loop exit
  • listener-open failure cleanup paths

5. Cleanup requested to closed

Cleanup must:

  • close the active listener fd when present
  • remove the Unix socket only when it is still a socket path
  • reset native listener state after cleanup

Current validation commands

Phase 1 listener work should continue to validate through:

pharos/scripts/pharos_runtime.sh native build-target macos-universal pharos/dist/native
pharos/scripts/check.sh ucal native-runtime
pharos/scripts/check.sh ucal runtime-parity
pharos/scripts/check.sh ucal runtime-bundle
pharos/dist/native/macos-universal/pharos status runtime shared --conf pharos/pharos.conf

The last two commands now act as retirement guards that prove the old UCAL host bundle stays removed. These commands do not yet replace deeper future listener-focused tests, but they are the current required executable validation surface for the extracted native listener lifecycle.