@adeu/core 1.16.0 → 1.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adeu/core",
-  "version": "1.16.0",
+  "version": "1.17.1",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/markup.test.ts

@@ -1,10 +1,11 @@
 import { describe, it, expect } from 'vitest';
-import { 
-  _replace_smart_quotes, 
-  _make_fuzzy_regex, 
-  _find_match_in_text, 
-  _build_critic_markup, 
-  apply_edits_to_markdown 
+import {
+  _replace_smart_quotes,
+  _make_fuzzy_regex,
+  _find_match_in_text,
+  _build_critic_markup,
+  apply_edits_to_markdown,
+  format_ambiguity_error
 } from './markup.js';
 import { ModifyText } from './models.js';
 
@@ -147,4 +148,38 @@ describe('apply_edits_to_markdown', () => {
     const result = apply_edits_to_markdown(text, [{ type: 'modify', target_text: target, new_text: newText }]);
     expect(result).toContain(expectedSubstring);
   });
+});
+
+describe('format_ambiguity_error (Turn Loop Trap mitigation)', () => {
+  // Mirror the DPA scenario: the same placeholder appears in multiple clauses.
+  const haystack =
+    'PROVIDER: [official company name] shall process the data. ' +
+    'PROVIDER: [official company name] is the data processor.';
+  const target = 'PROVIDER: [official company name]';
+  const positions: [number, number][] = [
+    [0, target.length],
+    [58, 58 + target.length],
+  ];
+
+  it('names BOTH match_mode escape hatches so the agent can re-call instead of looping', () => {
+    const msg = format_ambiguity_error(1, target, haystack, positions);
+
+    expect(msg).toContain('Edit 1 Failed: Ambiguous match');
+    expect(msg).toContain('appears 2 times');
+
+    // The actionable remediation that breaks the loop.
+    expect(msg).toContain('"match_mode": "all"');
+    expect(msg).toContain('"match_mode": "first"');
+    expect(msg).toContain('ALL 2 occurrences');
+    expect(msg).toContain('FIRST occurrence');
+
+    // The original "add more context" guidance is preserved as a third option.
+    expect(msg).toContain('Please provide more surrounding context');
+  });
+
+  it('still throws for fewer than two matches', () => {
+    expect(() => format_ambiguity_error(1, target, haystack, [[0, 5]])).toThrow(
+      /requires at least 2 matches/,
+    );
+  });
 });

package/src/markup.ts

@@ -422,8 +422,19 @@ export function format_ambiguity_error(
     lines.push(`    ... and ${remaining} more occurrence(s) not shown.`);
   }
 
+  // Tell the agent EXACTLY how to re-call. Without this, agents loop forever
+  // refining target_text/regex because they never learn that match_mode is the
+  // built-in escape hatch for genuine ambiguity.
+  lines.push("  To resolve, re-send this edit using ONE of these strategies:");
   lines.push(
-    "  Please provide more surrounding context in your target_text to uniquely identify the location.",
+    `    1. Set "match_mode": "all" to modify ALL ${total} occurrences (same target_text).`,
+  );
+  lines.push(
+    '    2. Set "match_mode": "first" to modify only the FIRST occurrence (same target_text).',
+  );
+  lines.push(
+    '    3. Please provide more surrounding context in your target_text to uniquely ' +
+      'identify a single location (keep the default "match_mode": "strict").',
   );
 
   return lines.join("\n");

package/src/search_write_engine.test.ts

@@ -25,6 +25,47 @@ describe('Search and Targeted Write Engine', () => {
     expect(() => engine.process_batch(edits)).toThrowError(BatchValidationError);
   });
 
+  it('strict rejection carries match_mode guidance, and the suggested re-call applies (Turn Loop Trap)', async () => {
+    // The DPA scenario: one placeholder repeated across clauses.
+    const doc = await createTestDocument();
+    addParagraph(doc, "PROVIDER: [official company name] shall process the data.");
+    addParagraph(doc, "PROVIDER: [official company name] is the data processor.");
+
+    const engine = new RedlineEngine(doc);
+    const strictEdit: any = {
+      type: 'modify',
+      target_text: "PROVIDER: [official company name]",
+      new_text: "PROVIDER: Acme Corp",
+    };
+
+    // 1. The strict edit is rejected — and the error MUST name the escape hatch
+    // so the agent re-calls instead of looping on context/regex refinement.
+    let caught: BatchValidationError | null = null;
+    try {
+      engine.process_batch([strictEdit]);
+    } catch (e) {
+      caught = e as BatchValidationError;
+    }
+    expect(caught).toBeInstanceOf(BatchValidationError);
+    const msg = caught!.errors.join("\n");
+    expect(msg).toContain("Ambiguous match");
+    expect(msg).toContain('"match_mode": "all"');
+    expect(msg).toContain('"match_mode": "first"');
+
+    // 2. Follow the guidance verbatim — the same target_text with match_mode="all"
+    // applies cleanly and mutates BOTH clauses on the saved document.
+    const doc2 = await createTestDocument();
+    addParagraph(doc2, "PROVIDER: [official company name] shall process the data.");
+    addParagraph(doc2, "PROVIDER: [official company name] is the data processor.");
+    const engine2 = new RedlineEngine(doc2);
+    const stats = engine2.process_batch([{ ...strictEdit, match_mode: 'all' }]);
+    expect(stats.edits[0].occurrences_modified).toBe(2);
+
+    const text = await extractTextFromBuffer(await doc2.save(), true);
+    expect(text.match(/Acme Corp/g)?.length).toBe(2);
+    expect(text).not.toContain("PROVIDER: [official company name]");
+  });
+
   it('match_mode="first" modifies only the first occurrence', async () => {
     const doc = await createTestDocument();
     addParagraph(doc, "This is a repetitive clause.");