feat(api): showcase workspace persistence backbone (#390)

[w7-mgfcode]

Summary

Implements E1 — Persistence Backbone of the showcase-workspace initiative (umbrella #389, epic #390). The demo slice gains its first persistence: a showcase_workspace table that records a preserved showcase run's configuration plus the soft-reference ids of every object the pipeline created.

• app/features/demo/models.py — new ShowcaseWorkspace ORM model (first table owned by the demo slice). No ForeignKeys to model_run / scenario_plan / batch_job / agent_session — recorded ids are opaque soft references, by design (documented in the model docstring).
• alembic/versions/324a2fa37fcc_... — create-table migration off head e4f5a6b7c8d9; applies + downgrades cleanly; alembic check reports no drift (env.py registers the demo models).
• DemoRunRequest gains additive Optional preservation: 'ephemeral'|'keep' (default 'ephemeral' — legacy behaviour byte-identical) and workspace_name (registry-alias pattern, ≤100 chars; requires preservation='keep', else 422 problem+json).
• app/features/demo/workspace.py — create/finalize (warn-and-continue: a DB failure never breaks the demo pipeline) + unrouted get/list helpers for tests and E4 (feat(api,ui): showcase-workspace E4 — workspace restore/replay (list/load workspaces + replay through the run path) #393).
• run_pipeline creates the row before the first step and finalizes it (completed/failed + collected ids + winner/WAPE/wall-clock) before the final yield — the mid-run-failure path records partial created_objects too. pipeline_complete.data and DemoRunResult gain additive workspace_id.
• docs/_base/API_CONTRACTS.md — additive contract notes; PRP tracked under PRPs/.

Validation

• ruff check + ruff format --check + mypy --strict + pyright --strict + unit suite (1952 passed) all green
• Demo-slice integration suite green against docker-compose Postgres (10 passed); full integration left to CI's fresh service DB (local shared-state pollution, known issue)
• Migration upgrade → downgrade → upgrade clean; alembic check: no new upgrade operations
• Manual smoke on a seeded stack: keep → completed row with real ids (winning_run_id, agent_session_id, alias, train model types); ephemeral → zero rows, workspace_id: null; workspace_name without keep → 422 application/problem+json

Closes #390

[sourcery-ai]

Sorry @w7-mgfcode, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 979887b0-243c-4646-b180-f7a033796bdc

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/showcase-workspace-persistence-backbone

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}