worker.postMessage({ action: "refresh" });

channel.postMessage({ type: "LOGOUT" });

navigator.serviceWorker.controller?.postMessage({ cache: "clear" });

port.addEventListener("message", event => {
  runtime.receive(event.data, {
    transport: "message-port",
    rawEvent: event,
  });
});

export type ProtocolEnvelope<TPayload = unknown> = {
  protocol: "app.browser.orchestration";
  protocolVersion: 1;

  messageId: string;
  messageType: string;
  messageKind: "command" | "event" | "query" | "reply" | "error" | "ack";

  createdAt: number;
  deadlineAt?: number;

  sender: ProtocolActor;
  recipient?: ProtocolRecipient;

  correlationId?: string;
  causationId?: string;
  idempotencyKey?: string;

  schemaVersion: number;
  payload: TPayload;

  meta?: ProtocolMeta;
};

export type ProtocolActor = {
  actorId: string;
  actorType: "window" | "dedicated-worker" | "shared-worker" | "service-worker";
  instanceId: string;
  appVersion: string;
};

export type ProtocolRecipient =
  | { kind: "any" }
  | { kind: "actor"; actorId: string }
  | { kind: "role"; role: "leader" | "cache-coordinator" | "auth-coordinator" }
  | { kind: "broadcast" };

export type ProtocolMeta = {
  traceId?: string;
  spanId?: string;
  attempt?: number;
  priority?: "low" | "normal" | "high";
  feature?: string;
  debug?: boolean;
};

if (envelope.protocol !== "app.browser.orchestration") {
  return ignore("unknown_protocol");
}

const messageId = crypto.randomUUID();

"auth.token.refresh.request"
"auth.token.refresh.result"
"session.logout.command"
"cache.entry.invalidated"
"worker.task.execute"
"worker.task.completed"
"tab.presence.heartbeat"
"leader.election.claim"

"refresh"
"done"
"update"
"sync"
"message"

function isExpired(envelope: ProtocolEnvelope): boolean {
  return typeof envelope.deadlineAt === "number" && Date.now() > envelope.deadlineAt;
}

const actor: ProtocolActor = {
  actorId: stableActorId,
  actorType: "window",
  instanceId: runtimeInstanceId,
  appVersion: __APP_VERSION__,
};

recipient: { kind: "role", role: "auth-coordinator" }

function isForMe(envelope: ProtocolEnvelope, self: ProtocolActor, roles: Set<string>): boolean {
  const r = envelope.recipient;

  if (!r) return true;
  if (r.kind === "any") return true;
  if (r.kind === "broadcast") return true;
  if (r.kind === "actor") return r.actorId === self.actorId;
  if (r.kind === "role") return roles.has(r.role);

  return false;
}

const request = {
  messageId: "m-1",
  correlationId: "c-100",
  messageKind: "query",
};

const reply = {
  messageId: "m-2",
  correlationId: "c-100",
  messageKind: "reply",
};

user.click.sync.button
  -> sync.request
     -> sync.item.started
     -> sync.item.completed
     -> cache.entry.invalidated

idempotencyKey: "offline-op:case-123:add-note:client-op-789"

type TokenRefreshRequestV1 = {
  reason: "startup" | "expiry" | "manual";
};

type TokenRefreshRequestV2 = {
  reason: "startup" | "expiry" | "manual";
  minExpiresInMs: number;
};

function normalizeTokenRefreshRequest(schemaVersion: number, payload: unknown) {
  if (schemaVersion === 1) {
    const v1 = parseV1(payload);
    return { ...v1, minExpiresInMs: 30_000 };
  }

  if (schemaVersion === 2) {
    return parseV2(payload);
  }

  throw new ProtocolError("UNSUPPORTED_SCHEMA_VERSION");
}

type LogoutCommand = ProtocolEnvelope<{
  reason: "user" | "server-revoked" | "session-expired";
  clearStorage: boolean;
}> & {
  messageKind: "command";
  messageType: "session.logout.command";
};

{ type: "DO_IT" }

{
  protocol: "app.browser.orchestration",
  protocolVersion: 1,
  messageKind: "command",
  messageType: "session.logout.command",
  messageId: "...",
  idempotencyKey: "logout:session:abc:revocation:42",
  createdAt: 1783497600000,
  deadlineAt: 1783497605000,
  sender: { ... },
  schemaVersion: 1,
  payload: {
    reason: "server-revoked",
    clearStorage: true
  }
}

type CacheInvalidatedEvent = ProtocolEnvelope<{
  cacheName: string;
  keys: string[];
  version: string;
}> & {
  messageKind: "event";
  messageType: "cache.entry.invalidated";
};

cache.invalidate
user.logout
sync.start

cache.entry.invalidated
session.logout.completed
sync.job.started

type GetLeaderQuery = ProtocolEnvelope<{
  role: "auth-coordinator" | "cache-coordinator";
}> & {
  messageKind: "query";
  messageType: "leader.get.query";
};

type ProtocolReply<TPayload> = ProtocolEnvelope<TPayload> & {
  messageKind: "reply";
  correlationId: string;
};

export type ProtocolErrorPayload = {
  code:
    | "BAD_MESSAGE"
    | "UNSUPPORTED_PROTOCOL_VERSION"
    | "UNSUPPORTED_SCHEMA_VERSION"
    | "VALIDATION_FAILED"
    | "UNAUTHORIZED_MESSAGE_TYPE"
    | "DEADLINE_EXCEEDED"
    | "HANDLER_FAILED"
    | "RESOURCE_BUSY"
    | "DUPLICATE_OPERATION";
  message: string;
  retryable: boolean;
  details?: Record<string, unknown>;
};

function toProtocolErrorPayload(error: unknown): ProtocolErrorPayload {
  if (error instanceof ProtocolError) {
    return {
      code: error.code,
      message: error.message,
      retryable: error.retryable,
      details: error.details,
    };
  }

  return {
    code: "HANDLER_FAILED",
    message: "Unhandled protocol handler failure",
    retryable: false,
  };
}

type AppMessage =
  | SessionLogoutCommand
  | AuthTokenRefreshRequest
  | AuthTokenRefreshResult
  | CacheEntryInvalidatedEvent
  | TabPresenceHeartbeatEvent
  | WorkerTaskExecuteCommand
  | WorkerTaskCompletedEvent
  | ProtocolErrorMessage;

function handleMessage(message: AppMessage) {
  switch (message.messageType) {
    case "session.logout.command":
      return handleLogout(message);

    case "auth.token.refresh.request":
      return handleTokenRefresh(message);

    case "cache.entry.invalidated":
      return handleCacheInvalidated(message);

    default:
      return assertNever(message);
  }
}

function assertNever(value: never): never {
  throw new Error(`Unhandled message: ${JSON.stringify(value)}`);
}

port.onmessage = event => {
  const message = event.data as AppMessage;
  handleMessage(message);
};

port.onmessage = event => {
  const decoded = decodeAppMessage(event.data);

  if (!decoded.ok) {
    logBadMessage(decoded.reason, event.data);
    return;
  }

  runtime.receive(decoded.value);
};

export type DecodeResult<T> =
  | { ok: true; value: T }
  | { ok: false; reason: string; details?: unknown };

export function decodeEnvelope(input: unknown): DecodeResult<ProtocolEnvelope> {
  if (typeof input !== "object" || input === null) {
    return { ok: false, reason: "not_object" };
  }

  const value = input as Record<string, unknown>;

  if (value.protocol !== "app.browser.orchestration") {
    return { ok: false, reason: "unknown_protocol" };
  }

  if (value.protocolVersion !== 1) {
    return { ok: false, reason: "unsupported_protocol_version" };
  }

  if (typeof value.messageId !== "string") {
    return { ok: false, reason: "missing_message_id" };
  }

  if (typeof value.messageType !== "string") {
    return { ok: false, reason: "missing_message_type" };
  }

  if (typeof value.createdAt !== "number") {
    return { ok: false, reason: "missing_created_at" };
  }

  return { ok: true, value: value as ProtocolEnvelope };
}

export const MessageTypes = {
  SessionLogoutCommand: "session.logout.command",
  AuthTokenRefreshRequest: "auth.token.refresh.request",
  AuthTokenRefreshResult: "auth.token.refresh.result",
  CacheEntryInvalidated: "cache.entry.invalidated",
  TabPresenceHeartbeat: "tab.presence.heartbeat",
  WorkerTaskExecute: "worker.task.execute",
  WorkerTaskCompleted: "worker.task.completed",
} as const;

export type MessageType = typeof MessageTypes[keyof typeof MessageTypes];

type Handler<T extends AppMessage> = (message: T, ctx: HandlerContext) => Promise<void> | void;

type HandlerMap = {
  [MessageTypes.SessionLogoutCommand]: Handler<SessionLogoutCommand>;
  [MessageTypes.AuthTokenRefreshRequest]: Handler<AuthTokenRefreshRequest>;
  [MessageTypes.CacheEntryInvalidated]: Handler<CacheEntryInvalidatedEvent>;
};

Tab A: app version 2026.07.08.1
Tab B: app version 2026.07.08.2
Service Worker: version 2026.07.07.9
SharedWorker: loaded from old JS chunk

type V1 = {
  reason: "expiry" | "manual";
};

type V2 = {
  reason: "expiry" | "manual";
  minExpiresInMs?: number;
};

type V1 = {
  token: string;
};

type V2 = {
  accessToken: string;
};

schemaVersion: 2

auth.token.refresh.result.v2

type HelloMessage = ProtocolEnvelope<{
  supportedProtocolVersions: number[];
  supportedMessageTypes: string[];
  capabilities: string[];
}> & {
  messageKind: "event";
  messageType: "runtime.hello";
};

{
  messageType: "worker.task.completed",
  payload: {
    taskId: "task-123",
    resultRef: {
      store: "indexeddb",
      database: "app-worker-results",
      key: "task-123/result"
    }
  }
}

const allowedFromWindowToWorker = new Set([
  "worker.task.execute",
  "worker.task.cancel",
]);

function authorizeMessage(message: ProtocolEnvelope, policy: Set<string>) {
  if (!policy.has(message.messageType)) {
    throw new ProtocolError("UNAUTHORIZED_MESSAGE_TYPE", false);
  }
}

{
  messageType: "auth.token.refresh.completed",
  payload: {
    sessionVersion: 42,
    expiresAt: 1783499999999
  }
}

{
  messageType: "session.logout.command",
  payload: {
    reason: "server-revoked",
    clearStorage: false
  }
}

function validateLogoutIntent(payload: LogoutPayload) {
  if (payload.reason === "server-revoked" && payload.clearStorage !== true) {
    throw new ProtocolError("VALIDATION_FAILED", false, {
      field: "clearStorage",
      reason: "server_revoked_logout_must_clear_storage",
    });
  }
}

export class ProtocolRouter {
  private handlers = new Map<string, Handler<any>>();

  register<T extends AppMessage>(
    messageType: T["messageType"],
    handler: Handler<T>,
  ): void {
    if (this.handlers.has(messageType)) {
      throw new Error(`Handler already registered for ${messageType}`);
    }

    this.handlers.set(messageType, handler);
  }

  async dispatch(message: AppMessage, ctx: HandlerContext): Promise<void> {
    const handler = this.handlers.get(message.messageType);

    if (!handler) {
      ctx.logger.warn("protocol.unhandled_message", {
        messageType: message.messageType,
        messageId: message.messageId,
      });
      return;
    }

    await handler(message, ctx);
  }
}

export type TransportName =
  | "message-port"
  | "broadcast-channel"
  | "service-worker"
  | "storage-event";

export type TransportAdapter = {
  name: TransportName;
  send(envelope: ProtocolEnvelope, transfer?: Transferable[]): void;
  close(): void;
};

export class BroadcastTransport implements TransportAdapter {
  readonly name = "broadcast-channel" as const;

  constructor(private readonly channel: BroadcastChannel) {}

  send(envelope: ProtocolEnvelope): void {
    this.channel.postMessage(envelope);
  }

  close(): void {
    this.channel.close();
  }
}

export class MessagePortTransport implements TransportAdapter {
  readonly name = "message-port" as const;

  constructor(private readonly port: MessagePort) {}

  send(envelope: ProtocolEnvelope, transfer: Transferable[] = []): void {
    this.port.postMessage(envelope, transfer);
  }

  close(): void {
    this.port.close();
  }
}

export type CreateMessageInput<TPayload> = {
  messageType: string;
  messageKind: ProtocolEnvelope["messageKind"];
  schemaVersion: number;
  payload: TPayload;
  sender: ProtocolActor;
  recipient?: ProtocolRecipient;
  correlationId?: string;
  causationId?: string;
  idempotencyKey?: string;
  ttlMs?: number;
  meta?: ProtocolMeta;
};

export function createMessage<TPayload>(
  input: CreateMessageInput<TPayload>,
): ProtocolEnvelope<TPayload> {
  const now = Date.now();

  return {
    protocol: "app.browser.orchestration",
    protocolVersion: 1,
    messageId: crypto.randomUUID(),
    messageType: input.messageType,
    messageKind: input.messageKind,
    createdAt: now,
    deadlineAt: input.ttlMs ? now + input.ttlMs : undefined,
    sender: input.sender,
    recipient: input.recipient,
    correlationId: input.correlationId,
    causationId: input.causationId,
    idempotencyKey: input.idempotencyKey,
    schemaVersion: input.schemaVersion,
    payload: input.payload,
    meta: input.meta,
  };
}

export function createErrorReply(
  request: ProtocolEnvelope,
  error: ProtocolErrorPayload,
  sender: ProtocolActor,
): ProtocolEnvelope<ProtocolErrorPayload> {
  return createMessage({
    messageType: "protocol.error",
    messageKind: "error",
    schemaVersion: 1,
    payload: error,
    sender,
    recipient: { kind: "actor", actorId: request.sender.actorId },
    correlationId: request.correlationId ?? request.messageId,
    causationId: request.messageId,
    ttlMs: 5_000,
    meta: {
      traceId: request.meta?.traceId,
      attempt: request.meta?.attempt,
    },
  });
}

type ProtocolLog = {
  direction: "in" | "out";
  transport: TransportName;
  messageId: string;
  messageType: string;
  messageKind: string;
  correlationId?: string;
  causationId?: string;
  senderActorId: string;
  senderType: string;
  recipient?: ProtocolRecipient;
  protocolVersion: number;
  schemaVersion: number;
  ageMs: number;
  expired: boolean;
  payloadBytesApprox?: number;
  result: "accepted" | "ignored" | "rejected" | "handled" | "failed";
  reason?: string;
};

function summarizePayload(payload: unknown): Record<string, unknown> {
  if (typeof payload !== "object" || payload === null) return { kind: typeof payload };

  return {
    fields: Object.keys(payload as Record<string, unknown>).slice(0, 20),
  };
}

type TokenRefreshRequest = ProtocolEnvelope<{
  reason: "startup" | "expiry" | "foreground" | "manual";
  minExpiresInMs: number;
  sessionVersion: number;
}> & {
  messageKind: "command";
  messageType: "auth.token.refresh.request";
};

type TokenRefreshCompleted = ProtocolEnvelope<{
  sessionVersion: number;
  accessTokenExpiresAt: number;
}> & {
  messageKind: "event";
  messageType: "auth.token.refresh.completed";
};

type TokenRefreshFailed = ProtocolEnvelope<{
  sessionVersion: number;
  reason: "network" | "revoked" | "invalid_grant" | "unknown";
  retryable: boolean;
}> & {
  messageKind: "event";
  messageType: "auth.token.refresh.failed";
};

type WorkerTaskExecute = ProtocolEnvelope<{
  taskId: string;
  taskType: "search-index" | "parse-csv" | "diff-document";
  inputRef?: DataRef;
  inlineInput?: unknown;
  priority: "low" | "normal" | "high";
}> & {
  messageKind: "command";
  messageType: "worker.task.execute";
};

type WorkerTaskCompleted = ProtocolEnvelope<{
  taskId: string;
  resultRef?: DataRef;
  inlineResult?: unknown;
  durationMs: number;
}> & {
  messageKind: "reply";
  messageType: "worker.task.completed";
  correlationId: string;
};

type DataRef = {
  store: "indexeddb" | "opfs" | "cache";
  key: string;
};

type CacheInvalidated = ProtocolEnvelope<{
  namespace: "case" | "user" | "lookup" | "asset";
  keys: string[];
  cacheVersion: string;
  reason: "mutation" | "deployment" | "manual" | "ttl";
}> & {
  messageKind: "event";
  messageType: "cache.entry.invalidated";
};

class UserSession {
  constructor(private token: string) {}
  isExpired() { return true; }
}

worker.postMessage(new UserSession("..."));

type UserSessionDto = {
  sessionId: string;
  expiresAt: number;
  sessionVersion: number;
};

<domain>.<resource>.<action-or-fact>.<kind>

auth.token.refresh.request
auth.token.refresh.completed
session.logout.command
session.logout.completed
cache.entry.invalidated
tab.presence.heartbeat
leader.election.claim
worker.task.execute
worker.task.completed
protocol.error
runtime.hello
runtime.welcome

GET_DATA
UPDATE
DONE
SYNC
WORKER_MESSAGE
BROADCAST_EVENT

type IgnoreReason =
  | "unknown_protocol"
  | "unsupported_protocol_version"
  | "expired"
  | "not_for_this_recipient"
  | "sender_is_self"
  | "unknown_message_type"
  | "duplicate_message"
  | "stale_epoch"
  | "stale_schema";

metrics.increment("protocol.message.ignored", {
  reason,
  messageType: envelope.messageType,
  transport,
});

function isSelfMessage(message: ProtocolEnvelope, self: ProtocolActor) {
  return message.sender.instanceId === self.instanceId;
}

type SequencedPayload<T> = {
  streamId: string;
  sequence: number;
  value: T;
};

function acceptSequenced(streamId: string, sequence: number) {
  const last = lastSequenceByStream.get(streamId) ?? 0;

  if (sequence <= last) {
    return false;
  }

  lastSequenceByStream.set(streamId, sequence);
  return true;
}

type LeaderCommandPayload = {
  role: "auth-coordinator";
  leaderId: string;
  epoch: number;
};

if (message.payload.epoch < currentEpoch) {
  return ignore("stale_epoch");
}

export class BrowserProtocolRuntime {
  constructor(
    private readonly self: ProtocolActor,
    private readonly router: ProtocolRouter,
    private readonly authorizer: MessageAuthorizer,
    private readonly logger: ProtocolLogger,
  ) {}

  async receive(raw: unknown, ctx: ReceiveContext): Promise<void> {
    const decoded = decodeEnvelope(raw);

    if (!decoded.ok) {
      this.logger.badMessage(ctx.transport, decoded.reason, decoded.details);
      return;
    }

    const message = decoded.value;
    const ageMs = Date.now() - message.createdAt;

    if (message.deadlineAt && Date.now() > message.deadlineAt) {
      this.logger.ignored(message, ctx.transport, "expired", { ageMs });
      return;
    }

    if (!isForMe(message, this.self, ctx.roles)) {
      this.logger.ignored(message, ctx.transport, "not_for_this_recipient", { ageMs });
      return;
    }

    try {
      this.authorizer.assertAllowed(message, ctx);
      await this.router.dispatch(message as AppMessage, {
        runtime: this,
        transport: ctx.transport,
        logger: this.logger,
      });

      this.logger.handled(message, ctx.transport, { ageMs });
    } catch (error) {
      this.logger.failed(message, ctx.transport, error);
      await this.maybeReplyWithError(message, ctx, error);
    }
  }

  send(
    transport: TransportAdapter,
    message: ProtocolEnvelope,
    transfer?: Transferable[],
  ): void {
    this.logger.out(message, transport.name);
    transport.send(message, transfer);
  }

  private async maybeReplyWithError(
    message: ProtocolEnvelope,
    ctx: ReceiveContext,
    error: unknown,
  ) {
    if (!message.correlationId && message.messageKind !== "query") {
      return;
    }

    if (!ctx.replyTransport) {
      return;
    }

    const errorReply = createErrorReply(
      message,
      toProtocolErrorPayload(error),
      this.self,
    );

    ctx.replyTransport.send(errorReply);
  }
}

it("rejects unknown protocol", () => {
  expect(decodeEnvelope({ protocol: "random" })).toEqual({
    ok: false,
    reason: "unknown_protocol",
  });
});

it("normalizes v1 token refresh request to current internal shape", () => {
  const normalized = normalizeTokenRefreshRequest(1, {
    reason: "expiry",
  });

  expect(normalized.minExpiresInMs).toBe(30_000);
});

it("does not allow follower tab to send leader-only cache commit", () => {
  expect(() => authorize(message, followerContext)).toThrow("UNAUTHORIZED_MESSAGE_TYPE");
});

fixtures/protocol/v1/session.logout.command.json
fixtures/protocol/v1/auth.token.refresh.completed.json
fixtures/protocol/v1/cache.entry.invalidated.json

channel.postMessage({ type: "UPDATE", data });

{ type: "APP_MESSAGE", payload: { action: "logout" } }

channel.postMessage({ type: "FULL_STATE", state: hugeReduxState });

worker.onmessage = event => setSearchResult(event.data);

if (event.data.correlationId !== currentSearchCorrelationId) {
  return;
}

if (Date.now() > event.data.deadlineAt) {
  return;
}

setSearchResult(event.data.payload);

throw new Error("nope");

requirement -> failure model -> protocol -> transport -> implementation -> observability -> testing

transport -> callback -> hope