Allow plugins to create draft revisions for published content

[swissky]

Plugins that synchronize or import content need a safe way to propose changes without changing what readers currently see. Today, ctx.content.update changes the live data columns; it does not give a plugin an editorial draft path for an already-published entry.

Issue #2399 describes a related mismatch that can cause later publishing to overwrite those column changes. Fixing that data-loss behavior is important, but the goal here is narrower and additive: let a plugin deliberately create or advance a reviewable draft while the current published revision remains live.

Use cases

• An external-system sync imports updated event details for an editor to review.
• A migration or bulk importer proposes changes to existing published entries.
• An integration generates a content update that should enter the normal editorial review flow rather than becoming public immediately.

Proposal

A possible interface is:

ctx.content.createDraftRevision(
  collection,
  id,
  patch,
  {
    expectedDraftRevisionId?,
    operationId?,
  },
): Promise<{
  item,
  draftRevisionId,
  alreadyApplied,
}>

Proposed contract:

• Merge patch into the existing draft when one exists; otherwise use the live revision as the base.
• Do not mutate the live revision or live content visible to readers.
• Apply the same schema and field validation as normal content writes.
• Use expectedDraftRevisionId for optimistic concurrency, so a plugin cannot silently overwrite an editor's newer draft.
• Accept an optional stable operationId for crash-safe replay. Scope it by plugin, collection, and entry so unrelated plugins or entries cannot collide.
• Persist operation identity across process restarts and return alreadyApplied: true when the same operation is replayed.
• Keep behavior aligned across SQLite/D1, Postgres, and sandbox bridges.

I would avoid exposing an operationRevisionId unless Core needs it for a concrete caller contract. The draft revision ID and replay result seem sufficient for plugins.

Simplest alternative

This may not need a new high-level method. It might be cleaner to fix or redefine ctx.content.update so updates consistently participate in revisions, or to expose a lower-level revision primitive that both admin and plugin paths share. Which seam would maintainers prefer?

Non-goals

• Publishing or approving the draft.
• Reading hidden draft contents without the existing permission checks.
• Building a general workflow engine.

Suggested tests

• Updating a published entry creates a draft while the published output remains unchanged.
• A second patch merges onto the current draft, not a stale live base.
• A stale expectedDraftRevisionId is rejected.
• Concurrent writers cannot silently overwrite one another.
• Replaying the same operationId after a simulated restart returns the original result without another revision.
• Reusing an operation ID for a different patch is rejected.
• Validation failures create neither a draft nor an operation marker.
• The same contract passes on SQLite, Postgres, and sandbox paths.

[saariuslystoned]

#2483 makes sense to me for plugins that need to create a draft revision from collection content. I think there's one related case it may need to handle.

Imagine a commerce plugin where products are normal EmDash collection entries:

• The collection stores the title, description, and other product content.
• Plugin storage stores the regular price, sale price, and sale schedule.
• To an editor, those pieces are all one product.

Example: restoring an older product revision

Product data	Monday	Friday	Where it lives
Name	Hot Sauce	Extra Hot Sauce	EmDash collection
Regular price	$10	$12	Plugin storage

Important

If an editor restores Monday's collection revision, EmDash can restore the name to Hot Sauce, but the price stays $12 because it lives in plugin storage. That creates a product version that never actually existed: Monday's name combined with Friday's price.

What should be restored together?

I don't think the answer is to include all plugin storage in every revision. By Friday, the site may also have new stock counts, paid orders, and payment records. Restoring the product must not roll those back.

• Include with the product revision: regular price, sale price, and sale schedule.
• Do not include: inventory, orders, or payments.

The plugin is responsible for telling EmDash which of its data is part of editing the product. EmDash would remain responsible for storing and restoring the complete revision safely.

Question for EmDash

Would you expect a plugin to be able to tell EmDash, "When this collection entry is revised or restored, include these specific pieces of plugin-owned data"? Or is the intended model that anything needing revisions must be a collection field or a plugin-declared collection, as discussed in #161?

I'm asking what EmDash expects here, not proposing a specific API. The important behavior for me is that restoring one item should not restore only half of what the editor sees as that item.