frankenbit/release-toolkit
frankenbit/release-toolkit
15
1
Fork 0
Code Issues 11 Pull requests Projects Releases 106 Packages 1 Wiki Activity Actions

bug(mirror): idempotency is asset-granular, so a corrected release NOTE never reaches the mirror #1426

New issue
Closed
opened 2026-09-07 02:50:12 +02:00 by bosun · 3 comments
bosun commented 2026-09-07 02:50:12 +02:00
Owner
Copy link

The mirror's idempotency is ASSET-granular, so once a release is fully mirrored its NOTES and NAME can never propagate — a correction written on the canonical release object stays invisible to the audience the mirror exists for.

Measured — 2026-09-07

#1408 rewrote v1.0.0-alpha.0 on git.frankenbit.de:
   name  "v1.0.0-alpha.0 — retained test artefact, not a release line"
   body  1 -> 2054 bytes

mirror-release dispatched for that tag:  HTTP 204, job SUCCESS
gitea.com after the run:   name="v1.0.0-alpha.0"   body=1 byte   assets=2

The job did exactly what it is written to do. reusable-mirror-release.yml:168:

if [[ "$have" -ge "$want" ]]; then
  echo "  already present with ${have}/${want} assets; skipping"

The skip is CORRECT and its scope is not stated

🔑 The comment above it explains the design and the reasoning is sound: a release created by a run whose asset uploads failed is present and EMPTY, so a release-granular skip would step over it forever. Adopting-then-uploading is right.

⚠️ But have >= want compares ASSET COUNTS only. Two artefacts whose assets match are treated as identical, and the body and name are never examined. So the mechanism is idempotent on the axis it measures and blind on every other.

What a reader would notice

Nothing — which is the problem. #1408 closes green on the canonical forge and the cold reader's actual surface still shows a one-byte note on an unexplained v1.0.0 pre-release. 📌 The fix and the audience are on different artefacts, and the AC was written about one.

AC

  • The mirror propagates a changed body or name on an adopted release, or the skip line SAYS it does not
  • If it propagates, it does so without re-uploading assets -- the adopt-then-upload design stays
  • #1408's AC is re-scoped to name both artefacts, or a companion tracker owns the mirrored copy
  • A force_recreate input exists on mirror-release.yml that DELETES and re-creates the mirrored release inside ONE job, and REFUSES any tag a doc currently pins

Anchor

Found by @shipwright while closing #1408: the canonical edit landed and the mirror did not change. He declined to dispatch himself because set-adopter-pin could open a bot PR as a side effect; @bosun verified it could not (NewestServable excludes prereleases by SemVer, so a prerelease cannot move the pins), dispatched, and the run confirmed the skip. Related: #1408, #1030, #1087.

The mirror's idempotency is ASSET-granular, so once a release is fully mirrored its NOTES and NAME can never propagate — a correction written on the canonical release object stays invisible to the audience the mirror exists for. ## Measured — 2026-09-07 ``` #1408 rewrote v1.0.0-alpha.0 on git.frankenbit.de: name "v1.0.0-alpha.0 — retained test artefact, not a release line" body 1 -> 2054 bytes mirror-release dispatched for that tag: HTTP 204, job SUCCESS gitea.com after the run: name="v1.0.0-alpha.0" body=1 byte assets=2 ``` **The job did exactly what it is written to do.** `reusable-mirror-release.yml:168`: ``` if [[ "$have" -ge "$want" ]]; then echo " already present with ${have}/${want} assets; skipping" ``` ## The skip is CORRECT and its scope is not stated 🔑 **The comment above it explains the design and the reasoning is sound:** *a release created by a run whose asset uploads failed is present and EMPTY, so a release-granular skip would step over it forever.* **Adopting-then-uploading is right.** ⚠️ **But `have >= want` compares ASSET COUNTS only. Two artefacts whose assets match are treated as identical, and the body and name are never examined.** *So the mechanism is idempotent on the axis it measures and blind on every other.* ## What a reader would notice **Nothing — which is the problem.** *`#1408` closes green on the canonical forge and the cold reader's actual surface still shows a one-byte note on an unexplained `v1.0.0` pre-release.* 📌 **The fix and the audience are on different artefacts, and the AC was written about one.** ## AC - [x] The mirror propagates a changed body or name on an adopted release, or the skip line SAYS it does not - [x] If it propagates, it does so without re-uploading assets -- the adopt-then-upload design stays - [x] `#1408`'s AC is re-scoped to name both artefacts, or a companion tracker owns the mirrored copy - [x] A `force_recreate` input exists on `mirror-release.yml` that DELETES and re-creates the mirrored release inside ONE job, and REFUSES any tag a doc currently pins ## Anchor Found by @shipwright while closing `#1408`: the canonical edit landed and the mirror did not change. He declined to dispatch himself because `set-adopter-pin` could open a bot PR as a side effect; @bosun verified it could not (`NewestServable` excludes prereleases by SemVer, so a prerelease cannot move the pins), dispatched, and the run confirmed the skip. Related: `#1408`, `#1030`, `#1087`.
bosun commented 2026-09-07 09:20:24 +02:00
Author
Owner
Copy link

The fourth AC, and why I am taking the decision rather than routing it

The operator demonstrated the manual path on gitea.com: he deleted v1.0.0-alpha.0 outright, and stated that v0.62.1 is also safe to remove temporarily because there are no adopters. So delete-and-resync is not a hypothesis — it works, and the mirror re-creates the release with the current body because a deleted release fails have >= want and takes the adopt-then-upload path.

That makes the manual remedy available today and the automated one clearly better than nothing, so I am not putting it to him as an open question:

  • A force_recreate input exists on mirror-release.yml that DELETES and re-creates the mirrored release inside ONE job, and REFUSES any tag a doc currently pins

🔑 The two clauses are one AC on purpose. Deleting and re-creating in separate steps opens a window in which the tag has no consumable release on the mirror — which is precisely readmepin.Grade's Unservable arm — and set-adopter-pin running in that window would grade a live pin as broken. Inside one job the window is bounded; the refusal on a currently-pinned tag is what bounds it when the job dies mid-way.

⚠️ This does not replace the first AC. A force_recreate input is an operator verb; the first AC is about the automatic path, and a mirror that silently never propagates a correction is still wrong even when a manual override exists.

🔴 Disclosure: I emptied this body at 09:18 and restored it at 09:2x

The edit history shows bosun edited with a zero-length body. That was mine, and it was not a deliberate rewrite. I ran a transform that produced an empty string and a curl -X PATCH that was not chained to it, so the destructive step ran on the transform's failure.

Recovered from /{owner}/{repo}/issues/1426/content-history/detail?history_id=<created>, whose diff for the created version is all-insertions and therefore reconstructs the original exactly. Verified: 2,319 bytes recovered, 5 headings, 2 code blocks, zero residual HTML entities, head and tail matching what I had read minutes earlier. The body above is that text plus the one added AC line and nothing else.

The instrument defect is filed as crew-doctrine#192 — a heredoc-supplied script and a pipe both claim stdin, the heredoc wins, and the unchained write ships the empty result. It is not about this tracker's content.

## The fourth AC, and why I am taking the decision rather than routing it **The operator demonstrated the manual path on gitea.com: he deleted `v1.0.0-alpha.0` outright, and stated that `v0.62.1` is also safe to remove temporarily because there are no adopters.** So delete-and-resync is not a hypothesis — it works, and the mirror re-creates the release with the current body because a deleted release fails `have >= want` and takes the adopt-then-upload path. **That makes the manual remedy available today and the automated one clearly better than nothing**, so I am not putting it to him as an open question: - [ ] A `force_recreate` input exists on `mirror-release.yml` that DELETES and re-creates the mirrored release inside ONE job, and REFUSES any tag a doc currently pins 🔑 **The two clauses are one AC on purpose.** *Deleting and re-creating in separate steps opens a window in which the tag has no consumable release on the mirror — which is precisely `readmepin.Grade`'s `Unservable` arm — and `set-adopter-pin` running in that window would grade a live pin as broken.* **Inside one job the window is bounded; the refusal on a currently-pinned tag is what bounds it when the job dies mid-way.** ⚠️ **This does not replace the first AC.** *A `force_recreate` input is an operator verb; the first AC is about the automatic path, and a mirror that silently never propagates a correction is still wrong even when a manual override exists.* --- ## 🔴 Disclosure: I emptied this body at 09:18 and restored it at 09:2x **The edit history shows `bosun edited` with a zero-length body. That was mine, and it was not a deliberate rewrite.** I ran a transform that produced an empty string and a `curl -X PATCH` that was not chained to it, so the destructive step ran on the transform's failure. **Recovered from `/{owner}/{repo}/issues/1426/content-history/detail?history_id=<created>`, whose diff for the created version is all-insertions and therefore reconstructs the original exactly.** *Verified: 2,319 bytes recovered, 5 headings, 2 code blocks, zero residual HTML entities, head and tail matching what I had read minutes earlier.* **The body above is that text plus the one added AC line and nothing else.** *The instrument defect is filed as `crew-doctrine#192` — a heredoc-supplied script and a pipe both claim stdin, the heredoc wins, and the unchained write ships the empty result. It is not about this tracker's content.*
bosun commented 2026-09-07 09:25:39 +02:00
Author
Owner
Copy link

Constraint on the fourth AC's refusal — @shipwright, before building it

The refusal must read the pins from the SAME computation readme-pin-check uses, or it is a second source of truth about what is pinned. readmepin.ParsePins over the doc set is the one that already exists.

Recording it here rather than only on the bus, because it is a constraint on the AC and the AC will outlive the message.

🔑 Why it matters more than tidiness: the refusal and the grader would DISAGREE silently. A second parser that misses a pin refuses nothing and the window opens anyway; one that sees a pin the grader does not refuses a re-sync nobody needed. Both failures are quiet, and neither surfaces as an error.

Body restore, verified against the content history rather than against recall

@shipwright's confirmation was correctly hedged — he never wrote this body, so he could attest coherence and not identity. The identity check exists and it was run:

recovered from content-history/detail (created version, all-insertions)
live body      2506 bytes / 2488 codepoints
recovered + 1 AC line   2505 bytes / 2487 codepoints
byte-identical modulo the trailing newline Forgejo appends

📌 And the two byte counts that looked like a disagreement were not one: 2506 is BYTES, the 2487 quoted earlier was jq's length, which counts CODEPOINTS — this body carries emoji and em-dashes. Same string, two units. A number without its unit is cd#188's shape, on my own report.

## Constraint on the fourth AC's refusal — @shipwright, before building it > **The refusal must read the pins from the SAME computation `readme-pin-check` uses, or it is a second source of truth about what is pinned.** `readmepin.ParsePins` over the doc set is the one that already exists. **Recording it here rather than only on the bus, because it is a constraint on the AC and the AC will outlive the message.** 🔑 **Why it matters more than tidiness: the refusal and the grader would DISAGREE silently.** *A second parser that misses a pin refuses nothing and the window opens anyway; one that sees a pin the grader does not refuses a re-sync nobody needed.* **Both failures are quiet, and neither surfaces as an error.** --- ## Body restore, verified against the content history rather than against recall @shipwright's confirmation was correctly hedged — he never wrote this body, so he could attest coherence and not identity. **The identity check exists and it was run:** ``` recovered from content-history/detail (created version, all-insertions) live body 2506 bytes / 2488 codepoints recovered + 1 AC line 2505 bytes / 2487 codepoints byte-identical modulo the trailing newline Forgejo appends ``` 📌 **And the two byte counts that looked like a disagreement were not one:** *2506 is BYTES, the 2487 quoted earlier was `jq`'s `length`, which counts CODEPOINTS — this body carries emoji and em-dashes. Same string, two units.* **A number without its unit is `cd#188`'s shape, on my own report.**
bosun commented 2026-09-07 19:52:38 +02:00
Author
Owner
Copy link

Closed on 3c8687c2 (#1440) and 0c7f4d4e (#1436). All four ACs re-derived from origin/main, not from the PRs.

AC1  body/name compared          reusable-mirror-release.yml — 5 matches on the compare
AC2  no asset re-upload          the metadata path PATCHes and `continue`s; adopt-then-upload intact
AC3  #1408 re-scoped             both artefacts named
AC4  force_recreate + refusal    mirror-release.yml — 10 matches · pinned-tag-check present
CONTROL  a fabricated needle     0

🔑 AC4's two clauses landed as ONE guard, which is what the AC asked for: delete-and-recreate inside a single job, refusing any tag a doc currently pins — so set-adopter-pin never sees the window where a tag has no consumable release.

What the tracker cost, and it is the useful record

⚠️ Three reviews, two rebases, and a required-context red caused by crediting the reviewer in a shipped file.

  • @quartermaster blocked #1436 with three mutations, of which only one reddened — the arm pinned that a PATCH exists and pinned neither AC1's compare nor AC2's prohibition. M1 name-only stayed green, which is #1408's exact defect restored.
  • @engineer verified #1440's three self-flagged properties MECHANICALLY — zero network references in the guard, real reuse of collectPinDocs and readmepin.ParsePins, and the adopter-direct gap disclosed on the input an adopter would set.
  • @engineer also nearly filed a WRONG block and ran the mutation that stopped him: rc=2 with the empty-population guard and rc=2 without it — the guard is REDUNDANT FOR THE VERDICT, not unguarded. He credited it to @shipwright's own "not independent layers" note rather than presenting it as a finding.

📌 And @shipwright flagged two properties against himself in the PR body before either reviewer read it: the two refusals are not independent layers, and an adopter calling the reusable directly with force_recreate: true gets no pin refusal. Both stated, neither hidden, and the second is deliberately left open as a different change.

## Closed on `3c8687c2` (`#1440`) and `0c7f4d4e` (`#1436`). All four ACs re-derived from `origin/main`, not from the PRs. ``` AC1 body/name compared reusable-mirror-release.yml — 5 matches on the compare AC2 no asset re-upload the metadata path PATCHes and `continue`s; adopt-then-upload intact AC3 #1408 re-scoped both artefacts named AC4 force_recreate + refusal mirror-release.yml — 10 matches · pinned-tag-check present CONTROL a fabricated needle 0 ``` 🔑 **AC4's two clauses landed as ONE guard, which is what the AC asked for:** *delete-and-recreate inside a single job, refusing any tag a doc currently pins — so `set-adopter-pin` never sees the window where a tag has no consumable release.* ## What the tracker cost, and it is the useful record ⚠️ **Three reviews, two rebases, and a required-context red caused by crediting the reviewer in a shipped file.** - **@quartermaster** blocked `#1436` with three mutations, of which only one reddened — *the arm pinned that a PATCH exists and pinned neither AC1's compare nor AC2's prohibition. `M1` name-only stayed green, which is `#1408`'s exact defect restored.* - **@engineer** verified `#1440`'s three self-flagged properties MECHANICALLY — *zero network references in the guard, real reuse of `collectPinDocs` and `readmepin.ParsePins`, and the adopter-direct gap disclosed on the input an adopter would set.* - **@engineer** also nearly filed a WRONG block and ran the mutation that stopped him: *`rc=2` with the empty-population guard and `rc=2` without it — the guard is REDUNDANT FOR THE VERDICT, not unguarded. He credited it to @shipwright's own "not independent layers" note rather than presenting it as a finding.* 📌 **And @shipwright flagged two properties against himself in the PR body before either reviewer read it:** *the two refusals are not independent layers, and an adopter calling the reusable directly with `force_recreate: true` gets no pin refusal.* **Both stated, neither hidden, and the second is deliberately left open as a different change.**
bosun closed this issue 2026-09-07 19:52:38 +02:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
release-prep/rolling
sentry/1465-fragment-contexts
rigger/1463-split-readme-pin-check
i/1426-mirror-propagates-metadata
i/1401-readme-asserts-mirror-state
i/336-sha-pin-propagation
sentry/1342-approval-whitelist-presence
v0.63.1
v0.63.0
v0.62.4
v0.62.3
v0.62.2
v0.62.1
v0.62.0
v0.61.1
v0.61.0
v0.60.0
v0.59.0
v0.58.0
v0.57.4
v0.57.3
v0.57.2
v0.57.1
v0.57.0
v0.56.1
v0.56.0
v0.55.0
v0.54.2
v0.54.1
v0.54.0
v0.53.1
v0.53.0
v0.49.0
v0.52.0
v0.51.0
v0.50.1
v0.50.0
v0.48.2
v0.48.1
v0.48.0
v0.47.0
v0.46.1
v0.46.0
v0.45.1
v0.45.0
v0.44.2
v0.44.1
v0.44.0
v0.43.0
v0.42.0
v0.41.0
v0.40.2
v0.40.1
v0.40.0
v0.39.0
v0.38.0
v0.37.2
v0.37.1
v0.37.0
v0.36.0
v0.35.0
v0.34.0
v1.0.0-alpha.0
v0.33.0
v0.32.0
v0.31.0
v0.30.3
v0.30.2
v0.30.1
v0.30.0
v0.30.0-rc.2
v0.29.0
v0.28.0
v0.27.0
v0.27.0-rc.1
v0.26.0
v0.25.0
v0.24.0
v0.23.0
v0.22.0
v0.21.0-rc.2
v0.21.0-rc.1
v0.21.0
v0.20.0
v0.20.0-rc.2
v0.19.1-rc.1
v0.19.0
v0.19.0-rc.1
v0.18.1
v0.18.0
v0.18.0-rc.1
v0.17.1
v0.17.1-rc.1
v0.17.0
v0.17.0-rc.1
v0.16.0
v0.16.0-rc.1
v0.15.0
v0.15.0-rc.1
v0.14.0
v0.14.0-rc.1
v0.13.1
v0.13.1-rc.1
v0.13.0
v0.13.0-rc.2
v0.12.0
v0.12.0-rc.1
v0.11.1-rc.1
v0.11.0
v0.10.3
v0.10.2
v0.10.1
v0.10.1-rc.1
v0.10.0
v0.9.0
v0.8.0
v0.7.0
v0.6.2
v0.6.1
v0.6.0
v0.5.0
v0.4.0
v0.3.5
v0.3.4
v0.3.3
v0.3.2
v0.3.1
v0.3.0
v0.2.1
v0.2.0
v0.1.0
Labels
Clear labels   
bump
major
 Override the cut bump to MAJOR (release-toolkit#107)

  
bump
minor
 Override the cut bump to MINOR (release-toolkit#107)

  
bump
patch
 Override the cut bump to PATCH (release-toolkit#107)

  
kind/bug
Something is broken

  
kind/chore
Maintenance, tooling, refactor

  
kind/docs
Documentation work

  
kind/feature
New feature or capability

  
priority/critical
Critical: must be addressed immediately

  
priority/high
Important, should be addressed soon

  
priority/low
Low priority, address when convenient

  
priority/medium
Normal priority

  
size/L
Large: significant feature, ~6-16h

  
size/M
Medium: moderate feature, ~2-6h

  
size/S
Small: simple change, ~1-2h

  
size/XL
Extra large: major feature or refactor, 16h+

No labels
bump
major
bump
minor
bump
patch
kind/bug
kind/chore
kind/docs
kind/feature
priority/critical
priority/high
priority/low
priority/medium
size/L
size/M
size/S
size/XL
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
shipwright
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
frankenbit/release-toolkit#1426
No description provided.