@officexapp/vidfarm-devcli 0.21.37 → 0.21.38

package/dist/src/devcli/experiments.js

@@ -0,0 +1,685 @@
+// Experiments — Vidfarm's wrapper over the EXPERIMENTS_DIARY.md ledger format.
+//
+// An ad campaign is an evolution, not a delivery: rounds of videos that vary ONE
+// composition param (structured) or vary everything (creative), posted across
+// however many channels the director holds, then read back against one north-star
+// metric. The method lives at `https://vidfarm.cc/experiment.md`; the ledger lives
+// at the work root as one markdown file, `EXPERIMENTS_DIARY.md`.
+//
+// This module owns ONLY the parts nothing else in the CLI owns:
+//   1. the ledger format (parse / scaffold / append),
+//   2. the arithmetic (capacity → epochs, median, outliers),
+//   3. the method lint (two variables in one round, a winner off one post, …).
+// It deliberately does NOT wrap posting, channels, briefs or constants — those are
+// `vidfarm schedule`, `vidfarm channels`, `vidfarm handoff` and `vidfarm harness`
+// already, and duplicating them would give an agent two ways to do one thing.
+//
+// Backend-free (Node built-ins only) so it ships in the public cloud-only CLI, and
+// LENIENT like storyboard.ts — a half-written diary is still worth reading, so
+// nothing here throws on a malformed file; it reports warnings.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+/** Canonical filename for the ledger at a work root. */
+export const EXPERIMENTS_FILENAME = "EXPERIMENTS_DIARY.md";
+export const EXPERIMENT_MODES = ["creative", "structured"];
+/** The four core metrics, in funnel order. Any of them can be the north star. */
+export const CORE_METRICS = ["views", "comments", "clicks", "buys"];
+export const DEFAULT_METRIC = "comments";
+/** A variant only counts as tested once it has this many posts behind it. One
+ *  post is noise in short form, so nothing is promoted off a single result. */
+export const MIN_POSTS_PER_VARIANT = 2;
+/** Beat the round median by this much to be an outlier worth chasing. */
+export const DEFAULT_OUTLIER_RATIO = 3;
+const ROUND_HEADING_RE = /^##[ \t]+round\b/i;
+const EPOCH_HEADING_RE = /^###[ \t]+epoch\b/i;
+const RESULTS_HEADING_RE = /^###[ \t]+results?\b/i;
+const SETUP_HEADING_RE = /^##[ \t]+setup\b/i;
+const ANY_H2_RE = /^##[ \t]+/;
+const ANY_H3_RE = /^###[ \t]+/;
+// A metadata list item. The key half deliberately accepts anything but a colon,
+// because the template's own keys carry parentheses and slashes — e.g.
+// "- Channels (capacity 4/epoch): a, b, c" and
+// "- North-star metric: comments (secondary: views, clicks)".
+const META_RE = /^\s*[-*]\s+([^:|]{1,60}?)\s*:\s*(.+?)\s*$/;
+const TABLE_ROW_RE = /^\s*\|(.+)\|\s*$/;
+const TABLE_SEP_RE = /^\s*\|[\s:|-]+\|\s*$/;
+const LEADING_INT_RE = /^(\d+)/;
+const TITLE_SEP_RE = /^[\s.:—-]+/;
+const DATE_RE = /(\d{4}-\d{2}-\d{2})/;
+const AGE_RE = /\bage\s*:?\s*([0-9]+\s*(?:h|hr|hrs|hours|d|day|days|w|wk|weeks)\b)/i;
+const SOURCE_RE = /\bsource\s*:?\s*([^,·|]+)/i;
+// A "posted" cell is written by hand as often as by `experiment log --posted`, so
+// accept a tick, a word, or a bare date — and accept them WITH a date appended
+// ("✅ 2026-08-15"), which is what this CLI itself writes.
+const TRUTHY_CELL = /(?:✅|✔|\byes\b|\btrue\b|\bdone\b|\bposted\b|\blive\b|^\s*x\s*$|\d{4}-\d{2}-\d{2})/i;
+function splitList(value) {
+    return value
+        .split(/\s*[;,]\s*/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function cells(line) {
+    const m = TABLE_ROW_RE.exec(line);
+    if (!m)
+        return [];
+    return (m[1] ?? "").split("|").map((c) => c.trim());
+}
+/** "14,200" → 14200 · "—" / "" / "n/a" → undefined. Diaries are hand-pasted, so
+ *  thousands separators and em-dash placeholders are normal, not errors. */
+function parseMetricNumber(raw) {
+    const t = raw.replace(/[,\s_]/g, "");
+    if (!t || /^(?:—|-|–|n\/a|na|\?)$/i.test(t))
+        return undefined;
+    const n = Number.parseFloat(t.replace(/[^0-9.eE+-]/g, ""));
+    return Number.isFinite(n) ? n : undefined;
+}
+function isMode(value) {
+    return EXPERIMENT_MODES.includes(value);
+}
+/**
+ * Parse an `EXPERIMENTS_DIARY.md`. Tolerant by design: unknown keys are kept in
+ * `extra`, malformed tables degrade to zero rows, and anything surprising becomes
+ * a warning. A diary an agent half-wrote by hand must still read back.
+ */
+export function parseDiary(source) {
+    const warnings = [];
+    const lines = source.split(/\r?\n/);
+    const setup = { secondary: [], channels: [], extra: {} };
+    const rounds = [];
+    let inSetup = false;
+    let round = null;
+    let epoch = null;
+    let results = null;
+    let tableHeader = null;
+    const closeTable = () => {
+        tableHeader = null;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        const lineNo = i + 1;
+        if (SETUP_HEADING_RE.test(line)) {
+            inSetup = true;
+            round = null;
+            epoch = null;
+            results = null;
+            closeTable();
+            continue;
+        }
+        if (ROUND_HEADING_RE.test(line)) {
+            inSetup = false;
+            epoch = null;
+            results = null;
+            closeTable();
+            const headingText = line.replace(/^##[ \t]+round\b/i, "").replace(TITLE_SEP_RE, "").trim();
+            round = {
+                index: rounds.length + 1,
+                constants: [],
+                epochs: [],
+                results: [],
+                extra: {},
+                line: lineNo,
+                endLine: lineNo
+            };
+            const intMatch = LEADING_INT_RE.exec(headingText);
+            if (intMatch) {
+                round.number = Number.parseInt(intMatch[1] ?? "", 10);
+                const rest = headingText.slice((intMatch[0] ?? "").length).replace(TITLE_SEP_RE, "").trim();
+                if (rest)
+                    round.title = rest;
+            }
+            else if (headingText) {
+                round.title = headingText;
+            }
+            rounds.push(round);
+            continue;
+        }
+        // Any other H2 closes the current round.
+        if (ANY_H2_RE.test(line)) {
+            inSetup = false;
+            round = null;
+            epoch = null;
+            results = null;
+            closeTable();
+            continue;
+        }
+        if (round && EPOCH_HEADING_RE.test(line)) {
+            results = null;
+            closeTable();
+            const text = line.replace(/^###[ \t]+epoch\b/i, "").replace(TITLE_SEP_RE, "").trim();
+            epoch = { label: text || undefined, date: DATE_RE.exec(text)?.[1], rows: [], line: lineNo, endLine: lineNo };
+            round.epochs.push(epoch);
+            round.endLine = lineNo;
+            continue;
+        }
+        if (round && RESULTS_HEADING_RE.test(line)) {
+            epoch = null;
+            closeTable();
+            const text = line.replace(/^###[ \t]+results?\b/i, "").replace(TITLE_SEP_RE, "").trim();
+            results = {
+                readDate: DATE_RE.exec(text)?.[1],
+                source: SOURCE_RE.exec(text)?.[1]?.trim(),
+                age: AGE_RE.exec(text)?.[1]?.replace(/\s+/g, ""),
+                rows: [],
+                line: lineNo,
+                endLine: lineNo
+            };
+            round.results.push(results);
+            round.endLine = lineNo;
+            continue;
+        }
+        if (round && ANY_H3_RE.test(line)) {
+            epoch = null;
+            results = null;
+            closeTable();
+            round.endLine = lineNo;
+            continue;
+        }
+        // ---- table rows ---------------------------------------------------------
+        if ((epoch || results) && TABLE_ROW_RE.test(line)) {
+            if (TABLE_SEP_RE.test(line))
+                continue;
+            const row = cells(line);
+            if (!tableHeader) {
+                tableHeader = row.map((c) => c.toLowerCase());
+                if (epoch)
+                    epoch.endLine = lineNo;
+                if (results)
+                    results.endLine = lineNo;
+                if (round)
+                    round.endLine = lineNo;
+                continue;
+            }
+            const get = (...names) => {
+                for (const name of names) {
+                    const idx = tableHeader?.indexOf(name) ?? -1;
+                    if (idx >= 0 && row[idx] !== undefined)
+                        return row[idx];
+                }
+                return undefined;
+            };
+            if (epoch) {
+                const postedCell = (get("posted", "live", "status") ?? "").trim();
+                epoch.rows.push({
+                    slot: get("slot"),
+                    video: get("video", "id", "clip"),
+                    variant: get("variant", "angle", "format", "hook", "testing"),
+                    channel: get("channel", "account", "destination"),
+                    posted: TRUTHY_CELL.test(postedCell),
+                    postedNote: postedCell || undefined,
+                    line: lineNo
+                });
+                epoch.endLine = lineNo;
+            }
+            else if (results) {
+                const video = (get("video", "id", "clip") ?? "").trim();
+                const metrics = {};
+                tableHeader.forEach((name, idx) => {
+                    if (!name || name === "video" || name === "id" || name === "clip" || name === "note" || name === "notes")
+                        return;
+                    const value = parseMetricNumber(row[idx] ?? "");
+                    if (value !== undefined)
+                        metrics[name] = value;
+                });
+                if (video) {
+                    results.rows.push({ video, metrics, note: get("note", "notes"), line: lineNo });
+                }
+                else {
+                    warnings.push({ message: "Result row with no video id — skipped.", line: lineNo });
+                }
+                results.endLine = lineNo;
+            }
+            if (round)
+                round.endLine = lineNo;
+            continue;
+        }
+        if (tableHeader && line.trim() === "")
+            closeTable();
+        // ---- metadata list items ------------------------------------------------
+        const meta = META_RE.exec(line);
+        if (meta) {
+            // "Channels (capacity 4/epoch)" → "channels"; "**Win condition**" → "win_condition".
+            const key = (meta[1] ?? "")
+                .toLowerCase()
+                .replace(/\([^)]*\)/g, "")
+                .replace(/\*/g, "")
+                .trim()
+                .replace(/[\s-]+/g, "_");
+            const value = (meta[2] ?? "").replace(/\*\*/g, "").trim();
+            if (inSetup) {
+                if (key.startsWith("north") || key === "metric" || key === "kpi") {
+                    // "comments (secondary: views, clicks)"
+                    const secondary = /\(secondary:\s*([^)]+)\)/i.exec(value);
+                    if (secondary)
+                        setup.secondary = splitList(secondary[1] ?? "");
+                    setup.metric = value.replace(/\(secondary:[^)]*\)/i, "").trim().toLowerCase();
+                }
+                else if (key === "channels" || key.startsWith("channels")) {
+                    const inner = /\(([^)]*)\)/.exec(value);
+                    setup.channels = splitList(value.replace(/\([^)]*\)/g, ""));
+                    if (inner && setup.channels.length === 0)
+                        setup.channels = splitList(inner[1] ?? "");
+                }
+                else if (key === "mode") {
+                    const normalized = value.toLowerCase();
+                    if (isMode(normalized))
+                        setup.mode = normalized;
+                    else {
+                        setup.extra.mode = value;
+                        warnings.push({ message: `Unknown mode "${value}" — expected creative or structured.`, line: lineNo });
+                    }
+                }
+                else if (key === "product")
+                    setup.product = value;
+                else if (key.startsWith("baseline"))
+                    setup.baseline = value;
+                else if (key === "editors" || key === "edited_by")
+                    setup.editors = value;
+                else if (key.startsWith("analytics") || key === "source")
+                    setup.source = value;
+                else
+                    setup.extra[key] = value;
+                continue;
+            }
+            if (round) {
+                round.endLine = lineNo;
+                if (key === "mode") {
+                    const normalized = value.toLowerCase().split(/[\s·|]/)[0] ?? "";
+                    if (isMode(normalized))
+                        round.mode = normalized;
+                    // A single "- Mode: structured · Variable: angle · Constants: …" line is
+                    // the compact form the doc's template uses. Split it out.
+                    const compact = value.split(/\s*[·|]\s*/).slice(1);
+                    for (const part of compact) {
+                        const colon = part.indexOf(":");
+                        if (colon === -1)
+                            continue;
+                        const k = part.slice(0, colon).trim().toLowerCase();
+                        const v = part.slice(colon + 1).trim();
+                        if (k === "variable")
+                            round.variable = v;
+                        else if (k === "constants")
+                            round.constants = splitList(v);
+                        else
+                            round.extra[k] = v;
+                    }
+                }
+                else if (key === "variable")
+                    round.variable = value;
+                else if (key === "constants")
+                    round.constants = splitList(value);
+                else if (key.startsWith("justification") || key === "why")
+                    round.justification = value;
+                else if (key.startsWith("win"))
+                    round.win = value;
+                else if (key === "videos") {
+                    const n = parseMetricNumber(value.split(/[^\d,]/)[0] ?? value);
+                    if (n !== undefined)
+                        round.videos = n;
+                    else
+                        round.extra.videos = value;
+                }
+                else if (key === "editors" || key === "edited_by")
+                    round.editors = value;
+                else if (key === "finding" || key === "findings")
+                    round.finding = value;
+                else if (key === "next")
+                    round.next = value;
+                else
+                    round.extra[key] = value;
+                continue;
+            }
+        }
+        // Bold prose lines the template uses for conclusions: "**Finding:** …".
+        if (round) {
+            const bold = /^\s*\*\*(finding|next)s?:?\*\*\s*(.+?)\s*$/i.exec(line);
+            if (bold) {
+                const key = (bold[1] ?? "").toLowerCase();
+                if (key === "finding")
+                    round.finding = (bold[2] ?? "").trim();
+                else
+                    round.next = (bold[2] ?? "").trim();
+                round.endLine = lineNo;
+            }
+        }
+    }
+    return { setup, rounds, warnings };
+}
+/** Read + parse a work root's diary. Missing file is NOT an error — it returns
+ *  `exists:false` so a caller can say "no campaign yet" and offer `--init`. */
+export function readDiary(dir) {
+    const absPath = path.join(dir, EXPERIMENTS_FILENAME);
+    if (!existsSync(absPath)) {
+        return {
+            exists: false,
+            path: EXPERIMENTS_FILENAME,
+            absPath,
+            manifest: { setup: { secondary: [], channels: [], extra: {} }, rounds: [], warnings: [] }
+        };
+    }
+    return { exists: true, path: EXPERIMENTS_FILENAME, absPath, manifest: parseDiary(readFileSync(absPath, "utf8")) };
+}
+// ── Arithmetic ───────────────────────────────────────────────────────────────
+// The part a weaker model gets quietly wrong: capacity, epochs, medians, and
+// which number actually beat the pack.
+/** Videos per epoch = channels held. One channel carries about one test post a
+ *  day before it reads as spam. */
+export function capacityOf(setup) {
+    return setup.channels.length;
+}
+export function epochsNeeded(videos, capacity) {
+    if (!Number.isFinite(videos) || videos <= 0)
+        return 0;
+    if (!Number.isFinite(capacity) || capacity <= 0)
+        return Number.POSITIVE_INFINITY;
+    return Math.ceil(videos / capacity);
+}
+export function median(values) {
+    const sorted = values.filter((v) => Number.isFinite(v)).sort((a, b) => a - b);
+    if (sorted.length === 0)
+        return undefined;
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[mid] : ((sorted[mid - 1] + sorted[mid]) / 2);
+}
+export function analyzeRound(round, setup, opts) {
+    const metric = (opts?.metric ?? setup.metric ?? DEFAULT_METRIC).toLowerCase();
+    const outlierRatio = opts?.outlierRatio ?? DEFAULT_OUTLIER_RATIO;
+    const capacity = capacityOf(setup);
+    const slotRows = round.epochs.flatMap((e) => e.rows);
+    const variantOf = new Map();
+    const postsOf = new Map();
+    for (const row of slotRows) {
+        if (!row.video)
+            continue;
+        if (row.variant)
+            variantOf.set(row.video, row.variant);
+        if (row.posted)
+            postsOf.set(row.video, (postsOf.get(row.video) ?? 0) + 1);
+    }
+    const resultRows = round.results.flatMap((block) => block.rows.map((row) => ({ row, block })));
+    const scored = [];
+    for (const { row, block } of resultRows) {
+        const value = row.metrics[metric];
+        if (value === undefined)
+            continue;
+        scored.push({
+            video: row.video,
+            value,
+            variant: variantOf.get(row.video),
+            posts: postsOf.get(row.video) ?? 0,
+            age: block.age,
+            source: block.source
+        });
+    }
+    const med = median(scored.map((s) => s.value));
+    for (const s of scored)
+        s.ratio = med && med > 0 ? s.value / med : undefined;
+    const ranked = [...scored].sort((a, b) => b.value - a.value);
+    const reported = new Set(resultRows.map(({ row }) => row.video));
+    return {
+        round,
+        metric,
+        capacity,
+        videosPlanned: round.videos,
+        epochsNeeded: round.videos !== undefined ? epochsNeeded(round.videos, capacity) : undefined,
+        epochsRun: round.epochs.length,
+        postedCount: slotRows.filter((r) => r.posted).length,
+        // Every planned slot still dark, across all epochs — not just the newest one.
+        unposted: slotRows.filter((r) => !r.posted && r.video).map((r) => r.video),
+        awaiting: slotRows.filter((r) => r.posted && r.video && !reported.has(r.video)).map((r) => r.video),
+        scored: ranked,
+        median: med,
+        outliers: med && med > 0 ? ranked.filter((s) => (s.ratio ?? 0) >= outlierRatio) : [],
+        weakest: ranked[ranked.length - 1],
+        readContexts: Array.from(new Set(round.results.map((b) => `${b.source ?? "?"}@${b.age ?? "?"}`)))
+    };
+}
+export function lintDiary(manifest, analyses) {
+    const findings = [];
+    const { setup, rounds } = manifest;
+    const capacity = capacityOf(setup);
+    if (!setup.metric) {
+        findings.push({
+            level: "warn",
+            code: "no-north-star",
+            message: "No north-star metric in Setup — every round is then judged by vibes.",
+            fix: `Add "- North-star metric: ${DEFAULT_METRIC}" (comments is the richest early-stage intel).`
+        });
+    }
+    if (capacity === 0) {
+        findings.push({
+            level: "warn",
+            code: "no-channels",
+            message: "No channels in Setup, so testing capacity is unknown and no round can be sized.",
+            fix: "Run `vidfarm channels` and list them: \"- Channels (capacity N/epoch): a, b, c\"."
+        });
+    }
+    const buysTotal = analyses
+        .filter((a) => a.metric === "buys")
+        .flatMap((a) => a.scored.map((s) => s.value))
+        .reduce((sum, v) => sum + v, 0);
+    if ((setup.metric ?? "").includes("buy") && buysTotal < 10) {
+        findings.push({
+            level: "warn",
+            code: "end-of-funnel-north-star",
+            message: `North star is buys, but only ${buysTotal} recorded so far — at this volume every round is statistically indistinguishable from noise.`,
+            fix: "Optimize views/comments/clicks until traffic is real, then switch to buys. If the director heard this and still wants buys, keep going and note it here."
+        });
+    }
+    for (const analysis of analyses) {
+        const round = analysis.round;
+        const at = { round: round.number ?? round.index, line: round.line };
+        const mode = round.mode ?? setup.mode;
+        if (mode === "structured") {
+            const variables = round.variable ? splitList(round.variable.replace(/\s+and\s+/gi, ",")).filter((v) => v.length > 0) : [];
+            if (variables.length > 1) {
+                findings.push({
+                    ...at,
+                    level: "error",
+                    code: "two-variables",
+                    message: `Round ${at.round} is structured but varies ${variables.length} params (${variables.join(", ")}) — the result is unreadable.`,
+                    fix: "Split it into parallel rounds on separate channel slots, one variable each."
+                });
+            }
+            if (!round.variable) {
+                findings.push({ ...at, level: "error", code: "no-variable", message: `Round ${at.round} is structured but names no variable.`, fix: "Add \"- Variable: <param>\"." });
+            }
+            if (round.constants.length === 0) {
+                findings.push({
+                    ...at,
+                    level: "warn",
+                    code: "no-constants",
+                    message: `Round ${at.round} is structured but pins no constants, so nothing is actually held.`,
+                    fix: "Write them down and enforce them: `vidfarm harness init short-form --out ./work/HARNESS.md`, then `vidfarm qa ./work --harness ./work/HARNESS.md`."
+                });
+            }
+            const editors = round.editors ?? setup.editors ?? "";
+            if (/gig|crowd|task ?force|worker/i.test(editors)) {
+                findings.push({
+                    ...at,
+                    level: "error",
+                    code: "structured-with-gigworkers",
+                    message: `Round ${at.round} is structured but is edited by a distributed task force — between-editor variance swamps the effect being measured.`,
+                    fix: "Run structured rounds with your own agent, or ship every worker the identical base fork and let them change only the one variable. Creative Mode is what gigworkers are for."
+                });
+            }
+        }
+        if (!round.win && analysis.scored.length === 0) {
+            findings.push({ ...at, level: "warn", code: "no-win-condition", message: `Round ${at.round} declares no win condition, and results are not in yet.`, fix: "Decide the number BEFORE posting: \"- Win condition: any variant at >=3x median comments\"." });
+        }
+        if (analysis.readContexts.length > 1) {
+            findings.push({
+                ...at,
+                level: "error",
+                code: "mixed-read-ages",
+                message: `Round ${at.round} mixes results read at different times/sources (${analysis.readContexts.join(", ")}) — a 24h number is not comparable to a 7d one.`,
+                fix: "Re-read the whole round at one age, or compare only within a single results block."
+            });
+        }
+        for (const outlier of analysis.outliers) {
+            if (outlier.posts < MIN_POSTS_PER_VARIANT) {
+                findings.push({
+                    ...at,
+                    level: "warn",
+                    code: "single-post-winner",
+                    message: `${outlier.video} looks like an outlier (${outlier.ratio?.toFixed(1)}x median ${analysis.metric}) off ${outlier.posts || "?"} post(s).`,
+                    fix: `Post it again before you promote it — ${MIN_POSTS_PER_VARIANT} minimum, 3 is better.`
+                });
+            }
+        }
+        if (capacity > 0 && analysis.epochsRun > 0) {
+            const latest = round.epochs[round.epochs.length - 1];
+            const used = latest?.rows.length ?? 0;
+            if (used > 0 && used < capacity) {
+                findings.push({
+                    ...at,
+                    level: "info",
+                    code: "unspent-capacity",
+                    message: `Latest epoch of round ${at.round} uses ${used} of ${capacity} slots — ${capacity - used} free.`,
+                    fix: "Fill them: more samples of this variable, a parallel round on another param (formats or hooks are the usual next), or a one-off theory logged as a one-off."
+                });
+            }
+        }
+        if (analysis.awaiting.length > 0) {
+            findings.push({ ...at, level: "info", code: "awaiting-results", message: `Round ${at.round}: ${analysis.awaiting.length} posted video(s) have no results logged (${analysis.awaiting.join(", ")}).`, fix: "Log them: `vidfarm experiment log <video> --views N --comments N --source <where> --age 48h`." });
+        }
+    }
+    if (rounds.length > 1) {
+        const structured = rounds.filter((r) => (r.mode ?? setup.mode) === "structured").length;
+        if (structured === rounds.length && !rounds.some((r) => r.finding)) {
+            findings.push({ level: "info", code: "all-structured-no-findings", message: "Every round is structured and none records a finding — structured rounds only pay off when you write down what they proved.", fix: "Add \"**Finding:** …\" to each finished round." });
+        }
+    }
+    return findings;
+}
+export function renderDiaryScaffold(input) {
+    const channels = input.channels ?? [];
+    const metric = input.metric ?? DEFAULT_METRIC;
+    const secondary = input.secondary?.length ? input.secondary : CORE_METRICS.filter((m) => m !== metric).slice(0, 2);
+    return [
+        `# Experiments Diary — ${input.product ?? "<product>"}`,
+        "",
+        `Method: https://vidfarm.cc/experiment.md · started ${input.date ?? ""}`.trim(),
+        "",
+        "## Setup",
+        `- North-star metric: ${metric} (secondary: ${secondary.join(", ")})`,
+        `- Channels (capacity ${channels.length || "?"}/epoch): ${channels.length ? channels.join(", ") : "<run `vidfarm channels` and list them>"}`,
+        `- Mode: ${input.mode ?? "creative"}`,
+        `- Editors: ${input.editors ?? "agent"}`,
+        `- Baseline checkpoint: ${input.baseline ?? "kinetic captions over b-roll, no VO, ~20s"}`,
+        `- Analytics source: ${input.source ?? "<flockposter | manual | email-channel | gigworkers>"}`,
+        "",
+        "Append only. Never rewrite history here — correct it with a later entry.",
+        ""
+    ].join("\n");
+}
+export function renderRoundScaffold(input) {
+    const videos = input.videos ?? input.slots?.length ?? 0;
+    const epochs = epochsNeeded(videos, input.capacity);
+    const slots = input.slots?.length
+        ? input.slots
+        : Array.from({ length: videos }, (_, i) => `v${String(i + 1).padStart(3, "0")}`);
+    const channels = input.channels ?? [];
+    const perEpoch = input.capacity > 0 ? input.capacity : slots.length;
+    const epochBlocks = [];
+    for (let e = 0; e < Math.max(1, Number.isFinite(epochs) ? epochs : 1); e++) {
+        const slice = slots.slice(e * perEpoch, (e + 1) * perEpoch);
+        if (slice.length === 0)
+            break;
+        epochBlocks.push([
+            `### Epoch ${e + 1} — ${e === 0 ? (input.date ?? "<date>") : "<date>"}`,
+            "",
+            "| slot | video | variant | channel | posted |",
+            "|---|---|---|---|---|",
+            ...slice.map((raw, i) => {
+                const [video, variant] = raw.split("|").map((s) => s.trim());
+                return `| ${i + 1} | ${video ?? ""} | ${variant ?? ""} | ${channels[i % Math.max(1, channels.length)] ?? ""} | |`;
+            }),
+            ""
+        ].join("\n"));
+    }
+    return [
+        `## Round ${input.number}${input.title ? ` — ${input.title}` : input.variable ? ` — ${input.variable}` : ""}`,
+        `- Mode: ${input.mode ?? "creative"}`,
+        ...(input.variable ? [`- Variable: ${input.variable}`] : []),
+        `- Constants: ${input.constants?.length ? input.constants.join(", ") : "—"}`,
+        `- Videos: ${videos} · Capacity ${input.capacity || "?"}/epoch → ${Number.isFinite(epochs) ? epochs : "?"} epoch(s)`,
+        `- Editors: ${input.editors ?? "agent"}`,
+        `- Justification: ${input.justification ?? "<why this variable is worth the capacity before the others>"}`,
+        `- Win condition: ${input.win ?? `any variant at >=${DEFAULT_OUTLIER_RATIO}x median`}`,
+        "",
+        ...epochBlocks,
+        ""
+    ].join("\n");
+}
+/** Splice text into a file's line array at `afterLine` (1-indexed; 0 = top). */
+function spliceLines(source, afterLine, block) {
+    const lines = source.split(/\r?\n/);
+    const at = Math.max(0, Math.min(lines.length, afterLine));
+    const insert = block.replace(/\s+$/, "").split("\n");
+    lines.splice(at, 0, ...insert, "");
+    return lines.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+/** Append a round block at the end of the diary. */
+export function appendRound(source, input) {
+    const body = source.replace(/\s+$/, "");
+    return `${body}\n\n${renderRoundScaffold(input).replace(/\s+$/, "")}\n`;
+}
+/** Append a result row to a round, reusing an existing results block when its
+ *  (date, source, age) match — because rows read at different ages must never
+ *  land in the same table. Returns the new file text. */
+export function appendResult(source, manifest, roundIndex, input) {
+    const round = manifest.rounds[roundIndex];
+    if (!round)
+        throw new Error("No such round in the diary.");
+    const columns = Object.keys(input.metrics);
+    const match = round.results.find((b) => b.readDate === input.date && (b.source ?? "") === (input.source ?? "") && (b.age ?? "") === (input.age ?? ""));
+    if (match && match.rows.length > 0) {
+        // Reuse the block's own column order so the table stays aligned.
+        const header = manifest.rounds[roundIndex]?.results.find((b) => b === match);
+        const known = header ? Object.keys(match.rows[0]?.metrics ?? {}) : columns;
+        const ordered = known.length ? known : columns;
+        const row = `| ${input.video} | ${ordered.map((c) => (input.metrics[c] !== undefined ? String(input.metrics[c]) : "")).join(" | ")} | ${input.note ?? ""} |`;
+        return { text: spliceLines(source, match.endLine, row), block: "existing" };
+    }
+    const ordered = columns.length ? columns : [...CORE_METRICS];
+    const block = [
+        `### Results — read ${input.date}${input.source ? `, source: ${input.source}` : ""}${input.age ? `, age: ${input.age}` : ""}`,
+        "",
+        `| video | ${ordered.join(" | ")} | note |`,
+        `|---|${ordered.map(() => "---|").join("")}---|`,
+        `| ${input.video} | ${ordered.map((c) => (input.metrics[c] !== undefined ? String(input.metrics[c]) : "")).join(" | ")} | ${input.note ?? ""} |`
+    ].join("\n");
+    return { text: spliceLines(source, round.endLine, `\n${block}`), block: "new" };
+}
+/** Mark a planned slot as posted. This records what already happened — the
+ *  posting itself is `vidfarm approve` + `vidfarm schedule`. */
+export function markPosted(source, manifest, video, opts) {
+    for (const round of manifest.rounds) {
+        for (const epoch of round.epochs) {
+            const row = epoch.rows.find((r) => r.video === video);
+            if (!row)
+                continue;
+            const lines = source.split(/\r?\n/);
+            const raw = lines[row.line - 1] ?? "";
+            const parts = cells(raw);
+            if (parts.length >= 5) {
+                if (opts.channel)
+                    parts[3] = opts.channel;
+                parts[4] = `✅ ${opts.date}`;
+                lines[row.line - 1] = `| ${parts.join(" | ")} |`;
+                return { text: lines.join("\n"), line: row.line };
+            }
+        }
+    }
+    throw new Error(`No planned slot for "${video}" in the diary. Add the round first: vidfarm experiment round …`);
+}
+export function findRoundIndex(manifest, wanted) {
+    if (wanted === undefined)
+        return manifest.rounds.length - 1;
+    const idx = manifest.rounds.findIndex((r) => (r.number ?? r.index) === wanted);
+    return idx;
+}
+export function writeDiary(absPath, text) {
+    writeFileSync(absPath, text.endsWith("\n") ? text : `${text}\n`, "utf8");
+}
+//# sourceMappingURL=experiments.js.map