@officexapp/vidfarm-devcli 0.21.37 → 0.21.39

package/dist/src/devcli/experiments.js

@@ -0,0 +1,906 @@
+// 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/experiments.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";
+/** The starting format menu, offered during planning — NOT discovered at build
+ *  time. Deliberately copywriting-led: in every one of these the words carry the
+ *  persuasion and the footage only has to hold attention, which is what makes
+ *  them fast, cheap and repeatable. All seven are sourceable for ~$0 from
+ *  `vidfarm public-raws --categories`. */
+export const EASY_FORMATS = [
+    { key: "b-roll", label: "kinetic captions over b-roll footage", note: "the workhorse — start here" },
+    { key: "talking-head", label: "talking head", note: "only if the user will film themselves; strongest trust signal" },
+    { key: "process", label: "process footage", note: "high watch-through, needs no narration" },
+    { key: "loop-background", label: "loop background footage", note: "cheapest of all; the copy is the entire video" },
+    { key: "satisfying", label: "satisfying footage", note: "strong retention, weak topical fit" },
+    { key: "lifestyle", label: "lifestyle footage", note: "best for identity and status angles" },
+    { key: "pov-quote", label: "POV quote aesthetic", note: "pure copywriting; a natural fit for hook tests" }
+];
+/** What to take when the director has no opinion — never stall on this choice. */
+export const DEFAULT_FORMAT = EASY_FORMATS[0].label;
+/** 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;
+}
+/** Posting frequency written next to a channel. Accepts the shapes a director
+ *  actually types: "tiktok_a x2", "tiktok_a ×2", "yt_a 1/day", "li_a 3/week",
+ *  "fb_a 2/month", and a bare "ig_a" (= once per epoch). "paused" or a 0 rate
+ *  contributes no capacity but stays listed. */
+const CHANNEL_RATE_RE = /^(.*?)[\s(]*(?:[x×]\s*(\d+(?:\.\d+)?)|(\d+(?:\.\d+)?)\s*\/\s*(day|epoch|wk|week|mo|month)|(paused|off))\)?\s*$/i;
+export function parseChannelPlan(entry) {
+    const raw = entry.trim();
+    const m = CHANNEL_RATE_RE.exec(raw);
+    if (!m || (!m[2] && !m[3] && !m[5]))
+        return { id: raw, perEpoch: 1, raw };
+    const id = (m[1] ?? "").trim() || raw;
+    if (m[5])
+        return { id, perEpoch: 0, raw };
+    if (m[2])
+        return { id, perEpoch: Number.parseFloat(m[2]), raw };
+    const n = Number.parseFloat(m[3] ?? "1");
+    const unit = (m[4] ?? "day").toLowerCase();
+    const perEpoch = unit.startsWith("w") ? n / 7 : unit.startsWith("m") ? n / 30 : n;
+    return { id, perEpoch, raw };
+}
+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: [], channelPlans: [], 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" || name === "channel" || name === "account")
+                        return;
+                    const value = parseMetricNumber(row[idx] ?? "");
+                    if (value !== undefined)
+                        metrics[name] = value;
+                });
+                if (video) {
+                    results.rows.push({ video, metrics, channel: get("channel", "account")?.trim() || undefined, 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);
+                    // Strip only a LEADING "(capacity N/epoch)" label — a per-channel rate
+                    // in parentheses further along is data, not a label.
+                    const entries = splitList(value.replace(/^\s*\([^)]*\)\s*/, ""));
+                    setup.channelPlans = (entries.length ? entries : splitList(inner?.[1] ?? "")).map(parseChannelPlan);
+                    setup.channels = setup.channelPlans.map((p) => p.id);
+                }
+                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 === "format" || key === "video_format")
+                    setup.format = value;
+                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 if (k === "format")
+                            round.format = 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: [], channelPlans: [], 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) {
+    if (setup.channelPlans.length === 0)
+        return setup.channels.length;
+    const total = setup.channelPlans.reduce((sum, p) => sum + (Number.isFinite(p.perEpoch) ? p.perEpoch : 0), 0);
+    // Round to 2dp so "3/week" style fractions don't print as 0.4285714285714286.
+    return Math.round(total * 100) / 100;
+}
+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);
+}
+/** Deal N video slots out across channels, epoch by epoch, respecting each
+ *  channel's posting frequency.
+ *
+ *  Fractional rates (a channel that can only take 3 posts a week) are handled by
+ *  carrying credit forward: the channel accrues `perEpoch` each epoch and takes a
+ *  slot whenever its credit reaches 1. That keeps a 3/week channel on a real
+ *  every-other-day cadence instead of either over-posting it daily or dropping it.
+ *  Deterministic — same inputs, same schedule. */
+export function allocateSlots(plans, videos) {
+    const active = plans.filter((p) => Number.isFinite(p.perEpoch) && p.perEpoch > 0);
+    if (active.length === 0 || videos <= 0)
+        return [];
+    const credit = new Map(active.map((p) => [p.id, 0]));
+    const out = [];
+    // Bound the loop: even the slowest channel mix can't need more epochs than
+    // videos / smallest-rate, and the +2 covers the first accrual.
+    const slowest = Math.min(...active.map((p) => p.perEpoch));
+    const maxEpochs = Math.ceil(videos / slowest) + 2;
+    for (let epoch = 1; epoch <= maxEpochs && out.length < videos; epoch++) {
+        for (const plan of active) {
+            let c = (credit.get(plan.id) ?? 0) + plan.perEpoch;
+            while (c >= 1 && out.length < videos) {
+                out.push({ epoch, channel: plan.id });
+                c -= 1;
+            }
+            credit.set(plan.id, c);
+        }
+    }
+    return out;
+}
+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();
+    // A video can occupy more than one slot — that IS the cross-account retest.
+    const channelsOf = 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);
+        if (row.channel) {
+            const set = channelsOf.get(row.video) ?? new Set();
+            set.add(row.channel);
+            channelsOf.set(row.video, set);
+        }
+    }
+    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,
+            channel: row.channel ?? (channelsOf.get(row.video)?.size === 1 ? Array.from(channelsOf.get(row.video) ?? [])[0] : undefined),
+            variant: variantOf.get(row.video),
+            posts: postsOf.get(row.video) ?? 0,
+            age: block.age,
+            source: block.source
+        });
+    }
+    // A RETEST is the same video MEASURED on two accounts — not a video whose slot
+    // was planned for one account and whose result came back from another (that is
+    // a plan change, and counting it would clear the confound warning for free).
+    // So: prefer distinct channels across RESULT rows; fall back to distinct
+    // channels across slots that were actually marked posted.
+    const measuredOn = new Map();
+    for (const s of scored) {
+        if (!s.channel)
+            continue;
+        const set = measuredOn.get(s.video) ?? new Set();
+        set.add(s.channel);
+        measuredOn.set(s.video, set);
+    }
+    for (const row of slotRows) {
+        if (!row.video || !row.channel || !row.posted)
+            continue;
+        if (resultRows.some(({ row: r }) => r.video === row.video && r.channel))
+            continue;
+        const set = measuredOn.get(row.video) ?? new Set();
+        set.add(row.channel);
+        measuredOn.set(row.video, set);
+    }
+    const med = median(scored.map((s) => s.value));
+    for (const s of scored)
+        s.ratio = med && med > 0 ? s.value / med : undefined;
+    // Normalize per ACCOUNT. Account health moves numbers by multiples, so a video
+    // is only fairly judged against its own channel's median — and a channel needs
+    // at least two results before it has one.
+    const byChannel = new Map();
+    for (const s of scored) {
+        if (!s.channel)
+            continue;
+        byChannel.set(s.channel, [...(byChannel.get(s.channel) ?? []), s.value]);
+    }
+    const channelMedians = {};
+    for (const [channel, values] of byChannel) {
+        if (values.length < 2)
+            continue;
+        const m = median(values);
+        if (m !== undefined && m > 0)
+            channelMedians[channel] = m;
+    }
+    for (const s of scored) {
+        const m = s.channel ? channelMedians[s.channel] : undefined;
+        s.channelRatio = m ? s.value / m : 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,
+        channelMedians,
+        retested: Array.from(measuredOn.entries()).filter(([, set]) => set.size > 1).map(([video]) => video),
+        // Prefer the account-normalized ratio when the channel has a baseline; fall
+        // back to the round median otherwise.
+        outliers: med && med > 0 ? ranked.filter((s) => (s.channelRatio ?? 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 (!setup.format) {
+        findings.push({
+            level: "warn",
+            code: "no-format",
+            message: "No starting video format in Setup — the format is a PLANNING decision, not something to discover while editing.",
+            fix: `Pick one in the interview and write it down: ${EASY_FORMATS.map((f) => f.label).join(" · ")}. No opinion? Take "${DEFAULT_FORMAT}" and move — don't stall.`
+        });
+    }
+    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>\"." });
+            }
+            // Format is a constant in most rounds. If the round neither pins one nor
+            // inherits one from Setup, its "constants" were never actually constant.
+            if (!round.format && !setup.format && !/format/i.test(round.variable ?? "")) {
+                findings.push({
+                    ...at,
+                    level: "warn",
+                    code: "round-no-format",
+                    message: `Round ${at.round} names no video format, so every video in it can drift to a different one.`,
+                    fix: `Add "- Format: <choice>" to the round (or to Setup, which it inherits). Default: "${DEFAULT_FORMAT}".`
+                });
+            }
+            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."
+            });
+        }
+        // Account health is the biggest confounder in the method: it moves numbers by
+        // multiples, often more than the variable under test. A round whose videos each
+        // sat on a different account has measured the accounts as much as the videos.
+        const channelsUsed = new Set(analysis.scored.map((s) => s.channel).filter(Boolean));
+        if (channelsUsed.size > 1 && analysis.retested.length === 0 && analysis.scored.length > 1) {
+            const normalized = Object.keys(analysis.channelMedians).length;
+            findings.push({
+                ...at,
+                level: normalized > 0 ? "warn" : "error",
+                code: "account-health-confound",
+                message: `Round ${at.round} ranks ${analysis.scored.length} videos across ${channelsUsed.size} accounts with no variant retested on a second account — account health can outweigh the variable you are testing.`,
+                fix: normalized > 0
+                    ? "Per-account medians exist for some channels — judge by those, not the round median. Then retest the leader on a different account to confirm the ordering holds."
+                    : "Re-post the apparent winner on a DIFFERENT account (deduped) and the apparent loser on the winner's account. If the ordering survives the swap, the effect is real; if it flips, you measured account health."
+            });
+        }
+        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;
+            // Only whole slots are postable, and fractional capacity ("3/week") leaves a
+            // remainder that isn't a usable slot — don't report 0.43 free.
+            const free = Math.floor(capacity - used);
+            if (used > 0 && free >= 1) {
+                findings.push({
+                    ...at,
+                    level: "info",
+                    code: "unspent-capacity",
+                    message: `Latest epoch of round ${at.round} uses ${used} of ${capacity} slots — ${free} 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."
+                });
+            }
+        }
+        // A channel scheduled beyond its own stated frequency is how an account gets
+        // throttled or flagged — and a throttled account poisons every number on it.
+        for (const epoch of round.epochs) {
+            const counts = new Map();
+            for (const row of epoch.rows) {
+                if (!row.channel)
+                    continue;
+                counts.set(row.channel, (counts.get(row.channel) ?? 0) + 1);
+            }
+            for (const [channel, used] of counts) {
+                const plan = setup.channelPlans.find((p) => p.id === channel);
+                if (!plan)
+                    continue;
+                const allowed = Math.max(1, Math.ceil(plan.perEpoch));
+                if (plan.perEpoch === 0) {
+                    findings.push({ ...at, level: "warn", code: "paused-channel-scheduled", message: `Round ${at.round}, epoch ${epoch.label ?? "?"}: ${channel} is marked paused but has ${used} slot(s).`, fix: "Un-pause it in Setup, or move those slots to an active channel." });
+                }
+                else if (used > allowed) {
+                    // A bare channel name carries no explicit rate — say "the default" rather
+                    // than echoing the id back as if it were a frequency.
+                    const stated = plan.raw.trim() === plan.id ? "once per epoch (the default)" : `${plan.raw.trim()} (~${allowed}/epoch)`;
+                    findings.push({
+                        ...at,
+                        level: "warn",
+                        code: "channel-overposted",
+                        message: `Round ${at.round}, epoch ${epoch.label ?? "?"}: ${channel} has ${used} slots but its stated frequency is ${stated}.`,
+                        fix: "Spread them over more epochs, or raise the channel's frequency in Setup if it really can take that volume."
+                    });
+                }
+            }
+        }
+        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 plans = input.channelPlans?.length
+        ? input.channelPlans
+        : (input.channels ?? []).map((id) => parseChannelPlan(id));
+    const channelList = plans.map((p) => p.raw.trim()).join(", ");
+    const capacity = plans.length
+        ? Math.round(plans.reduce((sum, p) => sum + p.perEpoch, 0) * 100) / 100
+        : 0;
+    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/experiments.md · started ${input.date ?? ""}`.trim(),
+        "",
+        "## Setup",
+        `- North-star metric: ${metric} (secondary: ${secondary.join(", ")})`,
+        `- Channels (capacity ${capacity || "?"}/epoch): ${channelList || "<run `vidfarm channels` and list them>"}`,
+        "  <!-- per-channel frequency: \"name x2\" = twice an epoch · \"name 3/week\" · \"name paused\" · bare name = once -->",
+        `- Mode: ${input.mode ?? "creative"}`,
+        `- Format: ${input.format ?? DEFAULT_FORMAT}`,
+        `- 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>"}`,
+        "",
+        "",
+        "Format menu (copywriting-led — the words do the work; all ~$0 via `vidfarm public-raws --categories`):",
+        ...EASY_FORMATS.map((f) => `- ${f.label} — ${f.note}`),
+        "",
+        "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")}`);
+    // Deal the slots out by each channel's OWN posting frequency, not round-robin —
+    // a 2/day channel earns two slots an epoch and a 3/week channel skips epochs.
+    const plans = input.channelPlans?.length
+        ? input.channelPlans
+        : (input.channels ?? []).map((id) => ({ id, perEpoch: 1, raw: id }));
+    const allocation = allocateSlots(plans, slots.length);
+    const byEpoch = new Map();
+    slots.forEach((raw, i) => {
+        const [video, variant] = raw.split("|").map((s) => s.trim());
+        // No channel plan at all → still emit the row, with the channel left blank.
+        const slot = allocation[i];
+        const epoch = slot?.epoch ?? Math.floor(i / Math.max(1, input.capacity || slots.length)) + 1;
+        const list = byEpoch.get(epoch) ?? [];
+        list.push({ video: video ?? "", variant, channel: slot?.channel ?? "" });
+        byEpoch.set(epoch, list);
+    });
+    const epochBlocks = [];
+    for (const [epoch, rows] of Array.from(byEpoch.entries()).sort((a, b) => a[0] - b[0])) {
+        epochBlocks.push([
+            `### Epoch ${epoch} — ${epoch === 1 ? (input.date ?? "<date>") : "<date>"}`,
+            "",
+            "| slot | video | variant | channel | posted |",
+            "|---|---|---|---|---|",
+            ...rows.map((r, i) => `| ${i + 1} | ${r.video} | ${r.variant ?? ""} | ${r.channel} | |`),
+            ""
+        ].join("\n"));
+    }
+    return [
+        `## Round ${input.number}${input.title ? ` — ${input.title}` : input.variable ? ` — ${input.variable}` : ""}`,
+        `- Mode: ${input.mode ?? "creative"}`,
+        ...(input.variable ? [`- Variable: ${input.variable}`] : []),
+        `- Format: ${input.format ?? DEFAULT_FORMAT}`,
+        `- Constants: ${input.constants?.length ? input.constants.join(", ") : "—"}`,
+        `- Videos: ${videos} · Capacity ${input.capacity || "?"} slots/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} | ${input.channel ?? ""} | ${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 | channel | ${ordered.join(" | ")} | note |`,
+        `|---|---|${ordered.map(() => "---|").join("")}---|`,
+        `| ${input.video} | ${input.channel ?? ""} | ${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