ms-moe-maker 0.4.0__tar.gz

ms_moe_maker-0.4.0/MsMoEMaker.pyproj

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
+  <PropertyGroup>
+    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
+    <SchemaVersion>2.0</SchemaVersion>
+    <ProjectGuid>7c1f4a92-3e6d-4b18-9a4c-2f8b6d5e1a03</ProjectGuid>
+    <ProjectHome>.</ProjectHome>
+    <!-- F5 runs the CLI. Pass a recipe in the project's debug arguments. -->
+    <StartupFile>ms_moe_maker\__main__.py</StartupFile>
+    <SearchPath>.</SearchPath>
+    <WorkingDirectory>.</WorkingDirectory>
+    <OutputPath>.</OutputPath>
+    <Name>MsMoEMaker</Name>
+    <RootNamespace>ms_moe_maker</RootNamespace>
+    <InterpreterId>Global|PythonCore|3.11</InterpreterId>
+    <IsWindowsApplication>False</IsWindowsApplication>
+    <Description>Build a mixture of experts from deliberately chosen specialists.</Description>
+    <TestFramework>Pytest</TestFramework>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
+    <DebugSymbols>true</DebugSymbols>
+    <EnableUnmanagedDebugging>false</EnableUnmanagedDebugging>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
+    <DebugSymbols>true</DebugSymbols>
+    <EnableUnmanagedDebugging>false</EnableUnmanagedDebugging>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="ms_moe_maker\__init__.py" />
+    <Compile Include="ms_moe_maker\__main__.py" />
+    <Compile Include="ms_moe_maker\_describe.py" />
+    <Compile Include="ms_moe_maker\events.py" />
+    <Compile Include="ms_moe_maker\levers.py" />
+    <Compile Include="ms_moe_maker\manifest.py" />
+    <Compile Include="ms_moe_maker\recipe.py" />
+    <Compile Include="ms_moe_maker\runner.py" />
+    <Compile Include="ms_moe_maker\stages.py" />
+    <Compile Include="tests\test_cli.py" />
+    <Compile Include="tests\test_runner.py" />
+  </ItemGroup>
+  <ItemGroup>
+    <Folder Include="ms_moe_maker\" />
+    <Folder Include="tests\" />
+  </ItemGroup>
+  <ItemGroup>
+    <Content Include="pyproject.toml" />
+    <Content Include="README.md" />
+    <Content Include="recipe.example.yaml" />
+  </ItemGroup>
+  <ItemGroup>
+    <InterpreterReference Include="Global|PythonCore|3.11" />
+  </ItemGroup>
+  <Import Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\Python Tools\Microsoft.PythonTools.targets" />
+</Project>

ms_moe_maker-0.4.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: ms-moe-maker
+Version: 0.4.0
+Summary: Build a mixture of experts from deliberately chosen specialists. Not a coding model - a coding model shaped like your stack.
+Author: Chad Roesler
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/ChadRoesler/MsMoEMaker
+Project-URL: Repository, https://github.com/ChadRoesler/MsMoEMaker
+Project-URL: Bug Tracker, https://github.com/ChadRoesler/MsMoEMaker/issues
+Keywords: moe,mixture-of-experts,qwen,fine-tuning,gguf,llm
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# Ms.MoE
+
+**Multi-Specified Mixture of Experts.** Five deliberate experts instead of a
+hundred lottery tickets.
+
+The design thesis is the inverse of a frontier MoE. Instead of training many
+experts and hoping specialisation emerges — then fighting dead and collapsed
+experts with a load-balancing auxiliary loss — you *hand-assign* the domains.
+Every expert has a guaranteed constituency, so none of them can go dead,
+because none of them was speculative.
+
+The corollary is what makes it maintainable by one person: because each expert
+does exactly one thing, you can retrain **one** and re-splice without touching
+the others.
+
+> Not a coding model. A coding model shaped like *your* stack.
+
+The real product is the factory, not the model. Swap the expert list and
+someone else gets their own Ms.MoE.
+
+---
+
+## Install
+
+```bash
+pip install ms-moe-maker
+```
+
+That gets you the CLI and the contract — about a megabyte, no torch. The heavy
+machinery lives in the pipeline this forks, in whatever venv you train in. That
+split is the point: `ms-moe-maker validate` runs on a laptop, so you can check a
+recipe and see what it will cost before going near a machine that can run it.
+
+## Use
+
+```bash
+ms-moe-maker describe                  # one line of JSON, exit 0, no side effects
+ms-moe-maker validate recipe.yaml      # parse, check, translate — touches nothing
+ms-moe-maker build recipe.yaml         # run it
+ms-moe-maker build recipe.yaml --json  # JSON Lines on stdout, prose on stderr
+```
+
+`ms-moe-maker build recipe.yaml` is the literal command. It's what's in this README,
+it's what a person types, and it's exactly what `seren-theatre[stagehand]`
+forks — no separate API path with different defaults. If those two ever
+diverged, the hand-run path would rot, because it's the one with no automated
+users. Making them identical removes the possibility.
+
+## The recipe
+
+A build, as a document. The point is that you can hand it to someone who
+doesn't have your box and they get your run — that's the difference between
+"it works, look" and a result.
+
+```yaml
+schema_version: 1
+name: msmoe-coder-5x-dryrun
+size: 0.5B
+base: huihui-ai/Qwen2.5-Coder-0.5B-Instruct-abliterated
+
+experts:
+  - name: powershell
+    source: { kind: hf, repo: SaeedRahmani/codeparrot_github_code_powershell, text_field: code }
+  - name: python
+    source: { kind: stack, language: Python }
+  # ...
+
+budget:
+  target_steps: 150        # 1200 for a real rung; 150 is the shakedown
+  max_seq_length: 2048
+  per_device_batch: 4
+  grad_accum: 2
+```
+
+See `recipe.example.yaml` for the annotated version — every field carries the
+measurement that chose it.
+
+Budgets are in **tokens**, derived from steps. Capping documents instead looked
+like balance and wasn't: at 10,000 documents each, PowerShell received 4.3× the
+gradient updates Shell did, and a different LR curve besides.
+
+## Refusals — read this bit
+
+Right now `ms-moe-maker build` drives an existing pipeline script by setting
+environment variables and forking it. That script exposes sixteen levers. A
+recipe declares far more than sixteen things.
+
+So the naive wrapper would accept `per_device_batch: 8`, run the build at 4,
+and report success — leaving you with a document that *looks* authoritative and
+silently isn't. That's the worst possible place to put that trap, in the one
+file whose entire selling point is reproducing someone else's run.
+
+**So a recipe field is honoured, or the build refuses. Never ignored.**
+
+The check isn't "is there a lever" — it's "will the run actually do what the
+document says". Ms.MoE reads the pipeline's own constants statically (via
+`ast`, never importing — importing it would cost you a CUDA context) and
+compares each field against the value that will really be used. Agreement is
+silence. Only disagreement refuses.
+
+```
+$ ms-moe-maker build recipe.yaml
+   2 recipe field(s) cannot be honoured by fraunkenstein_universal.py:
+     · budget.per_device_batch=8 cannot be applied: the pipeline uses 4 from
+       PER_DEVICE_BATCH and exposes no environment lever for it.
+     · gates.main_evals='manual' cannot be honoured: the pipeline runs end to
+       end with no stage boundary a gate could pause at.
+   REFUSED - nothing was run.
+```
+
+`--allow-refusals` proceeds anyway. The refusals are recorded in the run
+manifest either way, because the person who needs to know a lever was ignored
+is the one reading the dashboard six hours later, not the one who saw the
+terminal at kickoff.
+
+**The refusal list is the roadmap.** Each entry is a field somebody wanted to
+set and couldn't — which is exactly the priority order for pulling that part of
+the script into a real stage. When the list is empty, the decomposition is
+finished, and nobody had to guess when.
+
+## The run manifest
+
+A build writes `msmoe-run.json` into its run directory: what the run is, the
+ordered stage list, each stage's status and artifact, and any refusals.
+
+That file is the **only** interface between this package and any viewer.
+Nothing imports anything. `seren-theatre` reads the manifest when it's there
+and falls back to reading the directory when it isn't — so an instrumented run
+is exact and an uninstrumented directory still works. Neither package is
+required, and neither knows the other exists.
+
+## Events
+
+Under `--json`: one JSON object per line on stdout, prose on stderr, never
+interleaved.
+
+| event | when |
+|---|---|
+| `started` | the build begins; carries the resolved env and run dir |
+| `stage` | a stage changes status |
+| `progress` | something worth knowing inside a stage |
+| `refused` | recipe fields that couldn't be honoured |
+| `warning` / `error` | trouble |
+| `done` | terminal, with `ok` |
+
+Every line is flushed. A consumer following a six-hour build through a pipe
+would otherwise see nothing until the buffer filled — and that looks exactly
+like a hang.
+
+## Status
+
+The stage machinery, contract and CLI are real. The pipeline itself is still
+the original 2483-line script, driven from the outside — **wrap-then-carve**.
+The contract is the product; the internals move behind it without anything
+downstream noticing.
+
+## Licence
+
+GPL-3.0-only.

ms_moe_maker-0.4.0/README.md

@@ -0,0 +1,159 @@
+# Ms.MoE
+
+**Multi-Specified Mixture of Experts.** Five deliberate experts instead of a
+hundred lottery tickets.
+
+The design thesis is the inverse of a frontier MoE. Instead of training many
+experts and hoping specialisation emerges — then fighting dead and collapsed
+experts with a load-balancing auxiliary loss — you *hand-assign* the domains.
+Every expert has a guaranteed constituency, so none of them can go dead,
+because none of them was speculative.
+
+The corollary is what makes it maintainable by one person: because each expert
+does exactly one thing, you can retrain **one** and re-splice without touching
+the others.
+
+> Not a coding model. A coding model shaped like *your* stack.
+
+The real product is the factory, not the model. Swap the expert list and
+someone else gets their own Ms.MoE.
+
+---
+
+## Install
+
+```bash
+pip install ms-moe-maker
+```
+
+That gets you the CLI and the contract — about a megabyte, no torch. The heavy
+machinery lives in the pipeline this forks, in whatever venv you train in. That
+split is the point: `ms-moe-maker validate` runs on a laptop, so you can check a
+recipe and see what it will cost before going near a machine that can run it.
+
+## Use
+
+```bash
+ms-moe-maker describe                  # one line of JSON, exit 0, no side effects
+ms-moe-maker validate recipe.yaml      # parse, check, translate — touches nothing
+ms-moe-maker build recipe.yaml         # run it
+ms-moe-maker build recipe.yaml --json  # JSON Lines on stdout, prose on stderr
+```
+
+`ms-moe-maker build recipe.yaml` is the literal command. It's what's in this README,
+it's what a person types, and it's exactly what `seren-theatre[stagehand]`
+forks — no separate API path with different defaults. If those two ever
+diverged, the hand-run path would rot, because it's the one with no automated
+users. Making them identical removes the possibility.
+
+## The recipe
+
+A build, as a document. The point is that you can hand it to someone who
+doesn't have your box and they get your run — that's the difference between
+"it works, look" and a result.
+
+```yaml
+schema_version: 1
+name: msmoe-coder-5x-dryrun
+size: 0.5B
+base: huihui-ai/Qwen2.5-Coder-0.5B-Instruct-abliterated
+
+experts:
+  - name: powershell
+    source: { kind: hf, repo: SaeedRahmani/codeparrot_github_code_powershell, text_field: code }
+  - name: python
+    source: { kind: stack, language: Python }
+  # ...
+
+budget:
+  target_steps: 150        # 1200 for a real rung; 150 is the shakedown
+  max_seq_length: 2048
+  per_device_batch: 4
+  grad_accum: 2
+```
+
+See `recipe.example.yaml` for the annotated version — every field carries the
+measurement that chose it.
+
+Budgets are in **tokens**, derived from steps. Capping documents instead looked
+like balance and wasn't: at 10,000 documents each, PowerShell received 4.3× the
+gradient updates Shell did, and a different LR curve besides.
+
+## Refusals — read this bit
+
+Right now `ms-moe-maker build` drives an existing pipeline script by setting
+environment variables and forking it. That script exposes sixteen levers. A
+recipe declares far more than sixteen things.
+
+So the naive wrapper would accept `per_device_batch: 8`, run the build at 4,
+and report success — leaving you with a document that *looks* authoritative and
+silently isn't. That's the worst possible place to put that trap, in the one
+file whose entire selling point is reproducing someone else's run.
+
+**So a recipe field is honoured, or the build refuses. Never ignored.**
+
+The check isn't "is there a lever" — it's "will the run actually do what the
+document says". Ms.MoE reads the pipeline's own constants statically (via
+`ast`, never importing — importing it would cost you a CUDA context) and
+compares each field against the value that will really be used. Agreement is
+silence. Only disagreement refuses.
+
+```
+$ ms-moe-maker build recipe.yaml
+   2 recipe field(s) cannot be honoured by fraunkenstein_universal.py:
+     · budget.per_device_batch=8 cannot be applied: the pipeline uses 4 from
+       PER_DEVICE_BATCH and exposes no environment lever for it.
+     · gates.main_evals='manual' cannot be honoured: the pipeline runs end to
+       end with no stage boundary a gate could pause at.
+   REFUSED - nothing was run.
+```
+
+`--allow-refusals` proceeds anyway. The refusals are recorded in the run
+manifest either way, because the person who needs to know a lever was ignored
+is the one reading the dashboard six hours later, not the one who saw the
+terminal at kickoff.
+
+**The refusal list is the roadmap.** Each entry is a field somebody wanted to
+set and couldn't — which is exactly the priority order for pulling that part of
+the script into a real stage. When the list is empty, the decomposition is
+finished, and nobody had to guess when.
+
+## The run manifest
+
+A build writes `msmoe-run.json` into its run directory: what the run is, the
+ordered stage list, each stage's status and artifact, and any refusals.
+
+That file is the **only** interface between this package and any viewer.
+Nothing imports anything. `seren-theatre` reads the manifest when it's there
+and falls back to reading the directory when it isn't — so an instrumented run
+is exact and an uninstrumented directory still works. Neither package is
+required, and neither knows the other exists.
+
+## Events
+
+Under `--json`: one JSON object per line on stdout, prose on stderr, never
+interleaved.
+
+| event | when |
+|---|---|
+| `started` | the build begins; carries the resolved env and run dir |
+| `stage` | a stage changes status |
+| `progress` | something worth knowing inside a stage |
+| `refused` | recipe fields that couldn't be honoured |
+| `warning` / `error` | trouble |
+| `done` | terminal, with `ok` |
+
+Every line is flushed. A consumer following a six-hour build through a pipe
+would otherwise see nothing until the buffer filled — and that looks exactly
+like a hang.
+
+## Status
+
+The stage machinery, contract and CLI are real. The pipeline itself is still
+the original 2483-line script, driven from the outside — **wrap-then-carve**.
+The contract is the product; the internals move behind it without anything
+downstream noticing.
+
+## Licence
+
+GPL-3.0-only.

ms_moe_maker-0.4.0/ms_moe_maker/__init__.py

@@ -0,0 +1,28 @@
+"""Ms.MoE - Multi-Specified Mixture of Experts.
+
+Five deliberate experts instead of a hundred lottery tickets. The design thesis
+is the INVERSE of a frontier MoE: hand-assign the domains so every expert has a
+guaranteed constituency, which eliminates dead and collapsed experts by
+construction rather than fighting them with a load-balancing auxiliary loss.
+Because each expert does exactly one thing, you can retrain ONE and re-splice
+without touching the others - which is what makes it maintainable by one
+person.
+
+The real product is the factory, not the model. Swap the expert list and
+someone else gets their own Ms.MoE, shaped like THEIR stack.
+
+This package deliberately depends on nothing of Seren's. seren-theatre can
+watch a run, and seren-theatre[stagehand] can start one, but the arrow only
+points that way - and even then the two never speak, they share a directory.
+Opt in, never opt out.
+"""
+from __future__ import annotations
+
+try:
+    from ._version import version as __version__
+except Exception:  # noqa: BLE001 - source checkout without a build
+    __version__ = "0.0.0+unknown"
+
+from ._describe import DESCRIBE, NAME  # noqa: F401  (stdlib-only, safe here)
+
+__all__ = ["DESCRIBE", "NAME", "__version__"]

ms_moe_maker-0.4.0/ms_moe_maker/__main__.py

@@ -0,0 +1,253 @@
+"""The ms-moe-maker CLI - the command stagehand forks and a person types.
+
+Three verbs:
+
+    ms-moe-maker describe                     one line of JSON, exit 0, no side effects
+    ms-moe-maker validate recipe.yaml         parse + check, touching nothing
+    ms-moe-maker build recipe.yaml            translate, fork the pipeline, report
+
+`ms-moe-maker build recipe.yaml` is deliberately the literal string in the README and
+the literal string seren-theatre[stagehand] forks. Not a Python API call, not
+an internal entry point with different defaults - the same command. If the two
+ever diverge, the hand-run path is the one that rots, because it is the one
+with no automated users; making them identical removes the possibility.
+
+--describe is scanned before argparse for the same reason every Seren installer
+does it: it has to answer on a broken install, so nothing may run first.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from ._describe import DESCRIBE
+from .events import Events
+
+
+def _force_utf8_stdio() -> None:
+    """UTF-8 regardless of console codepage. Windows defaults to legacy, and
+    the pipeline prints emoji milestones - a UnicodeEncodeError mid-build would
+    kill a run over a decorative character."""
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+        except (AttributeError, ValueError):
+            pass
+
+
+def _find_pipeline(explicit: str | None, recipe_path: Path,
+                   required: bool) -> Path | None:
+    """Locate fraunkenstein_universal.py. None if absent and not required.
+
+    Looked up rather than assumed, and reported when missing, because "wrapped
+    a script that isn't there" should be one clear error and not a traceback
+    from subprocess. Order: --pipeline, beside the recipe, cwd, then upward.
+
+    `required` is the difference between the two verbs, and it is not a
+    convenience:
+
+      build    - REQUIRED. There is nothing to fork without it.
+      validate - OPTIONAL. The README promises `ms-moe-maker validate` runs on a
+                 laptop with no GPU so you can check a recipe BEFORE going
+                 near a machine that can run it. Demanding the pipeline made
+                 that promise false: a stranger with a recipe and no checkout
+                 got "could not find fraunkenstein_universal.py" and no
+                 validation at all. Recipe SHAPE is checkable on its own; only
+                 the refusal analysis needs a pipeline to compare against.
+
+    An explicit --pipeline that does not exist is always an error, for either
+    verb. Being told where it is and being wrong is different from not saying.
+    """
+    from .levers import DEFAULT_PIPELINE
+
+    if explicit:
+        p = Path(explicit)
+        if not p.is_file():
+            raise SystemExit(f"--pipeline {p} does not exist")
+        return p.resolve()
+
+    for candidate in (recipe_path.parent / DEFAULT_PIPELINE,
+                      Path.cwd() / DEFAULT_PIPELINE):
+        if candidate.is_file():
+            return candidate.resolve()
+    for parent in [Path.cwd(), *Path.cwd().parents]:
+        candidate = parent / DEFAULT_PIPELINE
+        if candidate.is_file():
+            return candidate.resolve()
+    if required:
+        raise SystemExit(
+            f"could not find {DEFAULT_PIPELINE}. Pass --pipeline PATH, or run "
+            f"from the directory that holds it.")
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    _force_utf8_stdio()
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    # Before argparse: zero side effects, works half-installed.
+    if "--describe" in argv or (argv and argv[0] == "describe"):
+        print(json.dumps(DESCRIBE))
+        return 0
+
+    ap = argparse.ArgumentParser(
+        prog="ms-moe-maker",
+        description="Build a mixture of experts from a recipe.")
+    ap.add_argument("command", choices=["build", "validate", "describe"])
+    ap.add_argument("recipe", nargs="?", help="path to the recipe .yaml")
+    ap.add_argument("--pipeline", default=None,
+                    help="path to fraunkenstein_universal.py (default: found "
+                         "beside the recipe, then upward from cwd)")
+    ap.add_argument("--json", action="store_true",
+                    help="JSON Lines events on stdout, prose on stderr")
+    ap.add_argument("--python", default=None,
+                    help="interpreter to run the pipeline with (default: the "
+                         "one running ms-moe-maker). Use this when the trainer lives "
+                         "in a different venv - which is the normal case, "
+                         "since ms-moe-maker is deliberately small and torch is not.")
+    ap.add_argument("--dryrun", action="store_true",
+                    help="FRAUNK_DRYRUN=1 - the whole pipeline, small")
+    ap.add_argument("--force", action="store_true",
+                    help="FRAUNK_FORCE=1 - redo stages whose artifacts exist")
+    ap.add_argument("--allow-refusals", action="store_true",
+                    help="run even though some recipe fields cannot be "
+                         "honoured. They are recorded in the manifest either "
+                         "way; this only removes the stop.")
+    a = ap.parse_args(argv)
+
+    ev = Events(enabled=a.json)
+
+    if a.command == "describe":
+        print(json.dumps(DESCRIBE))
+        return 0
+
+    if not a.recipe:
+        ap.error("a recipe path is required")
+
+    from .recipe import load, resolve, validate
+
+    recipe_path = Path(a.recipe).resolve()
+    try:
+        rec, parse_warns = load(str(recipe_path))
+    except Exception as exc:  # noqa: BLE001 - the message IS the product
+        ev.error("parse", str(exc))
+        ev.say(f"FAILED to parse {recipe_path}: {exc}")
+        return 2
+
+    errs, warns = validate(rec)
+    warns = parse_warns + warns
+    for w in warns:
+        ev.warning(w)
+        ev.say(f"   WARN  {w}")
+    for e in errs:
+        ev.error("validate", e)
+        ev.say(f"   ERROR {e}")
+    if errs:
+        ev.done(ok=False, stage="validate")
+        return 1
+
+    # RESOLVED BEFORE THE PIPELINE LOOKUP, on purpose. Both are explicit
+    # arguments, and an explicit argument that is wrong should say so no matter
+    # what else is also missing - same rule as --pipeline. Reporting "could not
+    # find fraunkenstein_universal.py" to someone who mistyped --python sends
+    # them to fix the wrong thing.
+    #
+    # MSMOE_PYTHON as well as --python: the interpreter is a property of the
+    # BOX, not of the run, so it belongs somewhere you set once. Same shape as
+    # the family's SEREN_<X>_* levers - a flag for the one-off, an env var for
+    # the machine.
+    interpreter = a.python or os.environ.get("MSMOE_PYTHON") or None
+    if interpreter:
+        ipath = Path(interpreter)
+        if not ipath.is_file():
+            raise SystemExit(f"--python {ipath} does not exist")
+        # abspath, NEVER resolve(). A venv's bin/python is a SYMLINK to the
+        # base interpreter, and resolving it throws the venv away: you asked
+        # for /lab/bin/python and got /usr/bin/python3.12, whose sys.prefix is
+        # /usr and whose site-packages has none of your training deps. The
+        # failure then reads as "No module named 'torch'" from an interpreter
+        # you never named, which is about as misleading as it gets.
+        #
+        # Measured: running the symlink gives sys.prefix=/tmp/venvtest;
+        # running its target gives sys.prefix=/usr. Same file, different venv.
+        # abspath normalises the path without following the link.
+        interpreter = os.path.abspath(str(ipath))
+
+    pipeline = _find_pipeline(a.pipeline, recipe_path,
+                              required=(a.command == "build"))
+
+    from .levers import Translation, translate
+
+    if pipeline is None:
+        # Recipe-only validation. Say so LOUDLY rather than reporting a clean
+        # bill of health: "valid" and "valid, and nothing checked whether the
+        # pipeline can honour it" are different answers, and quietly giving
+        # the first when you mean the second is how a document that lies gets
+        # blessed on its way out the door.
+        tr = Translation()
+        no_pipeline_note = (
+            "no pipeline found, so ONLY the recipe's own shape was checked. "
+            "Refusals could not be computed - run this again beside "
+            "fraunkenstein_universal.py, or pass --pipeline PATH, to find out "
+            "whether a build would actually honour these fields.")
+        ev.warning(no_pipeline_note)
+    else:
+        no_pipeline_note = ""
+        tr = translate(rec, pipeline, force=a.force)
+
+    if tr.refusals:
+        ev.refused(tr.refusals)
+        ev.say("")
+        ev.say(f"   {len(tr.refusals)} recipe field(s) cannot be honoured by "
+               f"{pipeline.name}:")
+        for r in tr.refusals:
+            ev.say(f"     · {r}")
+        ev.say("")
+        ev.say("   These are not warnings. A recipe is a document you hand to "
+               "someone so they get YOUR run, and a field that is silently "
+               "ignored makes it a document that lies. Fix the recipe, carve "
+               "the stage out, or pass --allow-refusals to proceed knowing "
+               "the build will not match the file.")
+
+    if a.command == "validate":
+        eff = resolve(rec)
+        ev.emit("resolved", **eff)
+        ev.say("")
+        ev.say(f"Ms.MoE recipe  {rec.name}  [{eff['recipe_id']}]")
+        ev.say(f"   pipeline {pipeline if pipeline else '(none found)'}")
+        ev.say(f"   honoured {len(tr.agreed)} field(s), "
+               f"{len(tr.env)} env lever(s) set")
+        ev.say(f"   refused  {len(tr.refusals)} field(s)")
+        if no_pipeline_note:
+            ev.say("")
+            ev.say(f"   NOTE  {no_pipeline_note}")
+        ok = not tr.refusals
+        ev.done(ok=ok, refusals=len(tr.refusals), agreed=len(tr.agreed),
+                env=tr.env, pipeline=str(pipeline) if pipeline else None,
+                # The consumer needs to be able to tell "no refusals" from
+                # "refusals were never computed". Same key set either way, one
+                # honest flag - the alternative is a caller inferring depth of
+                # analysis from an empty list, which it cannot do.
+                refusals_checked=pipeline is not None)
+        return 0 if ok else 1
+
+    # build
+    if tr.refusals and not a.allow_refusals:
+        ev.done(ok=False, stage="translate", refusals=len(tr.refusals))
+        ev.say("   REFUSED - nothing was run.")
+        return 3
+
+    from .runner import Runner
+
+    if interpreter:
+        ev.say(f"   pipeline interpreter: {interpreter}")
+    runner = Runner(rec, pipeline, tr, ev, cwd=pipeline.parent,
+                    dryrun=a.dryrun, python=interpreter)
+    return runner.run()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())