SlabUploader/.audit/m3-build-plan.md

# M3 Create — build plan (working record)

Status: WORKING RECORD · 2026-09-19 · **not normative**.

`docs/REQUIREMENTS.md` is the only normative text; `docs/MILESTONES.md` holds the M3 ID subset;
behavior is in `docs/capabilities/CREATE.md` and `docs/contracts/`. This file records decisions
made on 2026-09-19 so a new session does not re-litigate or drift from them. It **cites**
requirement IDs; it defines none.

## 1. Scope

Implement Milestone 3 only, per the M3 ID subset in `docs/MILESTONES.md` and
`docs/capabilities/CREATE.md`. Do not implement outside that subset unless the owner expands scope
in chat.

## 2. Settled contract rulings (owner, 2026-09-19)

| # | Question | Ruling | Now lives in |
|---|---|---|---|
| R1 | Soft delete representation | Add `deleted_at TEXT NULL`; deleted rows excluded from all GET responses; status enum unchanged | `docs/contracts/DATA-MODEL.md` §1–2, `docs/contracts/API.md` §4 |
| R2 | Publish completion vs the poll endpoint | The terminal poll returns `woo_product_id`; the local working slab row is then discarded; the device draft is cleared client-side; the app **never deletes from WooCommerce** | `docs/REQUIREMENTS.md` PUBLISH-25, `docs/contracts/API.md` §4 + §7, `docs/contracts/DATA-MODEL.md` §1 |
| R3 | Prompt storage | SQLite is the point of record (`prompts` + `prompt_revisions`). File-based prompts are **superseded**; no prompt files ship and the `backend/app/prompts:ro` compose mount was removed | `docs/contracts/PROMPTS.md` (unchanged), `deploy/docker-compose.yml`, `docs/DEPLOYMENT.md` |
| R4 | `/images` volume | Photo bytes are SQLite BLOBs (source of truth). `/images` holds only a health-probe file and short-lived staging (1024 px Call-1 JPEGs, Woo media uploads), purged after use. Health goes non-200 when the DB or `/images` is unwritable; `woo_reachable:false` stays 200 | `docs/contracts/DATA-MODEL.md` §1, APP-45 |

## 3. Implementation decisions

**Stack.** FastAPI + stdlib `sqlite3` + `schema.sql` (`CREATE TABLE IF NOT EXISTS`). No SQLAlchemy,
no Alembic. Pragmas `journal_mode=WAL`, `foreign_keys=ON`, `busy_timeout`, `synchronous=NORMAL`;
one process-wide connection behind a lock. The app factory takes `db_path` and `image_dir` so tests
get per-test isolation. Revisit an ORM/migrations only after real UAT data exists.

**Async (202 + poll).** One in-process job queue with a single consumer — **not** FastAPI
`BackgroundTasks` (Starlette background tasks make TestClient 202 tests accidentally synchronous).
Status transitions CAS inside `BEGIN IMMEDIATE`. Tests run the queue in an inline mode so contract
tests stay deterministic.

**Photos.** `slab_photos.original_blob` / `processed_blob` are the source of truth; `/images` per R4.

**Prompts.** DB-only with revisions per R3.

**Publish.** Per R2 and `docs/contracts/API.md` §7 + `docs/contracts/CONTENT-WOO.md`. On success:
set `woo_product_id`, purge photos, delete the working row after the terminal poll is served, clear
the device draft. `SLAB-UAT-*` always creates a draft. `max_upload_size` is checked before media
upload (`docs/contracts/WOO-API.md` §10).

**Other.**
- `ready` is server-derived from the REVIEW-5 set.
- SKU is entered at the Measure step (UX §2.5); do not widen the Capture union.
- The server stores client-sent derived numbers and never recomputes them as source of truth (APP-40).
- PUT order: 404 → 409 `revision_conflict` → 409 `duplicate_sku` → 422 `stale_field` → apply → `server_rev++`.
- Call 1 fills empty fields only; background inference writes bump `server_rev` and the client adopts the polled rev.
- Frontend additions stay outside the Capture union: `frontend/src/api/*`, `frontend/src/create/*`.

## 4. Slice order

| Slice | Delivers | M3 IDs |
|---|---|---|
| S0 | factory, config/startup guards, health/meta, JSON logs, Dockerfile | APP-30, APP-45, APP-55, APP-65, SETTINGS-10, SETTINGS-25, OPS-25 |
| S1 | AES-GCM crypto + Settings (masked, write-only secrets) | SETTINGS-5/15/20/25/30/35/75/85/90, QUALITY-125 |
| S2 | slabs CRUD, optimistic concurrency, soft delete | APP-5/15/20/35/40, REVIEW-45 |
| S3 | photos (multipart → BLOBs, original/processed, 410 after purge) | CAPTURE-95/105/130, PUBLISH-40 |
| S4 | Woo client (app-password Basic) + taxonomy sync + test-woo | METADATA-5/10/15/20/30, SETTINGS-40/50/51/55/60/80, QUALITY-35 |
| S5 | pricing, deterministic templates, server-derived ready | REVIEW-5/10/15/20/25/30/35/40/50, METADATA-70/80/85/90, QUALITY-90/95 |
| S6 | publish (sequence, UAT draft, duplicate/stale/partial-failure) | PUBLISH-5/10/15/20/25/30/31/35/36/37/38/40/45/50/55/60 |
| S7 | inference last (Call 1/Call 2, prompt revisions, templates fallback) | METADATA-35/40/45/50/55/60/65/66/75/95/100/105/110/115, SETTINGS-45/70 |
| Cross | frontend API client + Review / Settings / Publish screens | (UI for the slices above) |
| Exit | inference-off suite, Woo-mock integration, Compose UI E2E, real UAT draft | QUALITY-20/35/50/105/110/120 |

TDD every slice: the failing test precedes its implementation; never parallelize RED and GREEN of
the same scenario.

## 5. Guardrails

- Subagents run on a single local GPU: **one at a time, never in parallel**.
- Agents never declare a gate green; Ty owns gate exit (QUALITY-25, QUALITY-30).
- Run `python tools/check_requirements.py` after any docs change; it must pass.
- Ports `10880`–`10889` are this project's; never bind `:10880`. Dev-test runs on `:10881`, bound `0.0.0.0`.
- Create must work with inference off (zero inference calls) — QUALITY-20.
- No raw status codes, stack traces, or internal codes reach the owner — QUALITY-120.

## 6. Not yet validated

- Long-horizon multi-step agentic loops (more than one or two tool round-trips).
- M3 implementation has not started; this file is the pre-build record.