@norskvideo/ctl-dev-kit 0.2.63 → 0.2.65

package/build/flake.nix

@@ -13,7 +13,7 @@
 #                          integration) uses, so image builds never depend on the
 #                          ctl binary channel.
 #
-# The norsk-ctl pin below is bumped nightly by upgrade-latest; by hand with
+# The norsk-ctl pin below is bumped nightly by bump.yml; by hand with
 #   packages/dev-kit/build/refresh-ctl-pin.sh        (writes ctlVersion + hashes)
 {
   description = "norsk-ctl product build + dev shell";

package/build/flake.sdk-app.nix

@@ -10,7 +10,7 @@
   # an sdk-app's dev loop is its own SDK app plus a Norsk engine, not a
   # ctl-launched product container. It still PINS one: `ctlVersion` below is the
   # norsk-ctl the product's CI tiers (smoke) launch it with, read from here so a
-  # result belongs to a commit, and moved nightly by upgrade-latest. Decision: bun for tooling (install / build /
+  # result belongs to a commit, and moved nightly by bump.yml. Decision: bun for tooling (install / build /
   # test), Node for the shipped runtime (the SDK's blessed runtime).
   #
   # nixpkgs is pinned to the same rev the Studio flake uses, so bun matches the
@@ -29,7 +29,7 @@
 
   outputs = { self, nixpkgs, nixpkgs-biome }:
     let
-      # The norsk-ctl CI runs (see above); upgrade-latest moves it to `latest`.
+      # The norsk-ctl CI runs (see above); bump.yml moves it to `latest`.
       ctlVersion = "0.1.0-2026-09-15-81bbde8";
       systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
       forAllSystems = f: builtins.listToAttrs (map (s: { name = s; value = f s; }) systems);

package/build/refresh-ctl-pin.sh

@@ -36,4 +36,4 @@ done
 
 perl -0pi -e "s{(ctlVersion = \")[^\"]*(\")}{\${1}$ver\${2}}" "$flake"
 echo "updated $flake"
-echo "this is the starter's pin; each product's own flake.nix is bumped nightly by upgrade-latest"
+echo "this is the starter's pin; each product's own flake.nix is bumped nightly by bump.yml"

package/conventions/CLAUDE.core.md

@@ -79,17 +79,26 @@
   (`norsk-ctl serve`) + `norsk-ctl` on PATH (the nix shell) + `NORSK_LICENSE_FILE`.
   Anything the daemon can't see for you — a stored template, a rebuilt image — is
   stale until this loop re-runs; don't debug a ghost.
-- **The shared CI workflow is single-sourced too.** `.github/workflows/upgrade-latest.yml`
-  is copied verbatim from `@norskvideo/ctl-dev-kit` (`conventions/upgrade-latest.yml`),
+- **The shared CI workflows are single-sourced too.** `.github/workflows/bump.yml`
+  and the rest are copied verbatim from `@norskvideo/ctl-dev-kit` (`conventions/`),
   same as this core block and `nix/ctl-shell.nix`; `check:drift` fails CI if a copy
   diverges. Only the `product:` key is per-repo. Never hand-edit the copy — edit
   the dev-kit source and re-sync.
 - **CI runs the norsk-ctl this repo pins** (`flake.nix` `ctlVersion`), never S3's
-  moving `latest`; only a `ctl-candidate` run tests a channel (`rc`). The bump bots
-  (`upgrade-latest`, `sync-dev-kit`, `sync-ctl-packages`) never push to main: each
-  opens a PR, and `bot-prs` merges it once checks, smoke, integration and the
-  guides gate (build-image) are green on it. A red bot PR is the alarm for a bad
-  upstream change; main stays green.
+  moving `latest`; only a `ctl-candidate` run tests a channel (`rc`). One nightly
+  bump, `bump.yml`, moves the dev-kit, the ctl-* and moq-* packages, and the
+  engine/Studio/norsk-ctl pins together, and never pushes to main: it opens one PR
+  on `bump/nightly`, and `bot-prs` merges it once checks, smoke, integration and
+  the guides gate (build-image) are green on it. A red bump PR is the alarm for a
+  bad upstream change, and names what moved; main stays green. To land the rest
+  without a bad component: `gh workflow run bump.yml -f components=<the others>`
+  (`dev-kit`, `ctl-packages`, `pins`).
+- **Flaky checks stay out of gates, never out of sight.** The guides gate runs
+  the deterministic tiers; the engine tier runs beside it and reports (summary,
+  warning, cell detail) without gating until norsk-ctl task 57 is fixed. A
+  known-flaky test goes in `.github/quarantine.json` with an owner, a date and
+  an exit condition: `checks` leaves it out of the gating run, then runs it on
+  its own and reports it. Fix it and take it out; don't let an entry age.
 - **A config-driven workflow needs a parity-checked invariant contract.** If this
   product emits its Studio graph dynamically from config, its load-bearing rules
   are documented as stable-ID statements (`INV-<AREA>-<NNN>`) in an

package/conventions/bot-prs.yml

@@ -1,13 +1,16 @@
-# Land the pin bots' green PRs; put the red ones on the product dashboard.
+# Land the nightly bump's green PR; put a red one on the product dashboard.
 #
-# Three bots keep a product fresh: upgrade-latest (the Norsk nightly line and
-# the norsk-ctl pin), sync-dev-kit (this package) and sync-ctl-packages (the
-# ctl-* / moq-* npm family). All three ALWAYS open a PR and never push to main
-# (ci-workflows docs/dashboard/ci-fragility.md, proposal B): a bot's own gate
-# is lint, typecheck and unit tests, and the tiers that break on an upstream
-# change -- smoke, integration and the guides that gate build-image's publish
-# -- run on the PR. This workflow is what lands them. Nothing used to act on
-# those PRs: green
+# One bot keeps a product fresh: bump.yml, which moves the dev-kit, the ctl-* /
+# moq-* npm family, and the Norsk nightly pair and norsk-ctl pin in one run and
+# opens one PR on bump/nightly (ci-workflows docs/dashboard/ci-fragility.md,
+# proposal B2). It never pushes to main (proposal B): its own gate is lint,
+# typecheck and unit tests, and the tiers that break on an upstream change --
+# smoke, integration and the guides that gate build-image's publish -- run on
+# the PR. This workflow is what lands it. Until bump.yml, three bots did that
+# job, each with its own branch (upgrade-latest/*, sync-dev-kit/*,
+# chore/sync-ctl-packages); those are still triaged, so their PRs still in
+# flight when a product moves to bump.yml land or are reported like any other.
+# Nothing used to act on bot PRs: green
 # ones sat unmerged (studio's ctl-sdk was twenty releases behind on 2026-10-03,
 # its PR open since 09-03) and red ones were invisible, because the bot that
 # opened them reports success. With a product count that only goes up, "someone
@@ -23,8 +26,9 @@
 #     push alone cannot gate, and still runs on main after the merge. "Nothing
 #     failed yet" is not enough: a slow tier that has not started has no check
 #     run at all, so bot-prs used to merge before integration had begun;
-#   - it conflicts with main -> re-run the bot that owns the branch, ONCE per
-#     head, so it rebuilds the branch from today's main (see below);
+#   - it conflicts with main -> re-run bump.yml, ONCE per head, so it rebuilds
+#     the night from today's main (see below). Asked FIRST, whatever its
+#     checks say: the rebuild re-runs them all on the new base;
 #   - a check failed, it still conflicts after that rebuild, or it is a draft
 #     (the bot's own gate was red) -> list it, and report this repo's `bot-prs`
 #     cell RED on the product dashboard, which is the Discord message people
@@ -34,24 +38,30 @@
 #     workflow is broken, or does not run on PRs), so that is red too.
 # The cell goes green again once nothing is red.
 #
-# Why the conflict rebuild: the three bots fire within minutes of each other
-# each morning and all write package.json and bun.lock, each from main as it
-# stood. Whichever lands first leaves the other's open PR conflicting, and the
-# bot only rebuilds its branch on its next DAILY run -- so on 2026-10-09
-# commentary, probe and reuters each had a sync-ctl-packages PR "needing a
-# human" that a re-run of sync-ctl-packages fixed outright. Every bot rebuilds
-# from main when run: each force-pushes its branch from today's main and
-# closes any older PR of its own family. The marker comment caps it at one
+# Why the conflict rebuild: when the three bots fired within minutes of each
+# other, each writing package.json and bun.lock from main as it stood,
+# whichever landed first left the others conflicting, and a bot rebuilt its
+# branch only on its next DAILY run (2026-10-09: commentary, probe and reuters
+# each had a sync-ctl-packages PR "needing a human" that a re-run fixed). One
+# bump ends that, but a human's merge to main can still make bump/nightly
+# conflict. bump.yml rebuilds from main when run: it force-pushes bump/nightly
+# from today's main and closes any older bump PR, and an old bot's PR for each
+# component it moved -- so it is the rebuild for those branches too, whose own
+# workflows the move to bump.yml deleted. The marker comment caps it at one
 # rebuild per head, so a rebuild that still conflicts goes to a human instead
 # of looping every hour.
 #
+# It triages the bot PRs that target one base: main, unless a dispatch names
+# another (`base`). A trial of a dev-kit change against a throwaway branch is
+# triaged, rebuilt and merged there, never on main, and reports nothing.
+#
 # Runs when any gating tier finishes (the prompt path), hourly as a sweep,
 # and on demand. No checkout: it only talks to the GitHub API, so it needs none
 # of the runner-workspace steps the building workflows carry.
 #
 # Single-sourced in @norskvideo/ctl-dev-kit (conventions/bot-prs.yml) and copied
 # verbatim into each product repo -- it reads its dashboard key from this repo's
-# upgrade-latest.yml rather than carrying one -- so sync-drift creates it where
+# bump.yml rather than carrying one -- so sync-drift creates it where
 # absent and check:drift fails a copy that diverges. Never hand-edit the copy.
 name: bot-prs
 
@@ -62,6 +72,10 @@ on:
   schedule:
     - cron: "23 * * * *"
   workflow_dispatch:
+    inputs:
+      base:
+        description: "Triage the bot PRs that target this branch. main, unless trialling on a throwaway branch."
+        default: main
 
 permissions:
   contents: read
@@ -96,6 +110,7 @@ jobs:
           READ_TOKEN: ${{ github.token }}
           WRITE_TOKEN: ${{ secrets.CI_DISPATCH_TOKEN }}
           REPO: ${{ github.repository }}
+          BASE: ${{ inputs.base || 'main' }}
         run: |
           set -euo pipefail
           api="https://api.github.com/repos/$REPO"
@@ -114,12 +129,14 @@ jobs:
             exit 1
           }
 
-          # The bots own exactly these branches (see each workflow's PR step).
+          # The bump owns bump/nightly (see bump.yml's PR step); the other three
+          # are the retired bots' branches, still landed while in flight.
           pulls="$(gh_api "$api/pulls?state=open&per_page=100")"
           expect "listing open PRs" 'type == "array"' "$pulls"
-          prs="$(jq -c --arg repo "$REPO" '
+          prs="$(jq -c --arg repo "$REPO" --arg base "$BASE" '
             [.[] | select(.head.repo.full_name == $repo)
-                 | select(.head.ref | test("^(upgrade-latest/|sync-dev-kit/|chore/sync-ctl-packages$)"))
+                 | select(.base.ref == $base)
+                 | select(.head.ref | test("^(bump/nightly$|upgrade-latest/|sync-dev-kit/|chore/sync-ctl-packages$)"))
                  | {number, ref: .head.ref, sha: .head.sha, draft, url: .html_url}]' <<<"$pulls")"
 
           # Does this workflow (on stdin) run on pull_request? Only its `on:` block
@@ -204,12 +221,12 @@ jobs:
             fi
           }
 
-          # The workflow that owns each bot branch, i.e. the one that rebuilds it.
+          # The workflow that rebuilds each bot branch: bump.yml, for the retired
+          # bots' branches too (their workflows went when bump.yml arrived, and
+          # bump.yml supersedes their PRs for every component it moves).
           producer() {
             case "$1" in
-              upgrade-latest/*) echo upgrade-latest.yml ;;
-              sync-dev-kit/*) echo sync-dev-kit.yml ;;
-              chore/sync-ctl-packages) echo sync-ctl-packages.yml ;;
+              bump/nightly | upgrade-latest/* | sync-dev-kit/* | chore/sync-ctl-packages) echo bump.yml ;;
               *) echo "" ;;
             esac
           }
@@ -220,31 +237,14 @@ jobs:
           while IFS= read -r pr; do
             [ -n "$pr" ] || continue
             n="$(jq -r .number <<<"$pr")"; ref="$(jq -r .ref <<<"$pr")"; sha="$(jq -r .sha <<<"$pr")"
-            runs="$(gh_api "$api/commits/$sha/check-runs?per_page=100")"
-            expect "reading checks for #$n" '.check_runs | type == "array"' "$runs"
-            failed="$(jq -r '[.check_runs[] | select(.conclusion | IN("failure","cancelled","timed_out","action_required","startup_failure")) | .name] | unique | join(", ")' <<<"$runs")"
-            pending="$(jq -r '[.check_runs[] | select(.status != "completed")] | length' <<<"$runs")"
-            passed="$(jq -r '[.check_runs[] | select(.conclusion == "success")] | length' <<<"$runs")"
-            if [ -n "$failed" ]; then red+=("#$n $ref: failing $failed"); continue; fi
-            if [ "$(jq -r .draft <<<"$pr")" = "true" ]; then red+=("#$n $ref: draft (its bot's gate was red)"); continue; fi
-            if [ "$pending" -gt 0 ] || [ "$passed" -eq 0 ]; then echo "#$n $ref: checks not finished; next time"; continue; fi
-            # Every tier that runs on a bot PR must have PASSED on this head.
-            required="$(tiers_for "$sha")"
-            wf_runs="$(gh_api "$api/actions/runs?head_sha=$sha&per_page=100")"
-            expect "reading workflow runs for #$n" '.workflow_runs | type == "array"' "$wf_runs"
-            verdict="$(tier_verdict "$required" "$wf_runs" "$(date +%s)")"
-            case "$verdict" in
-              ok) ;;
-              red\ *) red+=("#$n $ref: ${verdict#red }"); continue ;;
-              rerun\ *)
-                for id in ${verdict#rerun }; do
-                  code="$(gh_actions -o /dev/null -w '%{http_code}' -X POST "$api/actions/runs/$id/rerun")"
-                  echo "#$n $ref: a gating tier (run $id) was cancelled; re-running it (HTTP $code)"
-                done
-                continue ;;
-              *) echo "#$n $ref: ${verdict#wait }; next time"; continue ;;
-            esac
-            # GitHub computes mergeability lazily; ask until it has an answer.
+            # Mergeability FIRST, before the checks are judged. A rebuild re-runs
+            # every tier on today's base, so a conflicting PR is rebuilt whatever
+            # its checks say: relay #11 (2026-10-10) carried a smoke failure from
+            # before main moved, was reported red for it, and sat conflicting
+            # for 90 minutes with its rebuild never asked for. Only a PR that
+            # still conflicts after its rebuild, or merges cleanly with red
+            # checks, is red. GitHub computes mergeability lazily; ask until it
+            # has an answer.
             mergeable=null
             for _ in 1 2 3 4 5; do
               mergeable="$(gh_api "$api/pulls/$n" | jq -r .mergeable)"
@@ -262,9 +262,9 @@ jobs:
               elif jq -e --arg m "$marker" 'any(.[]; .body | contains($m))' >/dev/null <<<"$comments"; then
                 red+=("#$n $ref: still does not merge cleanly with main after $wf rebuilt it")
               else
-                code="$(gh_actions -o /dev/null -w '%{http_code}' -X POST "$api/actions/workflows/$wf/dispatches" -d '{"ref":"main"}')"
+                code="$(gh_actions -o /dev/null -w '%{http_code}' -X POST "$api/actions/workflows/$wf/dispatches" -d "$(jq -nc --arg b "$BASE" '{ref:$b, inputs:{base:$b}}')")"
                 if [ "$code" = "204" ]; then
-                  body="$marker -- it conflicted with main (another bot landed first), so $wf was re-run to rebuild it from today's main. If the rebuilt branch conflicts too, this PR is reported for a human."
+                  body="$marker -- it conflicted with $BASE, so $wf was re-run to rebuild the bump from today's $BASE. If the rebuilt branch conflicts too, this PR is reported for a human."
                   gh_write -o /dev/null -X POST "$api/issues/$n/comments" -d "$(jq -nc --arg b "$body" '{body:$b}')" || true
                   rebuilt+=("#$n")
                   echo "#$n $ref: conflicts with main; re-ran $wf to rebuild it"
@@ -274,6 +274,30 @@ jobs:
               fi
               continue
             fi
+            runs="$(gh_api "$api/commits/$sha/check-runs?per_page=100")"
+            expect "reading checks for #$n" '.check_runs | type == "array"' "$runs"
+            failed="$(jq -r '[.check_runs[] | select(.conclusion | IN("failure","cancelled","timed_out","action_required","startup_failure")) | .name] | unique | join(", ")' <<<"$runs")"
+            pending="$(jq -r '[.check_runs[] | select(.status != "completed")] | length' <<<"$runs")"
+            passed="$(jq -r '[.check_runs[] | select(.conclusion == "success")] | length' <<<"$runs")"
+            if [ -n "$failed" ]; then red+=("#$n $ref: failing $failed"); continue; fi
+            if [ "$(jq -r .draft <<<"$pr")" = "true" ]; then red+=("#$n $ref: draft (its bot's gate was red)"); continue; fi
+            if [ "$pending" -gt 0 ] || [ "$passed" -eq 0 ]; then echo "#$n $ref: checks not finished; next time"; continue; fi
+            # Every tier that runs on a bot PR must have PASSED on this head.
+            required="$(tiers_for "$sha")"
+            wf_runs="$(gh_api "$api/actions/runs?head_sha=$sha&per_page=100")"
+            expect "reading workflow runs for #$n" '.workflow_runs | type == "array"' "$wf_runs"
+            verdict="$(tier_verdict "$required" "$wf_runs" "$(date +%s)")"
+            case "$verdict" in
+              ok) ;;
+              red\ *) red+=("#$n $ref: ${verdict#red }"); continue ;;
+              rerun\ *)
+                for id in ${verdict#rerun }; do
+                  code="$(gh_actions -o /dev/null -w '%{http_code}' -X POST "$api/actions/runs/$id/rerun")"
+                  echo "#$n $ref: a gating tier (run $id) was cancelled; re-running it (HTTP $code)"
+                done
+                continue ;;
+              *) echo "#$n $ref: ${verdict#wait }; next time"; continue ;;
+            esac
             # sha pins the merge to what was checked: a bot force-pushing the
             # branch meanwhile makes this refuse rather than land unchecked code.
             res="$(gh_write -X PUT "$api/pulls/$n/merge" -d "$(jq -nc --arg sha "$sha" '{merge_method:"squash", sha:$sha}')")"
@@ -304,7 +328,8 @@ jobs:
 
       - name: Report to the product dashboard
         # Always: a triage that broke is exactly what nobody would otherwise see.
-        if: always()
+        # But only for main: a trial against another base must not paint the board.
+        if: always() && (inputs.base || 'main') == 'main'
         env:
           TOKEN: ${{ secrets.CI_DISPATCH_TOKEN }}
           READ_TOKEN: ${{ github.token }}
@@ -317,13 +342,18 @@ jobs:
           REPO: ${{ github.repository }}
         run: |
           set -euo pipefail
-          # The dashboard key is the one upgrade-latest.yml reports under, read
-          # from it so this file can stay byte-identical across products.
-          product="$(curl -sS -H "Authorization: Bearer $READ_TOKEN" -H "Accept: application/vnd.github.raw" \
-            "https://api.github.com/repos/$REPO/contents/.github/workflows/upgrade-latest.yml" \
-            | sed -nE 's/^[[:space:]]*product:[[:space:]]*([^[:space:]]+).*/\1/p' | head -1)"
+          # The dashboard key is the one bump.yml reports under, read from it so
+          # this file can stay byte-identical across products; upgrade-latest.yml
+          # carried it before bump.yml did. -f: a 404 must not read as a key.
+          product=""
+          for wf in bump.yml upgrade-latest.yml; do
+            product="$(curl -fsS -H "Authorization: Bearer $READ_TOKEN" -H "Accept: application/vnd.github.raw" \
+              "https://api.github.com/repos/$REPO/contents/.github/workflows/$wf" 2>/dev/null \
+              | sed -nE 's/^[[:space:]]*product:[[:space:]]*([^[:space:]]+).*/\1/p' | head -1 || true)"
+            [ -z "$product" ] || break
+          done
           if [ -z "$product" ] || [ "$product" = "__PRODUCT__" ]; then
-            echo "::warning::no product key in upgrade-latest.yml; not reporting to the dashboard"
+            echo "::warning::no product key in bump.yml; not reporting to the dashboard"
             exit 0
           fi
           ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

package/conventions/build-docs.yml

@@ -164,15 +164,40 @@ jobs:
           NORSK_LICENSE_V2: ${{ secrets.NORSK_LICENSE_V2 }}
         run: printf '%s' "$NORSK_LICENSE_V2" > "$RUNNER_TEMP/norsk-license.json"
 
+      # Every norsk-ctl daemon starts the node MoQ relay (norsk-moq-relay) unless
+      # told not to, and nothing removes it: it is a node singleton, and the reap
+      # step only takes containers that mount this job's test-temp. So the first
+      # test daemon on a shared runner left one, and every later one adopted it
+      # (probe's smoke ran in relay mode on 2026-10-10; relay's smoke lost 4443
+      # to it). This job's daemons run without the node relay and discovery, so
+      # they neither start nor adopt one, and whatever is already on the host is
+      # named here. It reports and never fails: the leftover may be someone's.
+      - name: Isolate this job from node singletons other jobs left on this host
+        run: |
+          set -uo pipefail
+          echo "NORSK_CTL_MOQ_RELAY_ENABLE=0" >> "$GITHUB_ENV"
+          echo "NORSK_CTL_DISCOVERY_ENABLE=0" >> "$GITHUB_ENV"
+          left="$(docker ps -a --filter label=norsk-ctl.role --format '{{.Names}} {{.Label "norsk-ctl.role"}} {{.Status}} (created {{.CreatedAt}})' 2>/dev/null || true)"
+          if [ -z "$left" ]; then echo "no norsk-ctl containers on this host"; exit 0; fi
+          echo "norsk-ctl containers already on this host (other jobs' running instances are expected):"
+          echo "$left"
+          while IFS= read -r line; do
+            role="$(awk '{print $2}' <<<"$line")"
+            case "$role" in
+              moq-relay|discovery)
+                echo "::warning title=node singleton left on this host::$line -- left by an earlier job (a daemon's auto-start, or a run killed before its reap). This job's daemons run without it and will not adopt it; remove it with docker rm -f if nothing on this host needs it." ;;
+            esac
+          done <<<"$left"
+
       # The norsk-ctl this commit pins (flake.nix ctlVersion, moved by
-      # upgrade-latest's bump PR), never S3's moving `latest`: a guide run is then
+      # bump.yml's nightly PR), never S3's moving `latest`: a guide run is then
       # a real repeat, and a red belongs to a commit (ci-fragility proposal A).
       - name: Download the pinned norsk-ctl binary (flake.nix ctlVersion)
         run: |
           set -euo pipefail
           S3="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl"
           ver="$( { sed -nE 's/^[[:space:]]*ctlVersion = "([^"]+)";.*/\1/p' flake.nix 2>/dev/null || true; } | head -1)"
-          [ -n "$ver" ] || { echo "::error::flake.nix pins no ctlVersion. CI runs the norsk-ctl this commit pins (upgrade-latest moves it); add ctlVersion = \"<version>\"; to flake.nix."; exit 1; }
+          [ -n "$ver" ] || { echo "::error::flake.nix pins no ctlVersion. CI runs the norsk-ctl this commit pins (the nightly bump.yml moves it); add ctlVersion = \"<version>\"; to flake.nix."; exit 1; }
           echo "norsk-ctl pinned by flake.nix ctlVersion -> $ver"
           curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/$ver/norsk-ctl-$ver-linux-x64" -o "$RUNNER_TEMP/norsk-ctl"
           chmod +x "$RUNNER_TEMP/norsk-ctl"