RAOS-0000Draft · RFCv0.1.0June 2026Plane 0 · Foundation

Protocol Foundations, Context & Conformance

com.os.retailagent.shopping.core

The meta-spec every other RAOS spec imports · See the manifest in the Profile viewer

This is the shared substrate — the context object, the conformance ladder, the manifest, versioning, reasons, and degradation. It is an open draft. If a rule here is wrong, that's the most useful thing you can tell me. See the open questions →

Abstract

RAOS-0000 defines the shared substrate every other RetailAgentOS spec builds on. It is deliberately small and deliberately load-bearing. Five things live here and nowhere else: the BuyerContext object, the conformance-tier ladder and /.well-known/ucp manifest, the versioning contract, the unified ReasonEntryenvelope, and the provenance & freshness envelope.

It does not redesign the extension evaluator contract or the staged pipeline (Visibility → Eligibility → Price → Fulfillment → Quote) — those are owned by the architecture doc and referenced here. This spec defines the nouns and rules; the architecture defines the machine that runs them.

Why a foundation spec exists

Every RAOS spec answers one merchant-reasoning question — but each needs the sameprimitives: a buyer to evaluate against, a way to declare which contracts a merchant supports, a shared vocabulary of reasons, a rule for missing or stale data, and a promise the contract won't shift under a consumer's feet.

If each spec invents its own copy of these primitives, the series is a pile of incompatible extensions, not a platform.
The whole leverage is that a platform implements the substrate once — and every merchant inherits agent-readiness.
Every other spec's "Inputs" section references the BuyerContext defined here, not its own copy.

The buyer context

BuyerContext is the evaluation environment — buyer-scoped facts only: who is shopping, on what terms. Merchant facts (which extensions are active) do not live here; they live in the negotiated session manifest.

loyaltyTier is not a conformance tier. The buyer's gold/silver/guest standing answers who is shopping and is a claim owned by RAOS-0009. It is never a rung on the conformance ladder, which answers what the merchant can do. A guest can shop a Member-aware merchant. loyaltyTier (consumer loyalty, RAOS-0009) and membershipTier (B2B account standing, RAOS-0001) are themselves two orthogonal fields — neither subsumes the other — making three distinct identity axes in all.

Trust model (B6)

Claims arrive signed (verified envelope → trusted) or asserted (agent's word — simulated default). An untrusted privilege-granting claim falls back to guest / most-restrictive. The merchant trusts the signature, not the agent.

Unknown → most-restrictive

Any field the agent doesn't supply defaults to its most-restrictive interpretation: unknown customer type → guest, unknown region → region-gated items restricted.

Conformance tiers

A conformance tier describes a merchant's implementation maturity — cumulative, nested. It is orthogonal to a buyer's loyalty tier. Conformance ≠ buyer loyalty is the single most important rule in this spec.

Tier	Name	What the merchant can do	Archetype
0	Discoverable	An agent can find and correctly read my catalog.	Any store
1	Qualified	No dead-end carts — only eligible, in-stock items surface.	Boutique
2	Priced	The right price per buyer, honored at checkout.	Wholesale
3	Member-aware	Supports member-aware pricing, earn preview, subscriptions.	Grocery
4	Assisted	Full commerce — fulfillment, handoff, intent, returns.	Grocery chain

How a merchant declares what it supports

A merchant publishes a headline tier number (a maturity summary) backed by an authoritative capabilities[] list of the extensions it actually supports. Agents negotiate on capabilities[], never on the ladder — so a Tier-2 merchant can list an individual Tier-3 capability without claiming the full nested tier.

Headline tier is advisory

If the headline outruns capabilities[], the agent negotiates on capabilities[] and treats the number as advisory. No capability = not supported, regardless of the tier.

Version skew

Same major → compatible (additive minor/patch). Different major → fall back to highest shared major, or treat the capability as absent and degrade.

The rules every spec inherits

Determinism

Same (BuyerContext, manifest, catalog) → identical output, always. No model in the loop, no clock or randomness inside an evaluator. Time is injected so TTL/quote logic stays testable.

Most-restrictive default

Unknown, missing, or untrusted context defaults to the most-restrictive interpretation for any transaction-gating stage. An untrusted "I'm a gold member" never grants member pricing.

Fail-degraded — never fail-open, never crash

A throwing, timing-out, or absent extension yields a documented degraded result: BLOCK for safety-critical stages (Eligibility), INFO/omit for advisory ones (Loyalty). Unknown reason codes are treated as BLOCK.

Versioning & deprecation

semver per namespace; minor/patch additive-only; reason codes never repurposed. A deprecated code stays emitted for ≥1 major with a supersededBy pointer.

One reason vocabulary

Every stage emits one ReasonEntry shape, so an agent parses one vocabulary. severity replaces the ambiguous blocking boolean; BLOCKED vs CONDITIONAL is derived from whether a requirements[] path exists.

Severity	Meaning	Gates a sale?
`BLOCK`	Purchase is blocked in this context. If a requirements[] path exists it is CONDITIONAL; otherwise BLOCKED.	Yes
`CONDITION`	A resolvable path exists (link account, upgrade tier, upload certificate). Surface the path, never dead-end.	Yes
`INFO`	Advisory only — a loyalty earn preview, a freshness note. Never gates a transaction.	No

Every reason code is owned by exactly one namespace and declared in that spec's registry. Codes are additive-only — never repurposed. Unknown codes degrade to BLOCK.

Trust & freshness (the envelope)

Every computed contract may carry a provenance + freshness envelope so an agent (and a buyer) can trust that data is authentic and current. RAOS-0000 fixes the shape; RAOS-0008 owns the depth (real signing, key rotation, clock-skew, per-field freshness). Crypto is simulated for now — labeled loudly so simulated is never mistaken for real security.

Real merchant manifests

Sara's Boutique — open DTC

headline tier 1

Declares pricing_context + eligibility — nothing more. A Qualified merchant: an agent gets no dead-end carts, but no per-buyer pricing.

B&T Wholesale — B2B, bulk-priced

headline tier 2

Adds member_pricing + bulk_pricing on the eligibility floor. A Priced merchant: the right price per buyer, negotiated on capabilities[].

Fresh Corner Market — offers + fulfillment

headline tier 4

The richest archetype: promo_pricing, fulfillment_constraints, intent_capture. An Assisted merchant exercising the most edge cases.

Inspect these manifests in the Profile viewer

Gated — not designed here

The agent-reasoning / explainability trace format (audience, narration style, schema) is deliberately not designed in this spec. RAOS-0000 provides only the substrate a trace would draw on — the ordered list of ReasonEntry values with source namespaces. The trace format awaits a dedicated decision.

Open questions

These are genuine forks. Tell me I'm wrong.

#1Three-axis buyer identityResolved

BuyerContext keeps both loyaltyTier (consumer loyalty, RAOS-0009) and membershipTier (B2B account standing, RAOS-0001) as two distinct, orthogonal fields. With the conformance tier, that is a deliberate three-axis identity model — neither field subsumes the other.

RESOLVED (2026-06-07): keep separate. They answer different questions, are owned by different specs, and are not collapsed into one capability-set claim.

#2`severity` three-state vs two-state

RAOS-0000 standardizes BLOCK | CONDITION | INFO and derives BLOCKED/CONDITIONAL from requirements[]. Is CONDITION worth keeping as a distinct severity, or should agents just read BLOCK + presence of requirements[]?

Mirrors RAOS-0001 OQ#2 at the platform level.

#3Headline `tier` — keep it at all?

If agents must negotiate on capabilities[] and the headline is purely advisory, does publishing a tier number add value or invite the exact conformance-vs-loyalty conflation we are trying to kill?

Leaning: keep it as a human/marketing summary, clearly labeled advisory.

#4Most-restrictive default for discovery

Transaction stages default strict. Should discovery default open (risking surfacing something a buyer can't buy) or strict (risking under-surfacing)?

Mirrors RAOS-0001 OQ#4.

#5Where does `trust.mode` live — context or envelope?

The trust signal appears on both BuyerContext.trust and the provenance envelope. Is one canonical and the other a view, or are they genuinely different (buyer-claim trust vs data-payload trust)?

Leaning: genuinely different — keep both.

Have a view on any of these?

This is being built in the open precisely so the answers come from people who run real catalogs. Email me or reply on the build-log post.

rikbanerjee007@gmail.com

Why start here

Everything else imports this. The leverage of RetailAgentOS is that the substrate is implemented once and every merchant inherits it. If the BuyerContext is clean, the manifest negotiates on the right axis, reasons share one vocabulary, and versioning never breaks a consumer silently — then every spec above this one is a small, safe addition rather than a fresh negotiation of first principles.

A foundation you can't see is doing its job. This spec is that foundation.

All Specs Next: Eligibility & Visibility (RAOS-0001)