Document deleted_classes migration when moving old request-handler agents to workflows

[mvvmm]

Summary

When upgrading an existing Cloudflare deployment from the pre-0.8 request-handler agent model to the 0.8+ agent/workflow split, one-shot request handlers move from agents/ to workflows/. That changes the generated Durable Object class names, but the old generated agent classes may still exist in the user's preserved Wrangler migration history.

If the old generated classes remain in new_sqlite_classes history and are no longer exported by the generated Worker, flue dev --target cloudflare fails with an opaque Miniflare wrapper error.

Error

service core:user:<worker-name>: Uncaught TypeError: Class extends value undefined is not a constructor or null
  at __mf_do_wrapper.js:39:6 in createDurableObjectWrapper
  at __mf_do_wrapper_entry.js:5:33
[flue] Dev server failed: The Workers runtime failed to start.

Cause

Miniflare wraps every Durable Object class referenced by Wrangler migrations, not only classes currently referenced by durable_objects.bindings.

For example, before upgrading we had generated agent classes in migration history:

{ "tag": "flue-class-CodeReviewOrchestrator", "new_sqlite_classes": ["CodeReviewOrchestrator"] },
{ "tag": "flue-class-Orchestrate", "new_sqlite_classes": ["Orchestrate"] },
{ "tag": "flue-class-SpamAndOffTopicFilter", "new_sqlite_classes": ["SpamAndOffTopicFilter"] },
{ "tag": "flue-class-StyleGuideReview", "new_sqlite_classes": ["StyleGuideReview"] },

After migrating those request handlers to workflows, Flue generated workflow classes instead:

{ "tag": "flue-class-CodeReviewOrchestratorWorkflow", "new_sqlite_classes": ["CodeReviewOrchestratorWorkflow"] },
{ "tag": "flue-class-OrchestrateWorkflow", "new_sqlite_classes": ["OrchestrateWorkflow"] },
{ "tag": "flue-class-SpamAndOffTopicFilterWorkflow", "new_sqlite_classes": ["SpamAndOffTopicFilterWorkflow"] },
{ "tag": "flue-class-StyleGuideReviewWorkflow", "new_sqlite_classes": ["StyleGuideReviewWorkflow"] },

The generated Worker no longer exported CodeReviewOrchestrator, Orchestrate, SpamAndOffTopicFilter, or StyleGuideReview. Miniflare still saw those class names in migration history and attempted to wrap them, effectively calling:

createDurableObjectWrapper(undefined)

That produced the Class extends value undefined error.

Fix

Keep the old migration entries for deployed history, append migrations for the new workflow classes, and append a delete migration for the old generated classes:

{
  "tag": "flue-delete-old-agent-classes",
  "deleted_classes": [
    "CodeReviewOrchestrator",
    "Orchestrate",
    "SpamAndOffTopicFilter",
    "StyleGuideReview"
  ]
}

After adding deleted_classes, flue dev --target cloudflare starts successfully.

Documentation gap

The v0.8.0 changelog says applications must adopt the agent/workflow split and notes that Cloudflare workflows now receive per-workflow Durable Object bindings, but it does not explicitly explain the migration-history implication.

The v0.9.0 migration note says users now own Cloudflare Durable Object migrations and should copy previous flue-class-* history, but it emphasizes appending new_sqlite_classes for new generated classes. It does not warn that old generated classes that are no longer exported need deleted_classes (or renamed_classes, where appropriate).

The Cloudflare deployment guide does say to use explicit rename or delete migrations when changing deployed class lifecycle, but it does not show a deleted_classes example or connect it to the 0.8 request-handler-agent to workflow migration.

It would help to document this under the 0.8 migration notes and/or Cloudflare deployment guide, with an example of preserving old history, adding workflow classes, and deleting old generated agent classes.