@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/config/schemas/__tests__/memory-v3.test.ts

@@ -22,6 +22,7 @@ describe("MemoryV3ConfigSchema", () => {
       needleK: 100,
       denseK: 100,
       replyQueryK: 12,
+      spanQueryK: 0,
       selectorEnabled: true,
       selectorPromptPath: null,
       edge: { hubDegree: 30, seedCount: 18, perSeed: 6, cap: 45 },

package/src/config/schemas/live-voice.ts

@@ -79,7 +79,31 @@ export const LiveVoiceProgressConfigSchema = z
       )
       .default(5_000)
       .describe(
-        "Narrate after this much silence (ms) with the turn still running",
+        "How often (ms) a running turn's silence is checked, and so the soonest new tool activity is narrated",
+      ),
+    maxSilenceMs: z
+      .number({
+        error: "liveVoice.frontModel.progress.maxSilenceMs must be a number",
+      })
+      .int("liveVoice.frontModel.progress.maxSilenceMs must be an integer")
+      .positive(
+        "liveVoice.frontModel.progress.maxSilenceMs must be a positive integer",
+      )
+      .default(35_000)
+      .describe(
+        "Heartbeat ceiling (ms): narrate after this much unbroken silence even when nothing new has happened. Evaluated on the idle tick, so its resolution is idleIntervalMs and it must be at least that long",
+      ),
+    longOpMs: z
+      .number({
+        error: "liveVoice.frontModel.progress.longOpMs must be a number",
+      })
+      .int("liveVoice.frontModel.progress.longOpMs must be an integer")
+      .positive(
+        "liveVoice.frontModel.progress.longOpMs must be a positive integer",
+      )
+      .default(15_000)
+      .describe(
+        "A tool operation that ran at least this long (ms) narrates the moment it completes, without waiting for opsThreshold",
       ),
     minGapMs: z
       .number({
@@ -109,6 +133,14 @@ export const LiveVoiceProgressConfigSchema = z
         "Budget (ms) for LLM-generated progress text — not latency-critical: it speaks into dead air",
       ),
   })
+  // The heartbeat is checked when the idle tick finds the turn silent, so a
+  // ceiling shorter than the tick interval would be missed by up to a full
+  // interval — a promise the cadence cannot keep. Rejecting the combination
+  // beats silently overshooting it.
+  .refine((progress) => progress.maxSilenceMs >= progress.idleIntervalMs, {
+    error:
+      "liveVoice.frontModel.progress.maxSilenceMs must be at least idleIntervalMs — the heartbeat is evaluated on the idle tick",
+  })
   .describe(
     "Progress-narration tuning for live voice sessions (spoken updates during long-running turns)",
   );
@@ -172,12 +204,6 @@ export const LiveVoiceFrontModelConfigSchema = z
       )
       .default(600)
       .describe("Budget (ms) for LLM-generated ack text"),
-    llmAckText: z
-      .boolean({ error: "liveVoice.frontModel.llmAckText must be a boolean" })
-      .default(false)
-      .describe(
-        "Use the front model to phrase spoken acks; static phrases otherwise",
-      ),
     progress: LiveVoiceProgressConfigSchema.default(
       LiveVoiceProgressConfigSchema.parse({}),
     ),

package/src/config/schemas/llm.ts

@@ -39,6 +39,7 @@ export const LLMProvider = z
     "together",
     "litellm",
     "baseten",
+    "poolside",
     // Routing identities rather than adapters: "vellum" = the platform-managed
     // route (upstream derived from the model at dispatch), "chatgpt" = the
     // subscription route to OpenAI. Neither has a PROVIDER_CATALOG entry;

package/src/config/schemas/memory-retrospective.ts

@@ -52,6 +52,19 @@ export const MemoryRetrospectiveConfigSchema = z
         "Cadence of the scheduled retrospective sweep, the timer-driven backstop that re-scans conversations for unprocessed messages the event-driven triggers missed (e.g. a turn that ended in a crash or IPC drop before the post-turn hooks ran). A conversation is only swept when its last retrospective attempt is at least this old, so the sweep never competes with the responsive interval/message_count triggers on active conversations.",
       ),
 
+    sweepLookbackMs: z
+      .number({
+        error: "memory.retrospective.sweepLookbackMs must be a number",
+      })
+      .int("memory.retrospective.sweepLookbackMs must be an integer")
+      .positive(
+        "memory.retrospective.sweepLookbackMs must be a positive integer",
+      )
+      .default(7 * 24 * 60 * 60 * 1000)
+      .describe(
+        "How far back the scheduled retrospective sweep looks for stalled work. The sweep backstops turns that ended abnormally (crash / IPC drop), and such turns are by definition recent — so only conversations whose last message falls inside this window are scanned, and the retrospective job re-applies the same window at execution time so a stale queued backlog is skipped instead of run. Conversations dormant beyond the window are outside the sweep's scope entirely: their unprocessed tails are ordinary end-of-conversation remainders, not stalled work. Values below twice memory.retrospective.sweepIntervalMs are clamped up to that floor — scheduler and queue delay stretch the gap between consecutive scans past the nominal cadence, so a window at or under one interval would leave a permanent blind span between passes.",
+      ),
+
     keepSupersededRuns: z
       .boolean({
         error: "memory.retrospective.keepSupersededRuns must be a boolean",

package/src/config/schemas/memory-substrate.ts

@@ -0,0 +1,183 @@
+import { z } from "zod";
+
+import { WEIGHT_SUM_TOLERANCE } from "./memory-v2.js";
+
+/**
+ * Memory substrate (shared concept-page infrastructure) tuning.
+ *
+ * Every key is optional with no default: an unset key resolves to its
+ * historical `memory.v2` counterpart via `resolveSubstrateTuning` (the
+ * substrate's single config choke point), so the v2 schema keeps supplying
+ * the effective defaults. `spread_k`, `spread_hops`, and
+ * `ann_candidate_limit` map onto `memory.v2.k`, `memory.v2.hops`, and
+ * `memory.v2.ann_candidate_limit` respectively; every other key shares its
+ * name with its `memory.v2` twin.
+ */
+export const MemorySubstrateConfigSchema = z
+  .object({
+    sweep_enabled: z
+      .boolean({ error: "memory.substrate.sweep_enabled must be a boolean" })
+      .optional()
+      .describe(
+        "Whether the idle-debounced memory sweep job is enabled. `remember()` is the primary capture path; opt in only when the model is missing entries the sweep would have caught.",
+      ),
+    dense_weight: z
+      .number({ error: "memory.substrate.dense_weight must be a number" })
+      .min(0, "memory.substrate.dense_weight must be >= 0")
+      .max(1, "memory.substrate.dense_weight must be <= 1")
+      .optional()
+      .describe(
+        "Weight on dense (cosine) similarity in the hybrid retrieval score.",
+      ),
+    sparse_weight: z
+      .number({ error: "memory.substrate.sparse_weight must be a number" })
+      .min(0, "memory.substrate.sparse_weight must be >= 0")
+      .max(1, "memory.substrate.sparse_weight must be <= 1")
+      .optional()
+      .describe(
+        "Weight on sparse (BM25-style) similarity in the hybrid retrieval score — sparse acts as a discriminator for keyword-rich queries.",
+      ),
+    min_sparse_spread: z
+      .number({ error: "memory.substrate.min_sparse_spread must be a number" })
+      .min(0, "memory.substrate.min_sparse_spread must be >= 0")
+      .max(1, "memory.substrate.min_sparse_spread must be <= 1")
+      .optional()
+      .describe(
+        "Adaptive sparse weighting: when the spread (max - min) of normalized sparse scores across the candidate hit set falls below this, sparse contribution collapses to 0. Linear interpolation between this and `full_sparse_spread`. Optional escape hatch — leave unset to use the built-in default.",
+      ),
+    full_sparse_spread: z
+      .number({ error: "memory.substrate.full_sparse_spread must be a number" })
+      .min(0, "memory.substrate.full_sparse_spread must be >= 0")
+      .max(1, "memory.substrate.full_sparse_spread must be <= 1")
+      .optional()
+      .describe(
+        "Adaptive sparse weighting: at or above this spread, sparse weight stays at the configured `sparse_weight`. Optional escape hatch — leave unset to use the built-in default.",
+      ),
+    bm25_k1: z
+      .number({ error: "memory.substrate.bm25_k1 must be a number" })
+      .min(0, "memory.substrate.bm25_k1 must be >= 0")
+      .optional()
+      .describe(
+        "BM25 term-frequency saturation parameter. Increase to make repeated mentions of a term matter more, decrease to flatten the curve.",
+      ),
+    bm25_b: z
+      .number({ error: "memory.substrate.bm25_b must be a number" })
+      .min(0, "memory.substrate.bm25_b must be >= 0")
+      .max(1, "memory.substrate.bm25_b must be <= 1")
+      .optional()
+      .describe(
+        "BM25 document-length normalization. 0 disables length normalization, 1 fully normalizes. Concept-page collections include structured list pages with high information density per word, so values below Lucene's 0.75 default avoid over-penalizing them.",
+      ),
+    consolidation_interval_hours: z
+      .number({
+        error: "memory.substrate.consolidation_interval_hours must be a number",
+      })
+      .int("memory.substrate.consolidation_interval_hours must be an integer")
+      .positive(
+        "memory.substrate.consolidation_interval_hours must be a positive integer",
+      )
+      .optional()
+      .describe(
+        "Hours between scheduled consolidation runs that synthesize buffered memories into concept pages",
+      ),
+    consolidation_max_buffer_lines: z
+      .number({
+        error:
+          "memory.substrate.consolidation_max_buffer_lines must be a number",
+      })
+      .int("memory.substrate.consolidation_max_buffer_lines must be an integer")
+      .positive(
+        "memory.substrate.consolidation_max_buffer_lines must be a positive integer",
+      )
+      .nullable()
+      .optional()
+      .describe(
+        "Size-based trigger for consolidation. When `memory/buffer.md` reaches this many non-empty lines, consolidation runs even if the time-based interval hasn't elapsed. Set to `null` to disable the size trigger and rely solely on `consolidation_interval_hours`.",
+      ),
+    consolidation_max_entries_per_run: z
+      .number({
+        error:
+          "memory.substrate.consolidation_max_entries_per_run must be a number",
+      })
+      .int(
+        "memory.substrate.consolidation_max_entries_per_run must be an integer",
+      )
+      .positive(
+        "memory.substrate.consolidation_max_entries_per_run must be a positive integer",
+      )
+      .nullable()
+      .optional()
+      .describe(
+        "Upper bound on buffer entries one consolidation run may process. When the buffer holds more, the run's cutoff is moved back to the first over-cap entry's timestamp so the overflow is deferred to a follow-up pass. Bounds the context a single agentic run must read after a backlog. Set to `null` to always process the full buffer.",
+      ),
+    max_page_chars: z
+      .number({ error: "memory.substrate.max_page_chars must be a number" })
+      .int("memory.substrate.max_page_chars must be an integer")
+      .positive("memory.substrate.max_page_chars must be a positive integer")
+      .optional()
+      .describe(
+        "Soft upper bound on concept-page body length — pages exceeding this are flagged for split during consolidation",
+      ),
+    consolidation_prompt_path: z
+      .string({
+        error: "memory.substrate.consolidation_prompt_path must be a string",
+      })
+      .nullable()
+      .optional()
+      .describe(
+        "Optional path to a file whose contents replace the bundled consolidation prompt. Relative paths resolve under the workspace root; absolute paths and a leading `~/` (expanded to the home directory) are honored only when they still resolve inside the workspace root — a path that lands outside the workspace (including via symlinks) is rejected. The loaded contents may include `{{CUTOFF}}`, which is substituted with the run's ISO-8601 cutoff timestamp. If the file is rejected, missing, unreadable, or empty, the bundled prompt is used and a warning is logged.",
+      ),
+    spread_k: z
+      .number({ error: "memory.substrate.spread_k must be a number" })
+      .min(0, "memory.substrate.spread_k must be >= 0")
+      .max(1, "memory.substrate.spread_k must be <= 1")
+      .optional()
+      .describe(
+        "Spreading-activation propagation coefficient — fraction of own activation that flows to neighbors per hop. Falls back to `memory.v2.k`.",
+      ),
+    spread_hops: z
+      .number({ error: "memory.substrate.spread_hops must be a number" })
+      .int("memory.substrate.spread_hops must be an integer")
+      .nonnegative("memory.substrate.spread_hops must be non-negative")
+      .optional()
+      .describe(
+        "Maximum BFS distance for spreading activation across the concept graph. Falls back to `memory.v2.hops`.",
+      ),
+    ann_candidate_limit: z
+      .number({
+        error: "memory.substrate.ann_candidate_limit must be a number",
+      })
+      .int("memory.substrate.ann_candidate_limit must be an integer")
+      .positive(
+        "memory.substrate.ann_candidate_limit must be a positive integer",
+      )
+      .nullable()
+      .optional()
+      .describe(
+        "Per-channel cap on the unrestricted ANN candidate query used by memory recall (dense and sparse each return up to this many hits before they are unioned). `null` = unlimited (every page in the concept-page collection is eligible).",
+      ),
+  })
+  .describe(
+    "Memory substrate tuning — overrides for the shared concept-page infrastructure (consolidation, hybrid retrieval, BM25 encoding, sweep). Unset keys resolve to their historical `memory.v2` counterparts.",
+  )
+  .superRefine((config, ctx) => {
+    if (
+      config.dense_weight === undefined ||
+      config.sparse_weight === undefined
+    ) {
+      return;
+    }
+    const hybridSum = config.dense_weight + config.sparse_weight;
+    if (Math.abs(hybridSum - 1.0) >= WEIGHT_SUM_TOLERANCE) {
+      const message = `memory.substrate hybrid weights (dense_weight + sparse_weight) must sum to 1.0 (got ${hybridSum.toFixed(4)})`;
+      for (const path of ["dense_weight", "sparse_weight"] as const) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [path],
+          message,
+        });
+      }
+    }
+  });
+
+export type MemorySubstrateConfig = z.infer<typeof MemorySubstrateConfigSchema>;

package/src/config/schemas/memory-v2.ts

@@ -3,9 +3,10 @@ import { z } from "zod";
 /**
  * Tolerance for floating-point comparisons of weight sums. Using 0.001 lets
  * users specify weights to three decimal places without spurious rejections,
- * while still catching obvious mis-sums.
+ * while still catching obvious mis-sums. Shared with the `memory.substrate`
+ * schema so both namespaces apply the same hybrid-weight refinement.
  */
-const WEIGHT_SUM_TOLERANCE = 0.001;
+export const WEIGHT_SUM_TOLERANCE = 0.001;
 
 /**
  * Default cross-encoder model for memory v2 reranking.

package/src/config/schemas/memory-v3.ts

@@ -252,8 +252,7 @@ export const MemoryV3EntitySchema = z
 /**
  * Per-turn injection-gate tuning: thresholds the retrieval signals must clear
  * for the gate to open and run the selector. The gate runs only when the
- * `memory-v3-injection-gate` feature flag (the rollout switch) AND the
- * `enabled` kill-switch below are both on.
+ * `enabled` kill-switch below is on.
  */
 export const MemoryV3GateSchema = z
   .object({
@@ -261,7 +260,7 @@ export const MemoryV3GateSchema = z
       .boolean({ error: "memory.v3.gate.enabled must be a boolean" })
       .default(true)
       .describe(
-        "Whether the injection gate may run at all. false forces the full selection process every turn regardless of the `memory-v3-injection-gate` feature flag; true (default) defers to the flag.",
+        "Whether the injection gate may run at all. false forces the full selection process every turn; true (default) lets the gate run when the thresholds are met.",
       ),
     denseThreshold: z
       .number({ error: "memory.v3.gate.denseThreshold must be a number" })
@@ -327,7 +326,7 @@ export const MemoryV3GateSchema = z
       ),
   })
   .describe(
-    "Memory v3 per-turn injection gate tuning (thresholds; the gate runs when the `memory-v3-injection-gate` feature flag AND `enabled` are both on).",
+    "Memory v3 per-turn injection gate tuning (thresholds; the gate runs when `enabled` is on).",
   );
 
 // NOTE: a retired `workingSet` sub-config (maxPages/evictWindow for the old
@@ -383,6 +382,14 @@ export const MemoryV3ConfigSchema = z
       .describe(
         "Per-lane article budget for the reply-query finder pass: needle and dense each re-run over the assistant's previous message as separate queries (never concatenated with the user's message). 0 disables the pass. Deliberately small next to needleK/denseK — the pass adds the assistant-side retrieval signal, not a second full sweep.",
       ),
+    spanQueryK: z
+      .number({ error: "memory.v3.spanQueryK must be a number" })
+      .int("memory.v3.spanQueryK must be an integer")
+      .nonnegative("memory.v3.spanQueryK must be a non-negative integer")
+      .default(0)
+      .describe(
+        "Per-chunk article budget for the span-query dense pass: the current message's clause spans (merged into at most 8 contiguous chunks) re-run through the dense lane as separate queries, union-additive into the candidate pool. 0 disables the pass; it is also inert when denseK is 0 or the message yields fewer than two chunks. Deliberately small next to denseK — the pass rescues motifs a long message's single query vector averages away, not a second full sweep.",
+      ),
     selectorEnabled: z
       .boolean({ error: "memory.v3.selectorEnabled must be a boolean" })
       .default(true)

package/src/config/schemas/memory.ts

@@ -17,7 +17,8 @@ import {
   MemorySegmentationConfigSchema,
   QdrantConfigSchema,
 } from "./memory-storage.js";
-import { MemoryV2ConfigSchema } from "./memory-v2.js";
+import { MemorySubstrateConfigSchema } from "./memory-substrate.js";
+import { MemoryV2ConfigSchema, WEIGHT_SUM_TOLERANCE } from "./memory-v2.js";
 import { MemoryV3ConfigSchema } from "./memory-v3.js";
 
 export const MemoryConfigSchema = z
@@ -54,6 +55,9 @@ export const MemoryConfigSchema = z
     summarization: MemorySummarizationConfigSchema.default(
       MemorySummarizationConfigSchema.parse({}),
     ),
+    substrate: MemorySubstrateConfigSchema.default(
+      MemorySubstrateConfigSchema.parse({}),
+    ),
     v2: MemoryV2ConfigSchema.default(MemoryV2ConfigSchema.parse({})),
     v3: MemoryV3ConfigSchema.default(MemoryV3ConfigSchema.parse({})),
     retrospective: MemoryRetrospectiveConfigSchema.default(
@@ -118,6 +122,36 @@ export const MemoryConfigSchema = z
           "memory.retrieval.injection.perTurn.capabilityReserve + serendipitySlots must be less than maxNodes",
       });
     }
+    // Resolved hybrid-weight invariant. `resolveSubstrateTuning` pairs each
+    // `memory.substrate` weight with its `memory.v2` twin on an
+    // undefined-only fallback, so a single substrate weight forms its
+    // effective pair with the v2 value (schema default applied by now). The
+    // substrate schema's own refinement already covers the both-set case, and
+    // the v2 schema covers the neither-set case — this check guards the mixed
+    // case those local refinements cannot see.
+    const substrateDense = config.substrate?.dense_weight;
+    const substrateSparse = config.substrate?.sparse_weight;
+    const oneSubstrateWeightSet =
+      (substrateDense === undefined) !== (substrateSparse === undefined);
+    if (oneSubstrateWeightSet) {
+      const effectiveDense =
+        substrateDense !== undefined ? substrateDense : config.v2.dense_weight;
+      const effectiveSparse =
+        substrateSparse !== undefined
+          ? substrateSparse
+          : config.v2.sparse_weight;
+      const effectiveSum = effectiveDense + effectiveSparse;
+      if (Math.abs(effectiveSum - 1.0) >= WEIGHT_SUM_TOLERANCE) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [
+            "substrate",
+            substrateDense !== undefined ? "dense_weight" : "sparse_weight",
+          ],
+          message: `memory hybrid weights must sum to 1.0 after memory.substrate → memory.v2 fallback (effective dense_weight ${effectiveDense.toFixed(4)} + sparse_weight ${effectiveSparse.toFixed(4)} = ${effectiveSum.toFixed(4)})`,
+        });
+      }
+    }
   });
 
 export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;

package/src/config/schemas/services.ts

@@ -20,7 +20,9 @@ export const VALID_INFERENCE_PROVIDERS = [
   "openrouter",
 ] as const;
 
-const VALID_IMAGE_GEN_PROVIDERS = ["gemini", "openai"] as const;
+// `vellum` generates through the platform runtime proxy; the backend
+// (gemini/openai) derives from the selected model's prefix at request time.
+const VALID_IMAGE_GEN_PROVIDERS = ["vellum", "gemini", "openai"] as const;
 
 /**
  * Derived from `SEARCH_PROVIDER_CATALOG`. Adding a new web-search provider
@@ -51,7 +53,13 @@ const BaseServiceSchema = z.object({
  */
 const InferenceServiceSchema = z.object({});
 
-const ImageGenerationServiceSchema = BaseServiceSchema.extend({
+/**
+ * Image generation carries no `mode`: `provider` is the only axis. `"vellum"`
+ * generates through the platform runtime proxy for the model-appropriate
+ * backend, billed to Vellum credits; `"gemini"`/`"openai"` use the user's
+ * key. A `mode` key sent by an older client is stripped at parse.
+ */
+const ImageGenerationServiceSchema = z.object({
   provider: z.enum(VALID_IMAGE_GEN_PROVIDERS).default("gemini"),
   model: z.string().default(DEFAULT_IMAGE_MODEL),
 });

package/src/config/substrate-twin-shadowing.ts

@@ -0,0 +1,195 @@
+// ---------------------------------------------------------------------------
+// Memory substrate — twin-namespace shadowing detection
+// ---------------------------------------------------------------------------
+
+/** One `memory.v2` tunable's `memory.substrate` twin. */
+interface SubstrateTwin {
+  /** The twin's `memory.substrate` key, e.g. `spread_k` for `k`. */
+  readonly substrateKey: string;
+  /**
+   * Whether the v2 injection engine reads the `memory.v2` key straight out of
+   * its own namespace (`v2/injection.ts`, `v2/activation.ts`,
+   * `v2/backfill-jobs.ts`) rather than through `resolveSubstrateTuning`. For
+   * these keys the two namespaces feed two different consumers, so a
+   * `memory.v2` write retunes the v2 engine while substrate recall keeps
+   * reading the substrate twin — the pair can hold different effective values
+   * at once.
+   */
+  readonly alsoReadByV2Engine: boolean;
+}
+
+/**
+ * `memory.v2` key → its `memory.substrate` twin, for the fifteen substrate
+ * tunables that exist in both namespaces. `k` / `hops` are the historical
+ * `memory.v2` names for `spread_k` / `spread_hops`; every other key shares its
+ * name with its twin.
+ *
+ * Substrate precedence lives in `resolveSubstrateTuning`
+ * (`plugins/defaults/memory/substrate/tuning.ts`), which resolves each tunable
+ * as `memory.substrate.X ?? memory.v2.X`. Twelve keys reach the runtime only
+ * through that resolver; the three carrying `alsoReadByV2Engine` are read a
+ * second time by the live v2 injection engine off `config.memory.v2` directly.
+ *
+ * This table is the config surface's view of the same pairing, kept honest by
+ * `__tests__/substrate-twin-shadowing.test.ts`, which asserts it covers exactly
+ * the `memory.substrate` schema's keys.
+ */
+export const SUBSTRATE_TWIN_BY_V2_KEY: Readonly<Record<string, SubstrateTwin>> =
+  {
+    sweep_enabled: { substrateKey: "sweep_enabled", alsoReadByV2Engine: false },
+    dense_weight: { substrateKey: "dense_weight", alsoReadByV2Engine: false },
+    sparse_weight: { substrateKey: "sparse_weight", alsoReadByV2Engine: false },
+    min_sparse_spread: {
+      substrateKey: "min_sparse_spread",
+      alsoReadByV2Engine: false,
+    },
+    full_sparse_spread: {
+      substrateKey: "full_sparse_spread",
+      alsoReadByV2Engine: false,
+    },
+    bm25_k1: { substrateKey: "bm25_k1", alsoReadByV2Engine: false },
+    bm25_b: { substrateKey: "bm25_b", alsoReadByV2Engine: false },
+    consolidation_interval_hours: {
+      substrateKey: "consolidation_interval_hours",
+      alsoReadByV2Engine: false,
+    },
+    consolidation_max_buffer_lines: {
+      substrateKey: "consolidation_max_buffer_lines",
+      alsoReadByV2Engine: false,
+    },
+    consolidation_max_entries_per_run: {
+      substrateKey: "consolidation_max_entries_per_run",
+      alsoReadByV2Engine: false,
+    },
+    max_page_chars: {
+      substrateKey: "max_page_chars",
+      alsoReadByV2Engine: false,
+    },
+    consolidation_prompt_path: {
+      substrateKey: "consolidation_prompt_path",
+      alsoReadByV2Engine: false,
+    },
+    // The v2 injection engine reads these three off `config.memory.v2`:
+    // `k` / `hops` in `v2/injection.ts` and `v2/backfill-jobs.ts`,
+    // `ann_candidate_limit` in `v2/activation.ts`.
+    k: { substrateKey: "spread_k", alsoReadByV2Engine: true },
+    hops: { substrateKey: "spread_hops", alsoReadByV2Engine: true },
+    ann_candidate_limit: {
+      substrateKey: "ann_candidate_limit",
+      alsoReadByV2Engine: true,
+    },
+  };
+
+/** A `memory.substrate` value set on the twin of a given `memory.v2` key. */
+export type SubstrateShadowing = {
+  /** Dotted path of the twin, e.g. `memory.substrate.spread_k`. */
+  substratePath: string;
+  /** The twin's persisted value — what substrate recall resolves to. */
+  substrateValue: unknown;
+  /**
+   * Whether the v2 injection engine also reads the `memory.v2` key directly,
+   * so the write is not inert (see {@link SubstrateTwin.alsoReadByV2Engine}).
+   */
+  alsoReadByV2Engine: boolean;
+};
+
+function readPlainObject(value: unknown): Record<string, unknown> | undefined {
+  return value != null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/**
+ * The `memory.substrate` twin covering `path`, or `undefined` when `path` is
+ * not a shadowable `memory.v2` tunable or its twin is unset.
+ *
+ * `memory.substrate` is override-only and wins for substrate recall whenever
+ * its key is present — including when it holds an explicit `null`, which
+ * `resolveSubstrateTuning` treats as present. Detection therefore keys on
+ * presence, not truthiness. What that means for the `memory.v2` key depends on
+ * `alsoReadByV2Engine`: for a substrate-only twin the `memory.v2` value has no
+ * remaining consumer, while for the three engine-read twins it still tunes v2
+ * injection.
+ *
+ * `raw` is the unparsed config object (`loadRawConfig()` / the `config_get`
+ * payload), so the check sees exactly what is persisted.
+ */
+export function findSubstrateShadowing(
+  raw: Record<string, unknown>,
+  path: string,
+): SubstrateShadowing | undefined {
+  const segments = path.split(".");
+  if (segments.length !== 3 || segments[0] !== "memory") {
+    return undefined;
+  }
+  const [, namespace, key] = segments as [string, string, string];
+  if (namespace !== "v2") {
+    return undefined;
+  }
+  const twin = SUBSTRATE_TWIN_BY_V2_KEY[key];
+  if (twin === undefined) {
+    return undefined;
+  }
+  const substrate = readPlainObject(readPlainObject(raw.memory)?.substrate);
+  if (!substrate || !(twin.substrateKey in substrate)) {
+    return undefined;
+  }
+  return {
+    substratePath: `memory.substrate.${twin.substrateKey}`,
+    substrateValue: substrate[twin.substrateKey],
+    alsoReadByV2Engine: twin.alsoReadByV2Engine,
+  };
+}
+
+/**
+ * Operator-facing warning for a `config set` on a `memory.v2` tunable whose
+ * `memory.substrate` twin is set.
+ *
+ * Two classes, two messages. A substrate-only twin leaves the write with no
+ * consumer, so the warning names the winning key and the command that actually
+ * retunes it. An engine-read twin (`k`, `hops`, `ann_candidate_limit`) makes
+ * the write effective for v2 injection while substrate recall stays on the
+ * twin, so the warning reports the split rather than a no-op.
+ */
+export function describeShadowedConfigSet(
+  shadowing: SubstrateShadowing,
+  path: string,
+): string {
+  const value = JSON.stringify(shadowing.substrateValue) ?? "undefined";
+  if (shadowing.alsoReadByV2Engine) {
+    return (
+      `${path} is read directly by the memory-v2 injection engine, so this write ` +
+      `does change its behavior. Substrate recall reads ${shadowing.substratePath} ` +
+      `(${value}) instead, so the two can diverge. ` +
+      `Run 'assistant config set ${shadowing.substratePath} <value>' to move substrate recall with it.`
+    );
+  }
+  return (
+    `${shadowing.substratePath} is set (${value}) and takes precedence over ${path}, ` +
+    `so this write does not change the effective value. ` +
+    `Run 'assistant config set ${shadowing.substratePath} <value>' to retune it.`
+  );
+}
+
+/**
+ * Operator-facing annotation for a `config get` of a `memory.v2` tunable whose
+ * `memory.substrate` twin is set — the read-side counterpart of
+ * {@link describeShadowedConfigSet}, split along the same two classes so a read
+ * never confirms a value the runtime ignores nor denies one it honors.
+ */
+export function describeShadowedConfigGet(
+  shadowing: SubstrateShadowing,
+  path: string,
+): string {
+  const value = JSON.stringify(shadowing.substrateValue) ?? "undefined";
+  if (shadowing.alsoReadByV2Engine) {
+    return (
+      `Split: ${shadowing.substratePath} = ${value} is the effective value for ` +
+      `substrate recall, while the memory-v2 injection engine reads ${path} above.`
+    );
+  }
+  return (
+    `Shadowed: ${shadowing.substratePath} = ${value} takes precedence and is ` +
+    `the effective value.`
+  );
+}