Skip to content

docs(rcp): publish RCP v1.0.0 spec + stability policy (#35)#41

Draft
Narrator wants to merge 4 commits into
mainfrom
feat/issue-35-rcp-v1-spec
Draft

docs(rcp): publish RCP v1.0.0 spec + stability policy (#35)#41
Narrator wants to merge 4 commits into
mainfrom
feat/issue-35-rcp-v1-spec

Conversation

@Narrator
Copy link
Copy Markdown
Member

Closes #35.

Summary

Lands the public Runtime Context Protocol (RCP) v1.0.0 spec at docs/rcp/v1.md, plus the two decision records that back it (RFC 0001 — package extraction, RFC 0002 — v1 ratification). Together these are the artifact IDE-vendor outreach points at: an explicit, falsifiable stability policy with a schema-level differentiation lever versus runtime-only MCPs.

This PR ships the spec only. Tool-name canonicalization (#33), @domscribe/protocol package extraction (#32), telemetry (#34), SourcePosition schema enforcement (#38), and npm publish (#39) land in their own PRs this sprint.

What's in the spec

  • §0 Design intent — RCP framed as the build-time, framework-aware complement to WebMCP and Chrome DevTools MCP, not a competitor at the same layer. The framing is in the spec itself (not just the release post) because vendors read the spec, not the post.
  • §3 Tools, §4 Prompts — canonical snake_case names per RFC 0002. Dotted aliases through v1.x per §7.4.
  • §5 Wire schemas — ManifestEntry, RuntimeContext, Annotation, ProblemDetails, and now §5.5 SourcePosition as the v1 stability anchor.
  • §6 Error codes — full DomscribeErrorCode vocabulary (22 codes).
  • §7 Stability policy — frozen / additive / breaking rules with two new SourcePosition-specific falsifiability rows in §7.6.
  • §8 — exact @domscribe/protocol package surface (the six-export contract from RFC 0002).
  • §9 References — both RFCs linked.

RFC 0002 deltas in this PR

The prior spec draft (commit b4d99c0 by staff-swe-5) predated RFC 0002. This PR's spec commit (6e5e0b6) folds in the four RFC 0002 decisions:

  1. SourcePosition required on every resolve_* / query_* output — encoded as a schema-level invariant, not a relay convention. New §1 MUST clause, new §5.5, new §7.1 freeze entry, two new §7.6 examples. This is the load-bearing differentiator vs runtime-only MCPs.
  2. snake_case canonical tool grammar — already in the prior draft; preserved.
  3. Six-export @domscribe/protocol package surface — new §8 enumerates exactly what the package exports so consumers know what they can import without grepping the npm package.
  4. Build-time complement framing — new "Design intent" subsection. Honors DOP-memo language without being defensive.

RFC 0001 status moves from Proposed to Accepted (ratified by RFC 0002, sprint 2491) in this PR.

Why RFC 0002 is committed in this PR

Same rationale staff-swe-8 used for RFC 0001 in commit 836f7fa: the spec cross-links to ../rfcs/0002-protocol-v1-execution.md. If RFC 0002 isn't in the branch, the link renders broken on GitHub, failing the "renders cleanly" acceptance criterion. Verbatim PE content, no edits.

Acceptance criteria coverage

  • docs/rcp/v1.md renders cleanly on GitHub — all cross-links resolved within the branch (both RFCs present).
  • Stability policy explicit and falsifiable — §7.1–§7.6 with 11 worked examples; a reader can predict the verdict on a candidate change without consulting maintainers.
  • SourcePosition explicitly named as a v1 stable contract — §5.5 (dedicated section), §1 (MUST clause for servers), §7.1 (freeze list, separate entry).
  • Linked from README + TECHNICAL_SPEC.md — already in commit b4d99c0; verified resolved in this PR.
  • RFC 0001 status moved from Proposed to Accepted — commit 6e5e0b6.

What was tested

The acceptance criteria are documentation-shaped, not code-shaped — there are no tests to run. Verification was:

  • All four markdown cross-link targets (../rfcs/0001…md, ../rfcs/0002…md, README→docs/rcp/v1.md, TECHNICAL_SPEC→docs/rcp/v1.md) exist in the branch.
  • Numbered section references (§3, §5.5, §6, §7.1, §7.6) all resolve within v1.md.
  • The package surface table in §8 matches the RFC 0002 enumeration verbatim.

What was NOT tested and why

Commits

  1. 836f7fa (existing, staff-swe-8) — commits RFC 0001 referenced by the spec.
  2. b4d99c0 (existing, staff-swe-5) — initial v1.0.0 spec + README/TECHNICAL_SPEC cross-links.
  3. b9873cc — commits RFC 0002 referenced by the updated spec.
  4. 6e5e0b6 — aligns v1 spec with RFC 0002: SourcePosition anchor (§1, §5.5, §7.1, §7.6); package surface (§8); RFC 0001 status to Accepted.

Out of scope (deferred to other PRs this sprint)

Concern PR
@domscribe/protocol package extraction #32
snake_case tool registration + dotted aliases at MCP SDK layer #33
Telemetry endpoint (Cloudflare Worker + KV) + relay client #34
SourcePosition schema-level enforcement (Zod) #38
npm publish + non-author install verification #39

staff-swe-5 and others added 4 commits May 28, 2026 11:21
Adds docs/rcp/v1.md — the public Runtime Context Protocol spec
that IDE and agent vendors integrate against. Closes the RFC 0001
workstream 4 deliverable.

- Tools (12) and prompts (4) listed in canonical underscore form
- Wire schemas: ManifestEntry, RuntimeContext, Annotation, ProblemDetails
- Error code vocabulary (22 codes, full DomscribeErrorCode coverage)
- Stability policy: frozen/additive/breaking rules with worked examples
- Aliases-through-one-minor-cycle policy for dotted legacy names
- Cross-linked from README MCP Tools section and TECHNICAL_SPEC.md §3.4

Depends on #32 (@domscribe/protocol package) and #33 (canonical
underscore tool names) for full surface alignment; this PR ships
the spec text. Verifier should sync tool-name tables in README and
TECHNICAL_SPEC after #33 lands.

Refs #35
The v1 spec (`docs/rcp/v1.md`) cross-links to
`docs/rfcs/0001-rcp-as-versioning-unit.md` as the decision record
for extracting `@domscribe/protocol` as the RCP versioning unit.

The RFC was authored by principal-eng during sprint 2371 but had
not been committed to the repo; the spec link would render broken
on GitHub until this lands. Committing here so the spec PR
satisfies its "renders cleanly on GitHub" acceptance criterion
without requiring a separate landing.

Verbatim RFC content — no edits.

Refs #35
RFC 0002 (sprint 2491) ratifies RFC 0001 as Accepted and locks
three deferrals: snake_case canonical tool grammar, opt-in
telemetry shape, and the six-export @domscribe/protocol package
boundary. It also introduces SourcePosition required on every
resolve_*/query_* output as the v1 stability anchor.

The v1 spec (docs/rcp/v1.md) cross-links to this RFC as a
decision record; landing it here keeps the spec PR's 'renders
cleanly on GitHub' acceptance criterion satisfied without
requiring a separate landing PR (same pattern staff-swe-8 used
for RFC 0001 in 836f7fa).

Verbatim PE content — no edits.

Refs #35
…age surface

Sprint 2491 ratified RFC 0001 via RFC 0002, locking three decisions
the prior spec draft predated:

- SourcePosition is a required (non-optional) field on every
  resolve_*/query_* output schema. RFC 0002 names this the
  build-time differentiator vs runtime-only browser-channel MCPs
  (WebMCP, Chrome DevTools MCP). Encoded at the schema layer so
  conformance is testable, not aspirational.
- @domscribe/protocol package surface is a six-export contract.
  Runtime classes (DomscribeError, ID generators, migration
  helpers) stay in @domscribe/core to keep the protocol SemVer
  signal honest.
- RFC 0001 status moves from Proposed to Accepted with a
  cross-link to RFC 0002.

Spec changes:
- New 'Design intent' subsection naming the build-time/runtime
  complement framing without disparaging runtime MCPs.
- New §5.5 dedicated to SourcePosition as the v1 stability anchor
  (with the schema-level enforcement clause).
- §1 Conformance adds an explicit MUST for SourcePosition presence
  on resolve_*/query_* responses.
- §7.1 freeze list elevates SourcePosition presence above per-tool
  schema details; explains why it's called out separately.
- §7.6 falsifiability table adds two SourcePosition rows.
- New §8 enumerates the @domscribe/protocol package surface for
  consumers (former §8 Reference becomes §9, now includes RFC 0002).

Closes RFC 0002 implications-for-PM item (4)'s docs portion for
docs/rcp/v1.md. Tool-rename, package extraction, telemetry, and
SourcePosition schema enforcement land via #32/#33/#34/#38.

Refs #35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Publish docs/rcp/v1.md — RCP v1.0.0 spec + stability policy

1 participant