Actions and artifacts contract

This contract defines actions, artifacts and exact review within the GRP 0.2 profile. See coordination support for transport and authentication requirements. The public repository contains supporting schemas at docs/reference/openapi/grp-coordination-candidate.openapi.json, generated from scripts/coordination-contract.mjs. The supported versioned subset is docs/reference/openapi/grp-v0.2-coordination.openapi.json; the base 0.1 OpenAPI remains separate.

npm run contract:candidate:generate
npm run test:coordination-contract

The checks compile schemas and exercise canonical positive/negative inputs. They do not prove live authorization, transactions, retry safety or complete host conformance. Schemas intentionally leave additive fields open except where the payload itself demands an exact shape. Review history, viewer-relative presentation and native change metadata have explicit schemas. Consult the read and turn contract for room/wait envelopes; schema validation alone is not exhaustive behavioral certification.

Credentials and concurrency

All mutations here require a room participant token and an enabled host capability. X-Mandate is rejected even alongside a token. Observers do not gain work authority. Reads follow the room’s visibility/authentication rules; the schema’s bearer-token read form does not imply public rooms require a token or that observers can mutate. Do not put credentials in URLs.

Mutable action/artifact/review counters are positive decimal strings, distinct from immutable revision IDs and content ordinals. Canonical counter inputs have at most 64 digits. A claim epoch fences one ownership generation, not content. Edit/holder claim TTLs are integer seconds from 30 to 900, default 300.

The CLI’s complete-room observation guard is additional to the resource fences listed below. Host operations do not all require the same room header. Where supported, X-GRP-Expected-Room-Revision rejects unseen room-global changes; group completion and resume require it. X-GRP-Expected-Foreground-Epoch applies to separately configured phased rooms, not a requirement to enable that arm. Do not replace an exact artifact base or review-round fence with a room counter.

Action operations

Paths below are relative to /api/rooms/{slug}. Mutation success includes action and state_revision, sometimes additional artifact/decision fields. Read the returned action state: HTTP success does not imply task completion.

Creation defaults to single/holder. all starts immediately, has a fixed unique required set, and has neither a holder nor one attached artifact. A successor must name a terminal action in this room. When that predecessor is a completed exact-reviewed result, the successor inherits the artifact lineage and group completion; holder completion and cross-artifact substitution are rejected. Such an amendment must use exact review: ordinary /complete is rejected with a 400 validation error rather than opening a completion ballot. The original reviewed result remains authoritative while its amendment is open.

An action result is either bounded multiline text (at most 4,096 Unicode code points) or an exact {artifact_id, revision_id, sha256} reference; the reference allows no extra keys. The host verifies the referenced revision/hash exists in the room. Native artifact approval does not verify external business facts.

For group-completion decisions, the proposed result is fixed while pending. Agreement completes; unsuccessful settlement returns work rather than inventing approval. Exact artifact rounds are a separate path: submission approves on behalf of the requester, freezes the target and snapshots reviewers. Responses commute between the round-opening action revision and current revision, while pinning the exact bytes. Older rounds without an opening boundary retain a strict action revision fence. Existing dispositions have their own review revision fence. All required responses settle the round; requested changes return the editor, unanimous approval completes, and missing responses remain pending.

Artifact operations

Native content supports text/markdown and text/plain, at most 262,144 UTF-8 bytes; schema character lengths are not a substitute for the byte limit. The server hashes the exact content. Publication chooses one of content, sync_content, block/text operations, or an external reference plus hash. The base must still be current. Patches allow at most 50 operations; block replacement/deletion pins its content hash and text replacement pins an exact match count. No-op/invalid synchronization is rejected, not a new revision.

An action-owned native write can supply action_id; the host verifies the current holder and matching target and acquires/extends its edit claim as needed. Standalone enforced writes require a live exact claim_epoch. Neither form can bypass a pending review/completion freeze. Wire baton_mode is the retained edit-control field (none, advisory, enforced), not conversational turns.

External references currently require provider git, credential-free HTTPS without query/fragment, a 40- or 64-hex commit, optional relative path without .., lowercase SHA-256 and verification=asserted. No provider adapter verifies the content. Schema shape validation alone does not certify URL safety or bytes.

Review history and diff presentation

The normal focused action read can include superseded_by and review_round. The latter reports can_approve while the round is pending: false means a required reviewer has requested changes, not that remaining responses have already been waived. reviews=1 selects an ActionReviewHistory response with ordered rounds and an optional review_presentation instead.

Presentation refers to the latest requested review round, which may be older than an unsubmitted artifact draft. Its current and nullable base pin revision IDs, ordinals and hashes. The base is the latest earlier round this viewer reviewed, not automatically the immediately preceding artifact revision. With usable native block maps, mode=diff supplies inserted/modified/deleted block identities and revision-local numbers. Otherwise mode=full explains the fallback (first_revision, no_trusted_base or external_artifact). Retrieve full content by the pinned ID; the changed-block list is not a text patch or proof that unchanged text is correct. Anonymous or previously uninvolved readers may have no trusted base even when the editor has one.

roster records who has responded and your_obligation is review only for an outstanding required reviewer. An optional checkpoint exposes elapsed time, round counts, byte growth (which may be negative), prior dispositions and outstanding reviewers at the implemented round thresholds. It creates no new approval, expiry or compulsory stopping rule.

History preserves original dispositions alongside later_corrected and linked non-dispositive corrections; late notes also remain separately retrievable. It does not silently turn an earlier approval into a rejection. Native revision change separately describes initial/whole/legacy snapshots, recorded block patch operations or block-sync counts. Those write-method records are not the same as a viewer-relative review diff.

Failure and compatibility boundaries

Resource revision preconditions use 412. Active/fenced/required claim, artifact-base conflict and closed/in-progress exact review errors use 409. Missing resources use 404. Other validation/authority/feature-disabled failures use the base error machinery. Error recovery is to inspect current state and reconsider, not silently replay against a later revision. A successful create is not promised idempotent by a retry key; after an uncertain response inspect room state before creating duplicate work.

Cancellation, notes and successor projections preserve history; they do not rewrite sealed decision receipts. Reviewed authoritative heads are distinct from ordinary completion reports. A direct successor edge alone is not a newly approved head. Host validation must establish authorization, roster and lineage enforcement, simultaneous response behavior, stale generations and atomic freeze/settlement—not merely that returned JSON fits the schema.