# What Are the Responsibilities of the ICN (Inference Communication Node) in Magnitude?

> Discover the responsibilities of the ICN Inference Communication Node in Magnitude. Learn how it manages binary resolution, model lifecycle, and hardware for local inference within an ACN.

- Repository: [Magnitude/magnitude](https://github.com/magnitudedev/magnitude)
- Tags: internals
- Published: 2026-09-06

---

**The Inference Communication Node (ICN) in Magnitude is a private, local-inference runtime that handles binary resolution, process supervision, model lifecycle management, and hardware calibration—serving as the sole authority for all native inference concerns within an Agent Coordination Node (ACN).**

The ICN is implemented by the `@magnitudedev/icn` package and lives inside an ACN process. According to the [Magniude source code](https://github.com/magnitudedev/magnitude), it maintains strict ownership boundaries: ACN consumes the ICN through a generated client, but the ICN never exposes public APIs for hardware or model loading directly. This design isolates inference complexity from higher-level orchestration policies.

---

## Core Responsibilities of the ICN

The ICN's duties are specified in [`design/icn/lifecycle.md`](https://github.com/magnitudedev/magnitude/blob/main/design/icn/lifecycle.md) and implemented across the `@magnitudedev/icn` package. Here are the ten primary responsibilities:

### Binary Resolution and Verification

The ICN resolves a release-matched installation path for the `magnitude‑inference` binary, verifies its build identity and API version, and ensures the executable belongs to the declared installation. This prevents version skew between the ACN caller and the inference runtime.

### Process Supervision

The ICN spawns **exactly one** child process running `magnitude‑inference serve` within an [Effect](https://effect.website/) scope. It obtains a race-free loopback address and owns the entire child process lifetime. This ownership boundary is strict—no external process management is permitted.

### Generated Client Exposure

The ICN constructs the `IcnClient` from the OpenAPI contract in `@magnitudedev/icn-protocol` and exposes a scoped client whose streams preserve their response lifetime. ACN code accesses this through the `IcnProcess` service tag.

### Hardware Discovery and Calibration

The ICN discovers host inference hardware, runs calibration workers, and publishes calibrated **hardware facts**. These facts inform model placement decisions upstream in ACN.

### Model Catalog and Acquisition

The ICN owns four related duties:
- **Catalog** — reviewed model metadata
- **Discovery** — inventory of installed models
- **Catalog-installation** — downloading and verifying packages
- **Assessment** — running native planning pipelines to compute memory, performance, and capability footprints

### Model Instance Lifecycle

The ICN admits a model-free server, then manages **model instance** creation, replacement, stopping, and eviction. It handles leases, exposes progress via `ModelInstancesSnapshot`, and ensures inference requests hold valid leases before streaming begins.

### Health and Readiness

The ICN publishes `/health` and readiness records containing process identity, API version, and hardware calibration status. ACN uses these signals to determine when the ICN can accept work.

### Graceful Shutdown

On `SIGTERM`, the ICN initiates graceful shutdown with a ≤ 1 s deadline, then escalates to `SIGKILL` if needed. It closes all streams, cancels pending work, and cleans up the child process. This is implemented in the shutdown handler referenced by ACN.

### Observability

The ICN emits structured logs and tracing spans for process start, exit, health checks, model loading, and shutdown. It maintains a bounded diagnostic tail for debugging without unbounded memory growth.

### Boundary Enforcement

The ICN **never** exposes public listeners or client-side APIs for hardware, inventory, or native model loading. ACN is the sole consumer of the `IcnClient`. This isolation prevents unauthorized direct access to inference resources.

---

## How ACN Interacts with ICN Responsibilities

The following snippets from [`packages/acn/src/icn.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/icn.ts) and [`packages/acn/src/server.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/server.ts) demonstrate how ACN exercises ICN responsibilities through the generated client.

### Creating the ICN Provider

```typescript
// packages/acn/src/server.ts — bootstrap ICN into ACN service layer
import { makeIcnProvider } from "@magnitudedev/icn";

const acnServices = Layer.provideMerge(
  // ...other ACN layers...
  makeIcnProvider(),          // ← Injects scoped IcnClient
);

```

### Loading a Model and Obtaining a Lease

```typescript
// ACN service code acquiring a model instance
import { IcnProcess } from "@magnitudedev/icn";

const loadModel = Effect.gen(function* () {
  const icn = yield* IcnProcess;               // Scoped client from provider
  const lease = yield* icn.loadModel({         // Native model load
    modelId: "local/gguf/phi-2",
    // optional quantization, context length, etc.
  });
  // `lease` resolves when the inference stream completes
  return lease;
});

```

### Graceful Shutdown

```typescript
// ACN requesting ICN shutdown during its own teardown
import { IcnProcess } from "@magnitudedev/icn";

const shutdown = Effect.scoped(Effect.gen(function* () {
  const icn = yield* IcnProcess;
  // Sends SIGTERM, waits grace period, then SIGKILL if needed
  yield* icn.shutdown;
}));

```

---

## Key Source Files for ICN Responsibilities

| File | Relevance |
|------|-----------|
| [`design/icn/lifecycle.md`](https://github.com/magnitudedev/magnitude/blob/main/design/icn/lifecycle.md) | Complete specification of ICN responsibilities, ownership model, and state machine |
| [`packages/acn/src/server.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/server.ts) | ACN bootstrap code that calls `makeIcnProvider()` |
| [`packages/acn/src/icn.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn/src/icn.ts) | Implementation of `makeIcnProvider`, `IcnProcess`, and lifetime management |
| `packages/icn-protocol/src/generated/` | OpenAPI-generated `IcnClient` types and operations |
| [`design/model-management/instance-lifecycle.md`](https://github.com/magnitudedev/magnitude/blob/main/design/model-management/instance-lifecycle.md) | Model instance state machine that ICN implements |
| [`info/inference/parity.md`](https://github.com/magnitudedev/magnitude/blob/main/info/inference/parity.md) | ICN usage for parity testing against reference implementations |

---

## Summary

- The **ICN** is the private, process-scoped inference authority inside each ACN, implemented by `@magnitudedev/icn`.
- It handles **binary verification**, **process supervision**, **hardware calibration**, **model catalog/discovery/assessment**, and **instance lifecycle management**.
- ACN consumes ICN capabilities through a **generated `IcnClient`** obtained via `makeIcnProvider()` and the `IcnProcess` service tag.
- Strict **boundary enforcement** prevents external access to hardware and model APIs—ACN is the sole client.
- **Graceful shutdown**, **health/readiness signaling**, and **observability** ensure production-hardened operation.

---

## Frequently Asked Questions

### What is the relationship between ICN and ACN in Magnitude?

The ICN runs as a child process inside an ACN. ACN is the public-facing orchestrator that handles user sessions, cloud routing, and policy decisions. It delegates all native inference work—model loading, hardware discovery, request execution—to the ICN through a private generated client. This separation keeps the inference runtime isolated and version-locked to the ACN that spawned it.

### How does the ICN handle model loading and leasing?

The ICN manages a **model instance lifecycle**: it admits a model-free server, then creates instances on demand. Each load request returns a **lease**—an Effect that represents the right to stream inference from that instance. The ICN evicts or replaces instances based on memory pressure and policy, publishing state via `ModelInstancesSnapshot`. Inference requests must hold valid leases before streaming begins.

### Is the ICN accessible outside the ACN process?

**No.** The ICN deliberately enforces a strict boundary: it binds to a race-free loopback address and never exposes public listeners. The `@magnitudedev/icn-protocol` client is only distributed within the ACN package graph. External consumers must route through ACN's public API, which proxies or policy-gates all inference requests.

### What happens when an ICN receives a shutdown signal?

The ICN implements a two-phase shutdown: on `SIGTERM`, it stops accepting new work, waits up to 1 second for active streams to complete, then escalates to `SIGKILL` if the process has not exited. All streams are closed, pending work is cancelled, and the `magnitude‑inference` child process is reaped. ACN triggers this during its own teardown sequence.