simulator/src

Code-first simulator API.

simulator/src

packages/simulator/src

Purpose

Code-first simulator API.

Public surface

AgentConnection

Interface

export interface AgentConnection<Name extends string = string> {
  readonly agent: AgentHandle<Name>;
  readonly key: AgentKey;
  readonly routerUrl: ServerBaseUrl;
}

Runtime connection issued by every router implementation. It carries the credential and address a runtime dials; each runtime chooses its own startup deadline and owns whatever readiness evidence its process exposes.

AgentHandle

Class

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.

AgentProcessExited

Class

export class AgentProcessExited extends Schema.TaggedClass<AgentProcessExited>()(
  "moltzap.agent-process-exited/v1",
  {
    agentName: agentName,
    agentId: agentId,
    runtime: Schema.NonEmptyString,
    code: Schema.NonNegativeInt,
  },
) {}

A roster runtime process terminated with an operating-system exit code.

AgentProcessSignaled

Class

export class AgentProcessSignaled extends Schema.TaggedClass<AgentProcessSignaled>()(
  "moltzap.agent-process-signaled/v1",
  {
    agentName: agentName,
    agentId: agentId,
    runtime: Schema.NonEmptyString,
    signal: Schema.NonEmptyString,
  },
) {}

A roster runtime process terminated because it received a signal.

AgentRuntimeCompleted

Class

export class AgentRuntimeCompleted extends Schema.TaggedClass<AgentRuntimeCompleted>()(
  "moltzap.agent-runtime-completed/v1",
  {
    agentName: agentName,
    agentId: agentId,
    runtime: Schema.NonEmptyString,
  },
) {}

An autonomous runtime completed normally.

AgentRuntimeFailed

Class

export class AgentRuntimeFailed extends Schema.TaggedClass<AgentRuntimeFailed>()(
  "moltzap.agent-runtime-failed/v1",
  {
    agentName: agentName,
    agentId: agentId,
    runtime: Schema.NonEmptyString,
    cause: Schema.NonEmptyString,
  },
) {}

An autonomous runtime completed with a recorded failure.

AgentRuntimeReady

Class

export class AgentRuntimeReady extends Schema.TaggedClass<AgentRuntimeReady>()(
  "moltzap.agent-runtime-ready/v1",
  {
    agentName: agentName,
    agentId: agentId,
    runtime: Schema.NonEmptyString,
  },
) {}

A roster runtime has acquired its identity and completed readiness.

AgentRuntimeStartFailed

Class

export class AgentRuntimeStartFailed extends Schema.TaggedClass<AgentRuntimeStartFailed>()(
  "moltzap.agent-runtime-start-failed/v1",
  {
    agentName: agentName,
    runtime: Schema.NonEmptyString,
    cause: Schema.NonEmptyString,
  },
) {}

A roster runtime failed before it established readiness.

ClusterError

Class

export class ClusterError extends Data.TaggedError("ClusterError")<{
  readonly detail: string;
}> {
  override get message(): string {
    return this.detail;
  }
}

Cluster loss that ends a run without exposing its backend.

ClusterLost

Class

export class ClusterLost<
  Definitions extends Readonly<Record<string, AgentRuntimeLike>>,
> extends Data.TaggedClass("ClusterLost")<{
  readonly cause: Cause.Cause<SimulatorRunFailure<Definitions>>;
  readonly receipt: LedgerReceipt;
}> {}

Post-allocation cluster error plus all durable evidence retained.

ClusterServices

TypeAlias

export type ClusterServices = LedgerStorage | RouterProvider | Cluster;

Opaque service set supplied by a local-Kubernetes or GKE Layer.

CompletedLedgerReceipt

Class

export class CompletedLedgerReceipt extends Schema.TaggedClass<CompletedLedgerReceipt>()(
  "CompletedLedgerReceipt",
  {
    ledger: ledgerRef,
    completion: LedgerCompletion,
  },
) {}

Physical receipt for a ledger whose completion marker is durable.

ConversationAddress

Class

export class ConversationAddress {
  readonly [conversationAddressTypeId] = conversationAddressTypeId;

  readonly conversationId: ConversationId;
  readonly participants: ConversationParticipants;

  private constructor(
    conversationId: ConversationId,
    participants: ConversationParticipants,
  ) {
    this.conversationId = conversationId;
    this.participants = participants;
  }

  static [conversationAddressConstruction](
    conversationId: ConversationId,
    participants: ConversationParticipants,
  ): ConversationAddress {
    return new ConversationAddress(conversationId, participants);
  }
}

A participant-independent network address. Binding an endpoint produces a conversation socket; the address itself never implies a sender.

ConversationOpened

Class

export class ConversationOpened extends Schema.TaggedClass<ConversationOpened>()(
  "moltzap.conversation-opened/v1",
  {
    openedBy: agentId,
    conversationId: conversationId,
    participants: Schema.NonEmptyArray(agentId),
  },
) {}

A participant allocated a conversation address for a nonempty group.

ConversationParticipants

TypeAlias

export type ConversationParticipants = readonly [
  ParticipantHandle,
  ...(readonly ParticipantHandle[]),
];

Every conversation has at least one participant of any network role.

ConversationSocket

Class

export class ConversationSocket {
  readonly [conversationSocketTypeId] = conversationSocketTypeId;

  /**
   * The ordered receive cursor for this endpoint and conversation. Repeated
   * consumption advances the cursor instead of replaying old delivery.
   */
  readonly messages: Stream.Stream<ReceivedMessage, NetworkError>;

  readonly endpoint: ParticipantHandle;
  readonly address: ConversationAddress;
  private readonly sendMessage: (
    content: MessageParts,
  ) => Effect.Effect<Message, NetworkError>;

  private constructor(
    endpoint: ParticipantHandle,
    address: ConversationAddress,
    messages: Stream.Stream<ReceivedMessage, NetworkError>,
    sendMessage: (
      content: MessageParts,
    ) => Effect.Effect<Message, NetworkError>,
  ) {
    this.endpoint = endpoint;
    this.address = address;
    this.sendMessage = sendMessage;
    this.messages = messages;
  }

  static [conversationSocketConstruction](
    endpoint: ParticipantHandle,
    address: ConversationAddress,
    messages: Stream.Stream<ReceivedMessage, NetworkError>,
    sendMessage: (
      content: MessageParts,
    ) => Effect.Effect<Message, NetworkError>,
  ): ConversationSocket {
    return new ConversationSocket(endpoint, address, messages, sendMessage);
  }

  /**
   * Commit one message through the bound endpoint.
   * @param content Value supplied to the operation.
   * @returns The created conversation socket.
   */
  send(content: string | MessageParts): Effect.Effect<Message, NetworkError> {
    return validateParts(parts(content)).pipe(Effect.flatMap(this.sendMessage));
  }

  /**
   * Receive the next ordered delivery. Selection policy belongs in the
   * consuming Effect, so the socket never skips an earlier message.
   * @returns The created conversation socket.
   */
  receive(): Effect.Effect<ReceivedMessage, NetworkError> {
    return this.messages.pipe(
      Stream.runHead,
      Effect.flatMap(
        Option.match({
          onNone: () =>
            Effect.fail(
              networkError(
                "receive",
                `conversation ${this.address.conversationId} ended before another message arrived`,
              ),
            ),
          onSome: Effect.succeed,
        }),
      ),
    );
  }
}

A conversation address bound to exactly one controlled endpoint.

coreEvents

Variable

export const coreEvents = EventCatalog.merge(
  runEvents,
  routerEvents,
  runtimeEvents,
  endpointEvents,
  linkEvents,
)

The exact event classes readable from every simulator run ledger.

CustomerEvents

Interface

export interface CustomerEvents<Catalog extends AnyEventCatalog> {
  readonly emit: (
    event: EventOf<Catalog>,
    metadata?: EventMetadata,
  ) => Effect.Effect<LedgerRecord<Catalog>, LedgerFailure>;
}

Definition-bound emission of customer-owned event classes only.

EncodedEventOf

TypeAlias

export type EncodedEventOf<Catalog> = Schema.Schema.Encoded<
  CatalogSchemaOf<Catalog>
>;

The closed encoded union persisted for a catalog.

Endpoint

Class

export class Endpoint<Name extends string = string> {
  readonly [endpointTypeId] = endpointTypeId;

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

  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);
  }

  /**
   * Observe messages delivered after this stream is subscribed. Conversation
   * sockets retain their own ordered delivery queues independently.
   * @returns Live endpoint delivery stream.
   */
  messages(): Stream.Stream<ReceivedMessage, NetworkError> {
    return this.inbox.messages;
  }

  /**
   * Open a conversation through this endpoint's ordinary protocol attachment.
   * The opener is included in the resulting address automatically.
   * @param participants Nonempty addressed participant set.
   * @returns A conversation socket bound to this endpoint.
   */
  open(
    ...participants: ConversationParticipants
  ): Effect.Effect<ConversationSocket, NetworkError> {
    const [first, ...rest] = participants;
    const ids: ParticipantIds = [
      first.id,
      ...rest.map((participant) => participant.id),
    ];
    const addressed = addressedParticipants(this.participant, participants);
    return this.transport.openConversation(ids).pipe(
      Effect.flatMap((opened) =>
        this.inbox.conversation(opened.conversationId).pipe(
          Effect.map((messages) => ({
            messages,
            opened,
          })),
        ),
      ),
      Effect.map(({ messages, opened }) => {
        const address = makeConversationAddress(
          opened.conversationId,
          addressed,
        );
        return makeConversationSocket(
          this.participant,
          address,
          messages,
          (content) => this.transport.send(address.conversationId, content),
        );
      }),
    );
  }

  /**
   * Bind this endpoint as the sender for an existing address.
   * @param address Participant-independent conversation address.
   * @returns Endpoint-bound socket when this endpoint is addressed.
   */
  socket(
    address: ConversationAddress,
  ): Effect.Effect<ConversationSocket, NetworkError> {
    const isParticipant = address.participants.some(
      (participant) => participant.id === this.participant.id,
    );
    return isParticipant
      ? this.inbox
          .conversation(address.conversationId)
          .pipe(
            Effect.map((messages) =>
              makeConversationSocket(
                this.participant,
                address,
                messages,
                (content) =>
                  this.transport.send(address.conversationId, content),
              ),
            ),
          )
      : Effect.fail(
          networkError(
            "socket",
            `participant ${this.participant.name} is not addressed by the conversation`,
          ),
        );
  }
}

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

EndpointMessageReceived

Class

export class EndpointMessageReceived extends Schema.TaggedClass<EndpointMessageReceived>()(
  "moltzap.endpoint-message-received/v1",
  {
    endpointId: agentId,
    conversationId: conversationId,
    messageId: messageId,
    senderId: agentId,
    parts: messageParts,
  },
) {}

A controlled endpoint received a message through the data plane.

EndpointMessageSent

Class

export class EndpointMessageSent extends Schema.TaggedClass<EndpointMessageSent>()(
  "moltzap.endpoint-message-sent/v1",
  {
    endpointId: agentId,
    conversationId: conversationId,
    messageId: messageId,
    parts: messageParts,
  },
) {}

A controlled endpoint committed a message through the data plane.

EventCatalog

Class

export class EventCatalog<
  SchemaType extends CatalogSchema,
  Classes extends EventClass = EventClass,
> {
  readonly schema: Schema.Schema<
    Schema.Schema.Type<SchemaType>,
    Schema.Schema.Encoded<SchemaType>
  >;
  readonly eventClasses: readonly EventClass[];
  readonly tags: readonly VersionedEventTag[];
  private readonly [eventCatalogTypeId] = eventCatalogTypeId;

  private constructor(schema: SchemaType, eventClasses: readonly EventClass[]) {
    this.schema = Schema.make<
      Schema.Schema.Type<SchemaType>,
      Schema.Schema.Encoded<SchemaType>
    >(schema.ast);
    this.eventClasses = Object.freeze([...eventClasses]);
    this.tags = Object.freeze(
      this.eventClasses.map((eventClass) => eventClass._tag),
    );
    Object.freeze(this);
  }

  static make<
    const EventClasses extends readonly [
      EventClass,
      ...(readonly EventClass[]),
    ],
  >(
    ...eventClasses: EventClasses
  ): EventCatalog<EventClassesSchema<EventClasses>, EventClasses[number]> {
    validateEventClasses(eventClasses);
    return new EventCatalog(makeEventClassesSchema(eventClasses), eventClasses);
  }

  static empty(): EventCatalog<Schema.Schema<never>, never> {
    const eventClasses: readonly never[] = [];
    return new EventCatalog(Schema.make<never>(Schema.Never.ast), eventClasses);
  }

  static merge<
    const Catalogs extends readonly [
      EventCatalog<CatalogSchema>,
      ...ReadonlyArray<EventCatalog<CatalogSchema>>,
    ],
  >(
    ...catalogs: Catalogs
  ): EventCatalog<
    MergedCatalogSchema<Catalogs>,
    CatalogClassesOf<Catalogs[number]>
  > {
    const eventClasses = catalogs.flatMap((catalog) => catalog.eventClasses);
    validateEventClasses(eventClasses);
    return new EventCatalog(mergeCatalogSchemas(catalogs), eventClasses);
  }

  has(eventClass: EventClass): eventClass is Classes {
    return this.eventClasses.some(
      (catalogEventClass) => catalogEventClass === eventClass,
    );
  }

  hasEvent(event: unknown): event is Schema.Schema.Type<SchemaType> {
    if (typeof event !== "object" || event === null) {
      return false;
    }
    const constructor: unknown = Reflect.get(event, "constructor");
    return this.eventClasses.some((eventClass) => eventClass === constructor);
  }

  decode(input: unknown) {
    return Schema.decodeUnknown(Schema.asSchema(this.schema))(input, {
      onExcessProperty: "error",
    });
  }

  encode(event: Schema.Schema.Type<SchemaType>) {
    return Schema.encode(Schema.asSchema(this.schema))(event, {
      onExcessProperty: "error",
    });
  }
}

The exact immutable event universe for one definition.

The private type identifier makes catalog arguments nominal: a structural object cannot claim a schema, constructor list, and tag list that disagree.

EventCatalogDefinitionError

Class

export class EventCatalogDefinitionError extends Schema.TaggedError<EventCatalogDefinitionError>()(
  "EventCatalogDefinitionError",
  {
    failure: Schema.Literal("duplicate-tag", "invalid-tag"),
    tag: Schema.String,
  },
) {
  override get message(): string {
    return definitionFailureMessage[this.failure](this.tag);
  }
}

Invalid catalogs fail during definition construction, before a run starts.

EventCatalogDefinitionFailure

TypeAlias

export type EventCatalogDefinitionFailure = "duplicate-tag" | "invalid-tag";

Represents event catalog definition failure conditions.

EventClass

TypeAlias

export type EventClass = Schema.Schema.AnyNoContext & {
  readonly _tag: VersionedEventTag;
};

A schema-backed event constructor. The catalog retains both the schema and constructor faces so persisted values decode back into their exact class.

EventClassOf

TypeAlias

export type EventClassOf<Catalog> = CatalogClassesOf<Catalog>;

The closed constructor union declared by a catalog.

EventMetadata

Interface

export interface EventMetadata {
  readonly causationId?: string;
  readonly correlationId?: string;
}

Causality metadata accepted from a customer event producer.

EventOf

TypeAlias

export type EventOf<Catalog> = Schema.Schema.Type<CatalogSchemaOf<Catalog>>;

The closed instance union declared by a catalog.

IncompleteLedgerReceipt

Class

export class IncompleteLedgerReceipt extends Schema.TaggedClass<IncompleteLedgerReceipt>()(
  "IncompleteLedgerReceipt",
  {
    ledger: ledgerRef,
  },
) {}

Physical receipt retained when ledger completion could not be published.

isEntryModule

Function

export function isEntryModule(moduleUrl: string, invoked?: string): boolean

Whether a module is the process entry point rather than an ordinary import.

Both sides are canonicalized because they are not the same kind of path: Node resolves a module’s real path before it becomes import.meta.url, while process.argv[1] is whatever the caller typed. Every executable in this package reaches its module through a symlink in the controller image, where /opt/moltzap/dist points at the installed package directory. Comparing the two without canonicalizing makes a directly invoked entry point look like an import, so the process exits successfully having done nothing.

realPath returns undefined for a path that does not exist, so a missing or deleted argv[1] is a plain false rather than a thrown ENOENT.

Returns: Whether both locations name the same real file.

LedgerFailure

TypeAlias

export type LedgerFailure =
  | LedgerStorageError
  | ParseResult.ParseError
  | LedgerSerializationError;

Represents ledger failure conditions.

LedgerReceipt

TypeAlias

export type LedgerReceipt = typeof LedgerReceipt.Type;

Decoded physical ledger receipt.

LedgerReceipt

Variable

export const LedgerReceipt = Schema.Union(
  CompletedLedgerReceipt,
  IncompleteLedgerReceipt,
)

Schema for the complete physical ledger-receipt universe.

LinkController

Class

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

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

LinkControllerService

Interface

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

Interface

export interface LinkDelivery {
  /** Message sender identity. */
  readonly from: AgentId;
  /** Receiving participant identity. */
  readonly to: AgentId;
  /** Router message carried by the delivery. */
  readonly message: Message;
}

One committed message about to cross a directed link.

LinkDown

Class

export class LinkDown extends Schema.TaggedClass<LinkDown>()(
  "moltzap.link-down/v1",
  {
    from: agentId,
    to: agentId,
  },
) {}

A directed participant link transitioned from available to unavailable.

LinkMessageDelayed

Class

export class LinkMessageDelayed extends Schema.TaggedClass<LinkMessageDelayed>()(
  "moltzap.link-message-delayed/v1",
  {
    from: agentId,
    to: agentId,
    conversationId: conversationId,
    messageId: messageId,
    delayMillis: Schema.NonNegative,
  },
) {}

Active link policies deferred one delivery by a known total duration.

LinkMessageDropped

Class

export class LinkMessageDropped extends Schema.TaggedClass<LinkMessageDropped>()(
  "moltzap.link-message-dropped/v1",
  {
    from: agentId,
    to: agentId,
    conversationId: conversationId,
    messageId: messageId,
    reason: Schema.optional(Schema.String),
  },
) {}

An active link policy discarded one committed message before delivery.

LinkMessageHeld

Class

export class LinkMessageHeld extends Schema.TaggedClass<LinkMessageHeld>()(
  "moltzap.link-message-held/v1",
  {
    from: agentId,
    to: agentId,
    conversationId: conversationId,
    messageId: messageId,
  },
) {}

An active link policy parked one delivery until its lease clears.

linkPolicy

Variable

export const linkPolicy:

Canonical link policies for the common traffic shapes.

LinkPolicy

TypeAlias

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.

LinkPolicyCleared

Class

export class LinkPolicyCleared extends Schema.TaggedClass<LinkPolicyCleared>()(
  "moltzap.link-policy-cleared/v1",
  {
    from: agentId,
    to: agentId,
    policy: Schema.NonEmptyString,
  },
) {}

A described policy stopped shaping one directed participant link.

LinkPolicySet

Class

export class LinkPolicySet extends Schema.TaggedClass<LinkPolicySet>()(
  "moltzap.link-policy-set/v1",
  {
    from: agentId,
    to: agentId,
    policy: Schema.NonEmptyString,
  },
) {}

A described policy became active on one directed participant link.

LinkUp

Class

export class LinkUp extends Schema.TaggedClass<LinkUp>()("moltzap.link-up/v1", {
  from: agentId,
  to: agentId,
}) {}

A directed participant link transitioned from unavailable to available.

linkVerdict

Variable

export const linkVerdict = Data.taggedEnum<LinkVerdict>()

Constructors and matchers for the closed verdict union.

LinkVerdict

TypeAlias

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.

MessageParts

TypeAlias

export type MessageParts = Schema.Schema.Type<typeof messagePartsSchemaValue>;

Nonempty protocol message content.

Network

Class

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

Network operations available to the customer program.

NetworkError

Class

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 network boundary.

NetworkService

Interface

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

Controlled endpoint operations installed for one run scope.

ParticipantHandle

Class

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 router-issued network identity. The hidden symbol prevents structurally similar protocol data from being used as an identity handle.

ProgramFailed

Class

export class ProgramFailed extends Schema.TaggedClass<ProgramFailed>()(
  "moltzap.program-failed/v1",
  {
    cause: Schema.NonEmptyString,
  },
) {}

The customer program failed with a typed failure or defect.

ProgramFinished

Class

export class ProgramFinished<A, E> extends Data.TaggedClass("ProgramFinished")<{
  readonly exit: Exit.Exit<A, E>;
  readonly receipt: CompletedLedgerReceipt;
}> {}

Customer-program completion plus its complete durable evidence.

ProgramInterrupted

Class

export class ProgramInterrupted extends Schema.TaggedClass<ProgramInterrupted>()(
  "moltzap.program-interrupted/v1",
  {
    cause: Schema.NonEmptyString,
  },
) {}

The customer program was interrupted.

ProgramSucceeded

Class

export class ProgramSucceeded extends Schema.TaggedClass<ProgramSucceeded>()(
  "moltzap.program-succeeded/v1",
  {},
) {}

The customer program returned successfully.

ReadableRunLedger

Interface

export interface ReadableRunLedger<Catalog extends AnyEventCatalog> {
  readonly ref: LedgerRef;
  readonly manifest: LedgerManifest;
  readonly records: Stream.Stream<LedgerRecord<Catalog>, LedgerFailure>;
  readonly events: <Event extends EventClassOf<Catalog>>(
    eventClass: Event,
  ) => Stream.Stream<Schema.Schema.Type<Event>, LedgerFailure>;
}

Definition-bound read access to every committed core and customer event.

ReceivedMessage

Interface

export interface ReceivedMessage {
  readonly message: Message;
}

A message delivered to one attached endpoint.

RouterMessageCommitted

Class

export class RouterMessageCommitted extends Schema.TaggedClass<RouterMessageCommitted>()(
  "moltzap.router-message-committed/v1",
  {
    ...CommittedRouterMessage.fields,
  },
) {}

The router durably committed one message, plaintext parts included.

RouterStarted

Class

export class RouterStarted extends Schema.TaggedClass<RouterStarted>()(
  "moltzap.router-started/v1",
  {
    routerUrl: serverBaseUrlSchema,
  },
) {}

The run-scoped router is accepting participant connections.

RouterStartFailed

Class

export class RouterStartFailed extends Schema.TaggedClass<RouterStartFailed>()(
  "moltzap.router-start-failed/v1",
  {
    cause: Schema.NonEmptyString,
  },
) {}

Router acquisition failed before the data plane became available.

RouterStopFailed

Class

export class RouterStopFailed extends Schema.TaggedClass<RouterStopFailed>()(
  "moltzap.router-stop-failed/v1",
  {
    cause: Schema.NonEmptyString,
  },
) {}

Router release or stopped-router evidence collection failed.

Run

Variable

export const Run: Readonly<{ execute: typeof executeRunSpec }> = Object.freeze({
  execute: executeRunSpec,
})

Discoverable execution entry point for one experiment society.

RunSpec

Interface

export interface RunSpec<
  Id extends SimulatorDefinitionId = SimulatorDefinitionId,
  CustomerCatalogs extends
    readonly AnyEventCatalog[] = readonly AnyEventCatalog[],
  Definitions extends Readonly<Record<string, AgentRuntimeLike>> = Readonly<
    Record<string, AgentRuntimeLike>
  >,
  A = unknown,
  E = unknown,
  R = never,
  ClusterLayer extends Layer.Layer<
    never,
    unknown,
    unknown
  > = Layer.Layer<ClusterServices>,
> {
  /**
   * Present only on the exact values RunSpec.define produced, and carrying
   * their runner. This is the one identity gate: nothing structural
   * distinguishes a definition from a lookalike, and a lookalike has no
   * runner to invoke.
   */
  readonly [runSpecTypeId]?: () => RunSpecExecution<
    Id,
    CustomerCatalogs,
    Definitions,
    A,
    E,
    R,
    ClusterLayer
  >;
  readonly id: Id;
  readonly events: CustomerCatalogs;
  readonly agents: Definitions;
  readonly cluster: ClusterLayer &
    Layer.Layer<
      ClusterServices,
      Layer.Layer.Error<ClusterLayer>,
      Layer.Layer.Context<ClusterLayer>
    >;
  readonly execute: (
    context: RunExecutionContext<Id, CustomerCatalogs, Definitions>,
  ) => Effect.Effect<A, E, R>;
}

Immutable code-first definition of one experiment society.

RunSpec

Variable

export const RunSpec: Readonly<{ define: typeof defineRunSpec }> =
  Object.freeze({ define: defineRunSpec })

Discoverable constructor for immutable experiment definitions.

RunStarted

Class

export class RunStarted extends Schema.TaggedClass<RunStarted>()(
  "moltzap.run-started/v1",
  {
    definitionId: Schema.NonEmptyString,
  },
) {}

The run ledger is allocated and run-scoped acquisition has begun.

SimulatorDefinitionError

Class

export class SimulatorDefinitionError extends Schema.TaggedError<SimulatorDefinitionError>()(
  "SimulatorDefinitionError",
  {
    definitionId: Schema.String,
    detail: Schema.NonEmptyString,
  },
) {
  override get message(): string {
    return `Simulator definition "${this.definitionId}" is invalid: ${this.detail}`;
  }
}

Reports simulator definition failures.

SimulatorDefinitionId

TypeAlias

export type SimulatorDefinitionId = `${string}.${string}/v${number}`;

Stable code identity persisted in every ledger manifest.

SimulatorRunFailure

TypeAlias

export type SimulatorRunFailure<
  Definitions extends Readonly<Record<string, AgentRuntimeLike>>,
> =

Represents simulator run failure conditions.

SimulatorRunOutcome

TypeAlias

export type SimulatorRunOutcome<
  A,
  E,
  Definitions extends Readonly<Record<string, AgentRuntimeLike>>,
> = ProgramFinished<A, E> | ClusterLost<Definitions>;

Closed result of every run whose ledger allocation succeeded.

VersionedEventTag

TypeAlias

export type VersionedEventTag = `${string}.${string}/v${number}`;

Stable persisted identity for an event class.

Files

• cluster.ts
• entry.ts
• definition.ts
• catalog.ts
• core.ts
• append.ts
• conversation.ts
• endpoint.ts
• failure.ts
• link.ts
• participant.ts
• router.ts
• events.ts
• execute.ts