docs(spec): RFC 10008 QUERY binding + response envelope (S-05/S-06)

[dotnetcadet]

Summary

Completes the two W01 communication specification features on one branch: §4 Protocol Bindings (the RFC 10008 QUERY binding per ratified decision D2) and §6 Communication (the response envelope), plus the committed response-envelope JSON Schema and the golden request/response fixtures that seed the N-03 conformance suite.

This is documentation/spec + committed artifacts only — no library code changes. Every normative point of roadmap §2 D2 (the 8 ratified binding changes) is reflected in §4, and issue #22's registration-path decision is made (vendor tree).

Changes

• docs/specification.md §4 Protocol Bindings — expanded from skeleton into §4.1–§4.11:
  • <Binding>/<Map> element contracts (attributes + rules); routing rules (§4.2).
  • QUERY as the primary read binding with the query text as request body (§4.3), citing RFC 10008 §2/§2.2.
  • Media types application/vnd.ograph.query (request, UTF-8-fixed) and application/vnd.ograph+json (response), with the vendor-tree registration decision per RFC 6838 §3.1/§3.2 (§4.4).
  • The 400/415/422 status taxonomy exactly as D2 point 3 (+ 406 as separate response-negotiation), RFC 10008 §2.1 (§4.5).
  • Accept-Query as an RFC 8941 List without media-type parameters, path-scoped, advertised incl. on OPTIONS (§4.6).
  • Caching/conditionals: caches key on content+metadata, server emits validators (ETag) + Cache-Control, no-transform note, 304 semantics (§4.7).
  • Location/Content-Location re-fetch (§4.8); CORS-preflight note delegating enforcement host-side per D5 (§4.9); OPTIONAL GET ?query= fallback profile (§4.10).
  • Command binding method/payload mapping with the $.query placement marker left to S-07 (§4.11).
• docs/specification.md §6 Communication — response envelope: result shape (§6.1), $nodes single/collection composition (§6.2), recursive $edges (§6.3), per-edge $status/$errors partial-failure semantics (§6.4), $uri re-fetch (§6.5), $count/$total/cursor paging metadata (§6.6), and a table of deliberate deviations from the legacy sketch .designing/_old/responses/response.json (§6.7).
• docs/specification.md Appendix A — one supersession row for the legacy response sketch.
• docs/schemas/ograph-response.schema.json — self-contained JSON Schema draft 2020-12 for the envelope.
• docs/fixtures/ — 12 golden request/response fixtures + README.md manifest.

Work items resolved

Closes #22
Closes #23

Testing & verification

• Programmatic validation with jsonschema 4.26 (draft 2020-12):
  • Schema passes Draft202012Validator.check_schema (valid metaschema).
  • 10/10 envelope-bearing fixtures validate; 2 body-less fixtures (304, 204) correctly skipped; 0 failures.
  • Negative-case sanity checks confirm the schema rejects malformed envelopes (collection missing $count, single with $count, missing $status, error missing message, unknown top-level member, out-of-range status).
• Required-coverage checklist from issue [O01.01.01.06] Specify the response envelope (JSON Schema + golden fixtures) #23 is mapped in docs/fixtures/README.md: basic project, filter+sort+page, edge traversal with nested project, per-edge partial failure (edge 500 / root 200), empty result, 400 syntax, 415 wrong media type, 422 policy violation, conditional 304, GET-fallback — plus Accept-Query/OPTIONS and cursor-paging fixtures.
• Touched only §4, §6, and Appendix A of the spec, per scope.

🤖 Generated with Claude Code