@vellumai/assistant 0.7.1 → 0.7.3

package/src/memory/v2/__tests__/sim.test.ts

@@ -60,7 +60,6 @@ const state = {
   embedCalls: [] as Array<{ inputs: unknown[] }>,
   sparseCalls: [] as string[],
   embedReturn: [[0.1, 0.2, 0.3]] as number[][],
-  sparseReturn: { indices: [1, 2, 3], values: [0.5, 0.5, 0.5] },
   // Programmable Qdrant query response — one entry per `using` channel,
   // shifted in order so each test can stage dense + sparse results.
   queryResponses: {
@@ -71,16 +70,6 @@ const state = {
       points: Array<{ score?: number; payload: Record<string, unknown> }>;
     }>,
   },
-  // Separate response queue for the dedicated skills collection so a test
-  // querying both concept pages and skills doesn't have to interleave.
-  skillQueryResponses: {
-    dense: [] as Array<{
-      points: Array<{ score?: number; payload: Record<string, unknown> }>;
-    }>,
-    sparse: [] as Array<{
-      points: Array<{ score?: number; payload: Record<string, unknown> }>;
-    }>,
-  },
   queryCalls: [] as Array<{
     collection: string;
     using: string;
@@ -90,7 +79,7 @@ const state = {
 };
 
 // Re-export every real symbol from the embedding-backend module, overriding
-// only the two we control. Bun's `mock.module` replacement is process-wide,
+// only the one we control. Bun's `mock.module` replacement is process-wide,
 // so a partial mock here would break sibling test files that import other
 // exports from the same module (`selectEmbeddingBackend`, etc.).
 const realEmbeddingBackend = await import("../../embedding-backend.js");
@@ -104,9 +93,23 @@ mock.module("../../embedding-backend.js", () => ({
       vectors: state.embedReturn,
     };
   },
-  generateSparseEmbedding: (text: string) => {
+}));
+
+// `sim.ts` builds the query-side sparse vector via BM25's
+// `generateBm25QueryEmbedding`. Wrap it to record the call text, then
+// delegate to the real implementation so the resulting sparse vector is
+// well-formed. Capture the function reference *before* registering the
+// mock — ESM live bindings resolve through the namespace at call time, so
+// `realSparseBm25.fn(...)` after `mock.module` would route into the
+// mocked version and recurse.
+const realSparseBm25 = await import("../sparse-bm25.js");
+const realGenerateBm25QueryEmbedding =
+  realSparseBm25.generateBm25QueryEmbedding;
+mock.module("../sparse-bm25.js", () => ({
+  ...realSparseBm25,
+  generateBm25QueryEmbedding: (text: string) => {
     state.sparseCalls.push(text);
-    return state.sparseReturn;
+    return realGenerateBm25QueryEmbedding(text);
   },
 }));
 
@@ -134,11 +137,7 @@ class MockQdrantClient {
       filter: params.filter,
     });
     const channel = params.using as "dense" | "sparse";
-    const queue =
-      name === "memory_v2_skills"
-        ? state.skillQueryResponses[channel]
-        : state.queryResponses[channel];
-    return queue.shift() ?? { points: [] };
+    return state.queryResponses[channel].shift() ?? { points: [] };
   }
 }
 
@@ -146,9 +145,7 @@ mock.module("@qdrant/js-client-rest", () => ({
   QdrantClient: MockQdrantClient,
 }));
 
-const { simBatch, simSkillBatch, clamp01 } = await import("../sim.js");
-const { _resetMemoryV2SkillQdrantForTests } =
-  await import("../skill-qdrant.js");
+const { simBatch, clamp01, effectiveWeights } = await import("../sim.js");
 const { _resetMemoryV2QdrantForTests } = await import("../qdrant.js");
 
 // ---------------------------------------------------------------------------
@@ -159,18 +156,14 @@ function resetState(): void {
   state.embedCalls.length = 0;
   state.sparseCalls.length = 0;
   state.embedReturn = [[0.1, 0.2, 0.3]];
-  state.sparseReturn = { indices: [1, 2, 3], values: [0.5, 0.5, 0.5] };
   state.queryResponses.dense.length = 0;
   state.queryResponses.sparse.length = 0;
-  state.skillQueryResponses.dense.length = 0;
-  state.skillQueryResponses.sparse.length = 0;
   state.queryCalls.length = 0;
   // Bun's `mock.module` persists across files in the same process, so the
-  // qdrant modules' singletons may already hold a MockQdrantClient instance
-  // from a sibling test file. Reset both readiness caches so each test in
-  // this file gets a fresh `new QdrantClient()` resolved against our mock.
+  // qdrant module's singleton may already hold a MockQdrantClient instance
+  // from a sibling test file. Reset readiness so each test in this file
+  // gets a fresh `new QdrantClient()` resolved against our mock.
   _resetMemoryV2QdrantForTests();
-  _resetMemoryV2SkillQdrantForTests();
 }
 
 function configWithWeights(
@@ -216,6 +209,120 @@ afterEach(resetState);
 // clamp01
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// effectiveWeights — adaptive sparse weighting
+// ---------------------------------------------------------------------------
+
+describe("effectiveWeights", () => {
+  // The helper takes a generic config, but only reads
+  // `memory.v2.min_sparse_spread` / `full_sparse_spread`. Build a minimal
+  // shape so test cases can opt into custom thresholds vs the built-in
+  // defaults (0.2 / 0.5).
+  function configWithSpreadOverrides(
+    min?: number,
+    full?: number,
+  ): AssistantConfig {
+    return {
+      memory: { v2: { min_sparse_spread: min, full_sparse_spread: full } },
+    } as unknown as AssistantConfig;
+  }
+  const baseConfig = configWithSpreadOverrides();
+
+  test("returns base weights when sparse weight is zero", () => {
+    const result = effectiveWeights(
+      [{ sparseScore: 1 }, { sparseScore: 2 }],
+      2,
+      1.0,
+      0.0,
+      baseConfig,
+    );
+    expect(result.dense).toBe(1.0);
+    expect(result.sparse).toBe(0);
+  });
+
+  test("returns base weights when fewer than 2 sparse-bearing hits", () => {
+    // Single sparse-bearing hit — spread is undefined.
+    const result = effectiveWeights(
+      [{ sparseScore: 5 }, {}],
+      5,
+      0.7,
+      0.3,
+      baseConfig,
+    );
+    expect(result.dense).toBeCloseTo(0.7);
+    expect(result.sparse).toBeCloseTo(0.3);
+    expect(result.spread).toBe(0);
+  });
+
+  test("collapses sparse weight to 0 when spread is below min_sparse_spread", () => {
+    // Three hits with sparseNorm = {0.95, 0.97, 1.0} → spread 0.05 < 0.2.
+    const hits = [
+      { sparseScore: 9.5 },
+      { sparseScore: 9.7 },
+      { sparseScore: 10 },
+    ];
+    const result = effectiveWeights(hits, 10, 0.7, 0.3, baseConfig);
+    expect(result.spread).toBeCloseTo(0.05, 6);
+    expect(result.sparse).toBeCloseTo(0, 6);
+    // Dense compensates: gets the full sparse weight added back.
+    expect(result.dense).toBeCloseTo(1.0, 6);
+  });
+
+  test("preserves base weights when spread reaches full_sparse_spread", () => {
+    // sparseNorm = {0.5, 1.0} → spread 0.5 === default full threshold.
+    const hits = [{ sparseScore: 5 }, { sparseScore: 10 }];
+    const result = effectiveWeights(hits, 10, 0.7, 0.3, baseConfig);
+    expect(result.spread).toBeCloseTo(0.5, 6);
+    expect(result.sparse).toBeCloseTo(0.3, 6);
+    expect(result.dense).toBeCloseTo(0.7, 6);
+  });
+
+  test("interpolates linearly between min and full thresholds", () => {
+    // sparseNorm = {0.65, 1.0} → spread 0.35; midway between 0.2 and 0.5
+    // → factor = 0.5; effSparse = 0.5 * 0.3 = 0.15; effDense = 0.7 + 0.15.
+    const hits = [{ sparseScore: 6.5 }, { sparseScore: 10 }];
+    const result = effectiveWeights(hits, 10, 0.7, 0.3, baseConfig);
+    expect(result.spread).toBeCloseTo(0.35, 6);
+    expect(result.sparse).toBeCloseTo(0.15, 6);
+    expect(result.dense).toBeCloseTo(0.85, 6);
+  });
+
+  test("config overrides min and full thresholds", () => {
+    // Custom: min=0.0, full=1.0 — spread is now in [0, 1] linearly.
+    const config = configWithSpreadOverrides(0.0, 1.0);
+    const hits = [{ sparseScore: 8 }, { sparseScore: 10 }];
+    const result = effectiveWeights(hits, 10, 0.7, 0.3, config);
+    // spread 0.2; factor = 0.2; effSparse = 0.06.
+    expect(result.spread).toBeCloseTo(0.2, 6);
+    expect(result.sparse).toBeCloseTo(0.06, 6);
+    expect(result.dense).toBeCloseTo(0.94, 6);
+  });
+
+  test("falls back to base weights when full <= min (degenerate config)", () => {
+    const config = configWithSpreadOverrides(0.5, 0.3);
+    const hits = [{ sparseScore: 5 }, { sparseScore: 10 }];
+    const result = effectiveWeights(hits, 10, 0.7, 0.3, config);
+    expect(result.sparse).toBeCloseTo(0.3, 6);
+    expect(result.dense).toBeCloseTo(0.7, 6);
+  });
+
+  test("dense + sparse always equals baseDense + baseSparse", () => {
+    // Property check: total weight is preserved across the spread spectrum
+    // so `fused` stays interpretable as a [0, 1] similarity regardless of
+    // how aggressively sparse is collapsed.
+    const cases = [
+      [{ sparseScore: 1 }, { sparseScore: 1.05 }], // tiny spread
+      [{ sparseScore: 1 }, { sparseScore: 5 }], // mid spread
+      [{ sparseScore: 1 }, { sparseScore: 10 }], // full spread
+    ];
+    for (const hits of cases) {
+      const maxSparse = Math.max(...hits.map((h) => h.sparseScore));
+      const result = effectiveWeights(hits, maxSparse, 0.7, 0.3, baseConfig);
+      expect(result.dense + result.sparse).toBeCloseTo(1.0, 6);
+    }
+  });
+});
+
 describe("clamp01", () => {
   test("passes values already in [0, 1] through unchanged", () => {
     expect(clamp01(0)).toBe(0);
@@ -247,6 +354,24 @@ describe("simBatch", () => {
     expect(state.queryCalls).toHaveLength(0);
   });
 
+  test("empty text returns empty map without touching backends", async () => {
+    // Turn 1 has no prior assistant message, so `computeOwnActivation` calls
+    // `simBatch("", slugs, config)`. Gemini rejects empty content with HTTP
+    // 400 — short-circuit here so the activation pipeline doesn't crash.
+    const config = configWithWeights(0.7, 0.3);
+
+    for (const text of ["", "   ", "\n\n"]) {
+      state.embedCalls.length = 0;
+      state.sparseCalls.length = 0;
+      state.queryCalls.length = 0;
+      const out = await simBatch(text, ["alice-vscode"], config);
+      expect(out.size).toBe(0);
+      expect(state.embedCalls).toHaveLength(0);
+      expect(state.sparseCalls).toHaveLength(0);
+      expect(state.queryCalls).toHaveLength(0);
+    }
+  });
+
   test("identical text yields ~1.0 when both channels max out", async () => {
     const config = configWithWeights(0.7, 0.3);
     stageHybridResponse([
@@ -388,162 +513,3 @@ describe("simBatch", () => {
     }
   });
 });
-
-// ---------------------------------------------------------------------------
-// simSkillBatch
-// ---------------------------------------------------------------------------
-
-/**
- * Stage a single hybrid response on the dedicated skills queues. Mirrors
- * `stageHybridResponse` but uses `payload.id` (skills' Qdrant payload key)
- * instead of `payload.slug`.
- */
-function stageSkillHybridResponse(
-  hits: Array<{ id: string; denseScore?: number; sparseScore?: number }>,
-): void {
-  state.skillQueryResponses.dense.push({
-    points: hits
-      .filter((h) => h.denseScore !== undefined)
-      .map((h) => ({ score: h.denseScore, payload: { id: h.id } })),
-  });
-  state.skillQueryResponses.sparse.push({
-    points: hits
-      .filter((h) => h.sparseScore !== undefined)
-      .map((h) => ({ score: h.sparseScore, payload: { id: h.id } })),
-  });
-}
-
-describe("simSkillBatch", () => {
-  test("empty id list returns empty map without touching backends", async () => {
-    const config = configWithWeights(0.7, 0.3);
-
-    const out = await simSkillBatch("anything", [], config);
-
-    expect(out.size).toBe(0);
-    expect(state.embedCalls).toHaveLength(0);
-    expect(state.sparseCalls).toHaveLength(0);
-    expect(state.queryCalls).toHaveLength(0);
-  });
-
-  test("queries the dedicated skills collection and forwards an id-IN filter", async () => {
-    const config = configWithWeights(0.7, 0.3);
-    stageSkillHybridResponse([]);
-
-    await simSkillBatch(
-      "query",
-      ["example-skill-a", "example-skill-b"],
-      config,
-    );
-
-    expect(state.queryCalls).toHaveLength(2);
-    for (const call of state.queryCalls) {
-      expect(call.collection).toBe("memory_v2_skills");
-      // The candidate ids are forwarded as a Qdrant filter so Qdrant scores
-      // exactly the candidate set, not its global top-K. Without this,
-      // candidate ids absent from the global top-K silently score 0.
-      expect(call.filter).toEqual({
-        must: [
-          { key: "id", match: { any: ["example-skill-a", "example-skill-b"] } },
-        ],
-      });
-      // Limit equals the candidate count.
-      expect(call.limit).toBe(2);
-    }
-  });
-
-  test("fuses dense + sparse with the configured weight blend", async () => {
-    const config = configWithWeights(0.4, 0.6);
-    stageSkillHybridResponse([
-      { id: "example-skill-a", denseScore: 0.5, sparseScore: 4 }, // sparse-norm 1.0
-      { id: "example-skill-b", denseScore: 0.25, sparseScore: 2 }, // sparse-norm 0.5
-    ]);
-
-    const out = await simSkillBatch(
-      "query",
-      ["example-skill-a", "example-skill-b"],
-      config,
-    );
-
-    // example-skill-a: 0.4 * 0.5 + 0.6 * 1.0 = 0.8
-    // example-skill-b: 0.4 * 0.25 + 0.6 * 0.5 = 0.4
-    expect(out.get("example-skill-a")).toBeCloseTo(0.8, 6);
-    expect(out.get("example-skill-b")).toBeCloseTo(0.4, 6);
-  });
-
-  test("dense-only and sparse-only hits are handled symmetrically", async () => {
-    const config = configWithWeights(0.7, 0.3);
-    stageSkillHybridResponse([
-      { id: "example-skill-a", denseScore: 0.5 /* sparse omitted */ },
-      { id: "example-skill-b", sparseScore: 8 /* dense omitted */ },
-    ]);
-
-    const out = await simSkillBatch(
-      "query",
-      ["example-skill-a", "example-skill-b"],
-      config,
-    );
-
-    // example-skill-a: 0.7 * 0.5 + 0.3 * 0   = 0.35
-    // example-skill-b: 0.7 * 0   + 0.3 * 1.0 = 0.30 (sparse-norm = 8/8)
-    expect(out.get("example-skill-a")).toBeCloseTo(0.35, 6);
-    expect(out.get("example-skill-b")).toBeCloseTo(0.3, 6);
-  });
-
-  test("forwards candidate ids as the Qdrant restriction; only candidates in result", async () => {
-    // The bug we're guarding against: when the skills collection has more
-    // skills than `ids.length`, calling `hybridQuerySkills` without a filter
-    // returns Qdrant's global top-K. Candidate ids absent from that top-K
-    // would silently score 0. The fix is to forward the candidate ids as a
-    // server-side restriction so Qdrant scores exactly the candidate set.
-    const config = configWithWeights(0.7, 0.3);
-    stageSkillHybridResponse([
-      { id: "example-skill-a", denseScore: 0.5, sparseScore: 1 },
-      // `example-skill-c` would never be returned in production once the
-      // filter is applied; the post-filter in simSkillBatch defensively
-      // drops it even if a stale payload slips through.
-      { id: "example-skill-c", denseScore: 0.9, sparseScore: 1 },
-    ]);
-
-    const out = await simSkillBatch(
-      "query",
-      ["example-skill-a", "example-skill-b"],
-      config,
-    );
-
-    // The Qdrant filter was forwarded — both channels carry the id-IN
-    // restriction matching the caller's candidate set.
-    expect(state.queryCalls).toHaveLength(2);
-    for (const call of state.queryCalls) {
-      expect(call.filter).toEqual({
-        must: [
-          { key: "id", match: { any: ["example-skill-a", "example-skill-b"] } },
-        ],
-      });
-    }
-    // Only candidate ids appear in the result map.
-    expect(out.has("example-skill-a")).toBe(true);
-    expect(out.has("example-skill-c")).toBe(false);
-  });
-
-  test("returned scores are clamped into [0, 1]", async () => {
-    const config = configWithWeights(0.8, 0.5); // intentionally sums to > 1
-    stageSkillHybridResponse([
-      { id: "example-skill-a", denseScore: 1.0, sparseScore: 1 },
-    ]);
-
-    const out = await simSkillBatch("query", ["example-skill-a"], config);
-
-    expect(out.get("example-skill-a")).toBe(1);
-  });
-
-  test("embeds the query text exactly once via dense + sparse backends", async () => {
-    const config = configWithWeights(0.7, 0.3);
-    stageSkillHybridResponse([]);
-
-    await simSkillBatch("hello skill", ["example-skill-a"], config);
-
-    expect(state.embedCalls).toHaveLength(1);
-    expect(state.embedCalls[0].inputs).toEqual(["hello skill"]);
-    expect(state.sparseCalls).toEqual(["hello skill"]);
-  });
-});

package/src/memory/v2/__tests__/skill-store.test.ts

@@ -1,12 +1,17 @@
 /**
  * Tests for `assistant/src/memory/v2/skill-store.ts`.
  *
- * Coverage matrix from PR 5 acceptance criteria:
+ * Coverage matrix:
  *   - `seedV2SkillEntries` enumerates the catalog and calls
- *     `upsertSkillEmbedding` for each enabled skill.
+ *     `upsertConceptPageEmbedding` with `slug: "skills/<id>"` for each
+ *     enabled skill in the unified `memory_v2_concept_pages` collection.
  *   - It skips skills whose declared feature flag is disabled.
- *   - It calls `pruneSkillsExcept` with the active id list.
- *   - It populates the `entries` cache so `getSkillCapability` returns each entry.
+ *   - It calls `pruneSlugsWithPrefixExcept("skills/", ...)` with the active
+ *     id list as suffixes, so stale skill slugs in the unified collection
+ *     get pruned without touching concept-page slugs.
+ *   - It populates the `entries` cache so `getSkillCapability` returns each
+ *     entry — accepting both bare ids (`"example-skill"`) and unified-collection
+ *     slugs (`"skills/example-skill"`).
  *   - It swallows errors from the embedding backend — the function resolves
  *     and the cache is unchanged from prior state.
  *
@@ -29,6 +34,18 @@ mock.module("../../../util/logger.js", () => ({
 // Programmable test state — drives every mocked dependency below.
 // ---------------------------------------------------------------------------
 
+interface UpsertCall {
+  slug: string;
+  dense: number[];
+  sparse: { indices: number[]; values: number[] };
+  updatedAt: number;
+}
+
+interface PruneCall {
+  prefix: string;
+  activeSuffixes: readonly string[];
+}
+
 interface TestState {
   catalog: SkillSummary[];
   resolved: ResolvedSkill[];
@@ -38,14 +55,8 @@ interface TestState {
   embedThrows: Error | null;
   embedReturn: number[][];
   sparseReturn: { indices: number[]; values: number[] };
-  upsertCalls: Array<{
-    id: string;
-    content: string;
-    dense: number[];
-    sparse: { indices: number[]; values: number[] };
-    updatedAt: number;
-  }>;
-  pruneCalls: Array<readonly string[]>;
+  upsertCalls: UpsertCall[];
+  pruneCalls: PruneCall[];
   upsertThrows: Error | null;
 }
 
@@ -99,13 +110,16 @@ mock.module("../../embedding-backend.js", () => ({
   generateSparseEmbedding: () => state.sparseReturn,
 }));
 
-mock.module("../skill-qdrant.js", () => ({
-  upsertSkillEmbedding: async (params: TestState["upsertCalls"][number]) => {
+mock.module("../qdrant.js", () => ({
+  upsertConceptPageEmbedding: async (params: UpsertCall) => {
     if (state.upsertThrows) throw state.upsertThrows;
     state.upsertCalls.push(params);
   },
-  pruneSkillsExcept: async (ids: readonly string[]) => {
-    state.pruneCalls.push(ids);
+  pruneSlugsWithPrefixExcept: async (
+    prefix: string,
+    activeSuffixes: readonly string[],
+  ) => {
+    state.pruneCalls.push({ prefix, activeSuffixes });
   },
 }));
 
@@ -160,7 +174,7 @@ afterEach(resetState);
 // ---------------------------------------------------------------------------
 
 describe("seedV2SkillEntries", () => {
-  test("enumerates the catalog and upserts one point per enabled skill", async () => {
+  test("upserts each enabled skill into the unified collection under skills/<id>", async () => {
     const skillA = makeSummary({
       id: "example-skill-a",
       displayName: "Skill A",
@@ -182,15 +196,16 @@ describe("seedV2SkillEntries", () => {
     await seedV2SkillEntries();
 
     expect(state.upsertCalls).toHaveLength(2);
-    const ids = state.upsertCalls.map((c) => c.id).sort();
-    expect(ids).toEqual(["example-skill-a", "example-skill-b"]);
-
-    // Each upsert carries the per-skill dense + sparse + content payload.
-    const callA = state.upsertCalls.find((c) => c.id === "example-skill-a")!;
+    const slugs = state.upsertCalls.map((c) => c.slug).sort();
+    expect(slugs).toEqual(["skills/example-skill-a", "skills/example-skill-b"]);
+
+    // Each upsert carries the per-skill dense + sparse + updatedAt payload,
+    // keyed under the unified `skills/<id>` slug.
+    const callA = state.upsertCalls.find(
+      (c) => c.slug === "skills/example-skill-a",
+    )!;
     expect(callA.dense).toEqual([0.1, 0.2, 0.3]);
     expect(callA.sparse).toEqual(state.sparseReturn);
-    expect(callA.content).toContain("Skill A");
-    expect(callA.content).toContain("(example-skill-a)");
     expect(callA.updatedAt).toBeGreaterThan(0);
   });
 
@@ -207,12 +222,11 @@ describe("seedV2SkillEntries", () => {
     await seedV2SkillEntries();
 
     expect(state.upsertCalls).toHaveLength(1);
-    expect(state.upsertCalls[0].id).toBe("example-skill-a");
+    expect(state.upsertCalls[0].slug).toBe("skills/example-skill-a");
   });
 
   test("does not re-seed an installed-but-disabled skill from the remote catalog", async () => {
-    // Regression for https://github.com/vellum-ai/vellum-assistant/pull/28635
-    // (Codex P1): if `seenIds` is built only from enabled skills, a locally
+    // Regression: if `seenIds` is built only from enabled skills, a locally
     // installed-but-disabled skill falls through to the catalog loop and gets
     // embedded as if it were a discoverable uninstalled skill — contradicting
     // the user's explicit disablement.
@@ -223,8 +237,6 @@ describe("seedV2SkillEntries", () => {
       { summary: enabledSkill, state: "enabled" },
       { summary: disabledSkill, state: "disabled" },
     ];
-    // The remote catalog also contains the disabled skill (same id) — the
-    // seed function must NOT pull it back in via `getCatalog()`.
     state.fullCatalog = [
       {
         id: "example-skill-b",
@@ -237,7 +249,7 @@ describe("seedV2SkillEntries", () => {
     await seedV2SkillEntries();
 
     expect(state.upsertCalls).toHaveLength(1);
-    expect(state.upsertCalls[0].id).toBe("example-skill-a");
+    expect(state.upsertCalls[0].slug).toBe("skills/example-skill-a");
   });
 
   test("seeds genuinely uninstalled catalog skills alongside enabled installed skills", async () => {
@@ -263,8 +275,11 @@ describe("seedV2SkillEntries", () => {
 
     await seedV2SkillEntries();
 
-    const ids = state.upsertCalls.map((c) => c.id).sort();
-    expect(ids).toEqual(["example-skill-a", "uninstalled-skill"]);
+    const slugs = state.upsertCalls.map((c) => c.slug).sort();
+    expect(slugs).toEqual([
+      "skills/example-skill-a",
+      "skills/uninstalled-skill",
+    ]);
   });
 
   test("skips skills whose declared feature flag is disabled", async () => {
@@ -284,10 +299,10 @@ describe("seedV2SkillEntries", () => {
     await seedV2SkillEntries();
 
     expect(state.upsertCalls).toHaveLength(1);
-    expect(state.upsertCalls[0].id).toBe("example-skill-b");
+    expect(state.upsertCalls[0].slug).toBe("skills/example-skill-b");
   });
 
-  test("calls pruneSkillsExcept with the active id list", async () => {
+  test("calls pruneSlugsWithPrefixExcept with the active id list and the skills/ prefix", async () => {
     const skillA = makeSummary({ id: "example-skill-a" });
     const skillB = makeSummary({ id: "example-skill-b" });
     state.catalog = [skillA, skillB];
@@ -309,13 +324,14 @@ describe("seedV2SkillEntries", () => {
     await seedV2SkillEntries();
 
     expect(state.pruneCalls).toHaveLength(1);
-    expect([...state.pruneCalls[0]].sort()).toEqual([
+    expect(state.pruneCalls[0].prefix).toBe("skills/");
+    expect([...state.pruneCalls[0].activeSuffixes].sort()).toEqual([
       "example-skill-a",
       "example-skill-b",
     ]);
   });
 
-  test("passes only the active (post-flag-filter) ids to pruneSkillsExcept", async () => {
+  test("passes only the active (post-flag-filter) ids to pruneSlugsWithPrefixExcept", async () => {
     const flagged = makeSummary({
       id: "example-skill-a",
       featureFlag: "off-flag",
@@ -327,8 +343,6 @@ describe("seedV2SkillEntries", () => {
       { summary: unflagged, state: "enabled" },
     ];
     state.flagsEnabled = { "off-flag": false };
-    // Remote catalog must be non-empty so catalogAvailable is true and
-    // pruning is not skipped.
     state.fullCatalog = [
       { id: "example-skill-a", name: "example-skill-a", description: "A" },
       { id: "example-skill-b", name: "example-skill-b", description: "B" },
@@ -338,44 +352,35 @@ describe("seedV2SkillEntries", () => {
     await seedV2SkillEntries();
 
     expect(state.pruneCalls).toHaveLength(1);
-    expect([...state.pruneCalls[0]]).toEqual(["example-skill-b"]);
+    expect(state.pruneCalls[0].prefix).toBe("skills/");
+    expect([...state.pruneCalls[0].activeSuffixes]).toEqual([
+      "example-skill-b",
+    ]);
   });
 
-  test("populates the entries cache so getSkillCapability returns each entry", async () => {
+  test("populates the entries cache so getSkillCapability resolves both bare id and unified slug", async () => {
     const skillA = makeSummary({
       id: "example-skill-a",
       displayName: "Skill A",
     });
-    const skillB = makeSummary({
-      id: "example-skill-b",
-      displayName: "Skill B",
-    });
-    state.catalog = [skillA, skillB];
-    state.resolved = [
-      { summary: skillA, state: "enabled" },
-      { summary: skillB, state: "enabled" },
-    ];
-    state.embedReturn = [
-      [0.1, 0.2, 0.3],
-      [0.4, 0.5, 0.6],
-    ];
+    state.catalog = [skillA];
+    state.resolved = [{ summary: skillA, state: "enabled" }];
+    state.embedReturn = [[0.1, 0.2, 0.3]];
 
     expect(getSkillCapability("example-skill-a")).toBeNull();
 
     await seedV2SkillEntries();
 
-    const entryA = getSkillCapability("example-skill-a");
-    const entryB = getSkillCapability("example-skill-b");
-    expect(entryA).not.toBeNull();
-    expect(entryA?.id).toBe("example-skill-a");
-    expect(entryA?.content).toContain("Skill A");
-
-    expect(entryB).not.toBeNull();
-    expect(entryB?.id).toBe("example-skill-b");
-    expect(entryB?.content).toContain("Skill B");
+    // Bare id and unified-slug forms both resolve to the same entry.
+    const byId = getSkillCapability("example-skill-a");
+    const bySlug = getSkillCapability("skills/example-skill-a");
+    expect(byId).not.toBeNull();
+    expect(byId?.id).toBe("example-skill-a");
+    expect(byId?.content).toContain("Skill A");
+    expect(bySlug).toEqual(byId);
 
-    // Unknown ids return null even when the cache is populated.
     expect(getSkillCapability("unknown-skill")).toBeNull();
+    expect(getSkillCapability("skills/unknown-skill")).toBeNull();
   });
 
   test("swallows errors from embedWithBackend and leaves prior cache intact", async () => {
@@ -426,9 +431,10 @@ describe("seedV2SkillEntries", () => {
     await seedV2SkillEntries();
 
     expect(state.upsertCalls).toHaveLength(1);
-    expect(state.upsertCalls[0].id).toBe("remote-only");
+    expect(state.upsertCalls[0].slug).toBe("skills/remote-only");
     expect(state.pruneCalls).toHaveLength(1);
-    expect([...state.pruneCalls[0]]).toEqual(["remote-only"]);
+    expect(state.pruneCalls[0].prefix).toBe("skills/");
+    expect([...state.pruneCalls[0].activeSuffixes]).toEqual(["remote-only"]);
   });
 
   test("skips pruning when catalog fetch returns empty (network failure guard)", async () => {