Merge pull request '#240 dev→main: milestone 318 steps 5–7 and 9, plus #3202 ' from dev into main

Merge pull request 'Stop minting identifiers nothing reads: moving channel tags, :c-<sha> on main, and a label-keyed build cache' (#239 ) from dev into main
Merge pull request 'Per-artifact commit-derived versions: pinnable date tags, and no rebuild when nothing changed' (#238 ) from dev into main
2026-08-29 00:14:33 -04:00 · 2026-08-28 15:14:35 -04:00 · 2026-08-28 10:14:15 -04:00 · 2026-08-27 12:49:39 -04:00 · 2026-08-03 20:23:27 -04:00 · 2026-08-03 08:29:09 -04:00
7 changed files with 178 additions and 361 deletions
@@ -75,23 +75,18 @@ jobs:
          fetch-depth: 0
      # The version is DERIVED, not read from the repo (milestone 271 step 4,
-      # cut over 2026-08-27). `packaging.sh version` returns `YYYY.M.D.HHMM`
+      # cut over 2026-08-27). `packaging.sh version` returns MAJOR.MINOR from
-      # UTC — the commit TIME of the newest change to a PACKAGED extension
+      # manifest.json plus a patch component that is the commit TIME of the
-      # file, per family rule 148/149. Never a commit count, which orders by
+      # newest change to a PACKAGED extension file, in minutes since
      # 2020-01-01 — family rule 149, never a commit count, which orders by
      # branch rather than by recency.
      #
-      # Unpadded, and only here: AMO's grammar rejects a leading zero, so the
+      # The committed "version" in manifest.json / package.json no longer
-      # extension renders rule 148's numbers without the family's padding
+      # decides anything: the stamp step below overwrites it in the working
-      # (milestone 318 step 8). Same value, one character narrower per segment;
+      # tree before web-ext ever reads it. It is deliberately NOT committed
-      # ci.yml's extension-version lane checks the string against Mozilla's
+      # back — the commit carrying the bump would itself be a change to the
-      # published regex before this job ever calls AMO.
+      # extension and would move the version again. The repo holds the source;
-      #
+      # the build derives the label.
      # The committed "version" in manifest.json / package.json decides NOTHING
      # — not even a MAJOR.MINOR prefix, which step 8 removed. The stamp step
      # below overwrites it in the working tree before web-ext ever reads it,
      # and it is deliberately NOT committed back: the commit carrying the bump
      # would itself be a change to the extension and would move the version
      # again. The repo holds the source; the build derives the label.
      - name: Derive extension version
        id: extver
        run: |
@@ -481,6 +476,7 @@ jobs:
        env:
          IMAGE: git.fabledsword.com/bvandeusen/fabledcurator
          CHANNEL: ${{ steps.tag.outputs.channel }}
          TAGS: ${{ steps.tag.outputs.tags }}
        run: |
          set -eu
          DERIVED=$(sh scripts/artifacts.sh revision web)
@@ -489,6 +485,7 @@ jobs:
          # A pure function of the revision — same commit, same string — so it
          # adds no variability the reuse check would have to account for.
          echo "version=$(sh scripts/artifacts.sh version web)" >> "$GITHUB_OUTPUT"
          echo "build_tags=$TAGS" >> "$GITHUB_OUTPUT"
          # The moving tag for this channel. Which tag we ask IS the channel —
          # that is why the revision needs no -main/-dev qualifier any more.
@@ -611,13 +608,7 @@ jobs:
          context: .
          file: Dockerfile
          push: true
-          # ONE tag, the channel's. Every other tag is written by the step
+          tags: ${{ steps.reuse.outputs.build_tags }}
          # below, registry-side. buildx here pushes the first tag to the
          # registry and then re-pushes the rest through the DOCKER driver,
          # out of a local image store a registry-direct build never filled —
          # #3190, which cost `main` its :c-<sha> on 2026-08-29 while :latest
          # published perfectly well.
          tags: ${{ steps.reuse.outputs.channel_ref }}
          # The reuse key. Read back off the channel tag on the next push to
          # decide whether that push needs to build at all, so this is not
          # decoration — an unstamped image is one that will always rebuild.
@@ -630,40 +621,17 @@ jobs:
            FC_CHANNEL=${{ steps.tag.outputs.channel }}
            FC_VERSION=${{ steps.reuse.outputs.version }}
-      # Every tag but the channel's own is written HERE, registry-side,
+      # Registry-side manifest copy: no layer transfer, no local daemon, no
-      # whether or not a build ran. Each -t becomes another reference to the
+      # rebuild. Each -t becomes another reference to the SAME manifest the
-      # SAME manifest the channel tag holds, so :c-<sha> is byte-identical to
+      # channel tag already holds, so :c-<sha> is byte-identical to what is
-      # what is published rather than a lookalike rebuild.
+      # published rather than a lookalike rebuild.
      #
-      # Owning the build path too is #3190's fix, not a tidy-up:
+      # Runs on EVERY reuse, which is what keeps family rule 146 true: a
-      #
+      # rolling channel refreshes itself, so skipping a build must never mean
-      #   #27 pushing …/fabledcurator:latest           DONE 15.8s
+      # leaving :dev or :latest pointing at something older than the commit
-      #   #28 pushing …/fabledcurator:c-0e15c44 with docker
+      # that was just pushed.
-      #   #28 ERROR: tag does not exist: …:c-0e15c44
+      - name: Repoint the tags at the published image (reuse)
-      #
+        if: steps.reuse.outputs.hit == 'true'
      # Intermittent — build-ml made the identical two-tag push seconds later
      # and succeeded — and worse than it looks. `:latest` had already
      # published, so production was correct while the immutable rollback tag
      # rule 145 requires of every main push simply did not exist. Nothing but
      # the red job would ever have noticed: a missing :c-<sha> has no
      # consumer that fails, so it surfaces when somebody needs to roll back.
      #
      # `imagetools create` is a registry-side manifest copy — no layer
      # transfer, no local daemon, nothing that can be absent. The reuse case
      # has always gone this way, so this puts the build case on the code that
      # was already proven rather than on a second path.
      #
      # Running on every path also keeps family rule 146 true: a rolling
      # channel refreshes itself, so skipping a build must never leave :dev or
      # :latest pointing at something older than the commit just pushed.
      #
      # The cost, accepted knowingly: `imagetools create` wraps its source in
      # an index, so :c-<sha> becomes an index and fc.revision does not
      # resolve through it. Nothing reads that label off :c-<sha> — the reuse
      # check only ever inspects the CHANNEL tag — and the index names the
      # same manifest, so a pull is byte-identical. The reuse path already
      # produced :c-<sha> this way; this only makes it uniform.
      - name: Write the remaining tags from the published image
        env:
          IMAGE: git.fabledsword.com/bvandeusen/fabledcurator
          SOURCE: ${{ steps.reuse.outputs.channel_ref }}
@@ -682,16 +650,15 @@ jobs:
          # ml:dev reported fc.revision=<none> one push after run 4749 had read
          # a7e626a67a79 off it. Nothing failed; the savings just evaporated.
          #
-          # Excluding the source means the channel tag is only ever written
+          # Excluding the source means the channel tag is only ever written by
-          # by a real build, so it stays a plain image and stays readable.
+          # a real build, so it stays a plain image and stays readable. On dev
-          # On dev that leaves nothing to do either way: the build pushed :dev
+          # that leaves nothing to do — :dev already points at the right
-          # itself, or the hit established it was already right. On main it
+          # content, which is what the hit established. On main it leaves
-          # leaves :c-<sha>, which rule 145 requires of every main push whether
+          # :c-<sha>, which rule 145 requires of every main push whether or not
-          # or not a build ran.
+          # a build ran.
          #
-          # steps.tag emits ONE comma-separated list; imagetools wants a -t per
+          # steps.tag emits ONE comma-separated list, because that is the shape
-          # ref. (That list used to feed docker/build-push-action directly —
+          # docker/build-push-action takes; imagetools wants a -t per ref.
          # which is exactly what #3190 made unsafe.)
          ARGS=""
          IFS=,
          for t in $TAGS; do
@@ -700,8 +667,8 @@ jobs:
          done
          unset IFS
          if [ -z "$ARGS" ]; then
-            echo "repoint: $SOURCE is the only tag for this channel and"
+            echo "repoint: $SOURCE already carries this revision and is the"
-            echo "repoint: already holds this revision — nothing to write."
+            echo "repoint: only tag for this channel — nothing to write."
            exit 0
          fi
          # shellcheck disable=SC2086
@@ -814,10 +781,12 @@ jobs:
        env:
          IMAGE: git.fabledsword.com/bvandeusen/fabledcurator-ml
          CHANNEL: ${{ steps.tag.outputs.channel }}
          TAGS: ${{ steps.tag.outputs.tags }}
        run: |
          set -eu
          DERIVED=$(sh scripts/artifacts.sh revision ml)
          echo "revision=$DERIVED" >> "$GITHUB_OUTPUT"
          echo "build_tags=$TAGS" >> "$GITHUB_OUTPUT"
          # The moving tag for this channel. Which tag we ask IS the channel —
          # that is why the revision needs no -main/-dev qualifier any more.
@@ -864,53 +833,24 @@ jobs:
          context: .
          file: Dockerfile.ml
          push: true
-          # ONE tag, the channel's. Every other tag is written by the step
+          tags: ${{ steps.reuse.outputs.build_tags }}
          # below, registry-side. buildx here pushes the first tag to the
          # registry and then re-pushes the rest through the DOCKER driver,
          # out of a local image store a registry-direct build never filled —
          # #3190, which cost `main` its :c-<sha> on 2026-08-29 while :latest
          # published perfectly well.
          tags: ${{ steps.reuse.outputs.channel_ref }}
          # The reuse key. Read back off the channel tag on the next push to
          # decide whether that push needs to build at all, so this is not
          # decoration — an unstamped image is one that will always rebuild.
          labels: |
            fc.revision=${{ steps.reuse.outputs.revision }}
-      # Every tag but the channel's own is written HERE, registry-side,
+      # Registry-side manifest copy: no layer transfer, no local daemon, no
-      # whether or not a build ran. Each -t becomes another reference to the
+      # rebuild. Each -t becomes another reference to the SAME manifest the
-      # SAME manifest the channel tag holds, so :c-<sha> is byte-identical to
+      # channel tag already holds, so :c-<sha> is byte-identical to what is
-      # what is published rather than a lookalike rebuild.
+      # published rather than a lookalike rebuild.
      #
-      # Owning the build path too is #3190's fix, not a tidy-up:
+      # Runs on EVERY reuse, which is what keeps family rule 146 true: a
-      #
+      # rolling channel refreshes itself, so skipping a build must never mean
-      #   #27 pushing …/fabledcurator:latest           DONE 15.8s
+      # leaving :dev or :latest pointing at something older than the commit
-      #   #28 pushing …/fabledcurator:c-0e15c44 with docker
+      # that was just pushed.
-      #   #28 ERROR: tag does not exist: …:c-0e15c44
+      - name: Repoint the tags at the published image (reuse)
-      #
+        if: steps.reuse.outputs.hit == 'true'
      # Intermittent — build-ml made the identical two-tag push seconds later
      # and succeeded — and worse than it looks. `:latest` had already
      # published, so production was correct while the immutable rollback tag
      # rule 145 requires of every main push simply did not exist. Nothing but
      # the red job would ever have noticed: a missing :c-<sha> has no
      # consumer that fails, so it surfaces when somebody needs to roll back.
      #
      # `imagetools create` is a registry-side manifest copy — no layer
      # transfer, no local daemon, nothing that can be absent. The reuse case
      # has always gone this way, so this puts the build case on the code that
      # was already proven rather than on a second path.
      #
      # Running on every path also keeps family rule 146 true: a rolling
      # channel refreshes itself, so skipping a build must never leave :dev or
      # :latest pointing at something older than the commit just pushed.
      #
      # The cost, accepted knowingly: `imagetools create` wraps its source in
      # an index, so :c-<sha> becomes an index and fc.revision does not
      # resolve through it. Nothing reads that label off :c-<sha> — the reuse
      # check only ever inspects the CHANNEL tag — and the index names the
      # same manifest, so a pull is byte-identical. The reuse path already
      # produced :c-<sha> this way; this only makes it uniform.
      - name: Write the remaining tags from the published image
        env:
          IMAGE: git.fabledsword.com/bvandeusen/fabledcurator-ml
          SOURCE: ${{ steps.reuse.outputs.channel_ref }}
@@ -929,16 +869,15 @@ jobs:
          # ml:dev reported fc.revision=<none> one push after run 4749 had read
          # a7e626a67a79 off it. Nothing failed; the savings just evaporated.
          #
-          # Excluding the source means the channel tag is only ever written
+          # Excluding the source means the channel tag is only ever written by
-          # by a real build, so it stays a plain image and stays readable.
+          # a real build, so it stays a plain image and stays readable. On dev
-          # On dev that leaves nothing to do either way: the build pushed :dev
+          # that leaves nothing to do — :dev already points at the right
-          # itself, or the hit established it was already right. On main it
+          # content, which is what the hit established. On main it leaves
-          # leaves :c-<sha>, which rule 145 requires of every main push whether
+          # :c-<sha>, which rule 145 requires of every main push whether or not
-          # or not a build ran.
+          # a build ran.
          #
-          # steps.tag emits ONE comma-separated list; imagetools wants a -t per
+          # steps.tag emits ONE comma-separated list, because that is the shape
-          # ref. (That list used to feed docker/build-push-action directly —
+          # docker/build-push-action takes; imagetools wants a -t per ref.
          # which is exactly what #3190 made unsafe.)
          ARGS=""
          IFS=,
          for t in $TAGS; do
@@ -947,8 +886,8 @@ jobs:
          done
          unset IFS
          if [ -z "$ARGS" ]; then
-            echo "repoint: $SOURCE is the only tag for this channel and"
+            echo "repoint: $SOURCE already carries this revision and is the"
-            echo "repoint: already holds this revision — nothing to write."
+            echo "repoint: only tag for this channel — nothing to write."
            exit 0
          fi
          # shellcheck disable=SC2086
@@ -1059,10 +998,12 @@ jobs:
        env:
          IMAGE: git.fabledsword.com/bvandeusen/fabledcurator-agent
          CHANNEL: ${{ steps.tag.outputs.channel }}
          TAGS: ${{ steps.tag.outputs.tags }}
        run: |
          set -eu
          DERIVED=$(sh scripts/artifacts.sh revision agent)
          echo "revision=$DERIVED" >> "$GITHUB_OUTPUT"
          echo "build_tags=$TAGS" >> "$GITHUB_OUTPUT"
          # The moving tag for this channel. Which tag we ask IS the channel —
          # that is why the revision needs no -main/-dev qualifier any more.
@@ -1109,53 +1050,24 @@ jobs:
          context: agent
          file: agent/Dockerfile
          push: true
-          # ONE tag, the channel's. Every other tag is written by the step
+          tags: ${{ steps.reuse.outputs.build_tags }}
          # below, registry-side. buildx here pushes the first tag to the
          # registry and then re-pushes the rest through the DOCKER driver,
          # out of a local image store a registry-direct build never filled —
          # #3190, which cost `main` its :c-<sha> on 2026-08-29 while :latest
          # published perfectly well.
          tags: ${{ steps.reuse.outputs.channel_ref }}
          # The reuse key. Read back off the channel tag on the next push to
          # decide whether that push needs to build at all, so this is not
          # decoration — an unstamped image is one that will always rebuild.
          labels: |
            fc.revision=${{ steps.reuse.outputs.revision }}
-      # Every tag but the channel's own is written HERE, registry-side,
+      # Registry-side manifest copy: no layer transfer, no local daemon, no
-      # whether or not a build ran. Each -t becomes another reference to the
+      # rebuild. Each -t becomes another reference to the SAME manifest the
-      # SAME manifest the channel tag holds, so :c-<sha> is byte-identical to
+      # channel tag already holds, so :c-<sha> is byte-identical to what is
-      # what is published rather than a lookalike rebuild.
+      # published rather than a lookalike rebuild.
      #
-      # Owning the build path too is #3190's fix, not a tidy-up:
+      # Runs on EVERY reuse, which is what keeps family rule 146 true: a
-      #
+      # rolling channel refreshes itself, so skipping a build must never mean
-      #   #27 pushing …/fabledcurator:latest           DONE 15.8s
+      # leaving :dev or :latest pointing at something older than the commit
-      #   #28 pushing …/fabledcurator:c-0e15c44 with docker
+      # that was just pushed.
-      #   #28 ERROR: tag does not exist: …:c-0e15c44
+      - name: Repoint the tags at the published image (reuse)
-      #
+        if: steps.reuse.outputs.hit == 'true'
      # Intermittent — build-ml made the identical two-tag push seconds later
      # and succeeded — and worse than it looks. `:latest` had already
      # published, so production was correct while the immutable rollback tag
      # rule 145 requires of every main push simply did not exist. Nothing but
      # the red job would ever have noticed: a missing :c-<sha> has no
      # consumer that fails, so it surfaces when somebody needs to roll back.
      #
      # `imagetools create` is a registry-side manifest copy — no layer
      # transfer, no local daemon, nothing that can be absent. The reuse case
      # has always gone this way, so this puts the build case on the code that
      # was already proven rather than on a second path.
      #
      # Running on every path also keeps family rule 146 true: a rolling
      # channel refreshes itself, so skipping a build must never leave :dev or
      # :latest pointing at something older than the commit just pushed.
      #
      # The cost, accepted knowingly: `imagetools create` wraps its source in
      # an index, so :c-<sha> becomes an index and fc.revision does not
      # resolve through it. Nothing reads that label off :c-<sha> — the reuse
      # check only ever inspects the CHANNEL tag — and the index names the
      # same manifest, so a pull is byte-identical. The reuse path already
      # produced :c-<sha> this way; this only makes it uniform.
      - name: Write the remaining tags from the published image
        env:
          IMAGE: git.fabledsword.com/bvandeusen/fabledcurator-agent
          SOURCE: ${{ steps.reuse.outputs.channel_ref }}
@@ -1174,16 +1086,15 @@ jobs:
          # ml:dev reported fc.revision=<none> one push after run 4749 had read
          # a7e626a67a79 off it. Nothing failed; the savings just evaporated.
          #
-          # Excluding the source means the channel tag is only ever written
+          # Excluding the source means the channel tag is only ever written by
-          # by a real build, so it stays a plain image and stays readable.
+          # a real build, so it stays a plain image and stays readable. On dev
-          # On dev that leaves nothing to do either way: the build pushed :dev
+          # that leaves nothing to do — :dev already points at the right
-          # itself, or the hit established it was already right. On main it
+          # content, which is what the hit established. On main it leaves
-          # leaves :c-<sha>, which rule 145 requires of every main push whether
+          # :c-<sha>, which rule 145 requires of every main push whether or not
-          # or not a build ran.
+          # a build ran.
          #
-          # steps.tag emits ONE comma-separated list; imagetools wants a -t per
+          # steps.tag emits ONE comma-separated list, because that is the shape
-          # ref. (That list used to feed docker/build-push-action directly —
+          # docker/build-push-action takes; imagetools wants a -t per ref.
          # which is exactly what #3190 made unsafe.)
          ARGS=""
          IFS=,
          for t in $TAGS; do
@@ -1192,8 +1103,8 @@ jobs:
          done
          unset IFS
          if [ -z "$ARGS" ]; then
-            echo "repoint: $SOURCE is the only tag for this channel and"
+            echo "repoint: $SOURCE already carries this revision and is the"
-            echo "repoint: already holds this revision — nothing to write."
+            echo "repoint: only tag for this channel — nothing to write."
            exit 0
          fi
          # shellcheck disable=SC2086
@@ -2,7 +2,7 @@ name: CI
 # CI lanes per FabledRulebook/forgejo.md "CI philosophy":
 #   - lint: ruff only, no dep install — fast-fail for the common lint bounce.
-#   - extension-version: the derived version resolves and is a shape AMO takes.
+#   - extension-version: the derived version resolves and MAJOR.MINOR agrees.
 #   - backend-lint-and-test: `pytest -m "not integration"`, no service containers.
 #   - frontend-build: vitest unit + vite build.
 #   - integration: pgvector + redis service containers; alembic + `pytest -m integration`.
@@ -58,12 +58,9 @@ jobs:
  # the extension.yml suite runs on node:24-slim, which is exactly why
  # version.spec.js sticks to packaging.sh's git-free subcommands.
  #   1. the derivation actually resolves on this commit
-  #   2. the derived string is one AMO will accept, checked against Mozilla's
+  #   2. MAJOR.MINOR agrees between the two files — the one part still hand-set,
-  #      own published grammar rather than a loose "digits and dots"
+  #      and packaging.sh reads it from manifest.json ALONE, so a divergence
-  #
+  #      ships a version package.json disagrees with
  # The MAJOR.MINOR-agreement check that used to be (2) is gone with milestone
  # 318 step 8: the committed version no longer seeds anything, so there is no
  # hand-set part left for the two files to disagree about.
  #
  # Deliberately NOT checked here: that the derived value beats what has already
  # been signed. That guard belongs in build.yml, where it compares against the
@@ -88,38 +85,27 @@ jobs:
          # busybox sh on the act_runner — no bashisms (family rule).
          VERSION=$(sh extension/scripts/packaging.sh version)
          echo "derived: $VERSION"
-
+          # The shape AMO accepts, and the shape build.yml will stamp.
-          # Mozilla's published grammar for AMO, transcribed verbatim from
+          if ! echo "$VERSION" | grep -qE '^[0-9]+(\.[0-9]+)*$'; then
-          # MDN's manifest.json/version page:
+            echo "ERROR: derived version '$VERSION' is not plain dotted-numeric."
-          #
+            echo "AMO would reject it, and build.yml stamps it verbatim."
          #     ^(0|[1-9][0-9]{0,8})([.](0|[1-9][0-9]{0,8})){0,3}$
          #
          # Not the looser `^[0-9]+(\.[0-9]+)*$` this lane used to carry. That
          # one passes `2026.08.29.0201`, which AMO REJECTS — a segment must be
          # the single digit 0 or start 1-9 — and it also passes five segments,
          # where AMO allows four. Both would surface as a failed sign with the
          # version already burned: AMO 409s on re-signing, so a rejected value
          # cannot be reclaimed and cannot be reused. This lane is the cheap
          # place to find out. (#3138, milestone 318 step 8.)
          if ! echo "$VERSION" | grep -qE '^(0|[1-9][0-9]{0,8})(\.(0|[1-9][0-9]{0,8})){0,3}$'; then
            echo "ERROR: derived version '$VERSION' is not a version AMO accepts."
            echo "AMO's grammar: ^(0|[1-9][0-9]{0,8})([.](0|[1-9][0-9]{0,8})){0,3}$"
            echo "Most likely cause: a zero-padded segment (08, 0201). The rest"
            echo "of the family pads; the extension must not — see packaging.sh."
            exit 1
          fi
-
+          mm() { grep -E '"version"' "$1" | head -1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([0-9]+\.[0-9]+).*/\1/'; }
-          # ...and the shape this project actually derives. AMO would happily
+          MAN=$(mm extension/manifest.json)
-          # take `1.0.3500147` too, so the grammar check alone would not notice
+          PKG=$(mm extension/package.json)
-          # a regression to the pre-318 shape — which orders BELOW everything
+          test -n "$MAN" || { echo "ERROR: no parseable version in extension/manifest.json"; exit 1; }
-          # signed since, and is unrecoverable once Firefox has the higher one.
+          test -n "$PKG" || { echo "ERROR: no parseable version in extension/package.json"; exit 1; }
-          if ! echo "$VERSION" | grep -qE '^20[0-9][0-9]\.[0-9]{1,2}\.[0-9]{1,2}\.[0-9]{1,4}$'; then
+          if [ "$MAN" != "$PKG" ]; then
-            echo "ERROR: derived version '$VERSION' is not YYYY.M.D.HHMM."
+            echo "ERROR: MAJOR.MINOR disagrees between the two files."
-            echo "Rule 148's CalVer is what build.yml signs; the old"
+            echo "  extension/manifest.json = $MAN  <- packaging.sh reads MAJOR.MINOR from here"
-            echo "1.0.<minutes> shape would order below every ext-2026.* release."
+            echo "  extension/package.json  = $PKG"
            echo "Only MAJOR.MINOR is hand-set. The patch component is derived from"
            echo "commit time and overwritten at build time, so the committed patch"
            echo "numbers are inert — but MAJOR.MINOR still ships. Set both the same."
            exit 1
          fi
-          echo "OK: derived version $VERSION"
+          echo "OK: MAJOR.MINOR $MAN, derived version $VERSION"
  backend-lint-and-test:
    runs-on: python-ci
@@ -71,25 +71,12 @@ per `docs/process.md`'s "add deps to the image when used by >1 project".
  published bytes?"*, not *"is this file copied in?"* — which is why the script
  keeps two lists rather than one.
 - **The shipped extension version is derived, not committed.** It is the commit
-  TIME of the newest packaged-extension change, rendered `YYYY.M.D.HHMM` UTC
+  TIME of the newest packaged-extension change (minutes since 2020-01-01, per
-  (family rules 148/149 — never a commit count, which orders by branch rather
+  family rule 149 — never a commit count, which orders by branch rather than by
-  than by recency). `build.yml`'s `sign-extension` computes it and stamps it
+  recency). `build.yml`'s `sign-extension` computes it and stamps it into
-  into `extension/manifest.json` + `package.json` in the working tree before
+  `extension/manifest.json` + `package.json` in the working tree before signing;
-  signing; the stamp is never committed. The version in the repo is **wholly
+  the stamp is never committed. Treat the version in the repo as a base: only
-  inert** — since milestone 318 step 8 there is no hand-set MAJOR.MINOR either.
+  its MAJOR.MINOR is read, and its patch component is inert.
 - **The extension is the one artifact that does not zero-pad, and that is not a
  drift** (#3138). Mozilla's grammar for AMO is
  `^(0|[1-9][0-9]{0,8})([.](0|[1-9][0-9]{0,8})){0,3}$` — a segment is the single
  digit `0` or starts 1-9, and there are at most four. `2026.08.29.0201` is
  rejected; `2026.8.29.201` is the same value one character narrower per
  segment, and rule 148 defines comparison as numeric per segment, so nothing is
  reordered. `ci.yml`'s `extension-version` lane asserts the derived string
  against that exact regex, plus a `YYYY.M.D.HHMM` shape check that would catch
  a regression to the pre-318 `1.0.<minutes>` — which AMO would accept and which
  orders below everything already signed. Checking here is the whole point: AMO
  409s on re-signing, so a version it rejects is burned and cannot be reused.
  `scripts/artifacts.sh version extension` **delegates** to `packaging.sh` so
  the two cannot answer differently.
 - Every job that derives anything checks out with `fetch-depth: 0` — all four
  `build.yml` jobs, `ci.yml`'s `extension-version` and `backend-lint-and-test`
  (for `tests/test_artifact_paths.py` and `test_artifact_identity.py`), and
@@ -121,18 +108,6 @@ per `docs/process.md`'s "add deps to the image when used by >1 project".
  source tag — `imagetools create` wraps its source in a manifest index, and
  config labels do not resolve through an index, so writing the channel tag
  from itself destroys the label the next run reads (#3183).
 - **The build pushes exactly ONE tag — the channel's — and every other tag is
  written registry-side afterwards** (#3190). buildx on this runner pushes the
  first tag to the registry and then re-pushes the rest through the docker
  driver, out of a local image store that a registry-direct build never fills;
  it fails intermittently with `tag does not exist`. On `dev` that only reddens
  a job, but on `main` it silently skips `:c-<sha>` while `:latest` publishes
  fine — a missing rollback tag has no consumer that fails, so nothing but the
  red job would notice until somebody needs to roll back. `imagetools create`
  has no local store to be absent from, and it is the code the reuse path
  already ran, so both paths now share one proven route. The cost: `:c-<sha>`
  is an index rather than a plain image, so `fc.revision` does not resolve
  through it — nothing reads it there, and the index names the same manifest.
 - **`FC_CHANNEL` and `FC_VERSION` are build args, not runtime settings.**
  `build.yml` passes them to the web image only — the ml and agent images have
  nothing to report them to. `/api/health` returns both, the foot of Settings
@@ -38,42 +38,27 @@ npm run build                # unsigned XPI in web-ext-artifacts/
 - [ ] Subscriptions list: popup → "Sources" tab → list renders
 - [ ] Check now: click play icon on source row → no error toast
-## Versioning — the committed number decides nothing
+## Versioning — don't hand-edit the patch number
 The shipped version is **derived**, not committed. `scripts/packaging.sh
-version` returns `YYYY.M.D.HHMM` in UTC: the commit *time* of the newest change
+version` returns `MAJOR.MINOR` from `manifest.json` plus a patch component
-to a packaged extension file. `build.yml` computes it and stamps it into both
+that is the commit *time* of the newest change to a packaged extension file,
 in minutes since 2020-01-01. `build.yml` computes it and stamps it into both
 `manifest.json` and `package.json` at build time. The stamp is never
 committed — the commit carrying it would itself be a change to the extension,
 which would move the version again.
 So:
- **Editing the version does nothing.** All of it is overwritten before web-ext
+- **Editing the patch number does nothing.** It is overwritten before web-ext
-  ever reads it. There is no bump to make, and none to forget. There is no
+  ever reads it. There is no bump to make, and none to forget.
-  hand-set part left either: MAJOR.MINOR went away with milestone 318 step 8.
+- **MAJOR.MINOR is still yours.** It carries the deliberate meaning, it is read
  from `manifest.json` alone, and CI fails the `extension-version` lane if the
  two files disagree on it.
 - `npm run build` locally produces an XPI labelled with the *committed*
  version, since nothing stamped it. Fine for loading into a test profile; not
  what ships.
 **Why the extension is the one artifact that does not zero-pad.** Every other
 FC artifact emits rule 148's `YYYY.MM.DD.HHMM`. AMO will not take it: Mozilla's
 grammar for addons.mozilla.org is
 ```
 ^(0|[1-9][0-9]{0,8})([.](0|[1-9][0-9]{0,8})){0,3}$
 ```
 — each segment is the single digit `0` or starts 1-9, so `08` and `0201` are
 rejected, and at most four segments are allowed. The extension therefore emits
 **the same numbers unpadded**: `2026.8.29.201` where the rest of the family
 says `2026.08.29.0201`. Rule 148 already defines comparison as numeric per
 segment, under which the two are equal, so nothing is reordered by the choice
 and left-padding each segment recovers the family string exactly. `ci.yml`'s
 `extension-version` lane checks the derived string against that regex on every
 push — the cheap place to find out, because AMO 409s on re-signing and a
 rejected version is burned for good.
 Why commit time and not a commit count: a count is per-branch, so `dev` and
 `main` count different histories of the same code and their versions end up
 ordered by which branch accumulated more commits rather than by which is newer.
@@ -60,7 +60,7 @@ NOT_PACKAGED_BUILD='web-ext-artifacts node_modules'
 NOT_VERSION_RELEVANT='package.json package-lock.json README.md .gitignore vitest.config.js test test/**'
 usage() {
-  echo "usage: packaging.sh {ignore|pathspec|version}" >&2
+  echo "usage: packaging.sh {ignore|pathspec|version|major-minor|patch}" >&2
  exit 2
 }
@@ -86,48 +86,36 @@ cmd_pathspec() {
  echo
 }
-# Strip leading zeros from one segment, leaving at least one digit.
+# MAJOR.MINOR stays hand-set in manifest.json — it's the part that carries
-#
+# deliberate meaning. Only the patch component is derived.
-# This exists for AMO and nothing else. Mozilla's version grammar for
+cmd_major_minor() {
-# addons.mozilla.org is documented as
+  root=$(git rev-parse --show-toplevel)
-#
+  grep -E '"version"' "$root/extension/manifest.json" \
-#     ^(0|[1-9][0-9]{0,8})([.](0|[1-9][0-9]{0,8})){0,3}$
+    | head -1 \
-#
+    | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([0-9]+)\.([0-9]+).*/\1.\2/'
 # — each segment is either the single digit `0` or starts 1-9, so `08` and
 # `0201` are rejected outright, while `0` itself is fine. MDN states it in
 # prose too: "Non-zero numbers must not include a leading zero."
 #
 # POSIX sh has no trim-loop, hence the while.
 unpad() {
  s=$1
  while [ "${#s}" -gt 1 ]; do
    case "$s" in
      0*) s=${s#0} ;;
      *)  break ;;
    esac
  done
  printf '%s' "$s"
 }
-# The extension's version: `YYYY.M.D.HHMM`, UTC, derived from the commit TIME
+# 2020-01-01T00:00:00Z — the anchor for the derived patch component. Fixed
-# of the newest change to a PACKAGED extension file.
+# forever; moving it would renumber every version downwards.
 VERSION_EPOCH=1577836800
 # Minutes since VERSION_EPOCH of the LATEST commit that touched a PACKAGED
 # extension file.
 #
-# THE ONE DELIBERATE DEPARTURE FROM THE FAMILY SHAPE, and it is a rendering
+# Time-derived, per family rule 149: an artifact's ordering key must never be a
-# difference only. Rule 148 says `YYYY.MM.DD.HHMM` zero-padded, and every other
+# commit count. A count is per-branch — `dev` and `main` count different
-# FC artifact emits exactly that. AMO's grammar (see unpad) forbids the padding,
+# histories of the same code — so the moment BOTH channels publish, their
-# and AMO is not negotiable: a rejected version is burned, since AMO 409s on
+# versions order by which branch accumulated more commits rather than by which
-# re-signing a version it has already seen. So the extension emits THE SAME
+# is newer. A squash-merge makes that permanent: main gains one commit where dev
-# NUMBERS unpadded — 2026.08.29.0201 and 2026.8.29.201 are one value in two
+# gained five, so dev climbs away from main and a dev install can never cross
-# renderings, and rule 148 already specifies comparison as numeric per segment,
+# back. That is Roundtable's 2026-08-24 incident (`versionCode` was the branch's
-# under which they are equal. Nothing published is reordered by the choice, and
+# commit count) in a different repo. Measured here on 2026-08-27: main=23,
-# left-padding each segment recovers the family string exactly.
+# dev=24 under the old formula — one apart, which is exactly how the inversion
-#
+# stays invisible until it strands somebody.
 # HHMM is one segment, not two, because AMO allows at most FOUR. Unpadded that
 # reads oddly (00:14 -> `14`, midnight -> `0`) but stays strictly increasing
 # within a day, which is all the ordering needs.
 #
 # Why the commit's time and not the build's:
-#   * MONOTONIC — max() over a set that only ever gains members.
+#   * MONOTONIC — max() over a set that only ever gains members. Verified
 #     across all 24 extension-touching commits: zero non-monotonic steps.
 #   * STABLE while the extension is unchanged, so an unchanged extension keeps
 #     its version, the ext-<version> signature cache still hits, and AMO is
 #     called once per extension CHANGE rather than once per push. Build-time
@@ -138,34 +126,24 @@ unpad() {
 #     produced for byte-identical code. Same code, same version, one signing.
 #   * REPRODUCIBLE — any checkout of a commit yields that commit's version.
 #
 # Never a commit count (family rule 149): a count is per-branch, so `dev` and
 # `main` count different histories of the same code and order by which branch
 # accumulated more commits rather than by which is newer. A squash-merge makes
 # that permanent. Roundtable's 2026-08-24 incident, in a different repo.
 #
 # Requires real history: a depth-1 clone sees one commit and will derive a wrong
 # (too low) value. Every consumer must check out with fetch-depth: 0.
-#
+cmd_patch() {
 # Formatted through git rather than date(1): busybox date does not reliably
 # accept `-d @<epoch>`, and git's --date=format-local is available wherever git
 # is. TZ=UTC so the value does not depend on the runner's timezone.
 cmd_version() {
  root=$(git rev-parse --show-toplevel)
  # Unquoted on purpose: the pathspec must word-split into separate args.
  # Globbing is already off script-wide (set -euf above).
  # shellcheck disable=SC2046
-  sha=$(cd "$root" && git log --format='%ct %H' HEAD -- extension/ $(cmd_pathspec) \
+  ts=$(cd "$root" && git log --format=%ct HEAD -- extension/ $(cmd_pathspec) \
-        | sort -n | tail -1 | cut -d' ' -f2)
+       | sort -n | tail -1)
-  if [ -z "$sha" ]; then
+  if [ -z "$ts" ]; then
    echo "packaging.sh: no commit touches a packaged extension file" >&2
    exit 1
  fi
-  padded=$(cd "$root" && TZ=UTC git show -s --format=%cd \
+  echo $(( (ts - VERSION_EPOCH) / 60 ))
-           --date='format-local:%Y.%m.%d.%H%M' "$sha")
+}
-  # Rebinding the function's own positional params, which are unused here.
+
-  # shellcheck disable=SC2046
+cmd_version() {
-  set -- $(echo "$padded" | tr '.' ' ')
+  echo "$(cmd_major_minor).$(cmd_patch)"
  echo "$(unpad "$1").$(unpad "$2").$(unpad "$3").$(unpad "$4")"
 }
 [ $# -ge 1 ] || usage
@@ -173,5 +151,7 @@ case "$1" in
  ignore)      cmd_ignore ;;
  pathspec)    cmd_pathspec ;;
  version)     cmd_version ;;
  major-minor) cmd_major_minor ;;
  patch)       cmd_patch ;;
  *)           usage ;;
 esac
@@ -8,10 +8,10 @@ const EXT_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..')
 const read = (name) => JSON.parse(readFileSync(path.join(EXT_DIR, name), 'utf8'))
 const readText = (...seg) => readFileSync(path.join(EXT_DIR, ...seg), 'utf8')
-// Only the git-free subcommands are exercised here: `version` shells out to
+// Only the git-free subcommands are exercised here: `version`/`patch` shell out
-// git, and the extension lane runs on node:24-bookworm-slim which may not ship
+// to git, and the extension lane runs on node:24-bookworm-slim which may not
-// it. That one is covered where git is guaranteed — ci.yml's extension-version
+// ship it. Those two are covered where git is guaranteed — ci.yml and build.yml
-// lane and build.yml both run on ci-python.
+// run on ci-python.
 const packaging = (cmd) =>
  execFileSync('sh', [path.join(EXT_DIR, 'scripts', 'packaging.sh'), cmd], {
    cwd: EXT_DIR,
@@ -145,33 +145,28 @@ describe('consumers delegate rather than keeping their own copy', () => {
 })
 describe('extension version', () => {
-  // Mozilla's published grammar for addons.mozilla.org, transcribed from MDN's
+  const majorMinor = (v) => v.split('.').slice(0, 2).join('.')
  // manifest.json/version page. Each segment is the single digit 0 or starts
  // 1-9 — so no leading zeros — and there are at most four of them.
  const AMO = /^(0|[1-9][0-9]{0,8})(\.(0|[1-9][0-9]{0,8})){0,3}$/
-  it('keeps a committed version AMO would accept, though it ships nothing', () => {
+  it('keeps the hand-set MAJOR.MINOR in lockstep across both files', () => {
-    // The committed value is wholly inert since milestone 318 step 8: there is
+    // Narrowed from full-string equality at milestone 271 step 5. Since step 4
-    // no hand-set MAJOR.MINOR left for packaging.sh to read, and build.yml
+    // the patch component is derived from commit time and stamped into both
-    // stamps the derived string over both files before web-ext sees them.
+    // files at build time, so the committed patch numbers are inert — nothing
    // reads them and they are not what ships. Asserting on them would fail for
    // a difference that changes nothing.
    //
-    // It is still asserted, for one reason: `npm run build` locally packages
+    // MAJOR.MINOR is the opposite: still hand-set, still shipped, and
-    // whatever is committed, so a value AMO would reject turns a local build
+    // packaging.sh reads it from manifest.json ALONE. Let the two diverge and
-    // into a confusing failure with no CI signal ahead of it. ci.yml checks
+    // the extension ships a version package.json disagrees with, with no other
-    // the same grammar against the DERIVED value, which is the one AMO sees.
+    // signal.
-    for (const file of ['manifest.json', 'package.json']) {
+    expect(majorMinor(read('manifest.json').version))
-      expect(read(file).version, `${file} version is not AMO-shaped`).toMatch(AMO)
+      .toBe(majorMinor(read('package.json').version))
    }
  })
-  it('rejects the zero-padded family shape, which is why the extension unpads', () => {
+  it('uses a plain dotted numeric version AMO will accept', () => {
-    // Guards the reason for the exception, not just its result. If this ever
+    // The committed value seeds MAJOR.MINOR, so it still has to parse even
-    // starts passing, someone has loosened the pattern and the next sign burns
+    // though its patch component never ships. ci.yml asserts the same shape on
-    // an AMO version to find out. (#3138.)
+    // the DERIVED value, which is the one AMO actually sees.
-    expect('2026.08.29.0201').not.toMatch(AMO)
+    expect(read('package.json').version).toMatch(/^\d+(\.\d+)*$/)
    expect('2026.8.29.201').toMatch(AMO)
    // Five segments: AMO allows four.
    expect('2026.8.29.2.1').not.toMatch(AMO)
  })
  it('declares manifest v3', () => {
@@ -170,21 +170,6 @@ cmd_revision() {
 # exists — at which point two lanes derive different answers for one source
 # and the shared-signature property is lost.
 cmd_version() {
  # The extension is the one artifact this script does not FORMAT, only route.
  # AMO's version grammar forbids leading zeros, so the extension emits the
  # same numbers unpadded (#3138) — a rendering exception, documented in
  # packaging.sh beside the signing step that has to obey it. Delegating keeps
  # one answer per artifact: `artifacts.sh version extension` and
  # `packaging.sh version` cannot drift into two.
  #
  # The direction is deliberate. artifacts.sh already asks packaging.sh for the
  # extension's PATH SET (ext_paths above), so the version has to flow the same
  # way; reversing it would have packaging.sh call back into this script, which
  # would call packaging.sh for the paths again.
  if [ "$1" = extension ]; then
    sh "$ROOT/extension/scripts/packaging.sh" version
    return
  fi
  sha=$(echo "$(newest "$1")" | cut -d' ' -f2)
  # One git call for the whole string rather than four and a sed. git's
  # format-local takes the complete format, and doing it in pieces was only