feat(plugins): add revision based conditional writes to storage and KV

[logelog]

What does this PR do?

When two requests read a plugin counter and each save an increment, one increment can be lost: both writes succeed, but the later write replaces the earlier result. This PR adds revision based conditional writes so plugin developers can detect that conflict and retry from the latest value.

The same API is available on declared storage collections and ctx.kv in native, Cloudflare and Workerd plugins. A shared counter can use it as follows:

const key = "state:completedJobs";
const current = await ctx.kv.getVersioned<number>(key);
const result = await ctx.kv.compareAndSet(
	key,
	current?.revision ?? null,
	(current?.value ?? 0) + 1,
);
if (!result.applied) {
	throw new Error("Counter changed; read it again before retrying");
}

If both requests read the same revision, only one replacement applies. The other receives a conflict and can read, recompute and retry with a bounded policy.

• getVersioned(key) returns { value, revision }, or null when absent. Stored JSON null still has a revision.
• compareAndSet(key, expectedRevision, value) returns { applied: true, revision } on success or { applied: false } on conflict. An explicit null revision creates only when absent.
• compareAndDelete(key, expectedRevision) deletes only the matching version and returns { applied: boolean }.

Each operation targets one key in the calling plugin's namespace; collection access also requires a declared collection. Invalid input, permission failures and database failures reject the promise. Existing unconditional writes invalidate earlier revisions. Atomicity covers one key, so multiple records and external actions still require coordination by the plugin.

Migration

Migration 076 adds revisions with default "0" without a row backfill and can resume after interrupted schema changes. Triggers invalidate revisions for older writers, including delete/recreate cycles. Upgrade core and the matching sandbox adapter together, and apply the migration before using these methods.

Discussion: approved storage atomicity direction.

Type of change

• Bug fix
• Feature (requires maintainer approval through a Discussion)
• Refactor (no behavior change)
• Translation
• Documentation
• Performance improvement
• Tests
• Chore (dependencies, CI, tooling)

Checklist

• I have read CONTRIBUTING.md.
• Workspace typechecks pass.
• Full type-aware lint passes.
• Targeted tests pass on the affected database and sandbox runtimes.
• Changed files have been formatted.
• I have added and updated tests for the changes.
• User-visible admin strings are wrapped for translation: not applicable; no admin UI changes.
• I have added and reviewed the user-facing changeset.
• New features link to the approved discussion above.
• Screenshots are included for UI changes: not applicable.

AI-generated code disclosure

• This PR includes AI-generated code. GPT-5.6.

Screenshots / test output

Screenshots: not applicable; no UI changes.

Targeted coverage includes competing writers, stale revisions, namespace isolation, old writers, delete/recreate cycles, migration retries and sandbox adapters.

[changeset-bot]

🦋 Changeset detected

Latest commit: c4b441b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 17 packages

Name	Type
emdash	Minor
@emdash-cms/cloudflare	Minor
@emdash-cms/sandbox-workerd	Minor
@emdash-cms/fixture-perf-site	Patch
@emdash-cms/perf-demo-site	Patch
@emdash-cms/cache-demo-site	Patch
@emdash-cms/do-demo-site	Patch
@emdash-cms/do-solo-demo-site	Patch
@emdash-cms/admin	Minor
@emdash-cms/auth	Minor
@emdash-cms/blocks	Minor
create-emdash	Minor
@emdash-cms/gutenberg-to-portable-text	Minor
@emdash-cms/x402	Minor
@emdash-cms/auth-atproto	Patch
@emdash-cms/release-service	Patch
@emdash-cms/plugin-embeds	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Scope check

This PR changes 1,752 lines across 29 files. Large PRs are harder to review and more likely to be closed without review.

If this scope is intentional, no action needed. A maintainer will review it. If not, please consider splitting this into smaller PRs.

See CONTRIBUTING.md for contribution guidelines.

[pkg-pr-new]

Open in StackBlitz

@emdash-cms/admin

npm i https://pkg.pr.new/@emdash-cms/admin@2980

@emdash-cms/auth

npm i https://pkg.pr.new/@emdash-cms/auth@2980

@emdash-cms/auth-atproto

npm i https://pkg.pr.new/@emdash-cms/auth-atproto@2980

@emdash-cms/blocks

npm i https://pkg.pr.new/@emdash-cms/blocks@2980

@emdash-cms/cloudflare

npm i https://pkg.pr.new/@emdash-cms/cloudflare@2980

@emdash-cms/contentful-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/contentful-to-portable-text@2980

emdash

npm i https://pkg.pr.new/emdash@2980

create-emdash

npm i https://pkg.pr.new/create-emdash@2980

@emdash-cms/gutenberg-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/gutenberg-to-portable-text@2980

@emdash-cms/plugin-cli

npm i https://pkg.pr.new/@emdash-cms/plugin-cli@2980

@emdash-cms/plugin-types

npm i https://pkg.pr.new/@emdash-cms/plugin-types@2980

@emdash-cms/registry-client

npm i https://pkg.pr.new/@emdash-cms/registry-client@2980

@emdash-cms/registry-lexicons

npm i https://pkg.pr.new/@emdash-cms/registry-lexicons@2980

@emdash-cms/registry-moderation

npm i https://pkg.pr.new/@emdash-cms/registry-moderation@2980

@emdash-cms/registry-verification

npm i https://pkg.pr.new/@emdash-cms/registry-verification@2980

@emdash-cms/sandbox-workerd

npm i https://pkg.pr.new/@emdash-cms/sandbox-workerd@2980

@emdash-cms/x402

npm i https://pkg.pr.new/@emdash-cms/x402@2980

@emdash-cms/plugin-ai-moderation

npm i https://pkg.pr.new/@emdash-cms/plugin-ai-moderation@2980

@emdash-cms/plugin-atproto

npm i https://pkg.pr.new/@emdash-cms/plugin-atproto@2980

@emdash-cms/plugin-audit-log

npm i https://pkg.pr.new/@emdash-cms/plugin-audit-log@2980

@emdash-cms/plugin-color

npm i https://pkg.pr.new/@emdash-cms/plugin-color@2980

@emdash-cms/plugin-embeds

npm i https://pkg.pr.new/@emdash-cms/plugin-embeds@2980

@emdash-cms/plugin-field-kit

npm i https://pkg.pr.new/@emdash-cms/plugin-field-kit@2980

@emdash-cms/plugin-forms

npm i https://pkg.pr.new/@emdash-cms/plugin-forms@2980

@emdash-cms/plugin-webhook-notifier

npm i https://pkg.pr.new/@emdash-cms/plugin-webhook-notifier@2980

commit: c4b441b

[github-actions]

Overlapping PRs

This PR modifies files that are also changed by other open PRs:

• feat: cache purge API (object cache + native Workers Caching) #2297 (9 shared files)
• feat(core): lock a content entry while someone is editing it #2919 (4 shared files)
• feat(core): add getBylines() for listing a site's bylines #2352 (4 shared files)
• feat(plugins): predicate-guarded atomic updateIf for plugin storage (no-oversell) #2169 (3 shared files)
• feat(forms): create draft content entries from form submissions #2099 (4 shared files)
• fix(workerd): accept current plugin capability names #2576 (5 shared files)

This may cause merge conflicts or duplicated work. A maintainer will coordinate.

[ascorbic]

Overall I think this is great. Just one comment

[ascorbic]

Do we need to backfill existing rows? "0" is fine as an initial revision ID, and it'll update for existing unconditional writes. Better to not waste D1 resources unless really needed

[logelog]

Thanks, I've removed the backfill. Existing records start at "0"; write triggers still invalidate stale revisions, including for older writers and delete/recreate cycles.

[logelog]

I've restored this PR to its original scope: revision based conditional writes for plugin storage and KV, with the backfill removed. The additional work will be proposed separately.