Commerce Simulation Harness requirement matrix¶
This matrix traces PL-187’s observable stories to the highest automated seam currently exercising them. Tests assert public HTTP responses, durable lifecycle/source state, canonical source reads, and authoritative evidence values rather than private call order or class structure.
| Story | Observable requirement | Primary evidence |
|---|---|---|
| 1 | One-command local environment with no external service provisioning | docker compose config; compose.yaml; runner profile |
| 2 | Generated Catalog is browsable | test_simulation_storefront.py home/catalog journey |
| 3 | Category and Item pages | test_simulation_storefront.py page contract |
| 4 | Item views create Browsing Session evidence | storefront contract + test_simulation_storefront_runner.py |
| 5 | Cart and simulated checkout create Online Purchases without payment | storefront contract + source contract |
| 6 | Global Best Sellers, Most Viewed, and Trending placement | storefront page contract |
| 7 | Anchored Frequently Bought Together, Also Viewed, and Similar Items placement | storefront page contract |
| 8 | Developer provenance and fallback disclosure | storefront recommendation-state contract |
| 9 | Isolated run from validated scenario | scenario + lifecycle + service tests |
| 10 | Seeded independent logical reproducibility and ordering | scenario golden plan + runner compilation tests |
| 11 | UUIDs, wall time, and latency excluded from identity | scenario identity tests |
| 12 | Fully resolved scenario retained with run | lifecycle SQLAlchemy tests |
| 13 | Allowlisted common web overrides | scenario override boundary tests |
| 14 | Strict portable versioned JSON | scenario validation tests + example scenarios |
| 15 | Weighted missions plant controlled relationships | deterministic plan tests |
| 16 | Visitor/rate/concurrency/duration/ramp bounds | scenario and runner tests |
| 17 | Non-overridable hard caps | target-policy boundary-plus-one tables |
| 18 | Humans and runner share storefront HTTP actions | test_simulation_storefront_runner.py |
| 19 | Plans are separate from runtime scheduling | runner plan equality and concurrency tests |
| 20 | Manual and declared checkpoints | lifecycle/checkpoint/storefront control tests |
| 21 | Traffic quiesces at checkpoint | admission drain and checkpoint source-boundary tests |
| 22 | Existing Training API is idempotent | checkpoint stable-key/replay tests |
| 23 | Progress and terminal failures visible | checkpoint lifecycle + storefront status tests |
| 24 | Checkpoints retain snapshot identity | checkpoint success and mismatch tests |
| 25 | Intermediate checkpoint resumes traffic | checkpoint admission-state test |
| 26 | Feedback scenarios may follow served recommendations | feedback selector tests |
| 27 | Feedback mode is visibly distinguished | feedback labels/export/report tests |
| 28 | Planted-mission ranking metrics only when valid | evidence mode/unavailable-reason tests |
| 29 | Coverage/fallback/provenance/concentration/request/source/training/snapshot evidence | evidence hand-calculated fixtures |
| 30 | Unavailable measurements give reasons | evidence reason-code tests |
| 31 | Authoritative JSON and web projection | evidence canonical round-trip + storefront report tests |
| 32 | Deterministic local artwork | storefront SVG/accessibility tests |
| 33 | Non-local targets rejected before traffic | target-policy scheme/host/port/address/redirect tests |
| 34 | Cancellation stops new work and drains | lifecycle, admission, and runner cancellation tests |
| 35 | Active-run reset rejected | lifecycle/source reset tests |
| 36 | Simulation stays isolated from recommendation core | simulation package import boundary and module layout |
| 37 | Worker reads through existing Data Source Adapter | simulation source adapter contract |
| 38 | PostgreSQL runtime; SQLite only focused tests | runtime-config tests + Compose services |
| 39 | No retained shopper identity | storefront session contract and evidence schema |
| 40 | Complete workflow is covered at the HTTP seam | storefront-runner integration plus existing end-to-end recommendation suite |
Release verification also requires the pre-existing unit, contract, integration, migration, observability, lint, and type-check suites. PostgreSQL/Compose checks are release-required where their transaction, isolation, health, and process semantics cannot be established by SQLite or an in-process HTTP app. The separate qualification profile remains the only capacity-qualification path; this matrix makes no such claim.