Skip to content

Make SourcePosition required on every resolve_*/query_* output schema #38

@Narrator

Description

@Narrator

Sprint 2491 — task T2 (Batch A)

Implements RFC 0002 §3.4 — the load-bearing differentiation lever for the "build-time complement to WebMCP / Chrome DevTools MCP" positioning.

Background

Per RFC 0002, source location (file path + 1-based line + 1-based column) is not metadata — it is the differentiator versus runtime-only MCPs. We must encode this at the schema layer, not as a relay-side convention, so a v1 consumer can rely on it and we cannot regress without a major bump.

Scope

  • Add a required SourcePosition block to every resolve_* and query_* MCP tool output schema in @domscribe/protocol
  • SourcePosition shape: { path: string, line: number (>=1), column: number (>=1) }
  • Update relay emission so every response includes a real source position (no null, no sentinel)
  • Test suite must FAIL the moment any resolve_/query_ tool returns an output without a valid SourcePosition
  • Update @domscribe/protocol README + docs/rcp/v1.md stability policy: SourcePosition is a v1 stable contract; absence is a protocol violation

Acceptance

  • Zod schemas for resolve_* and query_* outputs reject responses missing source_position
  • Relay emits a valid SourcePosition for every resolve_/query_ response in integration tests
  • Schema tests fail (red) on a deliberately broken relay; pass (green) on the corrected one
  • docs/rcp/v1.md calls out SourcePosition as the v1 stability anchor

Depends on

#32 (@domscribe/protocol package must exist before schemas are tightened).

Risk (from RFC 0002)

Required SourcePosition is a forward-compat trap if a future use case legitimately needs to return a result without an AST origin (synthetic/computed elements). Acceptable in v1 — bumping major for v2 is the explicit alternative.

Out of scope

  • Synthetic-element handling — defer to a v2 RFC if/when the use case is real
  • Backfilling SourcePosition on non-resolve/query tools — those don't carry the same semantic guarantee

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestpriority:P0Urgent — security, data loss, or critical regressionrcpRuntime Context Protocol — public spec workstreams

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions