@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/onboard/steps/deploysh.ts

@@ -0,0 +1,105 @@
+// scripts/deploy.sh, as the wizard invokes it.
+//
+// The guided path IS the manual path. This module is deliberately tiny and
+// deliberately dumb: it builds the argv for the SAME script the deploying
+// skill documents, and it does nothing else. In particular it passes:
+//
+//   * no flag that skips a check — there is no such flag, and there must
+//     never be a reason to add one;
+//   * no environment override — the real StreamRunner spawns with the
+//     inherited environment and this builder has nowhere to put a `QC_*` var,
+//     so the wizard structurally cannot point the script at a different
+//     inventory, a different config or a different sandbox than the operator's
+//     own `scripts/deploy.sh` would use. The defaults it computes are exactly
+//     the ones the manual path gets: the install locator's config
+//     (`$QCR_CONFIG`, else the config home's config.toml — never the
+//     checkout's) and deploy/ansible/inventory.ini in the checkout.
+//
+// Every refusal therefore lands unchanged on the guided route: a dirty working
+// tree, a pi/OpenViking pin mismatch (all five mirrors), the "PIN-ME"
+// placeholder, a missing inventory or ansible-playbook, the disk and port
+// preflights inside the playbook itself, and the drain advisory that warns
+// when rounds are still running. The wizard's job is to run it and show what
+// it said — never to soften it.
+import { join } from "node:path";
+import { CHOICE_KEYS } from "../choices.js";
+import { sshAliasOf } from "./topology.js";
+
+/** `provision` installs the host (packages, Docker, secrets, the updater) and
+ * ships no image; `release <version>` is the deploy (CI built the image once
+ * from the release tag; the VM pulls it by digest); `verify` asks what runs.
+ * `sync` and `rebuild` are gone from the script — it refuses them. */
+export type DeployMode = "provision" | "release" | "verify";
+
+/** The version spelling deploy.sh accepts: X.Y.Z, optionally -prerelease. It
+ * names an image tag, so nothing else gets near the argv. */
+export const RELEASE_VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$/;
+
+/** A typed version -> the spelling deploy.sh takes (a leading `v` is the git
+ * tag's, not the version's), or null. */
+export function releaseVersionOf(raw: unknown): string | null {
+  const v = String(raw ?? "")
+    .trim()
+    .replace(/^v(?=\d)/, "");
+  return RELEASE_VERSION_RE.test(v) ? v : null;
+}
+
+/** The release version recorded by the last successful deploy, or null. */
+export function recordedReleaseVersion(choices: Readonly<Record<string, unknown>>): string | null {
+  const rec = choices[CHOICE_KEYS.vmDeployed];
+  if (typeof rec !== "object" || rec === null) return null;
+  // A record is the target host's own: one written for another alias is no
+  // version to ship to the host the topology names now.
+  if ((rec as Record<string, unknown>).host !== sshAliasOf(choices)) return null;
+  return releaseVersionOf((rec as Record<string, unknown>).version);
+}
+
+/** Match the deploy script's inherited inventory overrides without changing them. */
+export function effectiveInventoryPath(root: string, env: NodeJS.ProcessEnv = process.env): string {
+  return (
+    env.QC_INVENTORY || join(env.QC_ANSIBLE_DIR || join(root, "deploy", "ansible"), "inventory.ini")
+  );
+}
+
+export const DEPLOY_SCRIPT_REL = "scripts/deploy.sh";
+
+export function deployScriptPath(root: string): string {
+  return join(root, DEPLOY_SCRIPT_REL);
+}
+
+export interface DeployArgvOptions {
+  dryRun?: boolean;
+  /** Required by `release`, refused by every other mode. */
+  version?: string;
+  /** `release` only: the CI deploy manifest, when it is not the default
+   * `./deploy-manifest-<version>.json`. */
+  manifest?: string;
+}
+
+function words(mode: DeployMode, opts: DeployArgvOptions): string[] {
+  if (mode === "release") {
+    if (opts.version === undefined || !RELEASE_VERSION_RE.test(opts.version))
+      throw new Error(
+        `deploy.sh release needs a version (X.Y.Z), got ${JSON.stringify(opts.version)}`,
+      );
+    return [
+      ...(opts.dryRun ? ["--dry-run"] : []),
+      "release",
+      opts.version,
+      ...(opts.manifest ? ["--manifest", opts.manifest] : []),
+    ];
+  }
+  if (opts.version !== undefined || opts.manifest !== undefined)
+    throw new Error(`deploy.sh ${mode} takes no version or manifest`);
+  return [...(opts.dryRun ? ["--dry-run"] : []), mode];
+}
+
+/** `<root>/scripts/deploy.sh [--dry-run] release <version> | provision | verify`. */
+export function deployArgv(root: string, mode: DeployMode, opts: DeployArgvOptions = {}): string[] {
+  return [deployScriptPath(root), ...words(mode, opts)];
+}
+
+/** How the same invocation reads when the operator types it themselves. */
+export function deployCommandLine(mode: DeployMode, opts: DeployArgvOptions = {}): string {
+  return deployArgv("", mode, opts).join(" ");
+}

package/src/onboard/steps/embeddings.ts

@@ -0,0 +1,550 @@
+// The embedder step — where memory's vectors are computed, and the only
+// place a new operator is asked about it.
+//
+// Why it is a step: the shipped default is the local embedder — a small
+// English model served on loopback inside the daemon container — so nothing
+// but the model call leaves the machine, memory text included. That default
+// needs no answer and no key, which is exactly why the step exists: an
+// operator who WANTS hosted embeddings must say so, in one place, and the
+// whole installation then moves together — config.toml, the credential file, and (through the bring-up or
+// inventory step) the environment the boot actually renders. Half of that is
+// the failure this step makes impossible: a config that says "openai" over a
+// boot that renders "local" is a vector-store reset on the next start.
+//
+// The credential is its own file: `openai_api_key` is pi's model credential
+// and is never read for embeddings; the hosted opt-in reads
+// `<secrets>/<embedding_key_file>` (default `openai_embeddings_api_key`).
+// Either can be set without the other. The wizard never accepts the value
+// through the pi session (it would land in a transcript) — it points at
+// `deploy/collect-secrets.sh`, which reads it hidden and writes it 0600.
+//
+// Deterministic by construction: config and secrets are plain files under
+// paths derived from the injected state dir; verify() neither prompts nor
+// writes.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import {
+  EMBEDDING_PROVIDERS,
+  HOSTED_EMBEDDING,
+  LOCAL_EMBEDDING,
+  OPENVIKING_DEFAULTS,
+  parseConfig,
+  ovConfEmbedder,
+  parseOpenViking,
+  type EmbeddingProvider,
+  type OpenVikingConfig,
+} from "../../config.js";
+import type { CheckResult, OnboardingStep, StepContext, StepReport } from "../engine.js";
+import {
+  interviewConfigPath,
+  readTextOrNull,
+  readEnvText,
+  rootOf,
+  secretsDirFor,
+  writeAtomic,
+} from "./compose.js";
+import { assertNoDryRunEdit, patchToml, tomlString, type TomlEdit } from "./configfill.js";
+import { validateOpenAiKey } from "./llmauth.js";
+import { stackTransportFor } from "./transport.js";
+import { vmInventoryStep } from "./inventory.js";
+import { vmDeployStep } from "./vmdeploy.js";
+import { readTomlKey, readEnvKey } from "./ingress.js";
+import { topologyOf } from "./topology.js";
+
+export const EMBEDDINGS_STEP_ID = "embeddings";
+
+/** The embedder config.toml declares — what the bring-up step writes into the
+ * project `.env` and the inventory step writes as host vars. */
+export interface DeclaredEmbedder {
+  provider: string;
+  model: string;
+  dimension: number;
+  keyFile: string;
+}
+
+/** The loader's own reading of a config text's `[openviking]` block —
+ * defaults filled, `1_536` read as 1536, a hosted opt-in that omits its
+ * model/dimension given the HOSTED defaults — or null when the text does not
+ * parse or the loader refuses the block. */
+function loaderOpenViking(configText: string): OpenVikingConfig | null {
+  try {
+    const doc = parseToml(configText) as Record<string, unknown>;
+    const block = doc.openviking;
+    return parseOpenViking(
+      typeof block === "object" && block !== null && !Array.isArray(block)
+        ? (block as Record<string, unknown>)
+        : {},
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** The embedder an `[openviking]` block declares. */
+export function embedderOf(ov: OpenVikingConfig): DeclaredEmbedder {
+  return {
+    provider: ov.embedding_provider,
+    model: ov.embedding_model,
+    dimension: ov.embedding_dimension,
+    keyFile: ov.embedding_key_file,
+  };
+}
+
+/**
+ * Read `[openviking] embedding_*` out of a config.toml text, defaults filled
+ * exactly as the loader fills them — so a config that omits the block (an
+ * older one, or a hand-trimmed one) is read as the shipped local default and
+ * not as "unknown".
+ */
+export function declaredEmbedderOf(configText: string): DeclaredEmbedder {
+  // The loader's own reading first, which is exactly what the daemon will
+  // run. Only a text that does not parse (or a block the loader refuses)
+  // falls back to the tolerant line reader below.
+  const ov = loaderOpenViking(configText);
+  if (ov !== null) return embedderOf(ov);
+  const get = (key: string): string | null =>
+    readTomlKey(configText, "openviking", key)?.trim() ?? null;
+  const dimensionRaw = get("embedding_dimension");
+  return {
+    provider: get("embedding_provider") ?? OPENVIKING_DEFAULTS.embedding_provider,
+    model: get("embedding_model") ?? OPENVIKING_DEFAULTS.embedding_model,
+    dimension:
+      dimensionRaw !== null && /^[0-9]+$/.test(dimensionRaw)
+        ? Number(dimensionRaw)
+        : OPENVIKING_DEFAULTS.embedding_dimension,
+    keyFile: get("embedding_key_file") ?? OPENVIKING_DEFAULTS.embedding_key_file,
+  };
+}
+
+const EMBEDDER_FIELDS = [
+  {
+    key: "provider",
+    suffix: "EMBEDDING_PROVIDER",
+    fallback: OPENVIKING_DEFAULTS.embedding_provider,
+  },
+  { key: "model", suffix: "EMBEDDING_MODEL", fallback: OPENVIKING_DEFAULTS.embedding_model },
+  {
+    key: "dimension",
+    suffix: "EMBEDDING_DIMENSION",
+    fallback: OPENVIKING_DEFAULTS.embedding_dimension,
+  },
+  {
+    key: "keyFile",
+    suffix: "EMBEDDING_KEY_FILE",
+    fallback: OPENVIKING_DEFAULTS.embedding_key_file,
+  },
+] as const;
+const LOCAL_EMBEDDER_FIELDS = [
+  { key: "port", suffix: "LOCAL_EMBEDDER_PORT", fallback: OPENVIKING_DEFAULTS.local_embedder_port },
+  {
+    key: "threads",
+    suffix: "LOCAL_EMBEDDER_THREADS",
+    fallback: OPENVIKING_DEFAULTS.local_embedder_threads,
+  },
+] as const;
+
+/** Every embedder host field, with the deploy's tracked fallback value. */
+export const EMBEDDER_HOST_DEFAULTS: Readonly<Record<string, string>> = Object.fromEntries(
+  [...EMBEDDER_FIELDS, ...LOCAL_EMBEDDER_FIELDS].map((field) => [
+    `openviking_${field.suffix.toLowerCase()}`,
+    String(field.fallback),
+  ]),
+);
+
+/** The four `.env` keys docker-compose.yml passes into the daemon container. */
+export function embedderEnvEntries(e: DeclaredEmbedder): Array<[string, string]> {
+  return EMBEDDER_FIELDS.map((field) => [`QCR_OPENVIKING_${field.suffix}`, String(e[field.key])]);
+}
+
+/**
+ * The local embedder's two runtime knobs as `.env` keys:
+ * docker-compose.yml passes them to the entrypoint, which renders ov.conf's
+ * `api_base` and runs the provisioning embedder on that port — while the
+ * daemon reads the same two from config.toml. Mirrored on every bring-up so
+ * they cannot disagree: a port the two disagree on is a search nothing serves.
+ * The loader's own reading of the block; a config it cannot read gives the
+ * shipped defaults, exactly as the daemon would refuse to start on it.
+ */
+export function localEmbedderEnvEntries(configText: string): Array<[string, string]> {
+  const runtime = localEmbedderRuntimeOf(configText);
+  return LOCAL_EMBEDDER_FIELDS.map((field) => [
+    `QCR_OPENVIKING_${field.suffix}`,
+    String(runtime[field.key]),
+  ]);
+}
+
+/** The local embedder's two runtime knobs. */
+export interface LocalEmbedderRuntime {
+  port: number;
+  threads: number;
+}
+
+/** The loader's own reading of the local embedder's port and threads; a
+ * config it cannot read gives the shipped defaults, exactly as the daemon
+ * would refuse to start on it. */
+export function localEmbedderRuntimeOf(configText: string): LocalEmbedderRuntime {
+  const ov = loaderOpenViking(configText);
+  return {
+    port: ov?.local_embedder_port ?? OPENVIKING_DEFAULTS.local_embedder_port,
+    threads: ov?.local_embedder_threads ?? OPENVIKING_DEFAULTS.local_embedder_threads,
+  };
+}
+
+/** The inventory HOST VARS for local embedder knobs that differ from the
+ * shipped defaults (which the tracked group_vars carry) — scripts/deploy.sh
+ * refuses a config.toml whose port or threads the deploy would not render. */
+export function localEmbedderHostVars(rt: LocalEmbedderRuntime): Array<[string, string]> {
+  return LOCAL_EMBEDDER_FIELDS.filter((field) => rt[field.key] !== field.fallback).map((field) => [
+    `openviking_${field.suffix.toLowerCase()}`,
+    String(rt[field.key]),
+  ]);
+}
+
+/** The inventory HOST VARS for a hosted opt-in — nothing for the local
+ * default, which the tracked group_vars already carry. */
+export function embedderHostVars(e: DeclaredEmbedder): Array<[string, string]> {
+  return EMBEDDER_FIELDS.filter(
+    (field) => e.provider !== "local" || String(e[field.key]) !== String(field.fallback),
+  ).map((field) => [`openviking_${field.suffix.toLowerCase()}`, String(e[field.key])]);
+}
+
+export function describeEmbedder(e: {
+  provider: string;
+  model: string;
+  dimension: number;
+}): string {
+  return `${e.provider}/${e.model} (${e.dimension} dims)`;
+}
+
+const LOCAL_SENTENCE =
+  "memory embeds LOCALLY, inside the memory container — no memory text leaves the machine, and nothing but the model call does. " +
+  "No key is needed and none is read";
+const HOSTED_SENTENCE =
+  "memory embeds through OpenAI's hosted embeddings endpoint: EVERY memory entry's text, and every search query, is sent there. " +
+  "You chose this; the shipped default is local";
+
+/** The credential check for the hosted opt-in — pi's key never counts. */
+export function keyFileCheck(secretsDir: string, keyFile: string): CheckResult {
+  const path = join(secretsDir, keyFile);
+  const value = readTextOrNull(path)?.trim() ?? "";
+  if (validateOpenAiKey(value)) {
+    return {
+      name: "embeddings-key",
+      ok: true,
+      detail: `${path} is present (0600 by the wizard) — the memory engine reads it, and only it, for embeddings`,
+    };
+  }
+  const pi = existsSync(join(secretsDir, "openai_api_key"))
+    ? " pi's openai_api_key is there, but it is pi's model credential and is deliberately NOT used for embeddings."
+    : "";
+  return {
+    name: "embeddings-key",
+    ok: false,
+    detail:
+      (value === ""
+        ? `no ${keyFile} in ${secretsDir}.`
+        : `${path} exists but does not look like an OpenAI key.`) +
+      pi +
+      ` Without it the memory engine refuses to start (memory degrades; the embedder is never switched silently). Fix: in another terminal, ` +
+      `\`bash deploy/collect-secrets.sh\` and paste the key at the ${OPENVIKING_DEFAULTS.embedding_key_file} prompt` +
+      (keyFile === OPENVIKING_DEFAULTS.embedding_key_file
+        ? ""
+        : `; then securely copy ${join(secretsDir, OPENVIKING_DEFAULTS.embedding_key_file)} to ${path}, keeping mode 0600`) +
+      " (never through this session — it would land in a transcript), then run this step again",
+  };
+}
+
+function propagationNote(ctx: StepContext): CheckResult {
+  const vm = topologyOf(ctx.choices) === "vm";
+  return {
+    name: "propagation",
+    ok: true,
+    detail: vm
+      ? "the inventory step (68) writes these as HOST VARS on your inventory line, which is what the deploy renders. Run it again, including when switching back to local; scripts/deploy.sh refuses to deploy if config.toml and those values disagree"
+      : "the bring-up step (70) writes these into the project .env, which docker-compose.yml passes into the container",
+  };
+}
+
+const MIGRATION_NOTE: CheckResult = {
+  name: "existing-store",
+  ok: true,
+  detail:
+    "if this installation already holds memory embedded under a DIFFERENT embedder, the next boot moves the old vectors aside " +
+    "(kept, never deleted) and the daemon re-embeds reviewer memory through the server once it is ready; the companion's namespace " +
+    "is yours to rebuild from this machine with `qcr memory reembed`. The memory TEXT is never touched. docs/memory-embeddings.md has the whole shape",
+};
+
+/** Compare the compose inputs to the config the daemon loads, including shipped defaults. */
+export function embedderInputsCheck(configText: string, envText: string): CheckResult {
+  const expected = [
+    ...embedderEnvEntries(declaredEmbedderOf(configText)),
+    ...localEmbedderEnvEntries(configText),
+  ];
+  const defaults = Object.fromEntries([
+    ...embedderEnvEntries(declaredEmbedderOf("")),
+    ...localEmbedderEnvEntries(""),
+  ]);
+  const changed = expected
+    .filter(([key, value]) => (readEnvKey(envText, key) ?? defaults[key]) !== value)
+    .map(([key]) => key);
+  return {
+    name: "embedder",
+    ok: changed.length === 0,
+    detail: changed.length
+      ? `.env no longer renders config.toml's embedder (${changed.join(", ")}) — run the bring-up step again`
+      : "the environment renders the embedder config.toml declares",
+  };
+}
+
+async function activeEmbedderCheck(
+  ctx: StepContext,
+  declared: OpenVikingConfig,
+): Promise<CheckResult> {
+  const expected = ovConfEmbedder(declared);
+  // Emit identity fields alone: ov.conf also contains credentials.
+  const script = `import {readFileSync} from "node:fs";
+import {loadConfig} from "./dist/src/config.js";
+const cfg=loadConfig();
+const dense=JSON.parse(readFileSync(cfg.openviking.config_file,"utf8")).embedding?.dense;
+console.log(JSON.stringify({provider:dense?.provider,model:dense?.model,dimension:dense?.dimension,api_base:dense?.api_base}));`;
+  // ov.conf lives in the memory engine's container; its image keeps the app
+  // in /opt/qcr and exports QCR_CONFIG only inside its entrypoint.
+  const result = await stackTransportFor(ctx).execMemory([
+    "sh",
+    "-c",
+    'cd /opt/qcr 2>/dev/null; QCR_CONFIG="${QCR_CONFIG:-/opt/quickreview/config-home/${QCR_CONFIG_NAME:-config.toml}}" ' +
+      'exec node --input-type=module -e "$0"',
+    script,
+  ]);
+  let actual: Record<string, unknown> | undefined;
+  try {
+    const value: unknown = JSON.parse(result.stdout);
+    if (typeof value === "object" && value !== null && !Array.isArray(value))
+      actual = value as Record<string, unknown>;
+  } catch {
+    /* unreadable remains unknown */
+  }
+  if (
+    result.code !== 0 ||
+    !actual ||
+    typeof actual.provider !== "string" ||
+    typeof actual.model !== "string" ||
+    typeof actual.dimension !== "number"
+  )
+    return {
+      name: "embedder-runtime",
+      ok: false,
+      detail: `the active embedder configuration is unreadable (exit ${result.code}${
+        result.stderr.trim() ? `: ${result.stderr.trim().slice(0, 200)}` : ""
+      }) — its provider is unknown; restore access to the memory container before verifying delivery`,
+    };
+  const matches =
+    actual.provider === expected.provider &&
+    actual.model === expected.model &&
+    actual.dimension === expected.dimension &&
+    actual.api_base === expected.api_base;
+  return {
+    name: "embedder-runtime",
+    ok: matches,
+    detail: matches
+      ? "the active embedder matches config.toml"
+      : "the active embedder differs from config.toml — run bring-up (or inventory and a rebuild on the server route) before claiming the change delivered",
+  };
+}
+
+export function embeddingsStep(): OnboardingStep {
+  return {
+    id: EMBEDDINGS_STEP_ID,
+    title: "Memory embeddings: local by default",
+    explain:
+      "Decides where the memory engine computes its vectors. The shipped default is LOCAL: a small English embedding model " +
+      `(${LOCAL_EMBEDDING.model}, pinned in the image) served on loopback inside the memory ` +
+      "container, so nothing but the model call ever leaves the machine — memory text included — and no key is needed. Calling this " +
+      "step with no arguments keeps whatever the config already declares (the local default on a fresh install); moving an " +
+      'installation back to local takes an explicit `provider: "local"`. The alternative is OpenAI\'s hosted embeddings (`provider: "openai"`): every memory ' +
+      "entry's text is then sent to OpenAI, and the credential is its OWN secrets file (openai_embeddings_api_key, via " +
+      "deploy/collect-secrets.sh) — pi's openai_api_key is never used for it. Do not offer the hosted option as an upgrade; offer it " +
+      "only if the operator asks, and say plainly what leaves the machine.",
+    order: 38,
+    parameters: {
+      type: "object",
+      properties: {
+        provider: {
+          type: "string",
+          enum: [...EMBEDDING_PROVIDERS],
+          description:
+            '"local" (the shipped default) or "openai" (hosted; sends memory text to OpenAI). Omit to keep what config.toml declares.',
+        },
+        model: {
+          type: "string",
+          description: `Hosted only: the embedding model (default ${HOSTED_EMBEDDING.model}). Ignored for local, which has one model.`,
+        },
+        dimension: {
+          type: "string",
+          description: `Hosted only: the vector dimension of that model (default ${HOSTED_EMBEDDING.dimension}). Ignored for local.`,
+        },
+      },
+    },
+
+    async run(ctx): Promise<StepReport> {
+      const path = interviewConfigPath(ctx);
+      const text = readTextOrNull(path);
+      if (text === null) {
+        return {
+          ok: false,
+          checks: [
+            {
+              name: "config.toml",
+              ok: false,
+              detail: `${path} does not exist yet — run the config_fill step first; this step then writes the embedder into it`,
+            },
+          ],
+        };
+      }
+      const current = declaredEmbedderOf(text);
+      const rawProvider = String(ctx.input.provider ?? current.provider)
+        .trim()
+        .toLowerCase();
+      if (!(EMBEDDING_PROVIDERS as readonly string[]).includes(rawProvider)) {
+        return {
+          ok: false,
+          checks: [
+            {
+              name: "provider",
+              ok: false,
+              detail: `"${rawProvider}" is not an embedder — the choices are ${EMBEDDING_PROVIDERS.map((p) => `"${p}"`).join(" and ")}`,
+            },
+          ],
+        };
+      }
+      const provider = rawProvider as EmbeddingProvider;
+      const model =
+        provider === "local"
+          ? LOCAL_EMBEDDING.model
+          : String(
+              ctx.input.model ??
+                (current.provider === "openai" ? current.model : HOSTED_EMBEDDING.model),
+            ).trim() || HOSTED_EMBEDDING.model;
+      const dimensionRaw =
+        provider === "local"
+          ? String(LOCAL_EMBEDDING.dimension)
+          : String(
+              ctx.input.dimension ??
+                (current.provider === "openai" ? current.dimension : HOSTED_EMBEDDING.dimension),
+            ).trim();
+      if (!/^[1-9][0-9]*$/.test(dimensionRaw)) {
+        return {
+          ok: false,
+          checks: [
+            {
+              name: "dimension",
+              ok: false,
+              detail: `"${dimensionRaw}" is not a vector dimension — a positive integer, e.g. 1536 for text-embedding-3-small`,
+            },
+          ],
+        };
+      }
+      const edits: TomlEdit[] = [
+        { section: "openviking", key: "embedding_provider", value: tomlString(provider) },
+        { section: "openviking", key: "embedding_model", value: tomlString(model) },
+        { section: "openviking", key: "embedding_dimension", value: dimensionRaw },
+      ];
+      // Rule 1, structurally: the only wizard file that may write `dry_run`
+      // is golive.ts; every other edit list is asserted clean first.
+      assertNoDryRunEdit(edits);
+      const patched = patchToml(text, edits);
+      // Parse BEFORE writing — the loader's own validation is the lock, so a
+      // config this step writes can always be booted.
+      try {
+        parseConfig(patched);
+      } catch (err) {
+        return {
+          ok: false,
+          checks: [
+            {
+              name: "config validation",
+              ok: false,
+              detail: `the embedder this step would write does not load: ${String(err)} — nothing was written`,
+            },
+          ],
+        };
+      }
+      if (patched !== text) writeAtomic(path, patched);
+      const declared = declaredEmbedderOf(patched);
+
+      const checks: CheckResult[] = [
+        {
+          name: "embedder",
+          ok: true,
+          detail: `${describeEmbedder(declared)} — ${provider === "local" ? LOCAL_SENTENCE : HOSTED_SENTENCE}`,
+        },
+        {
+          name: "config.toml",
+          ok: true,
+          detail: `[openviking] embedding_provider/model/dimension ${patched === text ? "already said this" : `written to ${path}`}, and it parses`,
+        },
+      ];
+      if (provider !== "local")
+        checks.push(keyFileCheck(secretsDirFor(ctx.adapters, ctx.choices), declared.keyFile));
+      checks.push(propagationNote(ctx), MIGRATION_NOTE);
+      return {
+        ok: checks.every((c) => c.ok),
+        checks,
+        data: { provider, model: declared.model, dimension: declared.dimension, config_path: path },
+      };
+    },
+
+    async verify(ctx): Promise<StepReport> {
+      const path = interviewConfigPath(ctx);
+      const text = readTextOrNull(path);
+      if (text === null)
+        return {
+          ok: false,
+          checks: [{ name: "config.toml", ok: false, detail: `${path} does not exist` }],
+        };
+      let declared: DeclaredEmbedder;
+      let ov: OpenVikingConfig;
+      try {
+        ov = parseConfig(text).openviking;
+        declared = embedderOf(ov);
+      } catch (err) {
+        return {
+          ok: false,
+          checks: [
+            { name: "config.toml", ok: false, detail: `${path} does not load: ${String(err)}` },
+          ],
+        };
+      }
+      const checks: CheckResult[] = [
+        {
+          name: "embedder",
+          ok: true,
+          detail: `${describeEmbedder(declared)} — ${declared.provider === "local" ? LOCAL_SENTENCE : HOSTED_SENTENCE}`,
+        },
+      ];
+      if (declared.provider !== "local")
+        checks.push(keyFileCheck(secretsDirFor(ctx.adapters, ctx.choices), declared.keyFile));
+      const state = await stackTransportFor(ctx).daemonState();
+      if (state.state === "unknown")
+        checks.push({
+          name: "embedder-runtime",
+          ok: false,
+          detail: `running embedder is unknown (${state.detail}) — restore host access before verifying delivery`,
+        });
+      else if (state.state === "running") {
+        if (ov.enabled) checks.push(await activeEmbedderCheck(ctx, ov));
+        if (topologyOf(ctx.choices) === "vm") {
+          const inventory = await vmInventoryStep().verify(ctx);
+          const deployed = await vmDeployStep().verify(ctx);
+          checks.push(...inventory.checks, ...deployed.checks);
+        } else
+          checks.push({
+            ...embedderInputsCheck(text, readEnvText(rootOf(ctx.adapters))),
+            name: "embedder-inputs",
+          });
+      }
+      return { ok: checks.every((c) => c.ok), checks };
+    },
+  };
+}