@koda-sl/baker-cli 0.478.0 → 0.480.0

package/dist/chunk-RTWRNG3E.js

@@ -0,0 +1,821 @@
+import {
+  heldRules
+} from "./chunk-RCSOG2DV.js";
+import {
+  companyLine,
+  readCompanyReading
+} from "./chunk-7U3V64YT.js";
+import {
+  adSetViewerRows,
+  audienceNamesOf,
+  readAudienceNames
+} from "./chunk-BITS62MF.js";
+import {
+  rememberedJev,
+  updateLockedFile
+} from "./chunk-FNA277HP.js";
+import {
+  holdUnbilledSpend
+} from "./chunk-5WMTPYKT.js";
+import {
+  findWorkspaceRoot
+} from "./chunk-23H4ZJRP.js";
+import {
+  readAdSpec
+} from "./chunk-U2452GLO.js";
+import {
+  askAboutText,
+  briefRules
+} from "./chunk-ZBV5IV5T.js";
+import {
+  VIEWER_CHECK_MODEL,
+  canonicalize
+} from "./chunk-T6ATGN7Y.js";
+import {
+  AWARENESS_VALUES,
+  VIEWER_KNOWS_VALUES,
+  VIEWER_SOURCE_VALUES,
+  VIEWER_TEMPERATURE_VALUES,
+  describeMarket,
+  marketFromCompanyDoc,
+  viewerFromKnowledge
+} from "./chunk-KPYDTIAI.js";
+import {
+  askJev
+} from "./chunk-DWX44QL6.js";
+import {
+  HttpClient,
+  requireCredentialsFromEnv
+} from "./chunk-2FSEESJU.js";
+import {
+  optionalTurnId
+} from "./chunk-EE72SSB2.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-WNSE7N75.js";
+
+// src/commands/canvas/viewer-check.ts
+import { createHash as createHash2 } from "crypto";
+import { mkdir as mkdir2, readdir, readFile as readFile3, stat, writeFile as writeFile2 } from "fs/promises";
+import path3 from "path";
+import { defineCommand } from "citty";
+import { parse as parseYaml } from "yaml";
+import { z as z3 } from "zod";
+
+// src/commands/canvas/casting-check.ts
+import { createHash } from "crypto";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import path from "path";
+import { z } from "zod";
+var CastingAnswerSchema = z.object({
+  passes: z.boolean(),
+  why: z.string().default(""),
+  instead: z.string().default("")
+});
+function buildCastingPrompt(input) {
+  return [
+    "An ad is about to be made with these people in it:",
+    ...input.people.map((p) => `- ${p}`),
+    "",
+    `The company: ${input.company.trim() || "(not written down)"}`,
+    ...input.persona ? [`The ad is for: ${input.persona}`] : [],
+    ...input.market ? [`It runs for ${input.market}.`] : [],
+    ...input.rules && input.rules.length > 0 ? ["The company's own rules about who appears in its ads:", ...input.rules.map((r) => `- ${r}`)] : [],
+    "",
+    "Would each of these people pass, to someone scrolling there, as a real customer of this company (or, for a testimonial, someone who really used it)? Judge age, look, setting and origin against who actually buys this, where the ad runs. A model-like face selling to people who are not models does not pass, and a person a rule rules out does not pass. A rule about how or where a person is shown (their size, framing, a round photo, inside a mockup) is not this question: the finished ad is checked against it.",
+    'Reply with only this JSON: {"passes":true|false,"why":"<one sentence>","instead":"<who would pass, in a few words, when one does not>"}'
+  ].join("\n");
+}
+function cacheKey(input, model) {
+  return createHash("sha256").update(JSON.stringify({ prompt: buildCastingPrompt(input), model })).digest("hex");
+}
+function parseOrNull(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function castingCheck(input, opts) {
+  if (input.people.length === 0) return { status: "skipped" };
+  const file = path.join(opts.cacheDir, "casting-check", `${cacheKey(input, opts.model)}.json`);
+  const cachedRaw = await readFile(file, "utf8").catch(() => null);
+  const cachedParse = cachedRaw ? CastingAnswerSchema.safeParse(parseOrNull(cachedRaw)) : null;
+  if (cachedParse?.success) return { status: cachedParse.data.passes ? "passed" : "failed", answer: cachedParse.data, cached: true };
+  const prompt = buildCastingPrompt(input);
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const parsed = CastingAnswerSchema.safeParse(await opts.ask(prompt));
+    if (!parsed.success) continue;
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(parsed.data, null, 2)}
+`, "utf8");
+    return { status: parsed.data.passes ? "passed" : "failed", answer: parsed.data, cached: false };
+  }
+  return { status: "unavailable" };
+}
+function castingCheckFailure(answer, slug) {
+  return {
+    ok: false,
+    error: {
+      code: "casting_check_failed",
+      message: `Not rendered: the people cast would not pass as this company's real customers. ${answer.why}`.trim(),
+      fix: [
+        answer.instead ? `Cast ${answer.instead} instead:` : "Cast someone who would:",
+        "`baker avatars list` for the company's avatars (pass the one that fits with `--avatar` on the scaffold, or set its identity sheet URL from `baker avatars get <handle>` as the PERSON reference's `image` in prompt.json), or `baker avatars create` from the persona (age, origin, setting, accent for this market).",
+        `Then \`baker canvas run --slug ${slug}\` again.`
+      ].join(" ")
+    }
+  };
+}
+
+// src/commands/canvas/turn-renders.ts
+import { readFile as readFile2 } from "fs/promises";
+import path2 from "path";
+import { z as z2 } from "zod";
+var RUNS_PER_TURN = 2;
+var VIEWER_FAILS_PER_TURN = 2;
+var AD_TURN_MS = 12 * 6e4;
+var ROUND_MS = {
+  respec: 6e4,
+  extend: 8e4,
+  relayout: 1e5,
+  fix: 15e4,
+  regenerate: 22e4
+};
+var RENDER_MS = 15e4;
+var LedgerSchema = z2.object({
+  turnId: z2.string(),
+  creatives: z2.record(
+    z2.string(),
+    z2.object({
+      runs: z2.number().default(0),
+      verdict: z2.string().optional(),
+      viewerFails: z2.number().optional(),
+      spentMs: z2.number().optional()
+    })
+  )
+});
+var SHOW_AS_IT_STANDS = `Show the best version as a version ("Version 3"), never a file path or a run id, and say in one plain sentence what is left, in the person's words. End there: no question and no options; their next message says what changes.`;
+function mayBeCorrection(run, shownPrompt, promptOnDisk) {
+  if (run.fix !== void 0 || run.regenerate !== void 0) return true;
+  return shownPrompt !== void 0 && promptOnDisk != null && canonicalize(shownPrompt) !== canonicalize(promptOnDisk);
+}
+function turnRenderRefusal(ledger, turnId, slug, opts = {}) {
+  const entry = turnId !== void 0 && ledger?.turnId === turnId ? ledger.creatives[slug] : void 0;
+  if (!entry) return null;
+  if ((entry.verdict === "ready" || entry.verdict === "ready_with_notes") && opts.correction !== true) {
+    return {
+      code: "CONFLICT",
+      message: `This ad is already ready in this turn (${entry.verdict}): its notes are not defects, and new options are not made for them.`,
+      fix: `Show it now. Only a real defect you can name in it (a logo drawn twice, a word wrong) is corrected in this turn: \`baker canvas run --slug <slug> --fix "<what to change>"\`, or \`--regenerate ${opts.shape === "relayout" ? "adapt" : "format"}_<size>\` for one size. Any other change comes with the person's next message.`
+    };
+  }
+  if ((entry.spentMs ?? 0) + RENDER_MS > AD_TURN_MS) {
+    return {
+      code: "CONFLICT",
+      message: `This ad has had its ${AD_TURN_MS / 6e4} minutes in this turn, its automatic corrections included, and is still not ready.`,
+      fix: SHOW_AS_IT_STANDS
+    };
+  }
+  if (entry.runs >= RUNS_PER_TURN) {
+    return {
+      code: "CONFLICT",
+      message: `This ad was rendered twice in this turn, its automatic corrections included, and is still not ready.`,
+      fix: SHOW_AS_IT_STANDS
+    };
+  }
+  return null;
+}
+function recordTurnRender(ledger, turnId, slug, verdict, tookMs) {
+  const creatives = ledger?.turnId === turnId ? ledger.creatives : {};
+  const entry = creatives[slug];
+  const spentMs = (entry?.spentMs ?? 0) + (tookMs ?? 0);
+  return {
+    turnId,
+    creatives: {
+      ...creatives,
+      [slug]: { ...entry, runs: (entry?.runs ?? 0) + 1, verdict, ...spentMs > 0 ? { spentMs } : {} }
+    }
+  };
+}
+function roundFitsTurn(ledger, turnId, slug, renderMs, kind) {
+  const entry = turnId !== void 0 && slug !== void 0 && ledger?.turnId === turnId ? ledger.creatives[slug] : void 0;
+  return (entry?.spentMs ?? 0) + renderMs + ROUND_MS[kind] <= AD_TURN_MS;
+}
+function recordViewerFail(ledger, turnId, slug) {
+  const creatives = ledger?.turnId === turnId ? ledger.creatives : {};
+  const entry = creatives[slug] ?? { runs: 0 };
+  return { turnId, creatives: { ...creatives, [slug]: { ...entry, viewerFails: (entry.viewerFails ?? 0) + 1 } } };
+}
+function viewerChecksSpent(ledger, turnId, slug) {
+  const entry = turnId !== void 0 && ledger?.turnId === turnId ? ledger.creatives[slug] : void 0;
+  return (entry?.viewerFails ?? 0) >= VIEWER_FAILS_PER_TURN;
+}
+var ledgerPath = (cacheDir) => path2.join(cacheDir, "turn-renders.json");
+async function readTurnRenders(cacheDir) {
+  try {
+    const parsed = LedgerSchema.safeParse(JSON.parse(await readFile2(ledgerPath(cacheDir), "utf8")));
+    return parsed.success ? parsed.data : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function updateTurnRenders(cacheDir, change) {
+  await updateLockedFile(ledgerPath(cacheDir), async () => JSON.stringify(change(await readTurnRenders(cacheDir))));
+}
+
+// src/commands/canvas/viewer-check.ts
+var VIEWER_QUESTIONS = ["offer", "for_whom", "next_step"];
+var VIEWER_CLARITY = ["clear", "guess", "unclear"];
+var ViewerReply = z3.object({ answer: z3.string().default(""), clarity: z3.enum(VIEWER_CLARITY) });
+var ViewerAnswerSchema = z3.object({
+  offer: ViewerReply,
+  for_whom: ViewerReply,
+  next_step: ViewerReply,
+  /** The words that talk to the viewer as if they had already done something with the brand; "" when none. */
+  presumes: z3.string().default(""),
+  missing: z3.string().default("")
+});
+var VIEWER_REQUIRED_CLARITY = {
+  offer: "clear",
+  for_whom: "unclear",
+  next_step: "guess"
+};
+var RANK = { unclear: 0, guess: 1, clear: 2 };
+var sureEnough = (clarity, least) => RANK[clarity] >= RANK[least];
+var OFFER_READ = 0.5;
+var READ_QUESTION = "A viewer said an ad offers `viewer_said`; the ad means `meant`. Does `viewer_said` name the same thing on offer as `meant`, in other words or in another language? A general kind of thing that covers it counts (delivery driver jobs for van driving work).";
+var SELLS_QUESTION = "A viewer said an ad offers `viewer_said`. Is `viewer_said` about what `company_sells` describes: the same product or service, a part of it, or a step toward buying it (a quote, a survey, a trial), in any language?";
+function jevReadJudge(onSpend) {
+  return async (pairs) => {
+    const questions = pairs.flatMap((p) => [
+      { instructions: { viewer_said: p.said, meant: p.meant, question: READ_QUESTION } },
+      ...p.sells ? [{ instructions: { viewer_said: p.said, company_sells: p.sells, question: SELLS_QUESTION } }] : []
+    ]);
+    const answers = await askJev(questions, onSpend);
+    if (answers === null) return null;
+    let next = 0;
+    return pairs.map((p) => {
+      const meant = answers[next++] ?? 0;
+      return p.sells ? Math.max(meant, answers[next++] ?? 0) : meant;
+    });
+  };
+}
+async function misreadings(pairs, judge) {
+  const asked = pairs.flatMap(
+    (p, i) => p.said.trim() && p.meant?.trim() ? [{ i, pair: { said: p.said.trim(), meant: p.meant.trim(), ...p.sells?.trim() ? { sells: p.sells.trim() } : {} } }] : []
+  );
+  const out = pairs.map(() => false);
+  if (asked.length === 0) return out;
+  const judged = await judge(asked.map((a) => a.pair)).catch(() => null);
+  if (judged === null) return out;
+  asked.forEach((a, k) => {
+    const p = judged[k];
+    out[a.i] = p !== void 0 && p < OFFER_READ;
+  });
+  return out;
+}
+function judgeViewerAnswer(answer, intended, required = VIEWER_REQUIRED_CLARITY, offerMisread = false) {
+  const missed = [];
+  for (const question of VIEWER_QUESTIONS) {
+    const reply = answer[question];
+    const meant = question === "offer" ? intended.offer : question === "for_whom" ? intended.persona : void 0;
+    const withIntended = meant ? { intended: meant } : {};
+    if (RANK[reply.clarity] < RANK[required[question]]) {
+      missed.push({
+        question,
+        reason: reply.clarity === "unclear" ? "unclear" : "guessed",
+        viewerSaid: reply.answer,
+        ...withIntended
+      });
+    } else if (question === "offer" && offerMisread) {
+      missed.push({ question, reason: "misread", viewerSaid: reply.answer, ...withIntended });
+    }
+  }
+  if (answer.presumes.trim()) missed.push({ question: "presumes", reason: "presumed", viewerSaid: answer.presumes.trim() });
+  return { pass: missed.length === 0, missed };
+}
+var SMALL_PRINT = /^(fine_print|legal|disclaimer|footnote)$/;
+function wherePhrase(placements) {
+  const fullScreen = placements.length === 0 || placements.some((p) => /automatic|stor|reel/i.test(p));
+  return fullScreen ? "full screen through Instagram or Facebook Stories and Reels, thumb ready to swipe" : "through your Instagram or Facebook feed";
+}
+function knowledgePhrase(viewer, offer) {
+  const brand = "the advertiser";
+  if (!viewer.knows.includes("brand")) return `You have never heard of ${brand} and know nothing about what it sells.`;
+  const offerPart = viewer.knows.includes("offer") ? offer ? ` You know what they offer: ${offer}.` : " You know what they offer." : " You do not know what they are offering right now.";
+  const product = viewer.knows.includes("product") ? " You have used what they sell." : "";
+  return `You have come across ${brand} before.${offerPart}${product}`;
+}
+function buildViewerPrompt(input) {
+  const brand = "the advertiser";
+  const stranger = !input.viewer.knows.includes("brand");
+  const read = input.copy.filter((line) => !SMALL_PRINT.test((line.role ?? "").trim().toLowerCase().replace(/[\s-]+/g, "_")));
+  const words = read.length > 0 ? read.map((line) => `- "${line.text}"${line.on ? ` (written on the ${line.on})` : ""}`).join("\n") : "- none: the picture is the whole ad";
+  return [
+    `${input.viewer.market ? `You are ${describeMarket(input.viewer.market)}.` : "You live where this ad runs and read its language natively."} You are scrolling ${wherePhrase(input.viewer.placements)}. ${knowledgePhrase(input.viewer, input.intended.offer)}`,
+    `An ad from an advertiser whose name means nothing to you holds you for about three seconds: you take in the picture and read the biggest words, not every line. This is what you see, plus the platform's usual button under it (such as "Learn more"):`,
+    "",
+    `Picture: ${input.scene.trim()}`,
+    "Words on it:",
+    words,
+    "",
+    "Answer as this person, from those words, that picture and what you already know. Do not fill gaps with what ads like this usually sell.",
+    `For each question give your answer in English and how sure you are: "clear" when the words or the picture say it outright, or you already know it; "guess" when you are piecing it together from someone else's story or review, a list of perks, a statistic or the advertiser's name; "unclear" when you cannot tell.`,
+    "offer: what is being offered?",
+    "for_whom: who is it for?",
+    "next_step: what would you do next if you wanted it?",
+    ...stranger ? [
+      `presumes: quote the words that say you have already done something with ${brand} (bought, signed up, started a trial, an order or a registration, donated, left something in a basket); words that only speak to you, or say what you would get, do not count; "" when none do.`
+    ] : [],
+    'missing: in one short sentence, what you would need to be told to get it; "" when nothing.',
+    "",
+    `Reply with only this JSON: {"offer":{"answer":"","clarity":"clear|guess|unclear"},"for_whom":{"answer":"","clarity":"clear|guess|unclear"},"next_step":{"answer":"","clarity":"clear|guess|unclear"},${stranger ? '"presumes":"",' : ""}"missing":""}`
+  ].join("\n");
+}
+function viewerCheckCacheKey(input, model) {
+  const { temperature, knows, placements, market } = input.viewer;
+  const canonical = {
+    prompt: buildViewerPrompt({ ...input, viewer: { ...input.viewer, reasons: [] } }),
+    viewer: { temperature, knows: [...knows].sort(), placements: [...placements].sort(), ...market ? { market } : {} },
+    intended: input.intended,
+    model
+  };
+  return createHash2("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+async function cachedAnswer(file) {
+  try {
+    const parsed = ViewerAnswerSchema.safeParse(JSON.parse(await readFile3(file, "utf8")));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+async function checkViewer(input, opts) {
+  const file = path3.join(opts.cacheDir, "viewer-check", `${viewerCheckCacheKey(input, opts.model)}.json`);
+  let answer = await cachedAnswer(file);
+  const cached = answer !== null;
+  const prompt = buildViewerPrompt(input);
+  for (let attempt = 0; answer === null && attempt < 2; attempt++) {
+    const parsed = ViewerAnswerSchema.safeParse(await opts.ask(prompt));
+    if (parsed.success) answer = parsed.data;
+  }
+  if (answer === null) return { status: "unavailable", input };
+  if (!cached) {
+    await mkdir2(path3.dirname(file), { recursive: true });
+    await writeFile2(file, `${JSON.stringify(answer, null, 2)}
+`, "utf8");
+  }
+  const sure = sureEnough(answer.offer.clarity, VIEWER_REQUIRED_CLARITY.offer);
+  const [offerMisread = false] = sure ? await misreadings(
+    [{ said: answer.offer.answer, meant: input.intended.offer, sells: input.intended.sells }],
+    opts.judge ?? jevReadJudge()
+  ) : [];
+  const verdict = judgeViewerAnswer(answer, input.intended, VIEWER_REQUIRED_CLARITY, offerMisread);
+  const judged = { input, answer, verdict, cached };
+  return verdict.pass ? { ...judged, status: "passed" } : { ...judged, status: "failed" };
+}
+function describeViewer(viewer) {
+  const known = viewer.knows.map((k) => `the ${k}`);
+  const knows = known.length > 0 ? `who knows ${known.length > 1 ? `${known.slice(0, -1).join(", ")} and ${known.at(-1)}` : known[0]}` : "who knows nothing about the brand yet";
+  return `a ${viewer.temperature} viewer ${knows}, on ${viewer.placements.join(", ") || "automatic"} placements`;
+}
+var QUESTION_WORDS = {
+  offer: "what is offered",
+  for_whom: "who it is for",
+  next_step: "what to do next"
+};
+function missLine(miss) {
+  if (miss.question === "presumes") {
+    return `The words talk to them as if they had already done something with the brand: "${miss.viewerSaid}". They have not.`;
+  }
+  const said = miss.viewerSaid.trim() ? `"${miss.viewerSaid.trim()}"` : "nothing";
+  const how = miss.reason === "misread" ? `was sure it is ${said}` : miss.reason === "guessed" ? `could only guess ${said}` : `could not tell (said ${said})`;
+  const question = QUESTION_WORDS[miss.question];
+  return `${question.charAt(0).toUpperCase()}${question.slice(1)}: they ${how}${miss.intended ? `; the ad means "${miss.intended}"` : ""}.`;
+}
+function viewerCheckFailure(outcome, slug) {
+  const { viewer } = outcome.input;
+  const who = describeViewer(viewer);
+  const missing = outcome.answer.missing.trim();
+  const unsaid = outcome.verdict.missed.flatMap((m) => m.question === "presumes" ? [] : [QUESTION_WORDS[m.question]]);
+  const offer = outcome.input.intended.offer?.trim();
+  const rewrite = offer && outcome.verdict.missed.some((m) => m.question === "offer") ? [`Do this: make the biggest words say "${offer}", plainly, in the ad's language; keep the rest.`] : [];
+  const fix = [
+    ...rewrite,
+    ...unsaid.length > 0 ? [`Seen by ${who}, the words and picture alone do not say ${unsaid.join(" or ")}.`] : [`Seen by ${who}:`],
+    ...outcome.verdict.missed.map(missLine),
+    ...missing ? [`They needed: ${missing}`] : [],
+    "Rewrite the copy in prompt.json so the words on the ad say it plainly (name the offer and who it is for; a stranger reads only what is printed), then re-run.",
+    // The run asks the viewer itself, from the same cache: a separate check is one more wait (dev, Oct 2026).
+    `Then run the same \`baker canvas run\` again: it checks the new copy before it spends (or \`baker canvas viewer-check ${slug}\` alone).`,
+    "If this ad will run to people who already know the brand, record that viewer in _definition.md (`targetAdSet` and `viewer`, from `baker ads meta adsets --audience`) instead of rewriting."
+  ].join(" ");
+  return {
+    ok: false,
+    error: {
+      code: "viewer_check_failed",
+      message: `Not rendered: ${who} would not understand this ad.`,
+      fix,
+      viewer,
+      missed: outcome.verdict.missed
+    }
+  };
+}
+var RecordedViewer = z3.object({
+  temperature: z3.enum(VIEWER_TEMPERATURE_VALUES),
+  knows: z3.array(z3.enum(VIEWER_KNOWS_VALUES)).default([]),
+  placements: z3.array(z3.string().min(1)).default(["automatic"]),
+  source: z3.enum(VIEWER_SOURCE_VALUES),
+  reasons: z3.array(z3.string()).default([]),
+  market: z3.object({
+    country: z3.string().min(2),
+    language: z3.string().optional(),
+    currency: z3.string().optional(),
+    address: z3.string().optional()
+  }).optional()
+});
+var nameKey = (text) => text.normalize("NFD").replace(new RegExp("\\p{M}", "gu"), "").toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean).join(" ");
+function personaSegments(persona, entries) {
+  const describe = (entry) => entry.segment ?? entry.title ?? entry.slug;
+  if (!persona?.trim()) return entries.map(describe);
+  const wanted = nameKey(persona);
+  const match = entries.find(
+    (entry) => [entry.slug.replace(/[-_]/g, " "), entry.title, entry.segment].some((name) => name && nameKey(name) === wanted)
+  );
+  return [match ? describe(match) : persona.trim()];
+}
+async function resolveViewer(sources, lookups) {
+  const resolved = await resolveViewerAlone(sources, lookups);
+  if (resolved.viewer.market || !lookups.companyMarket) return resolved;
+  const market = await lookups.companyMarket().catch(() => void 0);
+  return market ? { ...resolved, viewer: { ...resolved.viewer, market } } : resolved;
+}
+async function resolveViewerAlone(sources, lookups) {
+  const notes = [];
+  if (sources.recorded !== void 0) {
+    const recorded = RecordedViewer.safeParse(sources.recorded);
+    if (recorded.success) return { viewer: recorded.data, from: "recorded", notes };
+    notes.push("The viewer recorded in _definition.md is not in the shape `baker ads meta adsets --audience` prints; it was skipped.");
+  }
+  if (sources.targetAdSet) {
+    try {
+      const fromAdSet = await lookups.adSetViewer(sources.targetAdSet);
+      if (fromAdSet) return { viewer: fromAdSet, from: "ad_set", notes };
+      notes.push(`Ad set ${sources.targetAdSet} is not in any connected Meta ad account.`);
+    } catch (e) {
+      notes.push(`Could not read ad set ${sources.targetAdSet} (${e instanceof Error ? e.message : String(e)}).`);
+    }
+  }
+  let entries = [];
+  try {
+    entries = await lookups.personas();
+  } catch (e) {
+    notes.push(`Could not read the personas in the Knowledge (${e instanceof Error ? e.message : String(e)}).`);
+  }
+  const personas = personaSegments(sources.persona, entries);
+  if (personas.length > 0 || sources.awareness) {
+    return { viewer: viewerFromKnowledge({ personas, awareness: sources.awareness }), from: "knowledge", notes };
+  }
+  return {
+    viewer: {
+      temperature: "cold",
+      knows: [],
+      placements: ["automatic"],
+      source: "knowledge",
+      reasons: [
+        "Nothing says who will see this ad (no viewer or targetAdSet in _definition.md, no persona in the Knowledge), so it is checked against a cold stranger who has never heard of the brand."
+      ]
+    },
+    from: "default",
+    notes
+  };
+}
+var Frontmatter = z3.object({
+  viewer: z3.unknown().optional(),
+  targetAdSet: z3.union([z3.string(), z3.number()]).transform(String).optional(),
+  persona: z3.string().optional(),
+  awareness: z3.enum(AWARENESS_VALUES).optional().catch(void 0),
+  angle: z3.string().optional()
+});
+function frontmatterOf(raw) {
+  const block = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
+  if (!block) return {};
+  try {
+    const parsed = Frontmatter.safeParse(parseYaml(block));
+    return parsed.success ? parsed.data : {};
+  } catch {
+    return {};
+  }
+}
+async function readCreativeForViewerCheck(creativeDir) {
+  const spec = readAdSpec(JSON.parse(await readFile3(path3.join(creativeDir, "prompt.json"), "utf8")));
+  const definition = frontmatterOf(await readFile3(path3.join(creativeDir, "_definition.md"), "utf8").catch(() => ""));
+  const offer = spec.message?.trim() || definition.angle?.trim();
+  const persona = spec.viewer?.who.trim() || definition.persona?.trim();
+  const brand = spec.brand?.name?.trim();
+  const sells = (await readCompanyReading(path3.resolve(creativeDir, "../../..")))?.sells;
+  return {
+    ad: {
+      copy: spec.copy.map((line) => ({
+        text: line.text,
+        ...line.lettering === "in_scene" && line.on ? { on: line.on } : {},
+        ...line.role ? { role: line.role } : {}
+      })),
+      scene: spec.scene.description,
+      ...brand ? { brand } : {},
+      intended: { ...offer ? { offer } : {}, ...persona ? { persona } : {}, ...sells ? { sells } : {} },
+      ...castPeople(spec)
+    },
+    sources: {
+      ...definition.viewer !== void 0 ? { recorded: definition.viewer } : {},
+      ...definition.targetAdSet ? { targetAdSet: definition.targetAdSet } : {},
+      ...definition.persona?.trim() ? { persona: definition.persona.trim() } : {},
+      ...definition.awareness ? { awareness: definition.awareness } : {}
+    }
+  };
+}
+function castPeople(spec) {
+  const people = spec.references.filter((r) => r.role === "identity" && (r.avatar || r.image) && !/^ANIMAL_/.test(r.id)).map((r) => r.what);
+  return people.length > 0 ? { people } : {};
+}
+async function readPersonas(workspaceRoot) {
+  const dir = path3.join(workspaceRoot, "src", "content", "personas");
+  let files;
+  try {
+    files = (await readdir(dir, { recursive: true })).filter((f) => f.endsWith(".md"));
+  } catch {
+    return [];
+  }
+  return await Promise.all(
+    files.map(async (file) => {
+      const raw = await readFile3(path3.join(dir, file), "utf8");
+      const block = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
+      let segment;
+      try {
+        segment = block ? parseYaml(block)?.segment : void 0;
+      } catch {
+        segment = void 0;
+      }
+      const title = raw.match(/^#\s+(.+)$/m)?.[1]?.trim();
+      return {
+        slug: path3.basename(file, ".md"),
+        ...title ? { title } : {},
+        ...typeof segment === "string" && segment.trim() ? { segment: segment.trim() } : {}
+      };
+    })
+  );
+}
+function bakerRead() {
+  const creds = requireCredentialsFromEnv();
+  const http = new HttpClient({ baseUrl: creds.url, apiKey: creds.apiKey, timeoutMs: 6e4, maxRetries: 1 });
+  return (apiPath, params) => http.getJson(params ? `${apiPath}?${new URLSearchParams(params)}` : apiPath);
+}
+async function metaAccountIds(read) {
+  const named = process.env.BAKER_META_AD_ACCOUNT_ID;
+  if (named) return [named];
+  const accounts = await read("/api/ads/meta/accounts");
+  return accounts.flatMap((a) => {
+    const id = a.externalId ?? a.id;
+    return typeof id === "string" && id ? [id] : [];
+  });
+}
+async function metaAdSetViewer(adSetId, workspaceRoot) {
+  const read = bakerRead();
+  for (const account of (await metaAccountIds(read)).slice(0, 5)) {
+    const params = { "account-id": account.startsWith("act_") ? account : `act_${account}` };
+    const adSet = (await read("/api/ads/meta/adsets", params)).find((row) => String(row.id) === adSetId);
+    if (!adSet) continue;
+    const [audiences, campaigns] = await Promise.all([
+      read("/api/ads/meta/audiences", params).catch(() => []),
+      read("/api/ads/meta/campaigns", params).catch(() => [])
+    ]);
+    const cacheDir = path3.join(workspaceRoot, "canvas", ".cache");
+    const spent = [];
+    const readName = await readAudienceNames(
+      audienceNamesOf([adSet], audiences),
+      rememberedJev(path3.join(cacheDir, "audience-names.json"), (u) => spent.push(u))
+    );
+    await holdUnbilledSpend(cacheDir, spent).catch(() => void 0);
+    return adSetViewerRows([adSet], audiences, campaigns, readName)[0]?.viewer ?? null;
+  }
+  return null;
+}
+var CAST_RULES = 8;
+function liveViewerLookups(workspaceRoot) {
+  return {
+    adSetViewer: (adSetId) => metaAdSetViewer(adSetId, workspaceRoot),
+    personas: () => readPersonas(workspaceRoot),
+    companyMarket: async () => marketFromCompanyDoc(await readFile3(path3.join(workspaceRoot, "COMPANY.md"), "utf8").catch(() => null)),
+    company: async () => companyLine(await readCompanyReading(workspaceRoot)),
+    // Who appears, as the rules that hold for this ad say: a person's on its picture or cast, the brand's on
+    // its cast only (a brand document's picture rules are often its web design system's: `briefRules`).
+    castRules: async (creativeDir) => briefRules((await heldRules(creativeDir)).rules).filter((r) => r.applies === "cast" || r.origin === "learned" && r.applies === "picture").slice(0, CAST_RULES).map((r) => r.text)
+  };
+}
+function gatewayViewerModel(model, onSpend) {
+  return (prompt) => askAboutText(model, prompt, onSpend);
+}
+var SKIP_WORDS = {
+  fix: "a correction of a version already checked",
+  resume: "a resumed render, checked when it started",
+  asked: "--skip-viewer-check"
+};
+function viewerCheckSkip(run) {
+  if (run.fix || run.useVariant || run.relaid || run.autoFixRound > 0) return "fix";
+  if (run.resumed) return "resume";
+  return run.asked ? "asked" : null;
+}
+async function viewerCheckBeforeRender(opts) {
+  let creative;
+  try {
+    creative = await readCreativeForViewerCheck(opts.creativeDir);
+  } catch (e) {
+    return {
+      viewer: null,
+      lines: [`[warn] viewer_check_skipped: prompt.json could not be read for the viewer check (${e instanceof Error ? e.message : String(e)}).`]
+    };
+  }
+  const resolved = await resolveViewer(creative.sources, opts.lookups);
+  const who = describeViewer(resolved.viewer);
+  const lines = resolved.notes.map((note) => `[viewer] ${note}`);
+  if (opts.skip) return { viewer: resolved.viewer, lines: [...lines, `[viewer] not asked: ${SKIP_WORDS[opts.skip]}.`] };
+  const casting = (async () => castingCheck(
+    {
+      people: creative.ad.people ?? [],
+      company: await opts.lookups.company?.().catch(() => "") ?? "",
+      rules: await opts.lookups.castRules?.(opts.creativeDir).catch(() => []) ?? [],
+      ...resolved.viewer.market ? { market: describeMarket(resolved.viewer.market) } : {},
+      ...creative.ad.intended.persona ? { persona: creative.ad.intended.persona } : {}
+    },
+    { cacheDir: opts.cacheDir, model: opts.model, ask: opts.ask }
+  ))().catch(() => ({ status: "unavailable" }));
+  const outcome = await checkViewer({ ...creative.ad, viewer: resolved.viewer }, opts);
+  if (outcome.status === "unavailable") {
+    lines.push(
+      `[warn] viewer_check_unavailable: the viewer model did not answer, so this ad renders without the viewer check. Read the copy as ${who} before showing it, or run \`baker canvas viewer-check ${opts.slug}\` again.`
+    );
+  } else if (outcome.status === "failed" && !opts.spent) {
+    return { viewer: resolved.viewer, lines, failure: viewerCheckFailure(outcome, opts.slug) };
+  } else if (outcome.status === "failed") {
+    lines.push(
+      `[viewer] this ad failed the viewer check twice in this turn, so it renders as written. Tell the person what ${who} missed: ${outcome.verdict.missed.map(missLine).join(" ")}`
+    );
+  } else {
+    lines.push(`[viewer] ${who} understood it: ${outcome.answer.offer.answer}${outcome.cached ? " (cached)" : ""}.`);
+  }
+  if (outcome.status === "unavailable") return { viewer: resolved.viewer, lines };
+  const cast = await casting;
+  if (cast.status === "failed") return { viewer: resolved.viewer, lines, failure: castingCheckFailure(cast.answer, opts.slug) };
+  if (cast.status === "passed") lines.push(`[casting] the people cast pass as real customers${cast.cached ? " (cached)" : ""}.`);
+  if (cast.status === "unavailable") {
+    lines.push("[warn] casting_check_unavailable: the model did not answer; check yourself that the people cast look like this company's real customers.");
+  }
+  return { viewer: resolved.viewer, lines };
+}
+var DESCRIPTION = "Would the person this ad reaches understand it? A model plays the viewer the creative is for (the `viewer` in _definition.md, else the one its `targetAdSet` reaches, else the persona and awareness in the Knowledge, else a cold stranger) and says, from prompt.json's copy and scene alone, what is offered, to whom and what to do next; the answer is compared with prompt.json's `message`. Start here after writing the copy, before rendering: baker canvas viewer-check spring-offer. `baker canvas run` makes the same check before it spends, from the same cache, and refuses a static ad the viewer would not understand (exit 2, `viewer_check_failed`, `fix` saying what they missed). Output is compact; --full adds the viewer's whole answer and why that viewer was chosen.";
+var ARGS = {
+  slug: {
+    type: "positional",
+    required: true,
+    description: "The creative: its slug (src/creatives/<slug>/), or the path to its folder, canvas or prompt.json."
+  },
+  full: {
+    type: "boolean",
+    required: false,
+    default: false,
+    description: "Add the viewer's whole answer, what the ad means to say, and how the viewer was resolved."
+  }
+};
+registerSchema({ command: "canvas.viewer-check", description: DESCRIPTION, args: ARGS });
+async function creativeDirOf(arg, workspaceRoot) {
+  const direct = path3.resolve(arg);
+  try {
+    return (await stat(direct)).isDirectory() ? direct : path3.dirname(direct);
+  } catch {
+    return path3.join(workspaceRoot, "src", "creatives", arg);
+  }
+}
+var viewerCheckCommand = defineCommand({
+  meta: { name: "viewer-check", description: DESCRIPTION },
+  args: ARGS,
+  async run({ args }) {
+    const cwd = process.cwd();
+    const workspaceRoot = findWorkspaceRoot(cwd) ?? cwd;
+    const creativeDir = await creativeDirOf(String(args.slug), workspaceRoot);
+    const slug = path3.basename(creativeDir);
+    let creative;
+    try {
+      creative = await readCreativeForViewerCheck(creativeDir);
+    } catch (e) {
+      writeJson({
+        ok: false,
+        error: {
+          code: "NOT_FOUND",
+          message: `No readable prompt.json in ${creativeDir} (${e instanceof Error ? e.message : String(e)}).`,
+          fix: "Pass the creative's slug (src/creatives/<slug>/) or its folder; its prompt.json must parse."
+        }
+      });
+      process.exit(1);
+    }
+    const resolved = await resolveViewer(creative.sources, liveViewerLookups(workspaceRoot));
+    const input = { ...creative.ad, viewer: resolved.viewer };
+    const cacheDir = path3.join(workspaceRoot, "canvas", ".cache");
+    const spent = [];
+    const outcome = await checkViewer(input, {
+      cacheDir,
+      model: VIEWER_CHECK_MODEL,
+      ask: gatewayViewerModel(VIEWER_CHECK_MODEL, (usage) => spent.push(usage)),
+      judge: jevReadJudge((usage) => spent.push(usage))
+    });
+    await holdUnbilledSpend(cacheDir, spent);
+    const who = describeViewer(resolved.viewer);
+    const detail = args.full ? {
+      viewer_profile: resolved.viewer,
+      viewer_from: resolved.from,
+      intended: input.intended,
+      ...outcome.status !== "unavailable" ? { answer: outcome.answer } : {},
+      ...resolved.notes.length > 0 ? { notes: resolved.notes } : {}
+    } : {};
+    if (outcome.status === "failed") {
+      const turnId = optionalTurnId();
+      const ledger = await readTurnRenders(cacheDir);
+      if (viewerChecksSpent(ledger, turnId, slug)) {
+        writeJson({
+          ok: true,
+          data: { checked: true, understood: false, viewer: who, missed: outcome.verdict.missed, ...detail },
+          hints: [
+            `This ad failed the viewer check twice in this turn: render it as written (baker canvas run --slug ${slug}) and tell the person what ${who} missed: ${outcome.verdict.missed.map(missLine).join(" ")}`
+          ]
+        });
+        return;
+      }
+      if (turnId) await updateTurnRenders(cacheDir, (current) => recordViewerFail(current, turnId, slug));
+      const failure = viewerCheckFailure(outcome, slug);
+      writeJson({ ...failure, error: { ...failure.error, ...detail } });
+      process.exit(2);
+    }
+    if (outcome.status === "unavailable") {
+      writeJson({
+        ok: true,
+        data: { checked: false, viewer: who, ...detail },
+        hints: [
+          "The viewer model did not answer (no gateway key here, or it failed twice). Read the copy as this viewer yourself, or run the check again."
+        ]
+      });
+      return;
+    }
+    writeJson({
+      ok: true,
+      data: {
+        checked: true,
+        understood: true,
+        viewer: who,
+        offer: outcome.answer.offer.answer,
+        for_whom: outcome.answer.for_whom.answer,
+        next_step: outcome.answer.next_step.answer,
+        ...outcome.cached ? { cached: true } : {},
+        ...detail
+      },
+      hints: [
+        resolved.from === "default" ? "Checked against a cold stranger because nothing says who will see this ad: record `targetAdSet` and `viewer` in _definition.md (`baker ads meta adsets --audience`) when it will run in a known ad set." : `Checked against ${who}. Render it: baker canvas run --slug ${slug}`
+      ]
+    });
+  }
+});
+
+export {
+  mayBeCorrection,
+  turnRenderRefusal,
+  recordTurnRender,
+  roundFitsTurn,
+  recordViewerFail,
+  viewerChecksSpent,
+  readTurnRenders,
+  updateTurnRenders,
+  VIEWER_QUESTIONS,
+  VIEWER_CLARITY,
+  ViewerAnswerSchema,
+  VIEWER_REQUIRED_CLARITY,
+  sureEnough,
+  OFFER_READ,
+  jevReadJudge,
+  misreadings,
+  judgeViewerAnswer,
+  buildViewerPrompt,
+  viewerCheckCacheKey,
+  checkViewer,
+  describeViewer,
+  viewerCheckFailure,
+  personaSegments,
+  resolveViewer,
+  readCreativeForViewerCheck,
+  readPersonas,
+  liveViewerLookups,
+  gatewayViewerModel,
+  viewerCheckSkip,
+  viewerCheckBeforeRender,
+  viewerCheckCommand
+};
+//# sourceMappingURL=chunk-RTWRNG3E.js.map