From 6731160967479c8b42249f094935cc9ba2c538c1 Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 13:48:11 -0700
Subject: [PATCH 01/17] feat(ast): add vanishCharStyleIds to ObjectMetaSchema

Resolved w:rStyle -> character-style w:vanish IDs, captured alongside
a body object so capture and the edit rewrite path can share one
source of truth without needing styles.xml at rewrite time (#650).

Additive JSONB field, no migration needed: absent and [] are
interchangeable, so an object row captured before this change
loads/parses unchanged. openapi.yaml updated to match.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 openapi.yaml                   | 11 +++++++
 src/ast/object-schemas.test.ts | 59 ++++++++++++++++++++++++++++++++++
 src/ast/object-schemas.ts      | 11 +++++++
 3 files changed, 81 insertions(+)

diff --git a/openapi.yaml b/openapi.yaml
index 082dda69..0a13c5e3 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -8132,6 +8132,17 @@ components:
           type: integer
           minimum: 1
           description: Table column count (table kind only).
+        vanishCharStyleIds:
+          type: array
+          description: >-
+            Resolved character-style IDs (#650) carrying an enabled
+            `w:vanish` — the styles a run's `w:rStyle` must resolve through
+            to be treated as hidden. Captured at import so hidden text stays
+            excluded from `objectText` on later edits, without needing
+            `styles.xml` at edit time. Absent and `[]` are interchangeable;
+            an object captured before this field existed has neither.
+          items:
+            type: string
         blob:
           type: array
           description: >-
diff --git a/src/ast/object-schemas.test.ts b/src/ast/object-schemas.test.ts
index 83064ab5..0ce7c420 100644
--- a/src/ast/object-schemas.test.ts
+++ b/src/ast/object-schemas.test.ts
@@ -111,6 +111,65 @@ describe('ObjectMetaSchema', () => {
   });
 });
 
+// ── vanishCharStyleIds (#650) ───────────────────────────────────────────────
+// Resolved w:rStyle → character-style w:vanish IDs, captured alongside the
+// object so capture and rewrite share one source of truth without needing
+// styles.xml at rewrite time. Additive JSONB field: absent and [] are
+// interchangeable, and a row captured before this change (no key at all)
+// must still load/parse identically to today.
+describe('ObjectMetaSchema — vanishCharStyleIds (#650)', () => {
+  const validTable = {
+    kind: 'table' as const,
+    floating: false,
+    generation: 'drawingml' as const,
+    rows: 1,
+    columns: 1,
+    blob: TABLE_BLOB,
+  };
+
+  it('a row/object captured before this change (no vanishCharStyleIds key) loads identically', () => {
+    const result = ObjectMetaSchema.safeParse(validTable);
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect('vanishCharStyleIds' in result.data).toBe(false);
+  });
+
+  it('accepts a table object with a populated vanishCharStyleIds array', () => {
+    const withVanish = { ...validTable, vanishCharStyleIds: ['HiddenChar', 'Redacted'] };
+    const result = ObjectMetaSchema.safeParse(withVanish);
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.vanishCharStyleIds).toEqual(['HiddenChar', 'Redacted']);
+  });
+
+  it('accepts an empty vanishCharStyleIds array, interchangeable with absent', () => {
+    expect(ObjectMetaSchema.safeParse({ ...validTable, vanishCharStyleIds: [] }).success).toBe(
+      true
+    );
+  });
+
+  it('rejects a non-string entry in vanishCharStyleIds', () => {
+    const bad = { ...validTable, vanishCharStyleIds: ['HiddenChar', 42] };
+    expect(ObjectMetaSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it('a textBox object (no rows/columns) still validates with vanishCharStyleIds populated — the field never couples to kind', () => {
+    const textBox = {
+      kind: 'textBox' as const,
+      floating: true,
+      generation: 'vml' as const,
+      blob: [{ '#text': 'boxed text' }],
+      vanishCharStyleIds: ['HiddenChar'],
+    };
+    const result = ObjectMetaSchema.safeParse(textBox);
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.vanishCharStyleIds).toEqual(['HiddenChar']);
+    expect(result.data.rows).toBeUndefined();
+    expect(result.data.columns).toBeUndefined();
+  });
+});
+
 // ── Editability fixation (#300, ADR-072 decision 2) ────────────────────────
 // An 'object' node is always locked (a captured OOXML blob is never
 // paragraph-editable text) and its 'objectText' children are always editable
diff --git a/src/ast/object-schemas.ts b/src/ast/object-schemas.ts
index 61e7ecf9..6ac24c65 100644
--- a/src/ast/object-schemas.ts
+++ b/src/ast/object-schemas.ts
@@ -72,6 +72,16 @@ export const ObjectBlobNodeSchema: z.ZodType<ObjectBlobNode> = z.custom<ObjectBl
  * decision 2). `rows`/`columns` are table-only (grid dimensions); `blob` is
  * the object's own top-level OOXML node(s) in document order, always
  * non-empty — an object with no captured content is never modeled at all.
+ *
+ * `vanishCharStyleIds` (#650) is the resolved set of character-style IDs
+ * that carry an enabled `w:vanish` — i.e. the `StyleMap.vanishCharStyleIds`
+ * a run's `w:rStyle` must resolve through to be treated as hidden. It is
+ * captured alongside the object so capture (`collectText`) and the edit
+ * rewrite path (`rewriteFirstText`) share one persisted source of truth
+ * without needing `styles.xml` at rewrite time, where it is unavailable.
+ * Additive JSONB field, no migration: an absent key and an empty array are
+ * fully interchangeable (today's behaviour — no runs treated as hidden by
+ * style), so a row captured before this change loads/edits unchanged.
  */
 export const ObjectMetaSchema = z.object({
   kind: ObjectKindSchema,
@@ -79,6 +89,7 @@ export const ObjectMetaSchema = z.object({
   generation: ObjectGenerationSchema,
   rows: z.number().int().positive().exactOptional(),
   columns: z.number().int().positive().exactOptional(),
+  vanishCharStyleIds: z.array(z.string()).exactOptional(),
   blob: z.array(ObjectBlobNodeSchema).check(z.minLength(1)),
 });
 

From 1832b7321d86c3422460e6ec3d706b118632d4fa Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 13:51:32 -0700
Subject: [PATCH 02/17] fix(parser): honor w:vanish w:val=0 toggle on style's
 own rPr
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

parseCharacterStyles's isVanish and parseVanish's paragraph-style
check used bare `'w:vanish' in rPr` presence checks. w:vanish is an
OOXML ST_OnOff toggle (ECMA-376 §17.3.2.45): an explicit w:val in
{0,false,off} switches it OFF even though the element is present.
Presence-only checks incorrectly marked such styles vanish, which
would suppress otherwise-visible spec text once #650's Part A relies
on the toggle resolving correctly at the style's own definition.

Switch both checks to isOnOffEnabled (ported from document.ts's
runIsVanish/isOnOffEnabled pattern) and add regression tests pinning
w:vanish w:val="0" as non-vanish for both character and paragraph
styles.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/parser/docx/styles.test.ts | 18 ++++++++++++++++++
 src/parser/docx/styles.ts      | 16 ++++++++++++++--
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/src/parser/docx/styles.test.ts b/src/parser/docx/styles.test.ts
index 6377772e..e243ff12 100644
--- a/src/parser/docx/styles.test.ts
+++ b/src/parser/docx/styles.test.ts
@@ -266,4 +266,22 @@ describe('vanish resolution', () => {
     expect(m.vanishCharStyleIds.has('ChildHide')).toBe(true);
     expect(m.vanishCharStyleIds.has('BaseHide')).toBe(true);
   });
+
+  // w:vanish is an OOXML ST_OnOff toggle (ECMA-376 §17.3.2.45), not a bare marker:
+  // an explicit w:val="0" on the STYLE's own rPr switches vanish OFF and must not
+  // mark the style hidden. Presence-only checks ('w:vanish' in rPr) get this wrong.
+  it('does not mark a character style vanish when its own w:vanish w:val is 0', () => {
+    const xml = `<?xml version="1.0"?><w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+      <w:style w:styleId="NotHiddenChar" w:type="character"><w:name w:val="NotHiddenChar"/><w:rPr><w:vanish w:val="0"/></w:rPr></w:style>
+    </w:styles>`;
+    const m = buildStyleMap(xml);
+    expect(m.vanishCharStyleIds.has('NotHiddenChar')).toBe(false);
+  });
+
+  it('does not mark a paragraph style vanish when its own w:vanish w:val is 0', () => {
+    const xml = `<?xml version="1.0"?><w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+      <w:style w:styleId="NotHiddenPara" w:type="paragraph"><w:name w:val="NotHiddenPara"/><w:rPr><w:vanish w:val="0"/></w:rPr></w:style>
+    </w:styles>`;
+    expect(buildStyleMap(xml).vanishStyleIds.has('NotHiddenPara')).toBe(false);
+  });
 });
diff --git a/src/parser/docx/styles.ts b/src/parser/docx/styles.ts
index b682756c..743546d3 100644
--- a/src/parser/docx/styles.ts
+++ b/src/parser/docx/styles.ts
@@ -48,11 +48,23 @@ function parseNumPr(pPr: Record<string, unknown>): NumPrResult {
   return { kind: 'active', numPr: { numId, ilvl } };
 }
 
+// w:vanish is an OOXML ST_OnOff TOGGLE (ECMA-376 §17.3.2.45), not a bare
+// presence marker: an explicit w:val in {0,false,off} switches it OFF even
+// though the element is present. Mirrors document.ts's isOnOffEnabled/
+// runIsVanish handling of the same toggle on runs.
+function isOnOffEnabled(node: unknown): boolean {
+  const val = getAttrVal(node).toLowerCase();
+  return val !== '0' && val !== 'false' && val !== 'off';
+}
+
 function parseVanish(raw: Record<string, unknown>): boolean {
   const pPr = asRecord(raw['w:pPr']);
   const pRpr = asRecord(pPr?.['w:rPr']);
   const rPr = asRecord(raw['w:rPr']);
-  return (pRpr !== undefined && 'w:vanish' in pRpr) || (rPr !== undefined && 'w:vanish' in rPr);
+  return (
+    (pRpr !== undefined && 'w:vanish' in pRpr && isOnOffEnabled(pRpr['w:vanish'])) ||
+    (rPr !== undefined && 'w:vanish' in rPr && isOnOffEnabled(rPr['w:vanish']))
+  );
 }
 
 // CT_OnOff, presence-aware: undefined when the style's pPr has no
@@ -195,7 +207,7 @@ function parseCharacterStyles(root: Record<string, unknown>): Map<string, CharSt
     const basedOn = getAttrVal(rec['w:basedOn']);
     styles.set(styleId, {
       ...(basedOn ? { basedOn } : {}),
-      isVanish: rPr !== undefined && 'w:vanish' in rPr,
+      isVanish: rPr !== undefined && 'w:vanish' in rPr && isOnOffEnabled(rPr['w:vanish']),
     });
   }
   return styles;

From d799fdafb2a7418eb50c0aa24a33cd7580578a86 Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 14:02:23 -0700
Subject: [PATCH 03/17] feat(parser): resolve rStyle-referenced character-style
 vanish in hasRunVanish
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extends hasRunVanish (body-objects.ts) with an optional vanishCharStyleIds
param so a run hidden via w:rPr>w:rStyle referencing a vanish character
style is now caught by the same predicate capture and rewrite both share
(#650) — a straight OR port of document.ts's runIsVanish, defaulting to an
empty set so every existing single-argument call site keeps compiling and
behaving byte-for-byte unchanged.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/parser/docx/body-objects.test.ts | 74 +++++++++++++++++++++++++++-
 src/parser/docx/body-objects.ts      | 49 ++++++++++++------
 2 files changed, 106 insertions(+), 17 deletions(-)

diff --git a/src/parser/docx/body-objects.test.ts b/src/parser/docx/body-objects.test.ts
index eccc9846..c7505e1b 100644
--- a/src/parser/docx/body-objects.test.ts
+++ b/src/parser/docx/body-objects.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { extractBodyObjects, anchorInteriorParagraphs } from './body-objects.js';
+import { extractBodyObjects, anchorInteriorParagraphs, hasRunVanish } from './body-objects.js';
 import { computeBodyOrder } from './body-order.js';
 import { createDocumentXmlParser, createOrderedDocumentXmlBuilder, toArray } from './xml-utils.js';
 import { buildStyleMap } from './styles.js';
@@ -294,6 +294,34 @@ function blobHostParagraph(children: readonly ObjectBlobNode[]): ObjectBlobNode
   return { 'w:p': children };
 }
 
+// Hand-built w:r fixtures for hasRunVanish's own unit tests (#650) — isolated
+// from the full extractBodyObjects walk so the predicate's OWN contract
+// (direct w:vanish OR rStyle-referenced character-style vanish) is pinned
+// independently of collectText's threading, which a later task wires up.
+function blobRun(rPrChildren: readonly ObjectBlobNode[]): ObjectBlobNode {
+  return { 'w:r': [{ 'w:rPr': rPrChildren }, { 'w:t': [blobTextNode('x')] }] };
+}
+
+// Computed `[tag]` keys (rather than a literal `'w:vanish':`/`'w:rStyle':`
+// property) mirror body-objects.ts's own `rebuilt` helper — the established
+// workaround for the same TS limitation (index signature + intersected `:@`
+// key can't both be checked against one hand-assembled literal at once, see
+// that function's comment) that a bare literal key + `:@` sibling hits.
+function attrNode(tag: string, val?: string): ObjectBlobNode {
+  const children: readonly ObjectBlobNode[] = [];
+  return (
+    val !== undefined ? { [tag]: children, ':@': { '@_w:val': val } } : { [tag]: children }
+  ) as ObjectBlobNode;
+}
+
+function blobVanish(val?: string): ObjectBlobNode {
+  return attrNode('w:vanish', val);
+}
+
+function blobRStyle(styleId: string): ObjectBlobNode {
+  return attrNode('w:rStyle', styleId);
+}
+
 // Depth-first search for the first `w:txbxContent`-tagged descendant of
 // `node` (including `node` itself) — a local test-only helper, not a
 // duplicate of body-objects.ts's own collection logic (this one is used only
@@ -329,6 +357,50 @@ function collectAllTxbxContentNodes(node: ObjectBlobNode): ObjectBlobNode[] {
   return found;
 }
 
+describe('hasRunVanish — rStyle-referenced character-style vanish (#650, capture+rewrite shared predicate)', () => {
+  it('resolves hidden via w:rStyle referencing a vanish character style id present in vanishCharStyleIds', () => {
+    const run = blobRun([blobRStyle('HiddenChar')]);
+    expect(hasRunVanish(run, new Set(['HiddenChar']))).toBe(true);
+  });
+
+  it('a w:rStyle reference NOT present in vanishCharStyleIds stays visible', () => {
+    const run = blobRun([blobRStyle('PlainChar')]);
+    expect(hasRunVanish(run, new Set(['HiddenChar']))).toBe(false);
+  });
+
+  // Straight OR port of document.ts's runIsVanish (#650 spike): a resolved-off
+  // direct <w:vanish w:val="0"/> does NOT override a matching rStyle — the
+  // two signals combine via plain OR, never special-cased against each other.
+  it('a resolved-off direct <w:vanish w:val="0"/> does not override a matching rStyle — still hidden', () => {
+    const run = blobRun([blobVanish('0'), blobRStyle('HiddenChar')]);
+    expect(hasRunVanish(run, new Set(['HiddenChar']))).toBe(true);
+  });
+
+  // The other half of the same invariant, phrased from the "never suppresses"
+  // direction: a resolved-off direct w:vanish with NO matching rStyle must
+  // never itself suppress visible text — this is the over-suppression guard
+  // hasRunVanish's own doc comment warns about, now re-pinned for the
+  // rStyle-aware predicate.
+  it('a resolved-off direct <w:vanish w:val="0"/> with no rStyle match never suppresses — stays visible', () => {
+    const run = blobRun([blobVanish('0')]);
+    expect(hasRunVanish(run, new Set(['HiddenChar']))).toBe(false);
+  });
+
+  it('hasRunVanish() with no 2nd arg is unchanged — an rStyle-only run stays visible for a caller that passes none', () => {
+    const run = blobRun([blobRStyle('HiddenChar')]);
+    expect(hasRunVanish(run)).toBe(false);
+  });
+
+  it('capture and rewrite are decided by the exact same predicate — same input yields the same output on both call shapes', () => {
+    const node = blobRun([blobRStyle('HiddenChar')]);
+    const vanishCharStyleIds = new Set(['HiddenChar']);
+    const captureResult = hasRunVanish(node, vanishCharStyleIds);
+    const rewriteResult = hasRunVanish(node, vanishCharStyleIds);
+    expect(captureResult).toBe(rewriteResult);
+    expect(captureResult).toBe(true);
+  });
+});
+
 describe('anchorInteriorParagraphs — hiddenSubtrees pass-through (#515 task 3)', () => {
   it('backward compatibility: default (no hiddenSubtrees) anchors an interior paragraph exactly as before', () => {
     const inner = blobTxbxContent('interior text');
diff --git a/src/parser/docx/body-objects.ts b/src/parser/docx/body-objects.ts
index 5dffb9c1..df148fce 100644
--- a/src/parser/docx/body-objects.ts
+++ b/src/parser/docx/body-objects.ts
@@ -162,21 +162,24 @@ function isOnOffEnabled(node: ObjectBlobNode): boolean {
   return val !== '0' && val !== 'false' && val !== 'off';
 }
 
-// #641: w:rPr>w:vanish check on a run, blob-tree-side — on the preserveOrder
-// ObjectBlobNode shape rather than document.ts's grouped `raw` tree. The two
-// trees are structurally different, and this module already keeps its own
-// self-contained tagOf/childrenOf/directChildrenByTag trio rather than
-// importing document.ts's, per the established per-module pattern
-// body-text-box-visibility.ts's own header documents.
+// #641/#650: w:rPr>w:vanish check on a run, blob-tree-side — on the
+// preserveOrder ObjectBlobNode shape rather than document.ts's grouped `raw`
+// tree. The two trees are structurally different, and this module already
+// keeps its own self-contained tagOf/childrenOf/directChildrenByTag trio
+// rather than importing document.ts's, per the established per-module
+// pattern body-text-box-visibility.ts's own header documents.
 //
-// Narrower than document.ts's runIsVanish in ONE respect: no
-// character-style-referenced vanish (a `w:rStyle` pointing at a character
-// style that itself carries w:vanish). Resolving that needs the StyleMap's
-// `vanishCharStyleIds`, which extractBodyObjects receives but does not
-// currently thread down to this leaf-level walk; ADR-092 records it as a
-// known scope limit, and no fixture in the 39-file DOCX corpus uses that
-// shape (0 files reference a vanish character style via w:rStyle). That
-// residual gap under-suppresses (a visible leak), never over-suppresses.
+// Straight OR port of document.ts's own `runIsVanish`: a run is hidden if
+// EITHER its own `w:rPr>w:vanish` is an enabled ST_OnOff toggle, OR its
+// `w:rPr>w:rStyle` names a character style present in the caller's
+// `vanishCharStyleIds` (the StyleMap's resolved set of character styles that
+// themselves carry an enabled `w:vanish`). No special-casing between the two
+// signals — a resolved-off direct `<w:vanish w:val="0"/>` does not override a
+// matching rStyle, mirroring document.ts's own behaviour exactly (#650).
+// `vanishCharStyleIds` defaults to an empty set so every pre-existing
+// single-argument call site (collectText below, object-blob-edit.ts's
+// rewriteFirstText, and #648's extract.ts) keeps compiling and behaving
+// byte-for-byte unchanged.
 //
 // EXPORTED so object-blob-edit.ts's `rewriteFirstText` applies the SAME rule
 // when it writes an edit back. That walk's stated contract is to reach text
@@ -184,11 +187,25 @@ function isOnOffEnabled(node: ObjectBlobNode): boolean {
 // a second, drifting copy of this predicate there would place edits into
 // hidden runs and blank the visible ones. One definition, both directions
 // (ADR-092).
-export function hasRunVanish(node: ObjectBlobNode): boolean {
+export function hasRunVanish(
+  node: ObjectBlobNode,
+  vanishCharStyleIds: ReadonlySet<string> = new Set()
+): boolean {
   if (tagOf(node) !== 'w:r') return false;
   const rPr = directChildrenByTag(node, 'w:rPr')[0];
   if (!rPr) return false;
-  return directChildrenByTag(rPr, 'w:vanish').some(isOnOffEnabled);
+  return resolveRunVanish(rPr, vanishCharStyleIds);
+}
+
+// The two OR'd vanish signals, split out of hasRunVanish purely to keep that
+// function's cognitive complexity low — no behavior of its own. `getAttrVal`
+// applied to the w:rStyle node's own `:@` attrs mirrors isOnOffEnabled's
+// identical read of a w:vanish node's `:@` below.
+function resolveRunVanish(rPr: ObjectBlobNode, vanishCharStyleIds: ReadonlySet<string>): boolean {
+  if (directChildrenByTag(rPr, 'w:vanish').some(isOnOffEnabled)) return true;
+  const rStyleNode = directChildrenByTag(rPr, 'w:rStyle')[0];
+  const rStyle = rStyleNode ? getAttrVal(rStyleNode[':@']) : '';
+  return rStyle !== '' && vanishCharStyleIds.has(rStyle);
 }
 
 // w:t's sole text payload, or undefined for a text-less/malformed node —

From 15dfa27e07b0f6a5510ea3c923946150fd6660f7 Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 14:15:36 -0700
Subject: [PATCH 04/17] feat(parser): thread vanishCharStyleIds through capture
 into persisted ObjectMeta

Threads the resolved vanish character-style ID set from the StyleMap the
builders already receive, down through the collectText chain, and persists
it via toObjectMeta. Stored as a SORTED array rather than a Set so the JSONB
column and fixture snapshots serialize deterministically, and omitted
entirely when empty so existing rows round-trip byte-identical.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/parser/docx/body-object-attach.ts |  10 +++
 src/parser/docx/body-objects.test.ts  | 102 +++++++++++++++++++++++-
 src/parser/docx/body-objects.ts       | 107 +++++++++++++++++---------
 3 files changed, 182 insertions(+), 37 deletions(-)

diff --git a/src/parser/docx/body-object-attach.ts b/src/parser/docx/body-object-attach.ts
index 3a97c107..5f7683eb 100644
--- a/src/parser/docx/body-object-attach.ts
+++ b/src/parser/docx/body-object-attach.ts
@@ -33,6 +33,13 @@ function parseRawBodyParagraphs(documentXml: string): readonly Record<string, un
   );
 }
 
+// #650: vanishCharStyleIds is persisted as a SORTED array — never a Set — so
+// the JSONB column and fixture snapshots serialize deterministically
+// regardless of the StyleMap's own (unordered) iteration order. Omitted
+// entirely when empty, mirroring rows/columns' exactOptional-omission
+// convention above: an absent key and an empty array are fully
+// interchangeable (ObjectMetaSchema's own doc comment), so a table/text-box
+// with no style-vanished runs round-trips byte-identical to today's rows.
 function toObjectMeta(captured: CapturedBodyObject): ObjectMeta {
   return {
     kind: captured.kind,
@@ -40,6 +47,9 @@ function toObjectMeta(captured: CapturedBodyObject): ObjectMeta {
     generation: captured.generation,
     ...(captured.rows !== undefined ? { rows: captured.rows } : {}),
     ...(captured.columns !== undefined ? { columns: captured.columns } : {}),
+    ...(captured.vanishCharStyleIds.size > 0
+      ? { vanishCharStyleIds: [...captured.vanishCharStyleIds].sort() }
+      : {}),
     blob: [...captured.blob],
   };
 }
diff --git a/src/parser/docx/body-objects.test.ts b/src/parser/docx/body-objects.test.ts
index c7505e1b..3d63540b 100644
--- a/src/parser/docx/body-objects.test.ts
+++ b/src/parser/docx/body-objects.test.ts
@@ -297,7 +297,11 @@ function blobHostParagraph(children: readonly ObjectBlobNode[]): ObjectBlobNode
 // Hand-built w:r fixtures for hasRunVanish's own unit tests (#650) — isolated
 // from the full extractBodyObjects walk so the predicate's OWN contract
 // (direct w:vanish OR rStyle-referenced character-style vanish) is pinned
-// independently of collectText's threading, which a later task wires up.
+// independently of collectText's threading. collectText now threads
+// vanishCharStyleIds all the way from the builders' StyleMap down to this
+// exact predicate (see the "rStyle-referenced vanish character style" describe
+// block below for the end-to-end capture coverage) — these isolated fixtures
+// still earn their keep as a focused unit test of the predicate alone.
 function blobRun(rPrChildren: readonly ObjectBlobNode[]): ObjectBlobNode {
   return { 'w:r': [{ 'w:rPr': rPrChildren }, { 'w:t': [blobTextNode('x')] }] };
 }
@@ -401,6 +405,102 @@ describe('hasRunVanish — rStyle-referenced character-style vanish (#650, captu
   });
 });
 
+// #650: builds a StyleMap with ONE character style, `styleId`, carrying
+// `<w:vanish/>` (or `<w:vanish w:val={val}/>` when `val` is given — e.g. `'0'`
+// for the resolved-off toggle case). Mirrors styles.test.ts's own
+// character-style-vanish fixture shape exactly, but goes through
+// buildStyleMap so the resulting StyleMap.vanishCharStyleIds is the SAME kind
+// of value buildTableObject/buildTextBoxObject receive from a real caller —
+// this is what proves the threading end-to-end, not just hasRunVanish alone.
+function charVanishStyleMap(styleId: string, val?: string): StyleMap {
+  const vanishAttr = val !== undefined ? ` w:val="${val}"` : '';
+  return buildStyleMap(
+    '<?xml version="1.0"?>' +
+      '<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">' +
+      `<w:style w:type="character" w:styleId="${styleId}"><w:name w:val="${styleId}"/>` +
+      `<w:rPr><w:vanish${vanishAttr}/></w:rPr></w:style></w:styles>`
+  );
+}
+
+// A paragraph mixing one plain visible run with a SECOND run whose
+// `w:rPr>w:rStyle` references `styleId` — the rStyle-vanish analogue of the
+// direct-`w:vanish` mixed-run fixtures used throughout this file (e.g. line
+// ~1007's "single interior paragraph mixing one visible run and one vanish
+// run"). Whether `styledText` actually gets suppressed depends entirely on
+// whether the StyleMap passed to `extract` resolves `styleId` into
+// `vanishCharStyleIds` — this builder makes no assumption either way.
+function rStyleRunPara(visibleText: string, styledText: string, styleId: string): string {
+  return (
+    `<w:p><w:r><w:t>${visibleText}</w:t></w:r>` +
+    `<w:r><w:rPr><w:rStyle w:val="${styleId}"/></w:rPr><w:t>${styledText}</w:t></w:r></w:p>`
+  );
+}
+
+describe('extractBodyObjects — #650 rStyle-referenced character-style vanish threaded through capture', () => {
+  it('table path: excludes a run whose w:rStyle references a vanish character style, keeps the unrelated visible run', () => {
+    const styleMap = charVanishStyleMap('HiddenChar');
+    const cellPara = rStyleRunPara('visible part ', 'hidden style part', 'HiddenChar');
+    const result = extract(table(row(cell(cellPara))), styleMap);
+
+    expect(result.tableObjects).toHaveLength(1);
+    const object = result.tableObjects[0]?.object;
+    expect(object?.interiorTexts.map((t) => t.text)).toEqual(['visible part ']);
+    expect(object?.vanishCharStyleIds).toEqual(styleMap.vanishCharStyleIds);
+  });
+
+  it('text box path: excludes a run whose w:rStyle references a vanish character style, keeps the unrelated visible run', () => {
+    const styleMap = charVanishStyleMap('HiddenChar');
+    const interior = rStyleRunPara('visible part ', 'hidden style part', 'HiddenChar');
+    const result = extract(textBoxHostParagraph(interior), styleMap);
+
+    expect(result.paragraphObjects).toHaveLength(1);
+    const object = result.paragraphObjects[0]?.object;
+    expect(object?.interiorTexts.map((t) => t.text)).toEqual(['visible part ']);
+    expect(object?.vanishCharStyleIds).toEqual(styleMap.vanishCharStyleIds);
+  });
+
+  // Over-suppression guard, ported to the full capture boundary (mirrors the
+  // toggle-OFF direct-w:vanish tests below in the #641 describe block, but
+  // for the STYLE-referenced signal): a character style whose OWN w:vanish is
+  // resolved OFF (`w:val="0"`) must never end up in vanishCharStyleIds
+  // (styles.test.ts's own contract), so a run referencing it via w:rStyle is
+  // never suppressed — visible text must survive on both capture paths.
+  it('a resolved-off <w:vanish w:val="0"/> on the referenced character style never suppresses — text survives, table + text-box paths', () => {
+    const styleMap = charVanishStyleMap('ToggleOffChar', '0');
+    expect(styleMap.vanishCharStyleIds.has('ToggleOffChar')).toBe(false);
+
+    const cellPara = rStyleRunPara('visible part ', 'also visible', 'ToggleOffChar');
+    const tableResult = extract(table(row(cell(cellPara))), styleMap);
+    expect(tableResult.tableObjects[0]?.object.interiorTexts.map((t) => t.text)).toEqual([
+      'visible part also visible',
+    ]);
+
+    const interior = rStyleRunPara('visible part ', 'also visible', 'ToggleOffChar');
+    const boxResult = extract(textBoxHostParagraph(interior), styleMap);
+    expect(boxResult.paragraphObjects[0]?.object.interiorTexts.map((t) => t.text)).toEqual([
+      'visible part also visible',
+    ]);
+  });
+
+  // An rStyle reference to a styleId the caller's StyleMap never resolved to
+  // vanish (here: EMPTY_STYLES, no character styles at all) must never
+  // suppress — proves the threaded set genuinely gates the check rather than
+  // any rStyle presence being treated as hidden.
+  it('an rStyle reference absent from the StyleMap never suppresses — unrelated visible content survives', () => {
+    const interior = rStyleRunPara('visible part ', 'unstyled elsewhere', 'HiddenChar');
+    const result = extract(textBoxHostParagraph(interior));
+
+    expect(result.paragraphObjects[0]?.object.interiorTexts.map((t) => t.text)).toEqual([
+      'visible part unstyled elsewhere',
+    ]);
+  });
+
+  it('defaults to an empty vanishCharStyleIds set on the captured object when the StyleMap has no character-style vanish', () => {
+    const result = extract(table(row(cell(para('cell text')))));
+    expect(result.tableObjects[0]?.object.vanishCharStyleIds).toEqual(new Set());
+  });
+});
+
 describe('anchorInteriorParagraphs — hiddenSubtrees pass-through (#515 task 3)', () => {
   it('backward compatibility: default (no hiddenSubtrees) anchors an interior paragraph exactly as before', () => {
     const inner = blobTxbxContent('interior text');
diff --git a/src/parser/docx/body-objects.ts b/src/parser/docx/body-objects.ts
index df148fce..c61a989b 100644
--- a/src/parser/docx/body-objects.ts
+++ b/src/parser/docx/body-objects.ts
@@ -49,6 +49,14 @@ export interface CapturedObjectText {
  * this, plus a fresh uuid/label, into the actual SpecNode + its `objectText`
  * children). `blob` already carries every interior paragraph's SDT anchor —
  * it is the exact node tree the parent `object.meta.object.blob` will store.
+ *
+ * `vanishCharStyleIds` (#650) is the SAME `StyleMap.vanishCharStyleIds` set
+ * used to decide which interior runs `collectText` skipped during capture —
+ * carried forward unfiltered (the full resolved set, not a subset narrowed to
+ * what this particular object actually referenced; simplicity, zero
+ * correctness cost) so `body-object-attach.ts`'s `toObjectMeta` can persist
+ * it and the edit rewrite path (`object-text-edit.ts`) can rebuild the same
+ * `ReadonlySet` at write time without re-parsing `styles.xml`.
  */
 export interface CapturedBodyObject {
   readonly kind: ObjectKind;
@@ -58,6 +66,7 @@ export interface CapturedBodyObject {
   readonly columns?: number;
   readonly blob: readonly ObjectBlobNode[];
   readonly interiorTexts: readonly CapturedObjectText[];
+  readonly vanishCharStyleIds: ReadonlySet<string>;
 }
 
 /** An out-of-scope body drawable SpecR could not capture (ADR-072 decision
@@ -176,10 +185,11 @@ function isOnOffEnabled(node: ObjectBlobNode): boolean {
 // themselves carry an enabled `w:vanish`). No special-casing between the two
 // signals — a resolved-off direct `<w:vanish w:val="0"/>` does not override a
 // matching rStyle, mirroring document.ts's own behaviour exactly (#650).
-// `vanishCharStyleIds` defaults to an empty set so every pre-existing
-// single-argument call site (collectText below, object-blob-edit.ts's
-// rewriteFirstText, and #648's extract.ts) keeps compiling and behaving
-// byte-for-byte unchanged.
+// `vanishCharStyleIds` defaults to an empty set so a caller that has none to
+// offer (object-blob-edit.ts's rewriteFirstText before its own #650 wiring,
+// #648's extract.ts) keeps compiling and behaving byte-for-byte unchanged.
+// collectText below now threads the real set through on every call — see its
+// own comment.
 //
 // EXPORTED so object-blob-edit.ts's `rewriteFirstText` applies the SAME rule
 // when it writes an edit back. That walk's stated contract is to reach text
@@ -222,15 +232,25 @@ function textOfWtNode(node: ObjectBlobNode): string | undefined {
 // wrapper (w:hyperlink, w:ins/w:del, w:sdt) reaches wrapped text the same
 // way document.ts's collectRuns does, with no per-wrapper special-casing.
 //
-// #641: a w:r flagged hasRunVanish is skipped entirely — no text pushed, no
-// descent into its subtree. This walk already passes transparently through
-// nested w:txbxContent boundaries (body-text-box-visibility.ts deliberately
-// treats a nested text box's interior as opaque and never adds it to
-// hiddenSubtrees — see ADR-092), so this single run-level check is what
-// keeps a hidden run's text from leaking into an ancestor interior
-// paragraph's captured text, whether that run sits directly in the
-// paragraph or several levels down inside a nested text box's own interior.
-function collectText(children: readonly ObjectBlobNode[], acc: string[]): void {
+// #641/#650: a w:r flagged hasRunVanish is skipped entirely — no text
+// pushed, no descent into its subtree. This walk already passes
+// transparently through nested w:txbxContent boundaries
+// (body-text-box-visibility.ts deliberately treats a nested text box's
+// interior as opaque and never adds it to hiddenSubtrees — see ADR-092), so
+// this single run-level check is what keeps a hidden run's text from
+// leaking into an ancestor interior paragraph's captured text, whether that
+// run sits directly in the paragraph or several levels down inside a nested
+// text box's own interior. `vanishCharStyleIds` is threaded down from the
+// object builders (buildTableObject/buildTextBoxObject, both fed by the
+// caller's `StyleMap.vanishCharStyleIds`) so a run hidden ONLY via a
+// `w:rStyle`-referenced character style is excluded here exactly like a
+// direct `w:rPr>w:vanish` run — the same `hasRunVanish` predicate,
+// same signal set, one call site deciding capture.
+function collectText(
+  children: readonly ObjectBlobNode[],
+  acc: string[],
+  vanishCharStyleIds: ReadonlySet<string>
+): void {
   for (const child of children) {
     const tag = tagOf(child);
     if (tag === 'w:t') {
@@ -238,14 +258,14 @@ function collectText(children: readonly ObjectBlobNode[], acc: string[]): void {
       if (text !== undefined) acc.push(text);
       continue;
     }
-    if (tag === 'w:r' && hasRunVanish(child)) continue;
-    collectText(childrenOf(child), acc);
+    if (tag === 'w:r' && hasRunVanish(child, vanishCharStyleIds)) continue;
+    collectText(childrenOf(child), acc, vanishCharStyleIds);
   }
 }
 
-function extractBlobText(node: ObjectBlobNode): string {
+function extractBlobText(node: ObjectBlobNode, vanishCharStyleIds: ReadonlySet<string>): string {
   const acc: string[] = [];
-  collectText([node], acc);
+  collectText([node], acc, vanishCharStyleIds);
   return acc.join('');
 }
 
@@ -268,13 +288,14 @@ interface ChildrenTransformResult {
 // walk must treat as opaque; see transformChildren's pass-through branch.
 function transformInteriorParagraphs(
   node: ObjectBlobNode,
-  hiddenSubtrees: ReadonlySet<ObjectBlobNode>
+  hiddenSubtrees: ReadonlySet<ObjectBlobNode>,
+  vanishCharStyleIds: ReadonlySet<string>
 ): InteriorTransformResult {
   const tag = tagOf(node);
   if (!tag) return { node, interiorTexts: [] };
   const value = node[tag];
   if (!isBlobNodeArray(value)) return { node, interiorTexts: [] };
-  const { children, interiorTexts } = transformChildren(value, hiddenSubtrees);
+  const { children, interiorTexts } = transformChildren(value, hiddenSubtrees, vanishCharStyleIds);
   const attrs = node[':@'];
   // `as ObjectBlobNode` mirrors object-anchor.ts's own established narrowing
   // (see wrapBlobParagraphWithAnchor): ObjectBlobNode's index signature plus
@@ -308,7 +329,8 @@ function transformInteriorParagraphs(
 // other half of this investigation.
 function transformChildren(
   children: readonly ObjectBlobNode[],
-  hiddenSubtrees: ReadonlySet<ObjectBlobNode>
+  hiddenSubtrees: ReadonlySet<ObjectBlobNode>,
+  vanishCharStyleIds: ReadonlySet<string>
 ): ChildrenTransformResult {
   const newChildren: ObjectBlobNode[] = [];
   const interiorTexts: CapturedObjectText[] = [];
@@ -323,7 +345,7 @@ function transformChildren(
       continue;
     }
     if (tagOf(child) === 'w:p') {
-      const text = extractBlobText(child);
+      const text = extractBlobText(child, vanishCharStyleIds);
       if (text.trim().length === 0) {
         newChildren.push(child);
         continue;
@@ -333,7 +355,7 @@ function transformChildren(
       interiorTexts.push({ id, text });
       continue;
     }
-    const transformed = transformInteriorParagraphs(child, hiddenSubtrees);
+    const transformed = transformInteriorParagraphs(child, hiddenSubtrees, vanishCharStyleIds);
     newChildren.push(transformed.node);
     interiorTexts.push(...transformed.interiorTexts);
   }
@@ -341,17 +363,19 @@ function transformChildren(
 }
 
 /** The public entry point for the interior-paragraph anchor walk (#515,
- * ADR-087): both {@link buildTableObject} and (a later task)
- * {@link buildTextBoxObject} call this, never the two private inner
- * functions directly. `hiddenSubtrees` defaults to an empty set — a no-op —
- * so every EXISTING call site (buildTableObject's own
- * `anchorInteriorParagraphs(normalized)`) compiles and behaves byte-for-byte
- * unchanged with zero edits. */
+ * ADR-087): both {@link buildTableObject} and {@link buildTextBoxObject} call
+ * this, never the two private inner functions directly. Both `hiddenSubtrees`
+ * (the #515 `w:txbxContent` boundary set) and `vanishCharStyleIds` (#650, the
+ * `StyleMap.vanishCharStyleIds` set `collectText` consults to skip
+ * rStyle-hidden runs) default to an empty set — a no-op — so a caller with
+ * neither to offer compiles and behaves byte-for-byte unchanged with zero
+ * edits. */
 export function anchorInteriorParagraphs(
   root: ObjectBlobNode,
-  hiddenSubtrees: ReadonlySet<ObjectBlobNode> = new Set()
+  hiddenSubtrees: ReadonlySet<ObjectBlobNode> = new Set(),
+  vanishCharStyleIds: ReadonlySet<string> = new Set()
 ): InteriorTransformResult {
-  return transformInteriorParagraphs(root, hiddenSubtrees);
+  return transformInteriorParagraphs(root, hiddenSubtrees, vanishCharStyleIds);
 }
 
 // ─── table capture ──────────────────────────────────────────────────────────
@@ -365,7 +389,10 @@ function classifyTableVisibility(
   return classifyTopLevelTables(wrapped, styleMap)[0];
 }
 
-function buildTableObject(blob: readonly ObjectBlobNode[]): CapturedBodyObject | undefined {
+function buildTableObject(
+  blob: readonly ObjectBlobNode[],
+  styleMap: StyleMap
+): CapturedBodyObject | undefined {
   const tableNode = blob[0];
   if (!tableNode) return undefined;
   // #517: normalize mc:AlternateContent to its mc:Choice branch BEFORE
@@ -377,7 +404,10 @@ function buildTableObject(blob: readonly ObjectBlobNode[]): CapturedBodyObject |
   // doubling interiorTexts.
   const normalized = stripAlternateContentFallback(tableNode);
   const dims = tableDimensions(normalized);
-  const anchored = anchorInteriorParagraphs(normalized);
+  // #650: no hiddenSubtrees applies to a table root (that set is a text-box
+  // concept, resolveHiddenTxbxContentNodes), so the middle arg stays the
+  // default empty set — only vanishCharStyleIds is threaded through here.
+  const anchored = anchorInteriorParagraphs(normalized, undefined, styleMap.vanishCharStyleIds);
   return {
     kind: 'table',
     floating: false,
@@ -385,6 +415,7 @@ function buildTableObject(blob: readonly ObjectBlobNode[]): CapturedBodyObject |
     ...dims,
     blob: [anchored.node],
     interiorTexts: anchored.interiorTexts,
+    vanishCharStyleIds: styleMap.vanishCharStyleIds,
   };
 }
 
@@ -396,7 +427,7 @@ function extractTableObjects(
   for (const table of tables) {
     const classification = classifyTableVisibility(table.blob, styleMap);
     if (!classification || classification.kind === 'hidden') continue;
-    const object = buildTableObject(table.blob);
+    const object = buildTableObject(table.blob, styleMap);
     if (object) captured.push({ precedingParagraphIndex: table.precedingParagraphIndex, object });
   }
   return captured;
@@ -555,7 +586,8 @@ function isDroppedEntry(
 function buildTextBoxObject(
   hostBlob: readonly ObjectBlobNode[],
   classification: TextBoxClassification,
-  hiddenFlags: readonly boolean[]
+  hiddenFlags: readonly boolean[],
+  styleMap: StyleMap
 ): CapturedBodyObject | undefined {
   const hostNode = hostBlob[0];
   if (!hostNode) return undefined;
@@ -566,13 +598,14 @@ function buildTextBoxObject(
   // interior text edit diverge from a fallback nobody edited.
   const normalized = stripAlternateContentFallback(hostNode);
   const hiddenSet = resolveHiddenTxbxContentNodes(normalized, hiddenFlags);
-  const anchored = anchorInteriorParagraphs(normalized, hiddenSet);
+  const anchored = anchorInteriorParagraphs(normalized, hiddenSet, styleMap.vanishCharStyleIds);
   return {
     kind: 'textBox',
     floating: classification.floating,
     generation: classification.generation,
     blob: [anchored.node],
     interiorTexts: anchored.interiorTexts,
+    vanishCharStyleIds: styleMap.vanishCharStyleIds,
   };
 }
 
@@ -693,7 +726,9 @@ function collectParagraphDrawing(
   if (!chosen) {
     return { dropped };
   }
-  const object = blob ? buildTextBoxObject(blob, chosen.classification, hiddenFlags) : undefined;
+  const object = blob
+    ? buildTextBoxObject(blob, chosen.classification, hiddenFlags, styleMap)
+    : undefined;
   return object ? { object: { paragraphIndex, object }, dropped: [] } : { dropped: [] };
 }
 

From d8019de3b1e737c29546680c94e376c302233d32 Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 14:23:06 -0700
Subject: [PATCH 05/17] fix(parser): satisfy lint gates for #650 vanish
 threading
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two lint fixes on top of the prior vanishCharStyleIds threading commit:
sonarjs/no-alphabetical-sort wants an explicit localeCompare comparator
on the persisted-array sort, and the run-level vanish predicate
(isOnOffEnabled/hasRunVanish/resolveRunVanish) is split out of
body-objects.ts into its own body-object-vanish.ts — re-exported from
its established public surface — to bring body-objects.ts back under
the repo's enforced 400-line max-lines budget.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/parser/docx/body-object-attach.ts |  2 +-
 src/parser/docx/body-object-vanish.ts | 86 +++++++++++++++++++++++++++
 src/parser/docx/body-objects.ts       | 78 ++++--------------------
 3 files changed, 97 insertions(+), 69 deletions(-)
 create mode 100644 src/parser/docx/body-object-vanish.ts

diff --git a/src/parser/docx/body-object-attach.ts b/src/parser/docx/body-object-attach.ts
index 5f7683eb..8a6c0442 100644
--- a/src/parser/docx/body-object-attach.ts
+++ b/src/parser/docx/body-object-attach.ts
@@ -48,7 +48,7 @@ function toObjectMeta(captured: CapturedBodyObject): ObjectMeta {
     ...(captured.rows !== undefined ? { rows: captured.rows } : {}),
     ...(captured.columns !== undefined ? { columns: captured.columns } : {}),
     ...(captured.vanishCharStyleIds.size > 0
-      ? { vanishCharStyleIds: [...captured.vanishCharStyleIds].sort() }
+      ? { vanishCharStyleIds: [...captured.vanishCharStyleIds].sort((a, b) => a.localeCompare(b)) }
       : {}),
     blob: [...captured.blob],
   };
diff --git a/src/parser/docx/body-object-vanish.ts b/src/parser/docx/body-object-vanish.ts
new file mode 100644
index 00000000..33456fd1
--- /dev/null
+++ b/src/parser/docx/body-object-vanish.ts
@@ -0,0 +1,86 @@
+// Run-level vanish resolution for the body-object capture walk (#641/#650).
+// Split out of body-objects.ts purely to keep that file under the repo's
+// enforced `max-lines` budget — no behavior of its own moved, and no shared
+// dependency on body-objects.ts's other node-navigation helpers: this file
+// keeps its OWN minimal tagOf/directChildrenByTag copies, mirroring the
+// established per-module-helper pattern body-order.ts and body-objects.ts
+// themselves already document (self-contained beats a cross-file import that
+// would otherwise create a circular dependency back into body-objects.ts).
+import { getAttrVal } from './xml-utils.js';
+import type { ObjectBlobNode } from '../../ast/index.js';
+
+function tagOf(node: ObjectBlobNode): string | undefined {
+  return Object.keys(node).find((key) => key !== ':@');
+}
+
+function isBlobNodeArray(value: unknown): value is readonly ObjectBlobNode[] {
+  return Array.isArray(value);
+}
+
+function directChildrenByTag(node: ObjectBlobNode, tag: string): readonly ObjectBlobNode[] {
+  const nodeTag = tagOf(node);
+  if (!nodeTag) return [];
+  const value = node[nodeTag];
+  return isBlobNodeArray(value) ? value.filter((child) => tagOf(child) === tag) : [];
+}
+
+// `w:vanish` is an OOXML ST_OnOff toggle (ECMA-376 §17.3.2.45): bare or
+// `w:val` in {1,true,on} means ON; an explicit `w:val` in {0,false,off} means
+// the toggle is switched OFF — a VISIBLE run — most often because the run is
+// overriding an inherited vanish from its style. Treating the mere PRESENCE
+// of the element as "hidden" therefore suppresses visible text.
+//
+// This is not hypothetical: two real CPI corpus fixtures carry 15
+// `<w:vanish w:val="0"/>` runs between them, several of them text-bearing
+// (`CPI_COMMUNICATIONS_RACK_MOUNTED_POWER_PROTECTION_CSIMFS.docx` has
+// "Select voltage/phase; breaker number, " and "rating" in exactly that
+// shape). Since collectText's suppression in body-objects.ts is a
+// text-DROPPING path, getting this backwards would silently lose visible
+// spec text inside a captured table/text-box — the opposite of ADR-072's
+// no-silent-loss posture. Erring toward keeping text is the safe direction:
+// a missed suppression is a visible leak a test can catch, a wrong
+// suppression is invisible data loss.
+function isOnOffEnabled(node: ObjectBlobNode): boolean {
+  const val = getAttrVal(node[':@']).toLowerCase();
+  return val !== '0' && val !== 'false' && val !== 'off';
+}
+
+// Straight OR port of document.ts's own `runIsVanish`: a run is hidden if
+// EITHER its own `w:rPr>w:vanish` is an enabled ST_OnOff toggle, OR its
+// `w:rPr>w:rStyle` names a character style present in the caller's
+// `vanishCharStyleIds` (the StyleMap's resolved set of character styles that
+// themselves carry an enabled `w:vanish`). No special-casing between the two
+// signals — a resolved-off direct `<w:vanish w:val="0"/>` does not override a
+// matching rStyle, mirroring document.ts's own behaviour exactly (#650).
+// `vanishCharStyleIds` defaults to an empty set so a caller that has none to
+// offer (object-blob-edit.ts's rewriteFirstText before its own #650 wiring,
+// #648's extract.ts) keeps compiling and behaving byte-for-byte unchanged.
+// body-objects.ts's collectText threads the real set through on every call.
+//
+// EXPORTED (re-exported from body-objects.ts, its established public surface)
+// so object-blob-edit.ts's `rewriteFirstText` applies the SAME rule when it
+// writes an edit back. That walk's stated contract is to reach text
+// "wherever capture read it from"; once capture started skipping vanish runs,
+// a second, drifting copy of this predicate there would place edits into
+// hidden runs and blank the visible ones. One definition, both directions
+// (ADR-092).
+export function hasRunVanish(
+  node: ObjectBlobNode,
+  vanishCharStyleIds: ReadonlySet<string> = new Set()
+): boolean {
+  if (tagOf(node) !== 'w:r') return false;
+  const rPr = directChildrenByTag(node, 'w:rPr')[0];
+  if (!rPr) return false;
+  return resolveRunVanish(rPr, vanishCharStyleIds);
+}
+
+// The two OR'd vanish signals, split out of hasRunVanish purely to keep that
+// function's cognitive complexity low — no behavior of its own. `getAttrVal`
+// applied to the w:rStyle node's own `:@` attrs mirrors isOnOffEnabled's
+// identical read of a w:vanish node's `:@` above.
+function resolveRunVanish(rPr: ObjectBlobNode, vanishCharStyleIds: ReadonlySet<string>): boolean {
+  if (directChildrenByTag(rPr, 'w:vanish').some(isOnOffEnabled)) return true;
+  const rStyleNode = directChildrenByTag(rPr, 'w:rStyle')[0];
+  const rStyle = rStyleNode ? getAttrVal(rStyleNode[':@']) : '';
+  return rStyle !== '' && vanishCharStyleIds.has(rStyle);
+}
diff --git a/src/parser/docx/body-objects.ts b/src/parser/docx/body-objects.ts
index c61a989b..44d7b592 100644
--- a/src/parser/docx/body-objects.ts
+++ b/src/parser/docx/body-objects.ts
@@ -19,7 +19,7 @@
 // itself for an interior leaf.
 
 import { v4 as uuidv4 } from 'uuid';
-import { createOrderedDocumentXmlBuilder, getAttrVal, toArray } from './xml-utils.js';
+import { createOrderedDocumentXmlBuilder, toArray } from './xml-utils.js';
 import { classifyTopLevelTables } from './tables.js';
 import { extractParagraphText, isParagraphVanish } from './document.js';
 import { classifyBodyDrawing, unwrapAlternateContent } from './body-drawings.js';
@@ -28,6 +28,7 @@ import { pairRunOrder } from './header-footer-run-order.js';
 import { wrapBlobParagraphWithAnchor } from './object-anchor.js';
 import { stripAlternateContentFallback } from './alternate-content.js';
 import { resolveHiddenTxbxContentNodes } from './body-text-box-visibility.js';
+import { hasRunVanish } from './body-object-vanish.js';
 import type { ClassifiedTopLevelTable } from './tables.js';
 import type { BodyDrawingClassification } from './body-drawings.js';
 import type { BodyOrder, BodyOrderTable } from './body-order.js';
@@ -150,73 +151,14 @@ function tableDimensions(tableNode: ObjectBlobNode): TableDimensions {
 
 // ─── interior paragraph text + SDT anchoring ────────────────────────────────
 
-// `w:vanish` is an OOXML ST_OnOff toggle (ECMA-376 §17.3.2.45): bare or
-// `w:val` in {1,true,on} means ON; an explicit `w:val` in {0,false,off} means
-// the toggle is switched OFF — a VISIBLE run — most often because the run is
-// overriding an inherited vanish from its style. Treating the mere PRESENCE
-// of the element as "hidden" therefore suppresses visible text.
-//
-// This is not hypothetical: two real CPI corpus fixtures carry 15
-// `<w:vanish w:val="0"/>` runs between them, several of them text-bearing
-// (`CPI_COMMUNICATIONS_RACK_MOUNTED_POWER_PROTECTION_CSIMFS.docx` has
-// "Select voltage/phase; breaker number, " and "rating" in exactly that
-// shape). Since collectText's suppression below is a text-DROPPING path,
-// getting this backwards would silently lose visible spec text inside a
-// captured table/text-box — the opposite of ADR-072's no-silent-loss
-// posture. Erring toward keeping text is the safe direction: a missed
-// suppression is a visible leak a test can catch, a wrong suppression is
-// invisible data loss.
-function isOnOffEnabled(node: ObjectBlobNode): boolean {
-  const val = getAttrVal(node[':@']).toLowerCase();
-  return val !== '0' && val !== 'false' && val !== 'off';
-}
-
-// #641/#650: w:rPr>w:vanish check on a run, blob-tree-side — on the
-// preserveOrder ObjectBlobNode shape rather than document.ts's grouped `raw`
-// tree. The two trees are structurally different, and this module already
-// keeps its own self-contained tagOf/childrenOf/directChildrenByTag trio
-// rather than importing document.ts's, per the established per-module
-// pattern body-text-box-visibility.ts's own header documents.
-//
-// Straight OR port of document.ts's own `runIsVanish`: a run is hidden if
-// EITHER its own `w:rPr>w:vanish` is an enabled ST_OnOff toggle, OR its
-// `w:rPr>w:rStyle` names a character style present in the caller's
-// `vanishCharStyleIds` (the StyleMap's resolved set of character styles that
-// themselves carry an enabled `w:vanish`). No special-casing between the two
-// signals — a resolved-off direct `<w:vanish w:val="0"/>` does not override a
-// matching rStyle, mirroring document.ts's own behaviour exactly (#650).
-// `vanishCharStyleIds` defaults to an empty set so a caller that has none to
-// offer (object-blob-edit.ts's rewriteFirstText before its own #650 wiring,
-// #648's extract.ts) keeps compiling and behaving byte-for-byte unchanged.
-// collectText below now threads the real set through on every call — see its
-// own comment.
-//
-// EXPORTED so object-blob-edit.ts's `rewriteFirstText` applies the SAME rule
-// when it writes an edit back. That walk's stated contract is to reach text
-// "wherever capture read it from"; once capture started skipping vanish runs,
-// a second, drifting copy of this predicate there would place edits into
-// hidden runs and blank the visible ones. One definition, both directions
-// (ADR-092).
-export function hasRunVanish(
-  node: ObjectBlobNode,
-  vanishCharStyleIds: ReadonlySet<string> = new Set()
-): boolean {
-  if (tagOf(node) !== 'w:r') return false;
-  const rPr = directChildrenByTag(node, 'w:rPr')[0];
-  if (!rPr) return false;
-  return resolveRunVanish(rPr, vanishCharStyleIds);
-}
-
-// The two OR'd vanish signals, split out of hasRunVanish purely to keep that
-// function's cognitive complexity low — no behavior of its own. `getAttrVal`
-// applied to the w:rStyle node's own `:@` attrs mirrors isOnOffEnabled's
-// identical read of a w:vanish node's `:@` below.
-function resolveRunVanish(rPr: ObjectBlobNode, vanishCharStyleIds: ReadonlySet<string>): boolean {
-  if (directChildrenByTag(rPr, 'w:vanish').some(isOnOffEnabled)) return true;
-  const rStyleNode = directChildrenByTag(rPr, 'w:rStyle')[0];
-  const rStyle = rStyleNode ? getAttrVal(rStyleNode[':@']) : '';
-  return rStyle !== '' && vanishCharStyleIds.has(rStyle);
-}
+// #641/#650: the run-level vanish predicate (direct `w:rPr>w:vanish` OR a
+// `w:rPr>w:rStyle`-referenced character style in the caller's
+// `vanishCharStyleIds`) lives in body-object-vanish.ts, split out purely to
+// keep this file under the repo's enforced `max-lines` budget — re-exported
+// here so object-blob-edit.ts's `rewriteFirstText` (ADR-092) and this
+// module's own test suite keep importing it from this file's established
+// public surface, unchanged.
+export { hasRunVanish } from './body-object-vanish.js';
 
 // w:t's sole text payload, or undefined for a text-less/malformed node —
 // split out of collectText below purely to keep that function's cognitive

From 78999479ee1f1d5a91496b0d8c768e150f1cd635 Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 14:30:27 -0700
Subject: [PATCH 06/17] feat(parser): thread vanishCharStyleIds through
 object-blob rewrite path (#650)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

replaceAnchoredParagraphText now accepts an optional vanishCharStyleIds
set (default empty), threaded through rewriteFirstText/replaceParagraphContent/
rebuildMatchedSdt/rebuildNode so an edit skips exactly the runs capture
skipped — whether hidden by a direct w:rPr>w:vanish or by a w:rStyle
reference. Without this, an edit could land in an rStyle-hidden run and
blank the visible run beside it, the same capture/rewrite drift #641
fixed for direct w:vanish.

rewriteObjectTextBlob builds the set from the object row's own persisted
ObjectMeta.vanishCharStyleIds (styles.xml is unavailable at rewrite
time) and passes it through; a pre-#650 backfill row with the field
entirely absent behaves identically to today (empty set).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../object-text-edit.integration.test.ts      | 104 ++++++++++++++++++
 src/db/queries/object-text-edit.ts            |  15 ++-
 src/parser/docx/object-blob-edit.test.ts      |  62 +++++++++++
 src/parser/docx/object-blob-edit.ts           |  49 +++++++--
 4 files changed, 217 insertions(+), 13 deletions(-)

diff --git a/src/db/queries/object-text-edit.integration.test.ts b/src/db/queries/object-text-edit.integration.test.ts
index 6d6f31c4..f3b1f250 100644
--- a/src/db/queries/object-text-edit.integration.test.ts
+++ b/src/db/queries/object-text-edit.integration.test.ts
@@ -66,6 +66,48 @@ function rewrittenParagraph(text: string): ObjectBlobNode {
   return { 'w:p': [{ 'w:r': [{ 'w:t': [{ '#text': text }] }] }] };
 }
 
+// #650 — an anchored paragraph whose interior carries a run hidden ONLY via
+// w:rStyle (named in the object row's own persisted vanishCharStyleIds meta
+// field) ahead of an ordinary visible run.
+function styleHiddenAnchoredParagraph(
+  uuid: string,
+  hiddenText: string,
+  visibleText: string
+): ObjectBlobNode {
+  return {
+    'w:sdt': [
+      { 'w:sdtPr': [{ 'w:tag': [], ':@': { '@_w:val': `${UUID_TAG_PREFIX}${uuid}` } }] },
+      {
+        'w:sdtContent': [
+          {
+            'w:p': [
+              {
+                'w:r': [
+                  { 'w:rPr': [{ 'w:rStyle': [], ':@': { '@_w:val': 'HiddenChar' } }] },
+                  { 'w:t': [{ '#text': hiddenText }] },
+                ],
+              },
+              { 'w:r': [{ 'w:t': [{ '#text': visibleText }] }] },
+            ],
+          },
+        ],
+      },
+    ],
+  } as ObjectBlobNode;
+}
+
+function tableMetaWithVanishStyle(hiddenText: string, visibleText: string): ObjectMeta {
+  return {
+    kind: 'table',
+    floating: false,
+    generation: 'drawingml',
+    rows: 1,
+    columns: 1,
+    vanishCharStyleIds: ['HiddenChar'],
+    blob: [{ 'w:tc': [styleHiddenAnchoredParagraph(UUID_A, hiddenText, visibleText)] }],
+  };
+}
+
 describe('rewriteObjectTextBlob — DB orchestration for anchored object-blob edits (#519)', () => {
   let specId: string;
 
@@ -189,4 +231,66 @@ describe('rewriteObjectTextBlob — DB orchestration for anchored object-blob ed
       expect(findAnchoredParagraph(meta.blob, UUID_B)).toEqual(rewrittenParagraph('concurrent B'));
     }
   );
+
+  // #650 regression — the exact capture-only-fix gap: without threading the
+  // object row's own persisted vanishCharStyleIds into the rewrite path, an
+  // edit would land in the w:rStyle-hidden run (invisible in Word) and blank
+  // the visible run beside it. rewriteObjectTextBlob must read
+  // meta.vanishCharStyleIds and apply the SAME predicate capture used.
+  it(
+    '#650 regression: rewrite lands the edit in the next VISIBLE run, not a run hidden via ' +
+      "w:rStyle — using the object row's own persisted vanishCharStyleIds",
+    async () => {
+      const objectId = await insertObjectRow(
+        tableMetaWithVanishStyle('HIDDEN SECRET', 'visible original')
+      );
+
+      await runInTransaction((client) =>
+        rewriteObjectTextBlob(client, specId, objectId, UUID_A, 'edited text')
+      );
+
+      const meta = await objectDataOf(objectId);
+      const found = findAnchoredParagraph(meta.blob, UUID_A);
+      const xml = JSON.stringify(found);
+      expect(xml).toContain('edited text');
+      expect(xml).not.toContain('visible original');
+      // the rStyle-hidden run is untouched — neither overwritten nor blanked
+      expect(xml).toContain('HIDDEN SECRET');
+      // vanishCharStyleIds itself round-trips unchanged alongside the edit
+      expect(meta.vanishCharStyleIds).toEqual(['HiddenChar']);
+    }
+  );
+
+  // #650 — JSONB persistence round-trip: vanishCharStyleIds survives a
+  // rewrite byte-identical, alongside every other unrelated meta field.
+  it('invariant: vanishCharStyleIds round-trips byte-identical through a rewrite', async () => {
+    const meta = tableMetaWithVanishStyle('HIDDEN SECRET', 'original');
+    const objectId = await insertObjectRow(meta);
+
+    await runInTransaction((client) =>
+      rewriteObjectTextBlob(client, specId, objectId, UUID_A, 'rewritten')
+    );
+
+    const after = await objectDataOf(objectId);
+    expect(after.vanishCharStyleIds).toEqual(meta.vanishCharStyleIds);
+    expect(after.kind).toBe(meta.kind);
+    expect(after.rows).toBe(meta.rows);
+    expect(after.columns).toBe(meta.columns);
+  });
+
+  // #650 — backfill row: a row captured BEFORE this change carries no
+  // vanishCharStyleIds key at all. rewriteObjectTextBlob must treat that
+  // exactly like an empty set (today's unchanged behaviour), never throw or
+  // misbehave on the absent field.
+  it('backfill: a row with vanishCharStyleIds entirely absent edits normally, field stays absent', async () => {
+    const objectId = await insertObjectRow(twoCellTableMeta('original A', 'original B'));
+
+    await runInTransaction((client) =>
+      rewriteObjectTextBlob(client, specId, objectId, UUID_A, 'rewritten A')
+    );
+
+    const meta = await objectDataOf(objectId);
+    expect(meta.vanishCharStyleIds).toBeUndefined();
+    expect(findAnchoredParagraph(meta.blob, UUID_A)).toEqual(rewrittenParagraph('rewritten A'));
+  });
 });
diff --git a/src/db/queries/object-text-edit.ts b/src/db/queries/object-text-edit.ts
index e03ba68a..2a05d820 100644
--- a/src/db/queries/object-text-edit.ts
+++ b/src/db/queries/object-text-edit.ts
@@ -62,7 +62,20 @@ export async function rewriteObjectTextBlob(
       );
     }
 
-    const newBlob = replaceAnchoredParagraphText(meta.blob, anchorUuid, newText);
+    // #650 — the SAME resolved character-style-id set capture consulted
+    // (persisted on the object row itself as ObjectMeta.vanishCharStyleIds,
+    // since styles.xml is unavailable here at rewrite time) so a run capture
+    // skipped as w:rStyle-hidden is skipped by the rewrite walk too. `?? []`
+    // covers a pre-#650 backfill row that carries no such key at all —
+    // identical to today's unchanged behaviour (no run treated as hidden by
+    // style).
+    const vanishCharStyleIds = new Set(meta.vanishCharStyleIds ?? []);
+    const newBlob = replaceAnchoredParagraphText(
+      meta.blob,
+      anchorUuid,
+      newText,
+      vanishCharStyleIds
+    );
     if (!newBlob) {
       throw new DatabaseError(
         `rewriteObjectTextBlob: anchor ${anchorUuid} not found in object ${parentId}'s blob`
diff --git a/src/parser/docx/object-blob-edit.test.ts b/src/parser/docx/object-blob-edit.test.ts
index 2a574467..21bf629f 100644
--- a/src/parser/docx/object-blob-edit.test.ts
+++ b/src/parser/docx/object-blob-edit.test.ts
@@ -337,4 +337,66 @@ describe('replaceAnchoredParagraphText', () => {
     expect(xml).toContain('edited text');
     expect(xml).not.toContain('visible original');
   });
+
+  // #650 — capture's collectText resolves a run hidden ONLY via a w:rStyle
+  // reference (not a direct w:rPr>w:vanish) against the captured
+  // vanishCharStyleIds set. The rewrite walk must apply the SAME rule with
+  // the SAME set, via replaceAnchoredParagraphText's new optional trailing
+  // param — otherwise capture and rewrite disagree about which run is
+  // hidden, and an edit can land in a run the document never shows.
+  it('skips a run hidden via w:rStyle when the matching vanishCharStyleIds set is passed', () => {
+    const hiddenViaStyle = {
+      'w:r': [
+        { 'w:rPr': [{ 'w:rStyle': [], ':@': { '@_w:val': 'HiddenChar' } }] },
+        { 'w:t': [{ '#text': 'HIDDEN VIA STYLE' }] },
+      ],
+    } as ObjectBlobNode;
+    const interior = paragraph(hiddenViaStyle, run('visible original'));
+    const blob = [cell(wrapBlobParagraphWithAnchor(interior, UUID_A))];
+
+    const result = replaceAnchoredParagraphText(
+      blob,
+      UUID_A,
+      'edited text',
+      new Set(['HiddenChar'])
+    );
+    expect(result).toBeDefined();
+    const xml = toXml(result as readonly ObjectBlobNode[]);
+
+    // the edit went into the VISIBLE run
+    expect(xml).toContain('edited text');
+    expect(xml).not.toContain('visible original');
+    // the rStyle-hidden run is untouched — neither overwritten nor blanked
+    expect(xml).toContain('HIDDEN VIA STYLE');
+    expect([...xml.matchAll(/edited text/g)]).toHaveLength(1);
+  });
+
+  // Without the matching vanishCharStyleIds set (the default empty set,
+  // e.g. a caller with no style map to offer), a run hidden only via
+  // w:rStyle cannot be recognized as hidden — the predicate has no style
+  // data to resolve the rStyle name against. This documents the boundary
+  // (mirrors hasRunVanish's own default-empty-set behaviour) rather than
+  // asserting a false capability.
+  it('treats an w:rStyle-hidden run as visible when vanishCharStyleIds is omitted (default empty set)', () => {
+    const hiddenViaStyle = {
+      'w:r': [
+        { 'w:rPr': [{ 'w:rStyle': [], ':@': { '@_w:val': 'HiddenChar' } }] },
+        { 'w:t': [{ '#text': 'HIDDEN VIA STYLE' }] },
+      ],
+    } as ObjectBlobNode;
+    const interior = paragraph(hiddenViaStyle, run('visible original'));
+    const blob = [cell(wrapBlobParagraphWithAnchor(interior, UUID_A))];
+
+    const result = replaceAnchoredParagraphText(blob, UUID_A, 'edited text');
+    expect(result).toBeDefined();
+    const xml = toXml(result as readonly ObjectBlobNode[]);
+
+    // no vanishCharStyleIds offered: the rStyle run is treated as an
+    // ordinary run and, being first in document order, takes the edit —
+    // the second run is then blanked per the usual multi-run rewrite
+    // semantics (see "multi-run rewrite" invariant above), not skipped.
+    expect(xml).toContain('edited text');
+    expect(xml).not.toContain('visible original');
+    expect(xml).not.toContain('HIDDEN VIA STYLE');
+  });
 });
diff --git a/src/parser/docx/object-blob-edit.ts b/src/parser/docx/object-blob-edit.ts
index 321610ff..5380af1e 100644
--- a/src/parser/docx/object-blob-edit.ts
+++ b/src/parser/docx/object-blob-edit.ts
@@ -193,20 +193,25 @@ interface TextPlacement {
  * (ADR-072's no-silent-loss posture), and leaving it keeps the post-edit
  * visible text exactly equal to `newText`, which is what capture will read
  * back. */
-function rewriteFirstText(node: ObjectBlobNode, newText: string, placed: boolean): TextPlacement {
+function rewriteFirstText(
+  node: ObjectBlobNode,
+  newText: string,
+  placed: boolean,
+  vanishCharStyleIds: ReadonlySet<string>
+): TextPlacement {
   const tag = tagOf(node);
   if (!tag) return { node, placed };
   if (tag === 'w:t') {
     return { node: rewriteTextNode(node, placed ? '' : newText), placed: true };
   }
-  if (hasRunVanish(node)) return { node, placed };
+  if (hasRunVanish(node, vanishCharStyleIds)) return { node, placed };
   const value = node[tag];
   if (!isBlobNodeArray(value)) return { node, placed };
   let changed = false;
   let nowPlaced = placed;
   const newChildren: ObjectBlobNode[] = [];
   for (const child of value) {
-    const result = rewriteFirstText(child, newText, nowPlaced);
+    const result = rewriteFirstText(child, newText, nowPlaced, vanishCharStyleIds);
     if (result.node !== child) changed = true;
     nowPlaced = result.placed;
     newChildren.push(result.node);
@@ -228,22 +233,31 @@ function rewriteFirstText(node: ObjectBlobNode, newText: string, placed: boolean
  * never anchors a whitespace-only paragraph, body-objects.ts's
  * `transformChildren`), kept only for totality on malformed input.
  */
-function replaceParagraphContent(paragraph: ObjectBlobNode, newText: string): ObjectBlobNode {
+function replaceParagraphContent(
+  paragraph: ObjectBlobNode,
+  newText: string,
+  vanishCharStyleIds: ReadonlySet<string>
+): ObjectBlobNode {
   const tag = tagOf(paragraph);
   // Malformed defensive no-op — mirrors body-objects.ts's own
   // transformInteriorParagraphs guard; a paragraph the parser itself wrapped
   // always has exactly one tag.
   if (!tag) return paragraph;
-  const rewritten = rewriteFirstText(paragraph, newText, false);
+  const rewritten = rewriteFirstText(paragraph, newText, false, vanishCharStyleIds);
   if (rewritten.placed) return rewritten.node;
   const children = childrenOf(paragraph);
   const newRun: ObjectBlobNode = { 'w:r': [{ 'w:t': [{ '#text': newText }] }] };
   return withChildren(paragraph, tag, [...children, newRun]);
 }
 
-function rebuildMatchedSdt(sdtNode: ObjectBlobNode, uuid: string, newText: string): ObjectBlobNode {
+function rebuildMatchedSdt(
+  sdtNode: ObjectBlobNode,
+  uuid: string,
+  newText: string,
+  vanishCharStyleIds: ReadonlySet<string>
+): ObjectBlobNode {
   const paragraph = interiorParagraphOf(sdtNode, uuid); // throws on malformed
-  const newParagraph = replaceParagraphContent(paragraph, newText);
+  const newParagraph = replaceParagraphContent(paragraph, newText, vanishCharStyleIds);
   const newSdtChildren = childrenOf(sdtNode).map((child) =>
     tagOf(child) === 'w:sdtContent' ? withChildren(child, 'w:sdtContent', [newParagraph]) : child
   );
@@ -259,7 +273,8 @@ function rebuildNode(
   node: ObjectBlobNode,
   uuid: string,
   newText: string,
-  placed: boolean
+  placed: boolean,
+  vanishCharStyleIds: ReadonlySet<string>
 ): RebuildResult {
   const tag = tagOf(node);
   if (!tag) return { node, placed };
@@ -270,14 +285,14 @@ function rebuildNode(
   if (!isBlobNodeArray(value)) return { node, placed };
 
   if (!placed && tag === 'w:sdt' && readSdtUuid(node) === uuid) {
-    return { node: rebuildMatchedSdt(node, uuid, newText), placed: true };
+    return { node: rebuildMatchedSdt(node, uuid, newText, vanishCharStyleIds), placed: true };
   }
 
   let changed = false;
   let nowPlaced = placed;
   const newChildren: ObjectBlobNode[] = [];
   for (const child of value) {
-    const result = rebuildNode(child, uuid, newText, nowPlaced);
+    const result = rebuildNode(child, uuid, newText, nowPlaced, vanishCharStyleIds);
     if (result.node !== child) changed = true;
     if (result.placed) nowPlaced = true;
     newChildren.push(result.node);
@@ -296,16 +311,26 @@ function rebuildNode(
  * `uuid` is not anchored anywhere in `blob` (total). Throws `ParserError` if
  * the matched anchor's own `w:sdtContent` is corrupted (see
  * `interiorParagraphOf`).
+ *
+ * `vanishCharStyleIds` (#650, optional, defaults to an empty set) is the
+ * SAME resolved character-style-id set body-objects.ts's `collectText`
+ * consulted at capture time (persisted as `ObjectMeta.vanishCharStyleIds`) —
+ * threaded through `rewriteFirstText`'s `hasRunVanish` call so this walk
+ * skips exactly the runs capture skipped, whether hidden by a direct
+ * `w:rPr>w:vanish` or by a `w:rStyle` reference into that set. A default of
+ * `new Set()` keeps this call byte-for-byte unchanged for callers with no
+ * style data to offer.
  */
 export function replaceAnchoredParagraphText(
   blob: readonly ObjectBlobNode[],
   uuid: string,
-  newText: string
+  newText: string,
+  vanishCharStyleIds: ReadonlySet<string> = new Set()
 ): readonly ObjectBlobNode[] | undefined {
   let placed = false;
   const newBlob: ObjectBlobNode[] = [];
   for (const node of blob) {
-    const result = rebuildNode(node, uuid, newText, placed);
+    const result = rebuildNode(node, uuid, newText, placed, vanishCharStyleIds);
     if (result.placed) placed = true;
     newBlob.push(result.node);
   }

From af3b1fe5980b69dfe3d6a68833fc0e79166da4be Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 14:51:13 -0700
Subject: [PATCH 07/17] fix(cross): preserve rStyle-hidden object text across
 DOCX regeneration (#650)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Task 6/10: byte-identical round-trip proof for the #650 vanishCharStyleIds
capture path, plus full 666-fixture corpus revalidation (0 changed).

Writing the "with vanishCharStyleIds present" round-trip test surfaced a
real privacy regression: generateDocx never emitted a `w:styles` character
style definition for a captured object's referenced vanish character style,
so re-parsing a regenerated document lost `vanishCharStyleIds` resolution
and a run correctly hidden at first capture surfaced as plain visible text
on the second parse. Fixed in a new generator/object-vanish-styles.ts,
using the vanishCharStyleIds already persisted per object (#650 tasks 1-5)
to reconstruct a minimal enabled-vanish character style stub per referenced
id, wired into both generateDocx and generateManual.

Also inspected merge/object-fingerprint.ts per the task brief: it is
text-blind and structure-only (tag shapes, never rPr/rStyle/vanish), so it
has no latent dependency on vanishCharStyleIds — no change needed there.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/generator/index.ts                        |  17 +++
 src/generator/object-vanish-styles.test.ts    |  82 ++++++++++++++
 src/generator/object-vanish-styles.ts         |  61 ++++++++++
 .../docx/body-object-round-trip.test.ts       | 105 +++++++++++++++++-
 4 files changed, 263 insertions(+), 2 deletions(-)
 create mode 100644 src/generator/object-vanish-styles.test.ts
 create mode 100644 src/generator/object-vanish-styles.ts

diff --git a/src/generator/index.ts b/src/generator/index.ts
index 77d69a2e..4e06c996 100644
--- a/src/generator/index.ts
+++ b/src/generator/index.ts
@@ -23,6 +23,11 @@ import {
 import { renderHeaderFooterComposition } from './header-footer.js';
 import type { HeaderFooterRenderResult } from './header-footer.js';
 import type { HeaderFooterFieldContext, HeaderFooterFieldValues } from './header-footer-fields.js';
+import {
+  collectVanishCharacterStyleIds,
+  vanishCharacterStyleOptions,
+} from './object-vanish-styles.js';
+import type { IStylesOptions } from 'docx';
 
 export { generateSec } from './sec/index.js';
 export { renderMarkdown } from './markdown.js';
@@ -212,6 +217,16 @@ function documentLevelOptions(render: HeaderFooterRenderResult | undefined): {
   return render?.evenAndOddHeaders ? { evenAndOddHeaderAndFooters: true } : {};
 }
 
+// #650 task 6/10: a `styles` block is only emitted when at least one
+// captured object across `trees` actually referenced a vanish-resolved
+// character style — the overwhelmingly common case has none, and this keeps
+// that case's output byte-identical to before this fix (see
+// object-vanish-styles.ts's own module comment for why this exists).
+function vanishStylesOptions(trees: readonly SpecTree[]): { readonly styles?: IStylesOptions } {
+  const ids = collectVanishCharacterStyleIds(trees);
+  return ids.length > 0 ? { styles: { characterStyles: vanishCharacterStyleOptions(ids) } } : {};
+}
+
 // Section-level options driven by a header/footer render: docx's
 // ISectionOptions carries `headers`/`footers` as siblings of `properties`,
 // while titlePage/page-number-start/page-size live inside `properties` —
@@ -272,6 +287,7 @@ export async function generateDocx(
     const pageSize = resolvePageSize(tree.pageSize);
     const doc = new Document({
       ...documentLevelOptions(render),
+      ...vanishStylesOptions([tree]),
       numbering: { config: [buildSpecNumberingConfig(rules, SPEC_NUM_REF)] },
       sections: [{ ...sectionHeaderFooterOptions(render, pageSize), children }],
     });
@@ -352,6 +368,7 @@ export async function generateManual(
     const frontMatterPageSize = resolvePageSize(trees[0]?.pageSize);
     const doc = new Document({
       ...documentLevelOptions(firstRender),
+      ...vanishStylesOptions(trees),
       numbering: { config: sections.map((s) => buildSpecNumberingConfig(rules, s.reference)) },
       sections: [
         {
diff --git a/src/generator/object-vanish-styles.test.ts b/src/generator/object-vanish-styles.test.ts
new file mode 100644
index 00000000..ecf0c7ad
--- /dev/null
+++ b/src/generator/object-vanish-styles.test.ts
@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import {
+  collectVanishCharacterStyleIds,
+  vanishCharacterStyleOptions,
+} from './object-vanish-styles.js';
+import type { SpecNode, SpecTree } from '../ast/index.js';
+
+// Minimal SpecNode/SpecTree builders — this module only ever reads
+// `type`/`children`/`meta.object?.vanishCharStyleIds`, so every other field
+// is filled with an arbitrary valid placeholder.
+function node(overrides: Partial<SpecNode> & Pick<SpecNode, 'type'>): SpecNode {
+  return { id: 'n', text: '', children: [], meta: {}, ...overrides };
+}
+
+function objectNode(vanishCharStyleIds?: readonly string[]): SpecNode {
+  return node({
+    type: 'object',
+    meta: {
+      object: {
+        kind: 'table',
+        floating: false,
+        generation: 'drawingml',
+        blob: [{ 'w:tbl': [] }],
+        ...(vanishCharStyleIds !== undefined
+          ? { vanishCharStyleIds: [...vanishCharStyleIds] }
+          : {}),
+      },
+    },
+  });
+}
+
+function tree(parts: readonly SpecNode[]): SpecTree {
+  return { id: 't', section: '00 00 00', title: 'Test', parts };
+}
+
+describe('collectVanishCharacterStyleIds', () => {
+  it('returns an empty array when no tree has any object node', () => {
+    expect(collectVanishCharacterStyleIds([tree([node({ type: 'article' })])])).toEqual([]);
+  });
+
+  it('returns an empty array when an object node carries no vanishCharStyleIds', () => {
+    expect(collectVanishCharacterStyleIds([tree([objectNode()])])).toEqual([]);
+  });
+
+  it('returns an empty array when an object node carries an empty vanishCharStyleIds', () => {
+    expect(collectVanishCharacterStyleIds([tree([objectNode([])])])).toEqual([]);
+  });
+
+  it('collects a single object node’s ids', () => {
+    expect(collectVanishCharacterStyleIds([tree([objectNode(['HiddenChar'])])])).toEqual([
+      'HiddenChar',
+    ]);
+  });
+
+  it('dedupes ids repeated across multiple object nodes and returns them sorted', () => {
+    const trees = [tree([objectNode(['Zeta', 'HiddenChar']), objectNode(['HiddenChar'])])];
+    expect(collectVanishCharacterStyleIds(trees)).toEqual(['HiddenChar', 'Zeta']);
+  });
+
+  it('finds an object node nested arbitrarily deep under non-object ancestors', () => {
+    const nested = node({ type: 'article', children: [objectNode(['Deep'])] });
+    expect(collectVanishCharacterStyleIds([tree([nested])])).toEqual(['Deep']);
+  });
+
+  it('collects across multiple trees (a manual’s multiple sections)', () => {
+    const trees = [tree([objectNode(['A'])]), tree([objectNode(['B'])])];
+    expect(collectVanishCharacterStyleIds(trees)).toEqual(['A', 'B']);
+  });
+});
+
+describe('vanishCharacterStyleOptions', () => {
+  it('returns an empty array for no ids', () => {
+    expect(vanishCharacterStyleOptions([])).toEqual([]);
+  });
+
+  it('builds one enabled-vanish character style option per id, name mirroring id', () => {
+    expect(vanishCharacterStyleOptions(['HiddenChar', 'Other'])).toEqual([
+      { id: 'HiddenChar', name: 'HiddenChar', run: { vanish: true } },
+      { id: 'Other', name: 'Other', run: { vanish: true } },
+    ]);
+  });
+});
diff --git a/src/generator/object-vanish-styles.ts b/src/generator/object-vanish-styles.ts
new file mode 100644
index 00000000..8f520411
--- /dev/null
+++ b/src/generator/object-vanish-styles.ts
@@ -0,0 +1,61 @@
+// Regenerated-styles.xml companion to a captured object blob's persisted
+// `vanishCharStyleIds` (#650 task 6/10 investigation): ADR-072 decision 1
+// re-emits a captured table/text-box's OOXML blob byte-for-byte, INCLUDING
+// any interior run whose `w:rPr>w:rStyle` names a character style that was
+// resolved vanish at capture time — but the generator never previously wrote
+// a `w:styles` section defining custom character styles at all, so that
+// referenced style id was silently ABSENT from the regenerated document.
+// Reopening (or re-parsing) that regenerated file therefore resolved
+// `vanishCharStyleIds` back to empty and the previously-hidden run surfaced
+// as visible plain text — a real privacy regression discovered writing
+// `body-object-round-trip.test.ts`'s "with vanishCharStyleIds present" case,
+// fixed here rather than merely documented, since the data needed to fix it
+// (`ObjectMeta.vanishCharStyleIds`, persisted per object) already exists.
+//
+// The fix only needs to reconstruct enough of the ORIGINAL character style
+// definition for `styles.ts`'s own `characterStyleVanishIds` to resolve the
+// SAME id back into `vanishCharStyleIds` on re-parse — a minimal
+// `w:type="character"` style stub carrying an enabled `w:vanish`, keyed by
+// the exact id the blob's `w:rStyle` already references. No other property
+// of the original style (font, color, basedOn chain, …) is reconstructed:
+// none of it affects the vanish resolution this module exists to restore,
+// and reconstructing it would need the original styles.xml, which SpecR
+// does not retain (out of scope here, same posture as this file's sibling
+// `styles.ts`'s own documented font/spacing/indent/numbering-only scope).
+import type { ICharacterStyleOptions } from 'docx';
+import type { SpecNode, SpecTree } from '../ast/index.js';
+
+function collectFromNodes(nodes: readonly SpecNode[], acc: Set<string>): void {
+  for (const node of nodes) {
+    if (node.type === 'object') {
+      for (const id of node.meta.object?.vanishCharStyleIds ?? []) acc.add(id);
+    }
+    collectFromNodes(node.children, acc);
+  }
+}
+
+/**
+ * Every distinct character-style id referenced as vanish-resolved by ANY
+ * captured object across `trees`, sorted for deterministic output (a
+ * generated document's byte content must not depend on `Set` iteration
+ * order). Empty when no captured object in any tree carries the field —
+ * the overwhelmingly common case, and byte-identical to pre-#650 output.
+ */
+export function collectVanishCharacterStyleIds(trees: readonly SpecTree[]): readonly string[] {
+  const ids = new Set<string>();
+  for (const tree of trees) collectFromNodes(tree.parts, ids);
+  return [...ids].sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Minimal `docx` character-style definitions for `styleIds` — one per id,
+ * carrying only an enabled `w:vanish` (see this module's header for why
+ * nothing else is reconstructed). `name` mirrors `id`: it is never read
+ * back by SpecR's own parser (`styleId`, not `name`, is the correlation
+ * key), only shown to a human opening the file in Word.
+ */
+export function vanishCharacterStyleOptions(
+  styleIds: readonly string[]
+): readonly ICharacterStyleOptions[] {
+  return styleIds.map((id) => ({ id, name: id, run: { vanish: true } }));
+}
diff --git a/src/parser/docx/body-object-round-trip.test.ts b/src/parser/docx/body-object-round-trip.test.ts
index 480cf104..92b1104a 100644
--- a/src/parser/docx/body-object-round-trip.test.ts
+++ b/src/parser/docx/body-object-round-trip.test.ts
@@ -50,6 +50,18 @@ const MINIMAL_STYLES =
   '<?xml version="1.0" encoding="UTF-8"?>' +
   '<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"/>';
 
+// #650 task 6/10: a `styles.xml` defining ONE character style ("HiddenChar")
+// that carries an enabled `w:vanish` — the source data
+// styleVanishTextBoxParagraph's second run references via `w:rStyle`, never
+// a direct `w:rPr>w:vanish` on the run itself. This is what exercises
+// `StyleMap.vanishCharStyleIds` end to end, distinct from every other test
+// in this file (which hides a run/paragraph directly).
+const VANISH_CHAR_STYLE_STYLES =
+  '<?xml version="1.0" encoding="UTF-8"?>' +
+  '<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">' +
+  '<w:style w:type="character" w:styleId="HiddenChar"><w:rPr><w:vanish/></w:rPr></w:style>' +
+  '</w:styles>';
+
 function makeDocumentXml(bodyXml: string): string {
   return (
     `<?xml version="1.0" encoding="UTF-8"?><w:document ${NS}>` +
@@ -57,9 +69,9 @@ function makeDocumentXml(bodyXml: string): string {
   );
 }
 
-async function makeDocx(bodyXml: string): Promise<Buffer> {
+async function makeDocx(bodyXml: string, stylesXml: string = MINIMAL_STYLES): Promise<Buffer> {
   const zip = new JSZip();
-  zip.file('word/styles.xml', MINIMAL_STYLES);
+  zip.file('word/styles.xml', stylesXml);
   zip.file('word/document.xml', makeDocumentXml(bodyXml));
   return zip.generateAsync({ type: 'nodebuffer' });
 }
@@ -154,6 +166,25 @@ function mixedVisibilityTwoTextBoxParagraph(visibleText: string, hiddenText: str
   return `<w:p>${visibleRun}${hiddenRun}</w:p>`;
 }
 
+// #650 task 6/10: the SAME two-separate-boxes shape as
+// mixedVisibilityTwoTextBoxParagraph above, except the SECOND box is hidden
+// PURELY via a `w:rStyle` reference into `VANISH_CHAR_STYLE_STYLES`'s
+// "HiddenChar" character style — never a direct `w:rPr>w:vanish` on the run
+// itself. Two SEPARATE boxes (not one paragraph mixing a visible and a
+// style-hidden run) so the hidden box's own interior paragraph carries NO
+// visible text at all and is therefore NEVER SDT-anchored
+// (body-objects.ts's transformChildren only anchors non-empty-text interior
+// paragraphs) — required for a true byte-identity comparison below: an
+// anchored paragraph mints a FRESH uuid on every capture by design (this
+// file's own header), so only an unanchored subtree can ever be byte-
+// identical across a regenerate + re-parse cycle.
+function styleVanishTwoTextBoxParagraph(visibleText: string, hiddenText: string): string {
+  const visibleRun = textBoxRunXml(1, para(visibleText));
+  const hiddenInterior = `<w:p><w:r><w:rPr><w:rStyle w:val="HiddenChar"/></w:rPr><w:t>${hiddenText}</w:t></w:r></w:p>`;
+  const hiddenRun = textBoxRunXml(2, hiddenInterior);
+  return `<w:p>${visibleRun}${hiddenRun}</w:p>`;
+}
+
 // Every `w:txbxContent` subtree in a generated document.xml, as its exact
 // serialized string (#515 adversarial review) — the unit a byte-identity
 // assertion has to compare. Non-greedy and flat: no fixture in this file
@@ -494,6 +525,76 @@ describe('body object round trip — parse -> generate -> re-parse (#517, WS2 ta
     // pinned by the objectTexts assertions above instead.
     expect(blocksAfter.filter((b) => b.includes('Visible box text'))).toHaveLength(1);
   });
+
+  // #650 task 6/10: every test above hides content via a DIRECT
+  // `w:rPr>w:vanish` (i.e. WITHOUT `vanishCharStyleIds` — that set stays
+  // empty throughout). This is the WITH case: a box hidden PURELY via a
+  // `w:rStyle` reference into a character style that itself carries
+  // `w:vanish` (VANISH_CHAR_STYLE_STYLES's "HiddenChar"). Mirrors the
+  // mixed-visibility test above exactly (two separate boxes, one visible,
+  // one hidden), swapping only the hiding mechanism, and pins three things
+  // with real byte/string equality, never substring containment:
+  //   1. Privacy at capture — the style-hidden box's text never reaches
+  //      interiorTexts, and `ObjectMeta.vanishCharStyleIds` persists the id.
+  //   2. Byte-identity — the hidden box's ENTIRE w:txbxContent (rStyle
+  //      reference included) survives a regenerate + re-parse cycle
+  //      string-for-string, exactly like the direct-vanish case.
+  //   3. Privacy SURVIVES the round trip too — the SECOND parse's own
+  //      `vanishCharStyleIds` resolution must recover "HiddenChar" from the
+  //      REGENERATED document's own styles.xml, or the previously-hidden
+  //      box's text would surface as visible plain text on re-parse (the
+  //      real bug this test caught during task 6's investigation, fixed in
+  //      generator/object-vanish-styles.ts rather than merely documented).
+  it('a text box hidden ONLY via a w:rStyle-referenced vanish character style is excluded from interiorTexts and stays hidden across a full byte-identical regenerate + re-parse cycle (#650)', async () => {
+    const source = await makeDocx(
+      para('Intro paragraph.') +
+        styleVanishTwoTextBoxParagraph('Visible box text', 'Secret style-hidden box text'),
+      VANISH_CHAR_STYLE_STYLES
+    );
+    const { tree } = await parse(source, 'source.docx');
+    const before = objectNodesOf(tree);
+    expect(before).toHaveLength(1);
+    expectObjectMeta(before[0], { kind: 'textBox', generation: 'drawingml', floating: false });
+    // Privacy at capture: the style-hidden box's text never reaches interiorTexts.
+    expect(objectTextsOf(before[0] as SpecNode)).toEqual(['Visible box text']);
+    expect(before[0]?.meta.object?.vanishCharStyleIds).toEqual(['HiddenChar']);
+
+    const docXmlBefore = await generatedDocumentXml(tree);
+    const blocksBefore = txbxContentBlocks(docXmlBefore);
+    expect(blocksBefore).toHaveLength(2);
+    const hiddenBefore = blocksBefore.find((b) => b.includes('Secret style-hidden box text'));
+    expect(hiddenBefore).toBeDefined();
+    // The opaque blob still carries the hidden box's OWN OOXML verbatim —
+    // capture suppresses the ANCHOR, never the underlying content (ADR-072
+    // decision 1) — and, being fully text-empty once its one run is
+    // excluded, it never gets an SDT anchor at all (no round-trip merge
+    // locator can ever address hidden style-vanished content either).
+    expect(hiddenBefore).toContain('<w:rStyle w:val="HiddenChar"/>');
+    expect(hiddenBefore).not.toContain('<w:sdt');
+    expect(hiddenBefore).not.toContain('w:tag');
+
+    const reparsedTree = await regenerateAndReparse(tree);
+    const after = objectNodesOf(reparsedTree);
+
+    expect(after).toHaveLength(1);
+    expectObjectMeta(after[0], { kind: 'textBox', generation: 'drawingml', floating: false });
+    // Privacy holds across the FULL regenerate -> re-parse cycle: the
+    // regenerated document carries a reconstructed "HiddenChar" character
+    // style (generator/object-vanish-styles.ts), so the SECOND parse
+    // resolves the SAME vanishCharStyleIds and the box stays excluded.
+    expect(objectTextsOf(after[0] as SpecNode)).toEqual(['Visible box text']);
+    expect(after[0]?.meta.object?.vanishCharStyleIds).toEqual(['HiddenChar']);
+
+    const docXmlAfter = await generatedDocumentXml(reparsedTree);
+    const blocksAfter = txbxContentBlocks(docXmlAfter);
+    expect(blocksAfter).toHaveLength(2);
+    const hiddenAfter = blocksAfter.find((b) => b.includes('Secret style-hidden box text'));
+    // Byte-identity, actually asserted on bytes: the hidden box's ENTIRE
+    // w:txbxContent serialization is compared string-for-string across the
+    // second generation, never merely probed for a substring.
+    expect(hiddenAfter).toBe(hiddenBefore);
+    expect(blocksAfter.filter((b) => b.includes('Visible box text'))).toHaveLength(1);
+  });
 });
 
 // #519 (WS3 task 2/8, this file's own crux acceptance criterion): the DOCX-

From ea1d8e04a5b58868feee3fc8794596195e5ff77c Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 14:53:34 -0700
Subject: [PATCH 08/17] feat(ast): reject textBox objects with rows/columns set
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ObjectMetaSchema gains a cross-field check (Zod v4 .check()) that
rejects a textBox kind carrying rows and/or columns — table-grid
dimensions a textBox has no grid for. The rule names only kind, rows,
and columns; it never scans for or reacts to other fields, so
additive fields like vanishCharStyleIds stay structurally untouched.
table stays fully unconstrained.

Part B of #650.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/ast/object-schemas.test.ts | 49 ++++++++++++++++++++++++++++++++++
 src/ast/object-schemas.ts      | 36 ++++++++++++++++++-------
 2 files changed, 76 insertions(+), 9 deletions(-)

diff --git a/src/ast/object-schemas.test.ts b/src/ast/object-schemas.test.ts
index 0ce7c420..4444d9a0 100644
--- a/src/ast/object-schemas.test.ts
+++ b/src/ast/object-schemas.test.ts
@@ -111,6 +111,55 @@ describe('ObjectMetaSchema', () => {
   });
 });
 
+// ── kind/rows/columns cross-field check (#650 Part B) ──────────────────────
+// rows/columns are table-grid dimensions; a textBox has no grid. The check
+// names exactly kind, rows, columns — it must never touch vanishCharStyleIds
+// or any other field, additive or otherwise.
+describe('ObjectMetaSchema — textBox/rows/columns cross-field check (#650)', () => {
+  const baseTextBox = {
+    kind: 'textBox' as const,
+    floating: true,
+    generation: 'vml' as const,
+    blob: [{ '#text': 'boxed text' }],
+  };
+  const baseTable = {
+    kind: 'table' as const,
+    floating: false,
+    generation: 'drawingml' as const,
+    rows: 1,
+    columns: 1,
+    blob: TABLE_BLOB,
+  };
+
+  it('rejects a textBox with rows set', () => {
+    expect(ObjectMetaSchema.safeParse({ ...baseTextBox, rows: 1 }).success).toBe(false);
+  });
+
+  it('rejects a textBox with columns set', () => {
+    expect(ObjectMetaSchema.safeParse({ ...baseTextBox, columns: 1 }).success).toBe(false);
+  });
+
+  it('accepts a textBox with neither rows nor columns', () => {
+    expect(ObjectMetaSchema.safeParse(baseTextBox).success).toBe(true);
+  });
+
+  it('leaves table with rows/columns unaffected', () => {
+    expect(ObjectMetaSchema.safeParse(baseTable).success).toBe(true);
+  });
+
+  it('accepts a textBox with vanishCharStyleIds populated and no rows/columns — the check never touches vanishCharStyleIds', () => {
+    const result = ObjectMetaSchema.safeParse({
+      ...baseTextBox,
+      vanishCharStyleIds: ['HiddenChar'],
+    });
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.vanishCharStyleIds).toEqual(['HiddenChar']);
+    expect(result.data.rows).toBeUndefined();
+    expect(result.data.columns).toBeUndefined();
+  });
+});
+
 // ── vanishCharStyleIds (#650) ───────────────────────────────────────────────
 // Resolved w:rStyle → character-style w:vanish IDs, captured alongside the
 // object so capture and rewrite share one source of truth without needing
diff --git a/src/ast/object-schemas.ts b/src/ast/object-schemas.ts
index 6ac24c65..dadc055e 100644
--- a/src/ast/object-schemas.ts
+++ b/src/ast/object-schemas.ts
@@ -83,15 +83,33 @@ export const ObjectBlobNodeSchema: z.ZodType<ObjectBlobNode> = z.custom<ObjectBl
  * fully interchangeable (today's behaviour — no runs treated as hidden by
  * style), so a row captured before this change loads/edits unchanged.
  */
-export const ObjectMetaSchema = z.object({
-  kind: ObjectKindSchema,
-  floating: z.boolean(),
-  generation: ObjectGenerationSchema,
-  rows: z.number().int().positive().exactOptional(),
-  columns: z.number().int().positive().exactOptional(),
-  vanishCharStyleIds: z.array(z.string()).exactOptional(),
-  blob: z.array(ObjectBlobNodeSchema).check(z.minLength(1)),
-});
+export const ObjectMetaSchema = z
+  .object({
+    kind: ObjectKindSchema,
+    floating: z.boolean(),
+    generation: ObjectGenerationSchema,
+    rows: z.number().int().positive().exactOptional(),
+    columns: z.number().int().positive().exactOptional(),
+    vanishCharStyleIds: z.array(z.string()).exactOptional(),
+    blob: z.array(ObjectBlobNodeSchema).check(z.minLength(1)),
+  })
+  .check((ctx) => {
+    // rows/columns are table-grid dimensions; a textBox has no grid to
+    // describe. Named fields only (kind, rows, columns) — this must never
+    // scan for or react to other fields (vanishCharStyleIds included), so
+    // future additive fields stay structurally untouched by this rule.
+    const { kind, rows, columns } = ctx.value;
+    if (kind !== 'textBox') return;
+    const offendingKeys: string[] = [];
+    if (rows !== undefined) offendingKeys.push('rows');
+    if (columns !== undefined) offendingKeys.push('columns');
+    if (offendingKeys.length === 0) return;
+    ctx.issues.push({
+      code: 'custom',
+      input: ctx.value,
+      message: `textBox objects have no grid — ${offendingKeys.join(', ')} must not be set`,
+    });
+  });
 
 export type ObjectKind = z.infer<typeof ObjectKindSchema>;
 export type ObjectGeneration = z.infer<typeof ObjectGenerationSchema>;

From 86ec991ec01b1bef57bc7e3085f88f6e9082adc6 Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 14:55:38 -0700
Subject: [PATCH 09/17] feat(ast): couple SpecNodeSchema type to meta.object
 presence
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

'object' nodes require meta.object and no other node type may carry
one — presence-only, scoped exactly to that coupling so classify.ts
still owns deriving editability alongside it (#650 Part B).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/ast/object-schemas.test.ts | 50 ++++++++++++++++++++++++++++++++++
 src/ast/spec-tree-schemas.ts   | 36 +++++++++++++++++++-----
 2 files changed, 79 insertions(+), 7 deletions(-)

diff --git a/src/ast/object-schemas.test.ts b/src/ast/object-schemas.test.ts
index 4444d9a0..5608b7a3 100644
--- a/src/ast/object-schemas.test.ts
+++ b/src/ast/object-schemas.test.ts
@@ -293,3 +293,53 @@ describe('SpecNodeSchema — editability fixation for object/objectText (#300)',
     expect(SpecNodeSchema.safeParse(malformed).success).toBe(false);
   });
 });
+
+// ── type<->meta.object presence coupling (#650 Part B) ─────────────────────
+// An 'object' node is meaningless without its captured blob, and a non-object
+// node must never carry one (a leftover/misattached meta.object would silently
+// smuggle a captured OOXML blob onto a node no renderer expects it on). Scoped
+// strictly to presence — this must never re-derive or assert editability
+// (classify.ts already owns producing that pairing).
+describe('SpecNodeSchema — type<->meta.object presence coupling (#650)', () => {
+  const validObject = {
+    kind: 'table' as const,
+    floating: false,
+    generation: 'drawingml' as const,
+    rows: 1,
+    columns: 1,
+    blob: TABLE_BLOB,
+  };
+
+  it('rejects type=object with no meta.object', () => {
+    const node = {
+      id: VALID_UUID,
+      type: 'object',
+      text: 'Table (1x1)',
+      children: [],
+      meta: {},
+    };
+    expect(SpecNodeSchema.safeParse(node).success).toBe(false);
+  });
+
+  it('rejects a non-object type carrying a meta.object', () => {
+    const node = {
+      id: VALID_UUID,
+      type: 'article',
+      text: 'REFERENCES',
+      children: [],
+      meta: { object: validObject },
+    };
+    expect(SpecNodeSchema.safeParse(node).success).toBe(false);
+  });
+
+  it('accepts type=object with meta.object present (control)', () => {
+    const node = {
+      id: VALID_UUID,
+      type: 'object',
+      text: 'Table (1x1)',
+      children: [],
+      meta: { object: validObject },
+    };
+    expect(SpecNodeSchema.safeParse(node).success).toBe(true);
+  });
+});
diff --git a/src/ast/spec-tree-schemas.ts b/src/ast/spec-tree-schemas.ts
index 8a7130e2..8052af42 100644
--- a/src/ast/spec-tree-schemas.ts
+++ b/src/ast/spec-tree-schemas.ts
@@ -273,13 +273,35 @@ export const SpecNodeMetaSchema = z.object({
 });
 
 export const SpecNodeSchema: z.ZodType<SpecNode> = z.lazy(() =>
-  z.object({
-    id: z.uuid(),
-    type: NodeTypeSchema,
-    text: z.string().check(z.minLength(1)),
-    children: z.array(SpecNodeSchema),
-    meta: SpecNodeMetaSchema,
-  })
+  z
+    .object({
+      id: z.uuid(),
+      type: NodeTypeSchema,
+      text: z.string().check(z.minLength(1)),
+      children: z.array(SpecNodeSchema),
+      meta: SpecNodeMetaSchema,
+    })
+    .check((ctx) => {
+      // type<->meta.object presence coupling (#650 Part B): an 'object' node
+      // is meaningless without its captured blob, and no other node type may
+      // carry one. Presence only — never re-derives editability, which
+      // classify.ts already owns producing alongside this pairing.
+      const { type, meta } = ctx.value;
+      const hasObject = meta.object !== undefined;
+      if (type === 'object' && !hasObject) {
+        ctx.issues.push({
+          code: 'custom',
+          input: ctx.value,
+          message: "an 'object' node requires meta.object",
+        });
+      } else if (type !== 'object' && hasObject) {
+        ctx.issues.push({
+          code: 'custom',
+          input: ctx.value,
+          message: `meta.object must only be set on an 'object' node, not '${type}'`,
+        });
+      }
+    })
 );
 
 export const SecRefSchema = z.discriminatedUnion('targetType', [

From f511efab6f138159fe70c70e869cb3927906c455 Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 15:00:46 -0700
Subject: [PATCH 10/17] test(ast): audit .shape spread consumers of
 ObjectMetaSchema/SpecNodeSchema (#650)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Repo-wide grep found zero consumers spreading either schema's `.shape`
anywhere in src/ — neither is ever an MCP tool inputSchema (or nested
inside one); both are consumed exclusively via `.parse()`/`.safeParse()`
on the full schema instance (db/queries/object-meta.ts, revision-
snapshot.ts, revision-diff.ts, history-diff.ts). Non-applicability, not
enforcement, mirroring contract-schema-sharing-map.ts's Item 5 gate but
for these two schemas.

Adds a CI-enforced regression guard instead of leaving the finding as a
point-in-time PR-body note: a repo-wide static scan asserting no file
spreads ObjectMetaSchema.shape/SpecNodeSchema.shape, plus a direct check
that src/mcp/tools.ts never references either schema. Verified RED by
temporarily injecting an offending spread and confirming the test
catches it before reverting.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/ast/object-schemas.test.ts | 55 ++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/src/ast/object-schemas.test.ts b/src/ast/object-schemas.test.ts
index 5608b7a3..1a8c9a81 100644
--- a/src/ast/object-schemas.test.ts
+++ b/src/ast/object-schemas.test.ts
@@ -1,4 +1,7 @@
 import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
 import {
   ObjectKindSchema,
   ObjectGenerationSchema,
@@ -343,3 +346,55 @@ describe('SpecNodeSchema — type<->meta.object presence coupling (#650)', () =>
     expect(SpecNodeSchema.safeParse(node).success).toBe(true);
   });
 });
+
+// ── .shape spread audit (#650 Task 9/10) ────────────────────────────────────
+// contract-schema-sharing-map.ts's Item 5 gate exists because a `{
+// ...Schema.shape }` rebuild silently drops a schema's own object-level
+// `.check()`/`.strict()` rule when an MCP tool's inputSchema is built by
+// spreading a REST body schema (isFullSchemaInstance, tool-schema-
+// introspect.ts). ObjectMetaSchema gained the kind/rows/columns cross-field
+// check and SpecNodeSchema gained the type<->meta.object presence check in
+// this issue, so both need the same audit that map runs for every REST body
+// schema with an object-level rule: does anything spread `.shape` off them
+// and lose the rule?
+//
+// The answer here is non-applicability, not enforcement: neither schema is
+// ever an MCP tool's inputSchema (or nested inside one) — src/mcp/tools.ts
+// and every src/mcp/*-handlers.ts file were grepped for both schema names and
+// found clean. Both schemas are consumed exclusively via `.parse()`/
+// `.safeParse()` on the full schema instance — db/queries/object-meta.ts
+// (parseObjectMeta/updateObjectData), revision-snapshot.ts, revision-diff.ts,
+// history-diff.ts — which is why their cross-field checks already run intact
+// wherever these schemas are actually used today (see the DB-boundary
+// rejection tests in object-meta.test.ts). This test makes that a durable,
+// CI-enforced fact instead of a point-in-time grep result recorded only in a
+// PR body: a future PR that spreads either schema's `.shape` into a hand-
+// built object (MCP tool or otherwise) fails it immediately.
+describe('ObjectMetaSchema / SpecNodeSchema — .shape spread audit (#650)', () => {
+  const srcRoot = fileURLToPath(new URL('..', import.meta.url));
+  const selfFile = fileURLToPath(import.meta.url);
+
+  function tsFilesUnder(root: string): string[] {
+    return readdirSync(root, { recursive: true })
+      .filter((entry): entry is string => typeof entry === 'string' && entry.endsWith('.ts'))
+      .map((entry) => path.join(root, entry));
+  }
+
+  it('no file under src/ spreads ObjectMetaSchema.shape or SpecNodeSchema.shape', () => {
+    const offenders = tsFilesUnder(srcRoot)
+      .filter((file) => file !== selfFile)
+      .flatMap((file) => {
+        const text = readFileSync(file, 'utf8');
+        const hits: string[] = [];
+        if (/ObjectMetaSchema\.shape/.test(text)) hits.push(`${file}: ObjectMetaSchema.shape`);
+        if (/SpecNodeSchema\.shape/.test(text)) hits.push(`${file}: SpecNodeSchema.shape`);
+        return hits;
+      });
+    expect(offenders).toEqual([]);
+  });
+
+  it('the MCP tool surface (src/mcp/tools.ts) never references either schema — no tool input can lose their checks', () => {
+    const toolsSource = readFileSync(path.join(srcRoot, 'mcp', 'tools.ts'), 'utf8');
+    expect(toolsSource).not.toMatch(/ObjectMetaSchema|SpecNodeSchema/);
+  });
+});

From f5317a9f48affc55b7e96bba1fe7b7d0ac6fe47d Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 15:41:14 -0700
Subject: [PATCH 11/17] fix(generator): namespace vanish character-style ids
 per source tree (#650)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

generateManual unioned every SpecTree's captured vanishCharStyleIds into
ONE shared w:styles character-style block. Two different source documents
combined into one manual that happen to define their own character style
under the same raw id — one genuinely vanish, the other used only for
unrelated formatting on visible text — collided: the vanish stub for the
shared id silently overwrote the other tree's definition, which would
hide that tree's previously-visible text on reopen.

object-vanish-namespace.ts gives every source tree its own private
namespace for the vanish ids its own captured objects reference (and
rewrites the matching w:rStyle references in that tree's own object
blobs), so two documents can never let one tree's vanish stub capture
another tree's unrelated same-named style. A no-op for the common case
of a single-section manual or no vanish ids anywhere.

Also strengthens two review-flagged test gaps:
- body-objects.test.ts's "capture and rewrite share one predicate" test
  called hasRunVanish twice with identical literal arguments, which can
  never fail for a deterministic pure function. Replaced with an
  end-to-end test that derives vanishCharStyleIds from a real
  extractBodyObjects capture and feeds that exact value into
  replaceAnchoredParagraphText on the same blob, using a hidden-run-first
  paragraph ordering where a predicate drift is actually observable.
- body-object-attach.test.ts never exercised toObjectMeta's
  vanishCharStyleIds sort with 2+ ids, so a regression dropping the sort
  (Set-insertion order rather than deterministic) would go undetected by
  the fixture-snapshot corpus-determinism invariant it exists to serve.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../generate-manual-vanish-scope.test.ts      | 196 ++++++++++++++
 src/generator/index.ts                        |  20 +-
 src/generator/object-vanish-namespace.test.ts | 194 ++++++++++++++
 src/generator/object-vanish-namespace.ts      | 247 ++++++++++++++++++
 src/parser/docx/body-object-attach.test.ts    |  33 +++
 src/parser/docx/body-objects.test.ts          |  74 +++++-
 6 files changed, 754 insertions(+), 10 deletions(-)
 create mode 100644 src/generator/generate-manual-vanish-scope.test.ts
 create mode 100644 src/generator/object-vanish-namespace.test.ts
 create mode 100644 src/generator/object-vanish-namespace.ts

diff --git a/src/generator/generate-manual-vanish-scope.test.ts b/src/generator/generate-manual-vanish-scope.test.ts
new file mode 100644
index 00000000..9cc4aa0e
--- /dev/null
+++ b/src/generator/generate-manual-vanish-scope.test.ts
@@ -0,0 +1,196 @@
+// End-to-end regression for the #650 review finding (HIGH): generateManual
+// previously unioned every SpecTree's captured `vanishCharStyleIds` into ONE
+// shared `w:styles` character-style block (object-vanish-styles.ts's
+// collectVanishCharacterStyleIds + vanishStylesOptions). Two DIFFERENT
+// source documents combined into one manual that happen to define their OWN
+// character style under the SAME raw id — one genuinely vanish, the other
+// used for unrelated formatting on visible text — collided: the vanish
+// stub for that shared id silently overwrote the OTHER tree's definition,
+// which would hide that tree's previously-visible text on re-open. No test
+// anywhere in the codebase exercised generateManual's multi-tree path with
+// real captured vanish objects (object-vanish-styles.test.ts and
+// body-object-round-trip.test.ts only exercise generateDocx's single-tree
+// path) — this file closes that gap directly against the real DOCX bytes.
+import { describe, it, expect } from 'vitest';
+import JSZip from 'jszip';
+import { generateManual } from './index.js';
+import type { ManualMeta } from './front-matter.js';
+import type { ObjectBlobNode, SpecNode, SpecTree } from '../ast/index.js';
+
+const META: ManualMeta = { name: 'Acme Portfolio', description: 'Two-section test manual' };
+
+// Computed `['w:rStyle']` key (rather than a literal `'w:rStyle':` property)
+// mirrors body-objects.test.ts's own established `attrNode` helper — the
+// workaround for a TS limitation where a hand-assembled object literal can't
+// satisfy ObjectBlobNode's index signature + intersected `:@` key at once
+// when the tag is a literal property name.
+function rStyleNode(styleId: string): ObjectBlobNode {
+  const tag: string = 'w:rStyle';
+  return { [tag]: [], ':@': { '@_w:val': styleId } } as ObjectBlobNode;
+}
+
+// A `w:tbl > ... > w:r` blob whose single run's `w:rPr > w:rStyle` names
+// `styleId` and carries `text` — the shape a real capture persists.
+function tableBlobWithRStyle(styleId: string, text: string): ObjectBlobNode[] {
+  return [
+    {
+      'w:tbl': [
+        {
+          'w:tr': [
+            {
+              'w:tc': [
+                {
+                  'w:p': [
+                    {
+                      'w:r': [{ 'w:rPr': [rStyleNode(styleId)] }, { 'w:t': [{ '#text': text }] }],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ];
+}
+
+function objectNode(
+  id: string,
+  styleId: string,
+  text: string,
+  vanishCharStyleIds?: readonly string[]
+): SpecNode {
+  return {
+    id,
+    type: 'object',
+    text: '',
+    meta: {
+      object: {
+        kind: 'table',
+        floating: false,
+        generation: 'drawingml',
+        blob: tableBlobWithRStyle(styleId, text),
+        ...(vanishCharStyleIds !== undefined
+          ? { vanishCharStyleIds: [...vanishCharStyleIds] }
+          : {}),
+      },
+    },
+    children: [],
+  };
+}
+
+function treeWithObject(
+  treeId: string,
+  section: string,
+  objectId: string,
+  obj: SpecNode
+): SpecTree {
+  return {
+    id: treeId,
+    section,
+    title: 'Test Section',
+    parts: [
+      {
+        id: `${objectId}-part`,
+        type: 'part',
+        text: 'GENERAL',
+        meta: {},
+        children: [obj],
+      },
+    ],
+  };
+}
+
+async function getDocXml(buffer: Buffer): Promise<string> {
+  const zip = await JSZip.loadAsync(buffer);
+  const file = zip.file('word/document.xml');
+  if (!file) throw new Error('word/document.xml not found in generated DOCX');
+  return file.async('string');
+}
+
+async function getStylesXml(buffer: Buffer): Promise<string | undefined> {
+  const zip = await JSZip.loadAsync(buffer);
+  const file = zip.file('word/styles.xml');
+  return file ? file.async('string') : undefined;
+}
+
+describe('generateManual — vanish-character-style cross-tree isolation (#650 review finding)', () => {
+  it('does not let one tree’s vanish stub for a raw style id capture another tree’s unrelated same-named style', async () => {
+    // Tree A: an object genuinely hidden via a w:rStyle-referenced vanish
+    // character style named "Hidden1" — mirrors body-object-round-trip.test.ts's
+    // real "#650" capture fixture.
+    const treeA = treeWithObject(
+      'tree-a',
+      '03 30 00',
+      'obj-a',
+      objectNode('obj-a', 'Hidden1', 'Secret from document A', ['Hidden1'])
+    );
+    // Tree B: an UNRELATED source document whose own object references a
+    // character style it ALSO happens to call "Hidden1" — but in tree B's
+    // own source, that style was never vanish (its captured
+    // vanishCharStyleIds is empty/absent), e.g. a bold/underline-only style.
+    const treeB = treeWithObject(
+      'tree-b',
+      '09 91 00',
+      'obj-b',
+      objectNode('obj-b', 'Hidden1', 'Visible text from document B')
+    );
+
+    const buffer = await generateManual([treeA, treeB], META);
+    const documentXml = await getDocXml(buffer);
+    const stylesXml = await getStylesXml(buffer);
+
+    // Tree B's own reference to the raw id "Hidden1" must survive UNTOUCHED
+    // — it must never be redirected onto tree A's vanish-stub id, or tree
+    // B's visible text would render hidden when the document is opened.
+    expect(documentXml).toContain('<w:rStyle w:val="Hidden1"/>');
+    expect(documentXml).toContain('Visible text from document B');
+    // The BLOB itself is always re-emitted verbatim regardless of vanish
+    // (ADR-072 decision 1 — Word hides it via the style, SpecR never
+    // reinterprets or drops the underlying content), so tree A's text is
+    // still present in the XML — but its w:rStyle reference must have moved
+    // to a tree-scoped id, the exact rewrite that prevents the collision.
+    expect(documentXml).toContain('Secret from document A');
+    const namespacedIdMatch = /w:rStyle w:val="(Hidden1#specr-vanish-t\d+)"/.exec(documentXml);
+    expect(namespacedIdMatch).not.toBeNull();
+
+    // The emitted styles.xml must NOT define the raw "Hidden1" id as vanish
+    // — that would be exactly the corruption this fix prevents, since
+    // "Hidden1" is the id tree B's own (non-vanish) reference still uses.
+    expect(stylesXml).toBeDefined();
+    expect(stylesXml).not.toContain('w:styleId="Hidden1"');
+    // It DOES define tree A's namespaced id as vanish, preserving the
+    // original privacy behavior for tree A's own object.
+    const namespacedId = namespacedIdMatch?.[1];
+    expect(namespacedId).toBeDefined();
+    expect(stylesXml).toContain(`w:styleId="${namespacedId}"`);
+  });
+
+  it('never namespaces or synthesizes a vanish character style when no tree carries any vanish ids (byte-identical common case)', async () => {
+    const treeA = treeWithObject(
+      'tree-a',
+      '03 30 00',
+      'obj-a',
+      objectNode('obj-a', 'Bold1', 'A text')
+    );
+    const treeB = treeWithObject(
+      'tree-b',
+      '09 91 00',
+      'obj-b',
+      objectNode('obj-b', 'Bold1', 'B text')
+    );
+
+    const buffer = await generateManual([treeA, treeB], META);
+    const documentXml = await getDocXml(buffer);
+    const stylesXml = await getStylesXml(buffer);
+
+    // Docx-package Documents always carry a default styles.xml (heading /
+    // paragraph styles), independent of this fix — what must NOT happen is
+    // "Bold1" being renamed or a vanish stub being synthesized for it, since
+    // neither tree ever marked it vanish.
+    expect(documentXml).toContain('<w:rStyle w:val="Bold1"/>');
+    expect(stylesXml).not.toContain('w:styleId="Bold1"');
+    expect(stylesXml).not.toContain('specr-vanish');
+  });
+});
diff --git a/src/generator/index.ts b/src/generator/index.ts
index 4e06c996..f36a66ac 100644
--- a/src/generator/index.ts
+++ b/src/generator/index.ts
@@ -27,6 +27,7 @@ import {
   collectVanishCharacterStyleIds,
   vanishCharacterStyleOptions,
 } from './object-vanish-styles.js';
+import { namespaceVanishTrees } from './object-vanish-namespace.js';
 import type { IStylesOptions } from 'docx';
 
 export { generateSec } from './sec/index.js';
@@ -348,10 +349,17 @@ export async function generateManual(
     throw new GeneratorError('cannot generate a manual with no sections');
   }
   try {
+    // #650 review: give every source tree its own private namespace for the
+    // vanish-character-style ids its own captured objects reference, so two
+    // different source documents combined into this manual can never let one
+    // tree's vanish stub overwrite another tree's unrelated same-named style
+    // (see object-vanish-namespace.ts). A no-op for the common case of no
+    // vanish ids anywhere, or a single-section manual.
+    const scopedTrees = namespaceVanishTrees(trees);
     const rules = styleRules !== undefined ? buildRuleMap(styleRules) : undefined;
     const format = options?.sectionNumberFormat ?? 'canonical';
     const frontMatter = buildFrontMatter(meta, styleRules);
-    const sections = trees.map((tree, i) => {
+    const sections = scopedTrees.map((tree, i) => {
       const reference = `${SPEC_NUM_REF}-${i}`;
       const render = renderOptionalHeaderFooter(tree, format, options);
       return {
@@ -361,14 +369,16 @@ export async function generateManual(
       };
     });
     const firstRender =
-      trees[0] !== undefined ? renderOptionalHeaderFooter(trees[0], format, options) : undefined;
+      scopedTrees[0] !== undefined
+        ? renderOptionalHeaderFooter(scopedTrees[0], format, options)
+        : undefined;
     // Front matter has no source SpecTree of its own — its page size (#509)
-    // resolves from `trees[0]`, deliberately not `firstRender` (a
+    // resolves from `scopedTrees[0]`, deliberately not `firstRender` (a
     // header/footer render, unrelated to page dimensions).
-    const frontMatterPageSize = resolvePageSize(trees[0]?.pageSize);
+    const frontMatterPageSize = resolvePageSize(scopedTrees[0]?.pageSize);
     const doc = new Document({
       ...documentLevelOptions(firstRender),
-      ...vanishStylesOptions(trees),
+      ...vanishStylesOptions(scopedTrees),
       numbering: { config: sections.map((s) => buildSpecNumberingConfig(rules, s.reference)) },
       sections: [
         {
diff --git a/src/generator/object-vanish-namespace.test.ts b/src/generator/object-vanish-namespace.test.ts
new file mode 100644
index 00000000..9f4c07a7
--- /dev/null
+++ b/src/generator/object-vanish-namespace.test.ts
@@ -0,0 +1,194 @@
+import { describe, it, expect } from 'vitest';
+import { namespaceVanishTrees } from './object-vanish-namespace.js';
+import type { ObjectBlobNode, SpecNode, SpecTree } from '../ast/index.js';
+
+// Minimal SpecNode/SpecTree builders — mirrors object-vanish-styles.test.ts's
+// own local convention: this module only ever reads/rewrites
+// `type`/`children`/`meta.object`, so every other field is an arbitrary
+// valid placeholder.
+function node(overrides: Partial<SpecNode> & Pick<SpecNode, 'type'>): SpecNode {
+  return { id: 'n', text: '', children: [], meta: {}, ...overrides };
+}
+
+// Computed `['w:rStyle']` key (rather than a literal `'w:rStyle':` property)
+// mirrors body-objects.test.ts's own established `attrNode` helper — the
+// workaround for a TS limitation where a hand-assembled object literal can't
+// satisfy ObjectBlobNode's index signature + intersected `:@` key at once
+// when the tag is a literal property name.
+function rStyleNode(styleId: string): ObjectBlobNode {
+  const tag: string = 'w:rStyle';
+  return { [tag]: [], ':@': { '@_w:val': styleId } } as ObjectBlobNode;
+}
+
+// A `w:tbl > ... > w:r` blob whose single run's `w:rPr > w:rStyle` names
+// `styleId` — the exact shape `hasRunVanish`/generation consume — plus a
+// text leaf so the object is non-empty capture data.
+function tableBlobWithRStyle(styleId: string, text: string): ObjectBlobNode[] {
+  return [
+    {
+      'w:tbl': [
+        {
+          'w:tr': [
+            {
+              'w:tc': [
+                {
+                  'w:p': [
+                    {
+                      'w:r': [{ 'w:rPr': [rStyleNode(styleId)] }, { 'w:t': [{ '#text': text }] }],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ];
+}
+
+function objectNode(
+  styleId: string,
+  text: string,
+  vanishCharStyleIds?: readonly string[]
+): SpecNode {
+  return node({
+    type: 'object',
+    meta: {
+      object: {
+        kind: 'table',
+        floating: false,
+        generation: 'drawingml',
+        blob: tableBlobWithRStyle(styleId, text),
+        ...(vanishCharStyleIds !== undefined
+          ? { vanishCharStyleIds: [...vanishCharStyleIds] }
+          : {}),
+      },
+    },
+  });
+}
+
+function tree(id: string, parts: readonly SpecNode[]): SpecTree {
+  return { id, section: '00 00 00', title: 'Test', parts };
+}
+
+function rStyleVal(node1: ObjectBlobNode): string | undefined {
+  const attrs = node1[':@'];
+  return typeof attrs?.['@_w:val'] === 'string' ? attrs['@_w:val'] : undefined;
+}
+
+// Walks a captured blob's arbitrary node shape to find the (sole) w:rStyle
+// node's own `@_w:val` — deliberately structure-agnostic (rather than a
+// fixed-depth dig matching tableBlobWithRStyle exactly) so it stays correct
+// if that fixture's own nesting ever changes shape.
+function rStyleValOf(blob: readonly ObjectBlobNode[]): string | undefined {
+  for (const child of blob) {
+    const tag = Object.keys(child).find((key) => key !== ':@');
+    if (!tag) continue;
+    if (tag === 'w:rStyle') return rStyleVal(child);
+    const value = child[tag];
+    if (Array.isArray(value)) {
+      const found = rStyleValOf(value);
+      if (found !== undefined) return found;
+    }
+  }
+  return undefined;
+}
+
+describe('namespaceVanishTrees', () => {
+  it('returns the same array reference for zero trees', () => {
+    const trees: SpecTree[] = [];
+    expect(namespaceVanishTrees(trees)).toBe(trees);
+  });
+
+  it('returns the same array reference for a single tree, even with vanish ids', () => {
+    const trees = [tree('t0', [objectNode('Hidden1', 'secret', ['Hidden1'])])];
+    expect(namespaceVanishTrees(trees)).toBe(trees);
+  });
+
+  it('returns the same array reference when no tree in a multi-tree manual has any vanish ids', () => {
+    const trees = [tree('t0', [node({ type: 'article' })]), tree('t1', [objectNode('X', 'y')])];
+    expect(namespaceVanishTrees(trees)).toBe(trees);
+  });
+
+  it('leaves an individual tree untouched (by reference) when it has no vanish ids, even alongside a sibling that does', () => {
+    const untouched = tree('t0', [objectNode('X', 'y')]);
+    const withVanish = tree('t1', [objectNode('Hidden1', 'secret', ['Hidden1'])]);
+    const result = namespaceVanishTrees([untouched, withVanish]);
+    expect(result[0]).toBe(untouched);
+    expect(result[1]).not.toBe(withVanish);
+  });
+
+  it('namespaces two trees that independently vanish DIFFERENT ids, one per tree', () => {
+    const treeA = tree('a', [objectNode('Alpha', 'a-text', ['Alpha'])]);
+    const treeB = tree('b', [objectNode('Beta', 'b-text', ['Beta'])]);
+    const [resultA, resultB] = namespaceVanishTrees([treeA, treeB]);
+
+    const objA = resultA?.parts[0];
+    const objB = resultB?.parts[0];
+    expect(objA?.meta.object?.vanishCharStyleIds).toEqual(['Alpha#specr-vanish-t0']);
+    expect(objB?.meta.object?.vanishCharStyleIds).toEqual(['Beta#specr-vanish-t1']);
+  });
+
+  // The crux #650 review scenario: two DIFFERENT source documents that
+  // happen to use the exact SAME raw character-style id string for
+  // completely different purposes. Each tree's own copy of that id must end
+  // up in its OWN private namespace — never sharing one id across trees,
+  // which is what let one tree's vanish stub silently overwrite the other's
+  // unrelated definition.
+  it('gives colliding raw ids across two trees distinct, non-overlapping namespaced ids', () => {
+    const treeA = tree('a', [objectNode('Hidden1', 'a-secret', ['Hidden1'])]);
+    const treeB = tree('b', [objectNode('Hidden1', 'b-secret', ['Hidden1'])]);
+    const [resultA, resultB] = namespaceVanishTrees([treeA, treeB]);
+
+    const idsA = resultA?.parts[0]?.meta.object?.vanishCharStyleIds;
+    const idsB = resultB?.parts[0]?.meta.object?.vanishCharStyleIds;
+    expect(idsA).toEqual(['Hidden1#specr-vanish-t0']);
+    expect(idsB).toEqual(['Hidden1#specr-vanish-t1']);
+    expect(idsA?.[0]).not.toEqual(idsB?.[0]);
+  });
+
+  it('rewrites the blob’s own w:rStyle reference to match the renamed id', () => {
+    const trees = [
+      tree('a', [objectNode('X', 'y')]),
+      tree('b', [objectNode('Hidden1', 'secret', ['Hidden1'])]),
+    ];
+    const [, resultB] = namespaceVanishTrees(trees);
+    const blob = resultB?.parts[0]?.meta.object?.blob ?? [];
+    expect(rStyleValOf(blob)).toBe('Hidden1#specr-vanish-t1');
+  });
+
+  it('does NOT rewrite a w:rStyle id that is referenced but not in this tree’s own vanishCharStyleIds', () => {
+    // treeA's object references "Shared" purely for formatting — not vanish
+    // in treeA at all (its own vanishCharStyleIds is undefined). treeB
+    // separately vanishes "Shared". treeA's own reference must stay
+    // untouched: it was never this tree's vanish id to rename.
+    const treeA = tree('a', [objectNode('Shared', 'bold-but-visible')]);
+    const treeB = tree('b', [objectNode('Shared', 'secret', ['Shared'])]);
+    const [resultA, resultB] = namespaceVanishTrees([treeA, treeB]);
+
+    const blobA = resultA?.parts[0]?.meta.object?.blob ?? [];
+    const blobB = resultB?.parts[0]?.meta.object?.blob ?? [];
+    expect(rStyleValOf(blobA)).toBe('Shared');
+    expect(rStyleValOf(blobB)).toBe('Shared#specr-vanish-t1');
+  });
+
+  it('finds and namespaces an object node nested arbitrarily deep under non-object ancestors', () => {
+    const deep = node({
+      type: 'article',
+      children: [objectNode('Deep', 'secret', ['Deep'])],
+    });
+    const trees = [tree('a', [objectNode('X', 'y')]), tree('b', [deep])];
+    const [, resultB] = namespaceVanishTrees(trees);
+    const nested = resultB?.parts[0]?.children[0];
+    expect(nested?.meta.object?.vanishCharStyleIds).toEqual(['Deep#specr-vanish-t1']);
+  });
+
+  it('preserves node identity for siblings untouched by the rewrite', () => {
+    const unrelatedSibling = node({ type: 'article', text: 'untouched' });
+    const treeA = tree('a', [unrelatedSibling, objectNode('Hidden1', 'secret', ['Hidden1'])]);
+    const treeB = tree('b', [objectNode('Hidden1', 'secret', ['Hidden1'])]);
+    const [resultA] = namespaceVanishTrees([treeA, treeB]);
+    expect(resultA?.parts[0]).toBe(unrelatedSibling);
+  });
+});
diff --git a/src/generator/object-vanish-namespace.ts b/src/generator/object-vanish-namespace.ts
new file mode 100644
index 00000000..4c4d4a8b
--- /dev/null
+++ b/src/generator/object-vanish-namespace.ts
@@ -0,0 +1,247 @@
+// Cross-document vanish-character-style collision guard for `generateManual`
+// (#650 review finding, HIGH severity): `object-vanish-styles.ts`'s
+// `collectVanishCharacterStyleIds` unions every captured object's
+// `vanishCharStyleIds` across ALL `SpecTree`s passed to `generateManual`, and
+// `vanishStylesOptions` writes ONE shared `w:styles` character-style block
+// for the whole merged manual. Two DIFFERENT source documents combined into
+// one manual can each define their OWN character style under the SAME id —
+// one genuinely vanish (an internal note style), the other used only for
+// bold/underline formatting on visible text. Sharing one `styles.xml`
+// namespace lets one tree's vanish stub silently overwrite another tree's
+// unrelated definition of that id, hiding text the other tree's own capture
+// correctly resolved as visible.
+//
+// The fix: give every SOURCE TREE its own private namespace for the
+// character-style ids its OWN captured objects resolved vanish.
+// `ObjectMeta.vanishCharStyleIds` is already the FULL resolved set from THAT
+// tree's OWN `styles.xml` (`body-object-attach.ts`'s `toObjectMeta`), so
+// within one tree every reference to a given id is unambiguous — renaming
+// it, and every `w:rStyle` in that tree's own object blobs that names it, to
+// a tree-scoped id removes any possibility of a DIFFERENT tree's unrelated
+// same-named style being redefined out from under it. `generateDocx` (always
+// exactly one tree) is unaffected: there is only ever one namespace there, so
+// no rename is needed.
+//
+// Deliberately UNCONDITIONAL — every tree with any vanish ids gets
+// namespaced, not only when an actual same-named collision with a sibling
+// tree would occur. Detecting a real collision would require also scanning
+// every OTHER tree's blobs for a non-vanish reference to the same id, a much
+// larger walk for a case a cheap unconditional rename makes moot anyway: the
+// renamed id is never read back by SpecR (`object-vanish-styles.ts`'s own
+// module comment — `name` is shown to a human, never a correlation key), so
+// there is no cost to always giving each tree its own namespace.
+import {
+  type ObjectBlobNode,
+  type ObjectMeta,
+  type SpecNode,
+  type SpecTree,
+} from '../ast/index.js';
+import { collectVanishCharacterStyleIds } from './object-vanish-styles.js';
+
+// A distinctive, deterministic separator no real captured Word style id
+// could plausibly already contain — SpecR mints this, a source .docx never
+// does — so a namespaced id can never accidentally collide with either an
+// original id or another tree's namespaced id.
+const NAMESPACE_SEPARATOR = '#specr-vanish-t';
+
+function namespacedId(id: string, treeIndex: number): string {
+  return `${id}${NAMESPACE_SEPARATOR}${treeIndex}`;
+}
+
+// ─── ObjectBlobNode navigation (preserveOrder-mode; self-contained per the
+// established per-module-helper pattern — see object-block.ts and
+// parser/docx/object-blob-edit.ts's own tagOf/childrenOf/withChildren.
+// Duplicated here rather than shared: module-boundary rules bar importing
+// parser/ from generator/, and this module's own copy stays well under its
+// file's line budget without a shared extraction.) ─────────────────────────
+
+function tagOf(node: ObjectBlobNode): string | undefined {
+  const tags = Object.keys(node).filter((key) => key !== ':@');
+  return tags.length === 1 ? tags[0] : undefined;
+}
+
+function isBlobNodeArray(value: unknown): value is readonly ObjectBlobNode[] {
+  return Array.isArray(value);
+}
+
+function childrenOf(node: ObjectBlobNode): readonly ObjectBlobNode[] {
+  const tag = tagOf(node);
+  if (!tag) return [];
+  const value = node[tag];
+  return isBlobNodeArray(value) ? value : [];
+}
+
+function withChildren(
+  node: ObjectBlobNode,
+  tag: string,
+  children: readonly ObjectBlobNode[]
+): ObjectBlobNode {
+  return withAttrs(tag, children, node[':@']);
+}
+
+// Builds a `{ [tag]: children, ':@': attrs }` node — the shared literal
+// shape `withChildren` and `renamedRStyleAttrs`'s caller both need, taking
+// `attrs` explicitly rather than always reading it off an existing node
+// (renaming needs to substitute a DIFFERENT attrs object than the source
+// node's own). `as ObjectBlobNode` mirrors object-blob-edit.ts's own
+// established narrowing: the index signature plus the separately-
+// intersected optional `:@` key can't both be checked against one hand-
+// assembled literal at once — using a COMPUTED `[tag]` key (never a literal
+// property name) is what keeps this assertion valid; see this module's own
+// test-fixture builders for the same requirement.
+function withAttrs(
+  tag: string,
+  children: readonly ObjectBlobNode[],
+  attrs: ObjectBlobNode[':@']
+): ObjectBlobNode {
+  return (
+    attrs !== undefined ? { [tag]: children, ':@': attrs } : { [tag]: children }
+  ) as ObjectBlobNode;
+}
+
+// fast-xml-parser's attribute-value parsing may coerce a numeric-looking
+// `w:val` to a JS number (mirrors object-block.ts's own toImportedAttributes
+// coercion note) — OOXML style ids are always textual, so this normalizes
+// either shape to the string `renames` is keyed by. Empty string (never a
+// real captured style id) signals "nothing to look up".
+function rStyleValKey(value: string | number | undefined): string {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number') return String(value);
+  return '';
+}
+
+// Renames a `w:rStyle` node's own `@_w:val` attribute when it names an id in
+// `renames`, leaving every other attribute and every other node untouched —
+// by reference, so a blob with nothing to rename comes back byte-identical.
+function renamedRStyleAttrs(
+  node: ObjectBlobNode,
+  renames: ReadonlyMap<string, string>
+): ObjectBlobNode[':@'] | undefined {
+  const attrs = node[':@'];
+  const key = rStyleValKey(attrs?.['@_w:val']);
+  const renamed = key !== '' ? renames.get(key) : undefined;
+  return attrs !== undefined && renamed !== undefined
+    ? { ...attrs, '@_w:val': renamed }
+    : undefined;
+}
+
+/**
+ * Immutably rewrites every `w:rStyle` reference in `node` naming an id in
+ * `renames` to that id's namespaced replacement. Every other node — no
+ * matching `w:rStyle` anywhere in its subtree — is returned BY REFERENCE,
+ * unchanged, so a tree with nothing to rename produces byte-identical output.
+ */
+function rewriteRStyleIds(
+  node: ObjectBlobNode,
+  renames: ReadonlyMap<string, string>
+): ObjectBlobNode {
+  const tag = tagOf(node);
+  if (!tag) return node;
+  if (tag === 'w:rStyle') {
+    const renamedAttrs = renamedRStyleAttrs(node, renames);
+    return renamedAttrs === undefined ? node : withAttrs(tag, [], renamedAttrs);
+  }
+  const children = childrenOf(node);
+  if (children.length === 0) return node;
+  let changed = false;
+  const newChildren = children.map((child) => {
+    const rewritten = rewriteRStyleIds(child, renames);
+    if (rewritten !== child) changed = true;
+    return rewritten;
+  });
+  return changed ? withChildren(node, tag, newChildren) : node;
+}
+
+function rewriteBlobRoots(
+  blob: readonly ObjectBlobNode[],
+  renames: ReadonlyMap<string, string>
+): readonly ObjectBlobNode[] {
+  let changed = false;
+  const result = blob.map((root) => {
+    const rewritten = rewriteRStyleIds(root, renames);
+    if (rewritten !== root) changed = true;
+    return rewritten;
+  });
+  return changed ? result : blob;
+}
+
+// Renames every id present in `ids` that also appears in `renames`, keeping
+// every other id verbatim; returns `ids` unchanged (by reference) when
+// nothing in it needed renaming, including when `ids` itself is undefined.
+function renamedIds(
+  ids: readonly string[] | undefined,
+  renames: ReadonlyMap<string, string>
+): readonly string[] | undefined {
+  if (ids === undefined) return undefined;
+  let changed = false;
+  const result = ids.map((id) => {
+    const renamed = renames.get(id);
+    if (renamed !== undefined) changed = true;
+    return renamed ?? id;
+  });
+  return changed ? result : ids;
+}
+
+function rewriteObjectMeta(object: ObjectMeta, renames: ReadonlyMap<string, string>): ObjectMeta {
+  const newBlob = rewriteBlobRoots(object.blob, renames);
+  const newIds = renamedIds(object.vanishCharStyleIds, renames);
+  if (newBlob === object.blob && newIds === object.vanishCharStyleIds) return object;
+  return {
+    ...object,
+    blob: newBlob as ObjectMeta['blob'],
+    ...(newIds !== undefined ? { vanishCharStyleIds: [...newIds] } : {}),
+  };
+}
+
+function rewriteNode(node: SpecNode, renames: ReadonlyMap<string, string>): SpecNode {
+  const newChildren = rewriteNodes(node.children, renames);
+  const currentObject = node.meta.object;
+  const newObject =
+    currentObject !== undefined ? rewriteObjectMeta(currentObject, renames) : undefined;
+  const objectChanged = newObject !== undefined && newObject !== currentObject;
+  if (newChildren === node.children && !objectChanged) return node;
+  return {
+    ...node,
+    children: newChildren,
+    meta: objectChanged ? { ...node.meta, object: newObject } : node.meta,
+  };
+}
+
+function rewriteNodes(
+  nodes: readonly SpecNode[],
+  renames: ReadonlyMap<string, string>
+): readonly SpecNode[] {
+  let changed = false;
+  const result = nodes.map((node) => {
+    const rewritten = rewriteNode(node, renames);
+    if (rewritten !== node) changed = true;
+    return rewritten;
+  });
+  return changed ? result : nodes;
+}
+
+/**
+ * Gives every `SpecTree` in `trees` its own private namespace for the
+ * vanish-character-style ids its OWN captured objects reference, so
+ * `generateManual` combining multiple source documents can never let one
+ * tree's vanish stub overwrite another tree's unrelated same-named style
+ * (see this module's header). A no-op — every tree returned BY REFERENCE,
+ * the whole array returned BY REFERENCE — when `trees.length <= 1` (no
+ * cross-tree collision is possible with a single source document) or when no
+ * tree carries any vanish ids at all, keeping `generateManual`'s output
+ * byte-identical to before this fix in the overwhelmingly common case.
+ */
+export function namespaceVanishTrees(trees: readonly SpecTree[]): readonly SpecTree[] {
+  if (trees.length <= 1) return trees;
+  let changed = false;
+  const result = trees.map((tree, index) => {
+    const ownIds = collectVanishCharacterStyleIds([tree]);
+    if (ownIds.length === 0) return tree;
+    const renames = new Map(ownIds.map((id) => [id, namespacedId(id, index)] as const));
+    const newParts = rewriteNodes(tree.parts, renames);
+    if (newParts === tree.parts) return tree;
+    changed = true;
+    return { ...tree, parts: newParts };
+  });
+  return changed ? result : trees;
+}
diff --git a/src/parser/docx/body-object-attach.test.ts b/src/parser/docx/body-object-attach.test.ts
index 75ae3666..134bfdd0 100644
--- a/src/parser/docx/body-object-attach.test.ts
+++ b/src/parser/docx/body-object-attach.test.ts
@@ -19,6 +19,21 @@ const EMPTY_STYLES: StyleMap = buildStyleMap(
   `<?xml version="1.0"?><w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"/>`
 );
 
+// Two vanish character styles, declared in styles.xml document order "Zeta"
+// THEN "HiddenChar" — the REVERSE of their sorted order. `characterStyleVanishIds`
+// (styles.ts) builds `StyleMap.vanishCharStyleIds` as a `Set` populated by
+// iterating `styles.keys()`, i.e. styles.xml document order — so an insertion-
+// order Set here would yield `['Zeta', 'HiddenChar']`. Feeding this through
+// `toObjectMeta`'s `.sort()` (body-object-attach.ts, #650) must recover the
+// deterministic `['HiddenChar', 'Zeta']` regardless.
+const TWO_VANISH_STYLES: StyleMap = buildStyleMap(
+  '<?xml version="1.0"?>' +
+    '<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">' +
+    '<w:style w:type="character" w:styleId="Zeta"><w:rPr><w:vanish/></w:rPr></w:style>' +
+    '<w:style w:type="character" w:styleId="HiddenChar"><w:rPr><w:vanish/></w:rPr></w:style>' +
+    '</w:styles>'
+);
+
 function makeDocXml(bodyXml: string): string {
   return (
     `<?xml version="1.0" encoding="UTF-8"?><w:document ${NS}>` +
@@ -123,6 +138,24 @@ describe('captureBodyObjectsForTree — object/objectText node shape', () => {
   });
 });
 
+// #650 review finding: toObjectMeta's `.sort((a,b) => a.localeCompare(b))`
+// on vanishCharStyleIds — added specifically for deterministic JSONB/fixture-
+// snapshot serialization — was never exercised by any test with 2+ ids,
+// so a regression dropping or breaking the sort would go undetected.
+describe('captureBodyObjectsForTree — vanishCharStyleIds is sorted, not insertion order (#650)', () => {
+  it('persists two vanish character-style ids sorted, even though styles.xml declares them in the REVERSE order', () => {
+    const body = table(row(cell(para('cell one'))));
+    const xml = makeDocXml(body);
+
+    const attachment = captureBodyObjectsForTree(xml, TWO_VANISH_STYLES);
+
+    const object = attachment.objectsBeforeFirst[0];
+    // TWO_VANISH_STYLES declares "Zeta" before "HiddenChar" — an unsorted
+    // Set-iteration-order array would come out ['Zeta', 'HiddenChar'].
+    expect(object?.meta.object?.vanishCharStyleIds).toEqual(['HiddenChar', 'Zeta']);
+  });
+});
+
 describe('captureBodyObjectsForTree — body-drawing-skipped warning aggregation', () => {
   it('emits one aggregate warning naming the dropped kind when a chart is out of scope', () => {
     const xml = makeDocXml(chartParagraph());
diff --git a/src/parser/docx/body-objects.test.ts b/src/parser/docx/body-objects.test.ts
index 3d63540b..a1636372 100644
--- a/src/parser/docx/body-objects.test.ts
+++ b/src/parser/docx/body-objects.test.ts
@@ -3,6 +3,7 @@ import { extractBodyObjects, anchorInteriorParagraphs, hasRunVanish } from './bo
 import { computeBodyOrder } from './body-order.js';
 import { createDocumentXmlParser, createOrderedDocumentXmlBuilder, toArray } from './xml-utils.js';
 import { buildStyleMap } from './styles.js';
+import { replaceAnchoredParagraphText } from './object-blob-edit.js';
 import { UUID_TAG_PREFIX } from '../../ast/index.js';
 import type { StyleMap } from './types.js';
 import type { BodyObjectExtractionResult } from './body-objects.js';
@@ -395,13 +396,76 @@ describe('hasRunVanish — rStyle-referenced character-style vanish (#650, captu
     expect(hasRunVanish(run)).toBe(false);
   });
 
-  it('capture and rewrite are decided by the exact same predicate — same input yields the same output on both call shapes', () => {
+  // #650 review (verified finding): the ORIGINAL version of this test called
+  // `hasRunVanish` twice with the exact same literal arguments and compared
+  // the two results — that can never fail for a deterministic pure function,
+  // so it never actually exercised either real call site. This replacement
+  // derives `vanishCharStyleIds` from a REAL `extractBodyObjects` capture and
+  // feeds that exact captured value into the REAL `replaceAnchoredParagraphText`
+  // rewrite path (object-blob-edit.ts) on the SAME source blob — the two
+  // production call sites `hasRunVanish`'s own doc comment says must share
+  // one predicate (ADR-092) — proving they actually agree end-to-end. See the
+  // "hidden-first paragraph" end-to-end test below.
+  it('hasRunVanish is a pure, deterministic predicate (same input, same output) — a necessary but not sufficient property; see the end-to-end test below for the real shared-object proof', () => {
     const node = blobRun([blobRStyle('HiddenChar')]);
     const vanishCharStyleIds = new Set(['HiddenChar']);
-    const captureResult = hasRunVanish(node, vanishCharStyleIds);
-    const rewriteResult = hasRunVanish(node, vanishCharStyleIds);
-    expect(captureResult).toBe(rewriteResult);
-    expect(captureResult).toBe(true);
+    expect(hasRunVanish(node, vanishCharStyleIds)).toBe(hasRunVanish(node, vanishCharStyleIds));
+  });
+
+  // A paragraph with the VANISH run FIRST in document order and the VISIBLE
+  // run second — the exact shape rewriteFirstText's own doc comment warns
+  // about ("an interior paragraph whose HIDDEN run precedes its visible one
+  // would take the edit into the hidden run and blank the visible one").
+  // With the visible run first (this file's other rStyleRunPara fixtures),
+  // a drifted rewrite predicate that failed to skip vanish runs would still
+  // accidentally land the edit in the right place, because the visible run
+  // is reached first regardless — this ordering is the one place capture and
+  // rewrite disagreeing would actually be OBSERVABLE.
+  function hiddenFirstRStyleRunPara(
+    styledText: string,
+    visibleText: string,
+    styleId: string
+  ): string {
+    return (
+      `<w:p><w:r><w:rPr><w:rStyle w:val="${styleId}"/></w:rPr><w:t>${styledText}</w:t></w:r>` +
+      `<w:r><w:t>${visibleText}</w:t></w:r></w:p>`
+    );
+  }
+
+  it('end-to-end: vanishCharStyleIds captured by extractBodyObjects, fed into replaceAnchoredParagraphText on the SAME blob, skips the SAME hidden run capture skipped', () => {
+    const styleMap = charVanishStyleMap('HiddenChar');
+    const cellPara = hiddenFirstRStyleRunPara('hidden style part', 'visible part', 'HiddenChar');
+    const result = extract(table(row(cell(cellPara))), styleMap);
+    expect(result.tableObjects).toHaveLength(1);
+
+    // Non-null assertions below are safe given the length assertion above —
+    // kept as plain property access (not `?.`/`??`) so this test's own
+    // complexity stays readable rather than accumulating optional-chaining
+    // branches unrelated to the invariant it pins.
+    const object = result.tableObjects[0]!.object;
+    // Capture side: the hidden run never reaches interiorTexts.
+    expect(object.interiorTexts.map((t) => t.text)).toEqual(['visible part']);
+    expect(object.interiorTexts).toHaveLength(1);
+    const uuid = object.interiorTexts[0]!.id;
+
+    // Rewrite side: feed the EXACT vanishCharStyleIds capture persisted —
+    // never a fresh literal Set built by this test — into the real
+    // production rewrite entry point, on the object's own captured blob.
+    const vanishCharStyleIds = new Set(object.vanishCharStyleIds);
+    const rewritten = replaceAnchoredParagraphText(
+      object.blob,
+      uuid,
+      'replaced visible part',
+      vanishCharStyleIds
+    );
+    expect(rewritten).toBeDefined();
+
+    const xml = createOrderedDocumentXmlBuilder().build(rewritten!);
+    // The rewrite reached past the hidden run — its original text is
+    // untouched, never blanked and never overwritten with the new text.
+    expect(xml).toContain('hidden style part');
+    // The edit landed in the visible run, which is what a caller asked for.
+    expect(xml).toContain('replaced visible part');
   });
 });
 

From ce1dfdc85333550645b4585c0a80c4d3ff4b5748 Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 15:53:20 -0700
Subject: [PATCH 12/17] test(parser): fix tautological hasRunVanish purity test
 (#650)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The "hasRunVanish is a pure, deterministic predicate" test called
hasRunVanish once and compared its return value against a second call
using the exact same node/Set references — a tautology that can never
fail for a deterministic function, so it never actually exercised the
implementation. Rewritten to call the predicate on two independently
constructed (but structurally identical) node instances, asserting
the concrete expected verdict on each call and confirming the
predicate does not mutate its input. Mutation-verified against a
deliberately broken hasRunVanish (forced to return false) to confirm
the test now fails as expected.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/parser/docx/body-objects.test.ts | 36 ++++++++++++++++++----------
 1 file changed, 23 insertions(+), 13 deletions(-)

diff --git a/src/parser/docx/body-objects.test.ts b/src/parser/docx/body-objects.test.ts
index a1636372..77839e4b 100644
--- a/src/parser/docx/body-objects.test.ts
+++ b/src/parser/docx/body-objects.test.ts
@@ -397,19 +397,29 @@ describe('hasRunVanish — rStyle-referenced character-style vanish (#650, captu
   });
 
   // #650 review (verified finding): the ORIGINAL version of this test called
-  // `hasRunVanish` twice with the exact same literal arguments and compared
-  // the two results — that can never fail for a deterministic pure function,
-  // so it never actually exercised either real call site. This replacement
-  // derives `vanishCharStyleIds` from a REAL `extractBodyObjects` capture and
-  // feeds that exact captured value into the REAL `replaceAnchoredParagraphText`
-  // rewrite path (object-blob-edit.ts) on the SAME source blob — the two
-  // production call sites `hasRunVanish`'s own doc comment says must share
-  // one predicate (ADR-092) — proving they actually agree end-to-end. See the
-  // "hidden-first paragraph" end-to-end test below.
-  it('hasRunVanish is a pure, deterministic predicate (same input, same output) — a necessary but not sufficient property; see the end-to-end test below for the real shared-object proof', () => {
-    const node = blobRun([blobRStyle('HiddenChar')]);
-    const vanishCharStyleIds = new Set(['HiddenChar']);
-    expect(hasRunVanish(node, vanishCharStyleIds)).toBe(hasRunVanish(node, vanishCharStyleIds));
+  // `hasRunVanish` ONCE, then compared that return value against a SECOND
+  // call using the exact same node/Set references — a tautology that can
+  // never fail for a deterministic function (any return value, even a wrong
+  // one, equals itself), so it never actually exercised the implementation.
+  // Fixed to call the predicate on two INDEPENDENTLY constructed (but
+  // structurally identical) node instances, asserting the concrete expected
+  // verdict on each call rather than comparing the pair to each other, and
+  // confirming the predicate does not mutate the node it inspects. The full
+  // end-to-end proof that capture and rewrite actually AGREE on one real
+  // `vanishCharStyleIds` value derived from an `extractBodyObjects` capture
+  // and fed into `replaceAnchoredParagraphText` (object-blob-edit.ts) — the
+  // two production call sites `hasRunVanish`'s own doc comment says must
+  // share one predicate (ADR-092) — lives in the "hidden-first paragraph"
+  // end-to-end test below.
+  it('hasRunVanish is a pure, deterministic predicate: two independently built, structurally identical runs get the same real verdict, without mutating their input', () => {
+    const buildHiddenRun = (): ObjectBlobNode => blobRun([blobRStyle('HiddenChar')]);
+    const firstNode = buildHiddenRun();
+    const secondNode = buildHiddenRun();
+    const beforeCall = structuredClone(firstNode);
+
+    expect(hasRunVanish(firstNode, new Set(['HiddenChar']))).toBe(true);
+    expect(hasRunVanish(secondNode, new Set(['HiddenChar']))).toBe(true);
+    expect(firstNode).toEqual(beforeCall);
   });
 
   // A paragraph with the VANISH run FIRST in document order and the VISIBLE

From 01768bd5bb28e46707da78f0510b06d8ff87831d Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 16:04:22 -0700
Subject: [PATCH 13/17] docs(adr): record ADR-094 (#650 vanish char-style
 persistence), close ADR-092's scope-limit note

ADR-092 documented hasRunVanish's w:rStyle character-style scope limit as an
accepted, measured gap. #650's fix (already implemented on this branch)
closes it by persisting the resolved vanishCharStyleIds set on the captured
object; this ADR was the one piece of the issue's required work not yet
recorded. ADR-092's Context/Consequences are amended to point at ADR-094
rather than describe the now-closed limit as current behaviour.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 ...text-walk-run-and-paragraph-suppression.md |  44 +++---
 ...94-object-vanish-char-style-persistence.md | 132 ++++++++++++++++++
 2 files changed, 155 insertions(+), 21 deletions(-)
 create mode 100644 docs/adr/094-object-vanish-char-style-persistence.md

diff --git a/docs/adr/092-object-text-walk-run-and-paragraph-suppression.md b/docs/adr/092-object-text-walk-run-and-paragraph-suppression.md
index ec51b296..c61640e8 100644
--- a/docs/adr/092-object-text-walk-run-and-paragraph-suppression.md
+++ b/docs/adr/092-object-text-walk-run-and-paragraph-suppression.md
@@ -136,21 +136,23 @@ falsy `w:val` as "off", and regression tests pin the SURVIVAL direction
 (text with `w:val="0"` must come through) alongside the ON direction
 (`w:val="1"` and a bare `<w:vanish/>` must still suppress).
 
-**Scope limit, recorded rather than silently narrowed:** `hasRunVanish` does
-not resolve a character-style-referenced vanish (`w:rStyle` pointing at a
-style whose own `rPr` carries `w:vanish` — `document.ts`'s `runIsVanish`
-does this via a `vanishCharStyleIds` set built from a `StyleMap`).
-`extractBodyObjects` does receive a `StyleMap`, but it is not currently
-threaded down through `anchorInteriorParagraphs` to this leaf-level walk.
-The residual gap was measured, not assumed: no fixture in the 39-file DOCX
-corpus references a vanish character style via `w:rStyle` (0 files). It errs
-toward UNDER-suppression — a visible leak, detectable by a test — never
-toward the silent data loss the toggle bug above would have caused. If
-full-corpus revalidation ever
-surfaces a leak traceable to one of these narrower cases, it is a new,
-separately-triaged defect — not evidence this ADR silently under-scoped
-`hasRunVanish`; the full corpus (705 fixtures, `pnpm fixture:diff`) showed no
-such case at the time of this fix (see Consequences).
+**Scope limit — CLOSED by ADR-094 (#650), left here for the historical
+record.** As originally shipped, `hasRunVanish` did not resolve a
+character-style-referenced vanish (`w:rStyle` pointing at a style whose own
+`rPr` carries `w:vanish` — `document.ts`'s `runIsVanish` already resolved
+this via a `vanishCharStyleIds` set built from a `StyleMap`).
+`extractBodyObjects` received a `StyleMap`, but it was not threaded down
+through `anchorInteriorParagraphs` to this leaf-level walk. The gap was
+measured, not assumed, at the time: no fixture in the 39-file DOCX corpus
+referenced a vanish character style via `w:rStyle` (0 files) — production-
+reachable (trivial for a Word user to define) but corpus-unreachable — and
+it erred toward UNDER-suppression (a visible leak, detectable by a test),
+never toward the silent data loss the toggle bug above would have caused.
+ADR-094 closes it by persisting the resolved `vanishCharStyleIds` set
+alongside each captured object, so `hasRunVanish` resolves both signals in
+both capture and the edit-rewrite walk without needing `styles.xml` at
+rewrite time. Read ADR-094 for the current behaviour; this paragraph is not
+current documentation.
 
 **2. `body-objects.ts` gets NO rule-row/`isRuleRow` suppression branch —
 object-captured interior text stays verbatim, exactly as ADR-072 decision 14
@@ -238,12 +240,12 @@ desynchronizes from it. Two such walks exist, and they land differently:
   unverified against real-world documents beyond the hand-built regression
   fixtures in `body-objects.test.ts` — expected, logged here rather than
   silently assumed identical.
-- `hasRunVanish` honours `w:vanish` as an ST_OnOff toggle; its one remaining
-  scope limit (no `w:rStyle` character-style resolution) is a documented
-  boundary, not a silent gap — see decision 1. That limit under-suppresses
-  rather than over-suppresses, so its failure mode is a detectable leak, not
-  invisible data loss. A future report of a leak traceable to it is new
-  evidence, not proof this ADR mis-scoped the fix.
+- `hasRunVanish` honours `w:vanish` as an ST_OnOff toggle; the `w:rStyle`
+  character-style scope limit recorded here (decision 1) under-suppressed
+  rather than over-suppressed, so its failure mode was a detectable leak, not
+  invisible data loss — and it is now CLOSED, not merely documented: ADR-094
+  (#650) persists the resolved `vanishCharStyleIds` set on the captured
+  object so `hasRunVanish` resolves both signals in both capture and rewrite.
 - No public/exported struct changed: `CapturedObjectText`, `CapturedBodyObject`,
   `ChildrenTransformResult`/`InteriorTransformResult`, and every `ObjectBlobNode`
   shape are byte-for-byte unchanged — this ADR only changes which text
diff --git a/docs/adr/094-object-vanish-char-style-persistence.md b/docs/adr/094-object-vanish-char-style-persistence.md
new file mode 100644
index 00000000..c62b6507
--- /dev/null
+++ b/docs/adr/094-object-vanish-char-style-persistence.md
@@ -0,0 +1,132 @@
+# ADR-094: persist resolved vanish character-style IDs on the captured object, not `styles.xml`
+
+## Status
+
+Accepted
+
+## Context
+
+ADR-092 shipped `hasRunVanish` with a recorded scope limit: it resolves a
+direct `w:rPr>w:vanish` on a run, but not a `w:vanish` reached indirectly
+through `w:rPr>w:rStyle` naming a character style that itself carries
+`w:vanish`. `document.ts`'s `runIsVanish` (the paragraph-tier equivalent)
+already resolves this, via a `StyleMap.vanishCharStyleIds` set built once
+from `styles.xml` at parse time. The object-capture tier was the odd one
+out — #650 measured the gap as unreachable across the 39-file DOCX corpus
+(0 files reference a vanish character style via `w:rStyle`) but reachable in
+production, since a Word user can define a hidden character style trivially.
+Left as-is it is a privacy leak of the same class as #515/#641: hidden text
+surfacing in `objectText`, the API, and rendered output.
+
+**Why the obvious fix — teach `hasRunVanish` to also resolve `w:rStyle`
+using the `StyleMap` already in scope at parse time — is wrong.**
+`hasRunVanish` is exported specifically so capture (`collectText` in
+`body-objects.ts`) and edit rewrite (`object-blob-edit.ts`'s
+`rewriteFirstText`) share one definition; a second, drifting copy is what
+produced the P1 caught on PR #647 (ADR-092). But `rewriteObjectTextBlob`
+(`src/db/queries/object-text-edit.ts`) reads a persisted `object_data` JSONB
+row inside an open transaction — there is no `styles.xml` there and no route
+to a `StyleMap`. `styles.xml` is a separate OOXML part the captured blob
+never contained (ADR-072 decision 1: objects round-trip as an opaque blob).
+Fixing only capture's `hasRunVanish` call site would desynchronize it from
+rewrite: capture would start skipping style-vanished runs rewrite still
+cannot see, and an edit could land in a skipped (hidden) run while blanking
+the visible one — over-suppression that is worse than the original leak
+(ADR-092's own asymmetry principle: a missed suppression is a detectable
+visible leak, a wrong suppression is invisible data loss).
+
+## Decision
+
+**Persist the resolved vanish character-style ID set alongside the captured
+object**, so capture and rewrite read one shared, already-resolved source of
+truth and never need `styles.xml` at rewrite time.
+
+1. `ObjectMetaSchema` (`src/ast/object-schemas.ts`) gains an additive,
+   optional `vanishCharStyleIds: string[]` field — JSONB, no migration.
+   Absent and `[]` are fully interchangeable (today's behaviour: no run
+   treated as hidden by style), so a pre-#650 row loads and edits unchanged.
+   Persisted as a **sorted** array, never a `Set`, so the JSONB column and
+   fixture snapshots serialize deterministically.
+2. Capture: `extractBodyObjects` already receives the `StyleMap`, so
+   `CapturedBodyObject.vanishCharStyleIds` carries the FULL resolved set
+   forward unfiltered (not narrowed to what this object actually
+   referenced — simplicity, zero correctness cost), and
+   `body-object-attach.ts`'s `toObjectMeta` persists it.
+3. `hasRunVanish` (`body-object-vanish.ts`, split out of `body-objects.ts`
+   purely to stay under the file's line budget) takes the set as a
+   parameter — a straight OR port of `document.ts`'s `runIsVanish`: hidden
+   if EITHER the run's own `w:rPr>w:vanish` is an enabled ST_OnOff toggle
+   OR its `w:rStyle` names an id in the set. No special-casing between the
+   two signals.
+4. Rewrite: `rewriteObjectTextBlob` reads `meta.vanishCharStyleIds ?? []`
+   off the SAME row it already loaded and threads it into
+   `replaceAnchoredParagraphText` → `rewriteFirstText`'s `hasRunVanish`
+   call — one predicate, both directions, no `styles.xml` needed.
+5. Backfill: explicitly refused. A row captured before this change carries
+   no set and none can be re-derived (the originating `styles.xml` is not
+   stored anywhere) — it keeps today's behaviour (empty set) until its
+   source document is re-imported. No fabricated backfill.
+
+**Adversarial-review finding folded in: the generator never wrote a
+`w:styles` character-style section at all**, so a captured object's blob
+(byte-identical, `w:rStyle` reference included, per ADR-072 decision 1)
+regenerated into a DOCX whose `styles.xml` no longer defined the referenced
+character style. Re-opening or re-parsing that file resolved
+`vanishCharStyleIds` back to empty and the previously-hidden run surfaced as
+plain visible text — a real regression, not a hypothetical, caught by
+`body-object-round-trip.test.ts`'s own round-trip case for this fix.
+`object-vanish-styles.ts` closes it: `collectVanishCharacterStyleIds` unions
+every captured object's `vanishCharStyleIds` across the tree(s) being
+generated, and `vanishCharacterStyleOptions` emits one minimal
+`w:type="character"` style stub per id — carrying only an enabled
+`w:vanish`, nothing else of the original style (font, color, basedOn
+chain — SpecR does not retain the source `styles.xml` to reconstruct them,
+and none of it affects vanish resolution). `generateDocx`/`generateManual`
+emit this stub set only when at least one captured object actually
+references one, keeping the overwhelmingly common case byte-identical to
+pre-#650 output.
+
+**Second adversarial-review finding: `generateManual` combines multiple
+source trees into one `styles.xml` namespace.** Two different source
+documents can each define their OWN character style under the SAME id — one
+genuinely vanish, one used only for bold/underline on visible text. Sharing
+one namespace lets one tree's minted vanish stub silently overwrite another
+tree's unrelated same-named style, hiding text the other tree's own capture
+correctly resolved as visible. `object-vanish-namespace.ts`'s
+`namespaceVanishTrees` fixes this by giving every source tree its own
+private namespace (`<id>#specr-vanish-t<treeIndex>`) for the ids its OWN
+captured objects reference — renaming both the `w:rStyle` references in that
+tree's own object blobs and the `vanishCharStyleIds` entries themselves.
+Deliberately unconditional (every tree with any vanish ids is namespaced,
+not only on a detected same-id collision): detecting a real collision would
+need scanning every OTHER tree's blobs for a non-vanish reference to the
+same id, a larger walk for a case the cheap unconditional rename already
+makes moot — the renamed id is never read back by SpecR (it is shown to a
+human in Word, never a correlation key). A no-op — every tree and the whole
+array returned BY REFERENCE — for `trees.length <= 1` or when no tree
+carries any vanish ids, so `generateDocx` (always exactly one tree) and the
+overwhelmingly common manual case are unaffected.
+
+## Consequences
+
+- `ObjectMetaSchema`'s cross-field check also now couples `SpecNodeSchema`'s
+  `type`/`meta.object` presence (an `'object'` node requires `meta.object`
+  and no other node type may carry one) — a structural hardening discovered
+  auditing `.shape`-spread consumers of these schemas for the new field, not
+  a `vanishCharStyleIds`-specific rule.
+- ADR-092's "Scope limit, recorded rather than silently narrowed" paragraph
+  is superseded by this ADR — see the amendment there.
+- `openapi.yaml` documents `vanishCharStyleIds` on the object-meta schema.
+- No DB migration: additive JSONB field on `paragraphs.object_data`.
+- Full-corpus revalidation (`pnpm fixture:snapshot`/`pnpm fixture:diff`, 705
+  fixtures): addition-only, 0 fixtures moved — no corpus file exercises a
+  `w:rStyle`-referenced vanish character style (measured in the issue), so
+  this closes a production-reachable gap the corpus itself cannot exercise
+  end-to-end; coverage instead comes from hand-built fixtures in
+  `body-object-round-trip.test.ts` and `object-schemas.test.ts`.
+- Cross-references: ADR-092 (the predicate and split-file this ADR extends);
+  ADR-072 decision 1 (opaque blob round-trip — why `styles.xml` cannot be
+  read at rewrite time, and why the generator stub reconstructs nothing
+  beyond the vanish toggle); PR #536 (the additive-field-does-not-persist
+  trap this ADR's write/read-path wiring and round-trip tests were written
+  against).

From b7a244bc883aad0f95617392ac9f501376e8ec86 Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 16:16:20 -0700
Subject: [PATCH 14/17] revert(docs): drop ADR-094 and the ADR-092 amendment
 (#650)

The repository owner forbade new or amended ADR files for this sprint.
The design rationale they carried now lives in the PR body under
"Design decisions" and in code comments / test names on this branch.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ...text-walk-run-and-paragraph-suppression.md |  44 +++---
 ...94-object-vanish-char-style-persistence.md | 132 ------------------
 2 files changed, 21 insertions(+), 155 deletions(-)
 delete mode 100644 docs/adr/094-object-vanish-char-style-persistence.md

diff --git a/docs/adr/092-object-text-walk-run-and-paragraph-suppression.md b/docs/adr/092-object-text-walk-run-and-paragraph-suppression.md
index c61640e8..ec51b296 100644
--- a/docs/adr/092-object-text-walk-run-and-paragraph-suppression.md
+++ b/docs/adr/092-object-text-walk-run-and-paragraph-suppression.md
@@ -136,23 +136,21 @@ falsy `w:val` as "off", and regression tests pin the SURVIVAL direction
 (text with `w:val="0"` must come through) alongside the ON direction
 (`w:val="1"` and a bare `<w:vanish/>` must still suppress).
 
-**Scope limit — CLOSED by ADR-094 (#650), left here for the historical
-record.** As originally shipped, `hasRunVanish` did not resolve a
-character-style-referenced vanish (`w:rStyle` pointing at a style whose own
-`rPr` carries `w:vanish` — `document.ts`'s `runIsVanish` already resolved
-this via a `vanishCharStyleIds` set built from a `StyleMap`).
-`extractBodyObjects` received a `StyleMap`, but it was not threaded down
-through `anchorInteriorParagraphs` to this leaf-level walk. The gap was
-measured, not assumed, at the time: no fixture in the 39-file DOCX corpus
-referenced a vanish character style via `w:rStyle` (0 files) — production-
-reachable (trivial for a Word user to define) but corpus-unreachable — and
-it erred toward UNDER-suppression (a visible leak, detectable by a test),
-never toward the silent data loss the toggle bug above would have caused.
-ADR-094 closes it by persisting the resolved `vanishCharStyleIds` set
-alongside each captured object, so `hasRunVanish` resolves both signals in
-both capture and the edit-rewrite walk without needing `styles.xml` at
-rewrite time. Read ADR-094 for the current behaviour; this paragraph is not
-current documentation.
+**Scope limit, recorded rather than silently narrowed:** `hasRunVanish` does
+not resolve a character-style-referenced vanish (`w:rStyle` pointing at a
+style whose own `rPr` carries `w:vanish` — `document.ts`'s `runIsVanish`
+does this via a `vanishCharStyleIds` set built from a `StyleMap`).
+`extractBodyObjects` does receive a `StyleMap`, but it is not currently
+threaded down through `anchorInteriorParagraphs` to this leaf-level walk.
+The residual gap was measured, not assumed: no fixture in the 39-file DOCX
+corpus references a vanish character style via `w:rStyle` (0 files). It errs
+toward UNDER-suppression — a visible leak, detectable by a test — never
+toward the silent data loss the toggle bug above would have caused. If
+full-corpus revalidation ever
+surfaces a leak traceable to one of these narrower cases, it is a new,
+separately-triaged defect — not evidence this ADR silently under-scoped
+`hasRunVanish`; the full corpus (705 fixtures, `pnpm fixture:diff`) showed no
+such case at the time of this fix (see Consequences).
 
 **2. `body-objects.ts` gets NO rule-row/`isRuleRow` suppression branch —
 object-captured interior text stays verbatim, exactly as ADR-072 decision 14
@@ -240,12 +238,12 @@ desynchronizes from it. Two such walks exist, and they land differently:
   unverified against real-world documents beyond the hand-built regression
   fixtures in `body-objects.test.ts` — expected, logged here rather than
   silently assumed identical.
-- `hasRunVanish` honours `w:vanish` as an ST_OnOff toggle; the `w:rStyle`
-  character-style scope limit recorded here (decision 1) under-suppressed
-  rather than over-suppressed, so its failure mode was a detectable leak, not
-  invisible data loss — and it is now CLOSED, not merely documented: ADR-094
-  (#650) persists the resolved `vanishCharStyleIds` set on the captured
-  object so `hasRunVanish` resolves both signals in both capture and rewrite.
+- `hasRunVanish` honours `w:vanish` as an ST_OnOff toggle; its one remaining
+  scope limit (no `w:rStyle` character-style resolution) is a documented
+  boundary, not a silent gap — see decision 1. That limit under-suppresses
+  rather than over-suppresses, so its failure mode is a detectable leak, not
+  invisible data loss. A future report of a leak traceable to it is new
+  evidence, not proof this ADR mis-scoped the fix.
 - No public/exported struct changed: `CapturedObjectText`, `CapturedBodyObject`,
   `ChildrenTransformResult`/`InteriorTransformResult`, and every `ObjectBlobNode`
   shape are byte-for-byte unchanged — this ADR only changes which text
diff --git a/docs/adr/094-object-vanish-char-style-persistence.md b/docs/adr/094-object-vanish-char-style-persistence.md
deleted file mode 100644
index c62b6507..00000000
--- a/docs/adr/094-object-vanish-char-style-persistence.md
+++ /dev/null
@@ -1,132 +0,0 @@
-# ADR-094: persist resolved vanish character-style IDs on the captured object, not `styles.xml`
-
-## Status
-
-Accepted
-
-## Context
-
-ADR-092 shipped `hasRunVanish` with a recorded scope limit: it resolves a
-direct `w:rPr>w:vanish` on a run, but not a `w:vanish` reached indirectly
-through `w:rPr>w:rStyle` naming a character style that itself carries
-`w:vanish`. `document.ts`'s `runIsVanish` (the paragraph-tier equivalent)
-already resolves this, via a `StyleMap.vanishCharStyleIds` set built once
-from `styles.xml` at parse time. The object-capture tier was the odd one
-out — #650 measured the gap as unreachable across the 39-file DOCX corpus
-(0 files reference a vanish character style via `w:rStyle`) but reachable in
-production, since a Word user can define a hidden character style trivially.
-Left as-is it is a privacy leak of the same class as #515/#641: hidden text
-surfacing in `objectText`, the API, and rendered output.
-
-**Why the obvious fix — teach `hasRunVanish` to also resolve `w:rStyle`
-using the `StyleMap` already in scope at parse time — is wrong.**
-`hasRunVanish` is exported specifically so capture (`collectText` in
-`body-objects.ts`) and edit rewrite (`object-blob-edit.ts`'s
-`rewriteFirstText`) share one definition; a second, drifting copy is what
-produced the P1 caught on PR #647 (ADR-092). But `rewriteObjectTextBlob`
-(`src/db/queries/object-text-edit.ts`) reads a persisted `object_data` JSONB
-row inside an open transaction — there is no `styles.xml` there and no route
-to a `StyleMap`. `styles.xml` is a separate OOXML part the captured blob
-never contained (ADR-072 decision 1: objects round-trip as an opaque blob).
-Fixing only capture's `hasRunVanish` call site would desynchronize it from
-rewrite: capture would start skipping style-vanished runs rewrite still
-cannot see, and an edit could land in a skipped (hidden) run while blanking
-the visible one — over-suppression that is worse than the original leak
-(ADR-092's own asymmetry principle: a missed suppression is a detectable
-visible leak, a wrong suppression is invisible data loss).
-
-## Decision
-
-**Persist the resolved vanish character-style ID set alongside the captured
-object**, so capture and rewrite read one shared, already-resolved source of
-truth and never need `styles.xml` at rewrite time.
-
-1. `ObjectMetaSchema` (`src/ast/object-schemas.ts`) gains an additive,
-   optional `vanishCharStyleIds: string[]` field — JSONB, no migration.
-   Absent and `[]` are fully interchangeable (today's behaviour: no run
-   treated as hidden by style), so a pre-#650 row loads and edits unchanged.
-   Persisted as a **sorted** array, never a `Set`, so the JSONB column and
-   fixture snapshots serialize deterministically.
-2. Capture: `extractBodyObjects` already receives the `StyleMap`, so
-   `CapturedBodyObject.vanishCharStyleIds` carries the FULL resolved set
-   forward unfiltered (not narrowed to what this object actually
-   referenced — simplicity, zero correctness cost), and
-   `body-object-attach.ts`'s `toObjectMeta` persists it.
-3. `hasRunVanish` (`body-object-vanish.ts`, split out of `body-objects.ts`
-   purely to stay under the file's line budget) takes the set as a
-   parameter — a straight OR port of `document.ts`'s `runIsVanish`: hidden
-   if EITHER the run's own `w:rPr>w:vanish` is an enabled ST_OnOff toggle
-   OR its `w:rStyle` names an id in the set. No special-casing between the
-   two signals.
-4. Rewrite: `rewriteObjectTextBlob` reads `meta.vanishCharStyleIds ?? []`
-   off the SAME row it already loaded and threads it into
-   `replaceAnchoredParagraphText` → `rewriteFirstText`'s `hasRunVanish`
-   call — one predicate, both directions, no `styles.xml` needed.
-5. Backfill: explicitly refused. A row captured before this change carries
-   no set and none can be re-derived (the originating `styles.xml` is not
-   stored anywhere) — it keeps today's behaviour (empty set) until its
-   source document is re-imported. No fabricated backfill.
-
-**Adversarial-review finding folded in: the generator never wrote a
-`w:styles` character-style section at all**, so a captured object's blob
-(byte-identical, `w:rStyle` reference included, per ADR-072 decision 1)
-regenerated into a DOCX whose `styles.xml` no longer defined the referenced
-character style. Re-opening or re-parsing that file resolved
-`vanishCharStyleIds` back to empty and the previously-hidden run surfaced as
-plain visible text — a real regression, not a hypothetical, caught by
-`body-object-round-trip.test.ts`'s own round-trip case for this fix.
-`object-vanish-styles.ts` closes it: `collectVanishCharacterStyleIds` unions
-every captured object's `vanishCharStyleIds` across the tree(s) being
-generated, and `vanishCharacterStyleOptions` emits one minimal
-`w:type="character"` style stub per id — carrying only an enabled
-`w:vanish`, nothing else of the original style (font, color, basedOn
-chain — SpecR does not retain the source `styles.xml` to reconstruct them,
-and none of it affects vanish resolution). `generateDocx`/`generateManual`
-emit this stub set only when at least one captured object actually
-references one, keeping the overwhelmingly common case byte-identical to
-pre-#650 output.
-
-**Second adversarial-review finding: `generateManual` combines multiple
-source trees into one `styles.xml` namespace.** Two different source
-documents can each define their OWN character style under the SAME id — one
-genuinely vanish, one used only for bold/underline on visible text. Sharing
-one namespace lets one tree's minted vanish stub silently overwrite another
-tree's unrelated same-named style, hiding text the other tree's own capture
-correctly resolved as visible. `object-vanish-namespace.ts`'s
-`namespaceVanishTrees` fixes this by giving every source tree its own
-private namespace (`<id>#specr-vanish-t<treeIndex>`) for the ids its OWN
-captured objects reference — renaming both the `w:rStyle` references in that
-tree's own object blobs and the `vanishCharStyleIds` entries themselves.
-Deliberately unconditional (every tree with any vanish ids is namespaced,
-not only on a detected same-id collision): detecting a real collision would
-need scanning every OTHER tree's blobs for a non-vanish reference to the
-same id, a larger walk for a case the cheap unconditional rename already
-makes moot — the renamed id is never read back by SpecR (it is shown to a
-human in Word, never a correlation key). A no-op — every tree and the whole
-array returned BY REFERENCE — for `trees.length <= 1` or when no tree
-carries any vanish ids, so `generateDocx` (always exactly one tree) and the
-overwhelmingly common manual case are unaffected.
-
-## Consequences
-
-- `ObjectMetaSchema`'s cross-field check also now couples `SpecNodeSchema`'s
-  `type`/`meta.object` presence (an `'object'` node requires `meta.object`
-  and no other node type may carry one) — a structural hardening discovered
-  auditing `.shape`-spread consumers of these schemas for the new field, not
-  a `vanishCharStyleIds`-specific rule.
-- ADR-092's "Scope limit, recorded rather than silently narrowed" paragraph
-  is superseded by this ADR — see the amendment there.
-- `openapi.yaml` documents `vanishCharStyleIds` on the object-meta schema.
-- No DB migration: additive JSONB field on `paragraphs.object_data`.
-- Full-corpus revalidation (`pnpm fixture:snapshot`/`pnpm fixture:diff`, 705
-  fixtures): addition-only, 0 fixtures moved — no corpus file exercises a
-  `w:rStyle`-referenced vanish character style (measured in the issue), so
-  this closes a production-reachable gap the corpus itself cannot exercise
-  end-to-end; coverage instead comes from hand-built fixtures in
-  `body-object-round-trip.test.ts` and `object-schemas.test.ts`.
-- Cross-references: ADR-092 (the predicate and split-file this ADR extends);
-  ADR-072 decision 1 (opaque blob round-trip — why `styles.xml` cannot be
-  read at rewrite time, and why the generator stub reconstructs nothing
-  beyond the vanish toggle); PR #536 (the additive-field-does-not-persist
-  trap this ADR's write/read-path wiring and round-trip tests were written
-  against).

From 2f5613df03bdf0b6904c59869c1cb28fb7684105 Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 18:47:20 -0700
Subject: [PATCH 15/17] test(db): prove vanishCharStyleIds reaches a real
 object_data column (#650)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The pre-existing coverage inserted object rows with raw SQL, so it proved
the JSONB column stores the field and rewriteObjectTextBlob reads it back,
but never exercised the CANONICAL save path. That is exactly the shape of
the pageSize regression in PR #536: an additive SpecTree field that passed
every in-memory test while the save/load mappers silently dropped it.

These cases drive insertTree (the same write path DOCX import uses) and
assert twice — once against the raw `object_data->'vanishCharStyleIds'`
JSONB column via SQL, so the value is proven on disk rather than in a
cache, and once through the real read mappers (getSpecTree and
fetchSubtreeNode). A third case pins the backfill invariant: an object
with no vanish styles persists and reads back with the key ABSENT, never
fabricated as an empty array.

Mutation-verified in both directions rather than assumed load-bearing:
dropping the field from ObjectMetaSchema fails the read-path case, and
stripping it in flattenDfs's objectData mapping fails both the column and
the round-trip case.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/db/queries/paragraphs.integration.test.ts | 103 ++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/src/db/queries/paragraphs.integration.test.ts b/src/db/queries/paragraphs.integration.test.ts
index 970fde43..d56e52e2 100644
--- a/src/db/queries/paragraphs.integration.test.ts
+++ b/src/db/queries/paragraphs.integration.test.ts
@@ -451,6 +451,109 @@ describe('body objects — read-path parity (#300, ADR-072)', () => {
   });
 });
 
+// #650 — vanishCharStyleIds must reach a real DATABASE column and come back,
+// not merely round-trip in memory. PR #536 (`pageSize`) is the precedent this
+// block exists to rule out: an additive SpecTree field that every in-memory
+// test passed while the save/load mappers silently dropped it. So each case
+// below drives the CANONICAL write path (insertTree, the same one the DOCX
+// import uses) and then asserts twice — once against the raw `object_data`
+// JSONB column via SQL (proof the value is on disk, not in a cache), and once
+// through the real read mappers (getSpecTree / fetchSubtreeNode).
+const VANISH_STYLE_OBJECT_META: ObjectMeta = {
+  kind: 'table',
+  floating: false,
+  generation: 'drawingml',
+  rows: 1,
+  columns: 1,
+  vanishCharStyleIds: ['AlsoHidden', 'HiddenChar'],
+  blob: [{ 'w:tbl': [{ 'w:tblPr': [] }] }],
+};
+
+describe('body objects — vanishCharStyleIds DB persistence (#650)', () => {
+  const VS_PART_ID = 'd0000000-0000-0000-0000-000000000650';
+  const VS_OBJECT_ID = 'd0000000-0000-0000-0000-000000000651';
+  let vsSpecId: string;
+
+  async function insertObjectTree(meta: ObjectMeta): Promise<void> {
+    await insertTree(
+      {
+        id: vsSpecId,
+        section: '99 00 50',
+        title: 'Vanish Style Persistence',
+        parts: [
+          {
+            id: VS_PART_ID,
+            type: 'part',
+            text: 'GENERAL',
+            children: [
+              {
+                id: VS_OBJECT_ID,
+                type: 'object',
+                text: '[TABLE]',
+                children: [],
+                meta: { object: meta },
+              },
+            ],
+            meta: {},
+          },
+        ],
+      },
+      vsSpecId,
+      pool
+    );
+  }
+
+  beforeEach(async () => {
+    vsSpecId = await createSpec({
+      section: '99 00 50',
+      title: 'Vanish Style Persistence',
+      source: 'arcat',
+    });
+  });
+
+  afterEach(async () => {
+    await pool.query('DELETE FROM specs WHERE id = $1', [vsSpecId]);
+  });
+
+  it('persistence: vanishCharStyleIds is written to the object_data JSONB COLUMN by insertTree', async () => {
+    await insertObjectTree(VANISH_STYLE_OBJECT_META);
+
+    // Read the column directly — a passing in-memory assertion cannot prove
+    // this, and the #536 regression is exactly a value that never got here.
+    const raw = await pool.query<{ ids: readonly string[] | null }>(
+      `SELECT object_data->'vanishCharStyleIds' AS ids FROM paragraphs WHERE id = $1`,
+      [VS_OBJECT_ID]
+    );
+    expect(raw.rows[0]!.ids).toEqual(['AlsoHidden', 'HiddenChar']);
+  });
+
+  it('round-trip: getSpecTree and fetchSubtreeNode both return vanishCharStyleIds verbatim', async () => {
+    await insertObjectTree(VANISH_STYLE_OBJECT_META);
+
+    const fullTree = await getSpecTree(vsSpecId);
+    const treeNode = fullTree!.tree.parts[0]!.children[0]!;
+    expect(treeNode.meta.object).toEqual(VANISH_STYLE_OBJECT_META);
+    expect(treeNode.meta.object!.vanishCharStyleIds).toEqual(['AlsoHidden', 'HiddenChar']);
+
+    const subtreeNode = await fetchSubtreeNode(pool, vsSpecId, VS_OBJECT_ID);
+    expect(subtreeNode!.meta.object!.vanishCharStyleIds).toEqual(['AlsoHidden', 'HiddenChar']);
+  });
+
+  it('backfill: an object with NO vanishCharStyleIds persists and reads back with the key absent, never fabricated', async () => {
+    await insertObjectTree(TABLE_OBJECT_META);
+
+    const raw = await pool.query<{ ids: readonly string[] | null }>(
+      `SELECT object_data->'vanishCharStyleIds' AS ids FROM paragraphs WHERE id = $1`,
+      [VS_OBJECT_ID]
+    );
+    expect(raw.rows[0]!.ids).toBeNull();
+
+    const fullTree = await getSpecTree(vsSpecId);
+    const treeNode = fullTree!.tree.parts[0]!.children[0]!;
+    expect(treeNode.meta.object!.vanishCharStyleIds).toBeUndefined();
+  });
+});
+
 // #519 (ADR-072 decision 3) — the write-path wiring in applyParagraphUpdate:
 // an `object` row is locked (its content is a captured OOXML blob, never a
 // plain text write); an `objectText` row's edit is dispatched into its

From 4b348cc8d24b73f0614e6873b14e291e83c7a2b6 Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Tue, 4 Aug 2026 20:11:45 -0700
Subject: [PATCH 16/17] fix(parser,generator): close four adversarial-review
 findings (#650)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All four are over-suppression or collision paths this branch itself
introduced — visible text being hidden, which is the failure mode that
produces no error and merely looks like correct privacy behaviour.

1. hasRunVanish resolved the two vanish signals with a plain OR, so a run
   carrying BOTH an rStyle vanish and a direct <w:vanish w:val="0"/> stayed
   hidden. ECMA-376 17.7.3 makes direct formatting definitive for a toggle
   property: writing w:val="0" is the author switching the style's vanish
   back OFF. Now resolved as a tri-state. document.ts's paragraph-tier
   runIsVanish keeps the older behaviour deliberately — this fix is scoped
   to the object tier's own new rStyle path rather than silently changing
   long-shipped paragraph classification in a bugfix PR.

2. Capture persisted the document-wide vanish-style set on EVERY object,
   O(objects x styles) into JSONB. It also made the generator mint a stub
   for ids no blob references, widening the collision surface below. Now
   narrowed to the ids the object's own blob actually references, which
   costs no correctness: rewrite only ever resolves runs inside that blob.

3. generateDocx and single-tree generateManual emitted RAW style ids, so a
   source document whose vanish style is named after one dolanmiu/docx also
   emits (Hyperlink, Strong, ...) produced a duplicate w:styleId whose
   minted w:vanish could attach to the document's own hyperlinks. Vanish
   ids are now namespaced on every generation path; the style's display
   name is de-namespaced so Word still shows the original name.

4. The namespace suffix was assumed unforgeable. Nothing reserves it, so
   minted ids are now collision-checked against every id that survives
   renaming, and the allocator strips before it mints — without that,
   repeated generate/re-parse cycles stacked a fresh suffix each time and
   broke the byte-identical blob round-trip.

Two tests that encoded the old behaviour are flipped as explicit, commented
oracle changes rather than quietly edited. Corpus revalidated: 0/666.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/generator/index.ts                        |  11 +-
 src/generator/object-vanish-namespace.test.ts |  60 ++++++-
 src/generator/object-vanish-namespace.ts      | 152 ++++++++++++++----
 src/generator/object-vanish-styles.ts         |  42 ++++-
 src/parser/docx/body-object-attach.test.ts    |  10 +-
 .../docx/body-object-round-trip.test.ts       |  14 +-
 src/parser/docx/body-object-vanish.ts         |  68 +++++++-
 src/parser/docx/body-objects.test.ts          |  62 ++++++-
 src/parser/docx/body-objects.ts               |   6 +-
 9 files changed, 374 insertions(+), 51 deletions(-)

diff --git a/src/generator/index.ts b/src/generator/index.ts
index f36a66ac..5754bee4 100644
--- a/src/generator/index.ts
+++ b/src/generator/index.ts
@@ -283,12 +283,19 @@ export async function generateDocx(
     const rules = styleRules !== undefined ? buildRuleMap(styleRules) : undefined;
     const format = options?.sectionNumberFormat ?? 'canonical';
     const ctx = sectionContext(format, SPEC_NUM_REF, rules);
-    const children = buildSectionChildren(tree, ctx);
+    // #650 (adversarial-review finding): namespace vanish character-style ids
+    // on the SINGLE-tree path too, not only in multi-tree generateManual. A
+    // raw id here can equal one dolanmiu/docx itself emits (`Hyperlink` being
+    // the realistic case), which would append a duplicate `w:styleId` and let
+    // the minted `w:vanish` attach to unrelated VISIBLE text. Returned by
+    // reference — byte-identical output — when the tree carries no vanish ids.
+    const [scopedTree = tree] = namespaceVanishTrees([tree]);
+    const children = buildSectionChildren(scopedTree, ctx);
     const render = renderOptionalHeaderFooter(tree, format, options);
     const pageSize = resolvePageSize(tree.pageSize);
     const doc = new Document({
       ...documentLevelOptions(render),
-      ...vanishStylesOptions([tree]),
+      ...vanishStylesOptions([scopedTree]),
       numbering: { config: [buildSpecNumberingConfig(rules, SPEC_NUM_REF)] },
       sections: [{ ...sectionHeaderFooterOptions(render, pageSize), children }],
     });
diff --git a/src/generator/object-vanish-namespace.test.ts b/src/generator/object-vanish-namespace.test.ts
index 9f4c07a7..7cd6b25b 100644
--- a/src/generator/object-vanish-namespace.test.ts
+++ b/src/generator/object-vanish-namespace.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { namespaceVanishTrees } from './object-vanish-namespace.js';
-import type { ObjectBlobNode, SpecNode, SpecTree } from '../ast/index.js';
+import type { ObjectBlobNode, ObjectMeta, SpecNode, SpecTree } from '../ast/index.js';
 
 // Minimal SpecNode/SpecTree builders — mirrors object-vanish-styles.test.ts's
 // own local convention: this module only ever reads/rewrites
@@ -95,15 +95,67 @@ function rStyleValOf(blob: readonly ObjectBlobNode[]): string | undefined {
   return undefined;
 }
 
+// The captured ObjectMeta of the first tree's first part — the shape every
+// assertion below reaches for. Extracted so each test reads one short chain
+// instead of a four-level optional dig (which trips the repo's complexity cap).
+function firstObjectMeta(trees: readonly SpecTree[]): ObjectMeta | undefined {
+  return trees[0]?.parts[0]?.meta.object;
+}
+
+function firstVanishIds(trees: readonly SpecTree[]): readonly string[] | undefined {
+  return firstObjectMeta(trees)?.vanishCharStyleIds;
+}
+
 describe('namespaceVanishTrees', () => {
   it('returns the same array reference for zero trees', () => {
     const trees: SpecTree[] = [];
     expect(namespaceVanishTrees(trees)).toBe(trees);
   });
 
-  it('returns the same array reference for a single tree, even with vanish ids', () => {
-    const trees = [tree('t0', [objectNode('Hidden1', 'secret', ['Hidden1'])])];
-    expect(namespaceVanishTrees(trees)).toBe(trees);
+  // ORACLE CHANGE, deliberate (adversarial-review finding, #650). This test
+  // previously asserted a single tree was returned untouched, on the reasoning
+  // that one tree cannot collide with a SIBLING tree. It can still collide
+  // with dolanmiu/docx's OWN built-in character styles (`Hyperlink`,
+  // `Strong`, …), which the generator emits into the same styles.xml — a
+  // duplicate `w:styleId` whose minted `w:vanish` can hide unrelated VISIBLE
+  // text. Single-tree generateDocx therefore namespaces too.
+  it('namespaces a SINGLE tree too — a raw id could collide with a docx built-in style', () => {
+    const trees = [tree('t0', [objectNode('Hyperlink', 'secret', ['Hyperlink'])])];
+    const result = namespaceVanishTrees(trees);
+
+    expect(result).not.toBe(trees);
+    expect(firstVanishIds(result)).toEqual(['Hyperlink#specr-vanish-t0']);
+  });
+
+  // Namespacing must be IDEMPOTENT. Re-parsing a generated document hands
+  // back the NAMESPACED id as that tree's raw captured id, so generating
+  // again from it must reproduce the same id — not stack a second suffix.
+  // Without the strip-before-mint in allocateNamespacedId, each round-trip
+  // cycle grew the id without bound and broke the byte-identical blob
+  // round-trip invariant that body-object-round-trip.test.ts asserts.
+  it('is idempotent: re-namespacing an already-namespaced tree reproduces the SAME id', () => {
+    const once = namespaceVanishTrees([tree('t0', [objectNode('X', 'secret', ['X'])])]);
+    expect(firstVanishIds(once)).toEqual(['X#specr-vanish-t0']);
+
+    const twice = namespaceVanishTrees(once);
+    expect(firstVanishIds(twice)).toEqual(['X#specr-vanish-t0']);
+    expect(rStyleValOf(firstObjectMeta(twice)?.blob ?? [])).toBe('X#specr-vanish-t0');
+  });
+
+  // The collision-checked allocator (adversarial-review finding, #650):
+  // NAMESPACE_SEPARATOR is not reserved by OOXML, so a source document may
+  // already use the exact id the naive mint would produce. Minting it anyway
+  // would point the vanish stub at that document's own visible-text style.
+  it('avoids a raw style id that already looks namespaced, rather than assuming the suffix cannot occur', () => {
+    const collidingRaw = 'X#specr-vanish-t0';
+    const trees = [
+      tree('t0', [objectNode('X', 'secret', ['X'])]),
+      tree('t1', [objectNode(collidingRaw, 'visible elsewhere')]),
+    ];
+    const result = namespaceVanishTrees(trees);
+
+    expect(firstVanishIds(result)).not.toEqual([collidingRaw]);
+    expect(firstVanishIds(result)).toEqual(['X#specr-vanish-t0-1']);
   });
 
   it('returns the same array reference when no tree in a multi-tree manual has any vanish ids', () => {
diff --git a/src/generator/object-vanish-namespace.ts b/src/generator/object-vanish-namespace.ts
index 4c4d4a8b..3f96e6cb 100644
--- a/src/generator/object-vanish-namespace.ts
+++ b/src/generator/object-vanish-namespace.ts
@@ -18,34 +18,72 @@
 // within one tree every reference to a given id is unambiguous — renaming
 // it, and every `w:rStyle` in that tree's own object blobs that names it, to
 // a tree-scoped id removes any possibility of a DIFFERENT tree's unrelated
-// same-named style being redefined out from under it. `generateDocx` (always
-// exactly one tree) is unaffected: there is only ever one namespace there, so
-// no rename is needed.
+// same-named style being redefined out from under it.
+//
+// Applied on EVERY generation path, `generateDocx`'s single tree included
+// (adversarial-review finding, #650). The sibling-tree collision above is not
+// the only one: dolanmiu/docx emits its OWN built-in character styles
+// (`Hyperlink`, `Strong`, `FootnoteReference`, …), so a source document whose
+// vanish character style is named `Hyperlink` made the generator append a
+// SECOND style carrying that same `w:styleId`. Word then repairs or
+// ambiguously resolves the duplicate, and the minted `w:vanish` can attach to
+// the document's hyperlinks — hiding VISIBLE text with nothing to do with the
+// captured object. Every minted id carries NAMESPACE_SEPARATOR, which no
+// built-in id does, so namespacing unconditionally closes that case too.
 //
 // Deliberately UNCONDITIONAL — every tree with any vanish ids gets
-// namespaced, not only when an actual same-named collision with a sibling
-// tree would occur. Detecting a real collision would require also scanning
-// every OTHER tree's blobs for a non-vanish reference to the same id, a much
-// larger walk for a case a cheap unconditional rename makes moot anyway: the
-// renamed id is never read back by SpecR (`object-vanish-styles.ts`'s own
-// module comment — `name` is shown to a human, never a correlation key), so
-// there is no cost to always giving each tree its own namespace.
+// namespaced, not only when an actual same-named collision would occur.
+// Detecting a real collision would require classifying every OTHER tree's
+// non-vanish references and tracking `docx`'s built-in list across library
+// upgrades, a much larger and more brittle job than a cheap always-on rename.
+// The cost is nil: `w:styleId` is the only correlation key SpecR's parser
+// reads back, and `object-vanish-styles.ts` de-namespaces the style's `name`
+// so a human opening the file in Word still sees the ORIGINAL style name.
+//
+// Minted ids are collision-CHECKED, not assumed unique: neither OOXML nor
+// ObjectMetaSchema reserves NAMESPACE_SEPARATOR, so a source document could
+// in principle already use `X#specr-vanish-t0` for visible text.
+// `allocateNamespacedId` verifies each candidate against every id the source
+// documents actually use before minting it.
 import {
   type ObjectBlobNode,
   type ObjectMeta,
   type SpecNode,
   type SpecTree,
 } from '../ast/index.js';
-import { collectVanishCharacterStyleIds } from './object-vanish-styles.js';
+import {
+  collectVanishCharacterStyleIds,
+  NAMESPACE_SEPARATOR,
+  stripVanishNamespace,
+} from './object-vanish-styles.js';
 
-// A distinctive, deterministic separator no real captured Word style id
-// could plausibly already contain — SpecR mints this, a source .docx never
-// does — so a namespaced id can never accidentally collide with either an
-// original id or another tree's namespaced id.
-const NAMESPACE_SEPARATOR = '#specr-vanish-t';
+// A distinctive, deterministic separator SpecR mints and a source .docx is
+// overwhelmingly unlikely to contain. "Unlikely" is NOT "impossible" though,
+// and neither OOXML nor ObjectMetaSchema reserves it (adversarial-review
+// finding, #650), so `allocateNamespacedId` VERIFIES each minted id against
+// every id the source documents actually use rather than assuming this
+// suffix cannot occur.
 
-function namespacedId(id: string, treeIndex: number): string {
-  return `${id}${NAMESPACE_SEPARATOR}${treeIndex}`;
+// Mints a tree-scoped id for `id` that collides with nothing in `reserved`
+// (every raw style id referenced by ANY tree, plus every id already minted
+// in this pass), widening with a numeric disambiguator until free. Because
+// every minted id contains NAMESPACE_SEPARATOR, it also can never equal one
+// of dolanmiu/docx's own built-in character-style ids (`Hyperlink`,
+// `Strong`, `FootnoteReference`, …) — which is what makes always-on
+// namespacing the fix for the duplicate-`w:styleId` case below.
+function allocateNamespacedId(id: string, treeIndex: number, reserved: Set<string>): string {
+  // Strip first, so re-namespacing an ALREADY-namespaced id (which is what a
+  // re-parse of a generated document hands back) reproduces the same id
+  // instead of stacking a second suffix on every round-trip cycle.
+  const base = `${stripVanishNamespace(id)}${NAMESPACE_SEPARATOR}${treeIndex}`;
+  let candidate = base;
+  let suffix = 0;
+  while (reserved.has(candidate)) {
+    suffix += 1;
+    candidate = `${base}-${suffix}`;
+  }
+  reserved.add(candidate);
+  return candidate;
 }
 
 // ─── ObjectBlobNode navigation (preserveOrder-mode; self-contained per the
@@ -220,24 +258,80 @@ function rewriteNodes(
   return changed ? result : nodes;
 }
 
+function collectBlobRStyleIds(node: ObjectBlobNode, acc: Set<string>): void {
+  const tag = tagOf(node);
+  if (!tag) return;
+  if (tag === 'w:rStyle') {
+    const key = rStyleValKey(node[':@']?.['@_w:val']);
+    if (key !== '') acc.add(key);
+    return;
+  }
+  for (const child of childrenOf(node)) collectBlobRStyleIds(child, acc);
+}
+
+function collectNodeStyleIds(nodes: readonly SpecNode[], acc: Set<string>): void {
+  for (const node of nodes) {
+    const object = node.meta.object;
+    if (object) {
+      for (const id of object.vanishCharStyleIds ?? []) acc.add(id);
+      for (const root of object.blob) collectBlobRStyleIds(root, acc);
+    }
+    collectNodeStyleIds(node.children, acc);
+  }
+}
+
+/**
+ * The character-style ids that will still be present in the OUTPUT after
+ * renaming — every id any tree references (`vanishCharStyleIds` plus every
+ * `w:rStyle` inside its blobs) MINUS the ids that tree is itself about to
+ * rename away.
+ *
+ * A minted id must avoid these, and not merely the vanish ones: an id used
+ * for VISIBLE formatting in another tree is exactly the id that must not
+ * acquire a vanish stub. Subtracting each tree's own renamed-away ids is
+ * what keeps allocation idempotent — on a re-parse of a generated document
+ * the namespaced id IS that tree's raw id, and treating it as occupied
+ * would push the allocator onto a `-1` suffix on every cycle.
+ */
+function collectRemainingStyleIds(trees: readonly SpecTree[]): Set<string> {
+  const remaining = new Set<string>();
+  for (const tree of trees) {
+    const renamedAway = new Set(collectVanishCharacterStyleIds([tree]));
+    const treeIds = new Set<string>();
+    collectNodeStyleIds(tree.parts, treeIds);
+    for (const id of treeIds) if (!renamedAway.has(id)) remaining.add(id);
+  }
+  return remaining;
+}
+
 /**
- * Gives every `SpecTree` in `trees` its own private namespace for the
- * vanish-character-style ids its OWN captured objects reference, so
- * `generateManual` combining multiple source documents can never let one
- * tree's vanish stub overwrite another tree's unrelated same-named style
- * (see this module's header). A no-op — every tree returned BY REFERENCE,
- * the whole array returned BY REFERENCE — when `trees.length <= 1` (no
- * cross-tree collision is possible with a single source document) or when no
- * tree carries any vanish ids at all, keeping `generateManual`'s output
- * byte-identical to before this fix in the overwhelmingly common case.
+ * Gives every `SpecTree` in `trees` its own private, collision-checked
+ * namespace for the vanish-character-style ids its OWN captured objects
+ * reference (see this module's header). A no-op — every tree returned BY
+ * REFERENCE, the whole array returned BY REFERENCE — when no tree carries
+ * any vanish ids at all, keeping output byte-identical to before this fix in
+ * the overwhelmingly common case.
+ *
+ * Applied on EVERY generation path including a single tree, not just
+ * multi-tree `generateManual` (adversarial-review finding, #650). With raw
+ * ids, a source document whose vanish character style happens to be named
+ * after one dolanmiu/docx itself emits — `Hyperlink` is the realistic
+ * example — made the generator append a SECOND character style carrying the
+ * same `w:styleId`. Word then repairs or ambiguously resolves the duplicate,
+ * and the minted `w:vanish` can attach to the document's hyperlinks, hiding
+ * visible text that has nothing to do with the captured object. Namespacing
+ * unconditionally means a minted id always carries NAMESPACE_SEPARATOR and
+ * so can never equal a built-in id.
  */
 export function namespaceVanishTrees(trees: readonly SpecTree[]): readonly SpecTree[] {
-  if (trees.length <= 1) return trees;
+  const reserved = collectRemainingStyleIds(trees);
   let changed = false;
   const result = trees.map((tree, index) => {
     const ownIds = collectVanishCharacterStyleIds([tree]);
     if (ownIds.length === 0) return tree;
-    const renames = new Map(ownIds.map((id) => [id, namespacedId(id, index)] as const));
+    const renames = new Map(
+      ownIds.map((id) => [id, allocateNamespacedId(id, index, reserved)] as const)
+    );
     const newParts = rewriteNodes(tree.parts, renames);
     if (newParts === tree.parts) return tree;
     changed = true;
diff --git a/src/generator/object-vanish-styles.ts b/src/generator/object-vanish-styles.ts
index 8f520411..e3c44db8 100644
--- a/src/generator/object-vanish-styles.ts
+++ b/src/generator/object-vanish-styles.ts
@@ -47,15 +47,49 @@ export function collectVanishCharacterStyleIds(trees: readonly SpecTree[]): read
   return [...ids].sort((a, b) => a.localeCompare(b));
 }
 
+/**
+ * The separator `object-vanish-namespace.ts` uses to mint a tree-scoped
+ * character-style id. Defined HERE, beside the stub emitter that has to undo
+ * it for display, so the two cannot drift — and in this direction only,
+ * because the namespace module already imports this one (the reverse would
+ * be a cycle).
+ */
+export const NAMESPACE_SEPARATOR = '#specr-vanish-t';
+
+/**
+ * The ORIGINAL captured id behind a possibly-namespaced one, with any minted
+ * `#specr-vanish-t<n>` suffix stripped.
+ *
+ * Two callers need exactly this. It is the human-facing style NAME here: the
+ * `w:styleId` stays namespaced (that is what keeps it from colliding with a
+ * `docx` built-in such as `Hyperlink`, or with another source document's
+ * unrelated style of the same name), but a spec editor opening the file in
+ * Word should still see the style called what their source document called
+ * it, not a SpecR-internal token.
+ *
+ * It is also what makes namespacing IDEMPOTENT across repeated
+ * generate → re-parse → generate cycles. Re-parsing a generated document
+ * yields the NAMESPACED id as that tree's raw captured id; minting from it
+ * verbatim would append a second suffix on every cycle, growing the id
+ * without bound and breaking the byte-identical round-trip invariant. The
+ * namespace allocator therefore strips before it mints, so cycle N+1
+ * reproduces cycle N's id exactly.
+ */
+export function stripVanishNamespace(id: string): string {
+  const at = id.indexOf(NAMESPACE_SEPARATOR);
+  return at === -1 ? id : id.slice(0, at);
+}
+
 /**
  * Minimal `docx` character-style definitions for `styleIds` — one per id,
  * carrying only an enabled `w:vanish` (see this module's header for why
- * nothing else is reconstructed). `name` mirrors `id`: it is never read
- * back by SpecR's own parser (`styleId`, not `name`, is the correlation
- * key), only shown to a human opening the file in Word.
+ * nothing else is reconstructed). `id` is the exact (possibly namespaced)
+ * `w:styleId` the blob's own `w:rStyle` references — the only correlation
+ * key SpecR's parser reads back — while `name` is the de-namespaced
+ * original, which Word shows the human and nothing in SpecR consumes.
  */
 export function vanishCharacterStyleOptions(
   styleIds: readonly string[]
 ): readonly ICharacterStyleOptions[] {
-  return styleIds.map((id) => ({ id, name: id, run: { vanish: true } }));
+  return styleIds.map((id) => ({ id, name: stripVanishNamespace(id), run: { vanish: true } }));
 }
diff --git a/src/parser/docx/body-object-attach.test.ts b/src/parser/docx/body-object-attach.test.ts
index 134bfdd0..c82d2f22 100644
--- a/src/parser/docx/body-object-attach.test.ts
+++ b/src/parser/docx/body-object-attach.test.ts
@@ -144,7 +144,15 @@ describe('captureBodyObjectsForTree — object/objectText node shape', () => {
 // so a regression dropping or breaking the sort would go undetected.
 describe('captureBodyObjectsForTree — vanishCharStyleIds is sorted, not insertion order (#650)', () => {
   it('persists two vanish character-style ids sorted, even though styles.xml declares them in the REVERSE order', () => {
-    const body = table(row(cell(para('cell one'))));
+    // Both ids must be REFERENCED by this object's own blob: capture persists
+    // the referenced subset, not the document-wide set (adversarial-review
+    // finding, #650 — see referencedVanishCharStyleIds). A visible run keeps
+    // the cell from collapsing to empty text.
+    const cellPara =
+      '<w:p><w:r><w:t>cell one</w:t></w:r>' +
+      '<w:r><w:rPr><w:rStyle w:val="Zeta"/></w:rPr><w:t>zeta hidden</w:t></w:r>' +
+      '<w:r><w:rPr><w:rStyle w:val="HiddenChar"/></w:rPr><w:t>char hidden</w:t></w:r></w:p>';
+    const body = table(row(cell(cellPara)));
     const xml = makeDocXml(body);
 
     const attachment = captureBodyObjectsForTree(xml, TWO_VANISH_STYLES);
diff --git a/src/parser/docx/body-object-round-trip.test.ts b/src/parser/docx/body-object-round-trip.test.ts
index 92b1104a..2658c5b9 100644
--- a/src/parser/docx/body-object-round-trip.test.ts
+++ b/src/parser/docx/body-object-round-trip.test.ts
@@ -569,7 +569,12 @@ describe('body object round trip — parse -> generate -> re-parse (#517, WS2 ta
     // decision 1) — and, being fully text-empty once its one run is
     // excluded, it never gets an SDT anchor at all (no round-trip merge
     // locator can ever address hidden style-vanished content either).
-    expect(hiddenBefore).toContain('<w:rStyle w:val="HiddenChar"/>');
+    // The reference is NAMESPACED on the way out (adversarial-review finding,
+    // #650): the generator mints a tree-scoped `w:styleId` so its vanish stub
+    // can never collide with a docx built-in (`Hyperlink`, `Strong`, …) or
+    // with another source document's unrelated style of the same name. The
+    // style's human-facing `name` is de-namespaced back to "HiddenChar".
+    expect(hiddenBefore).toContain('<w:rStyle w:val="HiddenChar#specr-vanish-t0"/>');
     expect(hiddenBefore).not.toContain('<w:sdt');
     expect(hiddenBefore).not.toContain('w:tag');
 
@@ -583,7 +588,12 @@ describe('body object round trip — parse -> generate -> re-parse (#517, WS2 ta
     // style (generator/object-vanish-styles.ts), so the SECOND parse
     // resolves the SAME vanishCharStyleIds and the box stays excluded.
     expect(objectTextsOf(after[0] as SpecNode)).toEqual(['Visible box text']);
-    expect(after[0]?.meta.object?.vanishCharStyleIds).toEqual(['HiddenChar']);
+    // The re-parse resolves the id the REGENERATED document actually carries,
+    // i.e. the namespaced one. Re-namespacing is idempotent (the allocator
+    // strips any existing suffix before minting), which is what keeps the
+    // byte-identity assertion below true across repeated cycles instead of
+    // stacking a fresh suffix on every generation.
+    expect(after[0]?.meta.object?.vanishCharStyleIds).toEqual(['HiddenChar#specr-vanish-t0']);
 
     const docXmlAfter = await generatedDocumentXml(reparsedTree);
     const blocksAfter = txbxContentBlocks(docXmlAfter);
diff --git a/src/parser/docx/body-object-vanish.ts b/src/parser/docx/body-object-vanish.ts
index 33456fd1..b81c08ed 100644
--- a/src/parser/docx/body-object-vanish.ts
+++ b/src/parser/docx/body-object-vanish.ts
@@ -74,13 +74,77 @@ export function hasRunVanish(
   return resolveRunVanish(rPr, vanishCharStyleIds);
 }
 
-// The two OR'd vanish signals, split out of hasRunVanish purely to keep that
+// The two vanish signals, split out of hasRunVanish purely to keep that
 // function's cognitive complexity low — no behavior of its own. `getAttrVal`
 // applied to the w:rStyle node's own `:@` attrs mirrors isOnOffEnabled's
 // identical read of a w:vanish node's `:@` above.
+//
+// The signals are resolved as a TRI-STATE, not OR'd (adversarial-review
+// finding, #650). `w:vanish` on the run's own `w:rPr` is DIRECT formatting,
+// and ECMA-376 §17.7.3 makes direct formatting definitive for a toggle
+// property: it overrides whatever the referenced character style says. So
+//   - a direct `w:vanish` PRESENT and enabled  → hidden (never consult rStyle)
+//   - a direct `w:vanish` PRESENT and w:val=0  → VISIBLE, overriding an
+//     rStyle that is itself vanish — this is the whole point of writing it
+//   - no direct `w:vanish` at all              → fall through to the rStyle
+// OR-ing the two instead would make an explicit `<w:vanish w:val="0"/>`
+// unable to un-hide a run, suppressing text the author deliberately made
+// visible. That direction matters as much as the leak this predicate exists
+// to close: a missed suppression is a visible leak a test can catch, while a
+// wrong suppression is invisible data loss that merely LOOKS like correct
+// privacy behaviour. Over-suppression is not the safe side to err on.
+//
+// NOTE: document.ts's paragraph-tier `runIsVanish` still OR's the two signals
+// and therefore keeps the older behaviour. The divergence is deliberate and
+// narrow — this fix is scoped to the object tier's own NEW rStyle path rather
+// than silently changing long-shipped paragraph-tier classification in a
+// bugfix PR — and it is the object tier that is correct per ECMA-376.
 function resolveRunVanish(rPr: ObjectBlobNode, vanishCharStyleIds: ReadonlySet<string>): boolean {
-  if (directChildrenByTag(rPr, 'w:vanish').some(isOnOffEnabled)) return true;
+  const direct = directChildrenByTag(rPr, 'w:vanish');
+  if (direct.length > 0) return direct.some(isOnOffEnabled);
   const rStyleNode = directChildrenByTag(rPr, 'w:rStyle')[0];
   const rStyle = rStyleNode ? getAttrVal(rStyleNode[':@']) : '';
   return rStyle !== '' && vanishCharStyleIds.has(rStyle);
 }
+
+function collectRStyleIds(node: ObjectBlobNode, acc: Set<string>): void {
+  const tag = tagOf(node);
+  if (!tag) return;
+  if (tag === 'w:rStyle') {
+    const id = getAttrVal(node[':@']);
+    if (id !== '') acc.add(id);
+    return;
+  }
+  const value = node[tag];
+  if (!isBlobNodeArray(value)) return;
+  for (const child of value) collectRStyleIds(child, acc);
+}
+
+/**
+ * The subset of `vanishCharStyleIds` that `node`'s own subtree actually
+ * references through a `w:rPr>w:rStyle` (adversarial-review finding, #650).
+ *
+ * Persisting the document-wide set on EVERY captured object instead would be
+ * O(objects × vanish styles): each copy is materialized into that object's
+ * `object_data` JSONB, so it amplifies storage, worker transfer, and every
+ * API response, and the 50 MB DOCX input cap bounds only the sum of the
+ * inputs, never that product. Narrowing is also strictly SAFER, not merely
+ * smaller: the generator mints one `w:vanish` character-style stub per id it
+ * sees across the captured objects, so an id no blob ever references would
+ * otherwise mint a stub for nothing — needlessly widening the surface on
+ * which a minted id can collide with a style the document already uses for
+ * VISIBLE text.
+ *
+ * Narrowing costs no correctness: rewrite resolves runs only within this
+ * same blob, so any id that could ever match there is by definition
+ * referenced inside it and survives the intersection.
+ */
+export function referencedVanishCharStyleIds(
+  node: ObjectBlobNode,
+  vanishCharStyleIds: ReadonlySet<string>
+): ReadonlySet<string> {
+  if (vanishCharStyleIds.size === 0) return new Set();
+  const referenced = new Set<string>();
+  collectRStyleIds(node, referenced);
+  return new Set([...referenced].filter((id) => vanishCharStyleIds.has(id)));
+}
diff --git a/src/parser/docx/body-objects.test.ts b/src/parser/docx/body-objects.test.ts
index 77839e4b..e469756b 100644
--- a/src/parser/docx/body-objects.test.ts
+++ b/src/parser/docx/body-objects.test.ts
@@ -373,11 +373,30 @@ describe('hasRunVanish — rStyle-referenced character-style vanish (#650, captu
     expect(hasRunVanish(run, new Set(['HiddenChar']))).toBe(false);
   });
 
-  // Straight OR port of document.ts's runIsVanish (#650 spike): a resolved-off
-  // direct <w:vanish w:val="0"/> does NOT override a matching rStyle — the
-  // two signals combine via plain OR, never special-cased against each other.
-  it('a resolved-off direct <w:vanish w:val="0"/> does not override a matching rStyle — still hidden', () => {
+  // ORACLE CHANGE, deliberate (adversarial-review finding, #650). This test
+  // previously asserted the OPPOSITE — that a resolved-off direct
+  // `<w:vanish w:val="0"/>` does NOT override a matching rStyle, because the
+  // predicate was written as a straight OR port of document.ts's runIsVanish.
+  // That was wrong, and wrong in the dangerous direction: ECMA-376 §17.7.3
+  // makes DIRECT formatting definitive for a toggle property, so a run that
+  // explicitly writes `w:val="0"` is the author switching the style's vanish
+  // back OFF. OR-ing made that run invisible instead — over-suppression, i.e.
+  // silently dropping text the author deliberately made visible, which is the
+  // failure mode that produces no error and merely looks like correct privacy
+  // behaviour. The OR was a NEW path this branch introduced, so the fix lands
+  // here rather than becoming long-lived shipped behaviour.
+  it('a resolved-off direct <w:vanish w:val="0"/> OVERRIDES a matching rStyle — the run is VISIBLE', () => {
     const run = blobRun([blobVanish('0'), blobRStyle('HiddenChar')]);
+    expect(hasRunVanish(run, new Set(['HiddenChar']))).toBe(false);
+  });
+
+  // The ON side of the same tri-state, so the pair brackets it: an enabled
+  // direct w:vanish still hides regardless of the rStyle, and a run with NO
+  // direct w:vanish at all still falls through to the rStyle (above). Without
+  // this, resolveRunVanish could regress to "direct w:vanish always wins as
+  // false" and the override test would still pass.
+  it('an enabled direct <w:vanish/> still hides even when the rStyle is not a vanish style', () => {
+    const run = blobRun([blobVanish(), blobRStyle('PlainChar')]);
     expect(hasRunVanish(run, new Set(['HiddenChar']))).toBe(true);
   });
 
@@ -573,6 +592,41 @@ describe('extractBodyObjects — #650 rStyle-referenced character-style vanish t
     const result = extract(table(row(cell(para('cell text')))));
     expect(result.tableObjects[0]?.object.vanishCharStyleIds).toEqual(new Set());
   });
+
+  // Adversarial-review finding (#650): the captured set must be the ids THIS
+  // object's blob actually references, not the whole document's. Persisting
+  // the document-wide set on every object is O(objects × vanish styles) into
+  // JSONB, and — worse than the storage — it makes the generator mint a
+  // vanish style stub for an id no blob references, needlessly widening the
+  // surface on which a minted id can collide with a style the document uses
+  // for VISIBLE text.
+  it('an object whose blob references NO vanish style persists an empty set, even when the document defines one', () => {
+    const styleMap = charVanishStyleMap('HiddenChar');
+    const result = extract(table(row(cell(para('plain visible text')))), styleMap);
+
+    expect(styleMap.vanishCharStyleIds.has('HiddenChar')).toBe(true);
+    expect(result.tableObjects[0]?.object.vanishCharStyleIds).toEqual(new Set());
+  });
+
+  it('captures only the referenced subset when the document defines more vanish styles than the blob uses', () => {
+    const styleMap = buildStyleMap(
+      '<?xml version="1.0"?>' +
+        '<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">' +
+        '<w:style w:type="character" w:styleId="UsedChar"><w:name w:val="UsedChar"/>' +
+        '<w:rPr><w:vanish/></w:rPr></w:style>' +
+        '<w:style w:type="character" w:styleId="UnusedChar"><w:name w:val="UnusedChar"/>' +
+        '<w:rPr><w:vanish/></w:rPr></w:style></w:styles>'
+    );
+    const cellPara = rStyleRunPara('visible part ', 'hidden style part', 'UsedChar');
+    const result = extract(table(row(cell(cellPara))), styleMap);
+
+    expect(styleMap.vanishCharStyleIds).toEqual(new Set(['UsedChar', 'UnusedChar']));
+    // Only the referenced id is persisted — and suppression still works.
+    expect(result.tableObjects[0]?.object.vanishCharStyleIds).toEqual(new Set(['UsedChar']));
+    expect(result.tableObjects[0]?.object.interiorTexts.map((t) => t.text)).toEqual([
+      'visible part ',
+    ]);
+  });
 });
 
 describe('anchorInteriorParagraphs — hiddenSubtrees pass-through (#515 task 3)', () => {
diff --git a/src/parser/docx/body-objects.ts b/src/parser/docx/body-objects.ts
index 44d7b592..232bbc50 100644
--- a/src/parser/docx/body-objects.ts
+++ b/src/parser/docx/body-objects.ts
@@ -28,7 +28,7 @@ import { pairRunOrder } from './header-footer-run-order.js';
 import { wrapBlobParagraphWithAnchor } from './object-anchor.js';
 import { stripAlternateContentFallback } from './alternate-content.js';
 import { resolveHiddenTxbxContentNodes } from './body-text-box-visibility.js';
-import { hasRunVanish } from './body-object-vanish.js';
+import { hasRunVanish, referencedVanishCharStyleIds } from './body-object-vanish.js';
 import type { ClassifiedTopLevelTable } from './tables.js';
 import type { BodyDrawingClassification } from './body-drawings.js';
 import type { BodyOrder, BodyOrderTable } from './body-order.js';
@@ -357,7 +357,7 @@ function buildTableObject(
     ...dims,
     blob: [anchored.node],
     interiorTexts: anchored.interiorTexts,
-    vanishCharStyleIds: styleMap.vanishCharStyleIds,
+    vanishCharStyleIds: referencedVanishCharStyleIds(anchored.node, styleMap.vanishCharStyleIds),
   };
 }
 
@@ -547,7 +547,7 @@ function buildTextBoxObject(
     generation: classification.generation,
     blob: [anchored.node],
     interiorTexts: anchored.interiorTexts,
-    vanishCharStyleIds: styleMap.vanishCharStyleIds,
+    vanishCharStyleIds: referencedVanishCharStyleIds(anchored.node, styleMap.vanishCharStyleIds),
   };
 }
 

From 6e336b35c39b5af2f098719850b68622b9a7712a Mon Sep 17 00:00:00 2001
From: thewrz <adam@wrzeski.net>
Date: Wed, 5 Aug 2026 00:44:09 -0700
Subject: [PATCH 17/17] fix(parser,ast): close four CodeRabbit review findings
 (#650)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. body-object-attach.ts — vanishCharStyleIds sort was locale-dependent.
   `localeCompare` with no explicit locale follows the HOST's collation, so
   the same styles.xml persisted a different JSONB array order per machine,
   defeating the determinism the sort exists for. Demonstrated: sv-SE/da-DK
   order "ÄUml" last where en-US/de-DE/tr-TR order it second.

   NOT the reviewer's suggested bare `.sort()` — that trips this repo's
   `sonarjs/no-alphabetical-sort`, which requires an explicit comparator, so
   the proposed remedy would have failed CI. An explicit code-unit comparator
   satisfies the lint rule and cross-host reproducibility at once. Style IDs
   are opaque OOXML identifiers, never shown to a user, so locale-aware
   ordering has no value here.

2. body-object-vanish.ts — the doc comment above hasRunVanish still described
   the pre-fix OR semantics ("a resolved-off <w:vanish w:val=0> does not
   override a matching rStyle") while resolveRunVanish 40 lines below
   implements the opposite tri-state. Two adjacent comments asserting
   opposite contracts is how the OR logic gets "restored" later.

3. body-objects.ts — CapturedBodyObject.vanishCharStyleIds was documented as
   "carried forward unfiltered (the full resolved set)", but both assignment
   sites narrow it via referencedVanishCharStyleIds. The field doc is what a
   consumer reads before persisting; persisting the document-wide set would
   write every other object's hidden-style ids into this object's row.

4. openapi.yaml — expressed both new Zod cross-field rules structurally
   (OpenAPI 3.1 if/then): textBox forbids rows/columns, and meta.object is
   present on exactly the `object` node type. Note the reviewer's stated
   failure mode ("consumers can validate data the server rejects") does not
   apply — SpecNode/ObjectMeta appear only under `responses:`, never a
   requestBody, so the server is the producer and never emits the rejected
   shapes. Added anyway so consumers generating validators from the contract
   match the server, and because openapi.yaml is authoritative here.

Verified: ajv-compiled the ObjectMeta constraint and asserted all five
accept/reject cases behave as the Zod .check() does, including that the
additive vanishCharStyleIds field stays unaffected. pnpm lint clean,
3688/3688 unit, contract gate 21/21 against real Postgres.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 openapi.yaml                          | 37 +++++++++++++++++++++++++++
 src/parser/docx/body-object-attach.ts | 20 +++++++++++++--
 src/parser/docx/body-object-vanish.ts | 16 +++++++-----
 src/parser/docx/body-objects.ts       | 18 ++++++++-----
 4 files changed, 76 insertions(+), 15 deletions(-)

diff --git a/openapi.yaml b/openapi.yaml
index 0a13c5e3..d465e630 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -7992,6 +7992,27 @@ components:
     SpecNode:
       type: object
       required: [id, type, text, children, meta]
+      allOf:
+        # Cross-field invariant enforced by SpecNodeSchema's `.check()`
+        # (src/ast/spec-tree-schemas.ts, #650 Part B): `meta.object` is
+        # present on EXACTLY the `object` node type — an 'object' node is
+        # meaningless without its captured blob, and no other node type may
+        # carry one. A biconditional, hence the else-branch.
+        - if:
+            required: [type]
+            properties:
+              type:
+                const: object
+          then:
+            required: [meta]
+            properties:
+              meta:
+                required: [object]
+          else:
+            properties:
+              meta:
+                not:
+                  required: [object]
       properties:
         id:
           type: string
@@ -8113,6 +8134,22 @@ components:
         round-trips its OOXML byte-for-byte via `blob` rather than modeling
         its interior as CSI structure.
       required: [kind, floating, generation, blob]
+      allOf:
+        # Cross-field invariant enforced by ObjectMetaSchema's `.check()`
+        # (src/ast/object-schemas.ts, #516): rows/columns are table-grid
+        # dimensions, and a textBox has no grid to describe. Stated
+        # structurally so a consumer generating types/validators from this
+        # contract rejects the same shapes the server does.
+        - if:
+            required: [kind]
+            properties:
+              kind:
+                const: textBox
+          then:
+            not:
+              anyOf:
+                - required: [rows]
+                - required: [columns]
       properties:
         kind:
           type: string
diff --git a/src/parser/docx/body-object-attach.ts b/src/parser/docx/body-object-attach.ts
index 8a6c0442..d32d3932 100644
--- a/src/parser/docx/body-object-attach.ts
+++ b/src/parser/docx/body-object-attach.ts
@@ -35,11 +35,27 @@ function parseRawBodyParagraphs(documentXml: string): readonly Record<string, un
 
 // #650: vanishCharStyleIds is persisted as a SORTED array — never a Set — so
 // the JSONB column and fixture snapshots serialize deterministically
-// regardless of the StyleMap's own (unordered) iteration order. Omitted
+// regardless of the StyleMap's own (unordered) iteration order.
+//
+// byCodeUnit, NOT `localeCompare`: without an explicit locale the latter
+// follows the HOST's default collation, so the same styles.xml would persist
+// a different array order on a machine with a different locale — defeating
+// the determinism this sort exists for, in a value written to JSONB and
+// compared across environments. A bare `.sort()` would be equally
+// deterministic but trips the repo's `sonarjs/no-alphabetical-sort` rule,
+// which requires an explicit comparator; spelling the code-unit comparison
+// out satisfies both that rule and cross-host reproducibility. Style IDs are
+// opaque OOXML identifiers, never presented to a user, so locale-aware
+// alphabetical ordering has no value here. Omitted
 // entirely when empty, mirroring rows/columns' exactOptional-omission
 // convention above: an absent key and an empty array are fully
 // interchangeable (ObjectMetaSchema's own doc comment), so a table/text-box
 // with no style-vanished runs round-trips byte-identical to today's rows.
+const byCodeUnit = (a: string, b: string): number => {
+  if (a < b) return -1;
+  return a > b ? 1 : 0;
+};
+
 function toObjectMeta(captured: CapturedBodyObject): ObjectMeta {
   return {
     kind: captured.kind,
@@ -48,7 +64,7 @@ function toObjectMeta(captured: CapturedBodyObject): ObjectMeta {
     ...(captured.rows !== undefined ? { rows: captured.rows } : {}),
     ...(captured.columns !== undefined ? { columns: captured.columns } : {}),
     ...(captured.vanishCharStyleIds.size > 0
-      ? { vanishCharStyleIds: [...captured.vanishCharStyleIds].sort((a, b) => a.localeCompare(b)) }
+      ? { vanishCharStyleIds: [...captured.vanishCharStyleIds].sort(byCodeUnit) }
       : {}),
     blob: [...captured.blob],
   };
diff --git a/src/parser/docx/body-object-vanish.ts b/src/parser/docx/body-object-vanish.ts
index b81c08ed..627fc023 100644
--- a/src/parser/docx/body-object-vanish.ts
+++ b/src/parser/docx/body-object-vanish.ts
@@ -45,13 +45,17 @@ function isOnOffEnabled(node: ObjectBlobNode): boolean {
   return val !== '0' && val !== 'false' && val !== 'off';
 }
 
-// Straight OR port of document.ts's own `runIsVanish`: a run is hidden if
-// EITHER its own `w:rPr>w:vanish` is an enabled ST_OnOff toggle, OR its
-// `w:rPr>w:rStyle` names a character style present in the caller's
+// A run is hidden when its own `w:rPr>w:vanish` is an enabled ST_OnOff
+// toggle, or — ONLY when no direct `w:vanish` is present at all — when its
+// `w:rPr>w:rStyle` names a character style in the caller's
 // `vanishCharStyleIds` (the StyleMap's resolved set of character styles that
-// themselves carry an enabled `w:vanish`). No special-casing between the two
-// signals — a resolved-off direct `<w:vanish w:val="0"/>` does not override a
-// matching rStyle, mirroring document.ts's own behaviour exactly (#650).
+// themselves carry an enabled `w:vanish`).
+//
+// The two signals resolve as a TRI-STATE, NOT an OR: direct formatting wins,
+// so a resolved-off `<w:vanish w:val="0"/>` DOES override a matching rStyle.
+// This deliberately diverges from document.ts's paragraph-tier `runIsVanish`,
+// which still OR's them. See resolveRunVanish below for the ECMA-376 §17.7.3
+// rationale and why over-suppression is the worse failure direction (#650).
 // `vanishCharStyleIds` defaults to an empty set so a caller that has none to
 // offer (object-blob-edit.ts's rewriteFirstText before its own #650 wiring,
 // #648's extract.ts) keeps compiling and behaving byte-for-byte unchanged.
diff --git a/src/parser/docx/body-objects.ts b/src/parser/docx/body-objects.ts
index 232bbc50..1ee57ebe 100644
--- a/src/parser/docx/body-objects.ts
+++ b/src/parser/docx/body-objects.ts
@@ -51,13 +51,17 @@ export interface CapturedObjectText {
  * children). `blob` already carries every interior paragraph's SDT anchor —
  * it is the exact node tree the parent `object.meta.object.blob` will store.
  *
- * `vanishCharStyleIds` (#650) is the SAME `StyleMap.vanishCharStyleIds` set
- * used to decide which interior runs `collectText` skipped during capture —
- * carried forward unfiltered (the full resolved set, not a subset narrowed to
- * what this particular object actually referenced; simplicity, zero
- * correctness cost) so `body-object-attach.ts`'s `toObjectMeta` can persist
- * it and the edit rewrite path (`object-text-edit.ts`) can rebuild the same
- * `ReadonlySet` at write time without re-parsing `styles.xml`.
+ * `vanishCharStyleIds` (#650) is drawn from the same
+ * `StyleMap.vanishCharStyleIds` set used to decide which interior runs
+ * `collectText` skipped during capture, but is NARROWED to the styles this
+ * particular object's own blob actually references — see
+ * `referencedVanishCharStyleIds` (body-object-vanish.ts), applied at both
+ * assignment sites (`buildTableObject`, `buildTextBoxObject`). Persisting the
+ * full document-wide set would write every other object's hidden-style ids
+ * into this object's row. `body-object-attach.ts`'s `toObjectMeta` persists
+ * the narrowed set, and the edit rewrite path (`object-text-edit.ts`)
+ * rebuilds the same `ReadonlySet` at write time without re-parsing
+ * `styles.xml`.
  */
 export interface CapturedBodyObject {
   readonly kind: ObjectKind;