Beta RC Epic Contracts

Reading guide

A detailed internal contract for agent-owned implementation epics and acceptance tests.

Use it to trace ownership and acceptance criteria; prefer public guides for day-to-day integration instructions.

Each Epic has one accountable owner. Shared files have a single designated writer per wave; collaborators review contracts and supply tests.

Shared API contract

Principal types

Principal	Source	Backend meaning
anonymous	no credentials	public endpoints only
buyer	user JWT role=buyer	own buyer-facing resources only
seller	user JWT role=seller + seller membership	only owned seller resources
admin	user JWT role=admin	platform-operator endpoints only
service	internal service credential	explicitly allowlisted internal routes only
dev	local-only dev identity	local development only; never production

Error contract

• 401 UNAUTHENTICATED: missing/invalid/expired/revoked credential.
• 403 FORBIDDEN: authenticated principal lacks role or tenant ownership.
• 404 NOT_FOUND: resource absent or deliberately hidden/private.
• 409 CONFLICT: uniqueness/idempotency/state conflict.
• 402 NOT_LIVE_PAYMENT: production paid-payment path intentionally disabled.
• 429 RATE_LIMITED: abuse/rate-limit policy exceeded.
• 400 INVALID_REQUEST: malformed DTO or business-rule violation.

Read-after-write contract

Mutation success requires the server write to succeed and the FE to refresh or preserve the exact server-returned state. A UI must not show success when only a local mock or optimistic state changed.

---

EP-01 — Unified Identity and Authorization Boundary

• Priority: P0
• Parent: ④ BACKEND_INFRA — lane ④-A
• Accountable owner: Backend Identity writer
• Collaborators: ② Platform FE, ③ Seller FE, ⑤ QA
• Primary paths: be-cloudflare/src/lib.rs, auth_impl.rs, refund_impl.rs, events_impl.rs, settle_impl.rs, endpoints_impl.rs, contracts/**
• Shared writer: ④ owns all listed backend files for this wave.

Contract

Create a single Identity/authorization resolver that distinguishes anonymous, buyer, seller, admin, service, and dev principals. No handler may reinterpret an unauthenticated request as admin or seller. Seller scope requires seller membership. Admin scope requires DB role admin. Service credentials are a distinct service principal and are allowed only on explicitly internal routes.

Acceptance criteria

• Given an anonymous request, when it calls a protected endpoint, then it receives 401 and no tenant data.
• Given a buyer JWT, when it calls seller/admin endpoints or lists subscriptions, then it receives 403 and cannot infer other tenants' data.
• Given Seller A and Seller B, when each lists or mutates resources, then each sees only owned resources and cross-tenant mutation fails.
• Given an admin JWT, when it calls operator-only APIs, then it receives operator data; when it calls seller-owned mutation APIs, policy must be explicit and audited.
• Given X-Dev-User or DEV_AUTH in production, when any protected endpoint is called, then the request fails closed.
• Given DB lookup failure during authorization, when a request is evaluated, then it fails closed.

Verification

Worker/D1 route-level tests plus staging curl/Playwright negative authorization matrix: anonymous, buyer, seller A, seller B, admin, service/dev headers.

---

EP-02 — Public/Private Visibility Fail-Closed

• Priority: P0
• Parent: ④ BACKEND_INFRA — lane ④-A
• Accountable owner: Backend public API writer
• Collaborators: ② Platform FE, ⑤ QA
• Primary paths: be-cloudflare/src/public_impl.rs, events_impl.rs, endpoints_impl.rs, migrations for slug uniqueness

Contract

Public storefronts, products, widgets, feedback, and public checkout surfaces must use dedicated public DTOs. Missing seller_settings, DB errors, unpublished stores/products/widgets, or private widgets must fail closed as 404/403, never as public.

Acceptance criteria

• Given a seller without seller_settings, when a public store is requested, then it returns 404.
• Given a private/unpublished store or product, when accessed by direct URL, then it returns 404 without sensitive fields.
• Given a private feedback widget, when feedback or feedback-payment is submitted, then the request is rejected.
• Given duplicate seller/product slug candidates, when public lookup occurs, then schema uniqueness or deterministic conflict handling prevents wrong-resource selection.
• Given a public DTO, when serialized, then it contains no seller secrets, webhook secrets, PII beyond the approved public fields, or internal IDs not required by contract.

Verification

Fresh and upgraded D1 schema checks, Worker public API tests, staging anonymous browser tests.

---

EP-03 — FE Route and Role Boundary

• Priority: P0
• Parent: ② PLATFORM_FE
• Accountable owner: Shared FE foundation steward
• Collaborators: ③ Seller FE, ④ Backend, ⑤ QA
• Primary paths: fe/middleware/**, fe/lib/api/client.ts, fe/pages/login.vue, fe/layouts/**, fe/pages/admin/**, fe/pages/dashboard.vue, fe/pages/onboarding.vue

Contract

Browser routes are guarded by actual auth state and /api/v1/me role. admin → /admin, seller → seller console, buyer → buyer/public surface or safe landing. API 401 clears invalid auth and redirects to login; API 403 shows an authorization error without implying login will fix it. Production builds never auto-send X-Dev-User.

Acceptance criteria

• Given an anonymous visitor, when opening /admin, /dashboard, or /onboarding, then they are redirected to /login with return intent.
• Given a buyer login, when opening seller/admin routes, then they receive 403 UI and no seller data.
• Given an admin login, when login succeeds, then they land in /admin, not /dashboard.
• Given an expired token, when API returns 401, then the FE clears auth and redirects to login.
• Given a production static build, when no token exists, then requests do not include X-Dev-User.

Verification

FE typecheck, local Playwright role navigation, staging deployed-artifact Playwright.

---

EP-04 — Seller Settings and Product Persistence

• Priority: P0/P1
• Parent: ③ SELLER_FE
• Accountable owner: Seller settings/product writer
• Collaborators: ④ Backend DTO writer, ⑤ QA
• Primary paths: fe/pages/settings/**, fe/pages/products/**, fe/stores/db.ts, fe/lib/api/client.ts, be-cloudflare/src/endpoints_impl.rs, verify_impl.rs

Contract

FE uses camelCase domain models; API uses snake_case DTOs. Explicit mapping must occur at the API client/store boundary. Seller profile, settings, store publication, webhook metadata, device defaults, product status, product delete, product create/update fields, plans, license, entitlements, and slug conflicts must round-trip through the server.

Acceptance criteria

• Given a seller updates profile/settings, when save succeeds, then the response is persisted and reload shows identical values.
• Given a settings save fails, when the UI handles it, then no success toast is shown and the previous server state remains visible.
• Given secret fields, when read back, then they are masked; updating only occurs through a distinct secret-update action.
• Given a product status toggle or delete, when API fails, then UI does not mark the operation successful.
• Given product create/update with plans/license/entitlements, when saved and reloaded, then no contract fields are lost.
• Given duplicate product slug, when create/update is attempted, then server returns a clear 409 and FE displays it.

Verification

Seller settings/product Playwright read-after-write, Worker API tests, fresh login/reload verification.

---

EP-05 — Public User Journey and Purchase Scope

• Priority: P1
• Parent: ② PLATFORM_FE
• Accountable owner: Public web writer
• Collaborators: ① Product & Design, ④ Backend, ⑤ QA
• Primary paths: fe/pages/index.vue, signup.vue, login.vue, store/**, checkout/**, donate/**, license/**, legal/**

Contract

Anonymous users can view published stores/products and submit supported free/public interactions. Production paid purchase CTA is disabled or clearly marked unavailable until real PG approval. Legal pages are linked and no dead links remain. Public surfaces use public APIs rather than seller-authenticated store state.

Acceptance criteria

• Given an anonymous visitor, when visiting the landing page, then legal links and supported CTAs work and unlaunched capabilities are not presented as live.
• Given an anonymous visitor, when opening a public store/product, then public API data renders without login or seller state.
• Given production, when a paid purchase CTA is reached, then it is disabled or returns explicit NOT_LIVE_PAYMENT without creating paid state.
• Given staging, when a sandbox transaction is allowed, then it is clearly labeled sandbox and never produces production paid entitlement.
• Given a license verification page, when used publicly, then it uses a public layout and public API contract.

Verification

Anonymous staging browser E2E for public store, product, free feedback, disabled production purchase CTA, and legal navigation.

---

EP-06 — Platform Operator Console

• Priority: P1
• Parent: ② PLATFORM_FE
• Accountable owner: Operator console writer
• Collaborators: ④ Backend admin APIs, ⑤ QA
• Primary paths: fe/pages/admin/**, fe/layouts/**, be-cloudflare/src/auth_impl.rs, endpoints_impl.rs

Contract

/admin/** is a platform-operator console backed by admin JWT APIs. It must not use setDevUser, seller fallback, or seller-only data as a proxy for cross-tenant administration. MVP shows operator dashboard, users, seller verification review, and read-only audit/transaction status where APIs exist.

Acceptance criteria

• Given a non-admin, when opening /admin, then access is denied before data loads.
• Given an admin JWT, when opening /admin, then operator navigation and authorized data load.
• Given an admin reviews seller verification, when approve/reject succeeds, then server state changes and audit/result is visible.
• Given an admin API failure, when rendered, then FE distinguishes 401, 403, and server errors.
• Given the page source, when inspected, then no setDevUser or mock admin identity remains.

Verification

Role-gated Playwright and Worker admin authorization matrix.

---

EP-07 — Commerce Reliability and Payment Safety

• Priority: P1
• Parent: ④ BACKEND_INFRA — lane ④-B
• Accountable owner: Commerce integrity writer
• Collaborators: ⑤ QA
• Primary paths: checkout_impl.rs, purchase_impl.rs, refund_impl.rs, events_impl.rs, settle_impl.rs, contracts/**, outbox/audit code

Contract

Commerce operations are idempotent, tenant-scoped, and auditable. No code path creates real paid entitlements in production while real PG is disabled. Consumerless outbox destinations are explicitly disabled or remain queued; they must not masquerade as delivered.

Acceptance criteria

• Given duplicate checkout requests with the same idempotency key, when concurrent, then one succeeds and the other returns the same result or 409 safely.
• Given refund/retry/subscription event requests, when the principal lacks ownership/admin authority, then they fail closed.
• Given production payment mode, when paid checkout/purchase/feedback-payment is attempted, then it fails closed and records no paid entitlement.
• Given an outbox event with no consumer, when dispatched, then it is not marked delivered/consumed as if externally sent.
• Given audit writes under concurrency, when verified, then chain integrity remains valid or the unsafe write is serialized.

Verification

Worker/D1 concurrency tests, idempotency tests, audit-chain verification, staging sandbox transaction tests only.

---

EP-08 — D1 Schema, Migration, Backup, and Runtime Safety

• Priority: P1
• Parent: ④ BACKEND_INFRA — lane ④-C
• Accountable owner: Database/runtime writer
• Collaborators: ⑤ QA
• Primary paths: be-cloudflare/migrations/**, be/migrations/**, wrangler.toml, scripts/**, runtime logging/CORS code

Contract

Migrations are forward-only and reproducible. Local, staging, and production data remain isolated. Schema constraints support tenant and public lookup correctness. Backup/restore and rollback procedures are executable and verified on non-production scratch resources before production use.

Acceptance criteria

• Given a fresh D1, when migrations 001–latest run, then schema version and constraints are correct.
• Given an existing D1, when migrations run twice, then no duplicate/destructive behavior occurs.
• Given seller/product slugs, when duplicates are attempted, then DB constraints reject them or API returns 409.
• Given a production backup need, when export/restore is rehearsed, then scratch restore row/hash counts match.
• Given structured Worker errors, when logged, then secrets/PII are not emitted.

Verification

Fresh/upgrade migration tests, D1 export/scratch restore, staging deploy verification, rollback rehearsal.

---

EP-09 — Staging Browser E2E and Release Gate

• Priority: P1 / required before release
• Parent: ⑤ INDEPENDENT_QA
• Accountable owner: QA evidence writer
• Collaborators: all implementation parents
• Primary paths: fe/e2e/**, fe/playwright.config.ts, scripts/verify-deployment.ps1, docs/agent/**, .devpay-control/**

Contract

Staging Playwright targets the official staging deployment, not a local Nuxt server. Tests use isolated accounts/data and real Worker/D1 APIs. Evidence records SHA, environment, actor role, command, and result.

Acceptance criteria

• Given the official staging FE/API, when Playwright runs, then it performs real browser flows against deployed artifacts.
• Given Seller A/B accounts, when cross-tenant access is attempted, then UI/API deny access.
• Given settings/product changes, when browser reloads or re-authenticates, then server state persists.
• Given private store/widget, when anonymous direct access occurs, then it is blocked.
• Given release evidence, when a test was not run, then status remains NOT_VERIFIED.

Verification

QA-owned test plan approval, reproducible artifacts, release-gate recommendation.

---

EP-10 — Product, Legal, and Launch Surface

• Priority: P1 / launch-blocking items marked P0 if externally announced
• Parent: ① PRODUCT_DESIGN
• Accountable owner: Product requirements writer
• Collaborators: PM, ② Platform FE, ⑤ QA
• Primary paths: docs/agent/**, fe/pages/legal/**, fe/pages/index.vue, onboarding/signup copy

Contract

Only supported features are publicly presented. Legal and support surfaces must not be dead ends. Product acceptance criteria remain traceable to implementation and test evidence.

Acceptance criteria

• Given the landing/signup pages, when reviewed, then legal links work and unavailable features are not advertised as live.
• Given seller onboarding, when reviewed, then it does not collect unused credentials or imply mock behavior in API mode.
• Given public beta scope, when release notes/UX copy are reviewed, then payment/email limitations are explicit.
• Given customer support requirements, when no support channel exists, then external public launch remains blocked or explicitly limited.
• Given product/design deliverables, when AI-produced, then they are marked as drafts until human/vendor acceptance if contractually required.

Verification

Product copy/link audit and PM approval before external announcement.