@vellumai/assistant 0.10.12 → 0.11.0-staging.1

package/src/workspace/migrations/135-copy-substrate-tunables.ts

@@ -0,0 +1,248 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getLogger } from "../../util/logger.js";
+import type { WorkspaceMigration } from "./types.js";
+
+const log = getLogger("workspace-migration-135");
+
+/**
+ * Marks the two optional `memory.v2` keys that ship with no schema default
+ * (`min_sparse_spread`, `full_sparse_spread`) — for those, raw presence IS
+ * user intent, so they copy on presence alone.
+ */
+const NO_DEFAULT: unique symbol = Symbol("no-default");
+
+/**
+ * The fifteen substrate tunables shared between the historical `memory.v2`
+ * namespace and the new `memory.substrate` namespace, each paired with the
+ * shipped `memory.v2` schema default (from `config/schemas/memory-v2.ts`).
+ * `memory.v2.k` and `memory.v2.hops` were renamed to `spread_k` /
+ * `spread_hops` on the substrate side; every other key keeps its name.
+ *
+ * The defaults matter because raw presence in config.json is NOT user intent:
+ * the config loader serializes the fully-parsed configuration for
+ * normally-created workspaces, so defaulted `memory.v2` leaves are persisted
+ * for most existing assistants. Copying those seeded values would populate
+ * the override-only `memory.substrate` namespace with today's defaults and
+ * permanently pin those assistants when substrate defaults are later retuned
+ * — the same default-pinning problem migration 119 solves for `memory.v3`
+ * tuning, distinguished the same way (value-vs-shipped-default comparison,
+ * table inlined per the migrations self-containment rule).
+ */
+const SUBSTRATE_KEY_PAIRS: ReadonlyArray<{
+  v2Key: string;
+  substrateKey: string;
+  shippedDefault: number | boolean | string | null | typeof NO_DEFAULT;
+  /**
+   * Additional values the loader has seeded as this key's default in earlier
+   * releases (multi-default keys, mirroring migration 119). A persisted value
+   * matching any of them is seeded, not a user override.
+   */
+  priorDefaults?: ReadonlyArray<number | boolean | string | null>;
+}> = [
+  {
+    v2Key: "sweep_enabled",
+    substrateKey: "sweep_enabled",
+    shippedDefault: false,
+  },
+  { v2Key: "dense_weight", substrateKey: "dense_weight", shippedDefault: 0.85 },
+  {
+    v2Key: "sparse_weight",
+    substrateKey: "sparse_weight",
+    shippedDefault: 0.15,
+  },
+  {
+    v2Key: "min_sparse_spread",
+    substrateKey: "min_sparse_spread",
+    shippedDefault: NO_DEFAULT,
+  },
+  {
+    v2Key: "full_sparse_spread",
+    substrateKey: "full_sparse_spread",
+    shippedDefault: NO_DEFAULT,
+  },
+  { v2Key: "bm25_k1", substrateKey: "bm25_k1", shippedDefault: 1.2 },
+  {
+    v2Key: "bm25_b",
+    substrateKey: "bm25_b",
+    shippedDefault: 0.4,
+    // Workspaces seeded before migration 075 carry the earlier 0.75 default.
+    priorDefaults: [0.75],
+  },
+  {
+    v2Key: "consolidation_interval_hours",
+    substrateKey: "consolidation_interval_hours",
+    shippedDefault: 8,
+  },
+  {
+    v2Key: "consolidation_max_buffer_lines",
+    substrateKey: "consolidation_max_buffer_lines",
+    shippedDefault: 100,
+  },
+  {
+    v2Key: "consolidation_max_entries_per_run",
+    substrateKey: "consolidation_max_entries_per_run",
+    shippedDefault: 150,
+  },
+  {
+    v2Key: "max_page_chars",
+    substrateKey: "max_page_chars",
+    shippedDefault: 5000,
+  },
+  {
+    v2Key: "consolidation_prompt_path",
+    substrateKey: "consolidation_prompt_path",
+    shippedDefault: null,
+  },
+  { v2Key: "k", substrateKey: "spread_k", shippedDefault: 0.5 },
+  { v2Key: "hops", substrateKey: "spread_hops", shippedDefault: 2 },
+  {
+    v2Key: "ann_candidate_limit",
+    substrateKey: "ann_candidate_limit",
+    shippedDefault: null,
+  },
+];
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Copy user-overridden substrate tunables from `memory.v2` to
+ * `memory.substrate` so the substrate namespace carries the user's tuned
+ * values itself, independent of the runtime resolver's substrate→v2 fallback.
+ *
+ * Value-based, not presence-based: a key is copied only when it is present
+ * under `memory.v2`, absent under `memory.substrate`, AND its value differs
+ * from the shipped v2 schema default. The config loader persists the
+ * fully-parsed configuration for normally-created workspaces, so a defaulted
+ * `memory.v2` leaf in config.json is seeded, not user intent — copying it
+ * would pin the assistant to today's value when substrate defaults are later
+ * retuned (migration 119's rationale). A persisted value equal to its shipped
+ * default is treated as seeded even if a user typed it deliberately — the
+ * acceptable trade-off 119 already makes — so `memory.substrate` stays an
+ * override-only surface. The two no-default keys (`min_sparse_spread`,
+ * `full_sparse_spread`) copy on presence alone.
+ *
+ * That rule is narrower than "explicitly present", and the gap is deliberate:
+ * a value equal to a shipped default never copies, even when the user typed it
+ * on purpose. For every key whose shipped default is the current one that costs
+ * nothing — `memory.substrate` plus the shipped defaults resolve to exactly
+ * what the resolver's fallback produces. `bm25_b`'s retired `0.75` is the sole
+ * exception: it is skipped as seeded yet differs from today's `0.4`, so on a
+ * workspace carrying it the value survives only through the resolver's
+ * `memory.v2` fallback. That is the one case where dropping the fallback would
+ * change behavior — see the equivalence proof in this migration's test.
+ *
+ * `memory.v2.*` is never modified — the v2 injection engine still reads it.
+ * An already-present `memory.substrate` key is never clobbered. `memory.substrate` is only
+ * written at all when at least one key copies, so a fresh config never gains
+ * an empty object.
+ *
+ * Weight-pair safety: copying cannot create an invalid config. The v2
+ * schema's own refinement validates `dense_weight + sparse_weight` on the
+ * PERSISTED values (absent leaves resolve to defaults before the check), so a
+ * valid config carrying a non-default weight necessarily carries its
+ * non-default twin — both differ from their defaults, both copy, and the
+ * copied substrate pair is exactly the pair v2 already accepted.
+ */
+export const copySubstrateTunablesMigration: WorkspaceMigration = {
+  id: "135-copy-substrate-tunables",
+  description:
+    "Copy memory.v2 substrate tunables that differ from their shipped defaults to memory.substrate (k→spread_k, hops→spread_hops) without touching memory.v2, clobbering existing memory.substrate values, or pinning loader-seeded defaults",
+  // run() only ever adds missing memory.substrate keys and never clobbers
+  // present ones, so retrying after a failed write attempt is safe.
+  retryFailedCheckpoint: true,
+
+  run(workspaceDir: string): void {
+    const configPath = join(workspaceDir, "config.json");
+    if (!existsSync(configPath)) {
+      return;
+    }
+
+    // A filesystem read failure propagates so the failed checkpoint retries
+    // on the next boot; only malformed JSON is a permanent no-op (the config
+    // loader owns surfacing that error).
+    const rawText = readFileSync(configPath, "utf-8");
+    let config: Record<string, unknown>;
+    try {
+      const raw = JSON.parse(rawText);
+      if (!isPlainObject(raw)) {
+        return;
+      }
+      config = raw;
+    } catch {
+      return;
+    }
+
+    const memory = config.memory;
+    if (!isPlainObject(memory)) {
+      return;
+    }
+    const v2 = memory.v2;
+    if (!isPlainObject(v2)) {
+      return;
+    }
+    // A malformed (non-object) persisted memory.substrate is left alone — the
+    // config loader surfaces that error; this migration must not clobber it.
+    if (memory.substrate !== undefined && !isPlainObject(memory.substrate)) {
+      return;
+    }
+
+    // Staged separately so memory.substrate is only attached when a key
+    // actually copies — never introduce an empty object.
+    const substrate: Record<string, unknown> = isPlainObject(memory.substrate)
+      ? memory.substrate
+      : {};
+
+    let copied = false;
+    for (const {
+      v2Key,
+      substrateKey,
+      shippedDefault,
+      priorDefaults,
+    } of SUBSTRATE_KEY_PAIRS) {
+      if (!(v2Key in v2) || substrateKey in substrate) {
+        continue;
+      }
+      // A persisted value equal to a shipped default (current or from an
+      // earlier release) is loader-seeded, not a user override — skip it so
+      // the substrate namespace stays override-only. Strict equality
+      // suffices: every tunable value is a primitive or null.
+      const value = v2[v2Key];
+      if (shippedDefault !== NO_DEFAULT && value === shippedDefault) {
+        continue;
+      }
+      if (priorDefaults?.some((seeded) => seeded === value)) {
+        continue;
+      }
+      substrate[substrateKey] = v2[v2Key];
+      copied = true;
+    }
+    if (!copied) {
+      return;
+    }
+    memory.substrate = substrate;
+
+    // Write-then-rename keeps the migration rerunnable: a crash mid-write
+    // must not leave a truncated config.json that a retry reads as malformed
+    // and "completes" past, stranding the user's v2 overrides. A write or
+    // rename failure propagates to the runner, which checkpoints this
+    // migration as failed and (via retryFailedCheckpoint) retries it on the
+    // next boot instead of recording it as completed.
+    const tmpPath = `${configPath}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(config, null, 2) + "\n");
+    renameSync(tmpPath, configPath);
+    log.info(
+      "Copied non-default memory.v2 substrate tunables to memory.substrate",
+    );
+  },
+
+  down(_workspaceDir: string): void {
+    // Forward-only: a copied value is indistinguishable from one the user set
+    // under memory.substrate directly, so removal could destroy deliberate
+    // overrides. The copy is also behavior-preserving, so there is nothing to
+    // unwind.
+  },
+};

package/src/workspace/migrations/__tests__/135-copy-substrate-tunables.test.ts

@@ -0,0 +1,446 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { MemoryConfigSchema } from "../../../config/schemas/memory.js";
+import { MemoryV2ConfigSchema } from "../../../config/schemas/memory-v2.js";
+import {
+  resolveSubstrateTuning,
+  type SubstrateTuning,
+} from "../../../plugins/defaults/memory/substrate/tuning.js";
+import { copySubstrateTunablesMigration as MIG } from "../135-copy-substrate-tunables.js";
+
+let workspaceDir: string;
+let configPath: string;
+
+/** The shipped `memory.v2` defaults, i.e. the effective value of an unset key. */
+const V2_SCHEMA_DEFAULTS = MemoryV2ConfigSchema.parse({});
+
+function pick<T>(
+  substrate: Record<string, unknown>,
+  key: string,
+  fallback: T,
+): T {
+  // Presence, not truthiness: `resolveSubstrateTuning` falls back only on
+  // `undefined`, so an explicit `null` counts as set.
+  return key in substrate ? (substrate[key] as T) : fallback;
+}
+
+/**
+ * `resolveSubstrateTuning` with the `memory.v2` fallback stripped: every
+ * tunable resolves from `memory.substrate` alone, or from the shipped v2
+ * schema default when the substrate key is absent.
+ *
+ * Migration 135's whole purpose is to make this resolver agree with the real
+ * one on a migrated workspace — that agreement is what lets the fallback be
+ * removed later without changing anyone's behavior.
+ */
+function resolveSubstrateOnly(
+  substrate: Record<string, unknown>,
+): SubstrateTuning {
+  const d = V2_SCHEMA_DEFAULTS;
+  return {
+    sweep_enabled: pick(substrate, "sweep_enabled", d.sweep_enabled),
+    dense_weight: pick(substrate, "dense_weight", d.dense_weight),
+    sparse_weight: pick(substrate, "sparse_weight", d.sparse_weight),
+    min_sparse_spread: pick(
+      substrate,
+      "min_sparse_spread",
+      d.min_sparse_spread,
+    ),
+    full_sparse_spread: pick(
+      substrate,
+      "full_sparse_spread",
+      d.full_sparse_spread,
+    ),
+    bm25_k1: pick(substrate, "bm25_k1", d.bm25_k1),
+    bm25_b: pick(substrate, "bm25_b", d.bm25_b),
+    consolidation_interval_hours: pick(
+      substrate,
+      "consolidation_interval_hours",
+      d.consolidation_interval_hours,
+    ),
+    consolidation_max_buffer_lines: pick(
+      substrate,
+      "consolidation_max_buffer_lines",
+      d.consolidation_max_buffer_lines,
+    ),
+    consolidation_max_entries_per_run: pick(
+      substrate,
+      "consolidation_max_entries_per_run",
+      d.consolidation_max_entries_per_run,
+    ),
+    max_page_chars: pick(substrate, "max_page_chars", d.max_page_chars),
+    consolidation_prompt_path: pick(
+      substrate,
+      "consolidation_prompt_path",
+      d.consolidation_prompt_path,
+    ),
+    spread_k: pick(substrate, "spread_k", d.k),
+    spread_hops: pick(substrate, "spread_hops", d.hops),
+    ann_candidate_limit: pick(
+      substrate,
+      "ann_candidate_limit",
+      d.ann_candidate_limit,
+    ),
+  };
+}
+
+function write(obj: unknown): void {
+  writeFileSync(configPath, JSON.stringify(obj, null, 2) + "\n");
+}
+function readRaw(): string {
+  return readFileSync(configPath, "utf-8");
+}
+function read(): Record<string, unknown> {
+  return JSON.parse(readRaw());
+}
+function memory(): Record<string, unknown> {
+  return read().memory as Record<string, unknown>;
+}
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "copy-substrate-tunables-"));
+  configPath = join(workspaceDir, "config.json");
+});
+afterEach(() => {
+  rmSync(workspaceDir, { recursive: true, force: true });
+});
+
+describe("135-copy-substrate-tunables", () => {
+  test("has the expected id", () => {
+    expect(MIG.id).toBe("135-copy-substrate-tunables");
+  });
+
+  test("no-ops when config.json is absent, unparseable, or has no memory config", () => {
+    // Absent config.json.
+    expect(() => MIG.run(workspaceDir)).not.toThrow();
+
+    // Unparseable config.json is left byte-for-byte alone.
+    writeFileSync(configPath, "{not json");
+    MIG.run(workspaceDir);
+    expect(readRaw()).toBe("{not json");
+
+    // No memory config — fresh-workspace shape.
+    write({ llm: { provider: "anthropic" } });
+    const before = readRaw();
+    MIG.run(workspaceDir);
+    expect(readRaw()).toBe(before);
+
+    // memory present but no v2 subtree.
+    write({ memory: { enabled: true } });
+    const beforeNoV2 = readRaw();
+    MIG.run(workspaceDir);
+    expect(readRaw()).toBe(beforeNoV2);
+  });
+
+  test("never introduces memory.substrate when memory.v2 sets no substrate tunables", () => {
+    write({ memory: { v2: { enabled: true, hybrid_min_score: 0.02 } } });
+    const before = readRaw();
+
+    MIG.run(workspaceDir);
+
+    // Nothing copied → no write at all, so no empty substrate object appears.
+    expect(readRaw()).toBe(before);
+  });
+
+  test("copies an explicit memory.v2.consolidation_interval_hours, leaving memory.v2 untouched", () => {
+    write({
+      memory: {
+        v2: { enabled: true, consolidation_interval_hours: 6 },
+      },
+    });
+
+    MIG.run(workspaceDir);
+
+    expect(memory()).toEqual({
+      v2: { enabled: true, consolidation_interval_hours: 6 },
+      substrate: { consolidation_interval_hours: 6 },
+    });
+    // Temp-then-rename persistence leaves no temp file behind on success.
+    expect(existsSync(configPath + ".tmp")).toBe(false);
+  });
+
+  // Root bypasses file permission checks, so chmod cannot make the workspace
+  // read-only — skip rather than assert a failure path that cannot be
+  // exercised.
+  test.skipIf(process.getuid?.() === 0)(
+    "throws on a write failure, leaving config.json byte-for-byte intact (retryable via failed checkpoint)",
+    () => {
+      write({ memory: { v2: { bm25_b: 0.6 } } });
+      const before = readRaw();
+
+      // A read-only workspace dir blocks creation of the config.json.tmp
+      // staging file, standing in for any persistence failure.
+      chmodSync(workspaceDir, 0o555);
+      try {
+        expect(() => MIG.run(workspaceDir)).toThrow();
+      } finally {
+        chmodSync(workspaceDir, 0o755);
+      }
+
+      // The failure surfaces to the runner (failed checkpoint, not completed)
+      // and the migration opts into retrying that checkpoint on the next boot.
+      expect(MIG.retryFailedCheckpoint).toBe(true);
+      // config.json is untouched — the failed write targeted the temp file.
+      expect(readRaw()).toBe(before);
+      expect(existsSync(configPath + ".tmp")).toBe(false);
+
+      // The retry succeeds once the workspace is writable again.
+      MIG.run(workspaceDir);
+      expect(memory().substrate).toEqual({ bm25_b: 0.6 });
+    },
+  );
+
+  // Root bypasses file permission checks, so chmod 0o000 cannot make the
+  // file unreadable — skip rather than assert a failure path that cannot be
+  // exercised.
+  test.skipIf(process.getuid?.() === 0)(
+    "throws on a filesystem read failure so the failed checkpoint retries; malformed JSON stays a no-op",
+    () => {
+      write({ memory: { v2: { bm25_b: 0.6 } } });
+
+      // An unreadable config.json is a transient fs failure, not malformed
+      // content — it must surface to the runner instead of completing.
+      chmodSync(configPath, 0o000);
+      try {
+        expect(() => MIG.run(workspaceDir)).toThrow();
+      } finally {
+        chmodSync(configPath, 0o644);
+      }
+
+      // The retry succeeds once the file is readable again.
+      MIG.run(workspaceDir);
+      expect(memory().substrate).toEqual({ bm25_b: 0.6 });
+    },
+  );
+
+  test("renames k→spread_k and hops→spread_hops; a tuned bm25_b lands on the substrate key", () => {
+    write({
+      memory: {
+        v2: { k: 0.4, hops: 3, bm25_b: 0.6 },
+      },
+    });
+
+    MIG.run(workspaceDir);
+
+    expect(memory().substrate).toEqual({
+      spread_k: 0.4,
+      spread_hops: 3,
+      bm25_b: 0.6,
+    });
+    expect(memory().v2).toEqual({ k: 0.4, hops: 3, bm25_b: 0.6 });
+  });
+
+  test("a migrated workspace resolves identically with the v2 fallback stripped", () => {
+    // A normally-created workspace: loader-seeded defaults alongside real user
+    // overrides, including the two no-default spread keys and the nullable
+    // keys on both sides of the copy rule.
+    write({
+      memory: {
+        v2: {
+          enabled: true,
+          // Seeded defaults — the migration must leave these behind.
+          sweep_enabled: false,
+          dense_weight: 0.85,
+          sparse_weight: 0.15,
+          bm25_k1: 1.2,
+          consolidation_max_entries_per_run: 150,
+          consolidation_prompt_path: null,
+          hops: 2,
+          // User overrides — the migration must carry these across.
+          bm25_b: 0.6,
+          consolidation_interval_hours: 6,
+          consolidation_max_buffer_lines: null,
+          max_page_chars: 9000,
+          k: 0.4,
+          ann_candidate_limit: 500,
+          min_sparse_spread: 0.05,
+          full_sparse_spread: 0.3,
+        },
+      },
+    });
+
+    MIG.run(workspaceDir);
+
+    const parsed = MemoryConfigSchema.parse(memory());
+    const withFallback = resolveSubstrateTuning(parsed);
+    const substrateOnly = resolveSubstrateOnly(
+      memory().substrate as Record<string, unknown>,
+    );
+
+    // The load-bearing claim: after the copy, the substrate namespace plus the
+    // shipped defaults reproduce the resolver's substrate→v2 fallback exactly.
+    expect(substrateOnly).toEqual(withFallback);
+    // Anchored against the operator's actual intent, so the equality above
+    // cannot pass by both sides being wrong in the same way.
+    expect(withFallback.consolidation_interval_hours).toBe(6);
+    expect(withFallback.consolidation_max_buffer_lines).toBeNull();
+    expect(withFallback.spread_k).toBe(0.4);
+    expect(withFallback.spread_hops).toBe(2);
+    expect(withFallback.min_sparse_spread).toBe(0.05);
+  });
+
+  test("bm25_b at the historical 0.75 default is the one value the copy rule cannot carry", () => {
+    // The skip list treats 0.75 as loader-seeded, so it never reaches
+    // memory.substrate and only the fallback keeps it in effect. Recorded here
+    // because it is the single case where dropping the fallback would change
+    // behavior.
+    write({ memory: { v2: { bm25_b: 0.75 } } });
+
+    MIG.run(workspaceDir);
+
+    const parsed = MemoryConfigSchema.parse(memory());
+    expect(resolveSubstrateTuning(parsed).bm25_b).toBe(0.75);
+    expect(resolveSubstrateOnly({}).bm25_b).toBe(0.4);
+  });
+
+  test("never clobbers an already-set memory.substrate key, but still copies its unset siblings", () => {
+    write({
+      memory: {
+        v2: { bm25_b: 0.6, max_page_chars: 9000 },
+        substrate: { bm25_b: 0.3 },
+      },
+    });
+
+    MIG.run(workspaceDir);
+
+    expect(memory().substrate).toEqual({ bm25_b: 0.3, max_page_chars: 9000 });
+    expect(memory().v2).toEqual({ bm25_b: 0.6, max_page_chars: 9000 });
+  });
+
+  test("skips loader-seeded values equal to the shipped defaults, including null-default keys", () => {
+    // The config loader persists the fully-parsed config for normally-created
+    // workspaces, so every defaulted v2 leaf is present in config.json. None
+    // of these are user intent — the migration must not pin them into the
+    // override-only substrate namespace.
+    write({
+      memory: {
+        v2: {
+          enabled: true,
+          sweep_enabled: false,
+          dense_weight: 0.85,
+          sparse_weight: 0.15,
+          bm25_k1: 1.2,
+          bm25_b: 0.4,
+          consolidation_interval_hours: 8,
+          consolidation_max_buffer_lines: 100,
+          consolidation_max_entries_per_run: 150,
+          max_page_chars: 5000,
+          consolidation_prompt_path: null,
+          k: 0.5,
+          hops: 2,
+          ann_candidate_limit: null,
+        },
+      },
+    });
+    const before = readRaw();
+
+    MIG.run(workspaceDir);
+
+    // Nothing differs from a shipped default → no copy, no write at all.
+    expect(readRaw()).toBe(before);
+  });
+
+  test("copies non-default values on nullable keys but skips their seeded null defaults", () => {
+    write({
+      memory: {
+        v2: {
+          ann_candidate_limit: 500,
+          consolidation_prompt_path: null,
+        },
+      },
+    });
+
+    MIG.run(workspaceDir);
+
+    // 500 differs from the shipped null default and copies; the seeded null
+    // equals its default and stays out of the substrate namespace.
+    expect(memory().substrate).toEqual({ ann_candidate_limit: 500 });
+  });
+
+  test("skips bm25_b values seeded by the earlier 0.75 default (multi-default key)", () => {
+    write({
+      memory: {
+        v2: { bm25_b: 0.75, bm25_k1: 1.5 },
+      },
+    });
+
+    MIG.run(workspaceDir);
+
+    // 0.75 matches the pre-migration-075 shipped default and is seeded, not a
+    // user override; the tuned bm25_k1 still copies.
+    expect(memory().substrate).toEqual({ bm25_k1: 1.5 });
+  });
+
+  test("copies the no-default spread keys on presence alone", () => {
+    // min_sparse_spread / full_sparse_spread ship with no schema default, so
+    // the loader never seeds them — raw presence IS user intent.
+    write({
+      memory: {
+        v2: { min_sparse_spread: 0.05, full_sparse_spread: 0.3 },
+      },
+    });
+
+    MIG.run(workspaceDir);
+
+    expect(memory().substrate).toEqual({
+      min_sparse_spread: 0.05,
+      full_sparse_spread: 0.3,
+    });
+  });
+
+  test("a tuned weight pair copies whole and still parses after migration (resolved-pair weight check)", () => {
+    // The v2 refinement validates dense_weight + sparse_weight on the
+    // persisted values, so a valid config with a non-default dense_weight
+    // necessarily persists its non-default twin — both copy, and the copied
+    // substrate pair is exactly the pair v2 already accepted.
+    write({ memory: { v2: { dense_weight: 0.9, sparse_weight: 0.1 } } });
+
+    MIG.run(workspaceDir);
+
+    expect(memory().substrate).toEqual({
+      dense_weight: 0.9,
+      sparse_weight: 0.1,
+    });
+    expect(() => MemoryConfigSchema.parse(memory())).not.toThrow();
+  });
+
+  test("is idempotent — a second run leaves the file byte-for-byte unchanged", () => {
+    write({
+      memory: {
+        v2: { bm25_b: 0.6, k: 0.4, ann_candidate_limit: 500 },
+        substrate: { sweep_enabled: true },
+      },
+    });
+
+    MIG.run(workspaceDir);
+    const afterFirst = readRaw();
+    MIG.run(workspaceDir);
+
+    expect(readRaw()).toBe(afterFirst);
+    expect(memory().substrate).toEqual({
+      sweep_enabled: true,
+      bm25_b: 0.6,
+      spread_k: 0.4,
+      ann_candidate_limit: 500,
+    });
+  });
+
+  test("down() is a forward-only no-op", () => {
+    write({ memory: { v2: { bm25_b: 0.6 }, substrate: { bm25_b: 0.6 } } });
+    const before = readRaw();
+
+    expect(() => MIG.down(workspaceDir)).not.toThrow();
+
+    expect(readRaw()).toBe(before);
+  });
+});

package/src/workspace/migrations/__tests__/backfill-v3-leaves.test.ts

@@ -6,8 +6,8 @@ import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import {
   readPage,
   writePage,
-} from "../../../plugins/defaults/memory/v3/substrate/page-store.js";
-import type { ConceptPageFrontmatter } from "../../../plugins/defaults/memory/v3/substrate/types.js";
+} from "../../../plugins/defaults/memory/substrate/page-store.js";
+import type { ConceptPageFrontmatter } from "../../../plugins/defaults/memory/substrate/types.js";
 import { backfillV3LeavesMigration } from "../092-backfill-v3-leaves.js";
 
 describe("092 backfill v3 leaves", () => {