SumDoc transport and message format

JSONL stdio

# $CLI is the path to the processor inside the installed application,
# it's given on the “Installation and verification” page
"$CLI" serve
{
  "schema": "fastdoc.session-serve.v1",
  "stage_id": "D7",
  "session_kind": "jsonl-stdio-document-session-prototype",
  "supported_commands": [
    "apply-composition",
    "apply-text-transaction",
    "commit-snapshot",
    "commit-structural-snapshot",
    "compatibility-inspect",
    "compose",
    "model",
    "mutate",
    "open",
    "paginate",
    "ping",
    "print",
    "print-delta",
    "print-summary",
    "print-window",
    "redo",
    "report",
    "review",
    "save",
    "save-checkpoint",
    "set-selection",
    "shutdown",
    "simple-field-inventory",
    "squash-history",
    "status",
    "style",
    "track-revisions-state",
    "undo"
  ],
  "ready": true
}

WebSocket

"$CLI" serve --ws 0 [--token <token>]
{"schema":"fastdoc.session-ws-bootstrap.v1","transport":"websocket","host":"127.0.0.1","port":49152,"token":"<64 hex>","ready":true}

The connection accepts only UTF-8 text frames, listens only on a local address, and checks the token passed in the connection address. Right after connecting, the same readiness line arrives as with standard-input/output exchange.

About --token. If you don’t set one, the processor generates a new token on every launch: 256 bits from the system randomness source — the same 64 hex characters in the readiness line — and it lives exactly as long as the process runs. If you set your own, rotating it on every launch becomes your responsibility, and a fixed value in the startup script cancels that rotation.

The core checks your own token only for being non-empty

The processor requires neither length nor randomness: --token secret is accepted just like 64 hex characters. It can’t tell a weak value from a strong one — the quality of your token is entirely up to you, and an empty string is the only thing it rejects.

The stage_id field in the readiness response

The readiness line carries a stage_id field with a value like D7. This is an internal marker of the core’s development stage: it can change in any release, and you shouldn’t rely on it. The schema field names the contract version.

Request and response envelope

interface Request { id?: unknown; cmd: SessionCommandName; /* command fields flattened */ }
interface Response<T=unknown> { id:unknown; ok:boolean; cmd?:string; elapsed_ms?:number; result?:T; error?:string; }

Situation	What comes back
The request isn’t an object, or is missing the cmd field	ok: false, with the error field — each request line must be a JSON object with a string cmd field
No command with that name exists	ok: false, with error — unknown session command: <name>
The command requires an open document	ok: false, with error — no document is open in this session
An internal processing error	ok: false and a message marked panicked. The session stays alive and the connection doesn’t drop — you can send the next command

What’s in the greeting line

The first line of the session isn’t a formality: you use it to verify what you’re talking to. It has five fields.

Field	What’s in it
schema	fastdoc.session-serve.v1 — the version of the conversation itself. Check this one at startup: if it doesn’t match, the processor is older or newer than your code.
session_kind	How you connected (three values, below).
supported_commands	The full list of commands this particular processor will accept. More reliable than the reference: it speaks for itself.
stage_id	An internal build-stage marker. Not needed for embedding; don’t branch on it.
ready	true when the session is ready to accept commands.

There are three kinds of session, and they show which way the conversation was opened:

session_kind value	When you see it
jsonl-stdio-document-session-prototype	Exchanging strings over standard input/output — serve with no flags.
json-websocket-document-session	The same contract over WebSocket — serve --ws.
json-websocket-embedded-surface-session	An embedded-surface session — surface.

The word prototype in the first name

This is the channel’s historical name, not a judgment of its maturity: exchanging lines over standard input and output is the main path for external integration; the quick start is built on it, and all session commands go through it. It can’t be renamed without breaking those who already check this value.

About timeouts

There’s no timeout in the JSONL or WebSocket session: the response arrives when the command has been processed, and any time limit is set by the client itself. The only timeout on the SumDoc side is five seconds for reading an HTTP request in Surface Host.

Exchange contract versions

Contract	Version
Machine-readable description of the session protocol	fastdoc.session-protocol-descriptor.v1
JSONL session readiness	fastdoc.session-serve.v1
Address and token for WebSocket	fastdoc.session-ws-bootstrap.v1
Starting the surface: address, token, version	fastdoc.surface-host-bootstrap.v1
Mounting the surface on your page	fastdoc.surface-mount.v1
Surface event to your application	fastdoc.surface-host-event.v1
Interaction context — proposed	a4.interaction-context.v1, not yet finalized

What this is, and what it doesn’t replace

This describes the verified current boundaries and a proposed external contract. It doesn’t replace an agreed specification: the final addressing types, the support matrix, and availability commitments are part of the pilot’s capability profile.