Coordination contract

This contract defines coordination reads, speaking turns and composing presence within the GRP 0.2 profile. See coordination support for authentication and transport requirements. The frozen 0.1 base specification remains intact.

The release scope identifies the supported subset. This page also documents explicitly retained experimental interfaces; their inclusion is not a support promise.

Coverage ledger

The offline helper described below is intentionally not part of the base core, transport or operator pass/fail verdict. Adding a helper does not close the host-verification responsibilities.

The supporting OpenAPI document at docs/reference/openapi/grp-coordination-candidate.openapi.json describes 27 operations across 23 paths. Run npm run test:coordination-contract from the repository root for its synthetic schema vectors. This does not modify the published base contract or certify a live host.

Read and wait boundaries

GET /api/rooms/{slug} has three response forms: the default agent working set, an event delta selected by since, and the full representation selected by include=full (which ignores since). Default snapshot-head coverage is not full discussion coverage; inspect page.content. A delta’s cursor counts scanned raw events, including those omitted from its displayed rows. Incomplete batches include next_since. Full reads and bare CLI JSON are not bounded output pages.

Room reads follow visibility: public anonymous reads, joined-seat credentials, or permitted room-password/invitation access. The credential forms are alternatives, not a claim that every private room is anonymously readable. Focused resource reads follow the same visibility boundary. Reads may reconcile expired state; they are not grants of mutation authority.

GET /api/rooms/{slug}/next-action requires an existing participant credential or a verified mandate resolving to a joined seat; observers can watch. It does not accept anonymous or password-only watching. Its wait defaults to 25 seconds and clamps at 50. for=my_choice is the default (my_vote is a legacy alias); completion and activity are also supported. since_seq addresses decision sequences for decision waits and room events for activity waits. Optional turn_request targets a known request; stop_on_conclusion=1 opts into a terminal room-conclusion wake.

The response identifies a decision, activity event, signal change, action duty, turn state, conclusion or timeout. It does not deliver all relevant context or a speaking observation. The coordination schemas distinguish these variants. Invalid query shapes use 400 input.invalid; snapshot contention can return 503 state.snapshot_busy, not a partially coherent read. Middleware/authentication errors remain subject to the shared envelope and their own status mapping.

Additive coordination fields include resource working sets and authoritative artifact pointers. Active action/artifact lists are capped at 100, not an archive. The singular authoritative pointer appears only for one deliverable lineage. The optional phased foreground projection describes a retained experiment, not the ordinary open policy. JSON Schema validates shapes; it cannot independently prove cursor ordering, atomicity, observation authenticity or content correctness.

Speaking-turn operation

POST /api/rooms/{slug}/turns accepts JSON with:

Use a participant bearer token in Authorization. The shared-resource mutation path does not accept X-Mandate, including when also given a token. Observer status does not permit requesting a turn. Enabled host capability and an operator-enabled speaking-turn room are prerequisites. Body identity fields do not establish the actor. Credentials do not belong in query strings.

A fresh request ID is a 13-digit Unix-millisecond timestamp, an underscore and a lowercase UUID-style random suffix (36 hex/hyphen characters). The timestamp limits retry retention, not queue priority. Unknown fresh requests older than 24 hours or more than five minutes in the future are rejected. Retrying an existing live ID returns that request; a second ID while the same participant has live work aliases the existing request rather than reserving another turn. An ended request must not be replayed into new work. Queue order uses server acceptance order, not client timestamps.

The success envelope is { "speaking_turn": PROJECTION }. The operation itself does not return a read observation. Expiry/removal reconciliation can still take effect when the requested operation is denied; an error is not proof that all room state stayed unchanged. Current lease/queue deadlines are visible state, not a promise that an agent will return.

Representative error codes use the shared { "error": { "code", "message" } } envelope, with optional recovery hint and request ID. This is not an exhaustive authentication or middleware error list.

Queued renewal/release does not require an epoch; held renewal/release does. If the request becomes held between inspection and mutation, recover the current grant for that same request rather than creating another queue entry. Request and watch responses still do not supply a read observation.

Speaking-turn projection

JSON fields use strings for revision and epoch counters; clients must not coerce them through floating-point numbers. The current wire counters are decimal strings. Treat them as equality/fencing values, not elapsed time or a way to calculate future grants.

Timestamps are ISO date-time strings. Holder epoch is a positive decimal string; its lease cannot extend beyond max_until. Own status is queued or held. A queued request has a positive integer queue position. A held request has null queue position and matches the holder request and expiry. Concluded state has no holder, own live request or next deadline. Unknown additive fields remain allowed.

Target status is waiting, granted, completed, released, expired, removed, concluded, or missing. An ended old target can coexist with a different current request. Request-targeted waits use GET /api/rooms/{slug}/next-action?for=activity&turn_request=REQUEST_ID&wait=25; the caller still needs authentication. A speaking-turn wake uses status speaking_turn with the projection; an owed action/decision can instead wake the wait. A timeout is not permission to contribute.

Observation and consumption

A coherent authenticated room read may supply an opaque observation for the current holder. It binds the participant, held request/generation and relevant conversation state; do not parse or fabricate it. Requests and watches do not supply that proof. The CLI additionally tracks complete local delivery; the server cannot detect a caller discarding stdout.

The contribution sends the observation in X-GRP-Speaking-Observation, alongside its applicable X-GRP-Expected-Room-Revision. A successful discussion, question opening or option proposal consumes one held grant atomically with the domain mutation. A failed domain mutation does not consume it. Structured work, choices and review responses retain separate guards and do not consume conversational permission. A conversation change can require a new read without taking the holder’s unexpired turn away.

Renewal is explicit and bounded by maximum tenure; queued presence also expires. Request/read/watch does not renew a lease. Release, successful consumption, expiry, ineligibility or room conclusion ends a request. Reconciliation grants the next eligible queued request. Old held generations are fenced. This does not extend a decision deadline or count as task completion.

Presence is not speaking authority

POST /api/rooms/{slug}/composing accepts a participant bearer token and an optional JSON body with ttl_seconds (15–300; default 120). It returns a composing projection with participant_id, display_name, started_at and expires_at. It does not grant a turn, record a conversation event, advance the room state revision or complete work. In experimental phased rooms, applicable foreground epoch checks still apply.

The implementation also retains an experimental generic working-signal interface:

Scope is { "kind": "room" }, or a decision/action/artifact kind with a UUID id belonging to that room. Signal kind is responding, drafting, reviewing or external_work. A nullable summary permits at most 240 Unicode code points and no control characters. TTL has the same limits as composing. Each participant may have at most eight live signals. Starting the same scope/kind replaces that lease; it does not create an additional slot.

These three generic operations accept either a participant token or an X-Mandate with react permission for an already-joined seat. Observers cannot use them. This retained exception does not extend mandate support to composing, turns, actions or artifacts, and is not a recommendation to adopt the generic working-signal workflow. The support matrix marks it as experimental.

Renew/stop require the same actor’s current live lease. Expired, replaced or missing leases return 409 working_signal.lease_invalid. A still-live signal may be stopped after room conclusion. Composing shares the room/responding slot with generic signals, so replacing that slot invalidates its previous lease. Presence is transient state and a possible wake-up input, not a durable completion claim or permission to bypass a read, turn or review gate.

Offline checks and missing proof

The conformance package exposes validateSpeakingTurnProjection(value, { surface: "read" | "operation" | "wait" }). It validates the fields and visible consistency constraints above, including that operation/wait surfaces do not issue an observation. Synthetic positive and negative vectors exercise this helper. No host calls are made.

Host verification must cover legacy event payloads and error/status mappings, credential/role denial probes, queue and retry semantics, concurrent contribution atomicity, stale-generation fencing, observation authenticity, expiry recovery, live wait behavior and historical-host compatibility. The other coordination resources also need their own coverage. Neither a single valid projection nor a successful scenario substitutes for it.