firma_process_orchestrator (root module)

Module: firma_process_orchestrator

Contents

Modules

• error - Error surface for firma-process-orchestrator.
• shutdown_event - Cross-process graceful-shutdown signal contract.
• start - Ordered startup, ownership transfer, and supervision.
• status - Observational stack status from runtime state and bounded probes.
• stop - Fail-closed teardown of a running stack.

---

Module: error

Error surface for firma-process-orchestrator.

Module: shutdown_event

Cross-process graceful-shutdown signal contract.

On Unix, [crate::platform::TerminationTarget::signal_soft] uses a kernel signal that does not depend on a shared terminal. Windows has no equivalent for Firma’s console-less children, so each child creates a named event at startup and the stop process signals that event. This module is the single source of truth for the name used on both sides of that protocol.

Module: start

Ordered startup, ownership transfer, and supervision.

See the crate-level lifecycle model for how this phase relates to external stop, status, and runtime-state authority.

Startup transaction

[StartupGuard] owns every [OwnedComponent] before startup performs another fallible operation. After ordered readiness it transfers the complete set to [RunningStack]. Normal errors invoke explicit rollback so a cleanup failure can be returned alongside the initiating error. Guard destruction is only an emergency hard-termination and collection-handoff path; it deliberately leaves uncertain runtime state for later teardown.

Foreground and detached supervision

[start_foreground_from_plan] keeps the [RunningStack] in the calling process through supervision and shutdown. [start_detached] instead owns a direct supervisor child through a two-phase readiness and attachment handshake. The supervisor calls [supervise_owned_generation_from_plan] and creates the components itself, so component capabilities never cross a process boundary. The launcher transfers only supervisor-child collection after attachment is confirmed; failures roll back only the generation it assigned.

A process-global collector is initialized before any managed child is spawned. Explicit detachment and destructor backstops transfer direct-child collection to it without creating threads or waiting for process exit during [Drop].

Module: status

Observational stack status from runtime state and bounded probes.

[probe] classifies a component as [State::Running] only when its persisted [TerminationTarget] is live and its recorded endpoint accepts a connection. A live target without a reachable endpoint is [State::Unhealthy]; missing or stale target state is [State::Stopped]. Listen-address and uptime metadata are best-effort and never grant lifecycle authority.

Module: stop

Fail-closed teardown of a running stack.

[stop_components] takes a process-target snapshot under [StateTransaction], then delegates to [stop_inner]. Runtime state is removed by [cleanup] only after every target is proven absent and [cleanup_generation] confirms the original [StateLease] still owns the directory. [target_may_exist] treats probe uncertainty as presence, preserving signalling effort and retry evidence. See the crate-level lifecycle model for the process and runtime-state capabilities required by teardown.

External teardown reconstructs the strongest available termination targets from persisted numeric identities. A [StackGeneration] fences which runtime state may be cleaned, but it does not prove that a reused OS process or process-group ID still names the original target. Callers should therefore treat retained runtime state as termination evidence, not durable process identity.