R6A-R4-R6 four-language qualitative appendix semantic identity and final DOCX layout gate

core/production_guard.py

@@ -11,6 +11,8 @@ from dataclasses import dataclass
 from typing import Any
 
 from docx import Document
+from docx.enum.section import WD_ORIENT
+from docx.oxml.ns import qn
 
 from utils.docx_builder import DocxBuildError, text_to_docx
 
@@ -54,6 +56,55 @@ def validate_docx_bytes(data: bytes, *, minimum_paragraphs: int = 8) -> None:
         )
 
 
+def validate_qualitative_appendix_docx_layout(data: bytes, *, label: str = "DOCX") -> None:
+    """Fail closed if the qualitative evidence Appendix lost its layout contract.
+
+    Validation is intentionally language-blind.  The renderer marks the
+    semantic Appendix table through structure + ASQ mode, while this final gate
+    verifies only the resulting OOXML layout signature.
+    """
+    try:
+        document = Document(io.BytesIO(data))
+    except Exception as exc:
+        raise OutputValidationError(f"{label} qualitative layout cannot be inspected: {exc}") from exc
+
+    orientations = [section.orientation for section in document.sections]
+    if not any(value == WD_ORIENT.LANDSCAPE for value in orientations):
+        raise OutputValidationError(f"{label} qualitative Appendix did not enter landscape orientation.")
+    if not orientations or orientations[-1] != WD_ORIENT.PORTRAIT:
+        raise OutputValidationError(f"{label} qualitative Appendix did not return to portrait orientation.")
+
+    candidates = []
+    for table in document.tables:
+        if len(table.columns) != 6:
+            continue
+        layout = table._tbl.tblPr.find(qn("w:tblLayout"))
+        if layout is None or layout.get(qn("w:type")) != "fixed":
+            continue
+        candidates.append(table)
+    if len(candidates) != 1:
+        raise OutputValidationError(
+            f"{label} qualitative Appendix expected exactly one fixed six-column evidence table; found {len(candidates)}."
+        )
+
+    table = candidates[0]
+    grid_cols = list(table._tbl.tblGrid.gridCol_lst)
+    widths = [int(col.get(qn("w:w")) or 0) for col in grid_cols]
+    if len(widths) != 6 or widths[-1] != max(widths) or widths[-1] <= widths[0] * 2:
+        raise OutputValidationError(
+            f"{label} qualitative Appendix representative-quote column lost its dominant width."
+        )
+    if not table.rows:
+        raise OutputValidationError(f"{label} qualitative Appendix evidence table has no rows.")
+
+    header_pr = table.rows[0]._tr.get_or_add_trPr()
+    if header_pr.find(qn("w:tblHeader")) is None:
+        raise OutputValidationError(f"{label} qualitative Appendix header is not configured to repeat across pages.")
+    for row in table.rows:
+        if row._tr.get_or_add_trPr().find(qn("w:cantSplit")) is None:
+            raise OutputValidationError(f"{label} qualitative Appendix contains a row that may split across pages.")
+
+
 
 _REFERENCE_HEADING_RE = re.compile(
     r"(?im)^#\s+(?:References|参考文献|Литература|Пайдаланылған әдебиеттер)\s*$"
@@ -469,13 +520,21 @@ def build_validated_package(
     validate_markdown_manuscript(english_markdown, language_name="English")
     validate_markdown_manuscript(translated_markdown, language_name="Target-language")
 
+    qualitative_mode = str(mode or "").strip().casefold() == "asq"
     try:
-        english_docx = text_to_docx(english_markdown).getvalue()
-        translated_docx = text_to_docx(translated_markdown).getvalue()
+        english_docx = text_to_docx(
+            english_markdown, qualitative_appendix=qualitative_mode
+        ).getvalue()
+        translated_docx = text_to_docx(
+            translated_markdown, qualitative_appendix=qualitative_mode
+        ).getvalue()
     except DocxBuildError as exc:
         raise OutputValidationError(str(exc)) from exc
     validate_docx_bytes(english_docx)
     validate_docx_bytes(translated_docx)
+    if qualitative_mode:
+        validate_qualitative_appendix_docx_layout(english_docx, label="English DOCX")
+        validate_qualitative_appendix_docx_layout(translated_docx, label="Target-language DOCX")
 
     entries: dict[str, bytes] = {
         english_filename: english_docx,
@@ -506,7 +565,13 @@ def build_validated_package(
                     f"ZIP file list mismatch: actual={sorted(names)}, expected={sorted(required)}"
                 )
             for name in (english_filename, translated_filename):
-                validate_docx_bytes(archive.read(name))
+                archived_docx = archive.read(name)
+                validate_docx_bytes(archived_docx)
+                if qualitative_mode:
+                    validate_qualitative_appendix_docx_layout(
+                        archived_docx,
+                        label="Archived English DOCX" if name == english_filename else "Archived target-language DOCX",
+                    )
     except OutputValidationError:
         raise
     except Exception as exc:

utils/docx_builder.py

@@ -30,12 +30,56 @@ def _normalize_heading_label(text):
     return value.rstrip(" :：")
 
 
+def _table_column_count(token):
+    if not isinstance(token, dict) or token.get("type") != "table":
+        return 0
+    for child in token.get("children") or []:
+        if isinstance(child, dict) and child.get("type") == "table_head":
+            return len(child.get("children") or [])
+    return 0
+
+
+def _qualitative_appendix_table_ordinal(markdown_content):
+    """Return the semantic evidence-table ordinal for an ASQ manuscript.
+
+    The qualitative Appendix is a structural business object: the unique
+    six-column Markdown table between the penultimate and final level-1
+    headings (Appendix and References in the frozen manuscript architecture).
+    Reader-facing header wording is intentionally irrelevant so EN/ZH/RU/KK
+    translations retain the same table identity.
+    """
+    tokens = mistune.create_markdown(renderer="ast", plugins=["table"])(str(markdown_content or ""))
+    h1_positions = [
+        index for index, token in enumerate(tokens)
+        if isinstance(token, dict)
+        and token.get("type") == "heading"
+        and int((token.get("attrs") or {}).get("level") or 0) == 1
+    ]
+    if len(h1_positions) < 2:
+        return None
+    appendix_start, references_start = h1_positions[-2], h1_positions[-1]
+    table_ordinal = -1
+    candidates = []
+    for index, token in enumerate(tokens):
+        if not isinstance(token, dict) or token.get("type") != "table":
+            continue
+        table_ordinal += 1
+        if appendix_start < index < references_start and _table_column_count(token) == 6:
+            candidates.append(table_ordinal)
+    if len(candidates) != 1:
+        return None
+    return candidates[0]
+
+
 class DocxRenderer(mistune.HTMLRenderer):
-    def __init__(self):
+    def __init__(self, *, qualitative_appendix_table_ordinal=None, semantic_qualitative_appendix=False):
         super().__init__()
         self.doc = Document()
         self.h_counters = [0] * 6
         self.is_first_h1 = True
+        self.table_ordinal = -1
+        self.qualitative_appendix_table_ordinal = qualitative_appendix_table_ordinal
+        self.semantic_qualitative_appendix = bool(semantic_qualitative_appendix)
         try:
             style = self.doc.styles['Normal']
             style.font.name = APP_CONFIG["docx_styles"]["font_name"]
@@ -134,12 +178,21 @@ class DocxRenderer(mistune.HTMLRenderer):
         if max_cols == 0:
             return ''
 
+        self.table_ordinal += 1
         header_labels = [cell.get_text(strip=True) for cell in rows[0].find_all(['td', 'th'])]
         qualitative_headers = [
             'Higher-order Theme', 'Empirical Concept', 'Process Stage',
             'Case/Actor', 'Evidence Role', 'Representative Quote',
         ]
-        qualitative_evidence_table = header_labels == qualitative_headers
+        if self.semantic_qualitative_appendix:
+            qualitative_evidence_table = (
+                self.qualitative_appendix_table_ordinal is not None
+                and self.table_ordinal == self.qualitative_appendix_table_ordinal
+            )
+        else:
+            # Legacy direct-render compatibility. Production ASQ packaging uses
+            # the semantic structural identity above and never depends on labels.
+            qualitative_evidence_table = header_labels == qualitative_headers
 
         if qualitative_evidence_table:
             previous = self.doc.sections[-1]
@@ -206,10 +259,26 @@ class DocxRenderer(mistune.HTMLRenderer):
         self.doc.add_paragraph(f"[Image: {alt or src}]")
         return ''
 
-def text_to_docx(markdown_content):
-    """Render markdown strictly; never disguise renderer failures as success."""
+def text_to_docx(markdown_content, *, qualitative_appendix=False):
+    """Render markdown strictly; never disguise renderer failures as success.
+
+    ``qualitative_appendix=True`` is an internal semantic contract supplied by
+    ASQ packaging. It binds the deterministic evidence table by manuscript
+    structure rather than reader-facing English/Chinese/Russian/Kazakh labels.
+    """
     try:
-        renderer = DocxRenderer()
+        semantic_qualitative_appendix = bool(qualitative_appendix)
+        qualitative_table_ordinal = None
+        if semantic_qualitative_appendix:
+            qualitative_table_ordinal = _qualitative_appendix_table_ordinal(markdown_content)
+            if qualitative_table_ordinal is None:
+                raise DocxBuildError(
+                    "Qualitative Appendix semantic table identity is missing or ambiguous."
+                )
+        renderer = DocxRenderer(
+            qualitative_appendix_table_ordinal=qualitative_table_ordinal,
+            semantic_qualitative_appendix=semantic_qualitative_appendix,
+        )
         mistune.create_markdown(renderer=renderer, plugins=['table'])(str(markdown_content or ''))
         doc = renderer.doc
         if not doc.paragraphs and not doc.tables: