@norskvideo/ctl-dev-kit 0.1.51 → 0.1.53

package/conventions/CLAUDE.core.md

@@ -84,7 +84,22 @@
   the doc lives and whether rules sit in one sweep suite
   (`norsk-ctl-product-playout`, `-commentary`) or beside the code they guard
   (`-probe`, `-turnkey-funke-pegasus`) is the repo's choice — the contract is
-  the IDs and the guard, not the layout.
+  the IDs and the guard, not the layout. A **customer-specific** workflow (a
+  reconciled `input.json` under `customers/<slug>/`) carries its **own**
+  `customers/<slug>/INVARIANTS.md`, scoped to that customer, seeded from
+  `testing/INVARIANTS.customer.template.md` and guarded by a parity test whose
+  `testDirs` is scoped to that customer's tests; assert against the composed
+  graph so resolved defaults (segment durations, resolutions, output count) are
+  guarded, not just literal config.
+- **Invariants are a developer-managed contract — never edit them autonomously.**
+  An `INVARIANTS.md` (product or customer) records what a human, or a paying
+  customer, has decided must not regress. Claude / automated agents MUST NOT add,
+  edit, remove, or renumber invariant rows — or weaken the tests that guard them
+  — on their own initiative; those changes come only through deliberate
+  interaction with a developer. If a code change appears to conflict with an
+  invariant, STOP and surface it to a developer rather than "fixing" the
+  invariant to make a test pass. This is precisely what protects against
+  accidental regressions to the things that matter most.
 - **Know who reads it — name the persona before writing docs or a
   persona-facing surface.** Every Norsk ctl product writes for the same four
   reader personas — Evaluator, Builder, Integrator, Operator (SRE) — defined in

package/conventions/check-drift.ts

@@ -2,7 +2,8 @@
 // shared conventions have diverged from this dev-kit's canonical source. Each
 // gated file uses the loosest mechanism that still pins what is shared:
 //   - byte-verbatim: CLAUDE.md fenced core, flake.nix, biome.json,
-//     tsconfig.base.json, the .gitignore core block
+//     tsconfig.base.json, the .gitignore core block, scripts/demo (only a
+//     product with tests/demo.spec.ts is asked for it)
 //   - masked per-repo line: checks.yml + upgrade-latest.yml (`product:` key)
 //   - base + sanctioned extension block: dprint.json (repo-specific excludes)
 //   - structural: root tsconfig.json (shape-dependent includes stay free),
@@ -16,7 +17,7 @@
 // dev-kit forces a re-sync. Canonical bytes ship alongside this script
 // (conventions/* + build/*), resolved package-relative so they work both
 // workspace-symlinked and installed from the published tarball.
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { parseManifestSeed } from "@norskvideo/ctl-sdk/manifest-seed";
 
@@ -245,6 +246,56 @@ export interface CanonicalBytes {
   gitignoreCore: string;
   buildImage: string;
   smoke: string;
+  /** conventions/demo.sh — the scripts/demo shim a product with tests/demo.spec.ts carries. */
+  demoShim: string;
+}
+
+// 05-demo s6: a product that has a demo (tests/demo.spec.ts) exposes it the
+// shared way — scripts/demo, the verbatim executable shim that re-execs under
+// the nix dev shell and delegates to `bun run demo`, and the package.json
+// "demo" script that resolves to the harness's ctl-demo bin. A product without
+// a demo is asked for neither; a shim left behind is still a copy and stays
+// verbatim.
+const DEMO_SPEC = "tests/demo.spec.ts";
+const DEMO_SHIM = "scripts/demo";
+const DEMO_SCRIPT = "ctl-demo";
+
+export function demoProblems(repoRoot: string, canonicalShim: string): string[] {
+  const problems: string[] = [];
+  const hasSpec = existsSync(join(repoRoot, DEMO_SPEC));
+  const shimPath = join(repoRoot, DEMO_SHIM);
+  if (existsSync(shimPath)) {
+    const actual = readFileSync(shimPath, "utf8");
+    if (actual !== canonicalShim) {
+      problems.push(
+        `${DEMO_SHIM} has drifted from @norskvideo/ctl-dev-kit conventions/demo.sh (${firstDiffLine(actual, canonicalShim)}). ${RESYNC}`,
+      );
+    }
+    if ((statSync(shimPath).mode & 0o111) === 0) {
+      problems.push(`${DEMO_SHIM} is not executable (chmod +x) — it is the entry a developer runs.`);
+    }
+  } else if (hasSpec) {
+    problems.push(
+      `${DEMO_SHIM} not found but ${DEMO_SPEC} exists. A product with a demo carries the shim verbatim from @norskvideo/ctl-dev-kit conventions/demo.sh (sync-drift writes it). ${RESYNC}`,
+    );
+  }
+  if (hasSpec) {
+    const pkgPath = join(repoRoot, "package.json");
+    let scripts: Record<string, string> | undefined;
+    try {
+      scripts = existsSync(pkgPath)
+        ? (JSON.parse(readFileSync(pkgPath, "utf8")) as { scripts?: Record<string, string> }).scripts
+        : undefined;
+    } catch (e) {
+      problems.push(`package.json is not parseable JSON (${e instanceof Error ? e.message : String(e)}).`);
+    }
+    if (scripts?.demo !== DEMO_SCRIPT) {
+      problems.push(
+        `package.json must carry "demo": "${DEMO_SCRIPT}" when ${DEMO_SPEC} exists — ${DEMO_SHIM} delegates to \`bun run demo\`.`,
+      );
+    }
+  }
+  return problems;
 }
 
 // A file that must be a verbatim, byte-for-byte copy of its dev-kit canonical.
@@ -435,6 +486,8 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes): DriftRe
     }
   }
 
+  for (const p of demoProblems(repoRoot, canonical.demoShim)) push(p);
+
   return { ok: problems.length === 0, problems };
 }
 
@@ -454,6 +507,7 @@ if (import.meta.main) {
     gitignoreCore: readFileSync(join(import.meta.dir, "gitignore.core"), "utf8"),
     buildImage: readFileSync(join(import.meta.dir, "build-image.yml"), "utf8"),
     smoke: readFileSync(join(import.meta.dir, "smoke.yml"), "utf8"),
+    demoShim: readFileSync(join(import.meta.dir, "demo.sh"), "utf8"),
   };
   const report = checkDrift(repoRoot, canonical);
   if (report.ok) {

package/conventions/demo.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# scripts/demo — this product's demo: tests/demo.spec.ts run by the
+# @norskvideo/ctl-test-harness demo driver (`ctl-demo`).
+#
+#   scripts/demo up                                  from source on a private daemon; Ctrl-C tears down
+#   scripts/demo up --mode image --daemon reuse      the built image into YOUR live daemon
+#   scripts/demo check                               headless; what CI runs
+#   scripts/demo spec | down | ui                    the plan / teardown / a multiplexer layout
+#
+# The driver's private daemon is the released norsk-ctl the repo's flake pins,
+# so this re-execs itself under `nix develop .#dev` when that binary is not on
+# PATH, then delegates to the package's `demo` script (`bun run demo`).
+#
+# Copied verbatim from @norskvideo/ctl-dev-kit conventions/demo.sh and
+# drift-gated: edit the dev-kit source and re-sync, never this copy.
+set -euo pipefail
+
+repo="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repo"
+
+if ! command -v norsk-ctl >/dev/null 2>&1; then
+  if [ -n "${IN_NIX_SHELL:-}" ]; then
+    echo "scripts/demo: norsk-ctl is not on PATH in this nix shell — the .#build shell carries no ctl; use \`nix develop .#dev\`" >&2
+    exit 1
+  fi
+  exec nix develop "$repo#dev" --command "$repo/scripts/demo" "$@"
+fi
+
+exec bun run demo -- "$@"

package/conventions/sync-drift.ts

@@ -18,8 +18,8 @@
 // cannot mechanically converge (e.g. a workflow with no product key to preserve)
 // is left for check-drift to flag, and a convention that genuinely breaks the
 // product surfaces as a red lint/typecheck/test — not as a silent bad copy.
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import {
   BEGIN,
   type CanonicalBytes,
@@ -195,6 +195,19 @@ function syncDprint(repoRoot: string, canonical: string, r: SyncReport): void {
   writeIfChanged(path, out, "dprint.json", r.written);
 }
 
+// scripts/demo (05-demo s6): verbatim + executable for a repo that has a demo
+// (tests/demo.spec.ts) or already carries the shim; a repo without a demo is
+// not given one. The package.json "demo" script is structural and stays the
+// product's to add — the gate names it.
+function syncDemoShim(repoRoot: string, canonical: string, r: SyncReport): void {
+  const rel = "scripts/demo";
+  const path = join(repoRoot, rel);
+  if (!existsSync(join(repoRoot, "tests/demo.spec.ts")) && !existsSync(path)) return;
+  mkdirSync(dirname(path), { recursive: true });
+  writeIfChanged(path, canonical, rel, r.written);
+  chmodSync(path, 0o755);
+}
+
 export function syncDrift(repoRoot: string, canonical: CanonicalBytes): SyncReport {
   const r: SyncReport = { written: [], skipped: [] };
 
@@ -218,6 +231,7 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes): SyncRepo
   syncClaude(repoRoot, canonical.core, r);
   syncGitignore(repoRoot, canonical.gitignoreCore, r);
   syncDprint(repoRoot, canonical.dprint, r);
+  syncDemoShim(repoRoot, canonical.demoShim, r);
 
   return r;
 }
@@ -239,6 +253,7 @@ if (import.meta.main) {
     gitignoreCore: readFileSync(join(dir, "gitignore.core"), "utf8"),
     buildImage: readFileSync(join(dir, "build-image.yml"), "utf8"),
     smoke: readFileSync(join(dir, "smoke.yml"), "utf8"),
+    demoShim: readFileSync(join(dir, "demo.sh"), "utf8"),
   };
   const report = syncDrift(repoRoot, canonical);
   if (report.written.length === 0) {

package/create-product/backend-turnkey.ts

@@ -32,10 +32,18 @@ pinned in \`flake.nix\` and put on PATH by the nix shell:
 \`norsk-ctl product add --dev-url http://localhost:${ctx.devPort}\` registers the
 running backend as a dev product.
 
-**Outer loop (real image):** \`bun run build:image\` builds the container via the
-shared dev-kit bundle driver (\`deployment/build-image.sh\`, tag \`${ctx.name}\`,
-container port 4321), then re-add it into the daemon —
-\`deployment/iterate.sh\` scripts the remove/re-add dance.
+**Demo:** \`bun run demo -- up\` runs \`tests/demo.spec.ts\` (the
+@norskvideo/ctl-test-harness demo driver) from source on a private daemon —
+dev backend, registration, launch, the camera1 sample on the ingest, ready
+gates, URLs; Ctrl-C tears down. \`check\` is the headless form CI runs,
+\`spec\` prints the plan. \`scripts/demo\` is the same entry re-exec'd under
+\`nix develop .#dev\` when the pinned ctl is not on PATH.
+
+**Outer loop (real image):** \`bun run iterate\` — \`bun run build:image\` (the
+shared dev-kit bundle driver via \`deployment/build-image.sh\`, tag \`${ctx.name}\`,
+container port 4321), then \`bun run demo -- up --mode image --daemon reuse\`:
+the driver deletes the instance, removes the template + product, re-adds the
+fresh image and checks the pins before relaunching.
 
 ## First run after generation
 
@@ -61,7 +69,8 @@ The daemon launches instances from a **stored** product-template snapshot
 fetched once at \`product add\`, and refuses to overwrite one by name.
 Rebuilding the image does NOT reach launched instances or new launches until
 you refresh the stored template (\`norsk-ctl template refresh <name>\`, or the
-full delete/remove/re-add dance in \`deployment/iterate.sh\`). Verify the
+delete/remove/re-add dance \`bun run iterate\` drives through the demo
+driver). Verify the
 refreshed \`~/.norsk-ctl/product-templates/<name>/compose.yml\` carries the pins
 \`manifest.seed.json\` declares.
 
@@ -126,10 +135,14 @@ function rootPackageJson(ctx: ShapeContext): string {
         dev: "bun run --cwd backend dev",
         start: "bun run --cwd backend start",
         iterate: "bash deployment/iterate.sh",
+        demo: "ctl-demo",
       },
       devDependencies: {
         "@biomejs/biome": "2.5.5",
         "@norskvideo/ctl-dev-kit": "^0.1.10",
+        // The demo driver (`ctl-demo`, tests/demo.spec.ts) — hoisted here so the
+        // root `demo` script resolves the bin.
+        "@norskvideo/ctl-test-harness": "^0.1.23",
         "@types/bun": "latest",
         "@types/node": "^22.10.0",
         typescript: "^5.7.2",
@@ -1174,7 +1187,7 @@ function testsPackageJson(ctx: ShapeContext): string {
         // directly, and bun links a member's deps into its OWN node_modules —
         // the backend's copy is not reachable from here.
         "@norskvideo/ctl-product-template-schema": "^0.1.0",
-        "@norskvideo/ctl-test-harness": "^0.1.3",
+        "@norskvideo/ctl-test-harness": "^0.1.23",
         "@types/bun": "latest",
         "@types/node": "^22.10.0",
         typescript: "^5.7.2",
@@ -1325,42 +1338,98 @@ describe("${ctx.name} image: container surface", () => {
 
 function iterateSh(ctx: ShapeContext): string {
   return `#!/usr/bin/env bash
-# Iterate loop: rebuild the image and push it through the daemon — the
-# stored-template trap (see CLAUDE.md) means NONE of this happens implicitly.
-# Modeled on funke-pegasus's deployment/iterate.sh (the fleet reference); grow
-# the TODOs into real probes as the product takes shape.
+#
+# Rebuild ${ctx.name} and reload it into the LIVE norsk-ctl daemon:
+#   build image -> \`bun run demo -- up --mode image --daemon reuse\`.
+#
+# The driver (tests/demo.spec.ts via @norskvideo/ctl-test-harness/demo) does
+# the stored-template dance CLAUDE.md describes: deletes the instance, removes
+# the template + product, adds the fresh image again, checks the studio pin
+# against manifest.seed.json, pumps the source, waits for the ready gates,
+# prints the URLs and holds. Ctrl-C (or \`bun run demo -- down\`) removes the
+# instance; your daemon and the registration stay.
+#
+# Needs the daemon already running (\`norsk-ctl serve\`), \`norsk-ctl\` on PATH
+# (\`nix develop .#dev\` provides it) and NORSK_LICENSE_FILE.
+#
+# Usage (from the repo root):
+#   bun run iterate                     # full loop
+#   SKIP_BUILD=1 bun run iterate        # reuse the existing image
+#   IMAGE_TAG=... bun run iterate       # build + register under another tag
 set -euo pipefail
 
-product="${ctx.name}"
-template="default"
-image="\${IMAGE_TAG:-${ctx.name}:dev}"
+here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+repo="$(cd "$here/.." && pwd)"
 
-echo "==> build image \${image}"
-bun run build:image
+# The licence names the product by image ref, so the build lands on that ref
+# directly (build-image.sh honours IMAGE_TAG).
+export IMAGE_TAG="\${IMAGE_TAG:-${ctx.name}:dev}"
 
-# Refresh the stored template in place if the daemon supports it; otherwise
-# fall back to the full remove/re-add dance.
-if norsk-ctl template refresh "\${template}" 2>/dev/null; then
-  echo "==> stored template refreshed"
+if [ -n "\${SKIP_BUILD:-}" ]; then
+  echo "=== build (skipped, SKIP_BUILD set) ==="
 else
-  echo "==> template refresh unavailable — full remove/re-add"
-  # TODO: delete instances first: norsk-ctl instance delete <id> --purge
-  norsk-ctl template remove "\${template}" || true
-  norsk-ctl product remove "\${product}" || true
-  norsk-ctl product add --image "\${image}" \${NORSK_LICENSE_FILE:+--license-file "\${NORSK_LICENSE_FILE}"}
+  echo "=== build image $IMAGE_TAG ==="
+  bun run --cwd "$repo" build:image
 fi
 
-# Verify the refresh landed — never assume (a stale stored template debugs
-# like a code bug).
-echo "==> stored template pins:"
-grep "image:" "\${HOME}/.norsk-ctl/product-templates/\${template}/compose.yml"
+cd "$repo"
+exec bun run demo -- up --mode image --daemon reuse
+`;
+}
 
-# TODO: launch an instance, pump a source, and assert output — funke's
-# iterate.sh pumps SRT and asserts playable HLS; do the equivalent here.
-echo "==> done (launch + probe steps are TODO)"
+function demoSpecTs(ctx: ShapeContext): string {
+  return `// The ${ctx.name} demo (fleet review 05-demo): the manifest's default
+// template with the daemon's camera1 sample pumped into the SRT ingest. Run by
+// the @norskvideo/ctl-test-harness demo driver:
+//
+//   bun run demo -- up                               from source on a private daemon; Ctrl-C tears down
+//   bun run demo -- up --mode image --daemon reuse   the built image into YOUR live daemon (bun run iterate)
+//   bun run demo -- check                            headless, torn down on exit; what CI runs
+//
+// The driver owns the daemon, the ingest port (INGEST_PORT, read back at
+// launch), the pump and the teardown. Grow the ready gates as the product
+// takes shape: the one below only says Studio's runtime API answers.
+import { defineDemo } from "@norskvideo/ctl-test-harness/demo";
+
+export default defineDemo({
+  product: "${ctx.name}",
+  dev: { command: ["bun", "run", "dev"], readyPath: "/healthz" },
+  // The licence names the product by image ref; build-image.sh honours IMAGE_TAG.
+  image: process.env.IMAGE_TAG ?? "${ctx.name}:dev",
+  template: { name: "default" },
+  launch: { hardware: "none" },
+  sources: [{ name: "input", asset: { preset: "camera1" }, ingest: { param: "INGEST_PORT" }, streamId: "input" }],
+  ready: [{ http: { studio: "/live/api/components" }, status: 200, timeoutMs: 120_000 }],
+  open: [
+    { name: "Studio", url: { proxy: "/instance/{id}/studio/" } },
+    { name: "Studio (host port, no auth)", url: { studio: "/" } },
+  ],
+});
 `;
 }
 
+const DEMO_SPEC_TEST_TS = `// The demo spec (tests/demo.spec.ts) is validated by defineDemo at import;
+// this adds, without Docker, the product-side agreement: the template it
+// names is one the manifest publishes and its source dials the parameter the
+// template declares — the class of rot the demo driver exists to stop.
+import { describe, expect, test } from "bun:test";
+import { buildManifest } from "../../shared/src/manifest.ts";
+import demo from "../demo.spec.ts";
+
+describe("tests/demo.spec.ts", () => {
+  test("names a template the manifest publishes as a default", () => {
+    const published = buildManifest().defaultProductTemplates.map((t) => t.name);
+    if (!demo.template || !("name" in demo.template)) throw new Error("the demo launches a published template");
+    expect(published).toContain(demo.template.name);
+  });
+
+  test("its source dials INGEST_PORT, the parameter the srt-listener template declares", () => {
+    const [input] = demo.sources ?? [];
+    expect(input && "param" in input.ingest ? input.ingest.param : "").toBe("INGEST_PORT");
+  });
+});
+`;
+
 const DOCKERIGNORE = `node_modules
 **/node_modules
 dist
@@ -1393,6 +1462,9 @@ export const backendTurnkey: ShapeModule = {
       { path: ".dockerignore", content: DOCKERIGNORE },
       { path: "examples/default/input.json", content: exampleInputJson(ctx) },
       { path: "deployment/iterate.sh", content: iterateSh(ctx), executable: true },
+      { path: "scripts/demo", content: ctx.canon.demoShim, executable: true },
+      { path: "tests/demo.spec.ts", content: demoSpecTs(ctx) },
+      { path: "tests/unit/demo-spec.test.ts", content: DEMO_SPEC_TEST_TS },
       { path: "shared/package.json", content: sharedPackageJson(ctx) },
       { path: "shared/tsconfig.json", content: WORKSPACE_TSCONFIG },
       { path: "shared/src/index.ts", content: SHARED_INDEX_TS },

package/create-product/canon.ts

@@ -26,6 +26,8 @@ export interface Canon {
   buildImage: string;
   gitignoreCore: string;
   invariantsTemplate: string;
+  /** conventions/demo.sh, emitted as scripts/demo. */
+  demoShim: string;
 }
 
 export function loadCanon(): Canon {
@@ -43,6 +45,7 @@ export function loadCanon(): Canon {
     buildImage: readFileSync(join(conventionsDir, "build-image.yml"), "utf8"),
     gitignoreCore: readFileSync(join(conventionsDir, "gitignore.core"), "utf8"),
     invariantsTemplate: readFileSync(join(import.meta.dir, "..", "testing", "INVARIANTS.template.md"), "utf8"),
+    demoShim: readFileSync(join(conventionsDir, "demo.sh"), "utf8"),
   };
 }
 

package/local-dev/README.md

@@ -30,7 +30,12 @@ bump `ctlVersion` + the four platform hashes in `flake.nix` (or run
 
 **Inner loop (fast, no image build)** — run the backend from source and register
 it as a `kind: dev` product, so edits to the backend / workflow / components land
-without building a container:
+without building a container. `bun run demo -- up` does the whole thing on a
+private daemon — `tests/demo.spec.ts` run by the test-harness demo driver: dev
+backend, registration, launch, the sample sources, the ready gates, the URLs;
+Ctrl-C tears down (`spec` prints the plan, `down` tears down from another
+shell). `scripts/demo` is the same entry, re-exec'd under `nix develop .#dev`
+when the pinned ctl is not on PATH. By hand, against your own daemon:
 
 ```sh
 bun install
@@ -40,15 +45,19 @@ norsk-ctl instance launch-template <id> --template <t> --hardware none
 ```
 
 **Outer loop (real container)** — rebuild the product image and reload it into
-the live daemon, with pin + segfault guards. This is `deployment/iterate.sh`:
+the live daemon. This is `bun run iterate` (`deployment/iterate.sh`):
+`build:image`, then `bun run demo -- up --mode image --daemon reuse`, where the
+driver deletes the instance, removes the template + product, re-adds the fresh
+image, checks the pins against `manifest.seed.json` and relaunches:
 
 ```sh
-NORSK_LICENSE_FILE=/path/to/license.json bun run iterate       # needs a running daemon + GPU
-HARDWARE=none NORSK_LICENSE_FILE=... bun run iterate           # no GPU reservation
+NORSK_LICENSE_FILE=/path/to/license.json bun run iterate       # needs a running daemon (+ GPU where the spec says nvidia)
+HARDWARE=none NORSK_LICENSE_FILE=... bun run iterate           # no GPU reservation (funke)
 ```
 
-`test:integration` uses the same daemon path but against the **released** ctl
-(via `NORSK_CTL_BINARY`), exactly as CI does — see `.github/workflows/integration.yml`.
+`bun run demo -- check` is the headless form CI runs after `test:integration`,
+both against the **released** ctl (via `NORSK_CTL_BINARY`), exactly as a
+customer would — see `.github/workflows/integration.yml`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",

package/testing/INVARIANTS.customer.template.md

@@ -0,0 +1,65 @@
+# <customer> workflow invariants
+
+<!-- Template from @norskvideo/ctl-dev-kit testing/INVARIANTS.customer.template.md.
+Copy to customers/<slug>/INVARIANTS.md, replace the example rows with the rules
+THIS customer cares about, and add the parity-guard test below. This is the
+customer-scoped sibling of INVARIANTS.template.md (which is product-scoped): use
+this one for a reconciled per-customer input.json under customers/, and the
+product template for the shipped product's own composed workflow. -->
+
+> **CUSTOMER CONTRACT — developer-managed.** These are the load-bearing rules
+> this customer deems important about their workflow. They change **ONLY**
+> through deliberate interaction with a developer. Claude / automated agents MUST
+> NOT add, edit, remove, or renumber the rows below — or weaken their guarding
+> tests — on their own initiative. If a code change appears to conflict with an
+> invariant, **stop and surface it to a developer** rather than "fixing" the
+> invariant. This is what protects the customer from accidental regressions to
+> the things they care about.
+
+Each rule has a stable ID (`INV-<AREA>-<NNN>`; never renumber, never reuse a
+retired ID) and at least one test that cites the ID verbatim — the parity guard
+fails CI when a row has no citing test or a test cites an unknown ID. Prefer
+asserting against the **composed Studio graph** (compose the customer's
+`input.json` and inspect the emitted workflow), not just the raw config — that
+way resolved defaults (segment durations, as-rendered resolutions, output count)
+are guarded too, not only literal fields. When a code comment carries one of
+these rules, cite the ID there too instead of restating the rule.
+
+| ID               | Invariant                                                                                                     | Guarded by                       |
+| ---------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| INV-PLAYLIST-001 | This customer serves legacy playlists only — every composed CMAF playlist is non-low-latency, never LL-HLS    | `<slug>/<slug>-invariants.test.ts` |
+| INV-SEG-001      | CMAF segment duration is 4s on every rendition (a resolved default — only guardable via the composed graph)   | `<slug>/<slug>-invariants.test.ts` |
+| INV-OUT-001      | Exactly three delivery rungs in a single named CMAF group, one playlist per rung                              | `<slug>/<slug>-invariants.test.ts` |
+| INV-RES-001      | The delivery resolutions are exactly the ladder the customer signed off (e.g. 1280x720 / 640x360 / 320x180)   | `<slug>/<slug>-invariants.test.ts` |
+| INV-MOQ-001      | The low-latency return / monitor rides MoQ, never a WHIP/RTMP fallback                                        | `<slug>/<slug>-invariants.test.ts` |
+
+The rows above are worked examples (drawn from the datum commentary deployment);
+delete them when seeding a new customer.
+
+## Parity guard
+
+Copy into `customers/<slug>/`-adjacent test dir as `<slug>-invariants-parity.test.ts`
+(keep it beside the invariant tests so `testDirs` stays scoped to this customer's
+IDs — other customers and the product's own invariants use their own guards):
+
+```ts
+import { expect, test } from "bun:test";
+import { join } from "node:path";
+import { invariantParityFromDisk } from "@norskvideo/ctl-dev-kit/testing/invariants";
+
+// Adjust the number of "../" hops to reach the repo root from this test's dir.
+const repoRoot = join(import.meta.dir, "..", "..", "..", "..");
+
+test("every <slug> invariant has a citing test and every cited ID is tabled", () => {
+  const report = invariantParityFromDisk({
+    invariantsPath: join(repoRoot, "customers", "<slug>", "INVARIANTS.md"),
+    testDirs: [import.meta.dir],
+  });
+  expect(report.problems).toEqual([]);
+});
+```
+
+A runtime-only invariant the composed graph can't show (e.g. a timing
+guarantee) still gets a table row — declare its ID in the guard's `untestableIds`
+option; the guard rejects unknown entries and flags the marker as stale once a
+test does cite the ID.