swactor/docs/specs/drafts/SWACTOR_CONTEXTUAL_PROCESS_SPEC.md

Swactor Contextual Process Feature and Migration Specification

Status: Implemented

Last modified: c705c74289

This specification supersedes the job-runner design. It defines the target behavior, architecture, migration, implementation order, and verification for spawning an OS process that may claim a Swactor context.

---

1. Objective

Swactor MUST support two explicit forms of supervised process execution:

1. Native process: the existing managed OS process, with lifecycle, termination, stdout, and stderr supervision.
2. Contextual process: the same managed OS process plus a provisioned, process-scoped Swactor context that an installed language binding may claim.

Contextual execution MUST reuse swactor-process; it MUST NOT introduce a job, job runner, scheduler, workspace protocol, setup/run phases, output collector, or job FSM.

For Python, the guest API remains:

import swactor

async def main(ctx):
    ...

swactor.run(main)

swactor.run MUST obtain everything required to construct ctx without the program supplying actor addresses, transport endpoints, capabilities, arena metadata, or routing configuration.

---

2. Scope

2.1 In scope

• safe supervision of contextual OS processes;
• one opaque host-to-child bootstrap handle;
• data-plane session, arena, routing, and capability provisioning;
• exactly-once binding attachment;
• observable distinction between OS start and context readiness;
• deterministic lifecycle and cleanup under races and failures;
• migration of the existing Python binding;
• removal of the job runner and job-specific process/data-plane terminology;
• a deterministic, model-based test architecture that exercises arbitrary legal event DAGs and rejects minimally invalid variants.

2.2 Out of scope

• automatic language or entrypoint detection;
• transparent libc, allocator, syscall, CUDA, or device interception;
• making an unaware executable use a Swactor context;
• dependency installation, workspaces, setup commands, or output collection;
• scheduling, placement, retry, or node provisioning policy;
• UI submission and remote artifact transfer;
• context inheritance across fork;
• generalized interactive process support.

A contextual executable opts in by invoking a supported binding. An executable that does not invoke a binding remains valid only on the native spawn path.

---

3. Terminology

• Process core: swactor-process, responsible only for OS process lifecycle.
• Contextual spawner: the composition layer that provisions a context and delegates OS supervision to the process core.
• Bootstrap handle: the sole opaque descriptor inherited by a contextual child.
• Bootstrap claim: the binding's one permitted use of that handle.
• Context ready: the binding has attached successfully and can use the provisioned data plane.
• Session: the process-scoped host data-plane session.
• Session capability: the unforgeable authorization for that session.
• Session access: the execution identity and namespace prefixes authorized for that session.
• Execution: one contextual process lifetime. This is correlation identity, not a job abstraction.

---

4. Required behavior

4.1 Native process behavior

spawn_local_process and ProcessSpec retain their existing contract. Native spawn MUST NOT:

• allocate an arena;
• create a data-plane session;
• inherit a bootstrap handle;
• wait for a binding;
• emit contextual lifecycle events;
• depend on the contextual-spawn crate.

4.2 Contextual process behavior

A contextual spawn MUST:

1. validate its process specification and session access;
2. provision the arena, session capability, host session, and private bootstrap channel;
3. transfer the child end of that channel through the process core as an explicitly owned inherited resource;
4. start the OS child using the existing process actor;
5. allow the installed binding to claim the bootstrap exactly once;
6. construct a usable binding context without caller coordination;
7. resolve context readiness or bootstrap failure;
8. preserve native process lifecycle facts;
9. stop a started child whose context cannot become ready;
10. revoke the session and release every contextual resource on every terminal path.

The contextual spawner owns this sequence. Its caller supplies normal process configuration and session authorization, not transport internals.

4.3 Guest-visible bootstrap surface

The child MUST inherit exactly one Swactor-owned bootstrap descriptor. The private binding ABI SHOULD use a fixed descriptor number so no environment variable is required.

The following environment variables MUST be removed:

SWACTOR_ARENA_FD
SWACTOR_DATA_PLANE_ACTOR
SWACTOR_JOB_CAPABILITY
SWACTOR_DATA_PLANE_ENDPOINT

The binding MUST treat the bootstrap descriptor as opaque. A one-use Unix SOCK_SEQPACKET channel is the preferred Linux implementation. The host sends private, versioned session material and transfers the arena descriptor with SCM_RIGHTS only after accepting the claim.

Possession of the bootstrap descriptor is a bearer capability. The protocol does not promise to conceal its bytes from a malicious child; it promises that these bytes are not configuration or application API and that another contextual spawn cannot accidentally receive them.

4.4 Binding behavior

swactor.run(main) MUST:

1. locate the private bootstrap descriptor;
2. perform one versioned bootstrap claim;
3. receive and validate the arena descriptor and private session material;
4. establish child routing;
5. attach the child data plane;
6. notify the host that context attachment succeeded;
7. invoke main(ctx) using the existing Python Context and data-plane API.

A missing, closed, malformed, incompatible, already-claimed, or rejected bootstrap MUST raise BootstrapError. Attachment errors MUST retain their existing typed translation where possible and MUST also resolve the host-side bootstrap as failed.

swactor.run MUST NOT silently fall back to an uncontextualized execution.

---

5. Lifecycle contract

Native process facts and context attachment facts are related but distinct.

5.1 Observable events

The contextual layer exposes:

Process(ProcessOutput)
ContextReady
BootstrapFailed { reason }

ProcessOutput remains owned by swactor-process and retains its current Started, SpawnFailed, Exited, Error, stdout, and stderr semantics.

5.2 Ordering and resolution

• ContextReady MUST occur only after Process(Started).
• ContextReady and BootstrapFailed are mutually exclusive.
• At most one context-resolution event may be emitted.
• If OS spawn fails, the contextual layer emits the native SpawnFailed fact and no context-resolution event: no child existed to claim a context.
• After Process(Started), a process terminal event MUST be preceded by exactly one context-resolution event.
• Exit, channel closure, attachment failure, or attachment deadline before readiness resolves as BootstrapFailed.
• BootstrapFailed after OS start MUST request native process termination.
• A late claim, attachment result, timeout, or stop acknowledgement MUST NOT change a resolved context outcome.
• Native process stdout and stderr remain observable before and after context resolution until the native process terminates.

5.3 Readiness

OS Started means only that the executable was created. ContextReady means the binding has attached and its data plane is usable. Callers MUST use ContextReady, not Started, when they require Swactor API availability.

The attachment deadline begins after OS start. It is configured by the contextual spawner and driven by its clock service; bindings MUST NOT embed a separate hard-coded policy deadline.

5.4 Stop and cleanup

A stop request may race provisioning, OS spawn, bootstrap claim, attachment, or exit. It MUST be idempotent.

• Before OS start, stop prevents or cancels spawn where possible.
• After OS start, stop delegates to send_process_command and its existing terminate/kill policy.
• Stop before readiness resolves the context as failed unless OS spawn itself fails first.
• Bootstrap channel closure and session revocation may begin immediately after context failure.
• Arena backing and resources reachable by the child MUST remain owned until the OS child has terminated.
• Cleanup effects MUST execute at most once and MUST eventually complete after the process reaches a terminal state.
• No terminal path may leave a routable child session, active capability, bootstrap descriptor, or arena owner behind.

---

6. Behavioral invariants

The implementation and every test oracle MUST enforce these invariants.

Identity and isolation

• I1: One contextual spawn owns one execution identity, session capability, host session, arena, and bootstrap channel.
• I2: A bootstrap handle can be claimed at most once.
• I3: A handle created for execution A cannot attach execution B.
• I4: Concurrent spawn cannot leak one Swactor-owned child descriptor into another child.
• I5: Stale events from an earlier execution or generation cannot affect a later execution.

Ordering and outcomes

• I6: Context cannot resolve before OS spawn resolves.
• I7: Context ready requires OS start, accepted claim, successful routing, and successful data-plane attachment.
• I8: Context ready and bootstrap failed cannot both occur.
• I9: Once emitted, process and context terminal facts are immutable.
• I10: Started contextual processes produce one context resolution before their native terminal event is forwarded.
• I11: Native spawn failure never masquerades as bootstrap failure.

Authorization and API boundary

• I12: The session accepts only its own capability and current generation.
• I13: Session access limits every namespace open independently of path discoverability.
• I14: No child-facing environment or argument exposes Swactor routing, actor, capability, endpoint, or arena internals.
• I15: Native spawn receives no contextual authority or resources.

Ownership and cleanup

• I16: Bootstrap resources outlive the attempt to exec the intended child.
• I17: Context resources outlive the running child and no longer.
• I18: Revocation and cleanup are idempotent under duplicate and reordered completion events.
• I19: Quiescence after any terminal path leaves no live bootstrap endpoint, host session, session capability, route, arena owner, or deadline.
• I20: Failure in one execution cannot stop, revoke, or corrupt another.

---

7. Public API target

Exact Rust layout may adapt to existing actor conventions, but the ownership and observable types below are normative.

7.1 Retained process API

ProcessSpec
ProcessCommand
ProcessOutput
ProcessOutputConfig
spawn_local_process
send_process_command

7.2 Process-core resource seam

swactor-process adds a narrow resource-bearing spawn primitive:

pub struct ProcessSpawnResources {
    // Owned descriptor mappings; construction validates unique child targets.
}

pub fn spawn_local_process_with_resources(
    ctx: &Ctx,
    sender: &ExternalSender,
    spec: ProcessSpec,
    resources: ProcessSpawnResources,
    output: ProcessOutputConfig,
) -> Result<ActorAddress, Error>;

ProcessSpawnResources owns descriptors until the OS spawn attempt resolves. Descriptor sources remain close-on-exec in the parent. Child descriptor mapping MUST happen atomically in the child through posix_spawn file actions or an equivalent safe pre_exec mapping; the implementation MUST NOT create an ambient parent-side non-CLOEXEC inheritance window.

The existing spawn_local_process is the empty-resource path.

7.3 Contextual process API

A new swactor-process-context composition crate exposes:

pub struct ContextualProcessSpawner { /* node services */ }

pub struct ContextualProcessSpec {
    pub process: ProcessSpec,
    pub access: SessionAccess,
    pub attach_deadline: Duration,
}

pub enum ContextualProcessOutput {
    Process(ProcessOutput),
    ContextReady,
    BootstrapFailed { reason: BootstrapFailure },
}

impl ContextualProcessSpawner {
    pub fn spawn(
        &self,
        ctx: &Ctx,
        sender: &ExternalSender,
        spec: ContextualProcessSpec,
        output: ContextualProcessOutputConfig,
    ) -> Result<ActorAddress, Error>;
}

ContextualProcessSpawner is constructed once from node-owned runtime, transport, namespace, arena, and route services. Per-spawn callers cannot supply raw host actor addresses, endpoint addresses, arena generations, or session capabilities.

7.4 Data-plane terminology

Clean cutover:

JobCapability  → SessionCapability
JobContext     → SessionAccess
run_id         → execution_id
JobHandoff     → removed
install_session_env → removed

No compatibility aliases or deprecated environment path remain.

---

8. Code architecture

8.1 Dependency direction

swactor-process                 data-plane
         \                         /
          \                       /
            swactor-process-context
                       |
                 language bindings

swactor-process MUST NOT depend on the data plane or contextual-spawn crate. The contextual crate may depend on both. Python consumes the guest bootstrap helper and existing data-plane API.

8.2 Deterministic coordinator

The contextual crate MUST separate lifecycle decisions from side effects.

A small coordinator owns plain state and implements:

apply(Event) -> ordered list of Effect

Representative input events:

SpawnRequested
ProvisionSucceeded / ProvisionFailed
ProcessStarted / ProcessSpawnFailed / ProcessExited / ProcessError
BootstrapClaimed / BootstrapRejected / BootstrapClosed
AttachmentSucceeded / AttachmentFailed
AttachmentDeadline
StopRequested
SessionFault
CleanupCompleted

Representative effects:

ProvisionSession
SpawnNativeProcess
ArmAttachmentDeadline / CancelAttachmentDeadline
AcceptBootstrap / RejectBootstrap / CloseBootstrap
EmitContextReady / EmitBootstrapFailed / EmitProcessOutput
StopNativeProcess
RevokeSession
ReleaseArena
Finish

The actor adapter executes effects through narrow ports and feeds their outcomes back as events. It MUST NOT contain independent lifecycle policy. The pure coordinator is production code, not a test-only copy.

Required ports are limited to:

• process spawn/control;
• session and arena provisioning;
• bootstrap transport;
• clock/deadline scheduling;
• lifecycle output.

This split exists to make races, failures, and cleanup exhaustively testable without real time, OS scheduling, or network nondeterminism. It MUST NOT grow into a generic workflow or job framework.

8.3 Bootstrap implementation

The bootstrap transport belongs beside the data-plane bootstrap contract. Its host and guest helpers own framing, version negotiation, descriptor transfer, and closure. Language bindings MUST call the guest helper rather than parse wire fields.

The arena header and mapping validation remain data-plane concerns. Actor routing and session authorization remain private bootstrap payload fields.

---

9. Deterministic contract test architecture

9.1 Test objective

Tests MUST prove behavior over arbitrary partial orders of legal lifecycle events, not only hand-authored happy paths. They MUST check invariants after each step and at quiescence. They MUST also prove that the checker rejects traces just outside the legal contract.

Tests MUST NOT depend on sleeps, wall-clock timing, random actor scheduling, real network timing, or inspection of private implementation fields.

9.2 Scenario DAG

The contextual crate provides a test harness with a typed ScenarioDag:

ScenarioDag
  nodes: typed external actions or port completions
  edges: required happens-before relationships
  identities: execution/session/generation correlation
  faults: explicit selected failure outcomes

The generator MUST:

1. choose one or more concurrent executions;
2. select legal terminal outcomes for provisioning, spawn, claim, attachment, stop, and exit;
3. add mandatory causal edges, such as spawn before OS start and claim before attachment result;
4. add arbitrary acyclic ordering edges between otherwise concurrent actions;
5. include races such as stop versus start, timeout versus claim, exit versus attachment, duplicate delivery, and stale completion;
6. reject contradictory outcome sets rather than normalizing them silently;
7. shrink while preserving graph validity and mandatory causal edges.

For each generated DAG, the harness executes multiple topological linearizations. Small DAGs SHOULD execute every topological order; larger DAGs execute deterministic seeded linearizations emphasizing first/last placement of concurrent boundary events.

9.3 Deterministic driver

The SUT uses the production coordinator with fake ports:

• virtual monotonic clock;
• deterministic execution/session/generation identifiers;
• synthetic owned-descriptor identities;
• recorded process, bootstrap, session, and output effects;
• explicit effect completion controlled by DAG nodes.

After every delivered event, the harness records:

input event
emitted effects
public lifecycle outputs
resource ledger
pending deadlines
context resolution
process resolution

No fake may make lifecycle decisions on behalf of the coordinator.

9.4 Independent contract oracle

The oracle MUST be declarative and separate from the coordinator transition implementation. It checks the trace and resource ledger against §5 and §6; it MUST NOT call the coordinator to calculate expected behavior.

At each prefix it checks safety properties, including uniqueness, ordering, isolation, authorization, and terminal monotonicity. At quiescence it also checks liveness obligations: required resolution occurred and the resource ledger is empty.

Generated traces and minimal regressions are persisted using the repository's existing proptest regression mechanism.

9.5 Deliberate rejection tests

The suite MUST bind each contract from both sides:

1. generate or construct a legal DAG and prove every selected linearization is accepted;
2. make one minimal illegal mutation and prove the oracle rejects it with the expected invariant identifier.

Required mutation pairs include:

Accepted boundary	Deliberately rejected neighbor
one claim	duplicate claim (I2)
execution A claims A's handle	execution B claims A's handle (I3)
child inherits its own descriptor	child inherits a sibling descriptor (I4)
ready after start and attachment	ready before start or attachment (I6, I7)
one context outcome	ready and failed both emitted (I8)
bootstrap failure after start	bootstrap failure used for OS spawn failure (I11)
authorized path open	open outside session prefixes (I13)
native spawn with no context	native spawn receives bootstrap authority (I15)
cleanup once after terminal	cleanup omitted or repeated non-idempotently (I18, I19)
stale event ignored	stale event changes current execution (I5)
one execution fails in isolation	sibling resources are revoked (I20)

These are passing tests that deliberately feed invalid traces to the checker and assert a specific rejection. The suite MUST also include checker-calibration fixtures with deliberately broken effect ledgers. This prevents a vacuous oracle that accepts everything or never observes cleanup leaks.

9.6 Boundary integration tests

Model tests do not replace real boundary verification:

• Process descriptor tests: real concurrent Linux children prove fixed-target inheritance, CLOEXEC, ownership through exec, and no sibling leakage.
• Bootstrap tests: real Unix sockets prove one-use claim, version rejection, truncated framing, peer closure, and SCM_RIGHTS arena transfer.
• Data-plane tests: real session attachment proves capability and generation rejection and cleanup.
• Python test: a real Python child calls swactor.run, observes usable ctx.data, performs one namespace operation, and exits successfully.
• Failure Python tests: missing claim, duplicate claim, attachment rejection, and user exception remain distinguishable.
• Native regression tests: existing swactor-process lifecycle, output, and stop contracts remain unchanged.

Integration tests use explicit synchronization events or bounded virtual/test engine progress. They MUST NOT use sleep as correctness synchronization.

---

10. Migration map

Current	Target	Action
swactor-process::spawn_local_process	Native process primitive	Retain unchanged behavior.
ProcessSpec	OS execution description	Keep free of context internals.
No owned inherited-resource seam	ProcessSpawnResources	Add and verify atomic child-only inheritance.
crates/process/pipeline.rs and yaml.rs	Nothing	Remove job/pipeline layer and exports, subject to final callsite inventory.
swactor-job-runner	Nothing	Remove crate, FSM, wire protocol, packaging, and tests.
Myelin job deployment/reconciliation	Contextual execution submission	Replace required node launch behavior; delete setup/workspace/output job paths.
JobHandoff and environment assembly	Private bootstrap host endpoint	Replace; no compatibility path.
Four bootstrap environment variables	Fixed opaque bootstrap descriptor	Remove constants, parsing, tests, and deployment assumptions.
JobCapability	SessionCapability	Rename every wire and API use.
JobContext { run_id, ... }	SessionAccess { execution_id, ... }	Rename and migrate serialized/configured uses.
install_session_env	Nothing	Delete.
Python job.rs	Context/bootstrap implementation	Rename module and internal job-named symbols.
JobRouting	Private context routing state	Rename; never expose to guest code.
swactor.run(main)	Same guest API	Preserve observable behavior while replacing bootstrap source.
Dashboard job-runner-* fixtures	Execution/process labels	Update fixtures without adding dashboard control behavior.
Draft job-runner spec	Superseded	Archive or remove when this migration lands.

No deprecated aliases, old environment fallback, dual bootstrap protocol, or job-runner compatibility shim may remain after migration.

---

11. Implementation sequence

Each stage must leave one authoritative path for the contract it introduces. Temporary compatibility is allowed only within an unmerged implementation branch and must not appear in the completed feature.

1. Inventory: confirm all process pipeline, job-runner, Myelin, deployment, dashboard fixture, Python, and data-plane callsites named in §10.
2. Process resources: implement owned child descriptor mapping and its real Linux isolation tests.
3. Terminology cutover: rename data-plane job capability/context concepts to session concepts across wire codecs, tests, and bindings.
4. Bootstrap channel: implement host/guest one-use protocol and boundary tests; keep private payload construction in Swactor.
5. Deterministic coordinator: implement event/effect core, ports, contract oracle, DAG generator, legal properties, and deliberate rejection fixtures.
6. Contextual actor: connect coordinator effects to process, data-plane, bootstrap, clock, and output adapters.
7. Python migration: make swactor.run claim the bootstrap channel; remove environment parsing and hard-coded attachment deadline.
8. End-to-end proof: spawn a real Python process through the contextual API and exercise ctx.data.
9. Application migration: replace the node-side job execution path with contextual process submission where required for current application behavior.
10. Deletion: remove job-runner crate, process pipeline/YAML job layer, old codecs, app job FSMs, workspace/output packaging, environment bootstrap, and obsolete tests/configuration.
11. Final verification: run focused suites, workspace compilation, and static absence checks for all removed symbols and environment variables.

Deletion follows successful migration of required callers; it is not deferred as follow-up cleanup.

---

12. Acceptance criteria

The feature is complete only when all of the following are true:

1. Native process behavior remains compatible and context-free.
2. A contextual Python process reaches ContextReady, uses ctx.data, and exits zero through real process supervision.
3. The child receives one opaque bootstrap descriptor and no Swactor bootstrap environment contract.
4. Concurrent contextual children cannot claim or inherit each other's resources.
5. Every started contextual process emits exactly one context resolution before its native terminal event.
6. Every failure and stop race reaches quiescence with an empty contextual resource ledger.
7. Arbitrary generated legal event DAGs satisfy every invariant under tested topological linearizations.
8. Minimal illegal mutations are rejected with the intended invariant IDs, and checker-calibration fixtures detect deliberately broken ledgers.
9. Python guest APIs and existing data-plane operations remain usable without caller-supplied routing or capability internals.
10. swactor-job-runner, process job/pipeline APIs, job-named data-plane session types, leaked bootstrap variables, and all compatibility paths are absent.
11. UI submission, remote transfer, generalized interception, scheduling, and provisioning remain outside this feature.