@norskvideo/ctl-test-harness 0.1.19 → 0.1.21

package/compose-advancing.d.ts

@@ -0,0 +1,26 @@
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export declare const DEFAULT_COMPOSE_NODE = "video_compose";
+/** The highest mediaIn across every node of that name; 0 when none. */
+export declare function maxNodeMediaIn(summary: unknown, node: string): number;
+/** One sample: the highest mediaIn of `node` across every root workflow under
+ *  `base` (`.../visualiser`). An unreachable visualiser reads as 0 — the
+ *  caller's second sample, not a throw, decides. */
+export declare function composeFrames(opts: {
+    fetch: FetchLike;
+    base: string;
+    node?: string;
+}): Promise<number>;
+export interface ComposeAdvancingResult {
+    advancing: boolean;
+    before: number;
+    after: number;
+    node: string;
+}
+/** Two samples `settleMs` apart: advancing when the second is above the first
+ *  and above zero — the fallback card and a stalled feed both read flat. */
+export declare function composeAdvancing(opts: {
+    fetch: FetchLike;
+    base: string;
+    node?: string;
+    settleMs?: number;
+}): Promise<ComposeAdvancingResult>;

package/compose-advancing.js

@@ -0,0 +1,61 @@
+// Is a programme really reaching the compositor? The daemon reports a source
+// "running" as soon as its ffmpeg sidecar is up, even if the SRT never
+// connected or the frames stalled; the only honest signal is the compose
+// node's own mediaIn climbing between two samples of the engine's visualiser
+// (`/visualiser/workflow` -> rootWorkflows[].wfid -> `/workflow/<wfid>/summary`
+// -> nodes[].mediaIn). Playout's scripts/ensure-sources.sh:52-64 as TypeScript
+// (05-demo s7 step 2), pure over an injected fetch so it is unit-tested and
+// reachable through whichever base the caller has: the daemon proxy's
+// `/instance/<id>/visualiser`, or `<id>-media-1:6791/visualiser` on norsk-net.
+export const DEFAULT_COMPOSE_NODE = "video_compose";
+const DEFAULT_SETTLE_MS = 6000;
+/** The highest mediaIn across every node of that name; 0 when none. */
+export function maxNodeMediaIn(summary, node) {
+    const nodes = summary?.nodes;
+    if (!Array.isArray(nodes))
+        return 0;
+    let max = 0;
+    for (const n of nodes) {
+        if (n?.name !== node)
+            continue;
+        const v = Number(n.mediaIn);
+        if (Number.isFinite(v) && v > max)
+            max = v;
+    }
+    return max;
+}
+async function getJson(fetch, url) {
+    const r = await fetch(url, { signal: AbortSignal.timeout(5000) });
+    if (!r.ok)
+        throw new Error(`GET ${url} -> ${r.status}`);
+    return r.json();
+}
+/** One sample: the highest mediaIn of `node` across every root workflow under
+ *  `base` (`.../visualiser`). An unreachable visualiser reads as 0 — the
+ *  caller's second sample, not a throw, decides. */
+export async function composeFrames(opts) {
+    const node = opts.node ?? DEFAULT_COMPOSE_NODE;
+    try {
+        const wf = (await getJson(opts.fetch, `${opts.base}/workflow`));
+        let max = 0;
+        for (const root of wf?.rootWorkflows ?? []) {
+            if (typeof root?.wfid !== "string")
+                continue;
+            const summary = await getJson(opts.fetch, `${opts.base}/workflow/${encodeURIComponent(root.wfid)}/summary`);
+            max = Math.max(max, maxNodeMediaIn(summary, node));
+        }
+        return max;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Two samples `settleMs` apart: advancing when the second is above the first
+ *  and above zero — the fallback card and a stalled feed both read flat. */
+export async function composeAdvancing(opts) {
+    const node = opts.node ?? DEFAULT_COMPOSE_NODE;
+    const before = await composeFrames({ fetch: opts.fetch, base: opts.base, node });
+    await new Promise((r) => setTimeout(r, opts.settleMs ?? DEFAULT_SETTLE_MS));
+    const after = await composeFrames({ fetch: opts.fetch, base: opts.base, node });
+    return { advancing: after > before && after > 0, before, after, node };
+}

package/container-logs.d.ts

@@ -0,0 +1,48 @@
+export interface SpawnResult {
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+export type SpawnLike = (cmd: string, args: string[], opts: {
+    encoding: "utf8";
+    timeout: number;
+}) => SpawnResult;
+/** `docker ps` argv listing "<name>\t<state>" for ONE instance's containers. */
+export declare function instanceContainersArgs(instanceId: string): string[];
+/** `docker logs` argv tailing one container. Combined stdout+stderr at the call site. */
+export declare function containerLogArgs(container: string, tail?: number): string[];
+export interface ContainerLog {
+    name: string;
+    state: string;
+    log: string;
+}
+/** Parse `docker ps --format "{{.Names}}\t{{.State}}"` output into rows. */
+export declare function parseContainerRows(psStdout: string): {
+    name: string;
+    state: string;
+}[];
+/** Pure: renders captured logs as an indented block per container. */
+export declare function formatContainerLogs(instanceId: string, entries: ContainerLog[]): string;
+/** Tail every container of one instance. Best-effort: docker unreachable is
+ *  an empty list, never a throw, so a diagnostic cannot mask what it describes. */
+export declare function collectInstanceContainerLogs(instanceId: string, tail?: number, spawn?: SpawnLike): ContainerLog[];
+/** The ready-to-print diagnostic block (empty-marker when nothing is found). */
+export declare function dumpInstanceContainerLogs(instanceId: string, tail?: number, spawn?: SpawnLike): string;
+export interface LogHit {
+    container: string;
+    line: string;
+}
+/** A string forbids a substring; a RegExp is tested per line. */
+export type LogPattern = string | RegExp;
+/** Every line, in any container of the instance, that matches a forbidden
+ *  pattern. `clean` when there are none — including when docker cannot be
+ *  reached, which is absence of evidence, not a failure of the thing probed. */
+export declare function containerLogsClean(opts: {
+    instanceId: string;
+    forbid: readonly LogPattern[];
+    tail?: number;
+    spawn?: SpawnLike;
+}): {
+    clean: boolean;
+    hits: LogHit[];
+};

package/container-logs.js

@@ -0,0 +1,101 @@
+// A launched instance's container logs, by the `norsk-ctl.instance=<id>`
+// label every per-instance container carries (norsk-ctl docker/constants.ts)
+// — so it finds them under either naming scheme (`<id>-media-1` on the
+// released ctl, `norsk-inst-<id>-media` on older ones). Lifted from funke's
+// tests/integration/support/container-logs.ts (05-demo s7 step 2): the
+// diagnostic dump, plus containerLogsClean — iterate.sh's segfault guard
+// generalised to "no forbidden line in any container of this instance".
+// Pure argv/parse/format helpers; only the two exported probes shell out,
+// through an injectable spawn.
+import { spawnSync } from "node:child_process";
+const defaultSpawn = (cmd, args, opts) => {
+    const r = spawnSync(cmd, args, opts);
+    return {
+        stdout: typeof r.stdout === "string" ? r.stdout : "",
+        stderr: typeof r.stderr === "string" ? r.stderr : "",
+        ...(r.error ? { error: r.error } : {}),
+    };
+};
+const DEFAULT_TAIL = 80;
+/** `docker ps` argv listing "<name>\t<state>" for ONE instance's containers. */
+export function instanceContainersArgs(instanceId) {
+    return ["ps", "-a", "--filter", `label=norsk-ctl.instance=${instanceId}`, "--format", "{{.Names}}\t{{.State}}"];
+}
+/** `docker logs` argv tailing one container. Combined stdout+stderr at the call site. */
+export function containerLogArgs(container, tail = DEFAULT_TAIL) {
+    return ["logs", "--tail", String(tail), container];
+}
+/** Parse `docker ps --format "{{.Names}}\t{{.State}}"` output into rows. */
+export function parseContainerRows(psStdout) {
+    return psStdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((l) => {
+        const [name, state] = l.split("\t");
+        return { name: name ?? "?", state: state ?? "?" };
+    });
+}
+/** Pure: renders captured logs as an indented block per container. */
+export function formatContainerLogs(instanceId, entries) {
+    if (entries.length === 0) {
+        return `  container logs for ${instanceId}: <none found / docker unreachable>`;
+    }
+    return entries
+        .map((e) => {
+        const body = e.log.trim() === ""
+            ? "    <empty>"
+            : e.log
+                .trimEnd()
+                .split("\n")
+                .map((l) => `    ${l}`)
+                .join("\n");
+        return `  --- ${e.name} (${e.state}) ---\n${body}`;
+    })
+        .join("\n");
+}
+/** Tail every container of one instance. Best-effort: docker unreachable is
+ *  an empty list, never a throw, so a diagnostic cannot mask what it describes. */
+export function collectInstanceContainerLogs(instanceId, tail = DEFAULT_TAIL, spawn = defaultSpawn) {
+    let rows = [];
+    try {
+        const ps = spawn("docker", instanceContainersArgs(instanceId), { encoding: "utf8", timeout: 15_000 });
+        if (ps.error)
+            return [];
+        rows = parseContainerRows(ps.stdout);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const row of rows) {
+        let log = "";
+        try {
+            const r = spawn("docker", containerLogArgs(row.name, tail), { encoding: "utf8", timeout: 15_000 });
+            log = r.error ? "<docker logs failed>" : `${r.stdout}${r.stderr}`;
+        }
+        catch {
+            log = "<docker logs failed>";
+        }
+        entries.push({ name: row.name, state: row.state, log });
+    }
+    return entries;
+}
+/** The ready-to-print diagnostic block (empty-marker when nothing is found). */
+export function dumpInstanceContainerLogs(instanceId, tail = DEFAULT_TAIL, spawn = defaultSpawn) {
+    return formatContainerLogs(instanceId, collectInstanceContainerLogs(instanceId, tail, spawn));
+}
+const matches = (pattern, line) => typeof pattern === "string" ? line.includes(pattern) : pattern.test(line);
+/** Every line, in any container of the instance, that matches a forbidden
+ *  pattern. `clean` when there are none — including when docker cannot be
+ *  reached, which is absence of evidence, not a failure of the thing probed. */
+export function containerLogsClean(opts) {
+    const hits = [];
+    for (const entry of collectInstanceContainerLogs(opts.instanceId, opts.tail ?? DEFAULT_TAIL, opts.spawn)) {
+        for (const line of entry.log.split("\n")) {
+            if (opts.forbid.some((p) => matches(p, line)))
+                hits.push({ container: entry.name, line });
+        }
+    }
+    return { clean: hits.length === 0, hits };
+}

package/demo/cli.d.ts

@@ -1,9 +1,11 @@
 #!/usr/bin/env bun
 import { type DemoRunOptions, type DemoRunResult, demoPorts } from "./run.js";
-import type { DemoSpec } from "./spec.js";
+import type { DemoDaemonPolicy, DemoMode, DemoSpec } from "./spec.js";
 export interface DemoArgs {
     action: "up" | "check" | "down" | "spec";
-    mode: "dev" | "standalone";
+    /** Absent: the spec's `mode`, else dev. */
+    mode?: DemoMode | "standalone";
+    daemon: DemoDaemonPolicy;
     exportOnly: boolean;
     json: boolean;
     spec: string;
@@ -27,6 +29,8 @@ export interface ResolvedSpecView {
     };
     launch?: DemoSpec["launch"];
     prerequisites?: DemoSpec["prerequisites"];
+    extras: string[];
+    beforeLaunch: boolean;
     sources: Array<{
         name: string;
         asset: NonNullable<DemoSpec["sources"]>[number]["asset"];

package/demo/cli.js

@@ -9,8 +9,9 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 // `ctl-demo`, the bin behind every product's `bun run demo` (05-demo s4):
 //
-//   demo up      [--mode dev]                       launch, print the URLs, hold; Ctrl-C tears down
-//   demo check   [--mode dev]                       the same, then tear down and exit 0/1 (what CI runs)
+//   demo up      [--mode dev|image] [--daemon private|reuse]
+//                                                   launch, print the URLs, hold; Ctrl-C tears down
+//   demo check   [--mode dev|image]                 the same, then tear down and exit 0/1 (what CI runs)
 //   demo check   --mode standalone --export-only    build + export-workdir + every symlink resolves
 //   demo down                                       tear down what `up` recorded, from any shell
 //   demo spec    [--json]                           the resolved spec: ports, template, sources, URLs
@@ -20,15 +21,21 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // under bun only: the spec is TypeScript and so is every product's dev shell.
 import { resolve } from "node:path";
 import { demoDown, demoPorts, demoSlug, runDemo, runExportCheck, } from "./run.js";
-const USAGE = `usage: demo <up|check|down|spec> [--mode dev|standalone] [--export-only] [--json] [--spec <path>]
+const USAGE = `usage: demo <up|check|down|spec> [--mode dev|image|standalone] [--daemon private|reuse] [--export-only] [--json] [--spec <path>]
 
-  up                                  launch on a private daemon, print the URLs, hold (Ctrl-C tears down)
-  check                               up, then tear down and exit 0/1 — what CI runs
+  up                                  launch, print the URLs, hold (Ctrl-C tears down)
+  check                               up, then tear down and exit 0/1 — what CI runs, always on a private daemon
   check --mode standalone --export-only
                                       build the template, export the standalone workdir, assert every symlink resolves
   down                                tear down what \`up\` recorded
   spec [--json]                       print the resolved spec without launching anything
 
+  --mode dev                          run the product from source (bun run dev) and add it by URL
+  --mode image                        add the built product image — the customer path
+  --daemon private                    a throwaway daemon on its own store (default)
+  --daemon reuse                      your listening daemon and real store; the driver deletes the instance,
+                                      removes the template and product, then adds again (stored templates
+                                      are immutable by name)
   --spec <path>                       the demo spec (default tests/demo.spec.ts)`;
 const DEFAULT_SPEC = "tests/demo.spec.ts";
 export function parseDemoArgs(argv) {
@@ -36,7 +43,7 @@ export function parseDemoArgs(argv) {
     if (action !== "up" && action !== "check" && action !== "down" && action !== "spec") {
         throw new Error(action ? `unknown action '${action}'\n${USAGE}` : USAGE);
     }
-    const args = { action, mode: "dev", exportOnly: false, json: false, spec: DEFAULT_SPEC };
+    const args = { action, daemon: "private", exportOnly: false, json: false, spec: DEFAULT_SPEC };
     for (let i = 0; i < rest.length; i++) {
         const flag = rest[i];
         const value = () => {
@@ -48,13 +55,18 @@ export function parseDemoArgs(argv) {
         switch (flag) {
             case "--mode": {
                 const m = value();
-                if (m === "image")
-                    throw new Error("--mode image is not yet implemented (05-demo s7 step 2); use --mode dev");
-                if (m !== "dev" && m !== "standalone")
+                if (m !== "dev" && m !== "image" && m !== "standalone")
                     throw new Error(`unknown mode '${m}'\n${USAGE}`);
                 args.mode = m;
                 break;
             }
+            case "--daemon": {
+                const d = value();
+                if (d !== "private" && d !== "reuse")
+                    throw new Error(`unknown daemon policy '${d}'\n${USAGE}`);
+                args.daemon = d;
+                break;
+            }
             case "--export-only":
                 args.exportOnly = true;
                 break;
@@ -74,6 +86,9 @@ export function parseDemoArgs(argv) {
     if (args.exportOnly && args.mode !== "standalone") {
         throw new Error("--export-only belongs to --mode standalone");
     }
+    if (args.action === "check" && args.daemon === "reuse") {
+        throw new Error("check runs on a private daemon (it is what CI runs); to reload your own daemon use `up --daemon reuse`");
+    }
     return args;
 }
 /** `demo spec --json`: what will run, resolved as far as it can be without a
@@ -109,6 +124,8 @@ export function resolvedSpecView(spec, opts) {
         template,
         ...(spec.launch !== undefined ? { launch: spec.launch } : {}),
         ...(spec.prerequisites !== undefined ? { prerequisites: spec.prerequisites } : {}),
+        extras: (spec.extras ?? []).map((e) => e.name),
+        beforeLaunch: spec.beforeLaunch !== undefined,
         sources: (spec.sources ?? []).map((s) => ({
             name: s.name,
             asset: s.asset ?? { preset: "camera1" },
@@ -158,10 +175,11 @@ export async function demoMain(argv, io) {
         }
         return 1;
     }
+    const mode = args.mode ?? spec.mode ?? "dev";
     try {
         switch (args.action) {
             case "spec": {
-                const view = resolvedSpecView(spec, { mode: args.mode });
+                const view = resolvedSpecView(spec, { mode });
                 io.stdout(args.json ? JSON.stringify(view, null, 2) : renderView(view));
                 return 0;
             }
@@ -174,9 +192,13 @@ export async function demoMain(argv, io) {
                     await io.runExportCheck(spec, { cwd: io.cwd });
                     return 0;
                 }
+                if (mode === "standalone") {
+                    throw new Error("the full standalone tier is not yet implemented (05-demo s7 step 3)");
+                }
                 await io.runDemo(spec, {
                     action: args.action,
-                    mode: "dev",
+                    mode,
+                    daemon: args.daemon,
                     cwd: io.cwd,
                     ...(io.abort ? { abort: io.abort } : {}),
                 });
@@ -195,6 +217,10 @@ function renderView(v) {
         `  daemon :${v.ports.daemonPort}  dev backend :${v.ports.backendPort}  proxy :${v.ports.proxyPort}  studio :${v.ports.studioHostPort}`,
         `  template ${"name" in v.template ? v.template.name : `build ${v.template.build.name}`}`,
     ];
+    if (v.image)
+        lines.push(`  image  ${v.image}`);
+    for (const e of v.extras)
+        lines.push(`  extra  ${e}`);
     for (const s of v.sources)
         lines.push(`  source ${s.name}: ${JSON.stringify(s.asset)} -> ingest ${JSON.stringify(s.ingest)}`);
     for (const g of v.ready)

package/demo/gates.d.ts

@@ -0,0 +1,22 @@
+import { type LogPattern, type SpawnLike } from "../container-logs.js";
+import type { DemoReady } from "./spec.js";
+/** Thrown by a gate whose failure is final: the driver stops polling and the
+ *  run fails with this message, teardown included. */
+export declare class DemoGateFailure extends Error {
+    constructor(message: string);
+}
+/** No forbidden line in any container of the instance (`Segmentation fault`,
+ *  say — funke's iterate.sh:156). Holds on clean logs; a hit fails the run at
+ *  once, naming the container and the line. */
+export declare function logsCleanGate(opts: {
+    forbid: readonly LogPattern[];
+    tail?: number;
+    spawn?: SpawnLike;
+}): DemoReady;
+/** The compositor's mediaIn is climbing (playout's ensure-sources.sh gate),
+ *  read through the daemon proxy's visualiser route for this instance. */
+export declare function composeAdvancingGate(opts?: {
+    node?: string;
+    settleMs?: number;
+    timeoutMs?: number;
+}): DemoReady;

package/demo/gates.js

@@ -0,0 +1,56 @@
+// Ready gates a spec composes rather than writes (05-demo s5): the lifted
+// probes as `{ custom, label }` entries for `ready: [...]`. A gate returns
+// false to be polled again; it throws DemoGateFailure to stop the run at once
+// — a segfault is not going to un-happen by waiting.
+import { composeAdvancing, DEFAULT_COMPOSE_NODE } from "../compose-advancing.js";
+import { containerLogsClean } from "../container-logs.js";
+/** Thrown by a gate whose failure is final: the driver stops polling and the
+ *  run fails with this message, teardown included. */
+export class DemoGateFailure extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DemoGateFailure";
+    }
+}
+/** No forbidden line in any container of the instance (`Segmentation fault`,
+ *  say — funke's iterate.sh:156). Holds on clean logs; a hit fails the run at
+ *  once, naming the container and the line. */
+export function logsCleanGate(opts) {
+    const label = `container logs clean of ${opts.forbid.map(String).join(", ")}`;
+    return {
+        label,
+        custom: async (ctx) => {
+            const r = containerLogsClean({
+                instanceId: ctx.instanceId,
+                forbid: opts.forbid,
+                ...(opts.tail !== undefined ? { tail: opts.tail } : {}),
+                ...(opts.spawn !== undefined ? { spawn: opts.spawn } : {}),
+            });
+            if (r.clean)
+                return true;
+            const lines = r.hits.map((h) => `  ${h.container}: ${h.line}`).join("\n");
+            throw new DemoGateFailure(`forbidden line(s) in the instance's container logs:\n${lines}`);
+        },
+    };
+}
+/** The compositor's mediaIn is climbing (playout's ensure-sources.sh gate),
+ *  read through the daemon proxy's visualiser route for this instance. */
+export function composeAdvancingGate(opts = {}) {
+    const node = opts.node ?? DEFAULT_COMPOSE_NODE;
+    return {
+        label: `${node} advancing`,
+        ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        custom: async (ctx) => {
+            const base = ctx.url({ proxy: "/instance/{id}/visualiser" });
+            const r = await composeAdvancing({
+                fetch: ctx.fetch,
+                base,
+                node,
+                ...(opts.settleMs !== undefined ? { settleMs: opts.settleMs } : {}),
+            });
+            if (!r.advancing)
+                ctx.log(`${node} not advancing yet (${r.before} -> ${r.after})`);
+            return r.advancing;
+        },
+    };
+}

package/demo/index.d.ts

@@ -1,6 +1,7 @@
 export type { DemoArgs, DemoCliIo, ResolvedSpecView } from "./cli.js";
 export { defaultDemoCliIo, demoMain, parseDemoArgs, resolvedSpecView } from "./cli.js";
-export type { CliResult, DemoDeps, DemoPorts, DemoRunOptions, DemoRunResult, DemoState, DemoStateStore, DemoTimeouts, ExportCheckOptions, IngestPortRow, ProcessHandle, TemplateParams, } from "./run.js";
-export { defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runDemo, runExportCheck, } from "./run.js";
-export type { DemoContext, DemoIngest, DemoOpen, DemoReady, DemoSource, DemoSpec, DemoTemplate, DemoUrl, } from "./spec.js";
+export { composeAdvancingGate, DemoGateFailure, logsCleanGate } from "./gates.js";
+export type { CliResult, DemoDeps, DemoPorts, DemoRunOptions, DemoRunResult, DemoState, DemoStateStore, DemoTimeouts, ExportCheckOptions, IngestPortRow, PinMismatch, ProcessHandle, TemplateParams, } from "./run.js";
+export { checkTemplatePins, defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runDemo, runExportCheck, } from "./run.js";
+export type { DemoContext, DemoDaemonPolicy, DemoExtra, DemoIngest, DemoLaunchContext, DemoMode, DemoOpen, DemoReady, DemoSource, DemoSpec, DemoTemplate, DemoUrl, } from "./spec.js";
 export { DemoSpecSchema, defineDemo, formatSpecIssues } from "./spec.js";

package/demo/index.js

@@ -1,3 +1,4 @@
 export { defaultDemoCliIo, demoMain, parseDemoArgs, resolvedSpecView } from "./cli.js";
-export { defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runDemo, runExportCheck, } from "./run.js";
+export { composeAdvancingGate, DemoGateFailure, logsCleanGate } from "./gates.js";
+export { checkTemplatePins, defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runDemo, runExportCheck, } from "./run.js";
 export { DemoSpecSchema, defineDemo, formatSpecIssues } from "./spec.js";

package/demo/run.d.ts

@@ -1,8 +1,9 @@
+import { type ManifestSeed } from "@norskvideo/ctl-sdk/manifest-seed";
 import { ensureRunnerOnNetwork } from "../container-net.js";
 import { type DaemonProcess, type StartDaemonOptions } from "../daemon.js";
 import { type BaseHarnessPorts } from "../harness-config.js";
 import { type SourceHandle, type SrtPumpTarget } from "../source-pump.js";
-import type { DemoIngest, DemoSpec } from "./spec.js";
+import type { DemoDaemonPolicy, DemoIngest, DemoMode, DemoSpec } from "./spec.js";
 export interface CliResult {
     stdout: string;
     stderr: string;
@@ -20,6 +21,10 @@ export interface DemoState {
     daemonPort: number;
     instanceId?: string;
     devPid?: number;
+    /** Absent on records from before the policy existed: private. */
+    daemon?: DemoDaemonPolicy;
+    /** Extra containers `up` started, for `down` to remove. */
+    extras?: string[];
 }
 export interface DemoStateStore {
     read(product: string): DemoState | null;
@@ -29,7 +34,12 @@ export interface DemoStateStore {
 export interface DemoDeps {
     licenseFile(): string;
     storeDir(slug: string): string;
+    /** The developer's real store, for `--daemon reuse`. */
+    realStoreDir(): string;
     writeFile(path: string, contents: string): void;
+    /** File contents, or null when unreadable (compose.yml, manifest.seed.json,
+     *  config.yaml, proxy-secret). */
+    readFile(path: string): string | null;
     fileExists(path: string): boolean;
     startDaemon(storeDir: string, options: StartDaemonOptions): {
         daemon: DaemonProcess;
@@ -42,11 +52,14 @@ export interface DemoDeps {
         cwd: string;
         env: Record<string, string>;
     }): ProcessHandle;
+    /** One `docker <argv>` invocation: extras, and the reuse policy's control-plane container sweep. */
+    docker(argv: string[]): CliResult;
     fetch(url: string, init?: RequestInit): Promise<Response>;
     startSources(opts: {
         daemonPort: number;
         instanceId: string;
         targets: readonly SrtPumpTarget[];
+        proxySecret?: string;
         timeoutMs?: number;
     }): Promise<SourceHandle[]>;
     stopSources(handles: SourceHandle[]): Promise<void>;
@@ -83,8 +96,12 @@ export interface DemoTimeouts {
 }
 export interface DemoRunOptions {
     action: "up" | "check";
-    mode: "dev";
-    /** The product repo root: dev command cwd, relative inputs and links. */
+    mode: DemoMode;
+    /** Default private. */
+    daemon?: DemoDaemonPolicy;
+    /** `reuse`: the daemon's port (default NORSK_CTL_PORT, else 8333). */
+    daemonPort?: number;
+    /** The product repo root: dev command cwd, relative inputs and links, manifest.seed.json. */
     cwd: string;
     /** Default: the product name without its `norsk-` prefix. */
     slug?: string;
@@ -134,6 +151,23 @@ export interface TemplateParams {
  *  no parameter carries it and the instance offers it as the conventional
  *  default, so the demo follows the template when the template moves. */
 export declare function resolveIngestPort(ingest: DemoIngest, rows: IngestPortRow[], t?: TemplateParams): number;
+/** A stored template's `image:` ref that disagrees with the product's seed. */
+export interface PinMismatch {
+    repo: string;
+    stored: string;
+    seed: string;
+}
+/** Image pins are read, never typed (05-demo s4): for every repo the seed's
+ *  `latest` names (studio, media), the stored compose must pin the same ref.
+ *  A repo the compose does not name is not a mismatch — the guard is about a
+ *  stale snapshot, not template completeness. */
+export declare function checkTemplatePins(composeText: string, seed: ManifestSeed): PinMismatch[];
+/** The two config.yaml scalars the proxy URL needs; a regex, not a YAML
+ *  parser, because that is all the driver reads from a store it does not own. */
+export declare function parseProxyConfig(configText: string | null): {
+    scheme: "http" | "https";
+    port: number;
+};
 export declare function findBrokenSymlinks(dir: string): string[];
 /** `<cwd>/test-temp/demo/<product>.json` — beside the store dirs, inside the
  *  consumer's repo, where `down` from another shell can find it. */