Your Market architecture — current

Status: current as of 2026-09-04. Companion to Identity architecture — current. Audience: Foundation engineers, security reviewers, integrators. Source of truth: functions/lib/market/, functions/market.js. When this doc disagrees with the code, trust the code.

This is the bulk-buy commerce-agent slice of Pillar 3 (Your Market). It sits beside the older vote-on-bids marketplace (product_requests / product_votes / pillar3-market), it does not replace it. Partner-facing copy (whitepaper, deck, yc-site) still describes the reverse-marketplace story; this file describes what the agent harness actually enforces.

1. What this is

Foundation has three pillars on one verified-human identity layer:

Chrome name is Foundation. Pillar color for Market is #0891b2. Mobile/web never hold a Solana keypair; chain writes (when any) go through Cloud Functions, same rule as anchorCommitment.

The product is not Amazon-shaped. A verified member commits qty + max unit price. That is demand, not a charge. Gathering continues until fill ≥ 80% or the target is met; then RFQ, award, per-member checkout, ship / return.

Fake demand must not move supplier prices: every demand line goes through requireAuth + requireVerifiedMember (functions/lib/verified-member.js), the same sybil gate Voice writes use.

2. Architecture (decided once)

The pattern is Anthropic's anatomy of effective commerce agents: one model in a standard agent loop, skills not subagents, no intent router.

Two agents only because they face different principals:

Tools call Foundation systems (catalog, pools, RFQ, orders, host payments). Search results arrive already ranked; the model chooses what to show (searchCatalog in functions/lib/market/engine.js).

UI components are tools: present_pools, present_checkout, present_quotes, present_review_queue. The server fills records from session-issued IDs (functions/lib/market/session.js). Layout in the tool args is the on-screen order.

Skills load as tool results so they cache with the session prefix (load_skill in functions/lib/market/harness.js). High-frequency instructions stay in the system prompt (functions/lib/market/prompts.js). Safety, legal, brand, and key user facts stay in the prompt.

Prompt-cache order, prefix-based (buildCacheLayers):

1. Global — prompt + tool defs (byte-identical across sessions)
2. Session — memory facts + history
3. Volatile — current time, current page (last, so it cannot bust the prefix)

Target hit rate is 90–99%. @plantagoai/ai's claudeWithCache is the shared caching wrapper used elsewhere in Foundation; the Market harness is built so a tool-capable loop can sit on the same global → session → volatile split. The eval suite grades a scripted model (functions/__tests__/market-evals.test.js) so quality does not depend on a live API key.

At 1K–1M members, Source sees aggregates only: committedQty, customerCount, p50Max, fillRatio. sourceAggregate() never returns a member list.

3. Lifecycle (Voice-shaped)

Implemented in functions/lib/market/engine.js.

1. Commit. Verified member writes one demand line: qty + maxUnitPrice. Not a charge. One line per (poolId, uid). Per-member qty cap is enforced on the resulting state (PER_MEMBER_QTY_CAP = 20), including retries.
2. Gather. Continues until committedQty / targetQty ≥ 0.8 or committedQty ≥ targetQty.
3. RFQ. Known suppliers: policy auto-applies open_rfq in-band (ops is not clicking every join). Thin pool or empty knownSupplierIds: human review queue (kind: "open_rfq").
4. Award. Quotes and supplier notes are untrusted: sanitized and wrapped in <untrusted-commerce-data> (functions/lib/market/fence.js). Auto-award if unitPrice ≤ unitCeiling and supplier rating ≥ 4.0. Else review (kind: "award").
5. Allocate. Per-member checkout orders, status awaiting_checkout. The model has no charge / capture_payment / place_order tool (POOL_TOOLS / SOURCE_TOOLS).
6. Place order. Host callable placeMarketOrder. Requires a payment nonce. The model cannot call this.
7. Returns. Auto-return under value/window constants (AUTO_RETURN_MAX_VALUE, AUTO_RETURN_WINDOW_DAYS); disputes to review.

The model stages. A policy or a person applies. Guardrails re-check at apply time (applyStaged), not at stage time — a ceiling that moved after staging still blocks the award. Writes serialize per pool (withPoolLock in functions/market.js).

4. Harness (enforced in code)

Every rule below is in functions/lib/market/, not only in the prompt.

Eval coverage (a negative for every positive): core join, unverified refusal, messy history, abandoned-intent, user-authored injection, data-plane injection in quote notes, multi-capability join+checkout, checkout without a commit, present_pools layout, dropped un-issued IDs.

5. Memory

Typed facts in Firestore (market_memory), not in the model:

• Always-on keys in the session prefix (qty_cap, delivery_preference, default_max)
• Per-turn prefetch from the same signals that pre-load a skill
• Everything else behind lookup_memory
• See / correct / delete callables; 365-day retention; MARKET_MEMORY_ENABLED=false disables writes and extraction

GDPR: market_memory and market_agent_sessions delete with the account; market_commitments and market_orders anonymize uid and keep amounts (financial-record retention, same posture as votes).

6. Demo

demoNearThreshold() (functions/lib/market/demo.js) seeds pool olive-oil-5l at 7/10 fill, known supplier Northwind (rating 4.5, quote $4.20, ceiling $5). One verified join trips RFQ → eligible auto-award → host checkout.

Seed into the emulator with seedMarketDemo (ring ≤ 1) or the emulator seeder once that path is wired.

7. What this is not

• Not the pillar3-market Anchor program. That program still mirrors supplier-selection votes on product_requests. See docs/superpowers/specs/2026-06-01-pillar3-market-design.md.
• Not a Voice vote. Do not embed a Voice subagent.
• Not a Share disbursement. No tool moves funds / allocations.
• Not a new brand. No "Foundation Mobile", no "Collective".

8. File map