Skip to content

Remove V1 Upgrade Collections Implementation Plan

Created: 2026-05-19 13:34 UTC Updated: 2026-05-19 13:34 UTC

Goal

Remove the V1 upgrade Payload collections from the active AnuvaX CMS schema, generated types, migrations, and current documentation. The upgrade API, CLI, and worker paths should continue to use the in-memory AnuvaRepository for runtime state. Future durable persistence should be deferred and documented as a known gap.

Non-Goals

  • Do not implement a durable AnuvaRepository store or adapter interface in this change.
  • Do not migrate or export data from the V1 Payload tables.
  • Do not preserve src/collections/anuvax/anuva-v1.ts as reference code.
  • Do not redesign Anuva contracts, stage gates, source adapters, workflow envelopes, or Mastra workflows.
  • Do not change Presentation Video UI behavior.
  • Do not remove the in-memory AnuvaRepository.

Current Behavior

The active Payload collection registry includes the V1 upgrade collections via AnuvaV1Collections:

  • conversation_states_v1
  • workflow_runs_v1
  • workflow_stage_gates_v1
  • source_documents_v1
  • scene_edit_history_v1
  • quality_metrics_v1
  • rss_feed_configs_v1
  • rss_ingest_runs_v1
  • rss_entries_v1

These collections are exposed through Payload admin/API schema and generated into src/payload-types.ts. Current docs still describe them as upgrade-path state. The current upgrade orchestration path also has equivalent runtime state in src/lib/anuva/repository.ts, which is consumed by orchestration, source adapter, retrieval, idempotency, CLI, and worker code.

Target Behavior

Payload no longer registers or exposes the V1 upgrade collections. The deleted V1 collection tables are dropped by an explicit migration because no hosted-environment export is required. Generated Payload types no longer contain V1 collection keys or interfaces. Current docs describe upgrade-path state as repository-owned, with durable repository persistence called out as a future gap.

Implementation Shape

flowchart TD
  inspect["Inspect current V1 references"] --> removeSchema["Remove V1 collection registry and file"]
  removeSchema --> migrate["Add drop-table migration"]
  migrate --> generate["Regenerate Payload types and import map if needed"]
  generate --> docs["Update current docs and Known Gaps"]
  docs --> verify["Run typecheck, lint, and targeted tests"]

  service["Anuva orchestration service"] --> repo["In-memory AnuvaRepository"]
  cli["Upgrade CLI"] --> service
  worker["Upgrade worker"] --> service
  repo -. future gap .-> durable["Durable repository store"]

Affected Files

Code and schema:

  • src/collections/anuvax/index.ts
  • src/collections/anuvax/anuva-v1.ts
  • src/payload-types.ts
  • src/app/(payload)/admin/importMap.js, only if regeneration changes it
  • src/migrations/20260519_000003_drop_v1_upgrade_collections.ts
  • src/migrations/index.ts

Runtime verification targets:

  • src/lib/anuva/repository.ts
  • src/lib/anuva/orchestration-service.ts
  • src/lib/anuva/source-adapters.ts
  • src/lib/anuva/retrieval.ts
  • src/lib/anuva/idempotency.ts
  • scripts/anuva-cli.ts
  • scripts/anuva-worker.ts
  • tests/unit/anuva-orchestration-service.test.ts
  • tests/unit/anuva-source-adapters.test.ts

Affected Docs

  • docs/core/PayloadDataModel.md
  • docs/state/CollectionMap.md
  • docs/core/WorkersAndJobs.md
  • docs/state/WorkflowMap.md
  • docs/state/KnownGaps.md
  • docs/changes/2026-05-19-1334-remove-v1-upgrade-collections/ImplementationLog.md, during implementation

Data And Schema Impact

This is a destructive schema cleanup. The implementation should drop existing V1 upgrade tables because the answered breakdown says no data export is needed.

Migration requirements:

  • Create src/migrations/20260519_000003_drop_v1_upgrade_collections.ts.
  • Register it in src/migrations/index.ts after 20260519_000002_drop_asset_slots.
  • Use idempotent SQL matching recent migration style: DROP CONSTRAINT IF EXISTS, DROP INDEX IF EXISTS, ALTER TABLE ... DROP COLUMN IF EXISTS, DROP TABLE IF EXISTS ... CASCADE, and DROP TYPE IF EXISTS ... CASCADE.
  • Remove V1 collection columns from payload_locked_documents_rels.
  • Drop V1 top-level tables and any nested array/select helper tables generated by Payload.
  • Drop V1 enum types for channel, readiness, role, status, failure class, source type, edit type, initiator, and RSS status fields.
  • Provide a down migration that recreates empty V1 tables/types if rollback is required. It does not need to restore deleted data.

Before writing the migration SQL, inspect the actual generated schema or current database to confirm exact table, column, index, constraint, and enum names. Do not guess final SQL names from collection config alone.

Tasks

  • [x] 1. Confirm current references
  • Search for all V1 collection slugs and exported names outside the change docs.
  • Confirm non-generated runtime code does not perform Payload CRUD against the V1 slugs.

  • Confirm repository-backed state methods cover run, artifact, quality metric, source document, conversation, idempotency, and worker state used by the upgrade path.

  • [x] 2. Remove Payload collection registration

  • Remove the AnuvaV1Collections import from src/collections/anuvax/index.ts.
  • Remove the spread of AnuvaV1Collections from the exported collection array.

  • Delete src/collections/anuvax/anuva-v1.ts.

  • [x] 3. Add destructive schema migration

  • Create src/migrations/20260519_000003_drop_v1_upgrade_collections.ts.
  • Drop lock relationship columns, V1 tables, nested V1 helper tables, and V1 enum types.
  • Add a rollback path that recreates empty V1 tables and relationships.

  • Register the migration in src/migrations/index.ts.

  • [x] 4. Regenerate generated artifacts

  • Run pnpm generate:types.
  • Run pnpm generate:importmap if Payload reports admin import-map changes or if generated admin files reference removed collections.

  • Confirm src/payload-types.ts no longer includes V1 collection keys, interfaces, relationship variants, or select types.

  • [x] 5. Update current docs

  • Remove V1 collection lists from docs/core/PayloadDataModel.md and docs/state/CollectionMap.md.
  • Update docs/core/WorkersAndJobs.md and docs/state/WorkflowMap.md so upgrade workflow state is described as repository-owned, not Payload-collection-backed.
  • Add a clear docs/state/KnownGaps.md note that durable persistence for AnuvaRepository remains deferred.

  • Revise Mermaid diagrams in changed docs where the collection/state relationship changes.

  • [x] 6. Update tests if needed

  • Fix any tests that import removed collection types or expect V1 collection availability.

  • Add a focused repository/orchestration test only if existing unit coverage does not prove the upgrade path still stores equivalent runtime state in AnuvaRepository.

  • [x] 7. Verify

  • Run targeted reference searches for all removed V1 slugs.
  • Run pnpm typecheck.
  • Run pnpm lint.
  • Run targeted Anuva unit tests.

  • Run pnpm test:int if implementation touches presentation actions, Payload route behavior, or generated types in a way that affects integration surfaces.

  • [x] 8. Record implementation

  • Update ImplementationLog.md with files changed, migration decisions, commands run, failures, and any deviations.

Verification Plan

Run these checks after implementation:

  • rg -n "conversation_states_v1|workflow_runs_v1|workflow_stage_gates_v1|source_documents_v1|scene_edit_history_v1|quality_metrics_v1|rss_feed_configs_v1|rss_ingest_runs_v1|rss_entries_v1|AnuvaV1Collections|ConversationStatesV1|WorkflowRunsV1" src scripts tests docs -g '!docs/_stale/**'
  • pnpm generate:types
  • pnpm generate:importmap, if admin import map may have changed
  • pnpm typecheck
  • pnpm lint
  • Targeted unit test command for Anuva repository/orchestration tests, using the repo's configured unit test runner from package.json
  • pnpm test:int, if integration-facing behavior or generated type fallout requires it

Expected reference-search result: only historical change docs, migration names, or intentional docs notes should mention removed V1 slugs. Active schema, runtime, generated types, scripts, and tests should not depend on them.

Docs Parity Checklist

  • [ ] docs/core/PayloadDataModel.md no longer lists V1 upgrade collections as active Payload collections.
  • [ ] docs/state/CollectionMap.md no longer lists V1 upgrade collections.
  • [ ] docs/core/WorkersAndJobs.md describes upgrade worker state through AnuvaRepository.
  • [ ] docs/state/WorkflowMap.md removes Payload V1 workflow collection language.
  • [ ] docs/state/KnownGaps.md explicitly notes deferred durable persistence for AnuvaRepository.
  • [ ] Any changed docs under docs/core or docs/state include revised Mermaid diagrams when diagrams describe affected state or collection relationships.
  • [ ] ImplementationLog.md records the final implementation and verification results.

Acceptance Criteria

  • src/collections/anuvax/anuva-v1.ts is deleted.
  • AnuvaV1Collections is no longer imported or registered.
  • The V1 upgrade tables are dropped by a registered migration.
  • src/payload-types.ts no longer contains V1 collection entries, interfaces, relationship variants, or select types.
  • No active code path references the removed V1 collection slugs.
  • Upgrade API/CLI/worker paths still use AnuvaRepository for equivalent runtime state.
  • Current docs no longer describe V1 upgrade collections as active state.
  • docs/state/KnownGaps.md documents the deferred durable repository persistence decision.
  • Required verification commands pass, or failures are recorded with clear causes in ImplementationLog.md.