docs: multistore storefront routing proposal — per-offer origins, offer route table, CR-owned agent config

[bussyjd]

What this is

Design proposal distilled from operating a live, paying multistore on obol-stack:
three x402-gated offers (90-route trading-intelligence REST API, solar-economics API,
public Hermes agent at $/turn), each on its own subdomain, with agents as paying
buyers of sibling offers. Reviewed against main @ be0a237; every claim is
file:line-cited and was adversarially verified (72 findings, 0 refuted).

Why now

The x402 market is origin-keyed; the stack is path-keyed. x402scan/agentcash
group and crawl per-origin (GET <origin>/openapi.json), while main hard-wires
shared-origin PathPrefix /services/<name> routes and ONE aggregate openapi. Any
crawler sees every offer on a stack mixed into one listing (the "3-service leak" we
hit live). Making a real store today takes ~16 hand-built HTTPRoutes + a static
discovery ConfigMap + a middleware that reconciles actively fight (force-SSA,
catch-all storefront route, template steamroll).

The URL contract (/services/<name>, catalog links, ERC-8004 endpoints) is what
buyers and indexers bind to — reversing it later is a breaking migration. This is
the decision to get right before teams build on it.

Proposals (full detail in the doc)

• P1 — per-offer origins: spec.hostname on ServiceOffer; hostname-scoped route +
  per-offer openapi + /.well-known/x402 + landing; tunnel hostname↔offer binding;
  storefront catch-all opt-out; identityRef for per-offer ERC-8004.
• P2 — offer route table: spec.routes[] (or openapiRef) as the single source
  driving openapi, verifier rules (per-route pricing, free paths), typed MCP tool
  catalog (marries the existing in-band x402mcp), and skill.md — kills the
  stream:true-in-4-surfaces drift class.
• P3 — CR-owned agent config: spec.mcpServers/maxTurns/toolTimeouts (downstream
  impl exists: 5427f4d) + obol.org/config-unmanaged; ends the hermes-config wipe
  (bit us twice mid-incident); paid-agent-safe defaults; key out of checksummed
  config; config-seed merges instead of clobbering.
• P4 — freePaths + limits: per-offer free Exact routes; spec.limits {maxInFlight, rps} rendered as Traefik middleware (client already wired, unused);
  free public agents (price 0 → bearer-injection route).
• P5 — reconcile safety for live-revenue clusters: stack up --dry-run +
  live-services gate; SSA without Force + one unmanaged annotation; operator
  image-pin overlay (also: hermesImage() ignores the HERMES_IMAGE env its own
  comment promises); split verifier/controller out of the base release; backup
  sweep of operator routes/middlewares.
• 13 verified mechanical fixes (table in doc): HandleVerify v2-metrics gap,
  unlogged no_matching_requirement 402s, ForwardAuth query-string free-pass,
  verifier route-sort specificity, reserved-path denylist, accepts[] missing
  scheme/maxTimeoutSeconds, settle-failure double-execution hazard, etc.

What main already got right (verified, credited in the doc)

Inline paid-gateway with settle-after-success, v1+v2 payment headers (+tests, in the
pinned image), structurally-free shared discovery routes, paid-agent key injection,
fail-closed prefixes, down/purge gates, catalog de-flapping, SOUL adversarial
section, logo/contact preflights, in-band paid-MCP.

Evidence

Appendix contains the sanitized live manifests this proposal generalizes — serving
paid USDC traffic on base for weeks.

https://claude.ai/code/session_01VquWN9UMaSHH7MHGcG8bw1