@norskvideo/ctl-dev-kit 0.1.95 → 0.1.96

package/build/flake.sdk-app.nix

@@ -0,0 +1,64 @@
+{
+  # Dev shell for a ctl "sdk-app" product — a bespoke Norsk SDK application
+  # (its runtime is its own daemon, not a composed Studio workflow launched by
+  # norsk-ctl). Single-sourced in @norskvideo/ctl-dev-kit (build/flake.sdk-app.nix)
+  # and copied verbatim into each sdk-app product repo (nix needs a flake.nix at
+  # the repo root for `nix develop`; it can't pull one from an npm package at CI
+  # bootstrap). Drift-gated for products whose package.json declares
+  # `"ctlProduct": { "shape": "sdk-app" }`.
+  #
+  # Unlike the Studio-product flake (build/flake.nix) this does NOT fetch the
+  # norsk-ctl daemon — an sdk-app's dev loop is its own SDK app plus a Norsk
+  # engine, not a ctl-launched product container. 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
+  # fleet's 1.3.13.
+  description = "norsk-ctl sdk-app product dev shell (bun tooling + node runtime)";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/d233902339c02a9c334e7e593de68855ad26c4cb"; # nixpkgs-unstable 2026-05-15, bun 1.3.13
+    # Biome must match the version pinned in package.json (@biomejs/biome 2.5.5)
+    # exactly; the node_modules biome binary is glibc-linked and can't run on
+    # NixOS, so `bun run lint` execs this nix build via BIOME_BINARY. Keep this
+    # pin in step with package.json's @biomejs/biome version (same rev the Studio
+    # flake uses).
+    nixpkgs-biome.url = "github:NixOS/nixpkgs/a5cbcfe954791221bfffe2307f7d1a1bf61a871e"; # biome 2.5.5
+  };
+
+  outputs = { self, nixpkgs, nixpkgs-biome }:
+    let
+      systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
+      forAllSystems = f: builtins.listToAttrs (map (s: { name = s; value = f s; }) systems);
+    in {
+      devShells = forAllSystems (system:
+        let
+          pkgs = import nixpkgs {
+            inherit system;
+            config.allowUnfree = true;
+          };
+          biome = (import nixpkgs-biome { inherit system; }).biome;
+          ffmpegFull = pkgs.ffmpeg-full;
+          tools = [
+            biome # `bun run lint` execs this via BIOME_BINARY (see below)
+            pkgs.bun # tooling: install / build / test (fleet parity, dev-kit)
+            pkgs.nodejs # the shipped runtime (bin/run -> node lib/index.js); also
+                        # parses @biomejs/biome's JS wrapper that reads BIOME_BINARY
+            pkgs.git
+            ffmpegFull # integration suites spawn a local ffmpeg (e.g. SRT egress capture)
+          ] ++ pkgs.lib.optionals pkgs.stdenv.isLinux [ pkgs.chromium ];
+        in {
+          default = pkgs.mkShell {
+            BIOME_BINARY = "${biome}/bin/biome";
+            buildInputs = tools;
+            shellHook = ''
+              export NIXPKGS_ALLOW_UNFREE=1
+              export FFMPEG_FULL=${ffmpegFull}
+            '' + pkgs.lib.optionalString pkgs.stdenv.isLinux ''
+              export BROWSER_FOR_TESTING=${pkgs.chromium}/bin/chromium
+            '';
+          };
+        });
+    };
+}

package/conventions/check-drift.ts

@@ -109,12 +109,12 @@ function workflowProblem(
 export const CTL_VERSION_LINE = /ctlVersion = "[^"]*";/;
 export const CTL_HASH_LINE = /hash = "sha256-[^"]*";/g;
 
-function flakeProblem(actual: string, canonical: string): string | undefined {
+function flakeProblem(actual: string, canonical: string, canonicalRef = "build/flake.nix"): string | undefined {
   const mask = (s: string) =>
     s.replace(CTL_VERSION_LINE, 'ctlVersion = "__CTL__";').replace(CTL_HASH_LINE, 'hash = "sha256-__HASH__";');
   const [ma, mc] = [mask(actual), mask(canonical)];
   if (ma === mc) return undefined;
-  return `flake.nix has drifted from @norskvideo/ctl-dev-kit build/flake.nix (${firstDiffLine(ma, mc)}). ${RESYNC}`;
+  return `flake.nix has drifted from @norskvideo/ctl-dev-kit ${canonicalRef} (${firstDiffLine(ma, mc)}). ${RESYNC}`;
 }
 
 // dprint.json is canonical-plus-extension: the shared config is verbatim, but a
@@ -276,6 +276,15 @@ export interface CanonicalBytes {
    *  hand copy is how build-docs.yml came to fail in both turnkeys, which never
    *  made one. */
   withDisplay: string;
+  /** build/flake.sdk-app.nix — the flake canonical for a `shape: "sdk-app"`
+   *  product (bun tooling + node runtime, no norsk-ctl daemon fetch). Optional so
+   *  a studio-only caller (and the existing test fixtures) need not supply it;
+   *  required when a repo declares the sdk-app shape. */
+  flakeSdkApp?: string;
+  /** conventions/checks.sdk-app.yml — the checks.yml variant for an sdk-app: the
+   *  Studio licence step removed (it reads shared/src/version.ts +
+   *  product-template.ts). Optional for the same reason as flakeSdkApp. */
+  checksSdkApp?: string;
 }
 
 // 05-demo s6: a product that has a demo (tests/demo.spec.ts) exposes it the
@@ -348,11 +357,35 @@ function verbatimProblem(
   return undefined;
 }
 
+// A product's shape. `studio` (the default, and every product before this) is a
+// control-plane backend composing a Norsk Studio workflow launched by the
+// norsk-ctl daemon. `sdk-app` is a bespoke Norsk SDK application whose runtime is
+// its own daemon — no Studio workflow, no {media,studio} seed, no ctl-daemon
+// flake, no product-template licence handshake. The shape selects which canonical
+// a shape-variant file is gated against and which studio-only checks are skipped;
+// absent ⇒ `studio`, so existing repos are unaffected.
+export type ProductShape = "studio" | "sdk-app";
+
 export interface CheckDriftOptions {
   /** The GitHub repo name (`norsk-ctl-product-playout`), which decides whether the
    *  public docs variant may be carried. The CLI resolves it ({@link resolveRepoName});
    *  a fixture passes it. Unknown is allowed only while nothing depends on it. */
   repoName?: string;
+  /** The product shape ({@link resolveShape}); a fixture passes it. Absent ⇒ `studio`. */
+  shape?: ProductShape;
+}
+
+/** A product's shape from `package.json` `ctlProduct.shape`; `studio` when the
+ *  field (or the file) is absent, so every existing repo keeps its behaviour. */
+export function resolveShape(repoRoot: string): ProductShape {
+  try {
+    const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")) as {
+      ctlProduct?: { shape?: string };
+    };
+    return pkg.ctlProduct?.shape === "sdk-app" ? "sdk-app" : "studio";
+  } catch {
+    return "studio";
+  }
 }
 
 /** `owner/name` from GITHUB_REPOSITORY (Actions), else the last path segment of
@@ -405,6 +438,7 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
   const push = (problem: string | undefined) => {
     if (problem) problems.push(problem);
   };
+  const shape: ProductShape = opts.shape ?? "studio";
 
   const claudePath = join(repoRoot, "CLAUDE.md");
   if (!existsSync(claudePath)) {
@@ -413,13 +447,20 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
     push(coreProblem(readFileSync(claudePath, "utf8"), canonical.core));
   }
 
+  // flake.nix is shape-selected: the studio flake fetches the norsk-ctl daemon,
+  // the sdk-app flake does not. Both are gated the same way (ctl pins masked; the
+  // sdk-app flake carries none, so it is effectively byte-verbatim).
   const flakePath = join(repoRoot, "flake.nix");
-  if (!existsSync(flakePath)) {
+  const flakeCanon = shape === "sdk-app" ? canonical.flakeSdkApp : canonical.flake;
+  const flakeRef = shape === "sdk-app" ? "build/flake.sdk-app.nix" : "build/flake.nix";
+  if (flakeCanon === undefined) {
+    throw new Error(`checkDrift: shape "${shape}" requires canonical.${shape === "sdk-app" ? "flakeSdkApp" : "flake"}`);
+  } else if (!existsSync(flakePath)) {
     problems.push(
-      `flake.nix not found at repo root (${flakePath}). It is copied verbatim from @norskvideo/ctl-dev-kit build/flake.nix.`,
+      `flake.nix not found at repo root (${flakePath}). It is copied verbatim from @norskvideo/ctl-dev-kit ${flakeRef}.`,
     );
   } else {
-    const problem = flakeProblem(readFileSync(flakePath, "utf8"), canonical.flake);
+    const problem = flakeProblem(readFileSync(flakePath, "utf8"), flakeCanon, flakeRef);
     if (problem) problems.push(problem);
   }
   push(verbatimProblem(repoRoot, "biome.json", "conventions/biome.base.json", canonical.biome));
@@ -443,13 +484,18 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
     push(dprintProblem(readFileSync(dprintPath, "utf8"), canonical.dprint));
   }
 
-  const seedPath = join(repoRoot, "manifest.seed.json");
-  if (!existsSync(seedPath)) {
-    problems.push(
-      `manifest.seed.json not found at repo root (${seedPath}). Every product pins its {media, studio} pair there (RFC 0001 Workstream C).`,
-    );
-  } else {
-    push(seedProblem(readFileSync(seedPath, "utf8")));
+  // manifest.seed.json pins a {media, studio} image pair — a Studio-product
+  // concept. An sdk-app is its own runtime (no Studio image), so it carries no
+  // seed and the check does not apply.
+  if (shape === "studio") {
+    const seedPath = join(repoRoot, "manifest.seed.json");
+    if (!existsSync(seedPath)) {
+      problems.push(
+        `manifest.seed.json not found at repo root (${seedPath}). Every product pins its {media, studio} pair there (RFC 0001 Workstream C).`,
+      );
+    } else {
+      push(seedProblem(readFileSync(seedPath, "utf8")));
+    }
   }
 
   const gitignorePath = join(repoRoot, ".gitignore");
@@ -461,13 +507,18 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
     push(gitignoreProblem(readFileSync(gitignorePath, "utf8"), canonical.gitignoreCore));
   }
 
-  const buildImagePath = join(repoRoot, "deployment", "build-image.sh");
-  if (!existsSync(buildImagePath)) {
-    problems.push(
-      `deployment/build-image.sh not found (${buildImagePath}). Every product ships the thin wrapper over the dev-kit build; see build/build-image.bootstrap.sh.`,
-    );
-  } else {
-    push(buildImageProblem(readFileSync(buildImagePath, "utf8"), canonical.buildImageBootstrap));
+  // deployment/build-image.sh wraps the dev-kit bundle-image build (a
+  // daemon-launched product container on port 4321). An sdk-app ships its own
+  // container, not the bundle image, so the wrapper does not apply.
+  if (shape === "studio") {
+    const buildImagePath = join(repoRoot, "deployment", "build-image.sh");
+    if (!existsSync(buildImagePath)) {
+      problems.push(
+        `deployment/build-image.sh not found (${buildImagePath}). Every product ships the thin wrapper over the dev-kit build; see build/build-image.bootstrap.sh.`,
+      );
+    } else {
+      push(buildImageProblem(readFileSync(buildImagePath, "utf8"), canonical.buildImageBootstrap));
+    }
   }
 
   // checks.yml is REQUIRED — it is the CI entry point that runs this very gate
@@ -476,12 +527,18 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
   // upgrade-latest.yml's.
   const checksPath = join(repoRoot, ".github", "workflows", "checks.yml");
   const checksRel = ".github/workflows/checks.yml";
-  if (!existsSync(checksPath)) {
+  const checksCanon = shape === "sdk-app" ? canonical.checksSdkApp : canonical.checks;
+  const checksRef = shape === "sdk-app" ? "conventions/checks.sdk-app.yml" : "conventions/checks.yml";
+  if (checksCanon === undefined) {
+    throw new Error(
+      `checkDrift: shape "${shape}" requires canonical.${shape === "sdk-app" ? "checksSdkApp" : "checks"}`,
+    );
+  } else if (!existsSync(checksPath)) {
     problems.push(
-      `${checksRel} not found (${checksPath}). Copy conventions/checks.yml from @norskvideo/ctl-dev-kit and set \`product:\` to this repo's dashboard key.`,
+      `${checksRel} not found (${checksPath}). Copy ${checksRef} from @norskvideo/ctl-dev-kit and set \`product:\` to this repo's dashboard key.`,
     );
   } else {
-    push(workflowProblem(checksRel, "conventions/checks.yml", readFileSync(checksPath, "utf8"), canonical.checks));
+    push(workflowProblem(checksRel, checksRef, readFileSync(checksPath, "utf8"), checksCanon));
   }
 
   // build-image.yml is REQUIRED — every product builds its image in CI (a
@@ -489,22 +546,27 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
   // lines are per-repo: the notify job's `product:` dispatch key and the
   // PUBLISH_IMAGE env (the Docker Hub repo, or empty for a build-only product);
   // both are masked.
-  const buildImageYmlPath = join(repoRoot, ".github", "workflows", "build-image.yml");
-  const buildImageYmlRel = ".github/workflows/build-image.yml";
-  if (!existsSync(buildImageYmlPath)) {
-    problems.push(
-      `${buildImageYmlRel} not found (${buildImageYmlPath}). Copy conventions/build-image.yml from @norskvideo/ctl-dev-kit, set \`product:\` to this repo's dashboard key, and set PUBLISH_IMAGE to its Docker Hub repo (empty for a build-only product).`,
-    );
-  } else {
-    push(
-      workflowProblem(
-        buildImageYmlRel,
-        "conventions/build-image.yml",
-        readFileSync(buildImageYmlPath, "utf8"),
-        canonical.buildImage,
-        [PRODUCT_LINE, PUBLISH_IMAGE_LINE],
-      ),
-    );
+  // build-image.yml builds the bundle image in CI — studio-product-shaped, so
+  // required only for the studio shape. (An sdk-app's own container build is not
+  // the dev-kit bundle image; it is out of scope for the shared gate today.)
+  if (shape === "studio") {
+    const buildImageYmlPath = join(repoRoot, ".github", "workflows", "build-image.yml");
+    const buildImageYmlRel = ".github/workflows/build-image.yml";
+    if (!existsSync(buildImageYmlPath)) {
+      problems.push(
+        `${buildImageYmlRel} not found (${buildImageYmlPath}). Copy conventions/build-image.yml from @norskvideo/ctl-dev-kit, set \`product:\` to this repo's dashboard key, and set PUBLISH_IMAGE to its Docker Hub repo (empty for a build-only product).`,
+      );
+    } else {
+      push(
+        workflowProblem(
+          buildImageYmlRel,
+          "conventions/build-image.yml",
+          readFileSync(buildImageYmlPath, "utf8"),
+          canonical.buildImage,
+          [PRODUCT_LINE, PUBLISH_IMAGE_LINE],
+        ),
+      );
+    }
   }
 
   // upgrade-latest.yml is OPTIONAL — a product may ship without a nightly bump
@@ -661,8 +723,13 @@ if (import.meta.main) {
     smoke: readFileSync(join(import.meta.dir, "smoke.yml"), "utf8"),
     integration: readFileSync(join(import.meta.dir, "integration.yml"), "utf8"),
     demoShim: readFileSync(join(import.meta.dir, "demo.sh"), "utf8"),
+    flakeSdkApp: readFileSync(join(import.meta.dir, "..", "build", "flake.sdk-app.nix"), "utf8"),
+    checksSdkApp: readFileSync(join(import.meta.dir, "checks.sdk-app.yml"), "utf8"),
   };
-  const report = checkDrift(repoRoot, canonical, { repoName: resolveRepoName(repoRoot) });
+  const report = checkDrift(repoRoot, canonical, {
+    repoName: resolveRepoName(repoRoot),
+    shape: resolveShape(repoRoot),
+  });
   if (report.ok) {
     console.log("drift-check: all shared-convention copies match @norskvideo/ctl-dev-kit.");
     process.exit(0);

package/conventions/checks.sdk-app.yml

@@ -0,0 +1,276 @@
+# Pre-merge gates for an "sdk-app" product, single-sourced in @norskvideo/ctl-dev-kit
+# (conventions/checks.sdk-app.yml) and drift-checked — only the ci-status-dispatch
+# `product:` key is per-repo. This is the checks.yml variant for a bespoke-SDK
+# product: identical to the Studio checks.yml EXCEPT it omits the licence step
+# (that step reads shared/src/version.ts + product-template.ts, which a
+# non-Studio product does not have). Keep the two in lockstep otherwise.
+#
+# Two jobs:
+#   - drift: the RFC 0001 Workstream I shared-conventions drift-check. Fails if
+#     this repo's forced copies have diverged from the pinned dev-kit — the
+#     fenced CLAUDE.md core, flake.nix, the shared config files, the manifest
+#     seed. Copies exist so a human reads them on GitHub with no tooling; the
+#     gate is the only thing keeping them true.
+#   - quality: the repo's own lint + typecheck + unit tests + docs path lint,
+#     via the shared package.json script interface every product carries. The
+#     "whole project clean" convention in the CLAUDE core has no teeth without
+#     this; docs:check is what keeps README/CLAUDE/docs paths true.
+#
+# Both run the same proven way build-image does — inside `nix develop .#build`
+# (which provides bun) on the x64 self-hosted pool — but skip the Docker image
+# build, so they also gate pull requests. To re-sync after a legitimate dev-kit
+# change: bump the @norskvideo/ctl-dev-kit pin, then copy the new files in.
+name: checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  drift:
+    runs-on: x64
+    steps:
+      # Runs BEFORE checkout, and does two things: points the harness's temp base
+      # out of the workspace for every later step in this job, and clears whatever
+      # the old repo-local default left behind on this runner. The body carries the
+      # why. It fails the job only when legacy litter survives -- which would take
+      # the checkout down a step later anyway, but report nothing useful.
+      - name: Route test-temp out of the workspace (pre-checkout)
+        run: |
+          set -uo pipefail
+          # These runners are docker-OUTSIDE-of-docker, so a bind-mount source the
+          # HOST daemon has not seen before is created by dockerd, as ROOT, on the
+          # host -- even when the launch passes --container-user (reproduced
+          # 2026-09-04). The harness's default base is repo-local for an OrbStack
+          # inotify constraint that binds macOS dev and nothing here, so every run
+          # seeded the CHECKOUT with root-owned dirs a non-root `git clean -ffdx`
+          # cannot remove. That took commentary's checks AND integration red on
+          # 2026-09-03. Use the sanctioned override, per-run and outside the
+          # checkout -- as 8ff17a8d did in June for one debug workflow, and stopped.
+          base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+          mkdir -p "$base"
+          echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
+          # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
+          # EACCESes. They cannot wedge a checkout, but they do fill the disk.
+          for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
+            docker run --rm --user 0:0 -v "$RUNNER_TEMP":/t alpine sh -c 'rm -rf -- "/t/$1"' sh "$old" >/dev/null 2>&1 || true
+          done
+          # LEGACY: a runner that ran the old default still carries a workspace
+          # test-temp, and a checkout with clean:true dies on it. Reap the holders
+          # first -- rm cannot unlink a live mountpoint even as root (EBUSY), and a
+          # RESTARTING leaked container re-creates the path as root seconds after
+          # any clean. Match on mount SOURCE, not a label: the holders are untracked
+          # by construction, because a killed run labels nothing.
+          tt="$GITHUB_WORKSPACE/test-temp"
+          [ -d "$tt" ] || exit 0
+          stuck=""
+          for c in $(docker ps -aq 2>/dev/null || true); do
+            if docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null | grep -q "^$tt/"; then
+              stuck="$stuck $c"
+            fi
+          done
+          if [ -n "$stuck" ]; then
+            echo "reaping containers holding mounts under $tt:$stuck"
+            docker rm -f $stuck || true
+          fi
+          # The DIRECTORY, not just its contents: an empty but root-owned base
+          # still EACCESes a later mkdtemp. Mounting the PARENT is what lets a root
+          # container unlink the leaf.
+          docker run --rm --user 0:0 -v "$GITHUB_WORKSPACE":/w alpine \
+            sh -c 'rm -rf /w/test-temp' || rm -rf "$tt" || true
+          # Fail HERE if it survived. The checkout fails on it either way, but
+          # reports only an EACCES rmdir with no clue what was holding the path.
+          if [ -e "$tt" ]; then
+            echo "::error::$tt survived the pre-checkout clean"
+            ls -lan "$tt" || true
+            exit 1
+          fi
+
+      - uses: actions/checkout@v5
+        with:
+          clean: true
+      - name: Shared-conventions drift-check (Workstream I)
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            # Belt-and-braces now that the checkout cleans: a persisted
+            # node_modules would defeat a frozen install, which does NOT relink a
+            # dep whose pinned version moved (a dev-kit bump leaves a stale
+            # node_modules/@norskvideo/ctl-dev-kit, so check:drift would run the
+            # OLD checker against the new canonical). Cheap when already gone.
+            find . -name node_modules -type d -prune -exec rm -rf {} + 2>/dev/null || true
+            bun install --frozen-lockfile
+            bun run check:drift
+          '
+
+  quality:
+    runs-on: x64
+    steps:
+      # Runs BEFORE checkout, and does two things: points the harness's temp base
+      # out of the workspace for every later step in this job, and clears whatever
+      # the old repo-local default left behind on this runner. The body carries the
+      # why. It fails the job only when legacy litter survives -- which would take
+      # the checkout down a step later anyway, but report nothing useful.
+      - name: Route test-temp out of the workspace (pre-checkout)
+        run: |
+          set -uo pipefail
+          # These runners are docker-OUTSIDE-of-docker, so a bind-mount source the
+          # HOST daemon has not seen before is created by dockerd, as ROOT, on the
+          # host -- even when the launch passes --container-user (reproduced
+          # 2026-09-04). The harness's default base is repo-local for an OrbStack
+          # inotify constraint that binds macOS dev and nothing here, so every run
+          # seeded the CHECKOUT with root-owned dirs a non-root `git clean -ffdx`
+          # cannot remove. That took commentary's checks AND integration red on
+          # 2026-09-03. Use the sanctioned override, per-run and outside the
+          # checkout -- as 8ff17a8d did in June for one debug workflow, and stopped.
+          base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+          mkdir -p "$base"
+          echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
+          # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
+          # EACCESes. They cannot wedge a checkout, but they do fill the disk.
+          for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
+            docker run --rm --user 0:0 -v "$RUNNER_TEMP":/t alpine sh -c 'rm -rf -- "/t/$1"' sh "$old" >/dev/null 2>&1 || true
+          done
+          # LEGACY: a runner that ran the old default still carries a workspace
+          # test-temp, and a checkout with clean:true dies on it. Reap the holders
+          # first -- rm cannot unlink a live mountpoint even as root (EBUSY), and a
+          # RESTARTING leaked container re-creates the path as root seconds after
+          # any clean. Match on mount SOURCE, not a label: the holders are untracked
+          # by construction, because a killed run labels nothing.
+          tt="$GITHUB_WORKSPACE/test-temp"
+          [ -d "$tt" ] || exit 0
+          stuck=""
+          for c in $(docker ps -aq 2>/dev/null || true); do
+            if docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null | grep -q "^$tt/"; then
+              stuck="$stuck $c"
+            fi
+          done
+          if [ -n "$stuck" ]; then
+            echo "reaping containers holding mounts under $tt:$stuck"
+            docker rm -f $stuck || true
+          fi
+          # The DIRECTORY, not just its contents: an empty but root-owned base
+          # still EACCESes a later mkdtemp. Mounting the PARENT is what lets a root
+          # container unlink the leaf.
+          docker run --rm --user 0:0 -v "$GITHUB_WORKSPACE":/w alpine \
+            sh -c 'rm -rf /w/test-temp' || rm -rf "$tt" || true
+          # Fail HERE if it survived. The checkout fails on it either way, but
+          # reports only an EACCES rmdir with no clue what was holding the path.
+          if [ -e "$tt" ]; then
+            echo "::error::$tt survived the pre-checkout clean"
+            ls -lan "$tt" || true
+            exit 1
+          fi
+
+      - uses: actions/checkout@v5
+        with:
+          clean: true
+      - name: Lint + typecheck + unit tests
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            # Belt-and-braces now that the checkout cleans: a persisted
+            # node_modules would defeat a frozen install, which does NOT relink a
+            # dep whose pinned version moved (a dev-kit bump leaves a stale
+            # node_modules/@norskvideo/ctl-dev-kit, so check:drift would run the
+            # OLD checker against the new canonical). Cheap when already gone.
+            find . -name node_modules -type d -prune -exec rm -rf {} + 2>/dev/null || true
+            bun install --frozen-lockfile
+            bun run lint
+            bun run typecheck
+            bun run test:unit
+            bun run docs:check
+            # The tree must resolve ONE zod 4 (conventions/zod-singleton.ts).
+            # studio guards this in-repo but never shipped the guard; products
+            # are where studio/ctl/moq-watch zod ranges meet, so a split slips
+            # in here and breaks a schema handed across the instance boundary.
+            bun node_modules/@norskvideo/ctl-dev-kit/conventions/zod-singleton.ts
+          '
+
+  # Report this pipeline's result to the aggregated product CI dashboard
+  # (id3as/ci-workflows) instead of posting its own pony — the dashboard renders
+  # the pony/emoji from the dispatched result. !cancelled() so a real pass/fail
+  # reports, but a cancelled/superseded run does NOT — a cancellation dispatched
+  # as failure would false-red the board on every drained or concurrency-
+  # superseded run.
+  notify:
+    needs: [drift, quality]
+    if: ${{ !cancelled() && github.event_name == 'push' }}
+    runs-on: x64
+    steps:
+      # Runs BEFORE checkout, and does two things: points the harness's temp base
+      # out of the workspace for every later step in this job, and clears whatever
+      # the old repo-local default left behind on this runner. The body carries the
+      # why. It fails the job only when legacy litter survives -- which would take
+      # the checkout down a step later anyway, but report nothing useful.
+      - name: Route test-temp out of the workspace (pre-checkout)
+        run: |
+          set -uo pipefail
+          # These runners are docker-OUTSIDE-of-docker, so a bind-mount source the
+          # HOST daemon has not seen before is created by dockerd, as ROOT, on the
+          # host -- even when the launch passes --container-user (reproduced
+          # 2026-09-04). The harness's default base is repo-local for an OrbStack
+          # inotify constraint that binds macOS dev and nothing here, so every run
+          # seeded the CHECKOUT with root-owned dirs a non-root `git clean -ffdx`
+          # cannot remove. That took commentary's checks AND integration red on
+          # 2026-09-03. Use the sanctioned override, per-run and outside the
+          # checkout -- as 8ff17a8d did in June for one debug workflow, and stopped.
+          base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+          mkdir -p "$base"
+          echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
+          # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
+          # EACCESes. They cannot wedge a checkout, but they do fill the disk.
+          for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
+            docker run --rm --user 0:0 -v "$RUNNER_TEMP":/t alpine sh -c 'rm -rf -- "/t/$1"' sh "$old" >/dev/null 2>&1 || true
+          done
+          # LEGACY: a runner that ran the old default still carries a workspace
+          # test-temp, and a checkout with clean:true dies on it. Reap the holders
+          # first -- rm cannot unlink a live mountpoint even as root (EBUSY), and a
+          # RESTARTING leaked container re-creates the path as root seconds after
+          # any clean. Match on mount SOURCE, not a label: the holders are untracked
+          # by construction, because a killed run labels nothing.
+          tt="$GITHUB_WORKSPACE/test-temp"
+          [ -d "$tt" ] || exit 0
+          stuck=""
+          for c in $(docker ps -aq 2>/dev/null || true); do
+            if docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null | grep -q "^$tt/"; then
+              stuck="$stuck $c"
+            fi
+          done
+          if [ -n "$stuck" ]; then
+            echo "reaping containers holding mounts under $tt:$stuck"
+            docker rm -f $stuck || true
+          fi
+          # The DIRECTORY, not just its contents: an empty but root-owned base
+          # still EACCESes a later mkdtemp. Mounting the PARENT is what lets a root
+          # container unlink the leaf.
+          docker run --rm --user 0:0 -v "$GITHUB_WORKSPACE":/w alpine \
+            sh -c 'rm -rf /w/test-temp' || rm -rf "$tt" || true
+          # Fail HERE if it survived. The checkout fails on it either way, but
+          # reports only an EACCES rmdir with no clue what was holding the path.
+          if [ -e "$tt" ]; then
+            echo "::error::$tt survived the pre-checkout clean"
+            ls -lan "$tt" || true
+            exit 1
+          fi
+
+      - uses: actions/checkout@v5
+        with:
+          clean: true
+      - id: meta
+        run: |
+          if [ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" = "true" ]; then
+            echo "state=failure" >> "$GITHUB_OUTPUT"
+          else
+            echo "state=success" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: ./.github/actions/ci-status-dispatch
+        with:
+          token: ${{ secrets.CI_DISPATCH_TOKEN }}
+          product: __PRODUCT__
+          pipeline: checks
+          status: ${{ steps.meta.outputs.state }}

package/conventions/sync-drift.ts

@@ -31,8 +31,10 @@ import {
   GITIGNORE_END,
   PRODUCT_LINE,
   PRODUCT_SENTINEL,
+  type ProductShape,
   PUBLISH_IMAGE_LINE,
   RUNNER_LINE,
+  resolveShape,
   splitAtMarkers,
 } from "./check-drift.ts";
 
@@ -258,13 +260,20 @@ function syncWithDisplay(repoRoot: string, canonical: string, r: SyncReport): vo
   chmodSync(path, 0o755);
 }
 
-export function syncDrift(repoRoot: string, canonical: CanonicalBytes): SyncReport {
+export function syncDrift(repoRoot: string, canonical: CanonicalBytes, shape: ProductShape = "studio"): SyncReport {
   const r: SyncReport = { written: [], skipped: [] };
+  // Shape-selected canonicals: an sdk-app's flake + checks are its own variants
+  // (the gate holds it to those). Everything else is shared across shapes.
+  const checksCanon = shape === "sdk-app" ? canonical.checksSdkApp : canonical.checks;
+  const flakeCanon = shape === "sdk-app" ? canonical.flakeSdkApp : canonical.flake;
+  if (checksCanon === undefined || flakeCanon === undefined) {
+    throw new Error(`syncDrift: shape "${shape}" requires canonical.flakeSdkApp and canonical.checksSdkApp`);
+  }
 
   writeIfChanged(join(repoRoot, "biome.json"), canonical.biome, "biome.json", r.written);
   writeIfChanged(join(repoRoot, "tsconfig.base.json"), canonical.tsconfigBase, "tsconfig.base.json", r.written);
 
-  syncWorkflow(repoRoot, ".github/workflows/checks.yml", canonical.checks, r);
+  syncWorkflow(repoRoot, ".github/workflows/checks.yml", checksCanon, r);
   syncWorkflow(repoRoot, ".github/workflows/upgrade-latest.yml", canonical.upgradeLatest, r);
   syncWorkflow(repoRoot, ".github/workflows/sync-dev-kit.yml", canonical.syncDevKit, r);
   // No per-repo line to preserve, so it is written whole -- and CREATED where
@@ -276,7 +285,9 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes): SyncRepo
     ".github/workflows/sync-ctl-packages.yml",
     r.written,
   );
-  syncBuildImage(repoRoot, canonical.buildImage, r);
+  // build-image.yml is the Studio bundle-image workflow; an sdk-app ships its
+  // own container, so it is not synced for that shape.
+  if (shape === "studio") syncBuildImage(repoRoot, canonical.buildImage, r);
   syncSmoke(repoRoot, canonical.smoke, r);
   syncIntegration(repoRoot, canonical.integration, r);
 
@@ -293,7 +304,7 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes): SyncRepo
     writeIfChanged(join(repoRoot, buildDocsRel), canonical.buildDocs, buildDocsRel, r.written);
   }
 
-  syncFlake(repoRoot, canonical.flake, r);
+  syncFlake(repoRoot, flakeCanon, r);
   syncClaude(repoRoot, canonical.core, r);
   syncGitignore(repoRoot, canonical.gitignoreCore, r);
   syncDprint(repoRoot, canonical.dprint, r);
@@ -325,8 +336,10 @@ if (import.meta.main) {
     smoke: readFileSync(join(dir, "smoke.yml"), "utf8"),
     integration: readFileSync(join(dir, "integration.yml"), "utf8"),
     demoShim: readFileSync(join(dir, "demo.sh"), "utf8"),
+    flakeSdkApp: readFileSync(join(dir, "..", "build", "flake.sdk-app.nix"), "utf8"),
+    checksSdkApp: readFileSync(join(dir, "checks.sdk-app.yml"), "utf8"),
   };
-  const report = syncDrift(repoRoot, canonical);
+  const report = syncDrift(repoRoot, canonical, resolveShape(repoRoot));
   if (report.written.length === 0) {
     console.log("sync-drift: all shared-convention copies already match @norskvideo/ctl-dev-kit.");
   } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.95",
+  "version": "0.1.96",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",