fix(xsd): scope local elements per-owner; link xsd-builtin symbols to profile; drop em dash

Three review-flagged correctness gaps before flipping ENABLE_OOXML_TOOLS.

P1 - Local element symbols collapsed across complexTypes.
  Inline <xsd:element name="X" type="..."/> declared inside two different
  complexTypes was deduped under (vocabulary, name, kind), keeping only the
  first-seen type_ref. Real WML hits this on tblGrid alone: declared as
  CT_TblGridBase inside CT_TblGridChange and as CT_TblGrid inside CT_Tbl.
  ooxml_children("w:tblGrid") would have followed CT_TblGridBase and missed
  the CT_TblGrid children.

  Migration 0004 adds xsd_symbols.parent_symbol_id (nullable) and replaces
  the 3-tuple unique with a 4-tuple UNIQUE NULLS NOT DISTINCT (vocab,
  local_name, kind, parent_symbol_id). Top-level decls keep parent NULL and
  still collide on name; local decls are scoped to their owner. ingest.ts
  passes the owning symbol id when upserting local element symbols.

P2 - xsd-builtin symbols had no profile membership.
  The on-demand inheritance pass created xsd:string / xsd:boolean / etc.
  via upsertSymbol but never called linkSymbolToProfile, so lookupSymbol
  (which JOINs xsd_symbol_profiles) returned null. Following an element's
  type_ref into a W3C built-in silently failed. Now also ensure the
  xs/xsd namespace exists and link the built-in symbol into the target
  profile.

P3 - Em dash in code comment.
  scripts/ingest-xsd/qname.ts line 12 used "—". Replaced with "-".

Tests:
  - New "local element symbols are scoped per-owner (no cross-CT collapse)"
    against a CT_OuterA / CT_OuterB fixture mirroring the WML tblGrid
    pattern: each `shared` element resolves to its own symbol with the
    correct per-owner type_ref.
  - New "xsd-builtin symbols have profile membership" verifies
    lookupSymbolByTypeRef succeeds for {...XMLSchema}string.
  - Existing fixture and WML smoke counts adjusted.

41 / 0 across db / ingest / mcp-server.

Author: caiopizzol

db/migrations/0004_local_element_scoping.sql

@@ -0,0 +1,49 @@
+-- Phase 4 review fix: scope local element symbols by their owner.
+--
+-- Before this migration, an inline <xsd:element name="X" type="..."/> declared
+-- inside two different complexTypes/groups collapsed to a single symbol keyed
+-- on (vocabulary_id, local_name, kind). The first-seen type_ref won and the
+-- later one was silently dropped, so e.g. WML's `tblGrid` (CT_TblGridBase
+-- inside CT_TblGridChange vs CT_TblGrid inside CT_Tbl) gave a wrong answer
+-- for ooxml_children("w:tblGrid").
+--
+-- Fix: add parent_symbol_id to xsd_symbols and include it in the canonical key
+-- with NULLS NOT DISTINCT so two top-level declarations (parent NULL) still
+-- collide while local declarations are scoped per-owner.
+--
+-- Idempotent.
+
+ALTER TABLE xsd_symbols
+	ADD COLUMN IF NOT EXISTS parent_symbol_id INT REFERENCES xsd_symbols(id) ON DELETE CASCADE;
+
+DO $$
+DECLARE cname TEXT;
+BEGIN
+	-- Drop the auto-named 3-tuple unique constraint, regardless of what postgres
+	-- ended up calling it.
+	SELECT conname INTO cname
+	FROM pg_constraint
+	WHERE conrelid = 'xsd_symbols'::regclass
+	  AND contype = 'u'
+	  AND conkey = (
+	    SELECT array_agg(attnum ORDER BY attnum)
+	    FROM pg_attribute
+	    WHERE attrelid = 'xsd_symbols'::regclass
+	      AND attname IN ('vocabulary_id', 'local_name', 'kind')
+	  );
+	IF cname IS NOT NULL THEN
+		EXECUTE 'ALTER TABLE xsd_symbols DROP CONSTRAINT ' || quote_ident(cname);
+	END IF;
+
+	IF NOT EXISTS (
+		SELECT 1 FROM pg_constraint
+		WHERE conname = 'xsd_symbols_canonical_key'
+		  AND conrelid = 'xsd_symbols'::regclass
+	) THEN
+		ALTER TABLE xsd_symbols
+			ADD CONSTRAINT xsd_symbols_canonical_key
+			UNIQUE NULLS NOT DISTINCT (vocabulary_id, local_name, kind, parent_symbol_id);
+	END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS idx_xsd_symbols_parent ON xsd_symbols(parent_symbol_id);

db/schema.sql

@@ -67,15 +67,22 @@ CREATE TABLE xsd_namespaces (
 -- type_ref holds the Clark-style {namespace}localName for elements and attributes
 -- that declare a @type. NULL for complexType/simpleType/group/attributeGroup.
 -- Phase 4 lookups follow type_ref to resolve element -> type when reading children.
+--
+-- parent_symbol_id is NULL for top-level declarations and set to the owning
+-- type/group symbol for inline (local) element declarations. The canonical
+-- key is 4-tuple with NULLS NOT DISTINCT so top-level decls still collide on
+-- name while local decls remain scoped per-owner.
 CREATE TABLE xsd_symbols (
   id SERIAL PRIMARY KEY,
   vocabulary_id TEXT NOT NULL,
   local_name TEXT NOT NULL,
   kind TEXT NOT NULL,
   type_ref TEXT,
+  parent_symbol_id INT REFERENCES xsd_symbols(id) ON DELETE CASCADE,
   payload JSONB DEFAULT '{}'::jsonb,
   created_at TIMESTAMPTZ DEFAULT NOW(),
-  UNIQUE (vocabulary_id, local_name, kind)
+  CONSTRAINT xsd_symbols_canonical_key
+    UNIQUE NULLS NOT DISTINCT (vocabulary_id, local_name, kind, parent_symbol_id)
 );
 
 CREATE TABLE xsd_symbol_profiles (
@@ -181,6 +188,7 @@ CREATE TABLE behavior_notes (
 );
 
 CREATE INDEX idx_xsd_symbols_lookup ON xsd_symbols(vocabulary_id, local_name, kind);
+CREATE INDEX idx_xsd_symbols_parent ON xsd_symbols(parent_symbol_id);
 CREATE INDEX idx_xsd_child_edges_parent ON xsd_child_edges(parent_symbol_id);
 CREATE INDEX idx_xsd_child_edges_compositor ON xsd_child_edges(compositor_id);
 CREATE INDEX idx_xsd_attr_edges_symbol ON xsd_attr_edges(symbol_id);

scripts/ingest-xsd/ingest.ts

@@ -192,6 +192,16 @@ export async function ingestSchemaSet(opts: IngestSchemaSetOptions): Promise<Ing
 					baseId = id;
 					if (inserted) stats.symbolsInserted++;
 					else stats.symbolsExisting++;
+					// Link to a profile so ooxml_lookup_type / lookupSymbolByTypeRef can
+					// follow type_refs into the W3C XSD namespace.
+					let xsdNsId = namespaceIds.get(baseQ.namespace);
+					if (xsdNsId == null) {
+						xsdNsId = await ensureNamespace(sql, baseQ.namespace);
+						namespaceIds.set(baseQ.namespace, xsdNsId);
+						stats.namespacesEnsured++;
+					}
+					const linked = await linkSymbolToProfile(sql, id, profileId, xsdNsId, sourceId);
+					if (linked) stats.profileMembershipsInserted++;
 				}
 				if (baseId == null) {
 					stats.inheritanceUnresolved++;
@@ -473,7 +483,15 @@ async function handleElement(
 			const r = resolveQNameAttr(a.type, ctx.prefixMap, ctx.ownerDecl.namespace);
 			typeRef = r.resolved ? `{${r.qname.namespace}}${r.qname.localName}` : a.type;
 		}
-		const key = symbolKey(ctx.ownerDecl.vocabularyId, a.name, "element");
+		// Local elements are scoped per-owner: the same name in two different
+		// complexTypes is not the same symbol (e.g. WML's tblGrid is
+		// CT_TblGridBase inside CT_TblGridChange but CT_TblGrid inside CT_Tbl).
+		const key = symbolKey(
+			ctx.ownerDecl.vocabularyId,
+			a.name,
+			"element",
+			ctx.ownerSymbolId,
+		);
 		let id = ctx.symbolIds.get(key);
 		if (id == null) {
 			const res = await upsertSymbol(
@@ -482,6 +500,7 @@ async function handleElement(
 				a.name,
 				"element",
 				typeRef,
+				ctx.ownerSymbolId,
 			);
 			ctx.symbolIds.set(key, res.id);
 			if (res.inserted) {
@@ -611,11 +630,12 @@ async function upsertSymbol(
 	localName: string,
 	kind: string,
 	typeRef: string | null = null,
+	parentSymbolId: number | null = null,
 ): Promise<{ id: number; inserted: boolean }> {
 	const [row] = await sql`
-		INSERT INTO xsd_symbols (vocabulary_id, local_name, kind, type_ref)
-		VALUES (${vocabularyId}, ${localName}, ${kind}, ${typeRef})
-		ON CONFLICT (vocabulary_id, local_name, kind) DO UPDATE
+		INSERT INTO xsd_symbols (vocabulary_id, local_name, kind, type_ref, parent_symbol_id)
+		VALUES (${vocabularyId}, ${localName}, ${kind}, ${typeRef}, ${parentSymbolId})
+		ON CONFLICT ON CONSTRAINT xsd_symbols_canonical_key DO UPDATE
 			SET type_ref = COALESCE(EXCLUDED.type_ref, xsd_symbols.type_ref)
 		RETURNING id, (xmax = 0) AS inserted
 	`;
@@ -916,8 +936,8 @@ function stripPrefixLocal(tag: string | null): string | null {
 	return colon < 0 ? tag : tag.slice(colon + 1);
 }
 
-function symbolKey(vocab: string, local: string, kind: string): string {
-	return `${vocab}|${local}|${kind}`;
+function symbolKey(vocab: string, local: string, kind: string, parentId: number | null = null): string {
+	return `${vocab}|${local}|${kind}|${parentId ?? ""}`;
 }
 
 // --- CLI -----------------------------------------------------------------

scripts/ingest-xsd/qname.ts

@@ -9,7 +9,7 @@
  *
  * 2. QName-valued attributes (ref, type, base, substitutionGroup, etc.) hold a
  *    "prefix:localName" string. Resolution uses the document's xmlns:* declarations.
- *    `resolveQNameAttr` returns either a resolved tuple or "unresolved" — we never
+ *    `resolveQNameAttr` returns either a resolved tuple or "unresolved" - we never
  *    invent a namespace for an unknown prefix.
  */
 

tests/ingest-xsd/fixtures/main.xsd

@@ -95,5 +95,18 @@
   <xsd:complexType name="CT_NestedAttrUser">
     <xsd:attributeGroup ref="AG_Outer"/>
   </xsd:complexType>
+  <!-- Mirrors the WML tblGrid case: two complexTypes both declare a local
+       element with the same name but DIFFERENT types. They must not collapse
+       into a single symbol. -->
+  <xsd:complexType name="CT_OuterA">
+    <xsd:sequence>
+      <xsd:element name="shared" type="ST_Jc"/>
+    </xsd:sequence>
+  </xsd:complexType>
+  <xsd:complexType name="CT_OuterB">
+    <xsd:sequence>
+      <xsd:element name="shared" type="xsd:string"/>
+    </xsd:sequence>
+  </xsd:complexType>
   <xsd:element name="document" type="CT_Empty"/>
 </xsd:schema>

tests/ingest-xsd/ingest.test.ts

@@ -223,12 +223,17 @@ test("ingest writes compositors and child edges for nested content models", asyn
 	//   CT_BaseWithChildren: sequence -> [ alpha, beta ]
 	//   CT_DerivedExtended: complexContent/extension -> sequence -> [ gamma ]
 	//   CT_NestedOrder:    sequence -> [ head, choice -> [ branchA, branchB ], tail ]
-	// Compositors: CT_Para(1) + CT_Body(2) + EG_PContent(1) + Base(1) + Derived(1) + Nested(2) = 8
-	expect(stats.compositorsInserted).toBe(8);
+	// Compositors: CT_Para(1) + CT_Body(2) + EG_PContent(1) + Base(1) + Derived(1) +
+	// Nested(2) + OuterA(1) + OuterB(1) = 10
+	expect(stats.compositorsInserted).toBe(10);
 	expect(stats.groupRefsInserted).toBe(1);
-	// Local element names (deduped per vocab): text, break, r, alpha, beta, gamma,
-	// head, branchA, branchB, tail = 10.
-	expect(stats.localElementsCreated).toBe(10);
+	// Local element symbols are scoped per-owner now, so the two `shared` decls
+	// in CT_OuterA and CT_OuterB count separately.
+	// Per-owner locals: text(CT_Para), break(CT_Body), r(EG_PContent),
+	// alpha+beta(CT_BaseWithChildren), gamma(CT_DerivedExtended),
+	// head+branchA+branchB+tail(CT_NestedOrder), shared(CT_OuterA),
+	// shared(CT_OuterB) = 12.
+	expect(stats.localElementsCreated).toBe(12);
 	expect(stats.childEdgesUnresolved).toBe(0);
 	expect(stats.groupRefsUnresolved).toBe(0);
 

tests/ingest-xsd/parse-schema.test.ts

@@ -85,10 +85,10 @@ test("declarationsByQName indexes all top-level declarations across documents",
 	const set = await parseSchemaSet({ schemaDir: FIXTURES_DIR, entrypoints: ["main.xsd"] });
 
 	const counts = countByKind(set.declarationsByQName);
-	// main.xsd: 1 element, 11 complexType, 1 simpleType, 1 group, 3 attributeGroup
+	// main.xsd: 1 element, 13 complexType, 1 simpleType, 1 group, 3 attributeGroup
 	// shared.xsd: 2 simpleType, 1 attribute
 	expect(counts.element).toBe(1);
-	expect(counts.complexType).toBe(11);
+	expect(counts.complexType).toBe(13);
 	expect(counts.simpleType).toBe(3);
 	expect(counts.group).toBe(1);
 	expect(counts.attributeGroup).toBe(3);

tests/mcp-server/ooxml-queries.test.ts

@@ -242,6 +242,51 @@ test("getChildren: nested compositor flatten preserves document order (CT_Nested
 	expect(branchA?.compositorPath).toEqual(["sequence(1..1)", "choice(0..unbounded)"]);
 });
 
+test("local element symbols are scoped per-owner (no cross-CT collapse)", async () => {
+	// Mirrors the WML tblGrid case (CT_TblGridBase inside CT_TblGridChange vs
+	// CT_TblGrid inside CT_Tbl). CT_OuterA / CT_OuterB both declare an inline
+	// 'shared' element but with different @type. They must produce distinct
+	// per-parent symbols, each carrying its own type_ref.
+	const ctA = await lookupType(db.sql, WML_NS, "CT_OuterA", "transitional");
+	const ctB = await lookupType(db.sql, WML_NS, "CT_OuterB", "transitional");
+	if (!ctA || !ctB) throw new Error("CT_OuterA / CT_OuterB not found");
+
+	const aChildren = await getChildren(db.sql, ctA.id, "transitional");
+	const bChildren = await getChildren(db.sql, ctB.id, "transitional");
+	expect(aChildren).toHaveLength(1);
+	expect(bChildren).toHaveLength(1);
+	expect(aChildren[0].localName).toBe("shared");
+	expect(bChildren[0].localName).toBe("shared");
+
+	// The two `shared` symbols carry different type_refs.
+	const sharedSymbols = await db.sql`
+		SELECT s.id, s.type_ref, s.parent_symbol_id, parent.local_name AS parent_name
+		FROM xsd_symbols s
+		JOIN xsd_symbols parent ON parent.id = s.parent_symbol_id
+		WHERE s.local_name = 'shared' AND s.kind = 'element'
+		ORDER BY parent.local_name
+	`;
+	expect(sharedSymbols).toHaveLength(2);
+	expect(sharedSymbols[0].parent_name).toBe("CT_OuterA");
+	expect(sharedSymbols[0].type_ref).toBe(`{${WML_NS}}ST_Jc`);
+	expect(sharedSymbols[1].parent_name).toBe("CT_OuterB");
+	expect(sharedSymbols[1].type_ref).toBe("{http://www.w3.org/2001/XMLSchema}string");
+});
+
+test("xsd-builtin symbols have profile membership (lookupSymbolByTypeRef can follow xsd:string)", async () => {
+	// Built-ins like xsd:string are auto-created during inheritance resolution and
+	// must be linked to xsd_symbol_profiles, otherwise ooxml_lookup_type for
+	// 'xsd:string' and lookupSymbolByTypeRef for {...XMLSchema}string return null.
+	const t = await lookupSymbolByTypeRef(
+		db.sql,
+		"{http://www.w3.org/2001/XMLSchema}string",
+		"transitional",
+	);
+	expect(t).not.toBeNull();
+	expect(t?.localName).toBe("string");
+	expect(t?.vocabularyId).toBe("xsd-builtin");
+});
+
 test("getAttributes: nested attributeGroup chain unfolds (CT_NestedAttrUser -> innerAttr + outerAttr)", async () => {
 	const ct = await lookupType(db.sql, WML_NS, "CT_NestedAttrUser", "transitional");
 	if (!ct) throw new Error("CT_NestedAttrUser not found");