Adopt core 0.30's change-set envelope for PATCH /records/:id

[cuibonobo]

Summary

core 0.29 replaced update(), setPermissions(), setUnlisted() and setParent() with a single mutate(id, changes), and moved the wire format with it. PATCH /records/:id now carries a change set — an envelope naming any combination of contentPatch, parentId, permissions, associations and unlisted, applied as one atomic write producing exactly one version — and PUT .../permissions and PUT .../unlisted are gone. One If-Match fences a whole multi-aspect edit, where each aspect previously cost a version and a round trip of its own and could not be fenced together at all.

changesFromWireBody() from @haverstack/core/wire owns the entire read of that envelope — which keys it may carry, the 400 an unrecognized or wholly absent key earns, the 422 a malformed value earns — so the route parses nothing itself, the same way createOptionsFromWireRecord() already owns POST /records. The two retired PUT handlers each carried a hand-rolled shape check the envelope parser makes redundant. GET /records/:id/permissions stays.

PATCH /entity keeps its own { content } envelope — no fixture governs it and its shape is this server's own — and moves to patchContent(), the content-only spelling update() left behind.

Change-feed frames carry ops: ChangeOp[] in place of op, with update renamed patch and reparent added. A reparent is matched against both containers a move concerns, so a subscription filtered on the origin learns the record left it.

Dependencies move in lockstep: core 0.31.0, wire-types 0.30.0, commons 0.25.0, adapter-local 0.30.0, conformance-fixtures 0.24.0. minimumReleaseAgeExclude now carries the scope pattern '@haverstack/*' in place of the seven per-version entries it had been accumulating — pnpm appends to that list itself on any install that has to hold a too-new package, and since Haverstack releases in lockstep, every sync was writing the whole scope back a version at a time. Third-party dependencies keep the cooldown.

Release

This lands as 0.8.0. release.yml picks the bump from the commits since the last tag, and none of the envelope work carried a conventional-commit prefix, so the release would have gone out as 0.7.9 — a patch — even though PATCH /records/:id no longer accepts a bare content patch and two endpoints are gone. A feat: prefix now carries it to the minor, which is where the compatibility boundary sits on a 0.x package.

The parentId answers, and who sees which

An earlier revision of this PR skipped error-bad-request-malformed-parent-id and error-conflict-parent-does-not-exist: canReadReferent() resolved a caller-named destination and refused a missing one before Stack ran either check, so both collapsed into 403 for every requester — the owner included, despite their documented exemption from that gate. Filed as haverstack/core#276.

Fixed in core 0.31.0 (core#279), so both fixtures pass unchanged and their dispatch tests are back. The anti-oracle property is intact for everyone else, and the docs now say so rather than leaving it implied. Probed against adapter-local:

parentId	owner acting alone	non-owner write-holder
""	400 bad_request	403 permission
"1hk153xffffz" (no such record)	409 conflict	403 permission

A non-owner learns they may not name the container, never whether it exists. docs/api.md § The change set carries that split, since the section had promised both answers to every caller.

core#278 needs nothing here

core 0.31.0 also lands StackQueryError.capability, the exported MissingCapability and filtersContent(), and assertQueryTravels() in @haverstack/core/wire. None of it reaches this server — capability does not travel (serializeError() does not carry it), assertQueryTravels() is the build-side half of a refusal parseQueryParams()/parseQueryBody() already apply here, and discovery spreads stack.features rather than re-deriving any of it. Recorded so a reviewer need not re-check.

Docs

Yes — the wire contract for record writes changed.

• docs/api.md — the Records endpoint table (PATCH re-described, the two PUT rows removed); a new ### The change set section covering the envelope, presence-not-truthiness, the merge asymmetry, per-key authority for all five keys, the 400/422/409 split and which requester sees which; the permissions-envelope paragraph; the If-Match endpoint list; the soft-delete refusal list; the ## Unlisted section's spelling; and the change-feed paragraph for ops. The reparent note sits with the change-feed filtering rule it qualifies, since a parentId filter is the one place where what a frame matched on and what it carries come apart.
• docs/deployment.md — no change needed; its one PATCH /records/:id mention is about thread routing, which is unaffected.
• README config table and .env.example — no change; no configuration moved.

The spec and conformance fixtures for this change live in haverstack/core — the envelope is core#269, the reparenting that precedes it is core#263 and core#266, the schema and group-admin rules released alongside are core#267 and core#271, and the gate fix is core#279.

Verification

pnpm run format:check && pnpm run lint && pnpm typecheck && pnpm test all clean, plus pnpm build. 524 tests passing, 27 files (520 before the two fixtures came back, 522 before the shape-error cases below).

Checked by hand:

• Dumped every affected fixture's method/path/requestBody from the fixtures package and matched the routes against them, rather than inferring the shape from the changelog.
• Audited all 52 PATCH call sites across the suite and classified each before touching any — fixture-bodied, already-a-change-set, /entity (a different envelope), or a bare content patch needing contentPatch. Two were hand-fixed rather than wrapped: tests/routes/versions.test.ts sent a wire-record-shaped body whose content/version/updatedAt keys had been landing as content fields under the old bare-patch rule, and the reserved-content-key test builds its body through JSON.parse.
• Probed the parentId answers directly against adapter-local on both tiers, before and after the core upgrade — the table above is measured, not read off the changelog.
• Probed per-key authority the same way for the two keys the docs had left undescribed: a non-owner write-holder may set associations, and may set parentId only when it can also read the destination it names.

New coverage for the five fixtures the reparenting work added: the two parent-change fixtures, the reparent feed frame, and the snapshot/restore pair that settles a record's container. Plus shape-error cases for permissions and associations, which had been resting on the unlisted case alone — a core bump that stopped rejecting a malformed value for either would have passed the whole suite.

Notes for reviewers

Two judgment calls worth a look:

1. tests/routes/versions.test.ts — the old body almost certainly did not mean what it did. I rewrote it as { contentPatch: { body: 'v2' } }, which is what the test's name says it wants (a v2 to have history for). If it was deliberately probing that native-looking keys land as content, that intent is now gone and wants its own test.
2. The _config.entityId test keeps its 409. entityId is a declared content field of _config (ConfigContent), so wrapping it in contentPatch still reaches checkConfigEntityIdUnchanged() rather than being refused as undeclared. Worth confirming, since it turns on schema details rather than on the envelope.

One thing found in review and deliberately not fixed here: core's validatePermissions() checks only the write-without-read rule, so a malformed permission entry ({ "access": "bogus" }, a missing entityId, a bare string) is stored verbatim, and a null entry throws a TypeError out of the validator as a 500. It fails closed — a junk entry grants nothing — and it is not a regression, since the retired PUT .../permissions did the same array-only check. It belongs in core rather than in this PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KeyEysH8Rr3LwiLTZBTDDb