feat(plugins): predicate-guarded atomic updateIf for plugin storage (no-oversell)

[vedanshujain]

What does this PR do?

Adds ctx.storage.<collection>.updateIf(id, { where, set?, delta? }) — a predicate-guarded atomic update for plugin storage, and the no-oversell primitive. Today plugin storage offers only unconditional put (whole-doc upsert), so "sell one iff in stock" is impossible in-process without a racy read-modify-write.

updateIf runs the guard and the arithmetic in one statement:

UPDATE _plugin_storage
SET data = <json_set/jsonb_set expr>, updated_at = ?
WHERE plugin_id = ? AND collection = ? AND id = ? AND <guard>
RETURNING data

No read-then-write, no interactive transaction — so N concurrent guarded decrements serialize correctly (exactly M of N apply, final stock 0, never oversell).

• where reuses the numeric-correct WhereClause translation from query() (landed upstream in fix(core): plugin storage where-filters fail on Postgres with boolean = integer (#920) emdash-cms/emdash#1898 + the numeric fix), so a multi-digit guard like stock >= 10 compares numerically on Postgres.
• set writes wholesale field values; delta applies integer inc/dec in-SQL over COALESCE(base, 0) (a delta on a missing/null field starts from 0). Integer-only deltas enforced at runtime; a field may not appear in both set and delta; at least one is required. set/delta are separate args so {inc:n} is never mistaken for a value.
• Returns { applied: true, data } or { applied: false } (row absent or guard failed — intentionally indistinguishable). Never inserts.

Backed by pluginDataWriteExpr (dialect-correct json_set/jsonb_set, values bound as params). No new column, no migration.

Tests

• storage-updateif.test.ts — guard pass/fail/missing, integer inc/dec + integer round-trip, float-delta rejection, COALESCE-from-0 on missing/null, wholesale set, set+delta, both-fields / neither-provided rejection, guard operator coverage (equality, multi-digit gte, in, startsWith, non-indexed field), empty-in no-op.
• storage-no-oversell.test.ts — M-of-N concurrent guarded decrements (the acceptance bar; Postgres is the real race, SQLite proves SQL correctness).

Both dialects; Postgres via EMDASH_TEST_PG. Full core plugin suites green (795 tests), typecheck / lint / format clean.

Type of change

• Bug fix
• Feature (requires maintainer-approved Discussion) — see Plugin storage has no atomic primitive - am I missing something? emdash-cms/emdash#632
• Refactor (no behavior change)
• Translation
• Documentation
• Performance improvement
• Tests
• Chore (dependencies, CI, tooling)

Checklist

• I have read CONTRIBUTING.md
• pnpm typecheck passes
• pnpm lint passes
• pnpm test passes (or targeted tests for my change) — full core plugin suites, both dialects
• pnpm format has been run
• I have added/updated tests for my changes (if applicable)
• User-visible strings in the admin UI are wrapped for translation (if applicable) — N/A
• I have added a changeset (if this PR changes a published package)
• New features link to an approved Discussion — see Plugin storage has no atomic primitive - am I missing something? emdash-cms/emdash#632 (approval pending)

AI-generated code disclosure

• This PR includes AI-generated code — model/tool: Claude Opus 4.8 (Claude Code)

[github-actions]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA

---

8 out of 13 committers have signed the CLA.
✅ (ascorbic)[https://github.com/ascorbic]
✅ (ArmandPhilippot)[https://github.com/ArmandPhilippot]
✅ (khoinguyenpham04)[https://github.com/khoinguyenpham04]
✅ (ahliweb)[https://github.com/ahliweb]
✅ (scottbuscemi)[https://github.com/scottbuscemi]
✅ (Glacier-Luo)[https://github.com/Glacier-Luo]
✅ (DavidPivert)[https://github.com/DavidPivert]
✅ (gruntlord5)[https://github.com/gruntlord5]
❌ @helio-cf
❌ @cherenkov
❌ @danielmlr
❌ @MatsudaTsunenori
❌ @hossein-webdev
_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}

[github-actions]

Scope check

This PR changes 542 lines across 7 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.

[github-actions]

Overlapping PRs

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

• feat(plugins): atomic conditional writes for plugin storage (insert / updateIf) #2 (5 shared files)
• fix(plugins): correct plugin-storage query/count/index/order on Postgres #1 (3 shared files)
• feat(plugins): atomic multi-document storage batch (ctx.storage.batch) #3 (3 shared files)

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

[github-actions]

This PR has been inactive for 14 days. It will be closed automatically in 7 days if there is no further activity.

If you're still working on this, please push an update or leave a comment.