protocol/testing/conformance/app

packages/protocol/src/testing/conformance/app

Purpose

Public barrel for app-layer conformance properties. App-layer conformance properties. Dispatch / lease / app-callback invariants — the 14 dispatch-admission properties (request / authorize / release / dispatch-lease-consumed / dispatch-lease-expired / dispatch-lease-get / slow-first / same-conv-concurrent / release-for-one-lease) plus app-disconnect fail-policy and idempotence. Each register* lives in its own file. The dispatch-admission properties draw on the cross-impl driver in app/_driver.ts.

Public surface

`ABANDON_OBSERVATION_BUFFER_MS`

Variable

export const ABANDON_OBSERVATION_BUFFER_MS = 1_000

`ABANDON_POLL_EXTRA_MS`

Variable

export const ABANDON_POLL_EXTRA_MS = 2_000

`APP_PROPERTIES`

Variable

export const APP_PROPERTIES: ReadonlyArray<
  (ctx: ConformanceRunContext) => void
> = [
  registerDispatchRequestAckMintsLease,
  registerDispatchRequestRecipientDisconnectAbandons,
  registerDispatchAuthorizeVerdictResolves,
  registerDispatchAuthorizeTimeoutSynthesizesDeny,
  registerDispatchReleaseFiresAfterResolve,
  registerDispatchReleaseSkippedOnAbandoned,
  registerDispatchLeaseConsumedFiresOnFirstSend,
  registerDispatchLeaseConsumedSuppressedOnSecondSend,
  registerDispatchLeaseExpiredFiresOnTtl,
  registerDispatchLeaseExpiredSuppressedOnConsumeBeforeTtl,
  registerDispatchLeaseGetModeratorSeesRecord,
  registerSameConversationDispatchRequestsConcurrent,
  registerSlowFirstDoesNotDelaySecondAck,
  registerReleaseForOneLeaseDoesNotWaitOnAnother,
  registerAppDisconnectFailPolicy,
  registerIdempotence,
]

All app-layer property registrars: dispatch-admission registrars first, then the cross-category registrars (boundary unavailable, rpc-semantics idempotence).

`ConsumedFrameView`

TypeAlias

export type ConsumedFrameView = {
  readonly messageId: string;
  readonly leaseId: string;
};

`DISPATCH_ADMISSION_CATEGORY`

Variable

export const DISPATCH_ADMISSION_CATEGORY = "dispatch-admission" as const

`dispatchAdmissionViolation`

Function

export function dispatchAdmissionViolation(
  name: string,
  reason: string,
): PropertyInvariantViolation

`DispatchTestDriver`

Interface

export interface DispatchTestDriver {
  readonly recipient: RecipientHandle;
  readonly moderator: ModeratorHandle;
  readonly fixtures: {
    readonly taskId: Schema.Schema.Type<typeof TaskId>;
    readonly conversationId: Schema.Schema.Type<typeof ConversationId>;
  };

  /**
   * Spin up an additional recipient client under a fresh agent identity.
   * Used by `same-conversation-dispatch-requests-reach-moderator-concurrently`
   * (two recipients in the same conversation issue `agent/dispatch/request`
   * back-to-back).
   */
  readonly addRecipient: (opts: {
    readonly agentName?: string;
  }) => Effect.Effect<RecipientHandle, PropertyFailure, Scope.Scope>;

  /**
   * Poll `app/dispatch/lease/get` until the lease reaches `expected` or the
   * bound elapses. Returns the final record. Used by every property
   * that asserts a state transition (PENDING→GRANTED, GRANTED→EXPIRED,
   * CLAIMED→CONSUMED, etc.). Implementation polls every 25 ms; bound
   * defaults to 5 s.
   */
  readonly assertLeaseState: (
    dispatchId: Schema.Schema.Type<typeof DispatchId>,
    expected: LeaseState,
    opts?: { readonly timeoutMs?: number },
  ) => Effect.Effect<void, PropertyFailure>;

  /**
   * Sleep `durationMs` against the real clock to let server-side TTLs elapse.
   * Property authors call this for `dispatch-lease-expired-fires-on-ttl` and the
   * moderator-response timeout property, which both run against a live server.
   */
  readonly advanceTime: (durationMs: number) => Effect.Effect<void>;
}

Cross-impl driver. One DispatchTestDriver instance per property, acquired under the property’s Scope. Wires up the real server, recipient + moderator clients, and shared task / conversation fixtures.

`DispatchVerdict`

TypeAlias

export type DispatchVerdict =
  | { readonly _tag: "grant"; readonly leaseTimeoutMs?: number }

Closed verdict union mirroring the wire DispatchAdmissionDecisionSchema. Properties that need to script a moderator’s reply pass a DispatchVerdict value to recipient.expectAuthorize / respondWith; the driver encodes it to the wire shape internally.

`FAST_ACK_THRESHOLD_MS`

Variable

export const FAST_ACK_THRESHOLD_MS = 1_000

`FORBIDDEN_ERROR_TAG`

Variable

export const FORBIDDEN_ERROR_TAG = "Forbidden"

`freshMessageId`

Function

export function freshMessageId(): Schema.Schema.Type<typeof MessageId>

`HOLD_DRAIN_BUFFER_MS`

Variable

export const HOLD_DRAIN_BUFFER_MS = 2_000

`HOLD_RELEASE_MARGIN_MS`

Variable

export const HOLD_RELEASE_MARGIN_MS = 500

`isUuidV4`

Function

export function isUuidV4(s: string): boolean

`leaseId`

Property

  readonly leaseId: string;
};

export function freshMessageId(): Schema.Schema.Type<typeof MessageId> {

`leaseId`

Property

export type LeaseIdOnlyView = { readonly leaseId: string };

`leaseId`

Property

  readonly leaseId: string;
  readonly verdict: { decision: string; reason?: string };

`LeaseIdOnlyView`

TypeAlias

export type LeaseIdOnlyView = { readonly leaseId: string };

`LeaseState`

TypeAlias

export type LeaseState =
  | "PENDING"
  | "CLAIMED"
  | "GRANTED"
  | "CONSUMED"
  | "DENIED"
  | "EXPIRED"
  | "ABANDONED"
  | "HOLD";

// ── Recipient handle ──────────────────────────────────────────────────

/**
 * Recipient-side surface. Owns one `AgentTestClient` connected to the real
 * server under a recipient agent identity. All methods return Effects
 * scoped to the surrounding `Scope`; releasing the scope closes the
 * underlying agent client.
 */
export interface RecipientHandle {
  readonly agentId: Schema.Schema.Type<typeof AgentId>;

  /**
   * Issue `agent/dispatch/request` for the given inbound. Returns the ack
   * payload `{leaseId, dispatchId}`. Single recipient may issue many
   * concurrent requests; the property is responsible for ordering its
   * own assertions.
   */
  readonly requestDispatch: (params: {
    readonly conversationId: Schema.Schema.Type<typeof ConversationId>;
    readonly messageId: Schema.Schema.Type<typeof MessageId>;
    readonly senderAgentId: Schema.Schema.Type<typeof AgentId>;
    readonly attempt?: number;
  }) => Effect.Effect<
    {
      readonly leaseId: Schema.Schema.Type<typeof LeaseId>;
      readonly dispatchId: Schema.Schema.Type<typeof DispatchId>;
    },
    PropertyFailure
  >;

  /**
   * Park until a `agent/dispatch/released` notification arrives that matches
   * `predicate` (default: any). Used by every property in the
   * `DispatchRelease` group + every property that asserts a verdict
   * delivery.
   */
  readonly waitForRelease: (
    predicate?: (
      frame: NotificationDelivery<typeof DispatchRelease>,
    ) => boolean,
    timeoutMs?: number,
  ) => Effect.Effect<
    NotificationDelivery<typeof DispatchRelease>,
    PropertyFailure
  >;

  /**
   * Send `agent/message/send` carrying `dispatchLeaseId`. Used to consume a
   * GRANTED lease + assert the consumed/duplicate behavior. Returns the
   * minted message id on success; on the lease-already-CONSUMED path,
   * fails with a `PropertyInvariantViolation` whose `reason` carries
   * the wire-error code + `LeaseInvalid` data tag the server returned.
   */
  readonly sendWithLease: (params: {
    readonly taskId: Schema.Schema.Type<typeof TaskId>;
    readonly conversationId: Schema.Schema.Type<typeof ConversationId>;
    readonly leaseId: Schema.Schema.Type<typeof LeaseId>;
    readonly text: string;
  }) => Effect.Effect<
    {
      readonly messageId: Schema.Schema.Type<typeof MessageId>;
      readonly errorTag?: string;
      readonly errorState?: string;
    },
    PropertyFailure
  >;

  /**
   * Disconnect the recipient's WS without graceful shutdown.
   * Drives ABANDONED + EXPIRED-on-disconnect transitions for every
   * `*-disconnect-*` property. The returned Effect resolves once the
   * server has observed the close (registry's connection-close
   * finalizer fired).
   */
  readonly hardClose: Effect.Effect<void, PropertyFailure>;
}

Closed lease-state union mirroring LeaseStateSchema. The driver’s assertLeaseState polls app/dispatch/lease/get until the registry settles to the named state or the bound elapses (the bound is per-property; default 5 s).

`makeDispatchTestDriver`

Function

export function makeDispatchTestDriver(
  ctx: ConformanceRunContext,
  config?: { readonly moderatorTimeoutMs?: number },
): Effect.Effect<DispatchTestDriver, PropertyFailure, Scope.Scope>

Acquire a fully-wired driver under the surrounding Scope. Releases close every lifecycle client + drop the connected app registration. Property authors call this from inside their property body; the driver is per-property, never shared. Cross-property state leakage is the exact failure mode the per-property scope prevents.

`messageId`

Property

  readonly messageId: string;
  readonly leaseId: string;
};

export function freshMessageId(): Schema.Schema.Type<typeof MessageId> {

`ModeratorHandle`

Interface

export interface ModeratorHandle {
  readonly agentId: Schema.Schema.Type<typeof AgentId>;
  readonly appId: string;

  /**
   * Park until a `app/dispatch/authorize` S→C request arrives that matches
   * `predicate` (default: any), then reply with `respondWith`. Internally
   * uses `AppTestClient.onAppCallback` to register the reply and
   * `awaitServerRequest` to observe the params.
   *
   * `holdResponseFor` is for the timeout-synthesizes-deny property:
   * delaying the reply past the moderator-response TTL forces the server
   * into the synthesized-deny branch. Default: reply immediately.
   */
  readonly handleAuthorize: (opts: {
    readonly respondWith: DispatchVerdict;
    readonly predicate?: (params: {
      readonly taskId: Schema.Schema.Type<typeof TaskId>;
      readonly conversationId: Schema.Schema.Type<typeof ConversationId>;
      readonly messageId: Schema.Schema.Type<typeof MessageId>;
    }) => boolean;
    readonly holdResponseFor?: number;
  }) => Effect.Effect<void, PropertyFailure>;

  /**
   * Drop the next inbound `app/dispatch/authorize` S→C request — install no
   * handler. Forces moderator-response TTL elapse. Used by
   * `dispatch-authorize-timeout-synthesizes-deny`.
   */
  readonly silenceAuthorize: Effect.Effect<void, PropertyFailure>;

  /**
   * Park until a `app/dispatch/lease-consumed` or `app/dispatch/lease-expired`
   * notification arrives matching `kind` and (optionally) `dispatchId`.
   */
  readonly waitForObservability: <K extends "consumed" | "expired">(
    kind: K,
    opts: {
      readonly dispatchId?: Schema.Schema.Type<typeof DispatchId>;
      readonly timeoutMs?: number;
    },
  ) => Effect.Effect<
    K extends "consumed"
      ? NotificationDelivery<typeof DispatchLeaseConsumed>
      : NotificationDelivery<typeof DispatchLeaseExpired>,
    PropertyFailure
  >;

  /**
   * Issue `app/dispatch/lease/get` from the moderator's connection. Used by the
   * positive `dispatch-lease-get-moderator-sees-record` property + every
   * `assertLeaseState` poll.
   */
  readonly getLease: (
    dispatchId: Schema.Schema.Type<typeof DispatchId>,
  ) => Effect.Effect<
    {
      readonly state: LeaseState;
      readonly verdict: DispatchVerdict | null;
      readonly leaseId: Schema.Schema.Type<typeof LeaseId>;
    },
    PropertyFailure
  >;
}

Moderator-side surface. Owns one AppTestClient connected to the real server under a moderator app identity, with HTTP registration plus app/network/connect already driven to install a dispatch_authorize hook. Holds the registered appId for app/dispatch/lease/get scope assertions.

`NEGATIVE_OBSERVABILITY_WINDOW_MS`

Variable

export const NEGATIVE_OBSERVABILITY_WINDOW_MS = 750

`NO_SECOND_RELEASE_WINDOW_MS`

Variable

export const NO_SECOND_RELEASE_WINDOW_MS = 250

`RecipientHandle`

Interface

export interface RecipientHandle {
  readonly agentId: Schema.Schema.Type<typeof AgentId>;

  /**
   * Issue `agent/dispatch/request` for the given inbound. Returns the ack
   * payload `{leaseId, dispatchId}`. Single recipient may issue many
   * concurrent requests; the property is responsible for ordering its
   * own assertions.
   */
  readonly requestDispatch: (params: {
    readonly conversationId: Schema.Schema.Type<typeof ConversationId>;
    readonly messageId: Schema.Schema.Type<typeof MessageId>;
    readonly senderAgentId: Schema.Schema.Type<typeof AgentId>;
    readonly attempt?: number;
  }) => Effect.Effect<
    {
      readonly leaseId: Schema.Schema.Type<typeof LeaseId>;
      readonly dispatchId: Schema.Schema.Type<typeof DispatchId>;
    },
    PropertyFailure
  >;

  /**
   * Park until a `agent/dispatch/released` notification arrives that matches
   * `predicate` (default: any). Used by every property in the
   * `DispatchRelease` group + every property that asserts a verdict
   * delivery.
   */
  readonly waitForRelease: (
    predicate?: (
      frame: NotificationDelivery<typeof DispatchRelease>,
    ) => boolean,
    timeoutMs?: number,
  ) => Effect.Effect<
    NotificationDelivery<typeof DispatchRelease>,
    PropertyFailure
  >;

  /**
   * Send `agent/message/send` carrying `dispatchLeaseId`. Used to consume a
   * GRANTED lease + assert the consumed/duplicate behavior. Returns the
   * minted message id on success; on the lease-already-CONSUMED path,
   * fails with a `PropertyInvariantViolation` whose `reason` carries
   * the wire-error code + `LeaseInvalid` data tag the server returned.
   */
  readonly sendWithLease: (params: {
    readonly taskId: Schema.Schema.Type<typeof TaskId>;
    readonly conversationId: Schema.Schema.Type<typeof ConversationId>;
    readonly leaseId: Schema.Schema.Type<typeof LeaseId>;
    readonly text: string;
  }) => Effect.Effect<
    {
      readonly messageId: Schema.Schema.Type<typeof MessageId>;
      readonly errorTag?: string;
      readonly errorState?: string;
    },
    PropertyFailure
  >;

  /**
   * Disconnect the recipient's WS without graceful shutdown.
   * Drives ABANDONED + EXPIRED-on-disconnect transitions for every
   * `*-disconnect-*` property. The returned Effect resolves once the
   * server has observed the close (registry's connection-close
   * finalizer fired).
   */
  readonly hardClose: Effect.Effect<void, PropertyFailure>;
}

Recipient-side surface. Owns one AgentTestClient connected to the real server under a recipient agent identity. All methods return Effects scoped to the surrounding Scope; releasing the scope closes the underlying agent client.

`registerAppDisconnectFailPolicy`

Function

export function registerAppDisconnectFailPolicy(
  ctx: ConformanceRunContext,
): void

`registerDispatchAuthorizeTimeoutSynthesizesDeny`

Function

export function registerDispatchAuthorizeTimeoutSynthesizesDeny(
  ctx: ConformanceRunContext,
): void

`registerDispatchAuthorizeVerdictResolves`

Function

export function registerDispatchAuthorizeVerdictResolves(
  ctx: ConformanceRunContext,
): void

`registerDispatchLeaseConsumedFiresOnFirstSend`

Function

export function registerDispatchLeaseConsumedFiresOnFirstSend(
  ctx: ConformanceRunContext,
): void

`registerDispatchLeaseConsumedSuppressedOnSecondSend`

Function

export function registerDispatchLeaseConsumedSuppressedOnSecondSend(
  ctx: ConformanceRunContext,
): void

`registerDispatchLeaseExpiredFiresOnTtl`

Function

export function registerDispatchLeaseExpiredFiresOnTtl(
  ctx: ConformanceRunContext,
): void

`registerDispatchLeaseExpiredSuppressedOnConsumeBeforeTtl`

Function

export function registerDispatchLeaseExpiredSuppressedOnConsumeBeforeTtl(
  ctx: ConformanceRunContext,
): void

`registerDispatchLeaseGetModeratorSeesRecord`

Function

export function registerDispatchLeaseGetModeratorSeesRecord(
  ctx: ConformanceRunContext,
): void

`registerDispatchReleaseFiresAfterResolve`

Function

export function registerDispatchReleaseFiresAfterResolve(
  ctx: ConformanceRunContext,
): void

`registerDispatchReleaseSkippedOnAbandoned`

Function

export function registerDispatchReleaseSkippedOnAbandoned(
  ctx: ConformanceRunContext,
): void

`registerDispatchRequestAckMintsLease`

Function

export function registerDispatchRequestAckMintsLease(
  ctx: ConformanceRunContext,
): void

`registerDispatchRequestRecipientDisconnectAbandons`

Function

export function registerDispatchRequestRecipientDisconnectAbandons(
  ctx: ConformanceRunContext,
): void

`registerIdempotence`

Function

export function registerIdempotence(ctx: ConformanceRunContext): void

`registerReleaseForOneLeaseDoesNotWaitOnAnother`

Function

export function registerReleaseForOneLeaseDoesNotWaitOnAnother(
  ctx: ConformanceRunContext,
): void

`registerSameConversationDispatchRequestsConcurrent`

Function

export function registerSameConversationDispatchRequestsConcurrent(
  ctx: ConformanceRunContext,
): void

`registerSlowFirstDoesNotDelaySecondAck`

Function

export function registerSlowFirstDoesNotDelaySecondAck(
  ctx: ConformanceRunContext,
): void

`ReleaseFrameView`

TypeAlias

export type ReleaseFrameView = {
  readonly leaseId: string;
  readonly verdict: { decision: string; reason?: string };
};

`SHORT_LEASE_TIMEOUT_MS`

Variable

export const SHORT_LEASE_TIMEOUT_MS = 250

`TIMEOUT_RELEASE_WAIT_MS`

Variable

export const TIMEOUT_RELEASE_WAIT_MS = 3_000

`TINY_MODERATOR_TIMEOUT_MS`

Variable

export const TINY_MODERATOR_TIMEOUT_MS = 200

`TTL_OBSERVATION_BUFFER_MS`

Variable

export const TTL_OBSERVATION_BUFFER_MS = 1_500

`verdict`

Property

  readonly verdict: { decision: string; reason?: string };

`withDriver`

Function

export function withDriver(
  ctx: ConformanceRunContext,
  body: (
    driver: DispatchTestDriver,
  ) => Effect.Effect<void, PropertyFailure, Scope.Scope>,
  driverOpts?: Parameters<typeof makeDispatchTestDriver>[1],
): PropertyRun

Run a property body inside a fresh per-property scope; acquires the driver, runs body, releases on completion.

Files

_driver.ts
_helpers.ts
app-disconnect-fail-policy.ts
dispatch-authorize-timeout.ts
dispatch-authorize-verdict.ts
dispatch-lease-consumed-fires-on-first-send.ts
dispatch-lease-consumed-suppressed-on-second.ts
dispatch-lease-expired-fires-on-ttl.ts
dispatch-lease-expired-suppressed-on-consume.ts
dispatch-lease-get-moderator-sees.ts
dispatch-release-after-resolve.ts
dispatch-release-skipped-on-abandoned.ts
dispatch-request-ack.ts
dispatch-request-recipient-disconnect.ts
idempotence.ts
index.ts
release-for-one-lease-does-not-wait.ts
same-conv-dispatch-requests-concurrent.ts
slow-first-does-not-delay-second-ack.ts

​protocol/testing/conformance/app

​Purpose

​Public surface

​Files

protocol/testing/conformance/app

Purpose

Public surface

Files