Repository navigation
fix(artifacts): optimistic-concurrency token for content PATCH (409 on stale write) - #7818
peterhieuvu wants to merge 1 commit into
Conversation
|
CI status note: the only red is Coverage Combine → "Upload combined coverage", which failed with a GitHub artifact-service error, not a test failure: All test lanes on the run are green (backend, frontend, lint, build); Coverage Gate then fails closed because Could a maintainer re-run the failed jobs on run 33600280562? I'm holding off pushing anything — the diff is unchanged and a push would only re-arm the fork approval gate for the whole suite, which is more maintainer work than a re-run click. |
37db268 to
02a001e
Compare
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the exchange install on real macOS ( [DESIGN-REVIEWED] b29c6ae |
GPT 5.6 Review (fork) — 🔴 changes requested (blocking)Reviewed 1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands. BLOCKING -- src/kiro_crew/hooks.py:3958 -- Verified writes fall back to an unconditional rename
Adjudication (Opus 5) — is blocking on each finding proportionate?Harm rung: HIGH-to-unbounded in kind (silent loss of an external editor's save, no backup) but bounded in reach — conditions confirmed: verifying caller only ( 🏷️ Fenced finding(s) machine-flagged as likely edge caseThe security fence keeps these findings blocking regardless of adjudication; the only clearance path is a human override recorded by a repository writer, who must independently verify a rationale before recording it — it is machine-authored, and a wrong override on a security-class finding ships exactly the class the fence exists to stop. (This lane's comment deliberately carries no override command.)
|
First Principles Review (Fable 5, fork) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The staged-copy recovery scan (~250 lines plus a pinned scan on every update) guards a loss the store's last-write-wins contract already accepts; discard failed stages instead. Not justified as shipped
What this change shipsInventory (10 items) — 5 justifiedIntent: refuse an artifact save based on outdated content (409 + rebase token) instead of silently overwriting another writer — an ADDITION of an opt-in guard, titled
[FIRST-PRINCIPLES-REVIEWED] b29c6ae |
UX Review (Fable 5, fork) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS A reflex second Cmd+S or double-click after the 409 is an irreversible overwrite of content the user never saw — only a relabel stands in the way. Watch
Suggestions
[UX-REVIEWED] b29c6ae |
Opus 5 Review (fork) — ✅ no blocking findingsReviewed Review detailsNothing blocks: one advisory finding on the guarded file-backed save path. FINDING — src/kiro_crew/artifacts.py:2573 — a transient source read failure inside a guarded save takes [OPUS-REVIEWED] 118203c |
02a001e to
638025f
Compare
The window is real and is now closed on both edges, in
On the prescribed fix ("revert the source-first write"): reverting would reopen the exact hole the CAS exists to close — with |
bolichen97
left a comment
There was a problem hiding this comment.
Description / code mismatch
One item does not line up: the checklist asserts no module doc covers this endpoint, but docs/system-specs/modules/artifacts.md documents PATCH /api/artifacts/{slug} and is not updated for the new request field, the new response field, or the new 409.
1. Documented PATCH contract changes (new request field, new response field, new 409) with no spec update, and the Description states the opposite
The Description says —
- Documentation updated (if applicable) — behavior documented in docstrings; no module doc covers this endpoint today
The code does — docs/system-specs/modules/artifacts.md:142 carries a PATCH /api/artifacts/{slug} row for this endpoint, so a module doc does cover it. The diff changes that endpoint's contract in three documented-surface ways and leaves the row untouched: the handler accepts a new optional expected_sha256 request field, rejects a non-string token with 400, and maps ArtifactConflictError to a 409 carrying {error, current_sha256, version} (src/kiro_crew/dashboard/handlers/artifacts.py); and to_dict adds content_sha256 to every content-carrying response (src/kiro_crew/artifacts.py). Docstrings are not a substitute here, because the spec row is the documented contract for this endpoint.
Risk — AGENTS.md:218 requires updating the spec in the SAME commit when an API, schema, or documented behavior changes. The artifacts spec is what the next contributor reads before touching a content-write path or writing a second client; leaving it silent means they will not know a token exists, that a 409 is now reachable, or that content_sha256 is part of the response contract. The checklist line makes this worse rather than neutral: it asserts there is no module doc to update, which removes the one prompt a reviewer would use to catch the omission. Docs Lint only validates index integrity, so no gate catches it either.
Required change — Extend the PATCH /api/artifacts/{slug} row at docs/system-specs/modules/artifacts.md:142 in this commit with: the optional expected_sha256 token, the 409 outcome and its {error, current_sha256, version} body, the 400 on a non-string token, and content_sha256 on content-carrying responses. Correct the checklist line "no module doc covers this endpoint today" to name the spec update. Store-side prose for ArtifactStore.update(expected_sha256=), ArtifactConflictError, and the file-backed compare-and-swap layer is welcome but optional, since that doc does not currently enumerate update()'s parameters or the other artifact exception classes.
638025f to
d772887
Compare
|
You're right on both counts — the spec row exists and my checklist line asserted the opposite, which is exactly the kind of claim that hides the omission. Fixed in
I kept the store-side prose ( |
d772887 to
ab9a547
Compare
|
CI on
Addendum 09:05 UTC: Opus 5 Review completed on this head — no blocking findings (the lane that was "review incomplete" on |
|
Round 28 → GPT 5.6 (on
Local lanes on Gates on the new base: 1122 backend tests over the touched suites, mypy, flake8, isort, black hunk-parity on every touched file, comment-history, the sync-io gate; tsc, eslint. Body updated (token minting, off-loop sites, tests). |
|
CI on A fork contributor cannot re-run a lane; they re-run on the next head or via the maintainers' override handler. Holding this head until the shards finish and the limit resets; I will append the shard results here. Addendum 10:10 UTC — shards finished: Linux shard 4 is green (the |
|
Rebased -> One real conflict, in Gates on the new base: 3309 backend tests over the touched suites, mypy, flake8, isort, comment-history (base This head re-runs the three lanes that never got a verdict on |
|
CI on
|
|
Rebased -> On the new base the baselined black gate passes; 2058 backend tests over the touched suites, mypy, flake8, isort, comment-history (base For the record on |
|
CI on
|
|
Round 29 -> GPT 5.6 on
Local lanes on Gates on the new base: 2060 backend tests over the touched suites, mypy, flake8, isort, black, comment-history (base |
|
CI on
Addendum 00:25 UTC: Coverage Gate fails closed on the same missing frontend shard ( Addendum 00:57 UTC: macOS shards 1 and 2 (shard 3 green) -- one failure each, both Linux-only assumptions running on darwin, both fixed together by open upstream PR #13202: shard 1 |
|
Rebased -> Clean rebase, no conflicts. Source and frontend byte-identical to Gates on the new base: 2319 backend tests over the touched suites; mypy, flake8, isort, black baseline gate, comment-history, sync-io; tsc, eslint, 935 frontend tests including the diff-scoped i18n register ratchets; |
|
CI on
GPT 5.6 on Gates on the new base: 1787 backend tests over the touched suites; mypy, flake8, isort, black baseline gate, comment-history (diff-scoped), sync-io; tsc, eslint, 935 frontend tests with the diff-scoped i18n ratchets; |
|
Round 30 -> GPT F1 on Opus (local lane, on the F1 fix) advisory at Opus advisory not adopted: a planted regular file with a hint-shaped name is retained across passes (logged each time) and would be installed by the existing unreadable-source Backend Lint on Local lanes on the F1 commit: GPT ( |
|
Bundle Size Gate on The Also on UX Review (advisory CONCERNS) on Gates on the new base: 1791 backend tests over the touched suites; mypy, flake8, isort, black baseline gate, comment-history (diff-scoped), sync-io; tsc, eslint, 935 frontend tests with the diff-scoped i18n ratchets; |
|
GPT on The round-30 code (recovery retain, exchange |
|
CI on
GPT on Gates on the new base: 1826 backend tests over the touched suites (crew-log emitter included); mypy, flake8, isort, black baseline gate, comment-history (diff-scoped), sync-io; tsc, eslint, 935 frontend tests with the diff-scoped i18n ratchets; |
|
Rebased -> Also on
Gates on the new base: 1791 backend tests over the touched suites; mypy, flake8, isort, black baseline gate, comment-history (diff-scoped), sync-io; tsc, eslint, 935 frontend tests with the diff-scoped i18n ratchets; |
|
CI on
Gates on the new base: 1791 backend tests over the touched suites; mypy, flake8, isort, black baseline gate, comment-history (diff-scoped), sync-io; tsc, eslint, 935 frontend tests with the diff-scoped i18n ratchets; |
|
Backend Lint on |
|
CI on
Every one of these clears on a re-run except the black kill, and a new head cannot clear that until #13386 is fixed upstream -- so no re-run head is pushed for the others alone. The next head is the rebase onto whatever fixes #13386; it re-runs all of them. |
|
Rebased ->
Outside those hunks the patch is byte-identical to This head re-runs the four attributed reds from |
|
CI on
The two shard flakes would clear on any re-run head; the black kill cannot until #13386 is fixed, so no re-run head is pushed for them alone -- the rebase onto that fix re-runs everything.
|
|
Proposing to split this PR. @bolichen97, since your "Changes requested" covers the whole thing, I'd like your view before anything is closed. Why. After 30 review rounds this is about 5,200 lines across 49 files, for a fix #7751 describes in four steps. Most of the growth came from one early choice: guarding the write back to a file-backed artifact's source file with a compare-and-swap, when #7751 only asked for that file to be read for the comparison. The staging, the pinned-directory hardening, the rename-exchange install, the recovery scan and the plain-rename finding that re-rolls on every head all follow from it. I should have stopped and asked about scope much earlier. The split:
What happens to this PR. If #14039 picks full compare-and-swap guarding, I'll rebuild this PR as that follow-up on top of #14075. Otherwise I'll close it. Until then I'm not pushing any more heads here. |
Open-PR triage (2026-10-05): OVERLAPPING with #14075. Rebase is required before any further work.I checked the full merge-base diff ( What's on main now: nothing from this PR. Relationships:
Staleness: the PR is 1,507 commits behind main. Breaking change / P0: neither found. The declared tightenings (an invalid Recommendation: MERGE-DISCUSSION. Leave this PR parked, as the author proposed on 2026-09-26, and do not close it yet:
No further heads on this branch are useful until #14039 is decided. |
|
Thank you @peterhieuvu for all the work here, and for splitting it as you proposed. Status check against main ( What did not land: the file-backed hardening (stale-write guard against external edits to Because part of this PR is still unlanded, I am leaving it open for now. No code or branch changes were made. |
Problem / Motivation
PATCH /api/artifacts/{slug}has no stale-write protection:api_artifact_updatepassesbody["content"]straight intoArtifactStore.update(), which writes unconditionally. Last write wins. Two dashboard windows open on the same artifact silently clobber each other today; a user's stale buffer silently overwrites an agent's iteration; and for file-backed artifacts, an external write tosource_pathis invisible to an editor holding a stale buffer. The frontendartifactEditGuardis page-local and does nothing across windows or surfaces.Neither existing field can detect a stale base:
versionis not bumped by silent saves (snapshot: false, the dashboard default), so two different live states can share a version number;updated_atis bumped by metadata-only renames/retags, so it false-positives on non-content changes.Why it matters
This is the same stale-snapshot-clobber class already recognized on the agent-config PUT surface (#7470, #7089) — the artifacts PATCH instance of it. The blast radius is user data: the overwritten content is someone's live edit. It gets worse as write frequency rises — any client implementing debounced autosave of live state multiplies the race windows. The store itself already treats this as a real problem for remote pushes (
PublicationMetadata.last_pushed_sha256, sent asexpectedCurrentSha256, is described in source as "the optimistic-concurrency guard"); local writes had no equivalent.What changed (motivation → approach → change)
Symptom → root cause: unconditional content writes with no way for a caller to say "only if nothing changed since I read." Approach: opt-in optimistic concurrency mirroring the store's own remote-push design, with the compare inside the store lock (a handler-level compare would be TOCTOU-racy against concurrent store writers).
ArtifactStore.update()gains optionalexpected_token. When provided withcontent, live content is read exactly the wayget()reads (source file for file-backed artifacts,current.htmlotherwise), digested, minted into the token and compared (constant-time) underself._lockbefore any mutation. Mismatch raises the newArtifactConflictError, which carriescurrent_token+version.content_tokenis HMAC-SHA256 oversalt:digestunder a 32-byte key the store loads at construction from<root>/.token_key(0600; creation serialized across processes by a lock file and published by rename, so racing processes share one whole key; a malformed key file is refused rather than silently replaced, since reissuing the key would invalidate every token in flight; the read is bounded to one byte past the key length before the exact-length check, so an oversized file planted at that path is refused without being read into memory at warm-up). Thesaltis a per-artifact random value (content_salt, persisted in meta.json, never sent to a client; on load it is accepted only as the empty legacy value or exactly 32 lowercase hex characters, anything else refused as a malformed meta.json rather than reaching the HMAC's ASCII encode as a 500) rotated on every store-mediated content write — without it the token would be a function of content alone, and a reader who can also write could mint a comparison token for a guessed secret by saving the guess somewhere; every save lands under a fresh salt instead, and no API mints under an old one. An external edit to a file-backed source rotates nothing and moves the digest, so the guard still trips on it; a snapshot re-reads the same content and keeps the salt, so it never 409s an editor holding a token against unchanged content. Historical reads (GET …?version=N) carry no token at all: a version is never an editing base, and minting one would let a writer snapshot a guess and compare its version token with the hidden version's under the same salt. Every store-mediated content write rotates the salt —create, a contentupdate, settling a blank's draft, and image creation — and an artifact written before the field existed is minted under a domain derived from its slug, so two pre-upgrade artifacts never share one. The default store is built post-bind on a worker thread (_kick_artifact_store, the same shape as the other post-bind kicks — never anon_startuphook, which would put its filesystem work in front of the listener), and a coroutine that needs the store before that warm-up has finished goes throughget_default_store_async: the cached instance is a plain attribute read (no I/O, no thread hop); an unbuilt one is constructed on a worker thread, never on the loop. Everyget_default_store()call inside a coroutine anywhere in the package uses that accessor or resolves the store inside the worker callable (a package-wide source-scan test pins it; the deploy teardown handler was bindingget_default_store().geton the loop before handing it to the thread), each module forwarding its own getter name so a test that substitutes it keeps the substitute. Auto Research constructs its store inside the worker thread it already writes from. The HTTP serializer redacts credentials out ofcontentafter the token is computed, and the codebase's own rule for redacted path labels (security/redaction.py, keyed HMAC) applies: an unkeyed hash beside redacted text would let a reader test low-entropy guesses for the redacted secret offline. The raw SHA-256 never leaves the store — it is used only where both sides are the store itself (the file compare-and-swap's base hash). The key is persisted rather than per-process so a token taken before a gateway restart still validates after it; losing the file costs one 409 per open editor and protects nothing at rest.source_pathbetween the compare and the mirror. For guarded writes the source mirror is a descriptor-pinned compare-and-swap through the existingverified_replace_file_nolinkprimitive (base_hash=the raw digest the client's token was minted from,max_bytes=MAX_CONTENT_BYTES);conflict/too_largeabort beforecurrent.htmlor metadata are touched._try_write_source_pathnow returns the verdict string instead of a bool; all call sites updated. Unguarded writes keep today's last-write-wins + demotion-to-source_copy_onlysemantics exactly.conflictto a verifying caller instead ofrefused. The predicate cannot tell a hostile ancestor swap from an editor's own atomic save (both install a new inode under the same name); for the verifying callerrefusedmeans "unwritable, no competing writer" and is answered by keeping the stale edit and demoting the link — so a swap in that window was reported as applied instead of 409ing. The post-staging twin of the check already made this split; the audit WARNING is unchanged for both. The prompts PUT handler shares this primitive and gains the same correction: a pre-staging swap now reaches it as its existingcontent_conflict409 rather than "write refused".ArtifactConflictError→ 409 with{error, current_token, version}so the client can refetch and re-base; a token that is not the 64-hex shape this store mints (non-string, wrong length, non-ASCII — which the constant-time compare would refuse by raising) is a 400 at the handler and a validation error at the store, never a 500 and never a phantom conflict.content_token(get,create,update), andto_dictemits it whenever content is included — minted from the raw content before the HTTP serializer's redaction pass, because the guard digests the raw bytes on disk; a snapshot-onlyupdatethat read its content off the source file stamps the raw bytes it read, asgetdoes, so a source that is not valid UTF-8 hands back a token a later save can match. The list path serializes without content and pays nothing; meta.json never carries it.ArtifactDetailPageadopts the token:handleSavesendsexpected_tokenfrom its last fetch, and so does the buffer flush that precedes the sync banner's Pull / Overwrite / Snapshot — a 409 there keeps the buffer, raises the same notice, and aborts the sync action instead of pushing the stale buffer over the newer content — and does not rebase the held token, so a retried sync action 409s and aborts again; only the labelled Save can overwrite. A 409 renders as a "changed since you loaded it" notice that preserves the buffer (editedContentuntouched,editingstays true) and refetches so the next save carries the fresh token — a deliberate overwrite instead of a silent one. New i18n key in all 13 catalogs (en-XA regenerated).Token omitted = today's behavior; zero existing callers change (MCP, revert, pull/publish, blank-settlement all send no token).
Review-round hardening:
api_artifacts_createin the artifacts handler and the auto-research report export (_handle_to_artifact) — go through_run_off_loop/asyncio.to_threadlike every other store call; every remainingstore.create/updatecaller (publish_sync,deploy/handlers,widget_artifacts) was already offloaded. The read/delete sites this diff touched to resolve the store asynchronously — the delete handler's pre-delete capture anddelete,list_versions, the version and event reads,record_impression, and relocate'sallowed_source_roots(it resolves paths and loads config) — go through_run_off_looptoo. Thread-witness tests cover every one.event_typevalidation moved to the top ofstore.update()(before any side effect), so an invalidevent_typeon a non-snapshot save is now a 400 instead of being silently accepted — previously it could also raise mid-write and leave a save partially applied.Guarded save ordering (file-backed artifacts). A guarded save touches two files with no transaction spanning them, so the order is chosen to make every failure either side-effect-free or recoverable: (1) the store's own copy is staged beside
current.htmlwithout being installed; (2) the source file is written as a compare-and-swap against the raw-byte hash the guard captured; (3) the staged copy is installed with one atomic rename. Consequences, all deliberate:conflict) discards the staged copy and answers 409 with nothing applied; there is no restore write that could itself fail.refusedmirror (read-only file, foreign owner, path outside its authorizing root — no competing writer) installs the store copy and demotes the artifact tosource_copy_only, visibly, instead of stranding the client in a permanent 409 loop.too_largedemotes the same way: a source overMAX_CONTENT_BYTESis served truncated, so the client's token and the guard's read agree with each other but can never match the file — a 409 would hand back the token the client already holds, a loop no rebase can exit. The oversize source is never written (a write would truncate it). If the install then fails, the stage is discarded with the error — a refused mirror wrote nothing, so there is no committed intent to recover and the caller sees the save fail.live_dirtyflags the un-snapshotted state), and the nextupdate()on the slug reconciles it under the store lock before doing anything else: source bytes equal to the staged content → the install is completed; a readable source that differs → the stage name carries a 16-hex prefix of the source hash the CAS compared against, so recovery can tell the two causes apart: a source still at that base means the commit never landed and the leftover is discarded; a source that has moved off both the staged content and its base may have been edited externally after the commit landed, so the leftover is retained (one WARNING per pass) rather than deleting the only copy of that edit; a hint-less staging-named entry (nothing the guarded save writes) or a store-only artifact → discarded; a source that cannot be read right now → retained until it can be judged. The exception: when the source is unreadable AND the update is itself about to writecurrent.html, the newest leftover is installed first — otherwise that write's unreadable-source fallback would install over it and demote the pointer, and the next pass would discard the only copy of a committed edit. The stale save then 409s onto the pending content (a real rebase target) instead. An install by recovery is booked as the content change it is, and booked before anything else the triggering update does: comment anchors are re-validated against the recovered text under the lock, andupsertis owed from that moment and fired after the lock is released on every exit — the normal one, a token conflict, a validation error — because the install consumes the stage and nothing would remain to trigger a second pass. The version bump of a snapshot save is the one thing recovery does not reconstruct; that state stays visibly un-snapshotted until the next snapshot.Staging is descriptor-pinned end to end. The store directory is pinned component-by-component (
pinned_fs.pin_parent, oneO_NOFOLLOWopenat per component), the staging file is created through that descriptor with an unpredictable name andO_CREAT|O_EXCL|O_NOFOLLOW, and the descriptor stays open until the stage ends: the install renames and the discard unlinks through it by basename, and an ended stage is inert. After staging, no operation on the stage ever re-resolves a pathname, so a directory renamed, replaced, or swapped for a symlink cannot receive the install, hide the stage from cleanup, or expose a same-named bystander to a by-name unlink. Where dir-fd syscalls are absent (Windows) the stage is created withtempfile.mkstempand handled by name. The store's pre-existing_write_textgoes through the same pair, so the class is closed store-wide. The sensitive-path check runs before any directory is created, so a refused target leaves no trace. The staged-copy recovery scan is pinned the same way: the artifact directory is opened once (open_dir_pinned, its own name never followed), and enumeration, reads, unlinks and the reinstall all go through that descriptor. Where dir-fd syscalls are absent (Windows) the scan does not run at all — a leftover is retained rather than judged, because unlinking or installing by pathname would follow a swapped ancestor (a junction) into a directory the scan never inspected; retaining deletes nothing.The install is a true compare-and-swap where the platform allows. Verifying the source's bytes through a pinned descriptor and then installing with
rename()leaves the window POSIX itself carries — no conditional rename — in which an external tool's atomic save lands between the last check and the install and is silently replaced. For a verifying caller the write gate now installs by atomic exchange (renameat2(RENAME_EXCHANGE)on Linux,renameatx_np(RENAME_SWAP)on macOS, via the same native seamplatform_compatalready used forRENAME_NOREPLACE): the inode that was displaced is moved into the staging name instead of destroyed, inspected against the verified inode (held open through the exchange, so its number cannot be recycled) and the post-hash(st_mtime_ns, st_size), and — because an equal-length in-place rewrite with a restored timestamp leaves both identical — its bytes are re-hashed through that held descriptor and must still match the verified base; on any mismatch it is exchanged straight back with the verdictconflict. The newer file is never gone, not even for the duration of the check. A filesystem that answers ENOSYS/EINVAL/EOPNOTSUPP to the exchange (some network mounts) or refuses the first exchange with any otherOSError(nothing has moved), and a platform without it (Windows; a glibc without therenameat2wrapper reaches the syscall directly), keep the plain-rename install with the residual window it has always had — and the caller keeps its own snapshot, so the safe direction is preserved there. The one failure the protocol refuses to clean up is an exchange-back that itself fails: without the exchange no rename is conditional, so nothing further is renamed — the newer content stays under the staging name (never unlinked), the stale payload stays at the original name, the state is logged at ERROR with both names, and the caller still answersconflictso the client refetches rather than trusting its save. A restore-by-plain-rename was tried and rejected: any rename in that state is unconditional and would overwrite a further writer landing on the name. The exchange-back that succeeds is checked too: a writer who replaces the original name between the conflict check and the exchange-back is what that exchange moves under the staging name (its own replace already unlinked the payload), so the stage is compared by identity against the payload's descriptor — held open (readable) through the install, so its inode number cannot be recycled — and its bytes re-hashed through that descriptor against the payload's hash (an in-place rewrite of the payload while it sat at the original name keeps the identity and changes the bytes), before the spent-stage unlink is authorised. If the stage is not the payload, one more exchange puts that later save back at the original name, the content it displaced stays under the staging name, nothing is unlinked, and the state is logged at ERROR with both names. One window stays open by construction and is documented rather than closed: a writer that opens the payload inode for writing during the instants it holds the original name, and writes only after the spent stage is unlinked, writes into an orphaned inode — the same loss every atomic-replace save (including the pre-PR plainrename()) has always inflicted on an in-place writer racing it; POSIX exposes no other process's descriptors, and the only closure (never unlinking the stage after a conflict) would leave a.tmpbeside the source on every 409.Out of scope, deliberately. The refused-mirror path installs the store copy and then persists the demotion as two steps; a crash between them leaves reads serving the old source until the next save — a two-file crash-window class that is recoverable, visible, and not a data-loss path (nothing is deleted, and the store copy holds the edit).
Tests
Store (
test/test_artifacts.py,TestConflictToken): matching token writes; stale token raises with recovery fields and writes nothing; omitted token keeps last-write-wins; token ignored on metadata-only updates; a silent save trips a stale token despite an unchanged version number (the reason the token is a hash, not the version); an external source-file edit trips the guard; an external edit confined to malformed UTF-8 bytes still trips it (raw-byte token) and the refetched token converges; the token follows the text for valid UTF-8 and store-only artifacts; the token is opaque (64 hex, not the SHA-256 of the content, stable per content, distinct per content); the key is persisted (a second store on the same root mints the same token and accepts it, a different root mints a different one, the key file is 32 bytes at 0600, meta.json carries the salt but never the token); a malformed or symlinked key file is refused at construction, not silently replaced (the link check is an lstat, so it holds on Windows where O_NOFOLLOW does not exist); an oversized key file (33 bytes and 16 MiB) is refused with a single bounded read (the requested size is recorded; the old unbounded read fails the test); a malformed expected_token on a content write is a validation error, not a conflict or a crash; a writer cannot mint a comparison token for a guess (a probe artifact with the same content, and an overwrite of the target itself, both land under a fresh salt; the token read before the write is stale; an external edit still trips the guard); a snapshot keeps the token domain; a snapshot-only save of a file-backed artifact with malformed UTF-8 bytes returns the same raw-byte tokengetmints and a save re-based on it proceeds (the old text-stamped token fails the test); a legacy meta.json without a salt tokenizes and gains one on its first write; a persisted salt that is non-ASCII or non-hex is refused as a malformed meta.json (the old code raisedUnicodeEncodeErrorfrom the HMAC encode); historical reads carry no token while the current read does; settling a blank and creating an image rotate the domain; two legacy artifacts get distinct domains; the post-bind kick constructs the default store on a worker thread and both gateway entrypoints kick it after the bind; the async accessor constructs an unbuilt store on a worker thread, returns a built one without a thread hop, honours a replaced module getter, and no coroutine anywhere in the package calls the synchronous getter (package-wide source scan, 41 sites on the prior code); Auto Research constructs its store on the worker thread; a source write racing in between the compare and the mirror answers conflict instead of clobbering (CAS layer); unguarded mirrors still last-write-wins;to_dictcarries/omits the token correctly. Existing_try_write_source_pathtests updated to the verdict-string contract.Store (
test/test_artifacts.py,TestPersistence): staging never writes through a planted sibling; the install never follows a symlink swapped in after staging; a symlinked target is refused; a parent swapped for a symlink after resolution is refused at staging; an install lands in the directory the stage was created in even after that directory is swapped away; a discard reaches a stage whose directory was swapped; the recovery scan acts only on the directory it opened (a swapped-in link's target receives neither the unlink nor the reinstall); an ended stage is never re-addressed by pathname (a same-named bystander in a swapped-in directory survives); no descriptor leaks across every lifecycle ending; a failed install after a committed CAS recovers on the next update; an unreadable source retains the leftover; a pending leftover is installed ahead of a write while the source is unreadable, and the newest wins when several are undecidable; a refused mirror plus a failed install leaves nothing to recover; an install by recovery on a metadata-only update firesupsertand re-validates comment anchors (a plain metadata-only update still fires nothing); the same booking holds when the triggering update is itself a stale-token conflict — the stage is consumed, the anchors are rescanned, and exactly oneupsertfires after the lock is released (the listener re-enters the store to prove it); both fail against the prior code; oversize / non-UTF-8 / planted-symlink staging lookalikes are removed. Every recovery test runs on both platform paths (a fixture parametrizes over the pinned scan and, by forcing_store_dir_fd_ok()false, the no-dir-fd path): the pinned leg keeps its assertions unchanged, the other asserts the documented retention — leftover untouched,current.htmlunchanged, noupsert, anchors not rescanned — so no platform skips the file.TestSourcePathSecurityHardening: a sensitive target is refused before any directory is created; an oversize source demotes on the guarded path instead of looping on 409, and the source is never written.Write gate (
test/test_hooks_coverage.py): an external atomic replace landing between hash-verify and staging answersconflictto a verifying caller (and staysrefusedfor the unverified one), with no staging residue; an external atomic replace landing after the last-moment stat — the windowrename()cannot close — answersconflictand the newer file wins (injected at the stat itself, so the test fails against a plain-rename install); the exchange disposes of the displaced verified inode on the happy path; an unlink-and-recreate with preserved size and mtime answersconflict(the verified inode is held open at exchange time, witnessed via/proc/self/fd); an equal-length in-place rewrite with a restored timestamp answersconflict(re-hash through the held descriptor); a filesystem without exchange falls back to the plain rename; a failed exchange-back preserves both files, attempts no further rename, and logs at ERROR; a third writer landing during a failed exchange-back is never touched; a third writer landing before a successful exchange-back is exchanged back to the original name and never unlinked (fails against the prior code, which unlinked it as the payload); an in-place rewrite of the payload at the original name before the exchange-back (same inode, different bytes) is likewise exchanged back and never unlinked (fails against an identity-only check); when that restoring exchange itself fails, both saves are preserved.Handler (
test/test_artifacts_handlers.py): stale token → 409 withcurrent_token/versionand content unchanged; matching token saves and returns the fresh token; malformed token → 400 not 409; detail response includescontent_token; the wire token is neither the hash of the raw nor of the redacted content and nocontent_sha256is emitted, yet it round-trips as the save token.Component (
website/src/test/ArtifactDetailPage.saveConflict.test.tsx, new — with a controlled Pierre editor stub so a buffer re-seed regression fails visibly): Save sends the token; a sync action's buffer flush sends it too and a 409 there aborts the action with the buffer intact (exactly one PATCH, the guarded flush); a retried sync action after the 409 sends the original token again and aborts again, and only the labelled Save then sends the 409's token (fails on the prior code, which rebased on the flush); after a 409, Cmd+Shift+S and the Snapshot button make no request and leave the banner alone (button disabled, title names Save as the one overwrite path), and plain Save then sends the 409's token (fails on the prior code: a second PATCH); 409 shows the conflict notice, relabels Save as the overwrite it now is, keeps the buffer, and refetches; a metadata edit after the 409 keeps the notice, its action and the label; non-409 errors keep the generic error path; a held Cmd+S never saves on its key-repeat after the 409 rebase (one PATCH, banner still up); a second save entering while one is in flight is dropped (one PATCH) — both fail against the prior handler.Manual verification
Live two-writer race in an isolated pod: opened the artifact, dirtied the editor, issued a silent save from "another window" via the API, clicked Save → 409 banner with the buffer intact; clicked Save again → informed overwrite applied with the fresh token. Screenshots below are from a re-run of that race in an isolated instance of this worktree at 3f86d36 (same patch as the current head; the rebase since only adopted the store fence from #12514).
Screenshots / video
Stale save refused — banner, buffer preserved, Save still armed:
"View the newer content" opens the live version in a popout without leaving the edit buffer
Sync-action abort state — the pre-sync flush before Snapshot is refused with 409: the sync banner shows the inline "Save refused — content changed" beside its action, the edit bar carries the conflict notice, the draft is kept, Save is relabelled as the overwrite, and Snapshot is disabled (its title says only Save overwrites). Captured through the real
ArtifactDetailPagein the repo's capture-harness pattern (website/capture/artifact-sync-conflict.*+website/scripts/capture-artifact-sync-conflict.mjs, which asserts every one of those properties and that exactly one PATCH — the refused flush — was made before shooting), because the sync banner renders only with a registered publish provider, which a live gateway here cannot supply:Same state, light theme
Related Issues
Fixes #7751
Pattern harvest
Rule candidate: review-prompt
Pattern: "content-write endpoint accepts no base token — concurrent writers silently clobber (compare against #7470/#7089 class); a compare outside the writer's own lock, or a mirror to an externally-writable file without CAS, reopens the same hole"
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)PATCH /api/artifacts/{slug}row indocs/system-specs/modules/artifacts.mdupdated with the token, the 409 body, the 400 on a malformed token, and the opaquecontent_token(with the persisted key) on content-carrying responses