@adeu/core 1.25.0 → 1.26.0

package/src/mapper.ts

@@ -9,6 +9,7 @@ import {
   get_run_style_markers,
   get_run_text,
   is_heading_paragraph,
+  split_boundary_whitespace,
   is_native_heading,
   iter_block_items,
   iter_document_parts_with_kind,
@@ -31,6 +32,12 @@ export interface TextSpan {
   part_index: number;
   // True for the read-only image marker projection ![alt](docx-image:N).
   is_image_marker?: boolean;
+  // Character offset of this span's text within its run's projected text.
+  // One run may back several spans: hoisting boundary whitespace outside
+  // style markers (QA 2026-07-19 F-03) projects a bold "The Supplier " run
+  // as core + trailing-space spans, and only the first starts at run
+  // offset 0. All span->run local-offset arithmetic must add this.
+  run_offset?: number;
 }
 
 export function renumber_snapshot_ids(
@@ -411,10 +418,12 @@ export class DocumentMapper {
     let current_wrappers: [string, string] = ["", ""];
     let current_style: [string, string] = ["", ""];
     let active_hyperlink_id: string | null = null;
+    // [kind, text, run, run_offset, ins_id, del_id, comment_ids]
     let pending_runs: [
       string,
       string,
       Run | null,
+      number,
       string | null,
       string | null,
       string[],
@@ -427,7 +436,7 @@ export class DocumentMapper {
         this._add_virtual_text(s_tok, current, paragraph);
         current += s_tok.length;
       }
-      for (const [kind, txt, r_obj, i_id, d_id, c_ids] of pending_runs) {
+      for (const [kind, txt, r_obj, r_off, i_id, d_id, c_ids] of pending_runs) {
         if (kind === "virtual") {
           this._add_virtual_text(txt, current, paragraph, active_hyperlink_id);
         } else {
@@ -442,6 +451,7 @@ export class DocumentMapper {
             hyperlink_id: active_hyperlink_id || undefined,
             comment_ids: c_ids.length > 0 ? c_ids : undefined,
             part_index: this._current_part_index,
+            run_offset: r_off,
           };
           this.spans.push(s);
           this._text_chunks.push(txt);
@@ -473,7 +483,8 @@ export class DocumentMapper {
 
       if (item instanceof Run) {
         const [prefix, suffix] = get_run_style_markers(item, native_heading);
-        const run_parts: [string, string, Run | null][] = [];
+        // [kind, text, run, run_offset]
+        const run_parts: [string, string, Run | null, number][] = [];
         const text = get_run_text(item);
 
         if (leading_strip_active) {
@@ -481,20 +492,50 @@ export class DocumentMapper {
           leading_strip_active = false;
         }
 
+        // run_local tracks each real part's offset within the run's projected
+        // text, so spans resolve back to exact run positions even when one
+        // run backs several spans.
+        let run_local = 0;
+        const append_wrapped = (segment: string): void => {
+          // Boundary whitespace stays OUTSIDE the style markers —
+          // `**The Supplier **` is malformed Markdown (QA 2026-07-19 F-03).
+          // Must mirror apply_formatting_to_segments exactly (the Virtual
+          // Text contract).
+          const [lead, core, trail] = split_boundary_whitespace(segment);
+          if (!core) {
+            run_parts.push(["real", segment, item, run_local]);
+            run_local += segment.length;
+            return;
+          }
+          if (lead) {
+            run_parts.push(["real", lead, item, run_local]);
+            run_local += lead.length;
+          }
+          if (prefix) run_parts.push(["virtual", prefix, null, 0]);
+          run_parts.push(["real", core, item, run_local]);
+          run_local += core.length;
+          if (suffix) run_parts.push(["virtual", suffix, null, 0]);
+          if (trail) {
+            run_parts.push(["real", trail, item, run_local]);
+            run_local += trail.length;
+          }
+        };
+
         if (text.includes("\n") && (prefix || suffix)) {
           const parts = text.split("\n");
           for (let idx = 0; idx < parts.length; idx++) {
-            if (idx > 0) run_parts.push(["real", "\n", item]);
-            if (parts[idx]) {
-              if (prefix) run_parts.push(["virtual", prefix, null]);
-              run_parts.push(["real", parts[idx], item]);
-              if (suffix) run_parts.push(["virtual", suffix, null]);
+            if (idx > 0) {
+              run_parts.push(["real", "\n", item, run_local]);
+              run_local += 1;
             }
+            if (parts[idx]) append_wrapped(parts[idx]);
           }
+        } else if ((prefix || suffix) && text) {
+          append_wrapped(text);
         } else {
-          if (prefix) run_parts.push(["virtual", prefix, null]);
-          if (text) run_parts.push(["real", text, item]);
-          if (suffix) run_parts.push(["virtual", suffix, null]);
+          if (prefix) run_parts.push(["virtual", prefix, null, 0]);
+          if (text) run_parts.push(["real", text, item, 0]);
+          if (suffix) run_parts.push(["virtual", suffix, null, 0]);
         }
 
         if (this.clean_view && Object.keys(active_del).length > 0) {
@@ -542,7 +583,7 @@ export class DocumentMapper {
             }
 
             const curr_comment_ids = Array.from(active_ids);
-            for (const [kind, txt, r_obj] of run_parts) {
+            for (const [kind, txt, r_obj, r_off] of run_parts) {
               if (
                 skip_leading_prefix &&
                 kind === "virtual" &&
@@ -555,6 +596,7 @@ export class DocumentMapper {
                 kind,
                 txt,
                 r_obj,
+                r_off,
                 curr_ins_id,
                 curr_del_id,
                 curr_comment_ids,
@@ -566,11 +608,12 @@ export class DocumentMapper {
             current_wrappers = new_wrappers;
             current_style = new_style;
             const curr_comment_ids = Array.from(active_ids);
-            for (const [kind, txt, r_obj] of run_parts) {
+            for (const [kind, txt, r_obj, r_off] of run_parts) {
               pending_runs.push([
                 kind,
                 txt,
                 r_obj,
+                r_off,
                 curr_ins_id,
                 curr_del_id,
                 curr_comment_ids,
@@ -1108,50 +1151,59 @@ export class DocumentMapper {
     );
     if (affected_spans.length === 0) return [];
 
-    const working_runs = affected_spans
-      .filter((s) => s.run !== null)
-      .map((s) => s.run!);
-    if (working_runs.length === 0) return [];
+    const real_spans = affected_spans.filter((s) => s.run !== null);
+    if (real_spans.length === 0) return [];
+
+    // One run may back several spans (boundary whitespace hoisted outside
+    // style markers projects a run as lead/core/trail spans, QA 2026-07-19
+    // F-03): deduplicate by identity or the run would be split and wrapped
+    // once per span.
+    const working_runs: Run[] = [];
+    for (const s of real_spans) {
+      if (!working_runs.some((r) => r === s.run)) {
+        working_runs.push(s.run!);
+      }
+    }
 
     let dom_modified = false;
 
-    const first_real_span = affected_spans.find((s) => s.run !== null);
+    // 1. Start Split — all local offsets are run-relative: span-relative
+    // position plus the span's own offset within the run.
+    const first_real_span = real_spans[0];
     let start_split_adjustment = 0;
 
-    if (first_real_span) {
-      const local_start = start_idx - first_real_span.start;
-      if (local_start > 0) {
-        const idx_in_working = 0;
-        const [, right_run] = this._split_run_at_index(
-          working_runs[idx_in_working],
-          local_start,
-        );
-        working_runs[idx_in_working] = right_run;
-        dom_modified = true;
-        start_split_adjustment = local_start;
+    const local_start =
+      start_idx - first_real_span.start + (first_real_span.run_offset || 0);
+    if (local_start > 0) {
+      const split_source = working_runs[0];
+      const [, right_run] = this._split_run_at_index(
+        split_source,
+        local_start,
+      );
+      for (let w = 0; w < working_runs.length; w++) {
+        if (working_runs[w] === split_source) working_runs[w] = right_run;
       }
+      dom_modified = true;
+      start_split_adjustment = local_start;
     }
 
-    const last_real_span = [...affected_spans]
-      .reverse()
-      .find((s) => s.run !== null);
-
-    if (last_real_span) {
-      const is_same_run = first_real_span === last_real_span;
-      const run_to_split = working_runs[working_runs.length - 1];
-      let overlap_end = Math.min(last_real_span.end, end_idx);
-      let local_end = overlap_end - last_real_span.start;
+    // 2. End Split
+    const last_real_span = real_spans[real_spans.length - 1];
+    const is_same_run = first_real_span.run === last_real_span.run;
+    const run_to_split = working_runs[working_runs.length - 1];
+    const overlap_end = Math.min(last_real_span.end, end_idx);
+    let local_end =
+      overlap_end - last_real_span.start + (last_real_span.run_offset || 0);
 
-      if (is_same_run && start_split_adjustment > 0) {
-        local_end -= start_split_adjustment;
-      }
+    if (is_same_run && start_split_adjustment > 0) {
+      local_end -= start_split_adjustment;
+    }
 
-      const run_text = get_run_text(run_to_split);
-      if (local_end > 0 && local_end < run_text.length) {
-        const [left_run] = this._split_run_at_index(run_to_split, local_end);
-        working_runs[working_runs.length - 1] = left_run;
-        dom_modified = true;
-      }
+    const run_text = get_run_text(run_to_split);
+    if (local_end > 0 && local_end < run_text.length) {
+      const [left_run] = this._split_run_at_index(run_to_split, local_end);
+      working_runs[working_runs.length - 1] = left_run;
+      dom_modified = true;
     }
 
     if (dom_modified && rebuild_map) {
@@ -1206,7 +1258,7 @@ export class DocumentMapper {
         }
         return [null, span.paragraph];
       } else {
-        const offset = index - span.start;
+        const offset = index - span.start + (span.run_offset || 0);
         const [left] = this._split_run_at_index(span.run, offset);
         if (rebuild_map) this._build_map();
         return [left, span.paragraph];

package/src/repro_qa_report_v7.test.ts

@@ -0,0 +1,380 @@
+// FILE: node/packages/core/src/repro_qa_report_v7.test.ts
+/**
+ * Node-engine repro tests for the 2026-07-19 black-box QA and UX report
+ * (adeu 1.25.0+35c8bb4). Mirrors python/tests/test_repro_qa_report_v7.py
+ * for the findings that live in the shared core engine:
+ *
+ *   F-02  a formatting-only replacement (bold -> italic) inherits the
+ *         replaced span's bold instead of realizing exactly the markers
+ *   F-03  a bold run with boundary whitespace projects as malformed
+ *         Markdown (`**The Supplier **`) in both ingest and mapper
+ *   F-04  an alt-text-only image difference becomes an unappliable edit
+ *   F-06  match_mode=all rebuilds the document map once per occurrence
+ *   F-09  sanitize leaves original comment timestamps un-normalized
+ *   F-13  an invalid regex target is reported as "not found" instead of
+ *         as a regex syntax error
+ *   F-21  edits_applied counts occurrences instead of change objects
+ *
+ * Every test fails against the commit preceding its fix.
+ */
+
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createTestDocument, addParagraph } from "./test-utils.js";
+import { DocumentObject } from "./docx/bridge.js";
+import { DocumentMapper } from "./mapper.js";
+import { RedlineEngine, BatchValidationError } from "./engine.js";
+import { _extractTextFromDoc, ExtractStructure } from "./ingest.js";
+import {
+  generate_structured_edits,
+  collect_media_difference_warnings,
+} from "./diff.js";
+import { zipSync } from "fflate";
+import { finalize_document } from "./sanitize/core.js";
+import { qn } from "./docx/dom.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function addStyledRun(
+  p: Element,
+  text: string,
+  style: { bold?: boolean; italic?: boolean } = {},
+): Element {
+  const xmlDoc = p.ownerDocument!;
+  const r = xmlDoc.createElement("w:r");
+  if (style.bold || style.italic) {
+    const rPr = xmlDoc.createElement("w:rPr");
+    if (style.bold) rPr.appendChild(xmlDoc.createElement("w:b"));
+    if (style.italic) rPr.appendChild(xmlDoc.createElement("w:i"));
+    r.appendChild(rPr);
+  }
+  const t = xmlDoc.createElement("w:t");
+  t.textContent = text;
+  if (text !== text.trim()) t.setAttribute("xml:space", "preserve");
+  r.appendChild(t);
+  p.appendChild(r);
+  return r;
+}
+
+function addEmptyParagraph(doc: DocumentObject): Element {
+  const xmlDoc = doc.element.ownerDocument!;
+  const p = xmlDoc.createElement("w:p");
+  doc.element.appendChild(p);
+  return p;
+}
+
+/** Builds the QA report's F-02 fixture: "Normal before **Important phrase** normal after." */
+async function buildBoldDoc(): Promise<DocumentObject> {
+  const doc = await createTestDocument();
+  const p = addEmptyParagraph(doc);
+  addStyledRun(p, "Normal before ");
+  addStyledRun(p, "Important phrase", { bold: true });
+  addStyledRun(p, " normal after.");
+  return doc;
+}
+
+function cleanText(doc: DocumentObject): string {
+  return _extractTextFromDoc(doc, { cleanView: true, includeAppendix: false }) as string;
+}
+
+// ---------------------------------------------------------------------------
+// F-02: formatting-only replacements realize exactly the requested markers
+// ---------------------------------------------------------------------------
+
+describe("QA v7 F-02: formatting-only replacement fidelity", () => {
+  it("clears inherited bold when the replacement carries explicit italic markers", async () => {
+    const doc = await buildBoldDoc();
+    const engine = new RedlineEngine(doc);
+    engine.process_batch([
+      {
+        type: "modify",
+        target_text: "**Important phrase**",
+        new_text: "_Important phrase_",
+      },
+    ]);
+    engine.accept_all_revisions();
+
+    const accepted = cleanText(doc);
+    expect(accepted).toContain("_Important phrase_");
+    expect(accepted).not.toContain("**");
+  });
+
+  it("clears bold when the replacement removes the markers entirely", async () => {
+    const doc = await buildBoldDoc();
+    const engine = new RedlineEngine(doc);
+    engine.process_batch([
+      {
+        type: "modify",
+        target_text: "**Important phrase**",
+        new_text: "Important phrase",
+      },
+    ]);
+    engine.accept_all_revisions();
+
+    const accepted = cleanText(doc);
+    expect(accepted).toContain("Normal before Important phrase normal after.");
+    expect(accepted).not.toContain("**");
+  });
+
+  it("still inherits bold for unmarked plain-text replacements", async () => {
+    const doc = await buildBoldDoc();
+    const engine = new RedlineEngine(doc);
+    engine.process_batch([
+      { type: "modify", target_text: "Important", new_text: "Critical" },
+    ]);
+    engine.accept_all_revisions();
+    expect(cleanText(doc)).toContain("**Critical phrase**");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// F-03: styled-run boundary whitespace stays outside emphasis markers
+// ---------------------------------------------------------------------------
+
+describe("QA v7 F-03: styled-run boundary whitespace", () => {
+  async function buildBoundaryDoc(): Promise<DocumentObject> {
+    const doc = await createTestDocument();
+    const p = addEmptyParagraph(doc);
+    addStyledRun(p, "The Supplier ", { bold: true });
+    addStyledRun(p, "shall deliver");
+    addStyledRun(p, " the Services by 31 December 2026.", { italic: true });
+    return doc;
+  }
+
+  it("extraction emits valid markdown with whitespace outside the markers", async () => {
+    const doc = await buildBoundaryDoc();
+    const text = (_extractTextFromDoc(doc, { cleanView: false }) as string).trim();
+    expect(text).toBe(
+      "**The Supplier** shall deliver _the Services by 31 December 2026._",
+    );
+  });
+
+  it("mapper projection matches ingest projection (virtual text contract)", async () => {
+    const doc = await buildBoundaryDoc();
+    const ingestText = (_extractTextFromDoc(doc, { cleanView: false }) as string).trim();
+    const mapper = new DocumentMapper(doc);
+    expect(mapper.full_text.trim()).toBe(ingestText);
+  });
+
+  it("plain-text edits across the styled boundary still apply", async () => {
+    const doc = await buildBoundaryDoc();
+    const engine = new RedlineEngine(doc);
+    const stats = engine.process_batch([
+      { type: "modify", target_text: "shall deliver", new_text: "must deliver" },
+    ]);
+    expect(stats.edits_applied).toBe(1);
+    engine.accept_all_revisions();
+    expect(cleanText(doc)).toContain("must deliver");
+  });
+
+  it("whitespace-only styled runs are not wrapped", async () => {
+    const doc = await createTestDocument();
+    const p = addEmptyParagraph(doc);
+    addStyledRun(p, "Alpha");
+    addStyledRun(p, "   ", { bold: true });
+    addStyledRun(p, "Omega");
+    const text = (_extractTextFromDoc(doc, { cleanView: false }) as string).trim();
+    expect(text).toBe("Alpha   Omega");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// F-04: an alt-text-only image difference must not become an edit
+// ---------------------------------------------------------------------------
+
+describe("QA v7 F-04: image alt-text diffs", () => {
+  it("drops hunks that reach inside a read-only image marker, with a warning", () => {
+    const text_orig = "Before image.\n\n![RED logo](docx-image:1)\n\nAfter image.";
+    const text_mod = "Before image.\n\n![BLUE logo](docx-image:1)\n\nAfter image.";
+    const struct = (text: string): ExtractStructure => ({
+      part_ranges: [[0, text.length, "body"]],
+      tables: [],
+    });
+
+    const { edits, warnings } = generate_structured_edits(
+      text_orig,
+      struct(text_orig),
+      text_mod,
+      struct(text_mod),
+    );
+
+    expect(edits).toEqual([]);
+    expect(
+      warnings.some((w) => /alternative text|image/i.test(w)),
+    ).toBe(true);
+  });
+});
+
+describe("QA v7 F-04: media byte differences", () => {
+  const makePkg = (mediaBytes: number[]): Uint8Array =>
+    zipSync({
+      "[Content_Types].xml": new TextEncoder().encode("<Types/>"),
+      "word/document.xml": new TextEncoder().encode("<w:document/>"),
+      "word/media/image1.png": new Uint8Array(mediaBytes),
+    });
+
+  it("warns when embedded media bytes differ", () => {
+    const warnings = collect_media_difference_warnings(
+      makePkg([1, 2, 3]),
+      makePkg([4, 5, 6]),
+    );
+    expect(warnings.length).toBe(1);
+    expect(warnings[0]).toMatch(/embedded media differ/);
+  });
+
+  it("stays silent when media are byte-identical", () => {
+    const warnings = collect_media_difference_warnings(
+      makePkg([1, 2, 3]),
+      makePkg([1, 2, 3]),
+    );
+    expect(warnings).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// F-06: match_mode=all must not rebuild the map once per occurrence
+// ---------------------------------------------------------------------------
+
+describe("QA v7 F-06: all-match application scaling", () => {
+  it("keeps map rebuilds constant as occurrence count grows", async () => {
+    const n = 30;
+    const doc = await createTestDocument();
+    for (let i = 0; i < n; i++) {
+      addParagraph(
+        doc,
+        `Clause ${i}: The party PLACEHOLDER-${String(i).padStart(4, "0")} shall comply. REPLACEME token.`,
+      );
+    }
+    const engine = new RedlineEngine(doc);
+
+    const proto = DocumentMapper.prototype as any;
+    const originalBuild = proto._build_map;
+    let buildCount = 0;
+    proto._build_map = function (this: any) {
+      buildCount += 1;
+      return originalBuild.call(this);
+    };
+
+    let stats: any;
+    try {
+      stats = engine.process_batch([
+        {
+          type: "modify",
+          target_text: "REPLACEME",
+          new_text: "SWAPPED",
+          regex: true,
+          match_mode: "all",
+        },
+      ]);
+    } finally {
+      proto._build_map = originalBuild;
+    }
+
+    expect(stats.edits_skipped).toBe(0);
+    expect(buildCount).toBeLessThan(n);
+
+    engine.accept_all_revisions();
+    const final = cleanText(doc);
+    expect(final.match(/SWAPPED/g)?.length).toBe(n);
+    expect(final).not.toContain("REPLACEME");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// F-09: comment timestamps must be normalized alongside change timestamps
+// ---------------------------------------------------------------------------
+
+describe("QA v7 F-09: comment timestamp normalization", () => {
+  it("normalizes w:date and w16cex:dateUtc in retained comment parts", async () => {
+    const fixturePath = resolve(
+      __dirname,
+      "../../../../shared/fixtures/golden.docx",
+    );
+    const doc = await DocumentObject.load(readFileSync(fixturePath));
+
+    await finalize_document(doc, {
+      filename: "golden.docx",
+      sanitize_mode: "keep-markup",
+    });
+
+    const commentParts = doc.pkg.parts.filter((p) =>
+      p.contentType.includes("comments"),
+    );
+    expect(commentParts.length).toBeGreaterThan(0);
+
+    const dates: string[] = [];
+    for (const part of commentParts) {
+      const xml = part._element.toString();
+      for (const m of xml.matchAll(/(?:w:date|w16cex:dateUtc)="([^"]+)"/g)) {
+        dates.push(m[1]);
+      }
+    }
+    expect(dates.length).toBeGreaterThan(0);
+    for (const d of dates) {
+      expect(d.startsWith("2025-01-01")).toBe(true);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// F-13: invalid regex targets must be diagnosed as regex errors
+// ---------------------------------------------------------------------------
+
+describe("QA v7 F-13: invalid regex diagnosis", () => {
+  it("names the regex problem instead of 'not found'", async () => {
+    const doc = await createTestDocument();
+    addParagraph(doc, "alpha DUPTOKEN one.");
+    const engine = new RedlineEngine(doc);
+
+    let error: BatchValidationError | null = null;
+    try {
+      engine.process_batch([
+        { type: "modify", target_text: "[", new_text: "x", regex: true },
+      ]);
+    } catch (e) {
+      error = e as BatchValidationError;
+    }
+    expect(error).toBeInstanceOf(BatchValidationError);
+    const msg = (error as BatchValidationError).errors.join("\n");
+    expect(msg).toMatch(/regular expression/i);
+    expect(msg).not.toMatch(/not found/i);
+  });
+
+  it("valid regexes still apply", async () => {
+    const doc = await createTestDocument();
+    addParagraph(doc, "alpha DUPTOKEN one.");
+    const engine = new RedlineEngine(doc);
+    const stats = engine.process_batch([
+      { type: "modify", target_text: "DUP\\w+", new_text: "XTOKEN", regex: true },
+    ]);
+    expect(stats.edits_applied).toBe(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// F-21: edits_applied counts change objects, not occurrences
+// ---------------------------------------------------------------------------
+
+describe("QA v7 F-21: edits_applied semantics", () => {
+  it("reports one applied edit with two modified occurrences", async () => {
+    const doc = await createTestDocument();
+    addParagraph(doc, "alpha DUPTOKEN one.");
+    addParagraph(doc, "beta DUPTOKEN two.");
+    const engine = new RedlineEngine(doc);
+    const stats = engine.process_batch([
+      {
+        type: "modify",
+        target_text: "DUPTOKEN",
+        new_text: "NEWTOKEN",
+        match_mode: "all",
+      },
+    ]);
+    expect(stats.edits.length).toBe(1);
+    expect(stats.edits_applied).toBe(1);
+    expect(stats.occurrences_modified).toBe(2);
+    expect(stats.edits[0].occurrences_modified).toBe(2);
+  });
+});

package/src/sanitize/core.ts

@@ -78,6 +78,9 @@ export async function finalize_document(doc: DocumentObject, options: FinalizeOp
   for (const w of transforms.detect_watermarks(doc)) report.warnings.push(w);
 
   report.add_transform_lines(transforms.normalize_change_dates(doc));
+  // Retained comments carry the same when-did-they-work signal in
+  // word/comments.xml as tracked changes do in the body (QA 2026-07-19 F-09).
+  report.add_transform_lines(transforms.normalize_comment_dates(doc));
 
   // Protection (Settings injection)
   if (options.protection_mode === 'read_only' || options.protection_mode === 'encrypt') {

package/src/sanitize/transforms.ts

@@ -417,6 +417,35 @@ export function normalize_change_dates(doc: DocumentObject): string[] {
   return count ? [`Track change timestamps: ${count} normalized`] : [];
 }
 
+/**
+ * Normalize timestamps on RETAINED comments to the fixed sanitize date.
+ * Keep-markup sanitize normalized core and tracked-change timestamps but
+ * left the original comment timestamps in word/comments.xml (w:date) and
+ * word/commentsExtensible.xml (w16cex:dateUtc) — visible through any
+ * extraction and carrying exactly the when-did-they-work signal the other
+ * normalizations remove (QA 2026-07-19 F-09).
+ */
+export function normalize_comment_dates(doc: DocumentObject): string[] {
+  let count = 0;
+  const fixed = "2025-01-01T00:00:00Z";
+  for (const part of doc.pkg.parts) {
+    if (!part.contentType.includes('comments')) continue;
+    for (const el of findAllDescendants(part._element, 'w:comment')) {
+      if (el.hasAttribute('w:date')) {
+        el.setAttribute('w:date', fixed);
+        count++;
+      }
+    }
+    for (const el of findAllDescendants(part._element, 'w16cex:commentExtensible')) {
+      if (el.hasAttribute('w16cex:dateUtc')) {
+        el.setAttribute('w16cex:dateUtc', fixed);
+        count++;
+      }
+    }
+  }
+  return count ? [`Comment timestamps: ${count} normalized`] : [];
+}
+
 export function scrub_doc_properties(doc: DocumentObject): string[] {
   const lines: string[] = [];
   const corePart = doc.pkg.getPartByPath('docProps/core.xml');