mirror-mind 0.0.1 → 0.32.1

package/ts/src/runtime/update.ts

@@ -0,0 +1,445 @@
+// `runtime update` — the pipeline body, run once for either install kind.
+// (CV22.DS10.US2; one body over two strategies since CV22.DS10.US3 plateau 4,
+// debt D-026.)
+//
+// Everything structural lives elsewhere: the stage vocabulary, the render, and
+// the strategy seam in `updatePipeline.ts`, the gate in `updateGate.ts`, the
+// git verbs and the clone strategy in `strategies/clone.ts`, the npm verbs and
+// the package strategy in `strategies/package.ts`, the install answer in
+// `installKind.ts`. This module is the ORDER those are used in, and the two
+// places the redesign departs from the oracle:
+//
+//   1. `capture` is a stage. The oracle reads `previous_commit` as a side
+//      effect of the status report; here it is recorded deliberately, before
+//      anything can move, because the recovery block is only as useful as that
+//      value and `apply` must be unreachable without it.
+//
+//   2. `migrate` and `validate` run in FRESH PROCESSES on the code that was
+//      just installed. The oracle migrates in-process, with the modules it
+//      imported before the fast-forward -- so a migration authored in the new
+//      commit is invisible to the very run that installed it.
+//
+// A LANE is a list of steps. The ordinary lane is the whole promise; the
+// repair lane is the smallest safe act that can make a broken updater usable
+// again -- no status gate (the status is what is broken), no backup, no
+// migrations (the new code owns those on the next ordinary run). The lane is
+// chosen once, below; no step asks which lane it is in.
+
+import { spawnSync } from "node:child_process";
+import { verifyBackupArchive } from "#runtime/backup.ts";
+import type { InstallKind } from "#runtime/installKind.ts";
+import { cloneStrategy, defaultGitRunner, type GitRunner } from "#runtime/strategies/clone.ts";
+import { defaultNpmRunner, type NpmRunner, packageStrategy } from "#runtime/strategies/package.ts";
+import type { statusAllowsUpdatePreflight } from "#runtime/updateGate.ts";
+import {
+  type ApplyStrategy,
+  stage,
+  type UpdateResult,
+  type UpdateStage,
+} from "#runtime/updatePipeline.ts";
+import { commandOnPath } from "#util/paths.ts";
+import { PROGRAM } from "#util/program.ts";
+import { shellWord } from "#util/shellWord.ts";
+
+/** Runs the FRONT DOOR again, on the code now installed. */
+export type UpdateSpawn = (argv: readonly string[]) => {
+  code: number;
+  stdout: string;
+  stderr: string;
+};
+
+export interface UpdateDeps {
+  install: InstallKind;
+  /** `origin/<channel>` for a clone; null for a package, which has no upstream. */
+  upstream: string | null;
+  channel: string;
+  mirrorHome: string | null;
+  /** The status report, re-read after apply through a fresh process. */
+  statusReady: () => { ready: boolean; detail: string };
+  gate: () => ReturnType<typeof statusAllowsUpdatePreflight> & { ready: boolean };
+  createBackup: () => string | null;
+  /**
+   * Injected like every other seam so the pipeline's ORDER can be driven
+   * without real archives. The default is the real verifier -- the stage is
+   * worthless if it can be satisfied by anything cheaper.
+   */
+  verifyBackup?: (path: string) => { valid: boolean; note: string | null };
+  git?: GitRunner;
+  spawnFrontDoor: UpdateSpawn;
+  fetch?: boolean;
+  migrate?: boolean;
+  /** Plan only: report what WOULD happen and touch nothing. */
+  dryRun?: boolean;
+  /**
+   * The self-repair lane. A minimal gate (readable checkout, upstream, clean
+   * tree), fast-forward, migrations SKIPPED, and an instruction to rerun
+   * `runtime update` with the repaired updater. It exists for the failure the
+   * ordinary gate cannot survive: an updater too broken to evaluate its own
+   * status, which is why entering it must not depend on that status.
+   */
+  repair?: boolean;
+  /** Why the repair lane was entered, when it was entered automatically. */
+  repairReason?: string;
+  /** The npm seam, injected for the same reason the git one is. */
+  npm?: NpmRunner;
+}
+
+/** One update in flight: what the steps have learned so far. */
+interface Run {
+  readonly deps: UpdateDeps;
+  readonly strategy: ApplyStrategy;
+  readonly stages: UpdateStage[];
+  previousRef: string | null;
+  /** What `plan` found to apply; set only on an `ahead` outcome. */
+  target: string | null;
+  dryRunDetail: string | null;
+  backupPath: string | null;
+  newRef: string | null;
+  changes: string[];
+}
+
+/** A step either ends the run with a result or lets the next step run. */
+type Step = (run: Run) => UpdateResult | null;
+
+function failed(run: Run, recovery: string[]): UpdateResult {
+  return {
+    stages: run.stages,
+    previousRef: run.previousRef,
+    newRef: run.newRef,
+    backupPath: run.backupPath,
+    success: false,
+    recovery,
+    installedChanges: [],
+  };
+}
+
+function succeeded(run: Run): UpdateResult {
+  return {
+    stages: run.stages,
+    previousRef: run.previousRef,
+    newRef: run.newRef,
+    backupPath: run.backupPath,
+    success: true,
+    recovery: [],
+    installedChanges: run.changes,
+  };
+}
+
+/** The ref `capture` recorded. A step that needs it runs after `capture` by construction. */
+function captured(run: Run): string {
+  if (run.previousRef === null) throw new Error("capture must run before this stage");
+  return run.previousRef;
+}
+
+function backupLine(run: Run): string[] {
+  return run.backupPath ? [`Backup: ${run.backupPath}`] : [];
+}
+
+// --- the steps ---------------------------------------------------------------
+
+const statusGate: Step = (run) => {
+  const verdict = run.deps.gate();
+  if (verdict.ready) {
+    run.stages.push(stage("status gate", "pass"));
+    return null;
+  }
+  if (!verdict.allowed) {
+    run.stages.push(stage("status gate", "fail", "runtime status is not ready"));
+    return failed(run, [
+      "Run: runtime diagnose",
+      "Resolve the reported drift, then retry runtime update.",
+    ]);
+  }
+  run.stages.push(stage("status gate", "pass", `update-safe preflight drift (${verdict.detail})`));
+  return null;
+};
+
+const repairPreflight: Step = (run) => {
+  run.stages.push(
+    stage("repair preflight", "pass", run.deps.repairReason ?? "requested with --repair-updater"),
+  );
+  const verdict = run.strategy.repairGate();
+  if (verdict.ok) return null;
+  run.stages.push(stage("repair preflight", "fail", verdict.detail));
+  return failed(run, verdict.recovery);
+};
+
+const capture: Step = (run) => {
+  const outcome = run.strategy.capture();
+  if (!outcome.ok) {
+    run.stages.push(stage("capture", "fail", outcome.detail));
+    return failed(run, outcome.recovery);
+  }
+  run.previousRef = outcome.ref;
+  run.stages.push(stage("capture", "pass", outcome.detail));
+  return null;
+};
+
+const fetch: Step = (run) => {
+  const fetchUpstream = run.strategy.fetch;
+  if (fetchUpstream === undefined) return null;
+  if (run.deps.fetch === false) {
+    run.stages.push(stage("fetch", "skip", "--no-fetch"));
+    return null;
+  }
+  const outcome = fetchUpstream();
+  if (!outcome.ok) {
+    run.stages.push(stage("fetch", "fail", outcome.detail));
+    return failed(run, outcome.recovery);
+  }
+  run.stages.push(stage("fetch", "pass", outcome.detail));
+  return null;
+};
+
+const plan: Step = (run) => {
+  const outcome = run.strategy.plan(captured(run));
+  if (outcome.kind === "blocked") {
+    run.stages.push(stage("plan", "fail", outcome.detail));
+    return failed(run, outcome.recovery);
+  }
+  run.stages.push(stage("plan", "pass", outcome.detail));
+  if (outcome.kind === "current") {
+    // Nothing to do, and nothing was archived to find that out.
+    run.newRef = run.previousRef;
+    return succeeded(run);
+  }
+  run.target = outcome.target;
+  run.dryRunDetail = outcome.dryRun;
+  return null;
+};
+
+const dryRunStop: Step = (run) => {
+  if (run.deps.dryRun !== true) return null;
+  // Everything above this line is read-only. Stopping here is the whole
+  // promise of a dry run: the stages a real run would take next are named,
+  // not performed.
+  run.stages.push(stage("backup", "skip", "dry run"));
+  run.stages.push(stage("verify backup", "skip", "dry run"));
+  run.stages.push(stage(run.strategy.applyStage, "skip", run.dryRunDetail ?? "dry run"));
+  run.stages.push(stage("migrate", "skip", "dry run"));
+  run.stages.push(stage("post-update status", "skip", "dry run"));
+  return succeeded(run);
+};
+
+const backupAndVerify: Step = (run) => {
+  const home = run.deps.mirrorHome ?? "<mirror home>";
+  let backupPath: string | null;
+  try {
+    backupPath = run.deps.createBackup();
+  } catch (error) {
+    run.stages.push(
+      stage("backup", "fail", error instanceof Error ? error.message : String(error)),
+    );
+    return failed(run, [`Backup directory must be writable: ${home}`]);
+  }
+  if (backupPath === null) {
+    run.stages.push(stage("backup", "fail", "database not found"));
+    return failed(run, [`Expected a database under: ${home}`]);
+  }
+  run.backupPath = backupPath;
+  run.stages.push(stage("backup", "pass", backupPath));
+
+  const verification = (run.deps.verifyBackup ?? verifyBackupArchive)(backupPath);
+  if (!verification.valid) {
+    run.stages.push(stage("verify backup", "fail", verification.note ?? "invalid backup"));
+    return failed(run, [
+      `Backup created but failed verification: ${backupPath}`,
+      "Inspect the archive before retrying runtime update; nothing has moved.",
+    ]);
+  }
+  run.stages.push(stage("verify backup", "pass"));
+  return null;
+};
+
+const skipBackup: Step = (run) => {
+  run.stages.push(stage("backup", "skip", "repair lane"));
+  return null;
+};
+
+/** The first irreversible step. */
+const apply: Step = (run) => {
+  const previousRef = captured(run);
+  if (run.target === null) throw new Error("plan must name a target before apply");
+  const outcome = run.strategy.apply(previousRef, run.target);
+  if (!outcome.ok) {
+    run.stages.push(stage(run.strategy.applyStage, "fail", outcome.detail));
+    return failed(run, [
+      ...outcome.recovery,
+      ...backupLine(run),
+      `Recover with: ${run.strategy.recoveryCommand(previousRef)}`,
+    ]);
+  }
+  run.newRef = outcome.newRef;
+  run.changes = outcome.changes;
+  run.stages.push(stage(run.strategy.applyStage, "pass", outcome.detail));
+  return null;
+};
+
+/** Fresh process, NEW code. */
+const migrate: Step = (run) => {
+  if (run.deps.migrate === false) {
+    run.stages.push(stage("migrate", "skip", "--skip-migrations"));
+    return null;
+  }
+  const home = run.deps.mirrorHome;
+  const result = run.deps.spawnFrontDoor(
+    home ? ["runtime", "migrate", "--mirror-home", home] : ["runtime", "migrate"],
+  );
+  if (result.code !== 0) {
+    run.stages.push(stage("migrate", "fail", firstLine(result.stderr || result.stdout)));
+    return failed(run, [
+      ...backupLine(run),
+      `${run.strategy.installedState(run.newRef)}; the database may be partly migrated.`,
+      `Restore the database from the backup, then: ${run.strategy.recoveryCommand(captured(run))}`,
+    ]);
+  }
+  run.stages.push(stage("migrate", "pass", migrateSummary(result.stdout)));
+  return null;
+};
+
+const skipMigrate: Step = (run) => {
+  run.stages.push(stage("migrate", "skip", "repair lane: the ordinary update owns migrations"));
+  return null;
+};
+
+/** Fresh process: the verdict comes from the code that was just installed. */
+const validate: Step = (run) => {
+  const post = run.deps.statusReady();
+  if (!post.ready) {
+    run.stages.push(stage("post-update status", "fail", post.detail));
+    return failed(run, [
+      `${run.strategy.installedState(run.newRef)} and the database may be migrated.`,
+      ...backupLine(run),
+      "Run: runtime diagnose",
+    ]);
+  }
+  run.stages.push(stage("post-update status", "pass"));
+  return null;
+};
+
+// --- the lanes ---------------------------------------------------------------
+
+const ORDINARY_LANE: readonly Step[] = [
+  statusGate,
+  capture,
+  fetch,
+  plan,
+  dryRunStop,
+  backupAndVerify,
+  apply,
+  migrate,
+  validate,
+];
+
+const REPAIR_LANE: readonly Step[] = [
+  repairPreflight,
+  capture,
+  fetch,
+  plan,
+  dryRunStop,
+  skipBackup,
+  apply,
+  skipMigrate,
+];
+
+function strategyFor(deps: UpdateDeps, install: Exclude<InstallKind, { kind: "unknown" }>) {
+  if (install.kind === "package") {
+    return packageStrategy(install, deps.channel, deps.npm ?? defaultNpmRunner);
+  }
+  return cloneStrategy(
+    install.repository,
+    deps.upstream ?? `origin/${deps.channel}`,
+    deps.git ?? defaultGitRunner,
+  );
+}
+
+export function runUpdate(deps: UpdateDeps): UpdateResult {
+  const stages: UpdateStage[] = [];
+  if (deps.install.kind === "unknown") {
+    stages.push(stage("status gate", "fail", `install kind unknown: ${deps.install.reason}`));
+    return {
+      stages,
+      previousRef: null,
+      newRef: null,
+      backupPath: null,
+      success: false,
+      recovery: [
+        "Mirror could not identify how it is installed, so it will not update itself.",
+        "A git checkout updates in place; a global npm install updates through npm.",
+      ],
+      installedChanges: [],
+    };
+  }
+
+  const run: Run = {
+    deps,
+    strategy: strategyFor(deps, deps.install),
+    stages,
+    previousRef: null,
+    target: null,
+    dryRunDetail: null,
+    backupPath: null,
+    newRef: null,
+    changes: [],
+  };
+  const lane = deps.repair === true ? REPAIR_LANE : ORDINARY_LANE;
+  for (const step of lane) {
+    const result = step(run);
+    if (result !== null) return result;
+  }
+  return succeeded(run);
+}
+
+/**
+ * What to say after the stages, when the update itself has nothing more to
+ * say. One case today (CV22.DS10.US3 plateau 4): a clone whose PATH does not
+ * reach `mirror`. Every skill invokes that name, and a checkout provides it
+ * only after `npm link` has run once at its root -- the seam every clone user
+ * crosses once, at the update that brought the skills saying it. A package
+ * put `mirror` on the PATH by being installed; a failed update's last words
+ * are its recovery block.
+ */
+export function postUpdateHints(
+  install: InstallKind,
+  result: UpdateResult,
+  env: NodeJS.ProcessEnv,
+  canExecute?: (path: string) => boolean,
+): string[] {
+  if (install.kind !== "clone" || !result.success) return [];
+  if (commandOnPath(PROGRAM, env, canExecute) !== null) return [];
+  // A command the person will paste: the path is one shell word (CR104).
+  return [
+    `\`${PROGRAM}\` is not on the PATH: run \`npm link\` once in ${shellWord(install.repository)}, so the skills can call it.`,
+  ];
+}
+
+function firstLine(text: string): string {
+  return text.trim().split("\n")[0] ?? "migration failed";
+}
+
+/** The one line from `runtime migrate`'s render worth carrying into a stage. */
+function migrateSummary(stdout: string): string {
+  const match = /^Migrate result: (.+)$/m.exec(stdout);
+  return match?.[1] ?? "completed";
+}
+
+/**
+ * Spawn the front door again, inheriting the environment explicitly. `entry`
+ * is the bin that loads it, not the `.ts` file: see the route's `spawner`.
+ */
+export function frontDoorSpawner(entry: string, env: NodeJS.ProcessEnv): UpdateSpawn {
+  return (argv) => {
+    const result = spawnSync(process.execPath, [entry, ...argv], {
+      encoding: "utf8",
+      // A spawned front door does NOT inherit `--env-file`; the variables it
+      // needs are passed explicitly or it resolves a different home than the
+      // process that launched it.
+      env: { ...env, NODE_OPTIONS: env.NODE_OPTIONS ?? "--no-warnings" },
+    });
+    return {
+      code: result.status ?? -1,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+    };
+  };
+}

package/ts/src/runtime/updateGate.ts

@@ -0,0 +1,40 @@
+// The pre-update status gate (CV22.DS10.US2).
+//
+// Port of `_status_allows_update_preflight`, kept as a pure function of the
+// status report because it is the single most consequential decision the
+// updater makes: whether to touch the tree at all.
+//
+// The relaxed lane is narrow ON PURPOSE, and the oracle's docstring says why:
+// the updater must not let old code block the very update that would teach it
+// about a newer migration. So core-migration ledger drift -- and ONLY that --
+// may pass a non-ready status, because the update still backs up before it
+// migrates and still requires a ready status afterwards. Everything else
+// (dirty tree, missing database, unready extension, unresolvable home) fails.
+
+import type { RuntimeStatusReport } from "#runtime/status.ts";
+
+export interface GateVerdict {
+  allowed: boolean;
+  detail: string;
+}
+
+export function statusAllowsUpdatePreflight(report: RuntimeStatusReport): GateVerdict {
+  if (report.mirror_home_error) return { allowed: false, detail: report.mirror_home_error };
+  if (report.git.error) return { allowed: false, detail: report.git.error };
+  if (report.git.dirty) return { allowed: false, detail: "git tree is dirty" };
+  if (report.db_exists !== true) return { allowed: false, detail: "database missing" };
+  if (report.extension_health.some((item) => !item.ready)) {
+    return { allowed: false, detail: "extension health is not ready" };
+  }
+
+  const core = report.core_migrations;
+  if (core.ready) return { allowed: true, detail: "runtime status is ready" };
+  if (core.note) return { allowed: false, detail: core.note };
+
+  const parts: string[] = [];
+  if (core.missing.length > 0) parts.push(`pending core migrations: ${core.missing.join(", ")}`);
+  if (core.unknown.length > 0) parts.push(`unknown core migrations: ${core.unknown.join(", ")}`);
+  if (parts.length > 0) return { allowed: true, detail: parts.join("; ") };
+
+  return { allowed: false, detail: "core migration status is not ready" };
+}

package/ts/src/runtime/updatePipeline.ts

@@ -0,0 +1,159 @@
+// The update pipeline: what Mirror promises when it updates itself.
+// (CV22.DS10.US2)
+//
+//   gate -> capture -> plan -> fetch -> backup -> verify -> apply
+//        -> migrate -> validate
+//
+// The order is the oracle's, and it is load-bearing in both directions: plan
+// and fetch are cheap and read-only, so they come first and a no-op update
+// never archives the database; `apply` is the first irreversible step, so
+// nothing reaches it until `capture` recorded where to go back to and
+// `verify backup` proved the archive opens.
+//
+// Only `apply` differs between a clone and a package. Everything here is the
+// same for both, which is why it lives in its own module rather than inside
+// either strategy -- and why the seam between the body and a strategy is
+// declared here too (CV22.DS10.US3 plateau 4, debt D-026): the body in
+// `update.ts` runs the order above once, and a strategy answers only the
+// questions whose answer depends on how Mirror was installed.
+
+/**
+ * The channels an update may follow, for either install kind: `stable` is the
+ * promoted release, `main` the development branch. A clone follows
+ * `origin/<channel>`; a package follows the dist-tag of the same name.
+ */
+export const KNOWN_CHANNELS: ReadonlySet<string> = new Set(["stable", "main"]);
+export const DEFAULT_CHANNEL = "stable";
+
+export type StageState = "pass" | "fail" | "skip";
+
+export interface UpdateStage {
+  name: string;
+  state: StageState;
+  detail?: string;
+}
+
+export interface UpdateResult {
+  stages: UpdateStage[];
+  /**
+   * Where to go back to, read BEFORE anything moved: a commit for a clone, an
+   * installed version for a package. The recovery block is only as useful as
+   * this value, which is why it is captured in its own stage rather than
+   * derived afterwards from a tree that has already changed.
+   */
+  previousRef: string | null;
+  newRef: string | null;
+  backupPath: string | null;
+  success: boolean;
+  recovery: string[];
+  installedChanges: string[];
+}
+
+export function stage(name: string, state: StageState, detail?: string): UpdateStage {
+  return detail === undefined ? { name, state } : { name, state, detail };
+}
+
+// --- the strategy seam -------------------------------------------------------
+
+/** A step that could not be taken, with the stage detail and the route back. */
+export interface Refusal {
+  ok: false;
+  detail: string;
+  recovery: string[];
+}
+
+export type CaptureOutcome = { ok: true; ref: string; detail: string } | Refusal;
+export type FetchOutcome = { ok: true; detail: string } | Refusal;
+export type GateOutcome = { ok: true } | Refusal;
+
+export type PlanOutcome =
+  /** Nothing to do; the update ends here without archiving anything. */
+  | { kind: "current"; detail: string }
+  /** Something to apply: `target` is what apply moves to, `dryRun` what a dry run says it would do. */
+  | { kind: "ahead"; target: string; detail: string; dryRun: string }
+  | { kind: "blocked"; detail: string; recovery: string[] };
+
+export type ApplyOutcome =
+  | { ok: true; newRef: string | null; detail: string; changes: string[] }
+  | Refusal;
+
+/**
+ * What differs between a clone and a package, and nothing else.
+ *
+ * The body owns the order, the gate, the dry run, the backup and its
+ * verification, the fresh-process migrate and validate, and the recovery
+ * block's shape. A strategy owns the meaning of a ref (a commit, a version),
+ * how to read it, how to learn whether the channel is ahead, how to move, and
+ * the words that name its own apply stage and its way back.
+ */
+export interface ApplyStrategy {
+  readonly kind: "clone" | "package";
+  /** What the render calls the irreversible step: `fast-forward` or `apply`. */
+  readonly applyStage: string;
+  /**
+   * The minimal gate the repair lane runs INSTEAD of the status gate: what
+   * must be true of the install itself when the status cannot be trusted.
+   */
+  repairGate(): GateOutcome;
+  /** The ref to go back to, read before anything moves. */
+  capture(): CaptureOutcome;
+  /** Absent when there is nothing to fetch: a registry is asked at plan time. */
+  fetch?(): FetchOutcome;
+  plan(previousRef: string): PlanOutcome;
+  apply(previousRef: string, target: string): ApplyOutcome;
+  /** The pasteable route back, with the captured ref in it. */
+  recoveryCommand(previousRef: string): string;
+  /** Where the code stands after apply, for the recovery block. */
+  installedState(newRef: string | null): string;
+}
+
+/** Port of `render_runtime_update_result`, in the redesign's vocabulary. */
+export function renderUpdateResult(result: UpdateResult): string {
+  const marks: Record<StageState, string> = { pass: "✓", fail: "✗", skip: "-" };
+  const lines: string[] = ["Mirror runtime update", ""];
+  for (const entry of result.stages) {
+    const mark = marks[entry.state] ?? "?";
+    lines.push(
+      entry.detail ? `[${mark}] ${entry.name}: ${entry.detail}` : `[${mark}] ${entry.name}`,
+    );
+  }
+  lines.push("");
+  if (result.previousRef && result.newRef && result.previousRef !== result.newRef) {
+    lines.push(`Previous: ${result.previousRef}`);
+    lines.push(`New: ${result.newRef}`);
+  }
+  if (result.backupPath) lines.push(`Backup: ${result.backupPath}`);
+  if (result.installedChanges.length > 0) {
+    lines.push("");
+    lines.push("Installed changes:");
+    for (const change of result.installedChanges) lines.push(`- ${change}`);
+  }
+  lines.push("");
+  if (result.success) {
+    lines.push("Update result: success");
+  } else {
+    lines.push("Update result: failed");
+    if (result.recovery.length > 0) {
+      lines.push("");
+      lines.push("Recovery:");
+      for (const entry of result.recovery) lines.push(`- ${entry}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * One line per update, for `<mirror-home>/front-door.log`.
+ *
+ * The log already records every routing decision; an update that moved the
+ * tree and migrated the database should not be the one event that leaves no
+ * trace. Months later this line is the only evidence of what happened.
+ */
+export function updateLogDetail(install: string, channel: string, result: UpdateResult): string {
+  const stages = result.stages.map((entry) => `${entry.name}=${entry.state}`).join(",");
+  const from = result.previousRef ?? "unknown";
+  const to = result.newRef ?? "unchanged";
+  return `update install=${install} channel=${channel} ${from}->${to} ${stages} result=${
+    result.success ? "success" : "failed"
+  }`;
+}

package/ts/src/runtime/version.ts

@@ -0,0 +1,36 @@
+// The project's version, read from source.
+//
+// Extracted from `runtime/git.ts` (CV22.DS9.TS2): the MCP server reports this
+// string in `initialize`, and importing the git module -- which spawns
+// `git`, carries network timeouts, and owns the read-only-repository boundary --
+// to learn a version is the wrong dependency direction. `git.ts` re-exports it,
+// so the runtime surface's call sites are unchanged.
+
+import { findPackageIdentity } from "./packageIdentity.ts";
+
+/**
+ * THE product version. One function, read by the updater, the release doctor,
+ * the welcome card, and the MCP server, so that npm distribution changes one
+ * body and nothing else (CV22.DS10.US2, decision D2).
+ *
+ * Until CV22.DS10.TS5 this walked upward for `pyproject.toml`'s first
+ * `version =` line, a port of `_version_from_pyproject`.
+ *
+ * **TS5 moves the authority to the TypeScript package** (decision D1). The
+ * comment that used to live here said US3 would do it, while the Zero Python
+ * gate assigned `pyproject.toml`'s deletion to TS5 -- both could not hold, and
+ * a version that reads a file this story deletes would answer `null` and
+ * render as `unknown` in the updater, the release doctor, the welcome card,
+ * and the MCP handshake.
+ *
+ * `package.json` therefore carries the real version from now on. US3 still
+ * changes exactly one place, which was US2's intent: `PACKAGE_NAME` and the
+ * `private` flag.
+ */
+export function packageVersion(start: string): string | null {
+  const identity = findPackageIdentity(start);
+  // A tree that is not ours has no version to report -- the same `null` the
+  // pyproject walk returned when it reached the filesystem root.
+  if (!identity?.isMirrorMind) return null;
+  return identity.version;
+}