Skip to content
Cinatra Docs

Artifacts v5.0 — Preflight & Legacy-Media Purge Gate (Phase 313)

Authoritative design: docs/superpowers/specs/2026-05-17-artifacts-and-file-upload-design.md (rev 2a). This page is the preflight contract for the v5.0 milestone (Phases 313–337). It gates every later phase.

1. DB / migration protocol

Section titled “1. DB / migration protocol”

The v5.0 milestone adds schema (blob metadata, immutable artifact-version, normalized refs, provider-ref cache, audit/retention — Phases 318–323). Per repo policy there are no in-process DB backups in the GSD flow; schema lands via buildCreateStoreSchemaQueries() / ensurePostgresSchema() on dev-server boot and is verified post-merge on main (GSD step 7.2). Each schema-bearing phase MUST:

  • Add tables/columns idempotently (CREATE TABLE IF NOT EXISTS, additive columns) — never destructive ALTERs on existing shared tables.
  • Keep the hard invariant: cinatra.objects.data (JSONB) never holds file bytes/base64 (see artifacts-architecture.md).
  • Be re-verified against the live cinatra schema post-merge (not just the worktree’s scoped schema).

2. Legacy-Media purge gate

Section titled “2. Legacy-Media purge gate”

The legacy “Media” surface is removed outright, not migrated. Conversion of asset-blog/asset-email deliverables is explicitly deferred to Phases 338–339 (out of this milestone). The purge itself is gated here and executed in the storage/surface stages.

Known legacy-media callers (enumerated — must all be removed/replaced by Phase 324)

Section titled “Known legacy-media callers (enumerated — must all be removed/replaced by Phase 324)”
CallerLocationDisposition
SavedMediaRecord (base64 store)packages/asset-blog/src/store.ts (~L70)Removed; replaced by file artifact + blob storage
saveBlogPostImageToMediaLibrary() writes imageBase64 + shadow-writes @cinatra-ai/asset-blog:saved-mediapackages/asset-blog/src/store.ts (~L1097, ~L1126)Rewired to the artifact service (deferred conversion = 338)
Object-type registration @cinatra-ai/asset-blog:saved-media + /assets/media nav/URLsrc/lib/register-all-object-types.ts (~L13, ~L36)De-registered; route deleted
Blog MCP primitives blog_media_image_save, blog_media_listpackages/asset-blog/src/mcp/*Superseded by artifact MCP CRUD (Phase 325); kept until 338 conversion
/assets/media page + nav entrysrc/app/assets/media/*, src/components/app-sidebar.tsxReplaced by /artifacts (Phase 324)

Purge guard (cheap, runnable)

Section titled “Purge guard (cheap, runnable)”

After the surface stage (Phase 324) the following must return no matches outside this preflight doc and the deferred-conversion phases:

Terminal window
grep -rn "SavedMediaRecord\|/assets/media\|blog_media_" \
  --include='*.ts' --include='*.tsx' src/ packages/ \
  | grep -v 'docs/ai/artifacts-preflight' || echo "PURGE CLEAN"

Scope of the Phase-324 blocking gate: only the /assets/media surface (route, nav, plugins-routes mount, the saved-media new-URL map) must be gone at the Phase 324 close — verified by grep -rn "assets/media" src packages | grep -v artifacts-preflight returning no matches (route deleted, nav repointed to /artifacts, revalidate path swapped). SavedMediaRecord / blog_media_* legitimately remain (asset-blog deliverable conversion is Phase 338, deferred) — they are NOT part of the 324 gate.

3. Phase ordering invariants (carried from the spec + codex plan review)

Section titled “3. Phase ordering invariants (carried from the spec + codex plan review)”
  • Phase 313.1 (extension-dispatch config-DI + kind-agnostic registry listing) — pre-existing systemic gap surfaced by codex round-2; see artifacts-architecture.md §5a. MUST land before Phase 324 (artifact registry-install / marketplace surface).
  • 314 (threat model + full-fidelity file contract) before any storage code (318+).
  • 315 (artifact extension kind + dispatch coherence) before 316 (built-in type extensions).
  • 316 before 317 (registry bridge needs real descriptors to prove pluggability).
  • 318 adapter → 319 version/ref schema+types → 320 Graphiti policy before 321 first write API.
  • 318–323 (storage+integrity spine) before 324–325 (service/UI/MCP wrap a complete spine).
  • 324 (service = canonical write path) before 325 (MCP wraps the service, never a 2nd write path).
  • 326 (multimodal contract) → 327 (capability registry) → 329 (provider adapters); 330 (chat upload UI) after 329.
  • 331 (chat path) before 332 (HITL/run-resume artifact-ref plumbing).

4. Out of scope (deferred to 338/339, not this milestone)

Section titled “4. Out of scope (deferred to 338/339, not this milestone)”
  • asset-blog deliverable conversion (body/image → file artifacts).
  • asset-email deliverable conversion (attachments/exported bodies → file artifacts).