@adeu/core 1.6.6 → 1.6.8

package/package.json

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

package/src/diff.ts

@@ -248,4 +248,58 @@ export function generate_edits_from_text(original_text: string, modified_text: s
   }
 
   return edits;
+}
+
+export function create_unified_diff(original_text: string, modified_text: string, context_lines: number = 3): string {
+  const dmp = new diff_match_patch.diff_match_patch();
+  const a = dmp.diff_linesToChars_(original_text, modified_text);
+  const diffs = dmp.diff_main(a.chars1, a.chars2, false);
+  dmp.diff_charsToLines_(diffs, a.lineArray);
+  
+  const output: string[] = [];
+  output.push('--- Original');
+  output.push('+++ Modified');
+  
+  let i = 0;
+  while (i < diffs.length) {
+    while (i < diffs.length && diffs[i][0] === 0) i++;
+    if (i >= diffs.length) break;
+    
+    let start = i;
+    let preContext: string[] = [];
+    if (start > 0 && diffs[start - 1][0] === 0) {
+      const lines = diffs[start - 1][1].replace(/\n$/, '').split('\n');
+      preContext = lines.slice(-context_lines);
+    }
+    
+    const chunk: string[] = [];
+    chunk.push(...preContext.map(l => ` ${l}`));
+    
+    while (i < diffs.length) {
+      const [op, text] = diffs[i];
+      const lines = text.replace(/\n$/, '').split('\n');
+      
+      if (op === 0) {
+        if (lines.length > context_lines * 2) break;
+        chunk.push(...lines.map(l => ` ${l}`));
+      } else {
+        const prefix = op === -1 ? '-' : '+';
+        chunk.push(...lines.map(l => `${prefix}${l}`));
+      }
+      i++;
+    }
+    
+    let postContext: string[] = [];
+    if (i < diffs.length && diffs[i][0] === 0) {
+      const lines = diffs[i][1].replace(/\n$/, '').split('\n');
+      postContext = lines.slice(0, context_lines);
+    }
+    chunk.push(...postContext.map(l => ` ${l}`));
+    
+    output.push('@@ ... @@');
+    output.push(...chunk);
+  }
+  
+  if (output.length === 2) return ''; // No changes
+  return output.join('\n');
 }

package/src/docx/bridge.ts

@@ -26,11 +26,12 @@ export class Part {
   public addRelationship(id: string, type: string, target: string, isExternal: boolean = false) {
     this.rels.set(id, new Relationship(id, type, target, isExternal));
     
-    // If this part represents a .rels file, update the XML directly
-    if (this._element.tagName === 'Relationships') {
+    // Directly append the relationship element to the document structure
+    if (this.partname.endsWith('.rels')) {
       const doc = this._element.ownerDocument;
       if (doc) {
-        const relEl = doc.createElement('Relationship');
+        // Use strict namespace to ensure it parses successfully on reload
+        const relEl = doc.createElementNS('http://schemas.openxmlformats.org/package/2006/relationships', 'Relationship');
         relEl.setAttribute('Id', id);
         relEl.setAttribute('Type', type);
         relEl.setAttribute('Target', target);
@@ -176,6 +177,17 @@ export class DocumentObject {
     relsPart.addRelationship(id, relType, target, false);
   }
 
+  public relateToExternal(target: string, relType: string): string {
+    let rId = 1;
+    while (this.part.rels.has(`rId${rId}`)) rId++;
+    const id = `rId${rId}`;
+    
+    this.part.rels.set(id, new Relationship(id, relType, target, true));
+    const relsPart = this.pkg.getOrCreateRelsPart(this.part.partname);
+    relsPart.addRelationship(id, relType, target, true);
+    return id;
+  }
+
   public async save(): Promise<Buffer> {
     for (const part of this.pkg.parts) {
       let xmlStr = serializeXml(part._element.ownerDocument || part._element);

package/src/domain.test.ts

@@ -0,0 +1,280 @@
+import { describe, it, expect } from 'vitest';
+import { createTestDocument, addParagraph } from './test-utils.js';
+import { DocumentObject } from './docx/bridge.js';
+import { extractTextFromBuffer } from './ingest.js';
+import { RedlineEngine, BatchValidationError } from './engine.js';
+import { ModifyText } from './models.js';
+import { split_structural_appendix } from './pagination.js';
+
+function addBookmark(paragraph: Element, name: string, idVal: string = "0", text: string = "") {
+  const doc = paragraph.ownerDocument!;
+  const start = doc.createElement('w:bookmarkStart');
+  start.setAttribute('w:name', name);
+  start.setAttribute('w:id', idVal);
+  paragraph.appendChild(start);
+
+  if (text) {
+    const r = doc.createElement('w:r');
+    const t = doc.createElement('w:t');
+    t.textContent = text;
+    if (text.includes(' ')) t.setAttribute('xml:space', 'preserve');
+    r.appendChild(t);
+    paragraph.appendChild(r);
+  }
+
+  const end = doc.createElement('w:bookmarkEnd');
+  end.setAttribute('w:id', idVal);
+  paragraph.appendChild(end);
+}
+
+function addCrossReference(paragraph: Element, refName: string, text: string) {
+  const doc = paragraph.ownerDocument!;
+  const fld = doc.createElement('w:fldSimple');
+  fld.setAttribute('w:instr', ` REF ${refName} \\h `);
+  const r = doc.createElement('w:r');
+  const t = doc.createElement('w:t');
+  t.textContent = text;
+  if (text.includes(' ')) t.setAttribute('xml:space', 'preserve');
+  r.appendChild(t);
+  fld.appendChild(r);
+  paragraph.appendChild(fld);
+}
+
+function addHyperlink(docObj: DocumentObject, paragraph: Element, url: string, text: string) {
+  const idStr = docObj.relateToExternal(url, 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink');
+
+  const doc = paragraph.ownerDocument!;
+  const hyperlink = doc.createElement('w:hyperlink');
+  hyperlink.setAttribute('r:id', idStr);
+  const r = doc.createElement('w:r');
+  const t = doc.createElement('w:t');
+  t.textContent = text;
+  if (text.includes(' ')) t.setAttribute('xml:space', 'preserve');
+  r.appendChild(t);
+  hyperlink.appendChild(r);
+  paragraph.appendChild(hyperlink);
+}
+
+function setupFootnotesPart(docObj: DocumentObject) {
+  const fnXml = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+    <w:footnotes xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+        <w:footnote w:type="separator" w:id="-1">
+            <w:p><w:r><w:separator/></w:r></w:p>
+        </w:footnote>
+        <w:footnote w:id="1">
+            <w:p><w:r><w:t>Footnote content.</w:t></w:r></w:p>
+        </w:footnote>
+    </w:footnotes>`;
+  
+  const partname = '/word/footnotes.xml';
+  const ctype = 'application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml';
+  const relType = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes';
+
+  const part = docObj.pkg.addPart(partname, ctype, fnXml);
+  docObj.relateTo(part, relType);
+}
+
+async function createDomainSemanticsStream() {
+  const doc = await createTestDocument();
+  
+  // 1. Appendix / Definitions
+  const p1 = addParagraph(doc, "1. Definitions");
+  p1.insertBefore(p1.ownerDocument!.createElement('w:pPr'), p1.firstChild);
+  addParagraph(doc, '"Affiliate" means any entity that controls, is controlled by, or is under common control.');
+  addParagraph(doc, "“Confidential Information” means all non-public information disclosed by one party to the other.");
+  addParagraph(doc, "This paragraph does not define anything.");
+
+  const p2 = addParagraph(doc, "2. Obligations");
+  p2.insertBefore(p2.ownerDocument!.createElement('w:pPr'), p2.firstChild);
+  addParagraph(doc, "The Affiliate shall protect the Confidential Information to the highest standard.");
+
+  // 3. Bookmarks and Cross-References
+  const p3 = addParagraph(doc, "Subject to ");
+  addBookmark(p3, "MyBookmark_1", "1", "Anchored Clause");
+  const r3 = p3.ownerDocument!.createElement('w:r');
+  const t3 = p3.ownerDocument!.createElement('w:t');
+  t3.textContent = ", the parties agree to...";
+  t3.setAttribute('xml:space', 'preserve');
+  r3.appendChild(t3);
+  p3.appendChild(r3);
+
+  const p4 = addParagraph(doc, "As strictly stated in ");
+  addCrossReference(p4, "MyBookmark_1", "Anchored Clause");
+  const r4 = p4.ownerDocument!.createElement('w:r');
+  const t4 = p4.ownerDocument!.createElement('w:t');
+  t4.textContent = ", either party may terminate.";
+  t4.setAttribute('xml:space', 'preserve');
+  r4.appendChild(t4);
+  p4.appendChild(r4);
+
+  // 4. Internal Anchors
+  const pAnchor = addParagraph(doc, "Section 5. Indemnification");
+  addBookmark(pAnchor, "_Ref12345", "0");
+
+  const pNoise = addParagraph(doc, "Some text.");
+  addBookmark(pNoise, "_GoBack", "2");
+  addBookmark(pNoise, "_Toc123456789", "3");
+
+  // 5. Footnotes
+  const pFn = addParagraph(doc, "Sentence with footnote");
+  const rFn = pFn.ownerDocument!.createElement('w:r');
+  const ref = pFn.ownerDocument!.createElement('w:footnoteReference');
+  ref.setAttribute('w:id', "1");
+  rFn.appendChild(ref);
+  pFn.appendChild(rFn);
+  setupFootnotesPart(doc);
+
+  // 6. Links and Cross references
+  const pLink = addParagraph(doc, "Please visit ");
+  addHyperlink(doc, pLink, "https://adeu.com", "Adeu HQ");
+
+  const pXref = addParagraph(doc, "As detailed in ");
+  addCrossReference(pXref, "_Ref12345", "Section 5");
+
+  return doc.save();
+}
+
+describe('Domain Semantics Engine', () => {
+  it('extracts and projects structural appendix and diagnostics correctly', async () => {
+    const buf = await createDomainSemanticsStream();
+    const text = await extractTextFromBuffer(buf);
+
+    expect(text).toContain("<!-- READONLY_BOUNDARY_START -->");
+    expect(text).toContain("# Document Structure (Read-Only)");
+
+    // Definitions
+    expect(text).toContain("## Defined Terms");
+    expect(text).toContain('"Affiliate"');
+    expect(text).toContain('"Confidential Information"');
+    expect(text).toContain("used 1 times");
+
+    // Named Anchors & Back-References
+    expect(text).toContain("## Named Anchors");
+    expect(text).toContain("MyBookmark_1");
+    expect(text).toContain("Anchored to:");
+    expect(text).toContain("Referenced from:");
+
+    // Internal anchors & Noise suppression
+    expect(text).toContain("{#_Ref12345}");
+    expect(text).toContain("Section 5. Indemnification{#_Ref12345}");
+    expect(text).not.toContain("{#_GoBack}");
+    expect(text).not.toContain("{#_Toc123456789}");
+
+    // Footnotes
+    expect(text).toContain("[^fn-1]");
+    expect(text).toContain("## Footnotes");
+    expect(text).toContain("[^fn-1]: Footnote content.");
+
+    // Links
+    expect(text).toContain("[Adeu HQ](https://adeu.com)");
+    expect(text).toContain("[~Section 5~](#_Ref12345)");
+  });
+
+  const edgeCases = [
+    { target: "# Document Structure (Read-Only)", newText: "# Modified Document Structure", errChecker: (m: string) => m.includes('read-only boundary') || m.includes('appendix') },
+    { target: "Sentence with footnote[^fn-1]", newText: "Sentence with footnote", errChecker: (m: string) => m.includes('footnote') && (m.includes('delete') || m.includes('remove')) },
+    { target: "Sentence with footnote", newText: "Sentence with footnote[^fn-99]", errChecker: (m: string) => m.includes('footnote') && (m.includes('insert') || m.includes('create')) },
+    { target: "Some text.", newText: "Some text.{#_Ref99999}", errChecker: (m: string) => m.includes('anchor') },
+    { target: "Section 5. Indemnification{#_Ref12345}", newText: "Section 5. Indemnification{#_Ref99999}", errChecker: (m: string) => m.includes('anchor') },
+    { target: "[~Section 5~](#_Ref12345)", newText: "[~Section 6~](#_Ref12345)", errChecker: (m: string) => m.includes('cross-reference') || m.includes('rejected') },
+    { target: "[~Section 5~](#_Ref12345)", newText: "[~Section 5~](#_Ref99999)", errChecker: (m: string) => m.includes('dependency corruption') || m.includes('rejected') },
+    { target: "As detailed in [~Section 5~](#_Ref12345)", newText: "As detailed in [~Section 5~](#_Ref12345) and [~Section 6~](#_Ref999)", errChecker: (m: string) => m.includes('cross-reference') || m.includes('read-only') },
+    { target: "As detailed in [~Section 5~](#_Ref12345)", newText: "As detailed in nothing", errChecker: (m: string) => m.includes('cross-reference') || m.includes('delete') },
+    { target: "Please visit [Adeu HQ](https://adeu.com)", newText: "Please visit [Adeu HQ](https://adeu.com) and [Google](https://google.com)", errChecker: (m: string) => m.includes('hyperlink') || m.includes('insert') },
+    { target: "Please visit [Adeu HQ](https://adeu.com)", newText: "Please visit nothing", errChecker: (m: string) => m.includes('hyperlink') || m.includes('delete') },
+  ];
+
+  for (const tc of edgeCases) {
+    it(`rejects invalid edits: ${tc.target} -> ${tc.newText}`, async () => {
+      const buf = await createDomainSemanticsStream();
+      const doc = await DocumentObject.load(buf);
+      const engine = new RedlineEngine(doc);
+      const edit: ModifyText = { type: 'modify', target_text: tc.target, new_text: tc.newText };
+
+      let errorThrown = false;
+      try {
+        engine.process_batch([edit]);
+      } catch (e) {
+        errorThrown = true;
+        if (e instanceof BatchValidationError) {
+          const msg = e.errors.join('\n').toLowerCase();
+          expect(tc.errChecker(msg)).toBe(true);
+        } else {
+          throw e; // unexpected error
+        }
+      }
+      expect(errorThrown).toBe(true);
+    });
+  }
+
+  it('safely edits footnotes and accepts changes', async () => {
+    const buf = await createDomainSemanticsStream();
+    const doc = await DocumentObject.load(buf);
+    const engine = new RedlineEngine(doc);
+
+    const edit: ModifyText = { type: 'modify', target_text: "Footnote content.", new_text: "This is an edited footnote." };
+    const stats = engine.process_batch([edit]);
+    expect(stats.edits_applied).toBe(1);
+
+    engine.accept_all_revisions();
+    const outBuf = await doc.save();
+    const cleanText = await extractTextFromBuffer(outBuf, true);
+    
+    expect(cleanText).toContain("[^fn-1]: This is an edited footnote.");
+  });
+
+  it('extracts defined terms and finds typos correctly', async () => {
+    const doc = await createTestDocument();
+    addParagraph(doc, '"Agreement" means this contract.');
+    addParagraph(doc, "“Party” shall mean either side.");
+    addParagraph(doc, '"Agreement" means another thing.'); // Duplicate
+    addParagraph(doc, 'This contract (hereinafter, the "Contract") is valid.');
+    addParagraph(doc, '"Confidential Information" on salainen asia.');
+    addParagraph(doc, '1.1 "Affiliate" tarkoittaa osakkuusyhtiötä.');
+    addParagraph(doc, 'We will act as the disclosing party (jäljempänä "Discloser").');
+    addParagraph(doc, 'This is a syntax example: ("Heading*") and ("<Term>")');
+    
+    addParagraph(doc, "The Agreement is binding. The Contract is signed.");
+    addParagraph(doc, "There is an Agrement here.");
+    addParagraph(doc, "We shared Confidential Information with the Affiliate. The Discloser is happy.");
+
+    const buf = await doc.save();
+    const full_text = await extractTextFromBuffer(buf, false);
+    const [, appendix] = split_structural_appendix(full_text);
+    
+    expect(appendix).toContain('"Agreement" \u2014 used');
+    expect(appendix).toContain('"Contract" \u2014 used');
+    expect(appendix).toContain('"Confidential Information" \u2014 used');
+    expect(appendix).toContain('"Affiliate" \u2014 used');
+    expect(appendix).toContain('"Discloser" \u2014 used');
+
+    expect(appendix).not.toContain('"Party"');
+    expect(appendix).not.toContain('"Heading*"');
+    expect(appendix).not.toContain('"<Term>"');
+
+    expect(appendix).toContain("[Error] Duplicate Definition: 'Agreement' is defined multiple times.");
+    expect(appendix).toContain("[Info] Possible Typos for 'Agreement': Found 'Agrement'");
+  });
+
+  it('reduces typo noise for short acronyms', async () => {
+    const doc = await createTestDocument();
+    addParagraph(doc, '"PSUs" means power supply units.');
+    addParagraph(doc, '"CPU" means central processing unit.');
+    addParagraph(doc, '"Party" means the entity.');
+    addParagraph(doc, "We rely on ESAs, LSPs, and GPUs for the servers.");
+    addParagraph(doc, "The GPU is very fast.");
+    addParagraph(doc, "The Pary signed the contract.");
+    addParagraph(doc, "We bought PSUs and a CPU.");
+    addParagraph(doc, "The Party begins today.");
+
+    const buf = await doc.save();
+    const full_text = await extractTextFromBuffer(buf, false);
+    const [, appendix] = split_structural_appendix(full_text);
+ 
+    expect(appendix).toContain("[Info] Possible Typos for 'Party': Found 'Pary'");
+    expect(appendix).not.toContain("'GPU'");
+    expect(appendix).not.toContain("'GPUs'");
+    expect(appendix).not.toContain("'ESAs'");
+    expect(appendix).not.toContain("'LSPs'");
+  });
+});

package/src/domain.ts

@@ -1,11 +1,265 @@
-/**
- * Lightweight port of domain.py (Semantic Diagnostics & Appendix).
- * Uses a simplified heuristic since full rapidfuzz isn't available.
- */
-
-export function build_structural_appendix(doc: any, base_text: string): string {
-  // To keep the initial ingestion port lean and maintain 100% parity on body text,
-  // we will return an empty appendix string for now. The python port can be completed
-  // in a follow-up PR if diagnostics are required in Node MCPs.
-  return '';
+import { DocumentObject } from './docx/bridge.js';
+import { Paragraph, Run } from './docx/primitives.js';
+import { iter_block_items, get_run_text } from './utils/docx.js';
+import { findAllDescendants } from './docx/dom.js';
+
+function boundedLevenshtein(a: string, b: string, maxDist: number = 2): number {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > maxDist) return maxDist + 1;
+  if (a.length === 0) return b.length <= maxDist ? b.length : maxDist + 1;
+  if (b.length === 0) return a.length <= maxDist ? a.length : maxDist + 1;
+
+  if (a.length > b.length) {
+    const temp = a;
+    a = b;
+    b = temp;
+  }
+
+  let row = Array.from({ length: a.length + 1 }, (_, i) => i);
+
+  for (let i = 1; i <= b.length; i++) {
+    const newRow = [i];
+    let minInRow = i;
+    for (let j = 1; j <= a.length; j++) {
+      const cost = a[j - 1] === b[i - 1] ? 0 : 1;
+      const val = Math.min(
+        row[j] + 1,
+        newRow[j - 1] + 1,
+        row[j - 1] + cost
+      );
+      newRow.push(val);
+      if (val < minInRow) minInRow = val;
+    }
+    if (minInRow > maxDist) return maxDist + 1;
+    row = newRow;
+  }
+  return row[a.length] <= maxDist ? row[a.length] : maxDist + 1;
+}
+
+function _get_paragraph_text(p: Paragraph): string {
+  let text = '';
+  const runs = findAllDescendants(p._element, 'w:r');
+  for (const r of runs) {
+    text += get_run_text(new Run(r, p));
+  }
+  return text;
+}
+
+export function extract_all_domain_metadata(
+  doc: DocumentObject,
+  base_text: string
+): [Record<string, { count: number }>, string[], Record<string, { anchored_to: string; referenced_from: string[] }>] {
+  const definitions: Record<string, { count: number }> = {};
+  const duplicates = new Set<string>();
+  const raw_anchors: Record<string, { anchored_to: string; referenced_from: string[] }> = {};
+  const raw_references: [string, string][] = [];
+
+  const leading_re = /^(?:[\d.\-()a-zA-Z]+\s*)?["“]([A-Z][A-Za-z0-9\s\-&'’]{1,60})["”]/;
+  const inline_re = /\([^)]*?["“]([A-Z][A-Za-z0-9\s\-&'’]{1,60})["”][^)]*?\)/g;
+
+  for (const item of iter_block_items(doc)) {
+    if (!(item instanceof Paragraph)) continue;
+
+    const text = _get_paragraph_text(item).trim();
+    if (!text) continue;
+
+    const extracted_terms: string[] = [];
+    const leading_match = text.match(leading_re);
+    if (leading_match) extracted_terms.push(leading_match[1].trim());
+
+    const inline_matches = text.matchAll(inline_re);
+    for (const m of inline_matches) {
+      extracted_terms.push(m[1].trim());
+    }
+
+    for (const term of extracted_terms) {
+      if (definitions[term]) duplicates.add(term);
+      else definitions[term] = { count: 0 };
+    }
+
+    const short_text = text.length > 60 ? text.substring(0, 60) + '...' : text;
+
+    const nodes = findAllDescendants(item._element, '*');
+    for (const node of nodes) {
+      if (node.tagName === 'w:bookmarkStart') {
+        const b_name = node.getAttribute('w:name');
+        if (b_name && (!b_name.startsWith('_') || b_name.startsWith('_Ref'))) {
+          if (!raw_anchors[b_name]) {
+            raw_anchors[b_name] = { anchored_to: short_text, referenced_from: [] };
+          }
+        }
+      }
+
+      let target: string | null = null;
+      if (node.tagName === 'w:fldSimple') {
+        const instr = node.getAttribute('w:instr') || '';
+        const parts = instr.trim().split(/\s+/);
+        if (parts.length > 1 && parts[0] === 'REF') target = parts[1];
+      } else if (node.tagName === 'w:instrText') {
+        const instr = node.textContent || '';
+        const parts = instr.trim().split(/\s+/);
+        if (parts.length > 1 && parts[0] === 'REF') target = parts[1];
+      }
+
+      if (target) raw_references.push([target, short_text]);
+    }
+  }
+
+  for (const [target, ref_text] of raw_references) {
+    if (raw_anchors[target]) {
+      raw_anchors[target].referenced_from.push(ref_text);
+    }
+  }
+
+  const diagnostics: string[] = [];
+
+  const def_keys = Object.keys(definitions);
+  if (def_keys.length > 0) {
+    const sorted_terms = def_keys.sort((a, b) => b.length - a.length);
+    const escapeRegExp = (str: string) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const alt = sorted_terms.map(escapeRegExp).join('|');
+    const usage_pattern = new RegExp(`(?<!["“])\\b(${alt})\\b(?![”"])`, 'g');
+
+    for (const m of base_text.matchAll(usage_pattern)) {
+      const matched_term = m[1];
+      if (definitions[matched_term]) definitions[matched_term].count++;
+    }
+
+    for (const term of def_keys) {
+      if (definitions[term].count === 0) {
+        delete definitions[term];
+        duplicates.delete(term);
+      }
+    }
+  }
+
+  for (const term of duplicates) {
+    diagnostics.push(`[Error] Duplicate Definition: '${term}' is defined multiple times.`);
+  }
+
+  const stop_words = new Set([
+    "The", "This", "That", "Such", "A", "An", "Any", "All", "Some", "No",
+    "Every", "Each", "As", "In", "Of", "For", "To", "On", "By", "With"
+  ]);
+
+  const all_cap_pattern = /\b[A-Z][a-zA-Z]*(?:\s+[A-Z][a-zA-Z]*)*\b/g;
+  const all_caps = new Set(base_text.match(all_cap_pattern) || []);
+
+  const valid_terms = new Set(Object.keys(definitions));
+  const terms_by_first_letter: Record<string, string[]> = {};
+  for (const term of valid_terms) {
+    const fl = term[0].toLowerCase();
+    if (!terms_by_first_letter[fl]) terms_by_first_letter[fl] = [];
+    terms_by_first_letter[fl].push(term);
+  }
+
+  const candidates_by_term: Record<string, string[]> = {};
+
+  for (const raw_candidate of all_caps) {
+    let candidate = raw_candidate.trim();
+    const words = candidate.split(/\s+/);
+    while (words.length > 0) {
+      const first = words[0];
+      const title = first.charAt(0).toUpperCase() + first.slice(1).toLowerCase();
+      if (stop_words.has(title)) words.shift();
+      else break;
+    }
+    candidate = words.join(' ');
+
+    if (candidate.length < 4) continue;
+    if (valid_terms.has(candidate)) continue;
+
+    const first_letter = candidate[0].toLowerCase();
+    let candidate_terms = terms_by_first_letter[first_letter] || [];
+
+    if (candidate.length > 5) {
+      for (const [k, v] of Object.entries(terms_by_first_letter)) {
+        if (k !== first_letter) candidate_terms = candidate_terms.concat(v);
+      }
+    }
+
+    for (const term of candidate_terms) {
+      if (Math.abs(candidate.length - term.length) > 2) continue;
+      if (candidate === term + 's' || candidate === term + 'es') continue;
+      if (term === candidate + 's' || term === candidate + 'es') continue;
+
+      const dist = boundedLevenshtein(candidate, term, 2);
+      if (dist === 0 || dist > 2) continue;
+
+      if (term.length <= 5) {
+        if (dist > 1) continue;
+        if (candidate[0].toLowerCase() !== term[0].toLowerCase()) continue;
+      }
+
+      if (!candidates_by_term[term]) candidates_by_term[term] = [];
+      if (!candidates_by_term[term].includes(candidate)) candidates_by_term[term].push(candidate);
+    }
+  }
+
+  for (const [term, candidates] of Object.entries(candidates_by_term)) {
+    candidates.sort();
+    const c_str = candidates.map(c => `'${c}'`).join(', ');
+    diagnostics.push(`[Info] Possible Typos for '${term}': Found ${c_str}`);
+  }
+
+  function diag_sort_key(msg: string) {
+    if (msg.startsWith('[Error]')) return 0;
+    if (msg.startsWith('[Warning]')) return 1;
+    return 2;
+  }
+
+  diagnostics.sort((a, b) => {
+    const keyA = diag_sort_key(a);
+    const keyB = diag_sort_key(b);
+    if (keyA !== keyB) return keyA - keyB;
+    return a.localeCompare(b);
+  });
+
+  return [definitions, diagnostics, raw_anchors];
+}
+
+export function build_structural_appendix(doc: DocumentObject, base_text: string): string {
+  const [defs, diagnostics, anchors] = extract_all_domain_metadata(doc, base_text);
+
+  const lines: string[] = [
+    "\n\n---",
+    "",
+    "<!-- READONLY_BOUNDARY_START -->",
+    "# Document Structure (Read-Only)",
+    "The content below is metadata describing the document's reference structure. Do not include this section in any tracked changes or edits \u2014 it is for your context only and will be discarded on write."
+  ];
+
+  let has_content = false;
+
+  if (Object.keys(defs).length > 0) {
+    has_content = true;
+    lines.push("\n## Defined Terms");
+    for (const [term, data] of Object.entries(defs)) {
+      lines.push(`- "${term}" \u2014 used ${data.count} times.`);
+    }
+  }
+
+  if (diagnostics.length > 0) {
+    has_content = true;
+    lines.push("\n## Semantic Diagnostics");
+    for (const diag of diagnostics) {
+      lines.push(`- ${diag}`);
+    }
+  }
+
+  if (Object.keys(anchors).length > 0) {
+    has_content = true;
+    lines.push("\n## Named Anchors");
+    for (const [b_name, data] of Object.entries(anchors)) {
+      lines.push(`- ${b_name} \u2192 Anchored to: "${data.anchored_to}"`);
+      for (const ref of data.referenced_from) {
+        lines.push(`  - Referenced from: "${ref}"`);
+      }
+    }
+  }
+
+  if (has_content) {
+    return lines.join('\n');
+  }
+  return "";
 }

package/src/index.ts

@@ -1,14 +1,13 @@
-/**
- * @adeu/core
- * Cross-platform XML Redlining Engine
- */
-export const identifyEngine = () => 'adeu-core-node';
+export function identifyEngine() {
+  return 'adeu-core-node';
+}
 
-export { extractTextFromBuffer } from './ingest.js';
 export { DocumentObject } from './docx/bridge.js';
 export { DocumentMapper, TextSpan } from './mapper.js';
 export { RedlineEngine, BatchValidationError } from './engine.js';
-export { generate_edits_from_text, trim_common_context } from './diff.js';
+export { generate_edits_from_text, trim_common_context, create_unified_diff } from './diff.js';
 export { apply_edits_to_markdown } from './markup.js';
 export { paginate, split_structural_appendix, PaginationResult, PageInfo } from './pagination.js';
-export { extract_outline, OutlineNode } from './outline.js';
+export { extract_outline, OutlineNode } from './outline.js';
+export { extractTextFromBuffer } from './ingest.js';
+export { finalize_document, FinalizeOptions, FinalizeResult } from './sanitize/core.js';