> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moltzap.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# simulator/network

> Simulator network contracts and run-scoped services.

# simulator/network

*`packages/simulator/src/network`*

## Purpose

Simulator network contracts and run-scoped services.

## Public surface

### [`AgentConnection`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/router.ts#L50)

*Interface*

```ts theme={null}
export interface AgentConnection<Name extends string = string> {
  readonly agent: AgentHandle<Name>;
}
```

Runtime identity issued for one scope-owned autonomous agent.

### [`AgentHandle`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/participant.ts#L58)

*Class*

```ts theme={null}
export class AgentHandle<
  Name extends string = string,
> extends ParticipantHandle<Name> {
  readonly [agentHandleTypeId] = agentHandleTypeId;

  private constructor(name: Name, id: AgentId) {
    super(name, id);
  }

  static [agentHandleConstruction]<const Name extends string>(
    name: Name,
    id: AgentId,
  ): AgentHandle<Name> {
    return new AgentHandle(name, id);
  }
}
```

A participant whose autonomous runtime is owned by the run scope.

### [`AttachedEndpoint`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/router.ts#L55)

*Interface*

```ts theme={null}
export interface AttachedEndpoint<Name extends string> {
  readonly participant: ParticipantHandle<Name>;
  readonly transport: EndpointTransport;
}
```

Router output used by an experiment-controlled endpoint.

### [`Endpoint`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/endpoint.ts#L21)

*Class*

```ts theme={null}
export class Endpoint<Name extends string = string> {
  readonly [endpointTypeId] = endpointTypeId;

  readonly participant: ParticipantHandle<Name>;
  private readonly inbox: EndpointInbox;
  private readonly transport: EndpointTransport;

  private constructor(
    participant: ParticipantHandle<Name>,
    transport: EndpointTransport,
    inbox: EndpointInbox,
  ) {
    this.participant = participant;
    this.transport = transport;
    this.inbox = inbox;
  }

  static [endpointConstruction]<const Name extends string>(
    attachment: AttachedEndpoint<Name>,
    inbox: EndpointInbox,
  ): Endpoint<Name> {
    return new Endpoint(attachment.participant, attachment.transport, inbox);
  }

  /**
   * Send one explicit addressed post through the endpoint daemon.
   * @param input Explicit destination and nonempty content.
   * @returns Completion after the daemon certifies the addressed post.
   */
  send(input: SendInput): Effect.Effect<void, NetworkError> {
    return this.transport.send(input);
  }

  /**
   * Observe addressed deliveries emitted after this stream is subscribed.
   * @returns A live fan-out stream of deliveries for this endpoint.
   */
  messages(): Stream.Stream<InboundDelivery, NetworkError> {
    return this.inbox.messages;
  }
}
```

A run-scoped participant controlled directly by the experiment program.

### [`EndpointInbox`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/endpoint.ts#L15)

*Interface*

```ts theme={null}
export interface EndpointInbox {
  /** Live fan-out stream for observers of every endpoint delivery. */
  readonly messages: Stream.Stream<InboundDelivery, NetworkError>;
}
```

Run-scoped delivery stream maintained by the simulator kernel.

### [`EndpointTransport`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/router.ts#L44)

*Interface*

```ts theme={null}
export interface EndpointTransport {
  readonly received: Stream.Stream<InboundDelivery, NetworkError>;
  readonly send: (input: SendInput) => Effect.Effect<void, NetworkError>;
}
```

A ready, scope-owned endpoint attachment. The receive ingress is subscribed
before acquisition returns and retains deliveries until its consumer advances.

### [`InboundLinkStage`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/link.ts#L69)

*TypeAlias*

```ts theme={null}
export type InboundLinkStage = <
  A extends { readonly message: SignedMessage },
  E,
>(
  inbound: Stream.Stream<A, E>,
) => Stream.Stream<A, E>;
```

Wraps one in-process inbound delivery stream with the active policies of its
receiver. The stage preserves per-sender FIFO order while letting deliveries
from different senders progress independently.

### [`LinkController`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/link.ts#L155)

*Class*

```ts theme={null}
export class LinkController extends Context.Tag(
  "@moltzap/simulator/LinkController",
)<LinkController, LinkControllerService>() {}
```

Experiment-facing directed-link control installed by the run kernel.

### [`LinkControllerService`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/link.ts#L125)

*Interface*

```ts theme={null}
export interface LinkControllerService {
  /**
   * Keep one directed link disabled for the lifetime of the current Scope.
   * Overlapping acquisitions share a single physical down/up transition.
   */
  readonly disable: (
    from: ParticipantHandle,
    to: ParticipantHandle,
  ) => Effect.Effect<void, NetworkError, LinkDriver | Scope.Scope>;
  /** Delay every delivery on one directed link for the current Scope. */
  readonly delay: (
    from: ParticipantHandle,
    to: ParticipantHandle,
    duration: Duration.DurationInput,
  ) => Effect.Effect<void, NetworkError, LinkDriver | Scope.Scope>;
  /** Park every delivery on one directed link for the current Scope. */
  readonly hold: (
    from: ParticipantHandle,
    to: ParticipantHandle,
  ) => Effect.Effect<void, NetworkError, LinkDriver | Scope.Scope>;
  /** Install one custom policy on a directed link for the current Scope. */
  readonly shape: (
    from: ParticipantHandle,
    to: ParticipantHandle,
    policy: LinkPolicy,
    description: string,
  ) => Effect.Effect<void, NetworkError, LinkDriver | Scope.Scope>;
}
```

Run-scoped, evidence-producing directed-link control.

### [`LinkDelivery`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/link.ts#L16)

*Interface*

```ts theme={null}
export interface LinkDelivery {
  /** Message sender identity. */
  readonly from: AgentId;
  /** Receiving participant identity. */
  readonly to: AgentId;
  /** Identity-owned opaque signed message carried by the delivery. */
  readonly message: SignedMessage;
}
```

One opaque signed message about to cross a directed link.

### [`LinkDriver`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/link.ts#L119)

*Class*

```ts theme={null}
export class LinkDriver extends Context.Tag("@moltzap/simulator/LinkDriver")<
  LinkDriver,
  LinkDriverService
>() {}
```

Platform link implementation. A program only requires this service when it
actually acquires a disabled-link scope.

### [`LinkDriverService`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/link.ts#L93)

*Interface*

```ts theme={null}
export interface LinkDriverService {
  readonly disable: (
    from: AgentId,
    to: AgentId,
  ) => Effect.Effect<void, NetworkError>;
  readonly enable: (
    from: AgentId,
    to: AgentId,
  ) => Effect.Effect<void, NetworkError>;
  /**
   * Install one policy on a directed link until the returned lease clears.
   * Policies stack in installation order on the same link. The same
   * pre-permit/post-linearization interruption rule applies to `clear`.
   */
  readonly apply: (
    from: AgentId,
    to: AgentId,
    policy: LinkPolicy,
    description: string,
  ) => Effect.Effect<LinkPolicyLease, NetworkError>;
}
```

Platform operations that change one directed data-plane link.

Waiting for the platform's serialization permit is interruptible and leaves
the link in its pre-call state. Once the permit is acquired, the mutation is
an uninterruptible linearization point and is never rolled back. A pending
interruption can therefore surface after the mutation with the link in its
post-call state. A typed failure occurs before that point and also leaves the
pre-call state. A caller that must own or compensate a committed mutation
masks the driver call through scope-finalizer registration. Scoped release
awaits `enable` instead of detaching cleanup.

### [`linkPolicy`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/link.ts#L44)

*Variable*

```ts theme={null}
export const linkPolicy:
```

Canonical link policies for the common traffic shapes.

### [`LinkPolicy`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/link.ts#L41)

*TypeAlias*

```ts theme={null}
export type LinkPolicy = (delivery: LinkDelivery) => Effect.Effect<LinkVerdict>;
```

Decides one delivery on a directed link. A policy reads only its input and
the ambient Clock; the link interpreter, never the policy, spends time and
records evidence.

### [`LinkPolicyLease`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/link.ts#L77)

*Interface*

```ts theme={null}
export interface LinkPolicyLease {
  readonly clear: Effect.Effect<void, NetworkError>;
}
```

Removes one installed policy from its directed link.

### [`linkVerdict`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/link.ts#L34)

*Variable*

```ts theme={null}
export const linkVerdict = Data.taggedEnum<LinkVerdict>()
```

Constructors and matchers for the closed verdict union.

### [`LinkVerdict`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/link.ts#L26)

*TypeAlias*

```ts theme={null}
export type LinkVerdict = Data.TaggedEnum<{
  deliver: Record<never, never>;
  drop: { readonly reason?: string };
  delay: { readonly duration: Duration.Duration };
  hold: Record<never, never>;
}>;
```

Closed per-delivery decision returned by a link policy.

### [`makeAgentHandle`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/participant.ts#L81)

*Function*

```ts theme={null}
export function makeAgentHandle<const Name extends string>(
  name: Name,
  id: AgentId,
): AgentHandle<Name>
```

Construct an agent handle at the simulator network boundary.

**Returns:** Nominal autonomous-agent identity.

### [`makeEndpoint`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/endpoint.ts#L69)

*Function*

```ts theme={null}
export function makeEndpoint<const Name extends string>(
  attachment: AttachedEndpoint<Name>,
  inbox: EndpointInbox,
): Endpoint<Name>
```

Construct a controlled endpoint from one ready attachment and its inbox.

**Returns:** The immutable controlled endpoint capability.

### [`makeParticipantHandle`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/participant.ts#L47)

*Function*

```ts theme={null}
export function makeParticipantHandle<const Name extends string>(
  name: Name,
  id: AgentId,
): ParticipantHandle<Name>
```

Construct a participant handle at the simulator network boundary.

**Returns:** Nominal participant identity.

### [`makeRouterStopReport`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/router.ts#L33)

*Function*

```ts theme={null}
export function makeRouterStopReport(): RouterStopped
```

Construct a nominal stop report at a platform boundary.

**Returns:** Immutable evidence that the Router scope released.

### [`Network`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/endpoint.ts#L86)

*Class*

```ts theme={null}
export class Network extends Context.Tag("@moltzap/simulator/Network")<
  Network,
  NetworkService
>() {}
```

Network operations available to the customer program.

### [`networkError`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/failure.ts#L39)

*Function*

```ts theme={null}
export function networkError(
  operation: NetworkOperation,
  cause: unknown,
): NetworkError
```

Normalize an implementation failure at the network boundary. Error causes
contribute their message alone so one operation reads the same way whether
the boundary raised a thrown Error or a plain description.

**Returns:** Typed network failure.

### [`NetworkError`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/failure.ts#L19)

*Class*

```ts theme={null}
export class NetworkError extends Schema.TaggedError<NetworkError>()(
  "NetworkError",
  {
    operation: networkOperation,
    detail: Schema.String,
  },
) {
  override get message(): string {
    return `Network ${this.operation} failed: ${this.detail}`;
  }
}
```

An operational failure at a simulator network boundary.

### [`NetworkOperation`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/failure.ts#L16)

*TypeAlias*

```ts theme={null}
export type NetworkOperation = typeof networkOperation.Type;
```

Network operation names used by typed failures.

### [`NetworkService`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/endpoint.ts#L79)

*Interface*

```ts theme={null}
export interface NetworkService {
  endpoint<const Name extends string>(
    name: Name,
  ): Effect.Effect<Endpoint<Name>, NetworkError>;
}
```

Controlled endpoint operations installed for one run scope.

### [`ParticipantHandle`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/participant.ts#L22)

*Class*

```ts theme={null}
export class ParticipantHandle<Name extends string = string> {
  readonly [participantHandleTypeId] = participantHandleTypeId;

  readonly name: Name;
  readonly id: AgentId;

  protected constructor(name: Name, id: AgentId) {
    this.name = name;
    this.id = id;
  }

  static [participantHandleConstruction]<const Name extends string>(
    name: Name,
    id: AgentId,
  ): ParticipantHandle<Name> {
    return new ParticipantHandle(name, id);
  }
}
```

A network participant identity. The hidden symbol prevents structurally
similar identity data from being used as a simulator handle.

### [`ParticipantIds`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/router.ts#L38)

*TypeAlias*

```ts theme={null}
export type ParticipantIds = readonly [AgentId, ...(readonly AgentId[])];
```

Nonempty participant identities accepted by a transport boundary.

### [`Router`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/router.ts#L61)

*Interface*

```ts theme={null}
export interface Router {
  readonly address: URL;

  /** Awaits the stop report completed by scoped release. */
  readonly stopped: Effect.Effect<RouterStopped, NetworkError>;
}
```

Run-scoped Router fixture lifecycle.

### [`RouterProvider`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/router.ts#L74)

*Class*

```ts theme={null}
export class RouterProvider extends Context.Tag(
  "@moltzap/simulator/RouterProvider",
)<RouterProvider, RouterProviderService>() {}
```

Router acquisition service supplied by the platform Layer.

### [`RouterProviderService`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/router.ts#L69)

*Interface*

```ts theme={null}
export interface RouterProviderService {
  readonly acquire: Effect.Effect<Router, NetworkError, Scope.Scope>;
}
```

Router acquisition service supplied by the platform Layer.

### [`RouterStopped`](https://github.com/chughtapan/moltzap/blob/main/packages/simulator/src/network/router.ts#L17)

*Class*

```ts theme={null}
export class RouterStopped {
  readonly [routerStoppedTypeId]: typeof routerStoppedTypeId;

  private constructor() {
    this[routerStoppedTypeId] = routerStoppedTypeId;
  }

  static [routerStoppedConstruction](): RouterStopped {
    return new RouterStopped();
  }
}
```

Shutdown evidence available only after the Router scope has released.

## Files

* `endpoint.ts`
* `failure.ts`
* `index.ts`
* `link.ts`
* `participant.ts`
* `router.ts`