JIT Spawning Model for the Agent Container Daemon (ACN) in Magnitude: Exact-Once Process Management

Magnitude uses a Just-In-Time (JIT) ensurance model driven by AcnInstanceManager to guarantee exact-once creation of ACN daemons, ensuring clients receive a single ready instance matching a specific revision through a finite-state machine lifecycle.

The magnitudedev/magnitude repository implements a sophisticated container orchestration mechanism that treats ACN lifecycle management as a stream-based coordination problem. The JIT spawning model for the agent container daemon (ACN) in Magnitude ensures that clients obtain precisely one healthy daemon instance per data root, eliminating race conditions through deterministic state transitions and SQLite-backed ownership records.

How the JIT Ensurance Model Works

The Ensurance Request Flow

When a client requires an ACN instance, it invokes AcnInstanceManager.ensure({ target }) with an AcnTarget encoding the desired revision. This method returns a stream of AcnEnsureEvent objects that represent the progression from request to resolution. According to the source code in packages/sdk/src/acn-jit/acn-instance-manager.ts, the manager transforms the target specification into a supervised lifecycle that guarantees exactly one terminal outcome.

Candidate Launch and State Machine

If no existing ACN satisfies the target, the AcnCandidateLaunchSupervisor initiates a new process candidate. This supervisor implements a strict finite-state machine defined in packages/sdk/src/acn-jit/acn-candidate-launch-supervisor.ts, transitioning through NotLaunched → Spawned → Admitted → Ready (with an alternative terminal state of Failed). Each state change is observable and irreversible, ensuring deterministic lifecycle progression.

Ownership and Identity Management

Every candidate binds to an ExactProcess identity and an AcnIdentity revision marker. The AcnOwnerStore persists this ownership relationship in SQLite, located in packages/acn/src/acn-subscriptions.ts. A candidate becomes the legitimate owner only after the store confirms a successful compare-and-replace operation, preventing split-brain scenarios where multiple processes claim the same ACN slot.

Admission and Readiness Verification

Once admitted, the AcnDaemonShutdownSupervisor (defined in packages/sdk/src/acn-jit/acn-daemon-shutdown-supervisor.ts) monitors the candidate for graceful termination signals, escalating from TERM to KILL if necessary. Simultaneously, the system awaits an HTTP 200 health response and revision verification. Only upon confirming both process health and identity match does the manager emit an AcnInstance<AcnReady> event.

Exact-Once Guarantees and Lifecycle Boundaries

Single-Result Stream Resolution

The runAcnEnsure pipeline in packages/sdk/src/acn-jit/acn-instance-manager.ts enforces a critical invariant: the ensurance stream resolves exactly once. It yields either a ready ACN instance or a typed terminal failure, failing explicitly if multiple readiness events appear. This design eliminates intermediate states like "starting" or "stopping" from the public API surface, presenting clients with a binary outcome.

Separation of Concerns Across Six Authorities

As documented in design/acn/lifecycle/jit-spawning.md, the Magnitude SDK decomposes lifecycle control into six narrow authorities:

• AcnOwnerObserver: Reads owner and health state without mutation.
• AcnConvergenceDecider: Pure function mapping observations to actions, implemented in packages/sdk/src/acn-jit/acn-convergence-decider.ts.
• AcnDaemonShutdownSupervisor: Owns graceful shutdown of existing daemons.
• AcnCandidateLaunchSupervisor: Owns the entire candidate lifecycle.
• AcnDaemonLaunchCommandResolver: Resolves launch commands without side effects.
• AcnEnsuranceCoordinator: Orchestrates the above components.

This separation isolates OS-level process-group control from ACN-specific business logic, implemented through effect-typed coordination primitives.

Practical Implementation: Requesting an ACN Instance

The public API exposes the JIT spawning mechanism through Effect-TS streaming primitives. The following TypeScript demonstrates how to request a specific ACN revision and consume the resulting instance:

import { AcnInstanceManager, AcnEnsureRequestSchema } from "@magnitudedev/sdk/acn-jit";
import { Effect } from "effect";

// 1️⃣ Request an ACN matching a specific revision
const request = AcnEnsureRequestSchema.encode({
  target: { revision: 42 }   // Desired ACN revision
});

// 2️⃣ Run the ensure stream – obtains a ready ACN or fails
const acnReady = Effect.gen(function* ($) {
  const stream = yield* $(AcnInstanceManager).ensure(request);
  return yield* $(AcnInstanceManager.runAcnEnsure(stream));
});

// 3️⃣ Use the ready instance (e.g., call an RPC)
acnReady.pipe(
  Effect.flatMap(acn => acn.rpc.someMethod({ /* … */ }))
);

This code triggers the full JIT spawning pipeline, including candidate supervision, ownership negotiation, and health verification, ultimately yielding an AcnReady instance suitable for RPC communication.

Summary

• The JIT spawning model for the agent container daemon (ACN) in Magnitude guarantees exact-once instantiation per data root through the AcnInstanceManager API.
• State transitions follow a rigorous finite-state machine from NotLaunched to Ready, supervised by the AcnCandidateLaunchSupervisor.
• SQLite-backed ownership via AcnOwnerStore prevents duplicate daemons through atomic compare-and-replace operations.
• The architecture separates concerns into six distinct authorities, isolating process control from policy decisions.
• Clients interact with a binary outcome stream that resolves exactly once, eliminating ambiguity around daemon readiness.

Frequently Asked Questions

What triggers the JIT spawning of an ACN in Magnitude?

A client request via AcnInstanceManager.ensure({ target }) triggers the process when no existing daemon matches the requested revision. The system lazily creates the candidate process only upon explicit demand, hence the Just-In-Time designation.

How does Magnitude prevent duplicate ACN instances?

The AcnOwnerStore maintains authoritative ownership records in SQLite. A candidate process must successfully complete a compare-and-replace operation to claim ownership. The runAcnEnsure pipeline additionally fails if it detects multiple readiness events, ensuring at-most-one semantics.

What happens if an ACN candidate fails during startup?

The AcnCandidateLaunchSupervisor FSM includes a terminal Failed state. If a candidate exits before reaching Ready or fails health checks, the stream emits a typed terminal failure. The client receives this error as the single resolution of the ensurance operation, allowing for explicit error handling without polling intermediate states.

How is ACN ownership persisted across process restarts?

Ownership binds to an ExactProcess identity and revision marker stored in SQLite via packages/acn/src/acn-subscriptions.ts. When the SDK restarts, the AcnOwnerObserver reads this persistent state to determine whether an existing valid owner exists, enabling seamless recovery without orphaned processes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}