recallnest 2.2.1 → 2.5.4

package/src/__tests__/temporal-validity.test.ts

@@ -0,0 +1,160 @@
+/**
+ * F3: Temporal Validity Windows — tests for eventTime, validUntil,
+ * retrieval filtering, and auto-GC decay acceleration.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  defaultEvolution,
+  parseEvolution,
+  patchEvolution,
+  type EvolutionMetadata,
+} from "../memory-evolution.js";
+
+// ---------------------------------------------------------------------------
+// Schema: eventTime field
+// ---------------------------------------------------------------------------
+
+describe("F3: eventTime in EvolutionMetadata", () => {
+  test("defaultEvolution includes eventTime: null", () => {
+    const evo = defaultEvolution(1000);
+    expect(evo.eventTime).toBeNull();
+    expect(evo.validFrom).toBe(1000);
+    expect(evo.validUntil).toBeNull();
+  });
+
+  test("parseEvolution extracts eventTime from metadata", () => {
+    const metadata = JSON.stringify({
+      evolution: {
+        status: "active",
+        version: 1,
+        accessCount: 0,
+        lastAccessedAt: null,
+        supersededBy: null,
+        supersedes: null,
+        evolutionNote: null,
+        consolidatedInto: null,
+        contributedToPattern: null,
+        sourceMemories: [],
+        validFrom: 1000,
+        validUntil: null,
+        eventTime: 5000,
+      },
+    });
+    const evo = parseEvolution(metadata);
+    expect(evo.eventTime).toBe(5000);
+  });
+
+  test("parseEvolution defaults eventTime to null when missing", () => {
+    const metadata = JSON.stringify({
+      evolution: {
+        status: "active",
+        version: 1,
+        validFrom: 1000,
+      },
+    });
+    const evo = parseEvolution(metadata);
+    expect(evo.eventTime).toBeNull();
+  });
+
+  test("patchEvolution can set eventTime", () => {
+    const metadata = JSON.stringify({ evolution: defaultEvolution(1000) });
+    const patched = patchEvolution(metadata, { eventTime: 9999 });
+    const evo = parseEvolution(patched);
+    expect(evo.eventTime).toBe(9999);
+  });
+
+  test("patchEvolution can set validUntil", () => {
+    const metadata = JSON.stringify({ evolution: defaultEvolution(1000) });
+    const patched = patchEvolution(metadata, { validUntil: 2000 });
+    const evo = parseEvolution(patched);
+    expect(evo.validUntil).toBe(2000);
+    // Other fields unchanged
+    expect(evo.validFrom).toBe(1000);
+    expect(evo.status).toBe("active");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Retrieval: filterByValidity (unit-level via import)
+// ---------------------------------------------------------------------------
+
+// We test the filterByValidity logic indirectly through the exported
+// parseEvolution + the contract: expired memories get score * 0.2.
+// Direct integration tested via full retriever in separate test files.
+
+describe("F3: validity window logic", () => {
+  function makeEvo(overrides: Partial<EvolutionMetadata> = {}): EvolutionMetadata {
+    return { ...defaultEvolution(1000), ...overrides };
+  }
+
+  test("memory with validUntil in the future is not expired", () => {
+    const now = 5000;
+    const evo = makeEvo({ validUntil: 10000 });
+    // validUntil > now → not expired
+    expect(evo.validUntil).toBeGreaterThan(now);
+  });
+
+  test("memory with validUntil in the past is expired", () => {
+    const now = 5000;
+    const evo = makeEvo({ validUntil: 3000 });
+    // validUntil < now → expired
+    expect(evo.validUntil).toBeLessThan(now);
+  });
+
+  test("memory without validUntil never expires", () => {
+    const evo = makeEvo({ validUntil: null });
+    expect(evo.validUntil).toBeNull();
+  });
+
+  test("point-in-time query: memory valid in range", () => {
+    const evo = makeEvo({ validFrom: 1000, validUntil: 5000 });
+    const queryTime = 3000;
+    expect(evo.validFrom).toBeLessThanOrEqual(queryTime);
+    expect(evo.validUntil).toBeGreaterThanOrEqual(queryTime);
+  });
+
+  test("point-in-time query: memory not yet valid", () => {
+    const evo = makeEvo({ validFrom: 5000, validUntil: 10000 });
+    const queryTime = 3000;
+    expect(evo.validFrom).toBeGreaterThan(queryTime);
+  });
+
+  test("point-in-time query: memory already expired at query time", () => {
+    const evo = makeEvo({ validFrom: 1000, validUntil: 3000 });
+    const queryTime = 5000;
+    expect(evo.validUntil).toBeLessThan(queryTime);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Auto-GC: decay acceleration for expired memories
+// ---------------------------------------------------------------------------
+
+describe("F3: GC decay acceleration", () => {
+  test("expired memory decay score is halved", () => {
+    // Simulate the GC logic: if validUntil < now, decayScore *= 0.5
+    const baseDecayScore = 0.30;
+    const now = 10000;
+    const validUntil = 5000; // expired
+    const adjusted = validUntil < now ? baseDecayScore * 0.5 : baseDecayScore;
+    expect(adjusted).toBe(0.15);
+  });
+
+  test("non-expired memory decay score unchanged", () => {
+    const baseDecayScore = 0.30;
+    const now = 10000;
+    const validUntil = 20000; // still valid
+    const adjusted = validUntil < now ? baseDecayScore * 0.5 : baseDecayScore;
+    expect(adjusted).toBe(0.30);
+  });
+
+  test("memory without validUntil — decay score unchanged", () => {
+    const baseDecayScore = 0.30;
+    const validUntil = null;
+    const adjusted = (validUntil != null && validUntil < Date.now())
+      ? baseDecayScore * 0.5
+      : baseDecayScore;
+    expect(adjusted).toBe(0.30);
+  });
+});

package/src/__tests__/term-registry.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  buildTaskHintTerms,
+  extractTerms,
+  looksLikeContinuityTask,
+  looksLikeRecallOnlyTask,
+  taskCueCoverage,
+} from "../term-registry.js";
+
+describe("term registry", () => {
+  it("extracts compact Chinese and latin cue terms", () => {
+    expect(extractTerms("继续 RecallNest continuity bridge 适配")).toEqual([
+      "继续",
+      "recallnest",
+      "continuity",
+      "bridge",
+      "适配",
+    ]);
+  });
+
+  it("can keep later terms when a wider extraction window is requested", () => {
+    expect(
+      extractTerms(
+        "继续 RecallNest continuity helper boundary audit ranking scoring selection orchestration context composer stable query fallback profile forwarding gap runner isolation",
+        24,
+      ),
+    ).toEqual(expect.arrayContaining([
+      "profile",
+      "forwarding",
+      "runner",
+      "isolation",
+    ]));
+  });
+
+  it("builds task hints for writing prompts across languages", () => {
+    expect(buildTaskHintTerms("continue my AI writing project")).toEqual([
+      "写作",
+      "文章",
+      "语气",
+      "风格",
+      "口语化",
+      "不端着",
+      "ai",
+      "公众号",
+    ]);
+  });
+
+  it("treats recall-only wording differently from writing actions", () => {
+    expect(looksLikeRecallOnlyTask("你还记得我之前的偏好吗")).toBe(true);
+    expect(looksLikeRecallOnlyTask("不要让我重复前情，继续写文章")).toBe(false);
+  });
+
+  it("tracks workflow cue coverage from pattern text", () => {
+    expect(
+      taskCueCoverage(
+        "patterns",
+        "Workflow pattern: Cross-window continuity handoff Tools: resume_context, checkpoint_session, search_memory",
+      ),
+    ).toEqual(["search_memory", "resume_context", "checkpoint"]);
+  });
+
+  it("treats named RecallNest and memory-layer continues as continuity tasks", () => {
+    expect(looksLikeContinuityTask("回到 RecallNest 继续做")).toBe(true);
+    expect(looksLikeContinuityTask("接着弄 RecallNest 那个 memory layer")).toBe(true);
+    expect(looksLikeContinuityTask("把记忆层这条线先续上")).toBe(true);
+    expect(looksLikeContinuityTask("把之前那套 recall 管线先捡起来")).toBe(true);
+    expect(looksLikeContinuityTask("pick up where we left off on RecallNest")).toBe(true);
+    expect(looksLikeContinuityTask("回到 A2A 继续做")).toBe(false);
+    // Status queries are NOT continuation tasks — entity+cases is sufficient
+    expect(looksLikeContinuityTask("RecallNest 现在啥情况")).toBe(false);
+  });
+
+  it("builds RecallNest continuity hints for memory-layer shorthand", () => {
+    expect(buildTaskHintTerms("把刚才那个 memory layer 接回去")).toEqual(expect.arrayContaining([
+      "recallnest",
+      "checkpoint_session",
+      "resume_context",
+      "store_memory",
+    ]));
+  });
+
+  it("builds RecallNest continuity hints for colloquial memory shorthand", () => {
+    expect(buildTaskHintTerms("把那条跨窗口记忆的活接着弄完")).toEqual(expect.arrayContaining([
+      "recallnest",
+      "checkpoint_session",
+      "resume_context",
+    ]));
+    expect(buildTaskHintTerms("把之前那套 recall 管线先捡起来")).toEqual(expect.arrayContaining([
+      "recallnest",
+      "checkpoint_session",
+      "resume_context",
+    ]));
+  });
+
+  it("treats 记忆项目 as continuity task and builds RecallNest hints", () => {
+    expect(looksLikeContinuityTask("那个记忆项目，之前做到哪了")).toBe(true);
+    expect(looksLikeContinuityTask("继续记忆项目")).toBe(true);
+    expect(buildTaskHintTerms("那个记忆项目，之前做到哪了")).toEqual(expect.arrayContaining([
+      "recallnest",
+      "resume_context",
+    ]));
+    expect(buildTaskHintTerms("continue the memory project")).toEqual(expect.arrayContaining([
+      "recallnest",
+    ]));
+  });
+
+  it("treats 跨终端记忆/记忆功能/记忆服务 shorthand as continuity cue", () => {
+    // "还搞吗" is a status question, not a continuation verb — correct to return false
+    expect(looksLikeContinuityTask("那个跨终端记忆还搞吗")).toBe(false);
+    expect(looksLikeContinuityTask("继续那个跨终端记忆")).toBe(true);
+    expect(looksLikeContinuityTask("上次做的那个记忆功能")).toBe(true);
+    expect(looksLikeContinuityTask("之前那个 MCP 记忆服务")).toBe(true);
+    expect(buildTaskHintTerms("那个跨终端记忆还搞吗")).toEqual(expect.arrayContaining([
+      "recallnest",
+    ]));
+    expect(buildTaskHintTerms("上次做的记忆功能")).toEqual(expect.arrayContaining([
+      "recallnest",
+    ]));
+  });
+});

package/src/__tests__/tool-error-surfacing.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "bun:test";
+
+import { registerAdvancedTools } from "../mcp-tools-advanced.js";
+import { registerGovernanceTools } from "../mcp-tools-governance.js";
+import { runToolSafely } from "../error-taxonomy.js";
+
+/**
+ * P1-7 第二阶段回归：验证「主操作错误」与「C 类逻辑失败」经 registerTool 的
+ * runToolSafely 包装后带 isError + reason_code，而不是被 handler 自吞成「看起来成功」的文本。
+ *
+ * 手法：用注入式 registerTool 捕获真实 handler，并复刻生产 registerTool 的 runToolSafely
+ * 包装，使测试看到与生产一致的 isError 行为（无需起 MCP server）。
+ */
+
+interface ToolResult {
+  content: { type: string; text: string }[];
+  isError?: boolean;
+}
+type CapturedHandler = (args: Record<string, unknown>) => Promise<ToolResult>;
+
+function captureTools(
+  register: (deps: any) => void,
+  getComponents: () => unknown,
+): Map<string, CapturedHandler> {
+  const handlers = new Map<string, CapturedHandler>();
+  const deps = {
+    registerTool: (
+      name: string,
+      _desc: string,
+      _schema: unknown,
+      handler: (...a: unknown[]) => unknown,
+    ) => {
+      // 复刻 mcp-server.ts registerTool 的兜底：把 handler 交给 runToolSafely。
+      handlers.set(name, (args) => runToolSafely(name, async () => handler(args)) as Promise<ToolResult>);
+    },
+    getComponents,
+    conflictStore: {},
+    workflowObservationStore: {},
+    getKGExtractor: () => null,
+    getKGStore: () => null,
+  };
+  register(deps as any);
+  return handlers;
+}
+
+describe("memory_drill_down error surfacing (P1-7)", () => {
+  it("surfaces a store error as isError with store_error reason (no swallow)", async () => {
+    const handlers = captureTools(registerAdvancedTools, () => ({
+      store: {
+        getById: async () => {
+          throw new Error("lancedb table read failed");
+        },
+      },
+    }));
+    const drill = handlers.get("memory_drill_down");
+    expect(drill).toBeDefined();
+    const r = await drill!({ id: "abcd1234", level: "full" });
+    expect(r.isError).toBe(true);
+    expect(r.content[0].text).toContain("store_error");
+  });
+
+  it("still returns plain not-found text (read-only, no isError)", async () => {
+    const handlers = captureTools(registerAdvancedTools, () => ({
+      store: { getById: async () => null },
+    }));
+    const r = await handlers.get("memory_drill_down")!({ id: "abcd1234", level: "full" });
+    expect(r.isError).toBeUndefined();
+    expect(r.content[0].text).toContain("No memory found");
+  });
+});
+
+describe("forget_memory error surfacing (P1-7 C 类)", () => {
+  it("throws logic failure into the taxonomy layer (isError) not fake-success text", async () => {
+    const handlers = captureTools(registerAdvancedTools, () => ({
+      // store.get → null ⇒ forgetMemory 早返回 success:false（不触碰 kg/audit）
+      store: { get: async () => null },
+    }));
+    const r = await handlers.get("forget_memory")!({ memoryId: "abcd1234", confirm: false });
+    expect(r.isError).toBe(true);
+    expect(r.content[0].text).toContain("not found");
+  });
+});
+
+describe("manage_alias error surfacing (P1-7 C 类)", () => {
+  it("throws invalid_input on missing add params (not returned as success text)", async () => {
+    const handlers = captureTools(registerGovernanceTools, () => ({}));
+    const r = await handlers.get("manage_alias")!({ action: "add" });
+    expect(r.isError).toBe(true);
+    expect(r.content[0].text).toContain("invalid_input");
+  });
+
+  it("throws invalid_input on missing remove trigger", async () => {
+    const handlers = captureTools(registerGovernanceTools, () => ({}));
+    const r = await handlers.get("manage_alias")!({ action: "remove" });
+    expect(r.isError).toBe(true);
+    expect(r.content[0].text).toContain("invalid_input");
+  });
+});

package/src/__tests__/tool-output-compressor.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect } from "bun:test";
+import { compressToolOutput } from "../tool-output-compressor.js";
+
+describe("compressToolOutput", () => {
+  // ========================================================================
+  // Base64 replacement
+  // ========================================================================
+
+  it("replaces large base64 blocks with size placeholder", () => {
+    const base64 = "A".repeat(2000);
+    const text = `Here is a screenshot:\n${base64}\nEnd of screenshot.`;
+    const result = compressToolOutput(text);
+    expect(result).toContain("[image:");
+    expect(result).toContain("base64");
+    expect(result).not.toContain("AAAA");
+  });
+
+  it("preserves short base64-like strings", () => {
+    const text = "The hash is abc123==";
+    expect(compressToolOutput(text)).toBe(text);
+  });
+
+  // ========================================================================
+  // Git output compression
+  // ========================================================================
+
+  it("compresses git push boilerplate", () => {
+    const text = `$ git push origin main
+Enumerating objects: 5, done.
+Counting objects: 100% (5/5), done.
+Delta compression using up to 8 threads
+Compressing objects: 100% (3/3), done.
+Writing objects: 100% (3/3), 450 bytes | 450.00 KiB/s, done.
+Total 3 (delta 2), reused 0 (delta 0)
+remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
+To github.com:user/repo.git
+   abc1234..def5678  main -> main
+
+Next I'll check the status.`;
+
+    const result = compressToolOutput(text);
+    expect(result).toContain("[git: ok");
+    expect(result).toContain("main");
+    expect(result).not.toContain("Enumerating objects");
+    expect(result).toContain("Next I'll check the status");
+  });
+
+  it("preserves git push failures", () => {
+    const text = `$ git push
+Enumerating objects: 5, done.
+error: failed to push some refs to 'origin'
+hint: Updates were rejected because the tip of your branch is behind -> main`;
+
+    const result = compressToolOutput(text);
+    expect(result).toContain("error");
+    expect(result).toContain("rejected");
+  });
+
+  // ========================================================================
+  // Test output compression
+  // ========================================================================
+
+  it("compresses passing test summary", () => {
+    const text = `$ bun test
+running 15 tests
+test a ... ok
+test b ... ok
+test c ... ok
+test result: ok. 15 passed; 0 failed; 0 ignored
+
+All tests passed.`;
+
+    const result = compressToolOutput(text);
+    expect(result.length).toBeLessThanOrEqual(text.length);
+    expect(result).toContain("All tests passed");
+  });
+
+  it("preserves failing test output", () => {
+    const text = `$ npm test
+Tests: 2 failed, 8 passed
+FAIL src/main.test.ts
+  ✕ should handle edge case`;
+
+    const result = compressToolOutput(text);
+    expect(result).toContain("failed");
+    expect(result).toContain("FAIL");
+  });
+
+  // ========================================================================
+  // Safety: user/AI content untouched
+  // ========================================================================
+
+  it("never modifies plain conversation text", () => {
+    const text = "User: How do I fix this git push error?\n\nAssistant: You need to pull first.";
+    expect(compressToolOutput(text)).toBe(text);
+  });
+
+  it("preserves AI reasoning about tool results", () => {
+    const text = "The test result shows 15 passed, which means our fix works.";
+    expect(compressToolOutput(text)).toBe(text);
+  });
+
+  // ========================================================================
+  // Edge cases
+  // ========================================================================
+
+  it("handles empty input", () => {
+    expect(compressToolOutput("")).toBe("");
+  });
+
+  it("handles short input", () => {
+    expect(compressToolOutput("hi")).toBe("hi");
+  });
+
+  it("handles text without tool outputs", () => {
+    const text = "This is a normal conversation.\nNo tool outputs here.";
+    expect(compressToolOutput(text)).toBe(text);
+  });
+
+  // ========================================================================
+  // Large output truncation
+  // ========================================================================
+
+  it("truncates large unmatched tool output", () => {
+    // Use content with spaces/special chars to avoid base64 regex match
+    const largeOutput = Array.from({ length: 150 }, (_, i) => `line ${i}: some detailed output here`).join("\n");
+    const text = `$ some-command\n${largeOutput}\n\nNext step.`;
+    const result = compressToolOutput(text);
+    expect(result).toContain("[...");
+    expect(result).toContain("chars truncated");
+    expect(result.length).toBeLessThan(text.length);
+  });
+
+  // ========================================================================
+  // 回归：工具输出块位于字符串结尾（原 \z 锚点 bug）
+  // 旧实现 lookahead 末项是 \z（JS 无此锚点 → 当字面字符 z）：
+  //   - 块结尾无字面 z 时整块漏匹配 → 末尾大输出逃过截断
+  //   - 块含字面 z 时惰性匹配在第一个 z 处误截断
+  // 修复为 (?![\s\S])（字符串绝对结尾）后两种都应正确处理。
+  // ========================================================================
+
+  it("truncates a large tool output block that ends the string (no trailing marker)", () => {
+    // 末尾块、无字母 z、后面没有下一个命令/空行大写/## → 旧 \z 实现整块漏匹配
+    const largeOutput = Array.from({ length: 150 }, (_, i) => `line ${i}: detailed output here`).join("\n");
+    const text = `$ some-command\n${largeOutput}`;
+    const result = compressToolOutput(text);
+    expect(result).toContain("chars truncated");
+    expect(result.length).toBeLessThan(text.length);
+  });
+
+  it("does not cut a trailing tool output block at a literal 'z'", () => {
+    // 末尾大块含字母 z → 旧 \z 实现在第一个 z 处截断匹配，导致块太短逃过截断
+    const largeOutput = Array.from({ length: 150 }, (_, i) => `line ${i}: zebra output zone`).join("\n");
+    const text = `$ some-command\n${largeOutput}`;
+    const result = compressToolOutput(text);
+    expect(result).toContain("chars truncated");
+    // 截断尾部应保留块真正的结尾，而不是停在某个 z 之前
+    expect(result).toContain("zone");
+  });
+});

package/src/__tests__/topic-tag.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "bun:test";
+import { detectTopicTag, extractTopicTag, injectTopicTag } from "../topic-tag.js";
+
+describe("detectTopicTag", () => {
+  it("detects auth-related content", () => {
+    expect(detectTopicTag("Implement JWT authentication with OAuth2 flow")).toBe("auth");
+  });
+
+  it("detects deploy-related content", () => {
+    expect(detectTopicTag("Set up CI/CD pipeline with GitHub Actions for production deployment")).toBe("deploy");
+  });
+
+  it("detects infra-related content", () => {
+    expect(detectTopicTag("Configure Docker containers and Kubernetes cluster")).toBe("infra");
+  });
+
+  it("detects testing-related content", () => {
+    expect(detectTopicTag("Write unit tests with bun test and add coverage for the new module")).toBe("testing");
+  });
+
+  it("detects database-related content", () => {
+    expect(detectTopicTag("Run SQL migration to add new columns to postgres users table")).toBe("database");
+  });
+
+  it("detects api-related content", () => {
+    expect(detectTopicTag("Design REST API endpoints for the new webhook integration")).toBe("api");
+  });
+
+  it("detects ui-related content", () => {
+    expect(detectTopicTag("Build React component with Tailwind CSS for the dashboard layout")).toBe("ui");
+  });
+
+  it("detects performance-related content", () => {
+    expect(detectTopicTag("Profile cache hit rates and optimize latency bottleneck")).toBe("perf");
+  });
+
+  it("detects security-related content", () => {
+    expect(detectTopicTag("Fix XSS vulnerability and add CSRF protection")).toBe("security");
+  });
+
+  it("detects memory-related content", () => {
+    expect(detectTopicTag("Improve recall retrieval with better embedding vectors for LanceDB")).toBe("memory");
+  });
+
+  it("detects mcp-related content", () => {
+    expect(detectTopicTag("Register new MCP tool in the Model Context Protocol server")).toBe("mcp");
+  });
+
+  it("detects llm-related content", () => {
+    expect(detectTopicTag("Optimize prompt engineering for better token efficiency with Claude")).toBe("llm");
+  });
+
+  it("returns undefined for generic text", () => {
+    expect(detectTopicTag("Had a great day today")).toBeUndefined();
+  });
+
+  it("returns undefined for empty text", () => {
+    expect(detectTopicTag("")).toBeUndefined();
+  });
+
+  it("picks strongest match when multiple topics present", () => {
+    const tag = detectTopicTag("Deploy the authentication service to production using Docker");
+    expect(tag).toBeDefined();
+    // Multiple topics present; strongest wins
+    expect(["auth", "deploy", "infra"]).toContain(tag);
+  });
+
+  it("handles Chinese text with English tech terms", () => {
+    expect(detectTopicTag("配置 Docker 容器编排和 Kubernetes 集群")).toBe("infra");
+  });
+
+  it("truncates very long text for efficiency", () => {
+    const longText = "Fix authentication bug. ".repeat(500);
+    expect(detectTopicTag(longText)).toBe("auth");
+  });
+});
+
+describe("extractTopicTag", () => {
+  it("extracts topicTag from metadata JSON", () => {
+    expect(extractTopicTag('{"topicTag":"auth","source":"manual"}')).toBe("auth");
+  });
+
+  it("returns undefined when no topicTag", () => {
+    expect(extractTopicTag('{"source":"manual"}')).toBeUndefined();
+  });
+
+  it("returns undefined for invalid JSON", () => {
+    expect(extractTopicTag("not json")).toBeUndefined();
+  });
+
+  it("returns undefined for undefined/null metadata", () => {
+    expect(extractTopicTag(undefined)).toBeUndefined();
+    expect(extractTopicTag("")).toBeUndefined();
+  });
+});
+
+describe("injectTopicTag", () => {
+  it("injects topicTag into metadata JSON", () => {
+    const result = injectTopicTag('{"source":"manual"}', "deploy");
+    const parsed = JSON.parse(result);
+    expect(parsed.topicTag).toBe("deploy");
+    expect(parsed.source).toBe("manual");
+  });
+
+  it("overwrites existing topicTag", () => {
+    const result = injectTopicTag('{"topicTag":"old","source":"manual"}', "new");
+    expect(JSON.parse(result).topicTag).toBe("new");
+  });
+
+  it("returns original on invalid JSON", () => {
+    expect(injectTopicTag("broken", "tag")).toBe("broken");
+  });
+});