@shundoo-ai/dsh-cosmic 1.0.17 → 1.0.18

package/skills/cosmic-build/skills/cosmic-design/scripts/data_model_contract.py

@@ -1,1301 +0,0 @@
-#!/usr/bin/env python3
-"""Dependency-free dataModel authoring/output contract validation.
-
-The JSON Schema files are the public contracts. This module mirrors the
-high-value constraints at runtime so app-build does not require jsonschema in
-customer environments. Every issue is stable and machine-readable.
-"""
-from __future__ import annotations
-
-import json
-import re
-from dataclasses import asdict, dataclass
-from pathlib import Path
-from typing import Any, Collection
-
-
-SCRIPT_DIR = Path(__file__).resolve().parent
-ROOT = SCRIPT_DIR.parents[2]
-POLICY_PATH = ROOT / "schemas" / "data-model-error-policy.json"
-
-IDENTIFIER_RE = re.compile(r"^[a-z][a-z0-9_]*$")
-ENTITY_IDENTIFIER_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]*$")
-MAX_PHYSICAL_TABLE_NAME = 25
-MAX_PHYSICAL_COLUMN_NAME = 24
-MAX_LOGICAL_ENTITY_NAME = 20
-MAX_LOGICAL_FIELD_NAME = 24
-MAIN_ENTITY_TYPES = frozenset({"BillEntity", "BaseEntity", "MainEntity"})
-DIRECT_ENTRY_TYPES = frozenset({"EntryEntity", "TreeEntryEntity"})
-SUBENTRY_TYPES = frozenset({"SubEntryEntity", "TreeSubEntryEntity"})
-CHILD_ENTITY_TYPES = frozenset(set(DIRECT_ENTRY_TYPES) | set(SUBENTRY_TYPES))
-ENTITY_TYPES = frozenset(set(MAIN_ENTITY_TYPES) | set(CHILD_ENTITY_TYPES))
-BASEDATA_TYPES = frozenset({"BasedataField", "MulBasedataField", "GroupField"})
-REF_BILL_TYPES = frozenset({"RefBillField"})
-COMBO_TYPES = frozenset(
-    {"ComboField", "MulComboField", "CheckBoxGroupField", "RadioOptGroupField"}
-)
-WRAPPED_TYPES = frozenset(
-    {
-        "UserField",
-        "OrgField",
-        "SupplierField",
-        "CustomerField",
-        "CostCenterField",
-        "ProdcutLineField",
-        "CityField",
-        "HRAdminOrgField",
-        "HRMulAdminOrgField",
-        "HRPositionField",
-        "HRMulPositionField",
-        "ProfitCenterField",
-    }
-)
-REFERENCE_TYPES = frozenset(
-    set(BASEDATA_TYPES)
-    | set(WRAPPED_TYPES)
-    | {
-        "MaterielField",
-        "UnitField",
-        "CurrencyField",
-        "AssistantField",
-        "RefBillField",
-        "AccountField",
-        "RequireTypeField",
-    }
-)
-BASEDATA_PROPERTY_SOURCE_TYPES = frozenset(
-    (set(REFERENCE_TYPES) - set(REF_BILL_TYPES))
-    | {
-        "GroupField",
-        "ParentBasedataField",
-        "ItemClassField",
-        "ItemClassTypeField",
-    }
-)
-FORBIDDEN_ENTITY_KEYS = frozenset(
-    {"entityKey", "tableName", "templateNumber", "operationKey", "id"}
-)
-FORBIDDEN_FIELD_KEYS = frozenset(
-    {
-        "fieldKey",
-        "columnName",
-        "tableName",
-        "operationKey",
-        "basedataHint",
-        "BillEntityId",
-        "refBillTargetNumber",
-        "id",
-    }
-)
-POST_BUILD_FIELD_PROPERTY_KEYS = frozenset(
-    {"defaultValue", "hidden", "precision", "scale", "maxLength"}
-)
-
-
-@dataclass(frozen=True)
-class ContractIssue:
-    code: str
-    path: str
-    message: str
-    retryAdvice: str = "fix_input"
-
-    def to_dict(self) -> dict[str, str]:
-        return asdict(self)
-
-
-def _issue(
-    issues: list[ContractIssue],
-    code: str,
-    path: str,
-    message: str,
-    retry_advice: str = "fix_input",
-) -> None:
-    issues.append(ContractIssue(code, path, message, retry_advice))
-
-
-def _required_string(
-    obj: dict[str, Any],
-    key: str,
-    path: str,
-    issues: list[ContractIssue],
-    retry_advice: str = "fix_input",
-    code: str = "DM_SCHEMA_REQUIRED",
-) -> str:
-    value = obj.get(key)
-    if not isinstance(value, str) or not value.strip():
-        _issue(
-            issues,
-            code,
-            f"{path}.{key}",
-            "required non-empty string is missing",
-            retry_advice,
-        )
-        return ""
-    return value.strip()
-
-
-def validate_authoring_contract(
-    value: object,
-    *,
-    known_field_types: Collection[str] | None = None,
-    manual_forbidden_field_types: Collection[str] = (),
-    skip_entities: Collection[str] = (),
-) -> list[ContractIssue]:
-    issues: list[ContractIssue] = []
-    if not isinstance(value, dict):
-        return [
-            ContractIssue(
-                "DM_SCHEMA_TYPE", "$", "top-level value must be an object"
-            )
-        ]
-
-    artifact = value.get("artifact")
-    if not isinstance(artifact, dict):
-        return [
-            ContractIssue(
-                "DM_SCHEMA_REQUIRED", "$.artifact", "required object is missing"
-            )
-        ]
-
-    _required_string(artifact, "parsedAt", "$.artifact", issues)
-    rules = artifact.get("rules")
-    if not isinstance(rules, list):
-        _issue(issues, "DM_SCHEMA_TYPE", "$.artifact.rules", "must be an array")
-    elif rules:
-        _issue(
-            issues,
-            "DM_SCHEMA_FORBIDDEN",
-            "$.artifact.rules",
-            "must be empty; business rules are outside dataModel authoring scope",
-        )
-
-    entities = artifact.get("entities")
-    if not isinstance(entities, list) or not entities:
-        _issue(
-            issues,
-            "DM_SCHEMA_REQUIRED",
-            "$.artifact.entities",
-            "must be a non-empty array",
-        )
-        return issues
-
-    skip = set(skip_entities)
-    known_types = set(known_field_types or ())
-    forbidden_types = set(manual_forbidden_field_types or ())
-    main_names: set[str] = set()
-    child_refs: list[dict[str, str]] = []
-    entity_names: set[str] = set()
-    entity_index: dict[str, dict[str, Any]] = {}
-    reference_fields: list[dict[str, Any]] = []
-    basedata_property_fields: list[dict[str, str]] = []
-    qty_fields: list[dict[str, str]] = []
-    physical_tables: dict[str, str] = {}
-    logical_entities: dict[str, str] = {}
-
-    for index, entity in enumerate(entities):
-        path = f"$.artifact.entities[{index}]"
-        if not isinstance(entity, dict):
-            _issue(issues, "DM_SCHEMA_TYPE", path, "must be an object")
-            continue
-        biz_name = str(entity.get("bizName") or "").strip()
-        if biz_name in skip:
-            continue
-
-        biz_name = _required_string(entity, "bizName", path, issues)
-        _required_string(entity, "displayName", path, issues)
-        entity_type = _required_string(entity, "type", path, issues)
-        if biz_name and not ENTITY_IDENTIFIER_RE.fullmatch(biz_name):
-            _issue(
-                issues,
-                "DM_SCHEMA_PATTERN",
-                f"{path}.bizName",
-                "must match ^[A-Za-z][A-Za-z0-9_]*$",
-            )
-        if biz_name:
-            if biz_name in entity_names:
-                _issue(
-                    issues,
-                    "DM_RELATION_DUPLICATE",
-                    f"{path}.bizName",
-                    f"duplicate entity bizName '{biz_name}'",
-                )
-            entity_names.add(biz_name)
-        if entity_type and entity_type not in ENTITY_TYPES:
-            _issue(
-                issues,
-                "DM_SCHEMA_ENUM",
-                f"{path}.type",
-                f"must be one of {sorted(ENTITY_TYPES)}",
-            )
-
-        forbidden = sorted(FORBIDDEN_ENTITY_KEYS.intersection(entity))
-        for key in forbidden:
-            _issue(
-                issues,
-                "DM_SCHEMA_FORBIDDEN",
-                f"{path}.{key}",
-                "decorated/runtime field must not be authored",
-            )
-
-        logical_entity = entity.get("logicalName")
-        if logical_entity is not None:
-            logical_path = f"{path}.logicalName"
-            if not isinstance(logical_entity, str) or not logical_entity.strip():
-                _issue(
-                    issues,
-                    "DM_LOGICAL_ENTITY_INVALID",
-                    logical_path,
-                    "explicit logical entity identifier must be a non-empty string",
-                    "user_input_required",
-                )
-            else:
-                logical_entity = logical_entity.strip()
-                if not IDENTIFIER_RE.fullmatch(logical_entity):
-                    _issue(
-                        issues,
-                        "DM_LOGICAL_ENTITY_INVALID",
-                        logical_path,
-                        "must match ^[a-z][a-z0-9_]*$",
-                        "user_input_required",
-                    )
-                if len(logical_entity) > MAX_LOGICAL_ENTITY_NAME:
-                    _issue(
-                        issues,
-                        "DM_LOGICAL_ENTITY_LENGTH",
-                        logical_path,
-                        f"exceeds platform limit {MAX_LOGICAL_ENTITY_NAME}",
-                        "user_input_required",
-                    )
-                owner = logical_entities.get(logical_entity)
-                if owner and owner != biz_name:
-                    _issue(
-                        issues,
-                        "DM_LOGICAL_ENTITY_DUPLICATE",
-                        logical_path,
-                        f"duplicates the explicit logical identifier of entity '{owner}'",
-                        "user_input_required",
-                    )
-                logical_entities[logical_entity] = biz_name
-
-        physical_table = entity.get("physicalName")
-        if physical_table is not None:
-            storage_path = f"{path}.physicalName"
-            if not isinstance(physical_table, str) or not physical_table.strip():
-                _issue(
-                    issues,
-                    "DM_STORAGE_TABLE_INVALID",
-                    storage_path,
-                    "explicit physical table name must be a non-empty string",
-                    "user_input_required",
-                )
-            else:
-                physical_table = physical_table.strip()
-                if not IDENTIFIER_RE.fullmatch(physical_table):
-                    _issue(
-                        issues,
-                        "DM_STORAGE_TABLE_INVALID",
-                        storage_path,
-                        "must match ^[a-z][a-z0-9_]*$",
-                        "user_input_required",
-                    )
-                if len(physical_table) > MAX_PHYSICAL_TABLE_NAME:
-                    _issue(
-                        issues,
-                        "DM_STORAGE_TABLE_LENGTH",
-                        storage_path,
-                        f"exceeds platform limit {MAX_PHYSICAL_TABLE_NAME}",
-                        "user_input_required",
-                    )
-                owner = physical_tables.get(physical_table)
-                if owner and owner != biz_name:
-                    _issue(
-                        issues,
-                        "DM_STORAGE_TABLE_DUPLICATE",
-                        storage_path,
-                        f"duplicates the explicit physical table of entity '{owner}'",
-                        "user_input_required",
-                    )
-                physical_tables[physical_table] = biz_name
-
-        parent_ref = str(entity.get("parentEntityRef") or "").strip()
-        if entity_type in MAIN_ENTITY_TYPES:
-            if parent_ref:
-                _issue(
-                    issues,
-                    "DM_RELATION_ROOT_HAS_PARENT",
-                    f"{path}.parentEntityRef",
-                    f"root entity type '{entity_type}' must not declare parentEntityRef",
-                )
-        if entity_type in {"BillEntity", "BaseEntity"}:
-            _required_string(entity, "templateKey", path, issues)
-            if biz_name:
-                main_names.add(biz_name)
-        elif entity_type == "MainEntity":
-            if biz_name:
-                main_names.add(biz_name)
-        elif entity_type in CHILD_ENTITY_TYPES:
-            parent = _required_string(entity, "parentEntityRef", path, issues)
-            if parent:
-                child_refs.append(
-                    {
-                        "path": f"{path}.parentEntityRef",
-                        "child": biz_name,
-                        "childType": entity_type,
-                        "parent": parent,
-                    }
-                )
-
-        auto_number = entity.get("autoNumber")
-        if auto_number is not None:
-            if entity_type != "BillEntity":
-                _issue(
-                    issues,
-                    "DM_AUTO_NUMBER_ENTITY_INVALID",
-                    f"{path}.autoNumber",
-                    "autoNumber is only valid for BillEntity",
-                )
-            elif not isinstance(auto_number, bool):
-                _issue(
-                    issues,
-                    "DM_AUTO_NUMBER_INVALID",
-                    f"{path}.autoNumber",
-                    "autoNumber must be boolean",
-                )
-
-        entry_display_type = entity.get("entryDisplayType")
-        if entry_display_type is not None:
-            if entity_type not in {"EntryEntity", "SubEntryEntity"}:
-                _issue(
-                    issues,
-                    "DM_RELATION_DISPLAY_TYPE_INVALID",
-                    f"{path}.entryDisplayType",
-                    "entryDisplayType is only valid for EntryEntity or SubEntryEntity",
-                )
-            if entry_display_type not in {"grid", "card"}:
-                _issue(
-                    issues,
-                    "DM_SCHEMA_ENUM",
-                    f"{path}.entryDisplayType",
-                    "must be one of ['grid', 'card']",
-                )
-
-        fields = entity.get("fields")
-        if not isinstance(fields, list):
-            _issue(
-                issues,
-                "DM_SCHEMA_TYPE",
-                f"{path}.fields",
-                "must be an array",
-            )
-            continue
-
-        seen_fields: set[str] = set()
-        seen_field_types: dict[str, str] = {}
-        physical_columns: dict[str, str] = {}
-        logical_fields: dict[str, str] = {}
-        for field_index, field in enumerate(fields):
-            field_path = f"{path}.fields[{field_index}]"
-            if not isinstance(field, dict):
-                _issue(issues, "DM_SCHEMA_TYPE", field_path, "must be an object")
-                continue
-            biz_word = _required_string(field, "bizWord", field_path, issues)
-            _required_string(field, "displayName", field_path, issues)
-            data_type = _required_string(field, "dataType", field_path, issues)
-            if biz_word and not IDENTIFIER_RE.fullmatch(biz_word):
-                _issue(
-                    issues,
-                    "DM_SCHEMA_PATTERN",
-                    f"{field_path}.bizWord",
-                    "must match ^[a-z][a-z0-9_]*$",
-                )
-            if biz_word:
-                if entity_type in {"TreeEntryEntity", "TreeSubEntryEntity"} and biz_word in {
-                    "pid",
-                    "is_group_node",
-                }:
-                    _issue(
-                        issues,
-                        "TREE_SYSTEM_FIELD_FORBIDDEN",
-                        f"{field_path}.bizWord",
-                        f"tree entity system field '{biz_word}' is injected by the platform",
-                    )
-                if biz_word in seen_fields:
-                    _issue(
-                        issues,
-                        "DM_RELATION_DUPLICATE",
-                        f"{field_path}.bizWord",
-                        f"duplicate field bizWord '{biz_word}' in entity '{biz_name}'",
-                    )
-                seen_fields.add(biz_word)
-            if known_types and data_type and data_type not in known_types:
-                _issue(
-                    issues,
-                    "DM_SCHEMA_ENUM",
-                    f"{field_path}.dataType",
-                    f"unknown field type '{data_type}'",
-                )
-            if data_type and data_type in forbidden_types:
-                message = f"field type '{data_type}' is forbidden from manual creation"
-                if entity_type == "MainEntity":
-                    message += (
-                        "; DynamicFormModel must retain requested business meaning "
-                        "with an ordinary field type; default or automatic behavior "
-                        "is a separate contract"
-                    )
-                _issue(
-                    issues,
-                    "FIELD_TYPE_MANUAL_FORBIDDEN",
-                    f"{field_path}.dataType",
-                    message,
-                )
-            for key in sorted(FORBIDDEN_FIELD_KEYS.intersection(field)):
-                _issue(
-                    issues,
-                    "DM_SCHEMA_FORBIDDEN",
-                    f"{field_path}.{key}",
-                    "decorated/deprecated field must not be authored",
-                )
-            for key in sorted(POST_BUILD_FIELD_PROPERTY_KEYS.intersection(field)):
-                _issue(
-                    issues,
-                    "DM_FIELD_PROPERTY_POST_BUILD_REQUIRED",
-                    f"{field_path}.{key}",
-                    "Direct field authoring accepts only mustInput; apply this "
-                    "property with the verified property command after modeling",
-                )
-            logical_field = field.get("logicalName")
-            if logical_field is not None:
-                logical_path = f"{field_path}.logicalName"
-                if not isinstance(logical_field, str) or not logical_field.strip():
-                    _issue(
-                        issues,
-                        "DM_LOGICAL_FIELD_INVALID",
-                        logical_path,
-                        "explicit logical field identifier must be a non-empty string",
-                        "user_input_required",
-                    )
-                else:
-                    logical_field = logical_field.strip()
-                    if not IDENTIFIER_RE.fullmatch(logical_field):
-                        _issue(
-                            issues,
-                            "DM_LOGICAL_FIELD_INVALID",
-                            logical_path,
-                            "must match ^[a-z][a-z0-9_]*$",
-                            "user_input_required",
-                        )
-                    if len(logical_field) > MAX_LOGICAL_FIELD_NAME:
-                        _issue(
-                            issues,
-                            "DM_LOGICAL_FIELD_LENGTH",
-                            logical_path,
-                            f"exceeds platform limit {MAX_LOGICAL_FIELD_NAME}",
-                            "user_input_required",
-                        )
-                    owner = logical_fields.get(logical_field)
-                    if owner and owner != biz_word:
-                        _issue(
-                            issues,
-                            "DM_LOGICAL_FIELD_DUPLICATE",
-                            logical_path,
-                            f"duplicates the explicit logical identifier of field '{owner}'",
-                            "user_input_required",
-                        )
-                    logical_fields[logical_field] = biz_word
-            physical_column = field.get("physicalName")
-            if physical_column is not None:
-                storage_path = f"{field_path}.physicalName"
-                if not isinstance(physical_column, str) or not physical_column.strip():
-                    _issue(
-                        issues,
-                        "DM_STORAGE_COLUMN_INVALID",
-                        storage_path,
-                        "explicit physical column name must be a non-empty string",
-                        "user_input_required",
-                    )
-                else:
-                    physical_column = physical_column.strip()
-                    if not IDENTIFIER_RE.fullmatch(physical_column):
-                        _issue(
-                            issues,
-                            "DM_STORAGE_COLUMN_INVALID",
-                            storage_path,
-                            "must match ^[a-z][a-z0-9_]*$",
-                            "user_input_required",
-                        )
-                    if len(physical_column) > MAX_PHYSICAL_COLUMN_NAME:
-                        _issue(
-                            issues,
-                            "DM_STORAGE_COLUMN_LENGTH",
-                            storage_path,
-                            f"exceeds platform limit {MAX_PHYSICAL_COLUMN_NAME}",
-                            "user_input_required",
-                        )
-                    owner = physical_columns.get(physical_column)
-                    if owner and owner != biz_word:
-                        _issue(
-                            issues,
-                            "DM_STORAGE_COLUMN_DUPLICATE",
-                            storage_path,
-                            f"duplicates the explicit physical column of field '{owner}'",
-                            "user_input_required",
-                        )
-                    physical_columns[physical_column] = biz_word
-
-            must_input = field.get("mustInput")
-            if "mustInput" in field and not isinstance(must_input, bool):
-                _issue(
-                    issues,
-                    "DM_PROPERTY_MUST_INPUT_INVALID",
-                    f"{field_path}.mustInput",
-                    "must be a boolean",
-                )
-            if data_type in BASEDATA_TYPES and "prdRef" not in field:
-                if "reference" not in field:
-                    _issue(
-                        issues,
-                        "DM_SCHEMA_REQUIRED",
-                        f"{field_path}.reference",
-                        f"{data_type} must declare reference or legacy prdRef",
-                    )
-            if data_type in REF_BILL_TYPES:
-                if "reference" not in field:
-                    _issue(
-                        issues,
-                        "DM_SCHEMA_REQUIRED",
-                        f"{field_path}.reference",
-                        "RefBillField must declare a structured reference",
-                    )
-                if "prdRef" in field:
-                    _issue(
-                        issues,
-                        "DM_SCHEMA_FORBIDDEN",
-                        f"{field_path}.prdRef",
-                        "RefBillField must use reference; prdRef is only for master data",
-                    )
-            if data_type in WRAPPED_TYPES:
-                for key in ("prdRef", "basedataNumber", "basedataHint"):
-                    if key in field and str(field.get(key) or "").strip():
-                        _issue(
-                            issues,
-                            "DM_SCHEMA_FORBIDDEN",
-                            f"{field_path}.{key}",
-                            f"wrapper type {data_type} has a built-in association",
-                        )
-            if data_type == "AssistantField":
-                _required_string(
-                    field,
-                    "assistantCategory",
-                    field_path,
-                    issues,
-                    code="ASSISTANT_CATEGORY_REQUIRED",
-                )
-                for key in ("reference", "prdRef", "basedataNumber"):
-                    if key in field:
-                        _issue(
-                            issues,
-                            "ASSISTANT_CATEGORY_REFERENCE_CONFLICT",
-                            f"{field_path}.{key}",
-                            "AssistantField references an assistant category, not a form",
-                        )
-            elif "assistantCategory" in field:
-                _issue(
-                    issues,
-                    "ASSISTANT_CATEGORY_TYPE_MISMATCH",
-                    f"{field_path}.assistantCategory",
-                    "assistantCategory is only valid for AssistantField",
-                )
-            if data_type in COMBO_TYPES:
-                options = field.get("comboOptions")
-                if not isinstance(options, list) or not options:
-                    _issue(
-                        issues,
-                        "DM_SCHEMA_REQUIRED",
-                        f"{field_path}.comboOptions",
-                        f"{data_type} requires a non-empty array",
-                    )
-                else:
-                    for option_index, option in enumerate(options):
-                        option_path = (
-                            f"{field_path}.comboOptions[{option_index}]"
-                        )
-                        if not isinstance(option, dict):
-                            _issue(
-                                issues,
-                                "DM_SCHEMA_TYPE",
-                                option_path,
-                                "must be an object",
-                            )
-                            continue
-                        _required_string(option, "label", option_path, issues)
-                        _required_string(option, "value", option_path, issues)
-            elif "comboOptions" in field:
-                _issue(
-                    issues,
-                    "FIELD_OPTIONS_TYPE_MISMATCH",
-                    f"{field_path}.comboOptions",
-                    f"comboOptions is not valid for field type '{data_type}'",
-                )
-
-            has_legacy_reference = any(
-                key in field for key in ("prdRef", "refTo")
-            )
-            reference = field.get("reference")
-            if (reference is not None or has_legacy_reference) and data_type not in REFERENCE_TYPES:
-                _issue(
-                    issues,
-                    "REFERENCE_FIELD_TYPE_MISMATCH",
-                    f"{field_path}.dataType",
-                    f"reference metadata is not valid for field type '{data_type}'",
-                )
-
-            normalized_reference: dict[str, str] | None = None
-            if reference is not None:
-                if not isinstance(reference, dict):
-                    _issue(
-                        issues,
-                        "DM_SCHEMA_TYPE",
-                        f"{field_path}.reference",
-                        "must be an object",
-                    )
-                else:
-                    mode = _required_string(
-                        reference,
-                        "mode",
-                        f"{field_path}.reference",
-                        issues,
-                    )
-                    if mode not in {"local", "platform"}:
-                        _issue(
-                            issues,
-                            "DM_SCHEMA_ENUM",
-                            f"{field_path}.reference.mode",
-                            "must be one of ['local', 'platform']",
-                        )
-                    elif mode == "local":
-                        entity_ref = _required_string(
-                            reference,
-                            "entityRef",
-                            f"{field_path}.reference",
-                            issues,
-                        )
-                        if entity_ref and not ENTITY_IDENTIFIER_RE.fullmatch(entity_ref):
-                            _issue(
-                                issues,
-                                "DM_SCHEMA_PATTERN",
-                                f"{field_path}.reference.entityRef",
-                                "must match ^[A-Za-z][A-Za-z0-9_]*$",
-                            )
-                        if "formNumber" in reference:
-                            _issue(
-                                issues,
-                                "DM_SCHEMA_FORBIDDEN",
-                                f"{field_path}.reference.formNumber",
-                                "local reference must not declare formNumber",
-                            )
-                        if data_type not in (BASEDATA_TYPES | REF_BILL_TYPES):
-                            _issue(
-                                issues,
-                                "REFERENCE_FIELD_TYPE_MISMATCH",
-                                f"{field_path}.dataType",
-                                "local references require BasedataField, MulBasedataField, or RefBillField",
-                            )
-                        normalized_reference = {
-                            "mode": mode,
-                            "target": entity_ref,
-                        }
-                    elif mode == "platform":
-                        form_number = _required_string(
-                            reference,
-                            "formNumber",
-                            f"{field_path}.reference",
-                            issues,
-                        )
-                        if "entityRef" in reference:
-                            _issue(
-                                issues,
-                                "DM_SCHEMA_FORBIDDEN",
-                                f"{field_path}.reference.entityRef",
-                                "platform reference must not declare entityRef",
-                            )
-                        normalized_reference = {
-                            "mode": mode,
-                            "target": form_number,
-                        }
-
-            carry_mappings = field.get("carryMappings")
-            normalized_mappings: list[tuple[str, str, str]] = []
-            if carry_mappings is not None:
-                if data_type not in REFERENCE_TYPES:
-                    _issue(
-                        issues,
-                        "CARRY_ON_NON_REFERENCE_FIELD",
-                        f"{field_path}.carryMappings",
-                        f"carryMappings is not valid for field type '{data_type}'",
-                    )
-                if normalized_reference is None:
-                    _issue(
-                        issues,
-                        "DM_SCHEMA_REQUIRED",
-                        f"{field_path}.reference",
-                        "carryMappings requires a structured reference",
-                    )
-                if not isinstance(carry_mappings, list) or not carry_mappings:
-                    _issue(
-                        issues,
-                        "DM_SCHEMA_REQUIRED",
-                        f"{field_path}.carryMappings",
-                        "must be a non-empty array",
-                    )
-                else:
-                    seen_mappings: set[tuple[str, str]] = set()
-                    for mapping_index, mapping in enumerate(carry_mappings):
-                        mapping_path = (
-                            f"{field_path}.carryMappings[{mapping_index}]"
-                        )
-                        if not isinstance(mapping, dict):
-                            _issue(
-                                issues,
-                                "DM_SCHEMA_TYPE",
-                                mapping_path,
-                                "must be an object",
-                            )
-                            continue
-                        source = _required_string(
-                            mapping,
-                            "sourceField",
-                            mapping_path,
-                            issues,
-                        )
-                        target = _required_string(
-                            mapping,
-                            "targetField",
-                            mapping_path,
-                            issues,
-                        )
-                        for key, val in (("sourceField", source), ("targetField", target)):
-                            if val and not IDENTIFIER_RE.fullmatch(val):
-                                _issue(
-                                    issues,
-                                    "DM_SCHEMA_PATTERN",
-                                    f"{mapping_path}.{key}",
-                                    "must match ^[a-z][a-z0-9_]*$",
-                                )
-                        pair = (source, target)
-                        if source and target and pair in seen_mappings:
-                            _issue(
-                                issues,
-                                "DM_RELATION_DUPLICATE",
-                                mapping_path,
-                                f"duplicate carry mapping {source!r} -> {target!r}",
-                            )
-                        seen_mappings.add(pair)
-                        normalized_mappings.append((mapping_path, source, target))
-
-            if normalized_reference is not None:
-                reference_fields.append(
-                    {
-                        "path": field_path,
-                        "owner": biz_name,
-                        "dataType": data_type,
-                        "reference": normalized_reference,
-                        "mappings": normalized_mappings,
-                    }
-                )
-
-            if data_type == "QtyField":
-                unit_ref = _required_string(
-                    field,
-                    "unitFieldRef",
-                    field_path,
-                    issues,
-                    code="QTY_UNIT_PAIR_MISSING",
-                )
-                if unit_ref and not IDENTIFIER_RE.fullmatch(unit_ref):
-                    _issue(
-                        issues,
-                        "DM_SCHEMA_PATTERN",
-                        f"{field_path}.unitFieldRef",
-                        "must match ^[a-z][a-z0-9_]*$",
-                    )
-                qty_fields.append(
-                    {"path": field_path, "owner": biz_name, "unitRef": unit_ref}
-                )
-            elif "unitFieldRef" in field:
-                _issue(
-                    issues,
-                    "QTY_UNIT_TYPE_MISMATCH",
-                    f"{field_path}.unitFieldRef",
-                    f"unitFieldRef is not valid for field type '{data_type}'",
-                )
-            if data_type == "BasedataPropField":
-                source_ref = _required_string(
-                    field,
-                    "refBaseFieldKey",
-                    field_path,
-                    issues,
-                    code="BASEDATA_PROP_SOURCE_MISSING",
-                )
-                display_prop = _required_string(
-                    field,
-                    "refDisplayProp",
-                    field_path,
-                    issues,
-                    code="BASEDATA_PROP_DISPLAY_MISSING",
-                )
-                if source_ref and not IDENTIFIER_RE.fullmatch(source_ref):
-                    _issue(
-                        issues,
-                        "DM_SCHEMA_PATTERN",
-                        f"{field_path}.refBaseFieldKey",
-                        "must match ^[a-z][a-z0-9_]*$",
-                    )
-                basedata_property_fields.append(
-                    {
-                        "path": field_path,
-                        "owner": biz_name,
-                        "sourceRef": source_ref,
-                        "displayProp": display_prop,
-                    }
-                )
-            else:
-                for property_key in ("refBaseFieldKey", "refDisplayProp"):
-                    if property_key in field:
-                        _issue(
-                            issues,
-                            "BASEDATA_PROP_TYPE_MISMATCH",
-                            f"{field_path}.{property_key}",
-                            f"{property_key} is only valid for BasedataPropField",
-                        )
-            if biz_word:
-                seen_field_types[biz_word] = data_type
-
-        list_config = entity.get("listConfiguration")
-        if list_config is not None:
-            config_path = f"{path}.listConfiguration"
-            if entity_type not in MAIN_ENTITY_TYPES:
-                _issue(
-                    issues,
-                    "DM_LIST_OWNER_INVALID",
-                    config_path,
-                    "listConfiguration is only valid on a main entity",
-                )
-            if not isinstance(list_config, dict) or not list_config:
-                _issue(issues, "DM_SCHEMA_TYPE", config_path, "must be a non-empty object")
-            else:
-                allowed_config_keys = {"columns", "quickSearch", "commonFilters"}
-                for key in sorted(set(list_config) - allowed_config_keys):
-                    _issue(
-                        issues,
-                        "DM_SCHEMA_FORBIDDEN",
-                        f"{config_path}.{key}",
-                        "unknown list configuration key",
-                    )
-                columns = list_config.get("columns")
-                if columns is not None:
-                    if not isinstance(columns, list) or not columns:
-                        _issue(issues, "DM_SCHEMA_TYPE", f"{config_path}.columns", "must be a non-empty array")
-                    else:
-                        seen_column_refs: set[str] = set()
-                        for column_index, column in enumerate(columns):
-                            column_path = f"{config_path}.columns[{column_index}]"
-                            if not isinstance(column, dict):
-                                _issue(issues, "DM_SCHEMA_TYPE", column_path, "must be an object")
-                                continue
-                            field_ref = _required_string(column, "fieldRef", column_path, issues)
-                            if field_ref and not IDENTIFIER_RE.fullmatch(field_ref):
-                                _issue(issues, "DM_SCHEMA_PATTERN", f"{column_path}.fieldRef", "must match ^[a-z][a-z0-9_]*$")
-                            if field_ref in seen_column_refs:
-                                _issue(issues, "DM_RELATION_DUPLICATE", f"{column_path}.fieldRef", f"duplicate list column fieldRef '{field_ref}'")
-                            seen_column_refs.add(field_ref)
-                            if column.get("order") not in (None, "NotOrder", "ASC", "DESC"):
-                                _issue(issues, "DM_SCHEMA_ENUM", f"{column_path}.order", "must be one of ['NotOrder', 'ASC', 'DESC']")
-                            for boolean_key in ("hyperlink",):
-                                if boolean_key in column and not isinstance(column[boolean_key], bool):
-                                    _issue(issues, "DM_SCHEMA_TYPE", f"{column_path}.{boolean_key}", "must be a boolean")
-                            for key in sorted(set(column) - {"fieldRef", "order", "hyperlink"}):
-                                _issue(issues, "DM_SCHEMA_FORBIDDEN", f"{column_path}.{key}", "unknown list column configuration key")
-                for collection_key in ("quickSearch", "commonFilters"):
-                    values = list_config.get(collection_key)
-                    values_path = f"{config_path}.{collection_key}"
-                    if values is None:
-                        continue
-                    if not isinstance(values, list) or not values:
-                        _issue(issues, "DM_SCHEMA_TYPE", values_path, "must be a non-empty array")
-                        continue
-                    seen_refs: set[str] = set()
-                    for ref_index, field_ref in enumerate(values):
-                        ref_path = f"{values_path}[{ref_index}]"
-                        if not isinstance(field_ref, str) or not IDENTIFIER_RE.fullmatch(field_ref):
-                            _issue(issues, "DM_SCHEMA_PATTERN", ref_path, "must match ^[a-z][a-z0-9_]*$")
-                        if field_ref in seen_refs:
-                            _issue(issues, "DM_RELATION_DUPLICATE", ref_path, f"duplicate fieldRef '{field_ref}'")
-                        seen_refs.add(field_ref)
-
-        if biz_name:
-            entity_index[biz_name] = {
-                "type": entity_type,
-                "fields": seen_fields,
-                "fieldTypes": seen_field_types,
-                "fieldMetadata": {
-                    str(field.get("bizWord") or "").strip(): field
-                    for field in fields
-                    if isinstance(field, dict)
-                    and str(field.get("bizWord") or "").strip()
-                },
-                "fieldCount": len(fields),
-                "path": path,
-            }
-        if entity_type == "BaseEntity" and len(fields) == 0:
-            _issue(
-                issues,
-                "BASEENTITY_EMPTY",
-                f"{path}.fields",
-                "new BaseEntity must define at least one business field",
-            )
-
-    expected_parent_types = {
-        "EntryEntity": MAIN_ENTITY_TYPES,
-        "TreeEntryEntity": MAIN_ENTITY_TYPES,
-        "SubEntryEntity": frozenset({"EntryEntity"}),
-        "TreeSubEntryEntity": frozenset({"TreeEntryEntity"}),
-    }
-    for relation in child_refs:
-        path = relation["path"]
-        parent = relation["parent"]
-        parent_entity = entity_index.get(parent)
-        if parent_entity is None:
-            _issue(
-                issues,
-                "DM_RELATION_PARENT_NOT_FOUND",
-                path,
-                f"parentEntityRef '{parent}' does not reference an entity in this artifact",
-            )
-            continue
-        allowed = expected_parent_types.get(relation["childType"], frozenset())
-        if parent_entity["type"] not in allowed:
-            _issue(
-                issues,
-                "DM_RELATION_PARENT_TYPE_INVALID",
-                path,
-                f"{relation['childType']} '{relation['child']}' requires parent type "
-                f"{sorted(allowed)}, got '{parent_entity['type']}'",
-            )
-
-    for relation in reference_fields:
-        reference = relation["reference"]
-        if reference["mode"] != "local":
-            continue
-        target_name = reference["target"]
-        target = entity_index.get(target_name)
-        if target is None:
-            _issue(
-                issues,
-                "LOCAL_REFERENCE_TARGET_MISSING",
-                f"{relation['path']}.reference.entityRef",
-                f"local reference target '{target_name}' does not exist",
-            )
-            continue
-        if target["type"] not in {"BillEntity", "BaseEntity"}:
-            _issue(
-                issues,
-                "LOCAL_REFERENCE_TARGET_INVALID",
-                f"{relation['path']}.reference.entityRef",
-                f"local reference target '{target_name}' must be a main entity",
-            )
-            continue
-        data_type = relation["dataType"]
-        expected_types = (
-            REF_BILL_TYPES
-            if target["type"] == "BillEntity"
-            else BASEDATA_TYPES
-        )
-        if data_type not in expected_types:
-            _issue(
-                issues,
-                "LOCAL_REFERENCE_TYPE_MISMATCH",
-                f"{relation['path']}.dataType",
-                f"local reference target '{target_name}' is {target['type']}; "
-                f"field type must be one of {sorted(expected_types)}, got '{data_type}'",
-            )
-            continue
-        owner = entity_index.get(relation["owner"], {})
-        owner_fields = set(owner.get("fields") or ())
-        source_fields = set(target.get("fields") or ()) | {"name"}
-        for mapping_path, source, target_field in relation["mappings"]:
-            if source and source not in source_fields:
-                _issue(
-                    issues,
-                    "CARRY_SOURCE_FIELD_MISSING",
-                    f"{mapping_path}.sourceField",
-                    f"source field '{source}' does not exist on '{target_name}'",
-                )
-            if target_field and target_field not in owner_fields:
-                _issue(
-                    issues,
-                    "CARRY_TARGET_FIELD_MISSING",
-                    f"{mapping_path}.targetField",
-                    f"target field '{target_field}' does not exist on '{relation['owner']}'",
-                )
-
-    for qty in qty_fields:
-        if not qty["unitRef"]:
-            continue
-        owner = entity_index.get(qty["owner"], {})
-        unit_type = (owner.get("fieldTypes") or {}).get(qty["unitRef"])
-        if unit_type != "UnitField":
-            _issue(
-                issues,
-                "QTY_UNIT_PAIR_MISSING",
-                f"{qty['path']}.unitFieldRef",
-                f"unitFieldRef '{qty['unitRef']}' must reference a UnitField in the same entity",
-            )
-
-    for relation in basedata_property_fields:
-        source_ref = relation["sourceRef"]
-        if not source_ref:
-            continue
-        owner = entity_index.get(relation["owner"], {})
-        source_type = (owner.get("fieldTypes") or {}).get(source_ref)
-        if source_type is None:
-            _issue(
-                issues,
-                "BASEDATA_PROP_SOURCE_MISSING",
-                f"{relation['path']}.refBaseFieldKey",
-                f"refBaseFieldKey '{source_ref}' does not reference a field in the same entity",
-            )
-        elif source_type not in BASEDATA_PROPERTY_SOURCE_TYPES:
-            advice = (
-                "; for bill-to-bill carry, put carryMappings on the RefBillField "
-                "and author ordinary target fields"
-                if source_type == "RefBillField"
-                else ""
-            )
-            _issue(
-                issues,
-                "BASEDATA_PROP_SOURCE_TYPE_MISMATCH",
-                f"{relation['path']}.refBaseFieldKey",
-                f"BasedataPropField source '{source_ref}' has incompatible type "
-                f"'{source_type}'{advice}",
-            )
-            continue
-
-        # A direct BasedataPropField is retained as a backward-compatible
-        # authoring input.  For a local reference its property can be resolved
-        # completely before emit, so reject a typo here instead of creating a
-        # form shell and discovering the missing RefProp in runBatch.
-        source_field = (owner.get("fieldMetadata") or {}).get(source_ref) or {}
-        source_reference = source_field.get("reference")
-        if not isinstance(source_reference, dict):
-            continue
-        if str(source_reference.get("mode") or "").strip() != "local":
-            continue
-        referenced_entity = str(
-            source_reference.get("entityRef") or ""
-        ).strip()
-        referenced = entity_index.get(referenced_entity)
-        if referenced is None:
-            # LOCAL_REFERENCE_TARGET_MISSING already owns this diagnostic.
-            continue
-        display_root = str(relation.get("displayProp") or "").split(".", 1)[0]
-        available = set(referenced.get("fields") or ()) | {"name", "number"}
-        if display_root and display_root not in available:
-            _issue(
-                issues,
-                "BASEDATA_PROP_DISPLAY_UNRESOLVED",
-                f"{relation['path']}.refDisplayProp",
-                f"property '{display_root}' does not exist on local reference "
-                f"target '{referenced_entity}'; use carryMappings with a real "
-                "sourceField and semantic target field",
-            )
-
-    assumptions = value.get("assumptions", [])
-    if not isinstance(assumptions, list):
-        _issue(issues, "DM_SCHEMA_TYPE", "$.assumptions", "must be an array")
-    else:
-        for index, assumption in enumerate(assumptions):
-            path = f"$.assumptions[{index}]"
-            if not isinstance(assumption, dict):
-                _issue(issues, "DM_SCHEMA_TYPE", path, "must be an object")
-                continue
-            for key in ("code", "target", "decision", "reason"):
-                _required_string(assumption, key, path, issues)
-    return issues
-
-
-def validate_output_contract(value: object) -> list[ContractIssue]:
-    issues: list[ContractIssue] = []
-    if not isinstance(value, dict):
-        return [ContractIssue("DM_OUTPUT_TYPE", "$", "must be an object")]
-    if value.get("schemaVersion") != "1.3":
-        _issue(
-            issues,
-            "DM_OUTPUT_VERSION",
-            "$.schemaVersion",
-            "must equal '1.3'",
-            "reconcile_first",
-        )
-    if value.get("producedBy") != "data_model_emit.py":
-        _issue(
-            issues,
-            "DM_OUTPUT_PRODUCER",
-            "$.producedBy",
-            "must equal 'data_model_emit.py'",
-            "reconcile_first",
-        )
-    _required_string(
-        value,
-        "producedAt",
-        "$",
-        issues,
-        "reconcile_first",
-        "DM_OUTPUT_REQUIRED",
-    )
-    _required_string(
-        value,
-        "modelType",
-        "$",
-        issues,
-        "reconcile_first",
-        "DM_OUTPUT_REQUIRED",
-    )
-    data_model = value.get("dataModel")
-    if not isinstance(data_model, list) or not data_model:
-        _issue(
-            issues,
-            "DM_OUTPUT_REQUIRED",
-            "$.dataModel",
-            "must be a non-empty array",
-            "reconcile_first",
-        )
-        return issues
-    for index, item in enumerate(data_model):
-        path = f"$.dataModel[{index}]"
-        if not isinstance(item, dict):
-            _issue(issues, "DM_OUTPUT_TYPE", path, "must be an object")
-            continue
-        for key in (
-            "businessObject",
-            "billOrEntityName",
-            "entityType",
-            "scene",
-            "templateNumber",
-            "headerFields",
-            "rules",
-        ):
-            if key not in item:
-                _issue(
-                    issues,
-                    "DM_OUTPUT_REQUIRED",
-                    f"{path}.{key}",
-                    "required emitted field is missing",
-                    "reconcile_first",
-                )
-        entries = item.get("entries")
-        if entries is not None:
-            if not isinstance(entries, list) or not entries:
-                _issue(
-                    issues,
-                    "DM_OUTPUT_TYPE",
-                    f"{path}.entries",
-                    "when present, must be a non-empty array",
-                    "reconcile_first",
-                )
-            else:
-                for entry_index, entry in enumerate(entries):
-                    entry_path = f"{path}.entries[{entry_index}]"
-                    if not isinstance(entry, dict):
-                        _issue(
-                            issues,
-                            "DM_OUTPUT_TYPE",
-                            entry_path,
-                            "must be an object",
-                            "reconcile_first",
-                        )
-                        continue
-                    for key in ("entityKey", "displayName", "entryFields"):
-                        if key not in entry:
-                            _issue(
-                                issues,
-                                "DM_OUTPUT_REQUIRED",
-                                f"{entry_path}.{key}",
-                                "required emitted entry field is missing",
-                                "reconcile_first",
-                            )
-    artifact = value.get("artifact")
-    if not isinstance(artifact, dict) or not isinstance(
-        artifact.get("entities"), list
-    ):
-        _issue(
-            issues,
-            "DM_OUTPUT_REQUIRED",
-            "$.artifact.entities",
-            "preserved authoring entities array is missing",
-            "reconcile_first",
-        )
-    meta = value.get("_meta")
-    if not isinstance(meta, dict):
-        _issue(
-            issues,
-            "DM_OUTPUT_REQUIRED",
-            "$._meta",
-            "emission metadata object is missing",
-            "reconcile_first",
-        )
-    else:
-        _required_string(
-            meta,
-            "sectionPath",
-            "$._meta",
-            issues,
-            "reconcile_first",
-            "DM_OUTPUT_REQUIRED",
-        )
-        artifact_count = meta.get("artifactCount")
-        if not isinstance(artifact_count, int) or artifact_count < 1:
-            _issue(
-                issues,
-                "DM_OUTPUT_TYPE",
-                "$._meta.artifactCount",
-                "must be an integer >= 1",
-                "reconcile_first",
-            )
-        if not isinstance(meta.get("appCode"), str):
-            _issue(
-                issues,
-                "DM_OUTPUT_TYPE",
-                "$._meta.appCode",
-                "must be a string",
-                "reconcile_first",
-            )
-    return issues
-
-
-def _load_policy() -> dict[str, Any]:
-    return json.loads(POLICY_PATH.read_text(encoding="utf-8"))
-
-
-def retry_advice_for_exit(exit_code: int) -> str:
-    policy = _load_policy()
-    return str(
-        (policy.get("exitCodes") or {}).get(str(exit_code), {}).get(
-            "retryAdvice", "never"
-        )
-    )
-
-
-def retry_advice_for_error(code: str) -> str:
-    prefixes = _load_policy().get("errorCodePrefixes") or {}
-    for prefix, advice in prefixes.items():
-        if code.startswith(prefix):
-            return str(advice)
-    return "fix_input"
-
-
-__all__ = [
-    "ContractIssue",
-    "retry_advice_for_error",
-    "retry_advice_for_exit",
-    "validate_authoring_contract",
-    "validate_output_contract",
-]