webGCP v0.1 — Standard for the Web Graph Context Protocol¶

Status: pre-implementation working draft (Step 2 of 6 per the underlying standards playbook); zero conformant servers exist yet. Canonical URL: https://webgcp.org/spec/v0.1/ Spec home: https://webgcp.org · Source repo: pending working-group convening (see §11.3); v0.1 markdown is the authoring artifact. License: Spec text under CC-BY-4.0; schemas and fixtures under Apache-2.0 This is not from any standards body. It is a public proposal authored at webgcp.org, intended for eventual donation to a neutral foundation after interop is demonstrated. Peer document: an implementation-shaped companion (BigQuery-backed reference instance, catalog-internal) accompanies this spec at standards/webgcp-standard.md in the maintaining catalog. The two are normative in different registers: this document specifies the protocol; the companion specifies the reference instance's conformance to it. Neither supersedes the other.

Editorial revision: v0.1-ed-2026-05-19 — non-normative only: §1.3 WebMCP-row accuracy refresh, §12 open-questions #5/#10 resolved, §16 review item ticked. The normative body, all /spec/v0.1 + /schemas/.../v0.1.json text/schemas, the conformance fixtures, and the .well-known/webgcp descriptor are byte-unchanged (RFC-errata-style; §10.4 normative immutability preserved).

How to read this document¶

If you read nothing else, read §0 and §1.3.

0. Maturity statement¶

v0.1 working draft. One L0-conformant reference instance is live as of 2026-05-16 at https://the-ai-news.web.app — server descriptor at /.well-known/webgcp, dynamic query endpoint at POST /webgcp/v0/query, conformance fixtures WGCP-L0-001 (happy path, 11 assertions) and WGCP-L0-002 (out-of-scope, 7 assertions) both pass against the live endpoint. L1–L4 are design targets; no L1+ implementation exists anywhere yet. A larger BigQuery-backed reference instance for L1+ conformance is in active build in the MyParallel catalog (M3a backend MCP server).

A ≥3-month production soak of the L0 reference instance is the gate to Step 3 of the underlying standards playbook — the clock started 2026-05-16; earliest Step 3 exit is 2026-08-16. Do not cite this document for L2+ production conformance claims until v0.2.

Anyone is invited to read, file issues, or build their own conformant server. Feedback is the input we need most. Per-section maturity flags throughout the document distinguish drafted target contract from running implementation.

0.5 The "GCP" in webGCP — what it stands for¶

The acronym GCP in webGCP stands for Graph Context Protocol. This document specifies the Context layer — manifests, bundle contracts, typed responses with provenance, applicability checking, L0–L4 conformance for an agent↔server query.

This disambiguation is load-bearing for v0.1 because at least one prior usage in adjacent literature expanded GCP as Graph Commerce Protocol. That usage is not what this document specifies. The two layers are different protocols at different concerns; sharing a domain (webgcp.org) and acronym is a coordination choice, not a merge.

0.6 The Substrate vs. Network Architecture¶

webGCP is the protocol for an agent network that runs on top of an underlying substrate. It is crucial for implementers to distinguish the two:

• The Substrate handles storage, compute, and repository management. A webGCP-compliant substrate MUST provide four properties: (1) stored artifacts with content-addressed identity, (2) typed nodes addressable by URN, (3) MCP-callable surfaces, and (4) HTTPS descriptor exposure (§5.1).
• The Network (webGCP) is the protocol layer that sits on top, standardizing how knowledge, settlement, decrees, and federation work across compliant substrate nodes.

MyParallel is the reference substrate. However, webGCP is fully store-agnostic. Any substrate that provides the four required properties can host a fully conformant webGCP server.

0.7 Context vs. Commerce Layer Split¶

webGCP strictly divides agentic operations into two layers: Context and Commerce.

• The Context Layer governs knowledge retrieval, provenance, applicability (decrees), and bundle contracts.
• The Commerce Layer governs settlement (x402 V2), reputation rollups, and marketplace routing.

This v0.1 specification strictly covers the Context Layer. The Commerce layer is explicitly out of scope for this document and will be governed by future extensions and neighbor standards (e.g., AP2, x402).

While the reference instance may run both layers simultaneously, implementers evaluating this v0.1 specification should focus solely on Context-layer conformance. Any references to Commerce endpoints, receipt ledgers, or settlement wallets in examples are informative previews of v0.2+, not normative v0.1 requirements.

1. Why this standard exists¶

1.1 The gap¶

Agents in production today behave like this: an agent gets a task, decides it needs information, searches, retrieves, evaluates, decides it needs more, searches again, fragments the picture together, loops. Most of the token and latency budget is spent before the model attempts the task. This is the rediscovery tax.

The dominant fix has been better retrieval: better embeddings, better chunking, bigger context windows, smarter rerankers. None of these address the underlying problem, which is that agents are missing a typed contract for the knowledge they need. They ask for "relevant text" and get a probabilistic pile. They cannot say "give me a customer record, a policy, and the prior-ticket history, with provenance, within 500 ms, only if my caller has permission, and refuse if any required field is stale."

webGCP defines that contract.

1.2 The thesis¶

A small set of typed objects, served at predictable URLs, with provenance on every field, can be the substrate for agent-ready knowledge across the web:

• Manifests describe what a knowledge base is for, when it applies, what inputs it needs, what it returns.
• Bundle Contracts describe what an agent needs, as a typed schema.
• KL-Query is the declarative wire format an agent uses to request a bundle.
• Typed Responses carry the bundle with per-field provenance, authority, and confidence.
• Discovery uses .well-known to make any compliant server reachable without prior coordination.

The protocol is implementation-neutral. A compliant server can use BigQuery, Snowflake, Postgres+pgvector, a graph database, a knowledge engine like Pinecone Nexus, or a hand-rolled store. The protocol constrains the shapes agents see, not the stores operators use.

1.3 Relationship to neighboring standards¶

webGCP composes with, does not replace:

A webGCP server that also exposes its tools via MCP and its in-page surface via WebMCP is the expected pattern. Nothing in this spec prevents that.

1.4 Known weaknesses of this draft¶

Stated up front so reviewers don't have to find them:

• Conformance suite is partial. L0 fixtures shipped (WGCP-L0-001 happy-path + WGCP-L0-002 out-of-scope; both pass live against the §13.1 reference instance). L1 fixtures in progress, L2–L4 not yet authored.
• L0 reference instance live; L1+ implementation pending. The L0 surface is deployed at the-ai-news.web.app (see §13.1 — Cloud Function webgcp-query in my-ai-00003, 8 fixture articles, both conformance fixtures pass). L1+ (vector search, multiple primitives, versioned artifacts, refresh SLAs) requires the larger MyParallel BQ-backed instance — myparallel.catalog (19 tables, 230 agencies + 29 skills with 3072-d embeddings) is live but its query endpoint (M3a) is undeployed.
• The federation model (§8) is the least tested part. Single-server deployments will work first; cross-server trust has only been sketched.
• "Applicability" semantics (§5.4) are inherited from the meta-knowledge literature. We have not proven they compose cleanly across domains.
• Cost economics for compile-once / serve-many in federated calls (who pays for the compile when many callers reuse one artifact) are unresolved. See §12, ADR-007.
• The set of retrieval primitives in §5.7 may be incomplete. Hybrid lexical/vector is well-covered; we may be under-specifying graph traversal.

2. Design principles¶

Drawn from what worked in prior standards and what failed.

2.1 Principles we hold¶

1. Contract before vendor. Every artifact in this spec is defined in terms of what agents and operators need to see, not what any particular store provides.
2. Idempotent by construction. A query with the same idempotency key returns the same response (or a typed failure explaining why not). Receipts are append-only and content-addressed. Replaying a query never causes a side effect.
3. Typed all the way down. Manifests, queries, responses, failures — all typed and machine-checkable. Free-text catch-all fields are an anti-pattern.
4. Provenance is mandatory. Every value carries source, timestamp, retriever, and authority. No exceptions, no opt-out.
5. Authority is explicit. Each field is tagged canonical | derived | inferred. Inferred values never auto-promote.
6. Applicability before similarity. Topical relevance is insufficient. A retrieval is valid only when its applicability constraints (scope, branch, time, authority) hold.
7. Minimal core, optional extensions. The core spec is small. Capabilities beyond the core live in versioned extensions, not in the core spec.
8. Discovery is link-driven. No central registry. Servers advertise themselves at .well-known/webgcp. Aggregators MAY exist; they are not the protocol.
9. Stable URLs forever. Once published at a versioned URL, an artifact (manifest, schema, fixture) does not change. New work happens at a new URL.
10. Be liberal in what you accept, conservative in what you emit. Servers parse defensively; servers emit only well-formed, fully-typed responses.

2.2 Lessons-learned, applied¶

These come from MCP's first 18 months, WebMCP's W3C path, Schema.org's adoption arc, the OCI's container standard, and a few cautionary tales.

2.3 Anti-principles (things we will not do)¶

• No proprietary vocabularies in the core. Vendor-specific field names belong in extensions.
• No mandatory cloud dependency. A conformant server can run on a laptop.
• No mandatory ML model. Embedding choice and dimensionality are implementation details.
• No "advisory" security. If it matters, it's MUST. If it doesn't, it's not in the spec.
• No version-skew shrug. Every artifact carries a version and a content hash. Mismatches are typed failures, not undefined behavior.

3. Mental model¶

3.1 The five nouns¶

3.2 Three-layer scope¶

L-server is the heart of webGCP. L-page interop is at the seam with WebMCP (§7.6). L-network interop is federation (§8).

3.3 The flow¶

                +-------------------------+
                |  Agent (any framework)  |
                +------------+------------+
                             | declares Bundle Contract,
                             | sends KL-Query
                             v
                +------------+------------+
                |    webGCP Client SDK    |
                +------------+------------+
                             |
                             v
+----------------------------+----------------------------+
|                  webGCP Server                          |
|                                                         |
|   [Manifest Registry]   [Applicability Planner]         |
|        |                       |                        |
|        v                       v                        |
|   [Composable Retriever] -> KBs (artifacts, stores)     |
|        |                                                |
|        v                                                |
|   [Response Assembler] -> typed Bundle + Trace          |
+----------------------------+----------------------------+
                             | optional federation
                             v
                +------------+------------+
                |     Peer webGCP Servers |
                +-------------------------+

4. Conformance Levels¶

Per §2.2, lessons from Schema.org and OCI: lenient cores get adopted; strict cores get bypassed. webGCP defines five conformance levels. A server claims the highest level it passes.

Levels are cumulative: L2 implies L1 implies L0. Each level has a conformance suite (§9).

A server's .well-known/webgcp document MUST declare its level. Levels are self-declared and externally verifiable against the conformance suite.

5. Normative requirements¶

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, REQUIRED, OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174.

5.1 Server identity and discovery¶

A webGCP server MUST publish a server descriptor at /.well-known/webgcp:

{
  "spec_version": "0.1",
  "conformance_level": "L1",
  "server_id": "urn:webgcp:example.com",
  "operator": "Acme Corp",
  "endpoints": {
    "query": "https://api.example.com/webgcp/v0/query",
    "manifests": "https://api.example.com/webgcp/v0/manifests",
    "schemas": "https://api.example.com/webgcp/v0/schemas"
  },
  "supported_features": ["bundle_contracts", "vector_hybrid", "direct_lookup"],
  "contact": "webgcp@example.com",
  "trust_roots": ["https://example.com/.well-known/webgcp/keys.json"]
}

The descriptor MUST be reachable over HTTPS. It MUST be served with Content-Type: application/json. It MUST be cacheable for at least one hour and no more than 24 hours.

5.1.1 DNS-layer service discovery (SVCB)¶

A webGCP server MUST publish an SVCB record (DNS RR TYPE 64) at the name _webgcp.<host> for each <host> at which it serves the descriptor (§5.1):

_webgcp.<host>.  3600  IN  SVCB  1  <host>.

• SvcPriority MUST be 1 (ServiceMode). AliasMode (priority 0) is reserved for v0.2 cross-host delegation.
• TargetName MUST resolve (via standard DNS resolution) to a host at which the descriptor in §5.1 is served over HTTPS. The canonical case is TargetName equal to the queried host itself.
• SvcParams are reserved for v0.2. v0.1 servers SHOULD NOT include any. Future versions may define SvcParamKeys for webgcp-version, webgcp-conformance-level, and webgcp-descriptor-path once IANA registrations land.
• TTL SHOULD be in the range 300–3600 seconds. Aggressive caching at the DNS layer is acceptable; the record changes only when the operator moves the descriptor.

The DNS record gives agents a sub-millisecond binary signal — "does this domain host webGCP?" — without an HTTPS round-trip. It also lets ecosystem-scanning agents discover webGCP operators across a population of domains at the DNS layer.

Restricted-domain caveat. Operators who do not control authoritative DNS at their conformance hostname (notably: subdomains of .web.app, .firebaseapp.com, .netlify.app, .vercel.app, GitHub Pages .github.io, and similar managed-platform autodomains) MUST NOT claim plain L0 conformance. They MAY instead claim L0-restricted-domain and MUST set conformance_level: "L0-restricted-domain" in their /.well-known/webgcp descriptor, with a restricted_domain_reason field naming the platform. To clear this caveat and claim full L0, the operator attaches a domain whose DNS they control (custom domain via their registrar) and publishes the SVCB record there.

Why this is in L0 (not L1+). Per §2.2's "minimal stable core" + "rough consensus and running code" principles: the cheapest moment to add a new MUST is when the conformance suite is small. The SVCB profile is a 3-line DNS-layer signal; making it an L0 requirement today costs each implementer a single registrar action and gains the entire ecosystem a frictionless discovery path. Adding it after the spec has hundreds of implementations would require a v2.0 break.

Verification. The conformance fixture WGCP-L0-003 verifies the DNS record + the follow-up HTTPS descriptor fetch. Implementations may run it via DNS-over-HTTPS (DoH) against any compliant public resolver (e.g., https://dns.google/resolve?name=_webgcp.<host>&type=64 or https://cloudflare-dns.com/dns-query?name=_webgcp.<host>&type=64) — no dig-equivalent local tooling required.

Operator caveat (empirical, 2026-05-16). Google DoH (dns.google/resolve) has been observed to return an empty Answer array for SVCB queries even when the record is correctly provisioned at authoritative DNS. Cloudflare DoH (cloudflare-dns.com/dns-query) returns the record correctly. Implementations testing L0-003 SHOULD use Cloudflare DoH as the primary verifier. See SVCB-AT-SQUARESPACE.md for the full operator-facing guide, including the byte-level decoding of RFC 3597 generic-format storage (\# 14 00 01 06 ...) which is wire-equivalent to typed SVCB rendering.

RFC 3597 equivalence (normative). Resolvers MAY render the SVCB rdata in RFC 3597 generic format (\# <rdlength> <hex-octets>); this is wire-equivalent to the typed representation and conformant implementations MUST accept either form when verifying §5.1.1 compliance.

First publicly-deployed L0 host on SVCB (2026-05-16). webgcp.org itself is the first publicly-deployed host honoring §5.1.1. Its own spec-host descriptor at https://webgcp.org/.well-known/webgcp declares this_host_svcb_status: "live 2026-05-16". The L0-003 fixture verifies against itself — an agent doing _webgcp.webgcp.org DNS query gets the SVCB record, follows TargetName to webgcp.org, fetches /.well-known/webgcp, and confirms all 9 L0-003 assertions in sub-millisecond DNS + a single HTTPS GET. The spec is self-conformant.

5.2 Manifest schema¶

Every KB MUST have a manifest. The manifest is the meta-knowledge layer: it describes what a KB is for, when it applies, what inputs it needs, and what authority its contents carry.

Manifests MUST validate against the JSON Schema at https://webgcp.org/schemas/manifest/v0.1.json (canonical URL once stub-published; the v0.1 shape is fully specified in the table below).

Required top-level fields:

Manifests MUST be content-addressed (SHA-256 over canonical form). A query MAY pin a manifest hash; if pinned, the server MUST refuse to serve under a different hash.

The full manifest schema will be published at https://webgcp.org/schemas/manifest/v0.1.json. Worked examples will be published at https://webgcp.org/examples/manifests/. (Both URLs are reserved as of v0.1; populated artifacts ship with the L1 conformance package — see §9.1.)

5.3 Bundle contract schema¶

Every agent that issues a webGCP query MUST do so against a named bundle contract. Bundle contracts describe what the agent needs as a typed object.

Bundle contracts MUST validate against the JSON Schema at https://webgcp.org/schemas/bundle/v0.1.json (canonical URL once stub-published; the v0.1 shape is fully specified in the table below).

Each field in a bundle contract carries:

Bundle contracts are versioned (semver) and content-addressed. Agents MUST pin a contract version.

5.4 Applicability¶

A server MUST evaluate each KB's applicability.in_scope_when and out_of_scope_when against the query's filter before retrieving from that KB.

5.4.1 Expression language: CEL¶

Predicate expressions MUST be written in CEL (Common Expression Language). CEL is chosen for its well-defined type system, deterministic evaluation, side-effect-free semantics, and wide implementation availability (Go, Java, C++, Rust, TypeScript, Python).

Each expression string is a single CEL expression that evaluates to bool. The evaluation environment exposes:

Implementations MUST support the CEL standard functions (string, math, list, map, timestamp). Implementations MUST NOT extend the environment with custom functions unless they also declare the extension in their manifest under applicability.cel_extensions[].

5.4.2 List composition: implicit AND¶

in_scope_when and out_of_scope_when are each an array of expression strings. Within a list, predicates compose as implicit AND — all must evaluate to true for the list to match:

in_scope_when:  [A, B, C]  →  A && B && C
out_of_scope_when: [X, Y]  →  X && Y

To express OR within a single predicate, use CEL's || operator inside one expression string (e.g., filter.channel == "retail" || filter.channel == "wholesale").

5.4.3 Precedence: out_of_scope_when wins¶

A KB's applicability is evaluated as:

in_scope  = all(in_scope_when)   evaluates to true
out_scope = all(out_of_scope_when) evaluates to true

KB is applicable  ⟺  in_scope AND NOT out_scope

If out_of_scope_when matches, the KB is excluded regardless of in_scope_when. This is not configurable — the exclusion always wins.

If in_scope_when is an empty array [], the KB is unconditionally in-scope (vacuous truth) unless excluded by out_of_scope_when.

If out_of_scope_when is an empty array [], no exclusion applies.

5.4.4 Missing filter keys¶

If a CEL expression references a key not present in filter, the expression MUST evaluate to false (not error). Implementations MUST use CEL's has() macro or null-safe access (filter.?key) to guard against missing keys, or MUST treat KeyNotFound errors as false at the evaluation boundary.

This means a KB with in_scope_when: ["filter.purchase_channel == 'retail'"] is out-of-scope for a query whose filter does not contain purchase_channel — safe default, no runtime crash.

5.4.5 Worked examples¶

Example 1 — simple channel gate:

{
  "applicability": {
    "in_scope_when": ["filter.purchase_channel == 'retail'"],
    "out_of_scope_when": ["filter.region == 'SANCTIONED'"]
  }
}

Query { "filter": { "purchase_channel": "retail", "region": "US" } } → KB is applicable (in-scope matches, out-of-scope does not).

Query { "filter": { "purchase_channel": "retail", "region": "SANCTIONED" } } → KB is excluded (out-of-scope wins).

Query { "filter": { "purchase_channel": "wholesale" } } → KB is not applicable (in-scope fails).

Example 2 — time-bounded applicability:

{
  "applicability": {
    "in_scope_when": [
      "filter.product_line == 'solar'",
      "now >= timestamp('2026-01-01T00:00:00Z')"
    ],
    "out_of_scope_when": []
  }
}

Both predicates must hold (implicit AND). The KB becomes applicable only for solar queries after 2026-01-01.

5.4.6 Evaluation failures¶

If a CEL expression fails to parse at manifest-load time, the server MUST reject the manifest (validation error). If a well-formed expression produces a runtime error during evaluation (e.g., type mismatch), the server MUST treat that predicate as false and SHOULD log a diagnostic.

5.4.7 Server behavior¶

If no KB is in-scope for a query, the server MUST return a typed out_of_scope failure (§6.7), not synthesize an answer from related-but-inapplicable KBs.

If a KB is in-scope but the query is missing required inputs declared in its manifest, the server MUST return a typed needs_input failure listing the missing inputs.

This is the protocol-level defense against the "franken-answer" failure mode: locally relevant evidence combined across incompatible applicability frames.

5.5 Provenance¶

Every value in a response MUST be accompanied by _meta carrying at minimum:

Servers MUST NOT return values without _meta. Clients MUST NOT consume values without _meta.

5.6 Authority and inference¶

A server MUST tag each value with one of:

• canonical — directly from a system of record declared in the manifest's authority.canonical_sources
• derived — computed deterministically from canonical sources (joins, aggregates, lookups)
• inferred — produced by a model or heuristic that could plausibly be wrong

Servers MUST NOT promote inferred values to canonical automatically. Promotion requires an explicit, audited step that is out of scope for the query path.

5.7 Retrieval primitives¶

A server MUST declare in its descriptor which primitives it supports. The core set:

Additional primitives MAY be declared via extension URIs. An L1+ server MUST support at least three primitives including direct_lookup.

5.8 Idempotency¶

Every query MAY carry an Idempotency-Key header. If present:

• The server MUST cache the response (or its failure) for at least 24 hours
• A subsequent query with the same key MUST return the same response (or failure)
• The server MUST return 409 Conflict with a typed failure if the same key is reused with a different query body

This is non-negotiable for any query whose response may drive a non-reversible action.

5.9 ACL enforcement¶

ACL MUST be enforced at retrieval, before any data reaches the response assembler or any model. Output-side redaction is permitted as defense in depth but is not a substitute.

Denied fields MUST be absent from the response, not present-but-redacted. A redactions_applied array MAY be returned in the trace metadata for audit purposes.

5.10 Untrusted-content handling¶

Content retrieved from KBs MUST be tagged with content_origin:

Clients and downstream agents MUST treat third_party_untrusted content as untrusted for the purpose of tool authorization. Instructions embedded in retrieved content MUST NOT be interpreted as authoritative agent commands.

5.11 Forbidden¶

A conformant server MUST NOT:

• Return values without _meta
• Serve manifests over HTTP (HTTPS only)
• Treat a missing required input as license to guess
• Combine fields across KBs whose applicability frames conflict
• Auto-promote inferred values to canonical
• Cache responses past their declared TTL
• Emit free-form errors (use typed failures, §6.7)

6. Wire format¶

6.1 Transport¶

Queries are HTTP POST to the server's query endpoint. Request and response bodies are JSON. Streaming responses use Server-Sent Events (SSE) over HTTPS.

6.2 Authentication¶

Servers MUST accept Bearer tokens. OIDC and OAuth 2.0 / 2.1 are supported. mTLS is required at L3+ for federation.

The invoker identity carries:

{
  "subject": "agent:<id>",
  "on_behalf_of": "user:<id>",
  "auth_assertion": "<JWT>",
  "mandate_ref": "<AP2 reference, optional>"
}

6.3 KL-Query¶

POST /webgcp/v0/query
Content-Type: application/json
Idempotency-Key: 7b3c...

{
  "intent": "Triage a refund for ticket T-91823",
  "bundle": {
    "contract_uri": "urn:agent:support-refund-triage/v3",
    "contract_hash": "sha256:..."
  },
  "filter": { ... domain-specific filters ... },
  "invoker": { ... see 6.2 ... },
  "scope": {
    "allow_kbs": ["urn:webgcp:acme:*"],
    "manifest_pins": [
      { "kb": "urn:webgcp:acme:policy/refund", "hash": "sha256:..." }
    ]
  },
  "provenance": { "required_fields": ["source_uri", "retrieved_at", "authority"] },
  "confidence": { "min_per_field": 0.7 },
  "budget": { "latency_ms_p95": 800, "max_tokens": 8000, "max_depth": 3 },
  "trace": { "trace_id": "...", "parent_span_id": "..." }
}

6.4 Success response¶

{
  "status": "ok",
  "bundle": {
    "<field>": {
      "value": <any>,
      "_meta": {
        "source_kb": "urn:webgcp:acme:crm/customer",
        "source_uri": "row://customers/C-104a9",
        "retrieved_at": "2026-05-15T19:01:42Z",
        "retriever_version": "v0.1.3",
        "authority": "canonical",
        "confidence": 1.0,
        "manifest_hash": "sha256:..."
      }
    }
  },
  "completeness": "strict_satisfied",
  "trace": { ... },
  "content_origin_summary": { "first_party": 6, "third_party_trusted": 1, "third_party_untrusted": 0 }
}

6.5 Statelessness¶

Servers MUST support stateless operation. Any session-like behavior (caches, partial results, etc.) MUST be reconstructable from the request itself (idempotency key, trace ID) — not from server memory. This makes horizontal scaling and load balancing tractable, learning from MCP's transport-scalability pains.

6.6 Caching¶

Servers SHOULD honor standard HTTP cache semantics. Manifests have Cache-Control: public, max-age=3600 by default; bundle responses are non-cacheable by default unless the server can prove freshness.

6.7 Typed failures¶

Servers MUST return one of these structured failures rather than free-form errors. Each carries enough structure for the agent to act without parsing English.

Free-form 4xx/5xx responses without a typed failure body are non-conformant.

7. Bundle contracts and worked examples¶

A bundle contract is the most important artifact in this protocol from an agent author's point of view. It is the typed signature of what the agent needs to do its job.

7.1 The contract-first method¶

1. Write the agent's mission in one sentence.
2. List the fields the agent must receive to make the decision (the "bundle").
3. Tag each field with source, freshness, authority, ACL, failure behavior.
4. Choose primitives that can deliver each field.
5. Pick the server / vendor / store that supports those primitives.

The contract is the architecture. Stores follow.

7.2 Worked examples published with the spec¶

The following bundle contracts will be maintained at https://webgcp.org/examples/bundles/ as canonical reference contracts. Each will come with a manifest, a fixture corpus, and a complete conformance test set. (URL reserved as of v0.1; populated artifacts ship with L1.)

• Support refund triage — heavy on direct lookups + one hierarchical tree (policy)
• Code review assistant — graph + tree + SQL + direct lookup mix
• Legal clause review — hierarchical trees, defined-term scope, cross-references
• Finance variance analysis — semantic layer dominant; narrative context as tree

These are not normative for the protocol. They are illustrative and serve as the public conformance corpus.

7.3 WebMCP interop seam¶

When a webGCP server has KBs that originate from a WebMCP-advertised webpage, the manifest MUST include a webmcp_origin block:

webmcp_origin:
  page: "https://shop.example.com/products/widget"
  registered_at: "2026-05-12T..."
  webmcp_tools:
    - "addToCart"
    - "checkInventory"

This is how L-page surfaces appear in the L-server registry. WebMCP defines the in-page contract; webGCP carries it forward into persistent knowledge.

8. Federation (L3)¶

8.1 Discovery¶

A webGCP server publishes itself at https://<host>/.well-known/webgcp (§5.1). Discovery is link-driven; no central registry is required.

A .well-known/webgcp/peers endpoint MAY list known peer servers. Aggregators / directories MAY exist as external services.

8.2 Cross-server queries¶

An agent (or planner) MAY issue a query whose scope spans multiple servers. The originating server fans out, validates incoming responses against their published manifests, and assembles the bundle.

Each field's _meta MUST identify the originating server. Cross-server fields are tagged content_origin: third_party_trusted (if the peer is in the trust list) or third_party_untrusted.

8.3 Trust¶

8.4 Forbidden federation behaviors¶

• A peer MUST NOT execute under the receiving server's service identity unless that's an explicit policy
• A peer MUST NOT silently substitute a different KB if the requested one is unreachable; it MUST return kb_unavailable
• A peer MUST NOT auto-trust based on reachability; the trust list is explicit

9. Conformance¶

9.1 Tests are runnable¶

For every normative requirement (§5) and every conformance level (§4), a runnable test fixture will be published at https://webgcp.org/conformance/v0.1/. As of v0.1 (2026-05-16): L0 fixtures live + passing — WGCP-L0-001 (happy path, 11 assertions), WGCP-L0-002 (out-of-scope, 7 assertions), WGCP-L0-003 (DNS-layer SVCB, 9 assertions); 27 assertions total, all pass against webgcp.org's own descriptor + SVCB record (the spec is self-conformant). L1 fixtures in progress, L2–L4 not yet authored. A standard without runnable conformance tests is aspirational; this one will not stay aspirational past L1 completion.

Each test fixture is a JSON file containing:

• A query
• The expected response (or typed failure)
• A reference to the requirement it verifies
• A reference fixture corpus (if needed)

9.1.1 Conformance Claims & L0 Fixture Mapping¶

L0 conformance is verified by a consolidated test suite. While this specification defines 11 distinct normative requirements (across §5.1 through §5.11), the conformance suite safely compresses these into three comprehensive fixtures:

• WGCP-L0-001 (11 assertions): Collectively exercises the normative requirements for discovery, applicability gating, provenance tracking, and typed responses.
• WGCP-L0-002 (7 assertions): Exercises out-of-scope boundaries, rejection handling, and typed failure modes.
• WGCP-L0-003 (9 assertions): Exercises DNS-layer SVCB discovery (§5.1.1), descriptor fetch, and spec-host self-conformance.

An implementation is L0-conformant when it passes all three fixtures, successfully validating all 27 assertions. The reference implementation currently passes all fixtures in production.

9.2 Self-declaration¶

A server claims a conformance level by:

1. Running the test suite for that level against itself
2. Publishing the results at https://<host>/.well-known/webgcp/conformance.json with a signed timestamp
3. Declaring the level in its server descriptor (§5.1)

Conformance is self-declared. External verification is possible because the tests are public.

9.3 Conformance test ID convention¶

9.4 Adversarial suite¶

At every level from L1 upward, the adversarial suite MUST pass to claim that level. The suite is specified below and authored in v0.1; the runnable fixtures land with the L1 conformance package. These are not aspirational; they test the security claims of the spec.

10. Versioning¶

10.1 Spec versioning¶

webGCP follows semver:

• 0.x — pre-stable, breaking changes allowed between minors
• 1.0 — stable, breaking changes only at majors
• 1.x — backwards-compatible additions only
• 2.0 — requires a transition period and an upgrade guide

10.2 Per-artifact versioning¶

Each manifest, bundle contract, and conformance fixture carries its own semver and is content-addressed. The spec version and the artifact versions evolve independently.

10.3 Stability gate (v1.0 promotion criterion)¶

Borrowed from IETF's rough-consensus-and-running-code tradition. Promotion of a feature from v0.x-draft to v1.0-stable requires:

1. The proposed text has passed working-group review (no WG is convened as of v0.1; see §11.3)
2. Two interoperable implementations exist and pass the conformance suite for that feature
3. At least one production deployment of each

No feature is stable on paper alone. As of v0.1, zero features have cleared this gate; the entire spec is v0.1-draft.

10.4 Permanent URLs¶

https://webgcp.org/spec/v0.1/ is immutable. Edits go to v0.2, v0.3, etc. The https://webgcp.org/spec/ redirects to the current version.

Schemas at https://webgcp.org/schemas/manifest/v0.1.json are immutable. Same convention.

This is the "stable URLs forever" principle (§2.1 #9) made operational.

11. Governance¶

11.1 Today¶

Single-author / small-group governance, transparently. The v0.1 source-of-record is at https://webgcp.org/spec/v0.1/. A github.com/webgcp/ organization is pending and will host the issue tracker and conformance fixtures once a working group is convened (see §11.3). Until then, issues and feedback can be filed via the contact listed at https://webgcp.org/.well-known/webgcp (operator field).

11.2 Contributor ladder (forward-looking)¶

Status as of v0.1: only level 1 (community participant) is staffed. Levels 2–5 will fill as activity warrants.

Drawn from MCP's stated 2026 governance maturation, applied early:

1. Community participant — anyone who reads, files issues, opens PRs
2. Working group contributor — sustained contribution in a specific area
3. Working group facilitator — runs a WG
4. Lead maintainer — owns a major component
5. Core maintainer — owns the spec direction

We will not staff levels 4–5 until level 1 has people in it.

11.3 Working groups (forward-looking)¶

Status as of v0.1: no WG is convened today. The list below is the planned topology for when activity warrants.

When activity warrants, working groups will form around:

• Transports & Sessions WG — wire format evolution, statelessness, sessions
• Manifests WG — manifest schema and applicability semantics
• Federation WG — discovery, trust, cross-server identity
• Conformance WG — test suite, fixtures, levels
• Security WG — threat model, adversarial suite, advisories

A WG owns SEPs (Spec Enhancement Proposals) in its area. Core maintainers retain strategic oversight.

11.4 Eventual donation¶

When two or more interoperable implementations exist and at least one external production deployment is using webGCP, we will approach a neutral foundation for donation. Most likely candidates, in order of fit:

1. Linux Foundation / AAIF — most natural fit; MCP, goose, AGENTS.md are already there; agent-infrastructure focus
2. W3C — if the WebMCP interop and federation-over-the-web angles dominate
3. CNCF — if cloud-native deployments dominate
4. Independent foundation — last resort; only if existing bodies are a poor fit

Donation does not change technical direction. It changes governance neutrality. We will not donate before there is something worth giving.

11.5 What we will not do¶

• Form a foundation prematurely. A board without users is theater.
• Sign sweetheart deals. No vendor gets early access to spec changes in exchange for adoption.
• Pivot to a product. webgcp.org is the protocol's home, not a company's marketing site. If we ever build a commercial product, it lives at a separate domain with separate branding.

12. Open questions¶

These are tracked, not deferred. Each will get an ADR before v1.0.

1. Manifest language — YAML surface with JSON Schema, or CUE-based? Current: YAML.
2. Embedding model neutrality — confirm we have not snuck in any model-specific assumption. The spec must work whether the operator uses Cohere, OpenAI, a self-hosted model, or none.
3. Cost economics in federation — when an artifact is compiled once and served to many federated callers, who pays for the compile? Advisory pricing in _meta?
4. Graph as first-class vs. one-primitive-among-several — the "G" in webGCP suggests graphs are central. Currently they are not privileged. Decide before v0.2.
5. WebMCP draft tracking — resolved (editorial 2026-05-19, non-normative): webGCP v0.1's WebMCP-interop surface (§1.3, §7.3 webmcp_origin) is pinned to the W3C Web Machine Learning CG WebMCP draft as of 2026-02-10 (navigator.modelContext). WebMCP breaking changes (e.g. the observed navigator.ai.* → navigator.modelContext.* rename) are absorbed by re-pinning in the next webGCP version — never by mutating immutable v0.1 (§10.4). Any webmcp_origin API-name realignment is a v0.2 item.
6. Right-to-delete fanout — across federated servers, deletion is a multi-party operation. Need a sub-protocol.
7. Receipt protocol — currently MAY. Promote to MUST at L2 governance level?
8. Vocabulary registry — should webGCP host a recommended-but-not-required vocabulary for common bundle field types (Schema.org pattern)?
9. Conformance suite governance — who can submit new conformance tests? Working-group review, or open PR?
10. Browser-side webGCP — resolved (editorial 2026-05-19, non-normative): boundary confirmed correct as-is. webGCP stays server-side only; the browser-side surface is WebMCP's responsibility, joined at the §7.3 / §7.6 L-page seam. Revisit only if WebMCP gains server-side persistence/federation (it does not, as of the 2026-02-10 draft).

13. Reference implementations¶

Implementer's companion: the construction sequence, gates, common pitfalls, and stack-substitution guide for building to L0 lives at https://webgcp.org/request-for-development/. Read it alongside this section — it's the "how" to this section's "what."

13.1 L0 reference instances (live, 2026-05-16)¶

Two L0 reference instances are publicly deployed as of 2026-05-16:

13.1.1 webgcp.org — first publicly-deployed L0 host honoring §5.1.1 (SVCB)¶

https://webgcp.org is the spec host AND the first publicly-deployed host honoring §5.1.1's DNS-layer SVCB MUST. Its own spec-host descriptor at https://webgcp.org/.well-known/webgcp declares this_host_svcb_status: "live 2026-05-16 — SVCB record provisioned at Squarespace DNS (TTL 14400)". The spec is self-conformant — the L0-003 fixture verifies against itself.

Because webgcp.org is the spec host, not a knowledge server, its descriptor carries role: "specification_authority" instead of conformance_level: Lx. The §5.1.1 SVCB MUST applies to any host serving the descriptor — spec hosts included.

13.1.2 the-ai-news.web.app — first publicly-deployed L0-restricted-domain reference server¶

https://the-ai-news.web.app — the first publicly-deployed Web Graph Context Protocol reference server, currently at L0-restricted-domain per §5.1.1's restricted-domain caveat (Firebase's .web.app zone does not allow operator-managed SVCB records). Full L0 conformance requires attaching a DNS-controllable custom domain.

Implementation: ~280 lines of Python (Flask + functions-framework) deployed as Cloud Function Gen2 in GCP project my-ai-00003 / us-central1, backing service webgcp-query. Bundled fixture articles spanning the 8 manifest categories for deterministic demo; the function exposes a one-flag swap to live Firestore when the operator wants real-time data. Source maintained in the the-ai-news repository.

The-ai-news also runs a separate Commerce-layer stack (x402 USDC settlement, agent marketplace, graph-authority routing) — per §0.7, Context and Commerce are composing layers that share an operator but neither subsumes the other.

13.2 L1+ reference instance (in build)¶

A larger BigQuery-backed instance is under active build in the MyParallel catalog. The substrate is live (myparallel.catalog, 19 tables, 230 agencies + 29 skills with 3072-d gemini-embedding-001 embeddings, backfilled 2026-05-16) but the query endpoint that exposes it via this protocol is in-development (M3a backend MCP server). When M3a ships, the MyParallel BQ instance becomes the L1 candidate — vector search via embed_text() UDF over catalog.entities.embedding, multiple retrieval primitives (vector + direct lookup + graph traversal), versioned artifacts. Public read access to the BQ dataset will be provided as a reference for the schema; the dataset is an implementation, not the standard.

13.3 Goals (third reference implementation, pre-WG)¶

A clean-room, vendor-neutral third reference implementation — currently unwritten — is intended for ease of adoption. Source will live at https://github.com/webgcp/reference-server and https://github.com/webgcp/reference-client once a GitHub organization is registered (pending working-group convening — see §11.3). Until then, the v0.1 draft is at https://webgcp.org/spec/v0.1/.

Goals:

• L0 conformance in under 1000 lines of TypeScript
• L1 conformance in under 2500 lines
• Runnable on a laptop with no cloud dependencies for the L0 demo
• A docker compose up brings up a complete L0 server with one example KB and one bundle contract

The L0 instance at the-ai-news.web.app (§13.1) proves feasibility — one impl exists in production. The L1+ instance (§13.2) will prove the larger-data + retrieval-primitive picture. The third (clean-room) instance will prove the spec is implementable by an outside reader from text alone. Step 4 (second-implementer test) of the underlying standards playbook is met when a non-author ships a conformant server against this spec; until then the standard is single-implementer and remains v0.x-draft.

14. Glossary¶

• Applicability — the property that a KB's contents are valid evidence for the current query, given scope, branch, time, and authority constraints
• Artifact — a pre-compiled, persistent, task-shaped representation of source data; indexed for fast serving
• Authority — the trust class of a value: canonical, derived, or inferred
• Bundle — the typed object an agent receives in response to a query
• Bundle contract — the typed schema describing what the bundle MUST contain
• Canonical source — the system of record for a fact
• Compile (verb) — the build-time process that transforms source data into artifacts
• Content origin — the trust classification of retrieved content: first_party, third_party_trusted, third_party_untrusted
• Federation — cross-server query, discovery, and trust
• Idempotency key — a client-provided identifier that allows safe retry without side effects
• Manifest — the agent-readable contract for a KB
• Meta-knowledge — knowledge about what a KB is for, when it applies, what inputs it needs
• Provenance — per-field metadata establishing where a value came from
• Trace — the auditable record of a query

15. Acknowledgments¶

This spec draws on prior art from:

• MCP (Anthropic, AAIF) — JSON-RPC tool-calling protocol; introduced the well-known-discovery and .well-known/mcp.json pattern
• WebMCP (W3C CG) — browser-side agent tool exposure; the in-page seam
• Pinecone Nexus / KnowQL — declarative agent query language and knowledge-compilation pattern
• Microsoft GraphRAG — automated graph construction and hierarchical community summaries
• Schema.org — vocabulary-as-dictionary adoption pattern; lenient core
• OCI — minimal stable core; explicit backward-compatibility commitment
• IETF RFCs (2119, 8174, 8446) — normative keyword conventions; rough-consensus-and-running-code
• JSON Schema — schema-as-artifact at stable URLs
• The applicability / meta-knowledge literature — manifest-based runtime checks before retrieval

webGCP is not original work in concept. Every individual idea is borrowed. The contribution is the typed integration of these ideas as one protocol, with stated conformance levels and runnable tests.

16. Checklist for review¶

If you are reviewing this draft, the most useful feedback addresses:

• [x] §1.3 accuracy — reviewed/refreshed editorial 2026-05-19 (WebMCP: W3C Web ML CG draft, navigator.modelContext, Chrome early-preview, no centralized discovery — the gap webGCP fills). Non-normative; normative body unchanged.
• [ ] Are the conformance levels in §4 the right cuts? Are the gates between them defensible?
• [x] §5.4 (applicability) — resolved v0.1.1: CEL chosen as expression language; implicit-AND composition; out_of_scope_when overrides; missing-key → false; worked examples added.
• [ ] §5.5 (provenance) — is the required _meta set minimal-but-sufficient?
• [ ] §6 (wire format) — is anything ambiguous? What would two independent implementations disagree about?
• [ ] §7 (bundle contracts) — does the contract-first method survive contact with a domain you know well?
• [ ] §8 (federation) — what's missing? What's overspecified?
• [ ] §9 (conformance) — can the tests as described be run by a third party against any server?
• [ ] §11 (governance) — is the staged approach (small now, donate when interop demands it) credible?
• [ ] §12 (open questions) — which is most urgent to resolve?

File issues via the contact in https://webgcp.org/.well-known/webgcp (operator field), or — once a working group is convened (see §11.3) — at the github.com/webgcp/ issue tracker. Specific quotes and counter-proposals welcome; unstructured "I don't like X" less so.

End of v0.1 draft.