Protocol Session Prototype

This directory retains the original experiment record. Implementation and tests now live in the terminal module, under terminal/src/session.ts and terminal/test/session.test.ts. Later resource-budget checks cover opt-in retained-state limits separately from this original experiment.

This prototype asks whether the draft Capability, Context, Block Operation, and error semantics can form one deterministic in-memory terminal-side session after Messages have already been decoded.

It exercises the current drafts for:

Observed Behavior

  • The tested host-declared supported and unsupported Capability outcomes are correlated, and retrying the same control request returns its original outcome.

  • The tested request-ID conflict is rejected without creating a Context.

  • Context closure seals mutable Blocks, retains their content and order, and remains successful when repeated for a known closed Context.

  • A tested host invalidation revokes one Context’s mutation authority without pretending to close or Seal its Blocks. A later Update and closure request both report context_not_open.

  • Explicit connection termination closes every remaining open Context and seals its mutable Blocks in the tested session.

  • The tested Append, complete Update, and Seal sequence preserves Block identity, order, content, and one-way lifecycle rules.

  • Tested Extend chains append only on the latest content Operation ID. A stale base leaves content unchanged, dependent fragments are rejected, and a complete Update establishes a new base from which Extend can continue.

  • Tested ReplaceSuffix Operations count Unicode scalar values, replace or delete a non-empty suffix, advance content state, and distinguish a stale base from an invalid retained-prefix boundary without partial mutation.

  • The tested semantic failures leave Block state unchanged, and a used Operation ID cannot be reused even when its first Operation failed.

  • A tested valid Update can be prepared without changing Block state, then committed or rejected with resource_exhausted; rejection leaves the Block unchanged while consuming the Operation ID.

  • A tested prepared Extend rejected with resource_exhausted leaves its fragment unapplied and leaves the prior successful content base usable by a new Extend Operation ID.

  • While one tested Operation is prepared, later Messages are refused until the host commits or rejects it, preserving the Session’s ordered execution boundary. Ending the connection instead discards the prepared Operation, closes its Context, and leaves its uncommitted content change unapplied.

  • The tested two Contexts maintain independent Block and Operation namespaces while reusing the same Block and Operation IDs.

Setup and Host Responsibilities

  • context-N identifiers are deterministic test fixtures. Context IDs remain opaque on the wire, and this allocation format is not proposed behavior.

  • completeBaselineSupported is a host-supplied assertion used to exercise both Capability outcomes. This prototype does not determine whether a real terminal satisfies the complete baseline.

  • endConnection() is an experimental host hook; it does not detect the end of a real byte stream by itself.

  • invalidateContext() is an experimental host hook for a terminal integration that has already determined frame-external traffic made a managed Block’s rendering or reliable range untrustworthy. The Session does not inspect terminal controls or rendered rows itself.

  • The session accepts already validated logical Messages and implements only the baseline text/plain representation.

  • handleInvalidMessage() is a separate experimental integration hook for reliable correlation metadata produced when the codec rejects a complete Message. It does not parse or accept malformed bytes itself.

  • prepareOperation() is an experimental two-phase host seam. It permits one prepared Block Operation at a time and does not itself detect resources, render content, or make an external renderer transactional.

  • ProtocolSessionError reports misuse of the local API, such as sending a terminal-originated Message into the terminal-side session. It is not a wire-level protocol.error.

Scope

These checks observe validated Messages and in-memory Session state. Byte transport is exercised by the Endpoint experiment; rendered history and reading behavior are exercised by the xterm integration. The original Session experiment covers baseline text/plain and host-triggered lifecycle events. Resource detection, partial-render failures, timeouts, and authentication require host integration.

Run

pnpm typecheck
pnpm test