@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/service.ts

@@ -0,0 +1,1483 @@
+// F074.5 — Lens service layer.
+//
+// The browser-owning operations, as pure functions shared by BOTH the HTTP
+// router (http.ts) and the MCP server (mcp.ts). Each is hard-scoped to a
+// project_slug — a project only ever touches its own runs/baselines.
+//
+// Artifact bytes are served back by the daemon itself (artifactUrl); the SPA
+// dashboard + cc point <img>/links at the daemon, the same way the rest of
+// the SPA already talks to 127.0.0.1:7475.
+
+import { randomUUID } from 'node:crypto';
+import sharp from 'sharp';
+import { durabilityOf } from './durability.ts';
+import type { Database } from 'bun:sqlite';
+import type { CaptureAction, CaptureMode } from './capture.ts';
+import { coerceStorageSeed } from './seed-storage.ts';
+import type { LensEngine } from './browser.ts';
+import { verify as runVerify, type LensStatus } from './verify.ts';
+import type { CriticMode } from './critic.ts';
+import type { VisionModelKey } from './critic-vision.ts';
+import type { VideoCheckOptions } from './video.ts';
+import type { AuthConfig, AuthEnv } from './auth/index.ts';
+import {
+  recordRun,
+  listRuns,
+  getRun,
+  listBaselines,
+  getBaselineBytes,
+  promoteBaseline,
+  deleteBaseline,
+  listBaselineVersions,
+  revertBaseline,
+} from './store.ts';
+import { runFlow, parseFlow, compileManuscript, type FlowResult, type FlowStepResult } from './flow.ts';
+// F074.24 — the daemon HOSTS the engine's own runFlow for flat cloud-shape
+// FlowRequests (one wire-shape, driven via @broberg/lens-client). The engine
+// natively speaks the cloud grammar (all 12 action-verbs), self-heals via the
+// same resolveTarget the daemon uses (F074.23), and does the F049 base_url nav —
+// so there is ZERO grammar translation. It owns its own Chromium + takes a
+// storageState directly, so nothing crosses the playwright version boundary.
+import { runFlow as engineRunFlow, flowBodySchema, type FlowResult as EngineFlowResult } from '@broberg/lens-engine';
+import { authProvenance, resolveAuthPaths, resolveLocale, manifestLocale } from './manifest.ts';
+import { recordFlowRun, listFlowRuns, type StoredFlowStep } from './flow-store.ts';
+import { artifactKeys, type LensStorage } from './storage.ts';
+import { exportPage, looksLikePdf, readMediaBox, ptToMm, type ExportMedia } from './export.ts';
+import { pdfContentStats, isVectorText, matchPhrase, outlineFontNames } from './pdf-text.ts';
+import type { LensRunRow, LensBaselineRow, LensFlowRunRow } from './schema.ts';
+import { runRecord } from './record-run.ts';
+
+export interface LensDeps {
+  db: Database;
+  storage: LensStorage;
+  port: number;
+  /** Sandbox roots — used to resolve a flow/manuscript's relative auth statePath
+   *  when local_path is passed. NOTE: inheriting a project's manifest auth is
+   *  the FLOW/MANUSCRIPT path only (effectiveFlowAuth in manifest.ts); this
+   *  comment used to claim it happened here too, which measurably it does not
+   *  — see resolveVerifyAuth below, which returns early when no auth is given. */
+  sandboxRoots: string[];
+  /** F272.2 — a getter, not the client itself: the daemon's cloud client is
+   *  re-made on login and nulled on logout, so capturing the value at wiring time
+   *  would hand this a client that is permanently stale (or permanently null on a
+   *  daemon that started signed-out and was signed in afterwards). */
+  cloud?: () => CloudClientLike | null;
+  /** lens F001.5 — the daemon's own sandbox check, injected (see sandbox.ts). The
+   *  package holds no copy of this security boundary; createLensRouter installs it. */
+  resolveSandboxedPath?: (path: string, sandboxRoots: string[]) => string;
+}
+
+/** The one method promoteFlowEvidence needs. Structural on purpose so a test can
+ *  pass a stub without dragging the daemon's real client (and its fetch) in. */
+export interface CloudClientLike {
+  callTool<T = unknown>(name: string, args?: Record<string, unknown>): Promise<T>;
+}
+
+/** F312.25 — `lens_record` through the MCP door.
+ *
+ *  Christian: «byg lens_record MCP-verbet». Before this, recording existed ONLY
+ *  as POST /lens/record on the daemon, so no other repo could use it — and F112
+ *  forbids them hand-rolling a call to :7475. Two repos hit that wall within one
+ *  hour on 6 September (this one, and fd-sundhed's F006.385).
+ *
+ *  IT DELEGATES. runRecord() is the same function the HTTP route calls; there is
+ *  no second handler here that "does the same thing". F095.15 is the precedent —
+ *  a rule present through one door and absent through the other looked correct
+ *  from either side, and a peer repo found it.
+ */
+export async function lensRecord(deps: LensDeps, args: Record<string, unknown>) {
+  // NAMED before a browser is launched. An empty `seconds` that reaches the
+  // recorder becomes a 0-second run that reports zero findings — indistinguishable
+  // from a clean result, which is the confusion this whole feature removes.
+  const missing = (['url', 'seconds'] as const).filter((k) => args[k] == null);
+  if (missing.length)
+    return {
+      ok: false as const,
+      error: `lens_record needs ${missing.join(' and ')}. \`url\` is the surface to watch and \`seconds\` is how long — a recording with no duration cannot say whether nothing happened or nothing was watched.`,
+    };
+
+  const { status: _status, ...rest } = await runRecord(args, {
+    config: { port: deps.port, sandbox_roots: deps.sandboxRoots },
+    storage: deps.storage,
+  });
+  return rest;
+}
+
+export function artifactUrl(port: number, key: string | null): string | null {
+  if (!key) return null;
+  return `http://127.0.0.1:${port}/lens/artifact?key=${encodeURIComponent(key)}`;
+}
+
+interface SurfaceInput {
+  url?: string;
+  mode?: CaptureMode;
+  selector?: string;
+  selector_index?: number;
+  /** {width,height} OR a device preset (`device`). A string is tolerated (some
+   *  MCP harnesses stringify object params). See coerceViewport. */
+  viewport?: { width: number; height: number } | string;
+  device?: string;
+  /** F252.1 — deviceScaleFactor for retina / 2×–3× captures. Default 1. */
+  scale?: number;
+  /** F098.9 — engine to drive (chromium default; webkit/firefox for cross-engine bugs). */
+  engine?: LensEngine;
+  /** F074.57 — BCP-47 locale + IANA timezone. Wins over the project's
+   *  lens.manifest.json; unset falls back to the manifest, then to nothing. */
+  locale?: string;
+  timezone?: string;
+  /** F074.59 — what this run reports for `prefers-reduced-motion`. Default
+   *  'reduce' (unchanged from every run before the option existed); pass
+   *  'no-preference' to let the run SEE motion. Never inherited from the
+   *  manifest: whether a run may animate is a property of the QUESTION being
+   *  asked, not of the project, and inheriting it would silently move baselines
+   *  for every capture in a repo that set it once. */
+  reduced_motion?: 'reduce' | 'no-preference';
+  /** F098.6 — navigation settle strategy (default 'domcontentloaded'). */
+  waitUntil?: 'load' | 'domcontentloaded' | 'commit';
+  waitFor?: string | number;
+  actions?: CaptureAction[];
+  auth?: AuthConfig;
+  /** F074.97 — {local, session} written BEFORE the first navigation, scoped to
+   *  this url's origin. Lets a saved-client-state bug be PHOTOGRAPHED instead of
+   *  only unit-fixtured. Omitted registers no init script, so no baseline moves. */
+  storage?: unknown;
+  surface_key?: string | null;
+  timeout_ms?: number;
+  /** F126.4 — composition critic: 'off' (default) | 'dom' | 'vision' | 'both'. */
+  critic?: CriticMode;
+  /** F126.4 — vision model for the critic's vision pass ('haiku' | 'sonnet'). */
+  critic_vision_model?: VisionModelKey;
+  /** F074.69 — load an UNPACKED extension build directory and capture its own
+   *  pages. Write the url as `extension://popup.html`; Lens substitutes the id
+   *  Chromium generates, because the caller cannot know it in advance. */
+  extension?: { path: string };
+}
+
+export interface CaptureInput extends SurfaceInput {
+  project: string;
+  url: string;
+}
+
+export interface VerifyInput extends CaptureInput {
+  assert?: string;
+  baseline_key?: string;
+  diff_threshold?: number;
+  /** F089.2 — smoke-only: skip the baseline diff entirely (render + assert). */
+  no_diff?: boolean;
+  /** Video-liveness: drive a <video> + assert it plays. Not-playing → fail. */
+  video?: VideoCheckOptions;
+}
+
+function requireProject(project: unknown): string {
+  if (typeof project !== 'string' || !project.trim()) {
+    throw new Error('project (slug) is required and scopes all runs/baselines');
+  }
+  return project.trim();
+}
+
+function runView(run: LensRunRow, port: number) {
+  return {
+    run_id: run.id,
+    project: run.project_slug,
+    surface_key: run.surface_key,
+    url: run.url,
+    mode: run.mode,
+    selector: run.selector,
+    status: run.status,
+    reason: run.reason,
+    diff_ratio: run.diff_ratio,
+    dom_hash: run.dom_hash,
+    assert_pass: run.assert_pass === null ? null : run.assert_pass === 1,
+    width: run.width,
+    height: run.height,
+    duration_ms: run.duration_ms,
+    created_at: run.created_at,
+    // F074.30 — which build this capture measured; null = not measured.
+    build: run.build ?? null,
+    screenshot_url: artifactUrl(port, run.artifact_key),
+    diff_url: artifactUrl(port, run.diff_artifact_key),
+    // F126.4 — composition-critic findings persisted with the run (history).
+    critic: run.critic_json ? safeParse(run.critic_json) : null,
+  };
+}
+
+function safeParse(json: string): unknown {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+// Lens-mobile — resolve a viewport from a {width,height} object, a device
+// preset, or a STRINGIFIED object. The MCP harness stringifies nested object
+// params that aren't declared in the tool schema → the daemon used to forward
+// that string to Playwright newContext ("expected object, got string" → hang).
+// Declaring `viewport` in the schema (mcp.ts) fixes the root; this coerce is the
+// belt-and-suspenders + the `device` preset convenience.
+const DEVICE_PRESETS: Record<string, { width: number; height: number }> = {
+  'iphone-15': { width: 393, height: 852 },
+  'iphone-13': { width: 390, height: 664 }, // F098.9 — sa's F024 webkit repro device
+  'iphone-15-pro-max': { width: 430, height: 932 },
+  'iphone-se': { width: 375, height: 667 },
+  'pixel-8': { width: 412, height: 915 },
+  ipad: { width: 820, height: 1180 },
+  mobile: { width: 390, height: 844 },
+  tablet: { width: 820, height: 1180 },
+  desktop: { width: 1280, height: 800 },
+};
+export function coerceViewport(
+  viewport?: { width: number; height: number } | string,
+  device?: string,
+): { width: number; height: number } | undefined {
+  // F098.4 — AN UNRESOLVABLE VIEWPORT IS AN ERROR, NOT A DESKTOP CAPTURE.
+  //
+  // Every branch below used to `return undefined` on bad input, and undefined
+  // means "use Playwright's default" — 1280×800. So asking for mobile with a
+  // typo'd device name or a viewport string that isn't JSON produced a DESKTOP
+  // screenshot with status "pass". Measured 20 Sep 2026: viewport:"ikke-json"
+  // → width 1280, height 800, pass. You get an answer about the wrong screen
+  // and nothing in it says so — the exact shape this card's original bug had,
+  // one branch further along.
+  //
+  // Asking for nothing is still fine: no viewport and no device → undefined →
+  // the default, deliberately. Only a viewport that was REQUESTED and could not
+  // be honoured throws.
+  if (device) {
+    const preset = DEVICE_PRESETS[device.toLowerCase()];
+    if (preset) return preset;
+    throw new Error(
+      `unknown device preset "${device}" — known: ${Object.keys(DEVICE_PRESETS).join(', ')}`,
+    );
+  }
+  if (viewport === undefined || viewport === null) return undefined;
+  let v: unknown = viewport;
+  if (typeof v === 'string') {
+    try {
+      v = JSON.parse(v);
+    } catch {
+      throw new Error(`viewport is not valid JSON: ${JSON.stringify(viewport)}`);
+    }
+  }
+  if (v && typeof v === 'object') {
+    const w = (v as { width?: unknown }).width;
+    const h = (v as { height?: unknown }).height;
+    if (typeof w === 'number' && typeof h === 'number') return { width: w, height: h };
+  }
+  throw new Error(`viewport must be {width:number,height:number} — got ${JSON.stringify(viewport)}`);
+}
+
+/** F074.22 — resolve a bare capture/verify's relative auth secretPath/statePath
+ *  against the CALLING PROJECT's registered local_path (the flow/manuscript path
+ *  already does this via effectiveFlowAuth). Without it a relative path is read
+ *  against the daemon's cwd — i.e. cardmem's own repo — so a consumer's relative
+ *  `.lens-mint-secret` silently reads cardmem's credential and 401s. Unregistered
+ *  project or an unresolvable path → left as-is (an absolute path still works).
+ *
+ *  IT DOES NOT INHERIT. `if (!auth) return auth` is deliberate: a capture with no
+ *  auth stays unauthenticated. Reported by xrt81 (2026-08-12) after a capture
+ *  passed only local_path, landed on the sign-in wall and timed out after 30s
+ *  while the same call as a manuscript was green — the tool description implied
+ *  inheritance applied to both. The description now says which is which.
+ *
+ *  Whether capture SHOULD inherit is a real question and deliberately not
+ *  answered here: auto-inheriting would change what every existing capture
+ *  photographs, and a manifest can carry `auth: null` per surface precisely
+ *  because an authenticated visitor gets redirected away from a public landing
+ *  page. Opt-in, if ever. */
+/** F074.57 — the project's registered repo root, so a capture inherits its
+ *  project's locale WITHOUT the caller passing local_path. Deliberately unlike
+ *  auth, and the asymmetry is the point: inheriting a credential changes WHO the
+ *  browser is and can silently photograph a login wall, so it stayed opt-in.
+ *  Inheriting a locale changes only how the SAME page is formatted, which is
+ *  exactly what "per project" has to mean for Christian's case — otherwise every
+ *  call site has to remember, and a rule you must remember is not a rule. */
+function projectLocale(deps: LensDeps, project: string): { locale?: string; timezone?: string } | null {
+  const row = deps.db
+    .query('SELECT local_path FROM registered_projects WHERE slug = ?')
+    .get(project) as { local_path: string } | undefined;
+  return row?.local_path ? manifestLocale(row.local_path, deps.sandboxRoots) : null;
+}
+
+export function resolveVerifyAuth(
+  deps: LensDeps,
+  project: string,
+  auth: AuthConfig | undefined,
+): AuthConfig | undefined {
+  if (!auth) return auth;
+  const row = deps.db
+    .query('SELECT local_path FROM registered_projects WHERE slug = ?')
+    .get(project) as { local_path: string } | undefined;
+  if (!row?.local_path) return auth;
+  return (resolveAuthPaths(auth, row.local_path) as AuthConfig | undefined) ?? auth;
+}
+
+/** F074.39 — lens_capture takes no `assert` and never ran one, but accepted the
+ *  parameter and answered `assert_pass: null` on every call, including a body
+ *  that could not possibly pass (beacon, idea `019fdcae`). A caller reading
+ *  "status: pass" had no way to know their assertion had simply been dropped.
+ *
+ *  So it REFUSES rather than ignores, and the message names the tool that does
+ *  run asserts. Same family as the `project_id` find of 2026-08-07: a parameter
+ *  the tool does not implement is silently accepted and the call succeeds. */
+export function rejectUnsupportedAssert(input: unknown, tool: string): void {
+  if (input && typeof input === 'object' && (input as { assert?: unknown }).assert !== undefined) {
+    throw new Error(
+      `${tool} does not run asserts — it only screenshots, and silently ignoring one would report a pass for an assertion that never ran. Use lens_verify({ assert }) instead.`,
+    );
+  }
+}
+
+/** lens_capture — screenshot a surface, record the run, return the shot URL. */
+export async function lensCapture(deps: LensDeps, input: CaptureInput) {
+  const project = requireProject(input.project);
+  rejectUnsupportedAssert(input, 'lens_capture');
+  const result = await runVerify({
+    url: input.url,
+    mode: input.mode,
+    selector: input.selector,
+    engine: input.engine,
+    ...resolveLocale(input, projectLocale(deps, project)),
+    reducedMotion: input.reduced_motion,
+    viewport: coerceViewport(input.viewport, input.device),
+    // F252.1 — some MCP harnesses stringify number params ("2"), and Playwright's
+    // newContext rejects a string deviceScaleFactor. Coerce; garbage → default 1.
+    deviceScaleFactor: input.scale == null ? undefined : Number(input.scale) || undefined,
+    waitUntil: input.waitUntil,
+    waitFor: input.waitFor,
+    actions: input.actions,
+    auth: resolveVerifyAuth(deps, project, input.auth),
+    timeoutMs: input.timeout_ms,
+    critic: input.critic,
+    criticVisionModel: input.critic_vision_model,
+    storage: coerceStorageSeed(input.storage),
+    extension: input.extension,
+    // capture-only: no baseline, no assert → status is page-loaded-ok
+  });
+  const run = await recordRun(deps.db, deps.storage, result, {
+    project_slug: project,
+    surface_key: input.surface_key ?? null,
+  });
+  // F074.69 — the extension id is returned so the caller can cite WHICH surface
+  // was photographed. It is generated at load time, so without this the run says
+  // only "an extension" and a reader cannot tell one build from another.
+  return { ...runView(run, deps.port), critic: result.critic, extension: result.extension ?? null };
+}
+
+/** lens_verify — capture + (optional) baseline diff + (optional) assert, with
+ *  the prioritised status logic. Baseline is auto-loaded from the store by
+ *  baseline_key when present. */
+export async function lensVerify(deps: LensDeps, input: VerifyInput) {
+  const project = requireProject(input.project);
+  // upmetrics #3 — auto-diff when a baseline EXISTS for the surface, even if the
+  // manifest surface didn't repeat baseline_key. lens_approve_baseline stores
+  // under the run's surface_key, so fall back to surface_key: approving a shot
+  // now activates the diff on the next gate with no manifest edit.
+  // F089.2 — a smoke surface NEVER diffs, even if a baseline exists (live-data
+  // dashboards drift to a false red otherwise). Render + anchor + assert only.
+  const effectiveBaselineKey = input.no_diff ? null : (input.baseline_key ?? input.surface_key ?? null);
+  let baseline: Buffer | null = null;
+  if (effectiveBaselineKey) {
+    baseline = await getBaselineBytes(deps.db, deps.storage, project, effectiveBaselineKey);
+  }
+  const result = await runVerify({
+    url: input.url,
+    mode: input.mode,
+    selector: input.selector,
+    engine: input.engine,
+    ...resolveLocale(input, projectLocale(deps, project)),
+    reducedMotion: input.reduced_motion,
+    viewport: coerceViewport(input.viewport, input.device),
+    // F255.10 — verify inherits `scale` from the capture schema; it was accepted and
+    // dropped here, so a scale:4 verify rendered 1×. Same coercion as lensCapture.
+    deviceScaleFactor: input.scale == null ? undefined : Number(input.scale) || undefined,
+    waitUntil: input.waitUntil,
+    waitFor: input.waitFor,
+    actions: input.actions,
+    auth: resolveVerifyAuth(deps, project, input.auth),
+    timeoutMs: input.timeout_ms,
+    assert: input.assert,
+    // Only declare a baselineKey to the status logic when a baseline actually
+    // exists — else a surface with a key but no approved shot would read as a
+    // hard "no-baseline" fail instead of a smoke pass.
+    // no_diff → no baselineKey at all (pure smoke). Else only declare one when a
+    // baseline actually exists, so a key with no approved shot reads as a smoke
+    // pass, not a hard "no-baseline" fail.
+    baselineKey: input.no_diff ? undefined : baseline ? effectiveBaselineKey ?? undefined : input.baseline_key,
+    baseline,
+    diffThreshold: input.diff_threshold,
+    critic: input.critic,
+    criticVisionModel: input.critic_vision_model,
+    storage: coerceStorageSeed(input.storage),
+    video: input.video,
+  });
+  const run = await recordRun(deps.db, deps.storage, result, {
+    project_slug: project,
+    surface_key: input.surface_key ?? input.baseline_key ?? null,
+  });
+  return {
+    ...runView(run, deps.port),
+    assert_detail: result.assertResult?.detail ?? null,
+    console: result.console,
+    network: result.network,
+    page_errors: result.pageErrors,
+    preflight_ok: result.preflight?.ok ?? true,
+    critic: result.critic,
+    video: result.video,
+  };
+}
+
+export interface CatalogueSurface {
+  name: string;
+  path: string;
+  mode?: CaptureMode;
+  selector?: string;
+  /** F098.6 — navigation settle strategy (default 'domcontentloaded'). */
+  waitUntil?: 'load' | 'domcontentloaded' | 'commit';
+  waitFor?: string | number;
+  assert?: string;
+  baseline_key?: string;
+  /** F089.2 — smoke-only: never pixel-diff this surface (live-data dashboard). */
+  no_diff?: boolean;
+  /** F092.9 — per-surface viewport (e.g. 390x844 for a mobile baseline). Object,
+   *  device preset, or stringified object (coerceViewport). */
+  viewport?: { width: number; height: number } | string;
+  device?: string;
+  /** F098.9 — per-surface engine override (chromium default; webkit/firefox). */
+  engine?: LensEngine;
+  /** Per-surface auth override. `undefined` = inherit the catalogue-level auth;
+   *  `null` = explicitly NO auth (e.g. a public landing page that would redirect
+   *  an authenticated visitor away). Lets one manifest mix public + authed. */
+  auth?: AuthConfig | null;
+}
+
+export interface CatalogueInput {
+  project: string;
+  base_url: string;
+  surfaces: CatalogueSurface[];
+  auth?: AuthConfig;
+  diff_threshold?: number;
+}
+
+/** lens_capture_catalogue — verify a batch of surfaces against one base URL.
+ *  F074.6 adds a lens.manifest.json loader that feeds this; here surfaces are
+ *  passed inline. Returns a per-surface verdict + an aggregate pass/fail. */
+export async function lensCaptureCatalogue(deps: LensDeps, input: CatalogueInput) {
+  const project = requireProject(input.project);
+  if (!Array.isArray(input.surfaces) || input.surfaces.length === 0) {
+    throw new Error('surfaces[] is required');
+  }
+  const base = input.base_url.replace(/\/$/, '');
+  const results = [];
+  for (const s of input.surfaces) {
+    const url = `${base}${s.path.startsWith('/') ? s.path : `/${s.path}`}`;
+    const view = await lensVerify(deps, {
+      project,
+      url,
+      mode: s.mode,
+      selector: s.selector,
+      waitUntil: s.waitUntil,
+      waitFor: s.waitFor,
+      assert: s.assert,
+      baseline_key: s.baseline_key,
+      no_diff: s.no_diff,
+      engine: s.engine,
+      viewport: coerceViewport(s.viewport, s.device),
+      surface_key: s.baseline_key ?? s.name,
+      // Per-surface auth wins; `null` = explicit no-auth; undefined inherits.
+      auth: (s.auth === null ? undefined : s.auth ?? input.auth),
+      diff_threshold: input.diff_threshold,
+    });
+    results.push({ name: s.name, ...view });
+  }
+  const failed = results.filter((r) => r.status === 'fail' || r.status === 'error');
+  // upmetrics #5 — a "pass" is ambiguous: a surface diffed against a baseline
+  // (diff_ratio !== null) is genuinely VISUAL-verified; a surface with no
+  // baseline that merely loaded without errors is a SMOKE pass. Split them so a
+  // green "7/7" can't masquerade as visual coverage it doesn't have.
+  const passes = results.filter((r) => r.status === 'pass');
+  const diffVerified = passes.filter((r) => r.diff_ratio !== null).length;
+  const smoke = passes.length - diffVerified;
+  return {
+    project,
+    total: results.length,
+    passed: passes.length,
+    diff_verified: diffVerified,
+    smoke,
+    no_baseline: results.filter((r) => r.status === 'no-baseline').length,
+    failed: failed.length,
+    aggregate: (failed.length === 0 ? 'pass' : 'fail') as LensStatus | 'pass' | 'fail',
+    surfaces: results,
+  };
+}
+
+export interface ApproveInput {
+  project: string;
+  run_id: string;
+  baseline_key?: string;
+}
+
+export async function lensApproveBaseline(deps: LensDeps, input: ApproveInput): Promise<LensBaselineRow & { artifact_url: string | null }> {
+  const project = requireProject(input.project);
+  const run = getRun(deps.db, input.run_id);
+  if (!run) throw new Error(`run not found: ${input.run_id}`);
+  if (run.project_slug !== project) {
+    throw new Error(`run ${input.run_id} belongs to "${run.project_slug}", not "${project}"`);
+  }
+  const baseline = await promoteBaseline(deps.db, deps.storage, input.run_id, input.baseline_key);
+  return { ...baseline, artifact_url: artifactUrl(deps.port, baseline.artifact_key) };
+}
+
+// F089 — clear (unapprove) a baseline so its surface returns to no-baseline
+// (smoke). A live-data surface wrongly approved diffs forever otherwise; approve
+// was one-way. upmetrics 2026-06-02.
+export async function lensClearBaseline(deps: LensDeps, input: { project: string; baseline_key: string }) {
+  const project = requireProject(input.project);
+  if (!input.baseline_key) throw new Error('baseline_key is required');
+  const cleared = await deleteBaseline(deps.db, deps.storage, project, input.baseline_key);
+  return { project, baseline_key: input.baseline_key, cleared };
+}
+
+export interface ListRunsInput {
+  project: string;
+  status?: string;
+  surface_key?: string;
+  limit?: number;
+}
+
+export function lensListRuns(deps: LensDeps, input: ListRunsInput) {
+  const project = requireProject(input.project);
+  const runs = listRuns(deps.db, project, {
+    status: input.status,
+    surface_key: input.surface_key,
+    limit: input.limit,
+  });
+  return { project, count: runs.length, runs: runs.map((r) => runView(r, deps.port)) };
+}
+
+/** lens_billboard — a Sharp contact-sheet grid of recent run screenshots.
+ *  Returns PNG bytes (a glanceable "wall" of the project's surfaces). */
+export async function lensBillboard(deps: LensDeps, project: string, limit = 24): Promise<Buffer> {
+  const p = requireProject(project);
+  const runs = listRuns(deps.db, p, { limit });
+  const cw = 220;
+  const ch = 140;
+  const gap = 8;
+  const cols = 4;
+  const bg = { r: 244, g: 241, b: 234 }; // --color-ivory-ish
+
+  const thumbs: Buffer[] = [];
+  for (const r of runs) {
+    if (!r.artifact_key) continue;
+    const bytes = await deps.storage.get(r.artifact_key);
+    if (!bytes) continue;
+    thumbs.push(await sharp(bytes).resize(cw, ch, { fit: 'cover', position: 'top' }).png().toBuffer());
+  }
+  if (thumbs.length === 0) {
+    return sharp({ create: { width: cw, height: ch, channels: 3, background: bg } }).png().toBuffer();
+  }
+  const rows = Math.ceil(thumbs.length / cols);
+  const W = cols * cw + (cols + 1) * gap;
+  const H = rows * ch + (rows + 1) * gap;
+  const composite = thumbs.map((input, i) => ({
+    input,
+    left: gap + (i % cols) * (cw + gap),
+    top: gap + Math.floor(i / cols) * (ch + gap),
+  }));
+  return sharp({ create: { width: W, height: H, channels: 3, background: bg } })
+    .composite(composite)
+    .png()
+    .toBuffer();
+}
+
+// ── F082 — E2E flow runs ────────────────────────────────────────────────────
+
+/**
+ * F074.36 — accept an auth block that arrived as a JSON STRING.
+ *
+ * `parseFlow` already tolerates this for `flow`, because MCP clients routinely
+ * serialize a nested object argument. `auth` did not, and the result was a
+ * truthy non-object that reached the adapter switch as `unknown auth adapter:
+ * undefined` — so the manuscript capability was broken for exactly the callers
+ * it was built for (MCP), while working over HTTP. Verified both ways before
+ * adding this: the HTTP call with a real object passed, the MCP call with the
+ * same content did not.
+ *
+ * Deliberately NOT silent: unparseable input throws rather than degrading to "no
+ * auth", which would drop the run back into the exact silence this card removes.
+ */
+export function coerceAuth(raw: unknown): AuthConfig | undefined {
+  if (raw == null) return undefined;
+  if (typeof raw === 'string') {
+    const s = raw.trim();
+    if (!s) return undefined;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(s);
+    } catch (err) {
+      throw new Error(`auth was a string but not valid JSON: ${err instanceof Error ? err.message : err}`);
+    }
+    return coerceAuth(parsed);
+  }
+  if (typeof raw !== 'object') throw new Error(`auth must be an object, got ${typeof raw}`);
+  const a = raw as { adapter?: unknown };
+  if (typeof a.adapter !== 'string' || !a.adapter) {
+    throw new Error('auth.adapter is required (storageState | cookieJwt | mintEndpoint)');
+  }
+  return raw as AuthConfig;
+}
+
+/** F074.36 — the run's auth provenance for the report. A run recorded before
+ *  this shipped has no column value; it says so rather than implying it ran
+ *  authenticated. */
+function parseAuthJson(raw: string | null | undefined): { source: string; adapter: string | null; note?: string } {
+  if (!raw) return { source: 'unknown', adapter: null, note: 'this run predates auth reporting' };
+  try {
+    return JSON.parse(raw) as { source: string; adapter: string | null; note?: string };
+  } catch {
+    return { source: 'unknown', adapter: null, note: 'auth provenance could not be read back' };
+  }
+}
+
+/** NULL = the row predates the column, so we have no answer; `{}` = the run
+ *  looked and found nothing. Malformed JSON is reported as unknown rather than
+ *  as "clean": a parse failure must never read as an all-clear. */
+function parseFindingsJson(raw: string | null | undefined): Record<string, unknown> | null {
+  if (raw == null) return null;
+  try {
+    const v = JSON.parse(raw);
+    return v && typeof v === 'object' ? (v as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function flowRunView(row: LensFlowRunRow, port: number) {
+  const steps = (JSON.parse(row.steps_json) as StoredFlowStep[]).map((s) => ({
+    index: s.index,
+    type: s.type,
+    label: s.label,
+    status: s.status,
+    testid: s.testid,
+    detail: s.detail,
+    ...(s.fault ? { fault: s.fault } : {}),
+    // F074.49 — the app's own failed responses. Present only on steps that have
+    // them, so a clean run reads exactly as before.
+    ...(s.network?.length ? { network: s.network } : {}),
+    // F126.7 — the composition findings, all of them. Named here as well as in
+    // flow.ts and flow-store.ts: the three-place rule F074.49 exists to enforce.
+    ...(s.critic ? { critic: s.critic } : {}),
+    // F213.12 — the third layer of the three-place rule, for F213.11's timing.
+    // Absent means the step never ran; 0 means it ran immediately, so the test
+    // is on the TYPE. A skipped step must stay silent rather than claim 0.
+    ...(typeof s.ms_after_navigation === 'number' ? { ms_after_navigation: s.ms_after_navigation } : {}),
+    // F213.13 — the step's own duration. start + duration is what makes a step
+    // with internal waiting (a click retrying actionability) answerable at all.
+    ...(typeof s.ms_step_duration === 'number' ? { ms_step_duration: s.ms_step_duration } : {}),
+    screenshot_url: artifactUrl(port, s.artifact_key),
+  }));
+  return {
+    flow_run_id: row.id,
+    project: row.project_slug,
+    flow_name: row.flow_name,
+    status: row.status,
+    failed_at: row.failed_at,
+    reason: row.reason,
+    step_count: row.step_count,
+    duration_ms: row.duration_ms,
+    created_at: row.created_at,
+    // F074.30 — WHICH build this run measured. null = not measured; a caller
+    // comparing two runs must refuse on a null rather than assume "same build".
+    build: row.build ?? null,
+    // F074.36 — the two facts that decide whether a verdict is worth anything:
+    // which page it judged, and whether it was logged in. `auth` is never
+    // omitted — a run with no credential says so, with the reason.
+    final_url: row.final_url ?? null,
+    auth: parseAuthJson(row.auth_json),
+    // F074.59 — which browser this verdict came from. 'reduce' | 'no-preference' |
+    // null = NOT RECORDED (a run predating the field). Always present, never
+    // defaulted: a green run that cannot say whether motion was on is
+    // uninterpretable, and guessing on its behalf is how that ambiguity survives.
+    reduced_motion: (row.reduced_motion as 'reduce' | 'no-preference' | null) ?? null,
+    // F272.2 — WHERE this run's screenshots live, so a session citing the run as
+    // evidence can see the answer AT CITATION TIME instead of discovering it after
+    // the machine is gone. 'local' = one Mac's disk behind 127.0.0.1, reachable by
+    // nobody else and by no one once the daemon stops. 'tigris' = durable. null =
+    // NOT RECORDED (a run predating the column) — a third fact, and `unknown` is
+    // never rounded up to durable. Always present, never defaulted, for the same
+    // reason reduced_motion above is.
+    artifact_backend: (row.artifact_backend as 'local' | 'tigris' | null) ?? null,
+    // F272.2 — the derived one-word answer to the only question a citation asks:
+    // can the owner still open this after this machine is gone?
+    evidence_durability: durabilityOf(row.artifact_backend),
+    // F074.99 — the run-level findings a reader can ACT on: a password that came
+    // back in the URL, a page that was never listening while we wrote to it.
+    // `{}` means the run looked and found nothing; NULL means the row predates
+    // the field and carries no answer either way — the same three-value posture
+    // as reduced_motion and artifact_backend above, and for the same reason.
+    //
+    // WHY THIS LINE EXISTS: both findings were computed correctly in flow.ts and
+    // surfaced NOWHERE. fd-sundhed searched the whole body of lens_run_manuscript
+    // and lens_list_flow_runs for the string and found neither — "the instrument
+    // measures right and nobody is told", which is the same shape as the probe
+    // that sat unwired to `fill` for a month.
+    findings: parseFindingsJson(row.findings_json),
+    steps,
+    // F255.5 — present only when the run was recorded. Same artifact mechanism as
+    // the step screenshots, so a consumer fetches it exactly the same way.
+    ...(row.video_key ? { video_url: artifactUrl(port, row.video_key) } : {}),
+  };
+}
+
+export interface RunFlowInput {
+  project: string;
+  /** Untrusted flow object — validated by parseFlow at the boundary. */
+  flow: unknown;
+  /** F082.4 — resume: skip flattened steps before this index. */
+  from?: number;
+  /** F082.6 — repo root. Resolves a flow's relative auth statePath AND lets the
+   *  flow inherit the project's lens.manifest.json auth when it has none. */
+  local_path?: string;
+  /** F092.9 — run the flow at a non-default viewport (e.g. 390x844 for mobile
+   *  E2E + baselines). Defaults to the 1280x800 desktop context. Object, device
+   *  preset, or stringified object (coerceViewport). */
+  viewport?: { width: number; height: number } | string;
+  device?: string;
+  /** F098.9 — engine to drive the flow (chromium default; webkit/firefox). */
+  engine?: LensEngine;
+  /** F074.57 — BCP-47 locale + IANA timezone. Wins over lens.manifest.json. A
+   *  bilingual site is captured once per language via this override. */
+  locale?: string;
+  timezone?: string;
+  /** F074.59 — what this run reports for `prefers-reduced-motion`. Default
+   *  'reduce' (unchanged from every run before the option existed); pass
+   *  'no-preference' to let the run SEE motion. Never inherited from the
+   *  manifest: whether a run may animate is a property of the QUESTION being
+   *  asked, not of the project, and inheriting it would silently move baselines
+   *  for every capture in a repo that set it once. */
+  reduced_motion?: 'reduce' | 'no-preference';
+  /** F126.4 — composition critic on each screenshot step ('off'|'dom'|'vision'|'both'). */
+  critic?: CriticMode;
+  /** F255.5 — record the whole run to a .webm and return it as video_url. */
+  record?: boolean;
+  /** F074.97 — {local, session} seeded before the flow's first navigation,
+   *  scoped to the flow's own base_url origin. */
+  storage?: unknown;
+}
+
+// F074.24 — a flat cloud FlowRequest ({name, base_url, steps:[{action,...}]}, no
+// {project,flow} wrapper) is recognised by a top-level `steps`/`base_url` and the
+// absence of `flow`. It is handed to the engine's runFlow; the native
+// {project, flow} body keeps the daemon's own manuscript executor.
+export interface FlatFlowInput {
+  /** Optional project scope (recommendation A: optional daemon-side). Runs land
+   *  under FLAT_FLOW_DEFAULT_PROJECT when absent. */
+  project?: string;
+  base_url: string;
+  steps: unknown[];
+  [k: string]: unknown;
+}
+
+export function isFlatFlowBody(input: unknown): input is FlatFlowInput {
+  if (!input || typeof input !== 'object') return false;
+  const o = input as Record<string, unknown>;
+  return o.flow === undefined && (Array.isArray(o.steps) || typeof o.base_url === 'string');
+}
+
+/** Runs from a flat cloud FlowRequest with no `project` land under this bucket. */
+export const FLAT_FLOW_DEFAULT_PROJECT = '_external';
+
+/** Map the engine's FlowResult (cloud shape) onto the daemon's FlowResult so it
+ *  persists as an ordinary daemon flow-run (recordFlowRun). resolved_via becomes
+ *  the step detail — the self-heal audit trail for a testid-less field. */
+export function mapEngineFlowResult(r: EngineFlowResult): FlowResult {
+  let failed_at: number | null = null;
+  let reason: string | null = null;
+  let duration_ms = 0;
+  const steps: FlowStepResult[] = r.steps.map((s) => {
+    duration_ms += s.ms ?? 0;
+    const status: FlowStepResult['status'] = s.status === 'ok' ? 'pass' : 'fail';
+    if (status === 'fail' && failed_at === null) {
+      failed_at = s.index;
+      reason = s.error ?? 'step failed';
+    }
+    return {
+      index: s.index,
+      type: s.action,
+      label: s.detail ?? s.action,
+      status,
+      testid: null,
+      detail: s.error ?? (s.resolved_via ? `resolved via ${s.resolved_via}` : (s.detail ?? null)),
+      screenshot: s.png ?? null,
+    };
+  });
+  return {
+    name: r.name ?? 'flow',
+    status: r.status === 'passed' ? 'pass' : 'fail',
+    steps,
+    failed_at,
+    reason,
+    duration_ms,
+  };
+}
+
+/** Build the engine's NATIVE cloud FlowResult for a flat-body response (F074.24
+ *  response convergence — storeform #16012). A flat (cloud-shape) caller must get
+ *  the same shape BOTH Lens surfaces share: `action` verbs, status `passed`/`ok`,
+ *  and a STRUCTURED `resolved_via` (not free-text detail) — so a consumer's
+ *  pass/fail check + self-heal drift telemetry read ONE contract. Re-mapping to
+ *  the daemon's legacy step-shape (as flowRunView does for native callers) is the
+ *  bug this fixes. png bytes are stripped; screenshot_url reuses the artifacts
+ *  recordFlowRun already persisted. */
+export function toCloudFlowResult(result: EngineFlowResult, row: LensFlowRunRow, port: number) {
+  const keyByIndex = new Map(
+    (JSON.parse(row.steps_json) as StoredFlowStep[]).map((s) => [s.index, s.artifact_key] as const),
+  );
+  return {
+    run_id: row.id,
+    name: result.name,
+    status: result.status,
+    final_url: result.final_url,
+    // F074.99 — the same findings the native surface carries. A flat/cloud caller
+    // (a CI runner with no daemon) is the consumer LEAST able to go and look
+    // somewhere else, so leaving them off this shape would be the gap at its
+    // worst.
+    findings: parseFindingsJson(row.findings_json),
+    steps: result.steps.map((s) => ({
+      index: s.index,
+      action: s.action,
+      status: s.status,
+      ms: s.ms,
+      detail: s.detail ?? null,
+      resolved_via: s.resolved_via ?? null,
+      error: s.error ?? null,
+      screenshot_url: artifactUrl(port, keyByIndex.get(s.index) ?? null),
+    })),
+  };
+}
+
+/** Host the engine's runFlow for a flat cloud FlowRequest (F074.24). Validates
+ *  with the engine's OWN flowBodySchema (single-source contract), runs it (the
+ *  engine owns its Chromium + applies any supplied storageState), persists the
+ *  result as a daemon flow-run, and returns the engine's NATIVE cloud FlowResult
+ *  so the response shape converges with the request (storeform #16012). Dispatched
+ *  from the HTTP /lens/flow handler on shape (isFlatFlowBody); the MCP tool +
+ *  native {project, flow} callers stay on lensRunFlow (unchanged daemon shape). */
+export async function runFlatFlow(deps: LensDeps, input: FlatFlowInput) {
+  const project = typeof input.project === 'string' && input.project.trim() ? input.project.trim() : FLAT_FLOW_DEFAULT_PROJECT;
+  // `project` is OUR routing field, not part of the engine body — strip it before
+  // validating instead of relying on the schema to ignore it.
+  //
+  // @broberg/lens-engine 0.7.0 made flowBodySchema STRICT: it now rejects any
+  // unrecognized key, where 0.6.x silently stripped them. So this line was the
+  // difference between "cloud flows run" and "every cloud flow throws
+  // Unrecognized key(s) in object: 'project'". Caught by the suite on the bump,
+  // which is the whole reason the bump goes through a gate.
+  //
+  // Strict is the BETTER contract (a typo'd `base_ur1` is now an error instead of
+  // a silently ignored key), so we adapt rather than ask for a revert.
+  //
+  // AND IT WAS DOCUMENTED. My first version of this comment said the change was
+  // unflagged. It was not: the 0.7.0 README leads with "Read this before
+  // upgrading: a flow that parses today can stop parsing", names `project`
+  // explicitly, and gives `.extend()` as the supported path. I concluded
+  // "not flagged" from "I did not see a flag", without looking where flags live —
+  // the same shape as everything else this week, aimed at a peer this time.
+  // Verified against the published tarball after they corrected me (#21371).
+  const { project: _routing, ...engineBody } = input;
+  const parsed = flowBodySchema.safeParse(engineBody);
+  if (!parsed.success) {
+    throw new Error(`flat flow: ${parsed.error.issues[0]?.message ?? 'invalid flow body'}`);
+  }
+  const result = await engineRunFlow(parsed.data);
+  // Persist as a daemon flow-run (own /flow-runs listing + artifact storage)…
+  const row = await recordFlowRun(deps.db, deps.storage, project, mapEngineFlowResult(result));
+  // …but RETURN the engine's native cloud FlowResult (not the daemon step-shape).
+  return toCloudFlowResult(result, row, deps.port);
+}
+
+/** lens_run_flow — execute a flow end-to-end in one authed page, persist the
+ *  per-step report + screenshots, return the E2E result. F074.24: a flat cloud
+ *  FlowRequest is delegated to the engine's runFlow; the native {project, flow}
+ *  body keeps the daemon's own manuscript executor. */
+export async function lensRunFlow(deps: LensDeps, input: RunFlowInput) {
+  const project = requireProject(input.project);
+  const flow = parseFlow(input.flow);
+  // F082.6 — auth reaches flows: own auth (relative paths resolved) or inherit
+  // the manifest's. Fixes the blocker where authed routes redirected to login.
+  // F074.36 — and the run now REPORTS which of those two it used, or why neither.
+  const provenance = authProvenance(flow.auth, input.local_path, deps.sandboxRoots);
+  flow.auth = provenance.auth;
+  const result = await runFlow(flow, process.env as AuthEnv, {
+    from: input.from,
+    engine: input.engine,
+    ...resolveLocale(input, manifestLocale(input.local_path, deps.sandboxRoots)),
+    reducedMotion: input.reduced_motion,
+    viewport: coerceViewport(input.viewport, input.device),
+    critic: input.critic,
+    localPath: input.local_path, // F213.6 — sandbox root for uploadFile fixture paths
+    record: input.record === true, // F255.5 — opt-in .webm of the whole run
+    storage: coerceStorageSeed(input.storage), // F074.97 — seed saved client state
+  });
+  const row = await recordFlowRun(deps.db, deps.storage, project, result, provenance);
+  return flowRunView(row, deps.port);
+}
+
+export interface RunManuscriptInput {
+  project: string;
+  /** Markdown manuscript — compiled to a flow then executed. */
+  manuscript: string;
+  /** F074.36 — an explicit auth block, same shape lens_run_flow takes. The prose
+   *  manuscript is the surface we tell people to reach for first, and until now
+   *  it was the only one that could not authenticate — so the easiest tool was
+   *  the one that silently tested the login screen. Wins over the manifest. */
+  auth?: AuthConfig;
+  /** F082.6 — repo root for relative auth + manifest-auth inheritance. */
+  local_path?: string;
+  /** F252.2 — run the manuscript at a non-default viewport/device so mobile-only
+   *  UI (behind lg:hidden etc.) can be click-driven, not just DOM-asserted. */
+  viewport?: { width: number; height: number } | string;
+  /** F074.57 — locale/timezone for the manuscript run; wins over the manifest. */
+  locale?: string;
+  timezone?: string;
+  /** F074.59 — what this run reports for `prefers-reduced-motion`. Default
+   *  'reduce' (unchanged from every run before the option existed); pass
+   *  'no-preference' to let the run SEE motion. Never inherited from the
+   *  manifest: whether a run may animate is a property of the QUESTION being
+   *  asked, not of the project, and inheriting it would silently move baselines
+   *  for every capture in a repo that set it once. */
+  reduced_motion?: 'reduce' | 'no-preference';
+  device?: string;
+  engine?: LensEngine;
+  /** F255.5 — record the whole run to a .webm and return it as video_url. */
+  record?: boolean;
+  /** F074.97 — {local, session} seeded before the manuscript's first navigation.
+   *  The prose surface is the one we tell people to reach for first, so a
+   *  capability it lacks is a capability most callers do not have. */
+  storage?: unknown;
+}
+
+/** lens_run_manuscript — compile a markdown manuscript to a flow and run it E2E.
+ *  The authoring shortcut: a repo writes prose, not JSON. */
+export async function lensRunManuscript(deps: LensDeps, input: RunManuscriptInput) {
+  const project = requireProject(input.project);
+  if (typeof input.manuscript !== 'string' || !input.manuscript.trim()) {
+    throw new Error('manuscript (markdown string) is required');
+  }
+  const flow = compileManuscript(input.manuscript);
+  // F082.6 — a manuscript inherits the project's manifest auth (DRY: the
+  // credential lives in one place) unless it declared its own.
+  // F074.36 — an explicit `auth` argument outranks both, and the provenance is
+  // REPORTED: "we ran without a credential" must never be something the caller
+  // has to infer from a confusing failure.
+  const provenance = authProvenance(coerceAuth(input.auth) ?? flow.auth, input.local_path, deps.sandboxRoots);
+  flow.auth = provenance.auth;
+  const result = await runFlow(flow, process.env as AuthEnv, {
+    engine: input.engine,
+    ...resolveLocale(input, manifestLocale(input.local_path, deps.sandboxRoots)),
+    reducedMotion: input.reduced_motion,
+    viewport: coerceViewport(input.viewport, input.device), // F252.2 — mobile-only UI E2E in manuscripts
+    localPath: input.local_path, // F213.6 — uploadFile fixture root
+    record: input.record === true, // F255.5 — opt-in .webm of the whole run
+    storage: coerceStorageSeed(input.storage), // F074.97 — seed saved client state
+  });
+  const row = await recordFlowRun(deps.db, deps.storage, project, result, provenance);
+  return flowRunView(row, deps.port);
+}
+
+export interface ListFlowRunsInput {
+  project: string;
+  flow_name?: string;
+  status?: string;
+  limit?: number;
+}
+
+export function lensListFlowRuns(deps: LensDeps, input: ListFlowRunsInput) {
+  const project = requireProject(input.project);
+  const runs = listFlowRuns(deps.db, project, {
+    flow_name: input.flow_name,
+    status: input.status,
+    limit: input.limit,
+  });
+  return { project, count: runs.length, flow_runs: runs.map((r) => flowRunView(r, deps.port)) };
+}
+
+export function lensListBaselines(deps: LensDeps, project: string) {
+  const p = requireProject(project);
+  const baselines = listBaselines(deps.db, p);
+  return {
+    project: p,
+    count: baselines.length,
+    baselines: baselines.map((b) => ({
+      baseline_key: b.baseline_key,
+      width: b.width,
+      height: b.height,
+      approved_from_run_id: b.approved_from_run_id,
+      updated_at: b.updated_at,
+      current_version_id: b.current_version_id,
+      artifact_url: artifactUrl(deps.port, b.artifact_key),
+    })),
+  };
+}
+
+// F094.3 — the approved-version history for one surface (newest first), each with
+// a thumbnail URL, so the dashboard can render a visual timeline (F094.4).
+export function lensListBaselineVersions(
+  deps: LensDeps,
+  input: { project: string; baseline_key: string },
+) {
+  const p = requireProject(input.project);
+  if (!input.baseline_key) throw new Error('baseline_key is required');
+  const versions = listBaselineVersions(deps.db, p, input.baseline_key);
+  const current = listBaselines(deps.db, p).find((b) => b.baseline_key === input.baseline_key);
+  return {
+    project: p,
+    baseline_key: input.baseline_key,
+    current_version_id: current?.current_version_id ?? null,
+    count: versions.length,
+    versions: versions.map((v) => ({
+      version_no: v.version_no,
+      version_id: v.id,
+      width: v.width,
+      height: v.height,
+      approved_from_run_id: v.approved_from_run_id,
+      commit_sha: v.commit_sha,
+      note: v.note,
+      approved_at: v.approved_at,
+      is_current: v.id === current?.current_version_id,
+      artifact_url: artifactUrl(deps.port, v.artifact_key),
+    })),
+  };
+}
+
+// F094.3 — revert a surface's active baseline to a prior version (re-point, no
+// history loss). The next verify diffs against the reverted image.
+export function lensRevertBaseline(
+  deps: LensDeps,
+  input: { project: string; baseline_key: string; version_no: number },
+): LensBaselineRow & { artifact_url: string | null } {
+  const project = requireProject(input.project);
+  if (!input.baseline_key) throw new Error('baseline_key is required');
+  if (typeof input.version_no !== 'number') throw new Error('version_no (number) is required');
+  const baseline = revertBaseline(deps.db, project, input.baseline_key, input.version_no);
+  return { ...baseline, artifact_url: artifactUrl(deps.port, baseline.artifact_key) };
+}
+
+
+// ── F272.2 — promote a flow run's evidence into durable storage ──────────
+//
+// THE CLAIM THIS EXISTS TO MAKE TRUE: "the owner can open this with the daemon
+// off." A 127.0.0.1 artifact URL can never satisfy it, no matter how correct the
+// bytes are — it is reachable from exactly one machine, by exactly one person,
+// and only while a process happens to be up.
+//
+// The daemon does the copying itself, deliberately. It is the only process that
+// can read the PNGs, and having it POST them straight to the cloud means the
+// bytes never pass through an agent's context — which is both the token-frugal
+// choice and the one that keeps a screenshot of a customer's screen out of a
+// transcript.
+
+export interface PromoteEvidenceInput {
+  project: string;
+  /** A flow run (lens_run_flow). Exactly one of flow_run_id / run_id. */
+  flow_run_id?: string;
+  /** F074.68 — a plain CAPTURE run (lens_capture / lens_verify). Until this
+   *  existed, the durable-evidence path we RECOMMEND could not be taken for a
+   *  screenshot: the warning told people to promote, and promote refused the id
+   *  they had. sanne cited six captures as proof for acceptance criteria and none
+   *  was promotable, so a correct action still read as `local_only` — which is
+   *  how a warning teaches people to ignore it. */
+  run_id?: string;
+  /** Only steps whose screenshot exists are promoted; pass a subset to promote
+   *  fewer. Omitted = every step that has one. Flow runs only. */
+  step_indexes?: number[];
+}
+
+export interface PromotedStep {
+  index: number;
+  label: string;
+  /** F074.68 — WHAT this artifact is. A capture run can carry two pictures, and
+   *  "2 promoted" does not say whether the second is the diff or a second screen.
+   *  Named rather than counted, so a caller never has to infer it. */
+  kind: 'step' | 'screenshot' | 'diff';
+  status: string;
+  artifact_id: string;
+  url: string;
+}
+
+export interface PromoteEvidenceResult {
+  /** Whichever kind of run was promoted; the other is null. */
+  flow_run_id: string | null;
+  run_id: string | null;
+  project: string;
+  /** What the run's backend was BEFORE this call — the reason it needed promoting. */
+  was: 'local' | 'tigris' | null;
+  promoted: PromotedStep[];
+  /** Steps that had no screenshot at all. Reported, never silently dropped: with
+   *  today's 12% capture rate (F272.3) this is the majority, and a caller that is
+   *  not told will read "3 promoted" as "the whole run is keepable". */
+  steps_without_screenshot: number;
+  /** The line to paste as AC evidence. Server-verifiable — cardmem_record_review
+   *  looks these ids up rather than believing a claim about them. */
+  evidence: string;
+}
+
+export async function promoteEvidence(
+  deps: LensDeps,
+  input: PromoteEvidenceInput,
+): Promise<PromoteEvidenceResult> {
+  // Exactly one id. Accepting both and silently preferring one is how a caller
+  // ends up promoting a run they did not mean; refusing says which they gave.
+  if (!!input.flow_run_id === !!input.run_id) {
+    throw new Error(
+      'pass exactly ONE of flow_run_id (a lens_run_flow run) or run_id (a lens_capture / lens_verify run)' +
+        (input.flow_run_id ? ' — both were given' : ' — neither was given'),
+    );
+  }
+
+  const cloud = deps.cloud?.();
+  if (!cloud) {
+    throw new Error(
+      'not signed in to cardmem — promoting evidence needs the daemon\'s cloud key (run `cardmem login`). Nothing was copied.',
+    );
+  }
+
+  // Resolve the cloud project id LAZILY. The daemon knows slugs; place_artifact
+  // needs the uuid, and guessing one would write into whatever project happened to
+  // match. Deferred until there is actually something to place, so the LOCAL "that
+  // run is not in this project" answer still comes first — resolving eagerly made
+  // an unknown project report "not known to cardmem" instead, which is true but is
+  // not the reason the caller's request failed. It also spares a network call for
+  // a run that turns out to have no screenshot at all.
+  let projectIdCache: string | null = null;
+  const projectId = async () => {
+    if (projectIdCache) return projectIdCache;
+    const projects = await cloud.callTool<{ projects?: Array<{ id: string; slug: string }> }>(
+      'cardmem_list_projects',
+      {},
+    );
+    const id = projects?.projects?.find((p) => p.slug === input.project)?.id;
+    if (!id) throw new Error(`project ${input.project} is not known to cardmem — cannot place artifacts`);
+    projectIdCache = id;
+    return id;
+  };
+
+  /** Read the bytes and hand them to the cloud. The daemon copies them itself, so a
+   *  screenshot of a customer's screen never passes through an agent's context. */
+  const place = async (key: string, name: string, whose: string) => {
+    // Project first, bytes second — the order the tests pin, and the right one: an
+    // unknown project is a mistake in the REQUEST, while missing bytes are a fact
+    // about the world. Report the caller's error before the world's.
+    const target = await projectId();
+    const bytes = await deps.storage.get(key);
+    if (!bytes) {
+      // The row says there is a picture and the storage does not have it. That is
+      // the exact silent loss this mechanism exists to prevent, so it is a real
+      // failure rather than a quiet omission.
+      throw new Error(
+        `${whose} claims a screenshot (${key}) but the bytes are GONE from ${deps.storage.backend} storage — the evidence this run cites no longer exists.`,
+      );
+    }
+    return cloud.callTool<{ artifact_id: string; url: string }>('cardmem_place_artifact', {
+      project_id: target,
+      name,
+      mime: 'image/png',
+      base64: bytes.toString('base64'),
+      source: 'lens-evidence',
+    });
+  };
+
+  const promoted: PromotedStep[] = [];
+  let withoutShot = 0;
+
+  // ── a plain CAPTURE run (F074.68) ────────────────────────────────────────
+  if (input.run_id) {
+    const run = deps.db
+      .query('SELECT * FROM lens_runs WHERE id = ? AND project_slug = ?')
+      .get(input.run_id, input.project) as LensRunRow | undefined;
+    // Scoped by project on purpose: a run id under a DIFFERENT project is not this
+    // project's evidence, and "not found" is the honest answer.
+    if (!run) throw new Error(`capture run ${input.run_id} not found in project ${input.project}`);
+
+    const stem = `lens-${run.surface_key || run.mode}-${input.run_id.slice(0, 8)}`;
+    // BOTH pictures when both exist, each NAMED. A diff is evidence of a different
+    // claim than the screenshot is, and promoting one silently while counting two
+    // is the ambiguity this card was told to decide rather than leave open.
+    if (run.artifact_key) {
+      const placed = await place(run.artifact_key, `${stem}.png`, `run ${input.run_id}`);
+      // Named fields, NOT `...placed`. The cloud's place_artifact response carries its
+      // own `kind` ("image"), and spreading it last silently overwrote ours — the
+      // stub in the test returns only {artifact_id,url}, so it could not see that.
+      // Measured live: the very first real promote came back kind:"image" while every
+      // test said "screenshot".
+      promoted.push({
+        index: 0, label: 'screenshot', kind: 'screenshot', status: run.status,
+        artifact_id: placed.artifact_id, url: placed.url,
+      });
+    } else {
+      withoutShot++;
+    }
+    if (run.diff_artifact_key) {
+      const placed = await place(run.diff_artifact_key, `${stem}-diff.png`, `run ${input.run_id} (diff)`);
+      promoted.push({
+        index: 1, label: 'diff', kind: 'diff', status: run.status,
+        artifact_id: placed.artifact_id, url: placed.url,
+      });
+    }
+
+    const evidence =
+      promoted.length === 0
+        ? `Lens capture run ${input.run_id} (${run.surface_key || run.mode}): NOTHING PROMOTED — this run stored no screenshot, so there is no pictorial evidence for it.`
+        : `Lens capture run ${input.run_id} (${run.surface_key || run.mode}, ${run.status}) — ${promoted
+            .map((p) => p.label)
+            .join(' + ')} promoted to durable storage: ${promoted.map((p) => p.url).join(' ')}`;
+
+    return {
+      flow_run_id: null,
+      run_id: input.run_id,
+      project: input.project,
+      // lens_runs carries no artifact_backend column, so this is genuinely unknown
+      // rather than 'local' — saying 'local' would be a guess dressed as a reading.
+      was: null,
+      promoted,
+      steps_without_screenshot: withoutShot,
+      evidence,
+    };
+  }
+
+  // ── a FLOW run ───────────────────────────────────────────────────────────
+  const row = deps.db
+    .query('SELECT * FROM lens_flow_runs WHERE id = ? AND project_slug = ?')
+    .get(input.flow_run_id!, input.project) as LensFlowRunRow | undefined;
+  if (!row) {
+    throw new Error(`flow run ${input.flow_run_id} not found in project ${input.project}`);
+  }
+
+  const steps = JSON.parse(row.steps_json) as StoredFlowStep[];
+  const wanted = input.step_indexes ? new Set(input.step_indexes) : null;
+
+  for (const step of steps) {
+    if (wanted && !wanted.has(step.index)) continue;
+    if (!step.artifact_key) {
+      withoutShot++;
+      continue;
+    }
+    const name = `lens-${row.flow_name}-${input.flow_run_id!.slice(0, 8)}-step-${String(step.index).padStart(2, '0')}.png`;
+    const placed = await place(step.artifact_key, name, `step ${step.index} of ${input.flow_run_id}`);
+    promoted.push({
+      index: step.index,
+      label: step.label,
+      kind: 'step',
+      status: step.status,
+      artifact_id: placed.artifact_id,
+      url: placed.url,
+    });
+  }
+
+  const evidence =
+    promoted.length === 0
+      ? `Lens flow run ${input.flow_run_id} (${row.flow_name}): NOTHING PROMOTED — none of the ${steps.length} steps stored a screenshot. There is no pictorial evidence for this run.`
+      : `Lens flow run ${input.flow_run_id} (${row.flow_name}, ${row.status}) — ${promoted.length} step still(s) promoted to durable storage: ${promoted
+          .map((p) => p.url)
+          .join(' ')}`;
+
+  return {
+    flow_run_id: input.flow_run_id!,
+    run_id: null,
+    project: input.project,
+    was: (row.artifact_backend as 'local' | 'tigris' | null) ?? null,
+    promoted,
+    steps_without_screenshot: withoutShot,
+    evidence,
+  };
+}
+
+/** @deprecated F074.68 — kept so nothing breaks mid-rename; promoteEvidence now
+ *  takes a capture run too, and the old name says it does not. */
+export const promoteFlowEvidence = promoteEvidence;
+
+// ─── F074.63 — lens_export ────────────────────────────────────────────────────
+
+export interface ExportInput {
+  project: string;
+  url: string;
+  format?: 'pdf' | 'svg';
+  page_size?: string;
+  landscape?: boolean;
+  print_background?: boolean;
+  margin?: { top?: string; right?: string; bottom?: string; left?: string };
+  media?: ExportMedia;
+  /** F074.64 — which surface to export; a print job is one sheet. */
+  /** F074.64 — which surface to export; a print job is ONE sheet and a mockup
+   *  document usually holds several. */
+  selector?: string;
+  /** Which match when the selector hits several — a bifold folder has two sheets
+   *  under one class. Default 0. */
+  selector_index?: number;
+  engine?: LensEngine;
+  viewport?: { width: number; height: number } | string;
+  device?: string;
+  scale?: number;
+  waitUntil?: 'load' | 'domcontentloaded' | 'commit';
+  waitFor?: string | number;
+  actions?: CaptureAction[];
+  auth?: AuthConfig;
+  timeout_ms?: number;
+  /** Strings the caller expects to find AS TEXT in the produced PDF. Checked
+   *  server-side and answered as booleans — the extracted text itself is never
+   *  returned, because a poster's worth of it is thousands of tokens the caller
+   *  did not ask for and cannot use. */
+  expect_text?: string[];
+}
+
+/** lens_export — render a URL to a VECTOR document, where text stays text.
+ *
+ *  The verdict block is the point of the whole tool, so it is computed from the
+ *  produced bytes and returned every time rather than left to the caller to
+ *  check. fd-sundhed's existing broken artifact is a valid PDF with a valid MIME
+ *  type; the only thing that separates it from a usable one is whether a
+ *  designer can select the text. So that is what the response reports. */
+export async function lensExport(deps: LensDeps, input: ExportInput) {
+  const project = requireProject(input.project);
+  const format = input.format ?? 'pdf';
+  if (format !== 'pdf' && format !== 'svg') {
+    throw new Error(`lens_export supports format:'pdf' or 'svg'. Got '${format}'.`);
+  }
+
+  const result = await exportPage({
+    url: input.url,
+    engine: input.engine,
+    viewport: coerceViewport(input.viewport, input.device),
+    deviceScaleFactor: input.scale == null ? undefined : Number(input.scale) || undefined,
+    waitUntil: input.waitUntil,
+    waitFor: input.waitFor,
+    actions: input.actions,
+    auth: resolveVerifyAuth(deps, project, input.auth),
+    timeoutMs: input.timeout_ms,
+    format,
+    pageSize: input.page_size,
+    landscape: input.landscape,
+    printBackground: input.print_background,
+    margin: input.margin,
+    media: input.media,
+    selector: input.selector,
+    selectorIndex: input.selector_index,
+  });
+
+  // "We wrote bytes" and "we wrote the format we promised" are different claims;
+  // only one of them is worth reporting to someone with a print deadline.
+  if (format === 'pdf' && !looksLikePdf(result.bytes)) {
+    throw new Error('lens_export produced bytes that are not a PDF (missing %PDF- header)');
+  }
+  if (format === 'svg' && !result.bytes.subarray(0, 200).toString('utf8').includes('<svg')) {
+    throw new Error('lens_export produced bytes that are not an SVG (no <svg root)');
+  }
+
+  const exportId = randomUUID();
+  const key = artifactKeys.exportDoc(project, exportId, format);
+  await deps.storage.put(key, result.bytes, format === 'svg' ? 'image/svg+xml' : 'application/pdf');
+
+  const stats = format === 'pdf' ? pdfContentStats(result.bytes) : null;
+  const box = format === 'pdf' ? readMediaBox(result.bytes) : null;
+  // Answered here, on the bytes, rather than by handing back the whole text:
+  // the caller wants to know whether their headline survived, not to read the
+  // document back through their own context.
+  const expected = Array.isArray(input.expect_text) ? input.expect_text.filter((t) => typeof t === 'string') : [];
+  const svgText = format === 'svg' ? result.bytes.toString('utf8').replace(/<[^>]+>/g, ' ') : '';
+  // F074.67 — HOW each phrase matched, not just whether. A phrase the page drew
+  // with different capitalisation than the caller wrote is FOUND (that is what
+  // was asked) but the difference is reported, because it is almost always
+  // `text-transform` in the stylesheet and the caller should see that the page
+  // says something other than their source does.
+  const matches = expected.map((t) => [t, matchPhrase(stats ?? svgText, t)] as const);
+  const textFound = Object.fromEntries(matches.map(([t, m]) => [t, m !== 'absent']));
+  const casingDiffers = matches.filter(([, m]) => m === 'case-insensitive').map(([t]) => t);
+  // F074.65 — a `false` here had TWO meanings and no way to tell them apart.
+  //
+  // Measured on the committed fixture: `expect_text` answered false for a phrase
+  // that IS on the page (drawn in a Type 3 font we could not decode) and false
+  // for a phrase in no document at all. Identical answers, opposite fixes — one
+  // says "your headline is missing", the other says "your headline became
+  // outlines". A caller acting on the first would go looking for a layout bug
+  // that does not exist.
+  //
+  // So when this document dropped text, the misses are named as UNVERIFIABLE
+  // rather than reported as absences. THE HONEST LIMIT, stated rather than
+  // papered over: within one document that dropped runs we cannot separate the
+  // two, so every miss is listed. Across documents we can — a file with nothing
+  // dropped lists nothing, which is what keeps this from degrading into "every
+  // miss is probably outlines".
+  const unreadable = stats && stats.undecodedRuns > 0
+    ? expected.filter((t) => !textFound[t])
+    : [];
+
+  return {
+    export_id: exportId,
+    project,
+    url: input.url,
+    final_url: result.finalUrl,
+    title: result.title,
+    format,
+    export_url: artifactUrl(deps.port, key),
+    artifact_key: key,
+    bytes: result.bytes.length,
+    page_size: result.pageSize,
+    landscape: result.landscape,
+    media: result.media,
+    print_background: result.printBackground,
+    // null = NOT MEASURED, never a plausible default: an assertion on page
+    // geometry must not pass on a PDF whose geometry was never read.
+    page_mm: box
+      ? { width: Number(ptToMm(box.widthPt).toFixed(1)), height: Number(ptToMm(box.heightPt).toFixed(1)) }
+      : null,
+    // The verdict a graphic designer actually cares about.
+    editable_text: stats ? isVectorText(stats) : (result.svg?.counts.text ?? 0) > 0,
+    // Counts only. Extracted text is deliberately never returned — see
+    // expect_text above.
+    content: stats
+      ? {
+          textRuns: stats.textRuns,
+          fonts: stats.fonts,
+          images: stats.images,
+          undecodableStreams: stats.undecodableStreams,
+          // F074.65 — runs whose characters we dropped. Separate from
+          // undecodableStreams (inflate failures) on purpose: merging them is how
+          // a lost line was reported as 0 problems.
+          undecodedRuns: stats.undecodedRuns,
+          textChars: stats.text.length,
+        }
+      : result.svg?.counts ?? null,
+    // F074.65 — the verdict a designer can ACT on. Present only when the page is
+    // drawn with outline fonts, so its absence is the good case rather than a
+    // field nobody reads.
+    ...(stats && outlineFontNames(stats).length > 0
+      ? {
+          outline_fonts: {
+            families: outlineFontNames(stats),
+            cause:
+              'Chromium cannot subset a VARIABLE font into a PDF font program, so it draws every ' +
+              'glyph as a Type 3 procedure. The document prints correctly and opens in Illustrator ' +
+              'as paths — the text can be moved but never re-typed.',
+            remedy:
+              'Serve STATIC instances of these families instead of the variable font files ' +
+              '(fontTools\' instancer produces them). Note that macOS system-ui / -apple-system is ' +
+              'a variable font, so Tailwind\'s default --font-sans stack lands here by default. ' +
+              'Or export format:\'svg\', which writes the font family by NAME and stays editable.',
+          },
+        }
+      : {}),
+    // F074.64 — what the SVG could NOT represent, named rather than approximated.
+    // An export that silently omits an element looks complete and is not.
+    ...(result.svg ? { unsupported: result.svg.unsupported } : {}),
+    ...(expected.length > 0 ? { text_found: textFound } : {}),
+    // A miss we cannot vouch for. Empty (and absent) whenever the document read
+    // cleanly, so a plain `false` keeps meaning "not on the page".
+    ...(unreadable.length > 0 ? { text_found_unverifiable: unreadable } : {}),
+    // F074.67 — found, but the page painted it in different capitals than the
+    // caller typed. Named rather than folded into a bare `true`: the difference
+    // is real and is nearly always a `text-transform` rule.
+    ...(casingDiffers.length > 0 ? { text_found_casing_differs: casingDiffers } : {}),
+    page_errors: result.pageErrors,
+    duration_ms: result.durationMs,
+  };
+}