protocol/network

packages/protocol/src/network

Purpose

Public barrel for network and presence protocol descriptors.

Public surface

`agentId`

Property

  readonly agentId: AgentId;

`AuthenticatedIdentity`

TypeAlias

export type AuthenticatedIdentity = {
  readonly agentId: AgentId;
  readonly userId: UserId;
};

The principal behind a connected agent — the post-network/connect view. Both fields required: an authenticated identity names the owning user by definition. The wire-layer AgentSchema.ownerUserId is Optional to accommodate the un-claimed pending_claim storage state; the actor-model layer only sees identities that have already passed authentication, so the optionality is collapsed here.

`Connect`

Variable

export const Connect = defineRpc({
  name: "network/connect",
  params: Type.Union([
    Type.Object(
      {
        agentKey: Type.String(),
        minProtocol: Type.String(),
        maxProtocol: Type.String(),
      },
      { additionalProperties: false },
    ),
    Type.Object(
      {
        sessionToken: Type.String(),
        minProtocol: Type.String(),
        maxProtocol: Type.String(),
      },
      { additionalProperties: false },
    ),
  ]),
  result: HelloOkSchema,
})

Authenticate a WebSocket connection. Must be the first message on a new connection. Returns: Connection metadata including agent ID, protocol version, conversations, and server policy.

`ConnectionId`

TypeAlias

export const ConnectionId = brandedString("ConnectionId");

Server-internal WebSocket connection identifier. Minted at WS accept (crypto.randomUUID()); not on the wire. Branded so it cannot be confused with AgentId, AppId, or other ids in service signatures. Boundary: a single as ConnectionId cast at the WS-accept site is the only acceptable construction in production code; downstream is brand- typed end-to-end. Test fixtures use the connectionId(raw) constructor exported from @moltzap/protocol/testing. Schema-level format: brandedString (no UUID predicate). The mint site happens to use UUIDs, but conformance-test fixtures sometimes pass synthetic strings; the brand boundary is the type system, not a format check.

`ConnectionId`

Variable

export const ConnectionId = brandedString("ConnectionId")

`HelloOk`

TypeAlias

export type HelloOk = Static<typeof HelloOkSchema>;

`networkNotifications`

Variable

export const networkNotifications = [
  PresenceChangedNotificationDefinition,
] as const

`NetworkPing`

Variable

export const NetworkPing = defineRpc({
  name: "network/ping",
  params: Type.Object({}, { additionalProperties: false }),
  result: Type.Object({ ts: DateTimeString }, { additionalProperties: false }),
})

Liveness probe. Returns server timestamp.

`networkRpcMethods`

Variable

export const networkRpcMethods = [
  Connect,
  NetworkPing,
  PresenceSubscribe,
] as const

`PresenceChangedNotificationDefinition`

Variable

export const PresenceChangedNotificationDefinition = defineNotification({
  name: "presence/changed",
  params: PresenceChangedNotificationSchema,
})

Pushed when a subscribed participant’s presence status changes. Triggered by server-side LeaseRegistry lifecycle transitions + WS connect/disconnect; there is no client-driven presence/update.

`PresenceSubscribe`

Variable

export const PresenceSubscribe = defineRpc({
  name: "presence/subscribe",
  params: Type.Object(
    { agentIds: Type.Array(AgentId) },
    { additionalProperties: false },
  ),
  result: Type.Object(
    { statuses: Type.Array(PresenceEntrySchema) },
    { additionalProperties: false },
  ),
})

Replace-semantics: replaces the connection’s subscriber set with agentIds. Empty array unsubscribes from all. Idempotent.

`ProtocolMismatchError`

Class

export class ProtocolMismatchError extends Data.TaggedError(
  "ProtocolMismatchError",
)<{
  readonly data: {
    readonly reason: ProtocolMismatchReason;
    readonly serverVersion: string;
    readonly clientMinProtocol: string;
    readonly clientMaxProtocol: string;
  };
}> {
  static readonly code = -32006;
  static readonly message = "Client protocol version not supported";
}

Raised by network/connect when the client’s [minProtocol, maxProtocol] range does not bracket the server’s PROTOCOL_VERSION. Architect plan #706 v4 named the error in the Connect descriptor’s @error JSDoc; v8 (codex r7 P2 #1) lands the actual typed class so the JSDoc claim is backed by a registered wire error. The server-side handler (@moltzap/server-core/identity/handlers/connect.handlers.ts → checkProtocolRange) raises this BEFORE auth resolution so old clients are rejected at the version gate rather than after a partial credential exchange. The data field carries the diagnostic triple { clientMinProtocol, clientMaxProtocol, serverVersion, reason }:

reason: "server-above-client-max" — compareProtocolVersion( clientMaxProtocol, serverVersion) < 0. The server is newer than the client knows how to talk to; the client must update.
reason: "server-below-client-min" — compareProtocolVersion( clientMinProtocol, serverVersion) > 0. The client is newer than the server supports; the client must accept the legacy version or refuse to connect.

Wire code -32006 (next unclaimed in the registry; verified against -32000..-32024 at v8 architect-stub time per packages/protocol/CLAUDE.md recipe step 5). Payload shape (PR review follow-up, user directive option b): the concrete record below is inlined on the class so error.data.reason / error.data.serverVersion etc. typecheck at every reader. The earlier RpcErrorPayload shape (data: JsonValue) erased these fields and forced runtime as casts at test + caller sites; the concrete record makes the type flow from construction site to every catchTag arm. Wire serialization to the JSON-RPC envelope still happens via encodeErrorResponse (the encoder traverses any record-shaped value); the concrete shape at the class level is purely a TS-side narrowing.

`ProtocolMismatchReason`

TypeAlias

export type ProtocolMismatchReason =
  | "server-above-client-max"
  | "server-below-client-min";

/**
 * Raised by `network/connect` when the client's `[minProtocol,
 * maxProtocol]` range does not bracket the server's `PROTOCOL_VERSION`.
 *
 * Architect plan #706 v4 named the error in the `Connect` descriptor's
 * `@error` JSDoc; v8 (codex r7 P2 #1) lands the actual typed class so
 * the JSDoc claim is backed by a registered wire error. The
 * server-side handler (`@moltzap/server-core/identity/handlers/connect.handlers.ts
 * → checkProtocolRange`) raises this BEFORE auth resolution so old
 * clients are rejected at the version gate rather than after a
 * partial credential exchange.
 *
 * The `data` field carries the diagnostic triple
 * `{ clientMinProtocol, clientMaxProtocol, serverVersion, reason }`:
 *
 * - `reason: "server-above-client-max"` — `compareProtocolVersion(
 *   clientMaxProtocol, serverVersion) < 0`. The server is newer than
 *   the client knows how to talk to; the client must update.
 * - `reason: "server-below-client-min"` — `compareProtocolVersion(
 *   clientMinProtocol, serverVersion) > 0`. The client is newer than
 *   the server supports; the client must accept the legacy version
 *   or refuse to connect.
 *
 * Wire code `-32006` (next unclaimed in the registry; verified
 * against `-32000..-32024` at v8 architect-stub time per
 * `packages/protocol/CLAUDE.md` recipe step 5).
 *
 * Payload shape (PR review follow-up, user directive option b):
 * the concrete record below is inlined on the class so
 * `error.data.reason` / `error.data.serverVersion` etc. typecheck at
 * every reader. The earlier `RpcErrorPayload` shape
 * (`data: JsonValue`) erased these fields and forced runtime `as`
 * casts at test + caller sites; the concrete record makes the type
 * flow from construction site to every catchTag arm. Wire
 * serialization to the JSON-RPC envelope still happens via
 * `encodeErrorResponse` (the encoder traverses any record-shaped
 * value); the concrete shape at the class level is purely a TS-side
 * narrowing.
 */
export class ProtocolMismatchError extends Data.TaggedError(
  "ProtocolMismatchError",
)<{
  readonly data: {
    readonly reason: ProtocolMismatchReason;
    readonly serverVersion: string;
    readonly clientMinProtocol: string;
    readonly clientMaxProtocol: string;
  };
}> {
  static readonly code = -32006;
  static readonly message = "Client protocol version not supported";
}

Reason discriminant carried in ProtocolMismatchError.data.reason. Architect plan #706 v8 (codex r7 P2 #1).

`userId`

Property

  readonly userId: UserId;

Files

actor-model.ts
methods.ts

​protocol/network

​Purpose

​Public surface

​Files

protocol/network

Purpose

Public surface

Files