Independent publish: staging and unstaging patches via patch groups

[freekh]

Lets one person publish a small fix without shipping somebody else's unfinished work.

A patch group is the set of patches one user has chosen to publish. Not a patch set — a patch set is computed from the schema and says which patches must move together; a patch group is curated and says which ones you want live.

Nothing changes for existing projects. A group holds every pending patch by default, so with staging untouched Publish is byte-identical to Publish today. Staging is opt-in.

Eight commits, each reviewable on its own. Design and reasoning: docs/independent-publish/PLAN.md. The content.val.build side: docs/independent-publish/HOME_REPO_PROMPT.md.

Start here: the traces

packages/ui/spa/utils/__snapshots__/patchGroups.test.ts.snap is the deliverable. Every scenario replays edits by several authors and prints, after each step, what each author picked their path in, what their group holds, what they see, and what each would commit. The headline story:

1.  bob edits p1: add items/0 = {"title":"Draft"}
      picked in   "Page" [A, B, C]
      patch sets  ?items [p1]
      bob    {p1}             "Page" [Draft, A, B, C]
      alice  {p1}             "Page" [Draft, A, B, C]

2.  alice edits p2: replace title = "Page*"
      patch sets  ?title [p2]   ?items [p1]
      alice  {p1, p2}         "Page*" [Draft, A, B, C]

3.  alice unstages p1
      alice  {p2}             "Page*" [A, B, C]   holds ?items [p1]

4.  alice publishes [p2]
      new base    "Page*" [A, B, C]
      bob    {p1}             "Page*" [Draft, A, B, C]

Alice ships her one-line title fix. Bob's half-finished list stays behind, survives the commit, and he ships it later. That is the whole feature.

The model, and the evidence for it

Two earlier versions of this design were wrong, and the tests are what showed it.

A group holds everything by default. The tempting model — your group starts empty and collects your own edits — corrupts content. Making the harness resolve op paths against each author's actual view, rather than letting a test hand-write an array index, exposed it: the closure runs when a patch is created, which is after its author picked a path. If Alice has inserted at items/0 and Bob's group doesn't hold it, Bob sees [A, B, C], picks index 1 meaning "B", and creating his patch closes his group over her insert — index 1 is now "A" and he has silently renamed the wrong element. It applies cleanly, every invariant holds, only the content is wrong. Staging later cannot fix a path chosen earlier. The picked in line in every trace is that guarantee made visible.

Patches outlive commits, but not for the reason I first wrote. An earlier revision claimed a base_commit check and a rebase step were needed; that was wrong, as you pointed out. A later revision justified the absence via the prefix rule alone, which was the reasoning that turned out to be unsound. The guarantee is real and comes from the default: an author's view already contained every other pending patch when they picked their path, so committing some of them into the base moves nothing.

The rule is that for every group and every patch set, the group's members within that patch set form a prefix in chain order. So staging pulls in what preceded it in the same patch set; unstaging drops what was built on top of it. The compare view names what a toggle moves and whose it is.

A held region is read-only until re-staged. The hole above is still reachable deliberately — unstage, then edit what you carved out. editWouldRestage is the guard, and it mirrors PatchSets.insert precisely: a replace keys on its own path, and only ops that can shift positions get the parent. Widening a replace would make a top-level field the whole module, so holding one region would block every edit — there's a unit test for exactly that.

Two pre-existing bugs fixed

1. Patch set paths compared with a raw string prefix. Nothing terminates a path segment, so ?foobar/title matched ?foo — deleting record key foo and retitling foobar were one inseparable change. The suite caught this on its first run. Over-grouping in the review screen before; publishing a deletion nobody asked for after.
2. PatchSets.insert took one op at a time while its de-duplication was per-patch, so every call after the first returned early and only a patch's first op ever reached a patch set. A move, or a file op sitting before its source op, was mis-grouped. It now takes the whole patch (six call sites).

Tests

• patchGroups.test.ts — 17 scenarios: why the default is everything, independence via unstaging, the guard and its narrowness, patch set integrity (sibling record keys, move across two arrays, last-write-wins), and the repair policy under both extend and truncate.
• patchGroupsStaging.test.ts — 20 unit tests, one contract per primitive, so a failure points at one function.
• Four Storybook stories: nothing held, one held, two entangled array changes, staging disabled.

problems asserts no group breaks the invariant, no group fails to apply, no author's stated intent stops being true in their own view, and nothing declared independent is entangled. blocked asserts refusals separately, since refusing is a correct outcome.

CI green: lint, format, typecheck, pnpm test (1102), pnpm run build, examples/next build, plus storybook build.

Two review passes

Both found real problems, all fixed in 083faba and 7839e59. Worth knowing about two:

• I introduced a regression in the insert refactor — marking a patch inserted before the !schema branch made the whole-module fallback patch set permanent, since ValSyncEngine only retries while isInserted is false. That would have made every change in a file one staging unit.
• The extend/truncate scenario never actually triggered repairGroup; the two snapshots were identical apart from the header. Rebuilt so a merge genuinely invalidates a group, and each test now asserts the repair line it expects.
• Also: patchGroupId was interpolated into the content API path unencoded, so "../../commit" would have reached a different endpoint with the project's auth headers.

Not done — blocked on content.val.build

ValSyncEngine does not yet hold a real group, so nothing reads one and behaviour is unchanged. PUT /patches rejects the group fields rather than accepting them and returning 200 for membership it cannot record. Remaining: sync engine wiring (group state, group-scoped optimistic source, patchGroupsSha, enforcing the guard at the point of editing), patch_group_id on apply_patches, and markApplied. §10 of the plan has the list.

Still open (§9)

Chiefly array co-editing: once two authors have both edited the same array and the first returns to it, both groups contain both authors' work and neither can publish alone — arrays are effectively single-writer for independent publishing unless patch sets get finer than "the whole array". Nothing is broken; it's a question of how much independence arrays get. Also whether a publisher is warned they're carrying someone else's work, and what an emptied group does on Publish.

[changeset-bot]

🦋 Changeset detected

Latest commit: 7839e59

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

This PR includes changesets to release 6 packages

Name	Type
@valbuild/ui	Minor
@valbuild/shared	Minor
@valbuild/server	Minor
@valbuild/next	Minor
@valbuild/react	Minor
@valbuild/cli	Minor

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