multilingualprogramming 0.4.0__tar.gz → 0.6.0__tar.gz

{multilingualprogramming-0.4.0 → multilingualprogramming-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multilingualprogramming
-Version: 0.4.0
+Version: 0.6.0
 Summary: Python application for multilingual programming
 Author-email: John Samuel <johnsamuelwrites@example.com>
 License: GPL-3.0-or-later
@@ -301,6 +301,7 @@ multilingual run main_en.ml --lang en
 - Date/time: `MPDate`, `MPTime`, `MPDatetime`
 - Frontend: `Lexer`, `Parser`, AST nodes, `SemanticAnalyzer`
 - Runtime: `PythonCodeGenerator`, `RuntimeBuiltins`, `ProgramExecutor`, `REPL`
+- WAT/WASM backend: `WATCodeGenerator` — compiles multilingual AST to executable WebAssembly (core language + OOP with stateful class instances)
 
 Additional syntax now supported:
 
@@ -396,6 +397,8 @@ Use this README for setup and workflow; use `docs/` for design rationale and pol
 - Development and debugging guide: [docs/development.md](docs/development.md)
 - Guide complet en francais: [docs/fr/programmation.md](docs/fr/programmation.md)
 - Language onboarding guide: [docs/language_onboarding.md](docs/language_onboarding.md)
+- WAT/WASM architecture overview: [docs/WASM_ARCHITECTURE_OVERVIEW.md](docs/WASM_ARCHITECTURE_OVERVIEW.md)
+- WAT/WASM OOP object model reference: [docs/wat_oop_model.md](docs/wat_oop_model.md)
 - Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
 - Release process: [docs/releasing.md](docs/releasing.md)
 - Changelog: [CHANGELOG.md](CHANGELOG.md)

{multilingualprogramming-0.4.0 → multilingualprogramming-0.6.0}/README.md

@@ -265,6 +265,7 @@ multilingual run main_en.ml --lang en
 - Date/time: `MPDate`, `MPTime`, `MPDatetime`
 - Frontend: `Lexer`, `Parser`, AST nodes, `SemanticAnalyzer`
 - Runtime: `PythonCodeGenerator`, `RuntimeBuiltins`, `ProgramExecutor`, `REPL`
+- WAT/WASM backend: `WATCodeGenerator` — compiles multilingual AST to executable WebAssembly (core language + OOP with stateful class instances)
 
 Additional syntax now supported:
 
@@ -360,6 +361,8 @@ Use this README for setup and workflow; use `docs/` for design rationale and pol
 - Development and debugging guide: [docs/development.md](docs/development.md)
 - Guide complet en francais: [docs/fr/programmation.md](docs/fr/programmation.md)
 - Language onboarding guide: [docs/language_onboarding.md](docs/language_onboarding.md)
+- WAT/WASM architecture overview: [docs/WASM_ARCHITECTURE_OVERVIEW.md](docs/WASM_ARCHITECTURE_OVERVIEW.md)
+- WAT/WASM OOP object model reference: [docs/wat_oop_model.md](docs/wat_oop_model.md)
 - Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
 - Release process: [docs/releasing.md](docs/releasing.md)
 - Changelog: [CHANGELOG.md](CHANGELOG.md)

{multilingualprogramming-0.4.0 → multilingualprogramming-0.6.0}/multilingualprogramming/__init__.py

@@ -36,6 +36,13 @@ from multilingualprogramming.codegen.executor import ProgramExecutor, ExecutionR
 from multilingualprogramming.codegen.repl import REPL
 from multilingualprogramming.core.ir import CoreIRProgram
 from multilingualprogramming.core.lowering import lower_to_core_ir
+from multilingualprogramming.runtime.numeric_primitives import (
+    Vec2,
+    ComplexScalar,
+    FastRNG,
+    BoundedArray,
+    MinDistanceAccumulator,
+)
 from multilingualprogramming.imports import (
     enable_multilingual_imports, disable_multilingual_imports,
 )
@@ -71,6 +78,11 @@ __all__ = [
     "REPL",
     "CoreIRProgram",
     "lower_to_core_ir",
+    "Vec2",
+    "ComplexScalar",
+    "FastRNG",
+    "BoundedArray",
+    "MinDistanceAccumulator",
     "enable_multilingual_imports",
     "disable_multilingual_imports",
 ]

multilingualprogramming-0.6.0/multilingualprogramming/__main__.py

@@ -0,0 +1,410 @@
+#
+# SPDX-FileCopyrightText: 2024 John Samuel <johnsamuelwrites@gmail.com>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+
+"""
+CLI entry point for the multilingual programming language.
+
+Usage:
+    python -m multilingualprogramming                     # Start REPL
+    python -m multilingualprogramming <file>.ml          # Execute a source file
+    python -m multilingualprogramming run <file>           # Execute a file
+    python -m multilingualprogramming repl [--lang XX]     # Start REPL
+    python -m multilingualprogramming compile <file>       # Show generated Python
+    python -m multilingualprogramming build-wasm-bundle <file>  # Build WAT/ABI bundle
+    python -m multilingualprogramming smoke --lang fr      # Validate one language pack
+    python -m multilingualprogramming smoke --all          # Validate all language packs
+"""
+# pylint: disable=mixed-line-endings
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from multilingualprogramming.codegen.encoding_guard import (
+    assert_clean_utf8_file,
+    assert_clean_text_encoding,
+)
+from multilingualprogramming.codegen.build_orchestrator import BuildOrchestrator
+from multilingualprogramming.codegen.executor import ProgramExecutor
+from multilingualprogramming.codegen.python_generator import PythonCodeGenerator
+from multilingualprogramming.codegen.repl import REPL
+from multilingualprogramming.codegen.wat_generator import WATCodeGenerator
+from multilingualprogramming.keyword.language_pack_validator import (
+    LanguagePackValidator,
+)
+from multilingualprogramming.exceptions import UnsupportedLanguageError
+from multilingualprogramming.lexer.lexer import Lexer
+from multilingualprogramming.parser.parser import Parser
+from multilingualprogramming.version import __version__
+
+
+def _read_source_file(path: str) -> str:
+    try:
+        with open(path, encoding="utf-8") as f:
+            return f.read()
+    except FileNotFoundError:
+        print(f"Error: file not found: {path}", file=sys.stderr)
+        sys.exit(1)
+    except OSError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _parse_program_from_file(path: str, lang: str | None):
+    source = _read_source_file(path)
+    lexer = Lexer(source, language=lang)
+    tokens = lexer.tokenize()
+    detected_lang = lexer.language or lang or "en"
+    parser = Parser(tokens, source_language=detected_lang)
+    return parser.parse()
+
+
+def cmd_run(args):
+    """Execute a multilingual source file."""
+    source = _read_source_file(args.file)
+
+    # Determine package context so that relative imports work.
+    # Walk up from the file's directory while __init__.ml files exist;
+    # that chain of directories forms the package name.  The directory
+    # above the outermost package becomes the sys.path entry.
+    resolved = Path(args.file).resolve()
+    pkg_parts = []
+    current = resolved.parent
+    while (current / "__init__.ml").is_file():
+        pkg_parts.append(current.name)
+        current = current.parent
+    pkg_parts.reverse()
+    package_name = ".".join(pkg_parts) if pkg_parts else None
+
+    # The path entry is either the package root (when inside a package)
+    # or the script's own directory (top-level script).
+    path_entry = str(current if pkg_parts else resolved.parent)
+    if path_entry not in sys.path:
+        sys.path.insert(0, path_entry)
+
+    # Pass __package__ so the import system can resolve relative imports.
+    run_globals = {"__package__": package_name} if package_name else {}
+
+    executor = ProgramExecutor(language=args.lang)
+    result = executor.execute(source, globals_dict=run_globals or None)
+
+    if result.output:
+        sys.stdout.write(result.output)
+
+    if not result.success:
+        for err in result.errors:
+            print(err, file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_repl(args):
+    """Start the interactive REPL."""
+    repl = REPL(
+        language=args.lang,
+        show_python=args.show_python,
+        show_wat=args.show_wat,
+        show_rust=args.show_rust,
+    )
+    repl.run()
+
+
+def cmd_compile(args):
+    """Compile a source file and print the generated Python."""
+    program = _parse_program_from_file(args.file, args.lang)
+
+    generator = PythonCodeGenerator()
+    python_source = generator.generate(program)
+    print(python_source)
+
+
+def cmd_smoke(args):
+    """Run language-pack smoke validation checks."""
+    registry_validator = LanguagePackValidator()
+    languages = (
+        sorted(registry_validator.get_supported_languages())
+        if args.all
+        else [args.lang]
+    )
+
+    failed = False
+    for language in languages:
+        try:
+            errors = registry_validator.validate(language)
+        except UnsupportedLanguageError as exc:
+            failed = True
+            print(f"[FAIL] {language}: {exc}", file=sys.stderr)
+            continue
+
+        if errors:
+            failed = True
+            print(f"[FAIL] {language}", file=sys.stderr)
+            for error in errors:
+                print(f"  - {error}", file=sys.stderr)
+        else:
+            print(f"[PASS] {language}")
+
+    if failed:
+        sys.exit(1)
+
+
+def cmd_wat_abi(args):
+    """Parse source and emit the generated WAT ABI manifest JSON."""
+    program = _parse_program_from_file(args.file, args.lang)
+    manifest = WATCodeGenerator().generate_abi_manifest(program)
+    print(json.dumps(manifest, ensure_ascii=False, indent=2))
+
+
+def cmd_wat_host_shim(args):
+    """Emit JS host-import shim from generated WAT ABI manifest."""
+    program = _parse_program_from_file(args.file, args.lang)
+    generator = WATCodeGenerator()
+    manifest = generator.generate_abi_manifest(program)
+    print(generator.generate_js_host_shim(manifest))
+
+
+def cmd_wat_renderer_template(args):
+    """Emit JS renderer skeleton from generated WAT ABI manifest."""
+    program = _parse_program_from_file(args.file, args.lang)
+    generator = WATCodeGenerator()
+    manifest = generator.generate_abi_manifest(program)
+    print(generator.generate_renderer_template(manifest))
+
+
+def cmd_encoding_check(args):
+    """Validate UTF-8/no-mojibake policy for provided files."""
+    failed = False
+    for fpath in args.files:
+        try:
+            assert_clean_utf8_file(fpath)
+            print(f"[PASS] {fpath}")
+        except (OSError, UnicodeDecodeError, ValueError) as exc:
+            failed = True
+            print(f"[FAIL] {fpath}: {exc}", file=sys.stderr)
+    if failed:
+        sys.exit(1)
+
+
+def cmd_encoding_check_generated(args):
+    """Validate generated compiler outputs for encoding regressions."""
+    program = _parse_program_from_file(args.file, args.lang)
+    wat_generator = WATCodeGenerator()
+    py_source = PythonCodeGenerator().generate(program)
+    wat_source = wat_generator.generate(program)
+    abi_json = json.dumps(
+        wat_generator.generate_abi_manifest(program), ensure_ascii=False, indent=2
+    )
+
+    assert_clean_text_encoding("generated_python", py_source)
+    assert_clean_text_encoding("generated_wat", wat_source)
+    assert_clean_text_encoding("generated_abi_json", abi_json)
+    print("[PASS] generated_python")
+    print("[PASS] generated_wat")
+    print("[PASS] generated_abi_json")
+
+
+def cmd_build_wasm_bundle(args):
+    """Build deterministic WAT artifact bundle with atomic writes."""
+    program = _parse_program_from_file(args.file, args.lang)
+    orchestrator = BuildOrchestrator(args.out_dir)
+    outputs = orchestrator.build_from_program(program)
+    print(f"[PASS] {outputs.transpiled_python}")
+    print(f"[PASS] {outputs.wat}")
+    print(f"[PASS] {outputs.abi_manifest}")
+    print(f"[PASS] {outputs.host_shim_js}")
+    print(f"[PASS] {outputs.renderer_template_js}")
+    print(f"[PASS] {outputs.build_graph}")
+    print(f"[PASS] {outputs.build_lockfile}")
+
+
+def _maybe_dispatch_direct_file_run(argv):
+    """Dispatch `multilingual <file>.ml [--lang XX]` to `cmd_run`."""
+    if not argv:
+        return False
+
+    first = argv[0]
+    if first.startswith("-"):
+        return False
+    if not first.lower().endswith(".ml"):
+        return False
+
+    arg_parser = argparse.ArgumentParser(
+        prog="multilingual",
+        description="Execute a multilingual source file",
+    )
+    arg_parser.add_argument("file", help="Path to the source file")
+    arg_parser.add_argument(
+        "--lang", default=None,
+        help="Source language code (e.g., en, fr, hi). Auto-detect if omitted.",
+    )
+    args = arg_parser.parse_args(argv)
+    cmd_run(args)
+    return True
+
+
+def main():  # pylint: disable=too-many-statements
+    """Run the CLI entry point and dispatch subcommands."""
+    argv = sys.argv[1:]
+    if _maybe_dispatch_direct_file_run(argv):
+        return
+
+    parser = argparse.ArgumentParser(
+        prog="multilingual",
+        description=(
+            "Multilingual Programming Language CLI "
+            "(default command starts interactive REPL; "
+            "pass <file>.ml to run directly)"
+        ),
+    )
+    parser.add_argument(
+        "--version", action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # run subcommand
+    run_parser = subparsers.add_parser("run", help="Execute a source file")
+    run_parser.add_argument("file", help="Path to the source file")
+    run_parser.add_argument(
+        "--lang", default=None,
+        help="Source language code (e.g., en, fr, hi). Auto-detect if omitted.",
+    )
+
+    # repl subcommand
+    repl_parser = subparsers.add_parser("repl", help="Start interactive REPL")
+    repl_parser.add_argument(
+        "--lang", default=None,
+        help="Source language code (e.g., en, fr, hi). Auto-detect if omitted.",
+    )
+    repl_parser.add_argument(
+        "--show-python", action="store_true",
+        help="Display generated Python code before execution",
+    )
+    repl_parser.add_argument(
+        "--show-wat", action="store_true",
+        help="Display generated WAT (WebAssembly Text) code before execution",
+    )
+    repl_parser.add_argument(
+        "--show-rust", action="store_true",
+        help="Display generated Rust/Wasmtime bridge code before execution",
+    )
+
+    # compile subcommand
+    compile_parser = subparsers.add_parser(
+        "compile", help="Show generated Python code"
+    )
+    compile_parser.add_argument("file", help="Path to the source file")
+    compile_parser.add_argument(
+        "--lang", default=None,
+        help="Source language code (e.g., en, fr, hi). Auto-detect if omitted.",
+    )
+
+    # smoke subcommand
+    smoke_parser = subparsers.add_parser(
+        "smoke", help="Validate language pack(s)"
+    )
+    smoke_parser.add_argument(
+        "--lang", default="en",
+        help="Language code to validate (default: en)",
+    )
+    smoke_parser.add_argument(
+        "--all", action="store_true",
+        help="Validate all supported languages",
+    )
+
+    wat_abi_parser = subparsers.add_parser(
+        "wat-abi", help="Emit WAT ABI manifest JSON for a source file"
+    )
+    wat_abi_parser.add_argument("file", help="Path to the source file")
+    wat_abi_parser.add_argument(
+        "--lang", default=None,
+        help="Source language code (e.g., en, fr, hi). Auto-detect if omitted.",
+    )
+
+    wat_host_parser = subparsers.add_parser(
+        "wat-host-shim",
+        help="Emit JS host shim from WAT ABI manifest for a source file",
+    )
+    wat_host_parser.add_argument("file", help="Path to the source file")
+    wat_host_parser.add_argument(
+        "--lang", default=None,
+        help="Source language code (e.g., en, fr, hi). Auto-detect if omitted.",
+    )
+
+    wat_renderer_parser = subparsers.add_parser(
+        "wat-renderer-template",
+        help="Emit JS renderer skeleton from WAT ABI manifest for a source file",
+    )
+    wat_renderer_parser.add_argument("file", help="Path to the source file")
+    wat_renderer_parser.add_argument(
+        "--lang", default=None,
+        help="Source language code (e.g., en, fr, hi). Auto-detect if omitted.",
+    )
+
+    encoding_check_parser = subparsers.add_parser(
+        "encoding-check",
+        help="Validate UTF-8 and no-mojibake markers for files",
+    )
+    encoding_check_parser.add_argument("files", nargs="+", help="Files to validate")
+
+    encoding_generated_parser = subparsers.add_parser(
+        "encoding-check-generated",
+        help="Validate generated Python/WAT/ABI outputs for a source file",
+    )
+    encoding_generated_parser.add_argument("file", help="Path to the source file")
+    encoding_generated_parser.add_argument(
+        "--lang", default=None,
+        help="Source language code (e.g., en, fr, hi). Auto-detect if omitted.",
+    )
+
+    build_bundle_parser = subparsers.add_parser(
+        "build-wasm-bundle",
+        help="Build deterministic WAT artifacts (WAT, ABI, JS shim, renderer)",
+    )
+    build_bundle_parser.add_argument("file", help="Path to the source file")
+    build_bundle_parser.add_argument(
+        "--lang", default=None,
+        help="Source language code (e.g., en, fr, hi). Auto-detect if omitted.",
+    )
+    build_bundle_parser.add_argument(
+        "--out-dir", default="build/wasm",
+        help="Output directory for generated artifacts (default: build/wasm)",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "run":
+        cmd_run(args)
+    elif args.command == "repl":
+        cmd_repl(args)
+    elif args.command == "compile":
+        cmd_compile(args)
+    elif args.command == "smoke":
+        cmd_smoke(args)
+    elif args.command == "wat-abi":
+        cmd_wat_abi(args)
+    elif args.command == "wat-host-shim":
+        cmd_wat_host_shim(args)
+    elif args.command == "wat-renderer-template":
+        cmd_wat_renderer_template(args)
+    elif args.command == "encoding-check":
+        cmd_encoding_check(args)
+    elif args.command == "encoding-check-generated":
+        cmd_encoding_check_generated(args)
+    elif args.command == "build-wasm-bundle":
+        cmd_build_wasm_bundle(args)
+    else:
+        # Default: start REPL
+        args.lang = None
+        args.show_python = False
+        args.show_wat = False
+        args.show_rust = False
+        cmd_repl(args)
+
+
+if __name__ == "__main__":
+    main()

multilingualprogramming-0.6.0/multilingualprogramming/codegen/build_orchestrator.py

@@ -0,0 +1,137 @@
+#
+# SPDX-FileCopyrightText: 2026 John Samuel <johnsamuelwrites@gmail.com>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+
+"""Deterministic build orchestration for WAT artifact bundles."""
+
+import json
+import os
+import time
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+from multilingualprogramming.codegen.python_generator import PythonCodeGenerator
+from multilingualprogramming.codegen.wat_generator import WATCodeGenerator
+
+
+@dataclass
+class BuildOutputs:  # pylint: disable=too-many-instance-attributes
+    """Resolved output file paths for build artifacts."""
+
+    wat: Path
+    abi_manifest: Path
+    host_shim_js: Path
+    renderer_template_js: Path
+    transpiled_python: Path
+    build_graph: Path
+    build_lockfile: Path
+    build_lock: Path
+
+
+class BuildOrchestrator:  # pylint: disable=too-many-instance-attributes
+    """Atomic, lock-guarded, deterministic artifact build."""
+
+    def __init__(self, output_dir: str | Path):
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self.outputs = BuildOutputs(
+            wat=self.output_dir / "module.wat",
+            abi_manifest=self.output_dir / "abi_manifest.json",
+            host_shim_js=self.output_dir / "host_shim.js",
+            renderer_template_js=self.output_dir / "renderer_template.js",
+            transpiled_python=self.output_dir / "transpiled.py",
+            build_graph=self.output_dir / "build_graph.json",
+            build_lockfile=self.output_dir / "build.lock.json",
+            build_lock=self.output_dir / ".multilingual-build.lock",
+        )
+
+    def _acquire_lock(self, timeout_seconds: float = 10.0, poll_interval: float = 0.05):
+        start = time.perf_counter()
+        while True:
+            try:
+                fd = os.open(
+                    self.outputs.build_lock,
+                    os.O_CREAT | os.O_EXCL | os.O_WRONLY,
+                )
+                os.close(fd)
+                return
+            except FileExistsError:
+                if (time.perf_counter() - start) >= timeout_seconds:
+                    raise TimeoutError(
+                        f"Timeout acquiring build lock: {self.outputs.build_lock}"
+                    ) from None
+                time.sleep(poll_interval)
+
+    def _release_lock(self):
+        try:
+            self.outputs.build_lock.unlink()
+        except FileNotFoundError:
+            pass
+
+    @staticmethod
+    def _atomic_write_text(path: Path, content: str):
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with NamedTemporaryFile("w", encoding="utf-8", delete=False, dir=path.parent) as tmp:
+            tmp.write(content)
+            tmp_path = Path(tmp.name)
+        os.replace(tmp_path, path)
+
+    def build_from_program(self, program) -> BuildOutputs:
+        """Generate and atomically write all build artifacts from parsed Program."""
+        self._acquire_lock()
+        try:
+            wat_generator = WATCodeGenerator()
+            python_source = PythonCodeGenerator().generate(program)
+            wat_source = wat_generator.generate(program)
+            manifest = wat_generator.generate_abi_manifest(program)
+            host_shim = wat_generator.generate_js_host_shim(manifest)
+            renderer_template = wat_generator.generate_renderer_template(manifest)
+            source_digest = hashlib.sha256(python_source.encode("utf-8")).hexdigest()
+
+            build_graph = {
+                "version": 1,
+                "nodes": {
+                    "program": [],
+                    "transpiled_python": ["program"],
+                    "module_wat": ["program"],
+                    "abi_manifest": ["program", "module_wat"],
+                    "host_shim_js": ["abi_manifest"],
+                    "renderer_template_js": ["abi_manifest"],
+                },
+            }
+            build_lockfile = {
+                "version": 1,
+                "source_digest_sha256": source_digest,
+                "artifacts": {
+                    "transpiled_python": self.outputs.transpiled_python.name,
+                    "module_wat": self.outputs.wat.name,
+                    "abi_manifest": self.outputs.abi_manifest.name,
+                    "host_shim_js": self.outputs.host_shim_js.name,
+                    "renderer_template_js": self.outputs.renderer_template_js.name,
+                    "build_graph": self.outputs.build_graph.name,
+                },
+            }
+
+            self._atomic_write_text(self.outputs.transpiled_python, python_source)
+            self._atomic_write_text(self.outputs.wat, wat_source)
+            self._atomic_write_text(
+                self.outputs.abi_manifest,
+                json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True),
+            )
+            self._atomic_write_text(self.outputs.host_shim_js, host_shim)
+            self._atomic_write_text(self.outputs.renderer_template_js, renderer_template)
+            self._atomic_write_text(
+                self.outputs.build_graph,
+                json.dumps(build_graph, ensure_ascii=False, indent=2, sort_keys=True),
+            )
+            self._atomic_write_text(
+                self.outputs.build_lockfile,
+                json.dumps(build_lockfile, ensure_ascii=False, indent=2, sort_keys=True),
+            )
+            return self.outputs
+        finally:
+            self._release_lock()

multilingualprogramming-0.6.0/multilingualprogramming/codegen/encoding_guard.py

@@ -0,0 +1,50 @@
+#
+# SPDX-FileCopyrightText: 2026 John Samuel <johnsamuelwrites@gmail.com>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+
+"""Encoding guardrails for generated compiler/runtime artifacts."""
+
+from pathlib import Path
+
+_MOJIBAKE_MARKERS = (
+    "\ufffd",   # replacement character
+    "Ã",
+    "Â",
+    "—",
+    "–",
+    "“",
+    "”",
+    "‘",
+    "’",
+    "…",
+    "→",
+    "≥",
+)
+
+
+def detect_text_encoding_issues(text: str) -> list[str]:
+    """Return a list of encoding/mojibake issues detected in *text*."""
+    issues = []
+    if text.startswith("\ufeff"):
+        issues.append("utf8_bom_present")
+    for marker in _MOJIBAKE_MARKERS:
+        if marker in text:
+            issues.append(f"suspicious_marker:{marker}")
+    return issues
+
+
+def assert_clean_text_encoding(label: str, text: str) -> None:
+    """Raise ValueError when text contains BOM or mojibake markers."""
+    issues = detect_text_encoding_issues(text)
+    if issues:
+        joined = ", ".join(issues)
+        raise ValueError(f"{label} contains encoding issues: {joined}")
+
+
+def assert_clean_utf8_file(path: str | Path) -> None:
+    """Validate file can be decoded as UTF-8 and has no known mojibake markers."""
+    fpath = Path(path)
+    content = fpath.read_text(encoding="utf-8")
+    assert_clean_text_encoding(str(fpath), content)