@topy-ai/maggie 0.7.9 → 0.7.11

package/bundled-tools/clis/maggie_design.py

@@ -328,7 +328,7 @@ PHASES = [
         ],
     },
 ]
-DESIGN_JOB_PHASES = ("created", "preflight", "planned", "validated", "ready", "failed")
+DESIGN_JOB_PHASES = ("created", "preflight", "planned", "validated", "ready", "done", "failed")
 
 
 def existing_evidence(project: Path, target: dict[str, str]) -> list[str]:
@@ -506,7 +506,32 @@ def design_resume(project: Path, job_id: str) -> int:
     return run_design_job(job["urls"], project, job["clone_run"], force=True)[0]
 
 
-def in_place_job(project: Path, routes: list[str], force: bool = False) -> int:
+def _step_records(names: list[str]) -> list[dict[str, object]]:
+    return [{"name": name, "status": "pending", "evidence": None} for name in names]
+
+
+def design_step(project: Path, job_id: str, step: str, evidence: str) -> int:
+    """Record one piece of implementation evidence and make progress durable."""
+    path = design_job_path(project.resolve(), job_id)
+    if not path.exists():
+        raise ValueError(f"design job not found: {path}")
+    job = json.loads(path.read_text(encoding="utf-8"))
+    steps = job.get("steps", [])
+    target = next((item for item in steps if item.get("name") == step), None)
+    if target is None:
+        raise ValueError(f"unknown design step for {job_id}: {step}")
+    evidence_path = Path(evidence).expanduser().resolve()
+    if not evidence_path.exists():
+        raise ValueError(f"step evidence does not exist: {evidence_path}")
+    target.update({"status": "done", "evidence": str(evidence_path), "completedAt": datetime.now(timezone.utc).isoformat()})
+    job.setdefault("history", []).append({"event": "step-completed", "step": step, "evidence": str(evidence_path), "at": datetime.now(timezone.utc).isoformat()})
+    job["phase"] = "done" if all(item.get("status") == "done" for item in steps) else "ready"
+    save_design_job(project, job)
+    print(json.dumps({"jobId": job_id, "step": step, "status": target["status"], "phase": job["phase"], "evidence": str(evidence_path)}, indent=2))
+    return 0
+
+
+def in_place_job(project: Path, routes: list[str], force: bool = False, content_source: str = "") -> int:
     """Create a resumable redesign contract for existing first-party routes."""
     project = project.resolve()
     if not routes:
@@ -540,7 +565,13 @@ def in_place_job(project: Path, routes: list[str], force: bool = False) -> int:
                     break
         if not match:
             raise ValueError(f"existing route required for in-place redesign: {route}")
-        resolved_routes.append({"route": value, "source": str(match)})
+        catch_all = match.stem in {"[...slug]", "[[...slug]]"}
+        resolved_routes.append({
+            "route": value,
+            "source": str(match),
+            "resolution": "declared" if content_source else ("unproven" if catch_all else "direct-file"),
+            "contentSource": content_source or ("unproven catch-all route; declare the DB/content resolver before implementation" if catch_all else str(match)),
+        })
     digest = hashlib.sha256((str(project) + "\n" + "\n".join(routes)).encode()).hexdigest()[:12]
     job_id = f"in-place-{digest}"
     path = design_job_path(project, job_id)
@@ -558,7 +589,34 @@ def in_place_job(project: Path, routes: list[str], force: bool = False) -> int:
         "clone_run_required": False,
         "shared_tokens_required": True,
         "palette_change_allowed": False,
-        "required_steps": ["inspect-route", "apply-design-contract", "visual-review", "route-validation"],
+        "required_steps": ["inspect-route", "declare-content-source", "apply-design-contract", "visual-review", "route-validation"],
+        "steps": _step_records(["inspect-route", "declare-content-source", "apply-design-contract", "visual-review", "route-validation"]),
+        "history": [{"phase": "ready", "at": datetime.now(timezone.utc).isoformat()}],
+    }
+    save_design_job(project, job)
+    print(json.dumps(job, indent=2, ensure_ascii=False))
+    return 0
+
+
+def section_job(project: Path, route: str, section_id: str, force: bool = False) -> int:
+    """Create a focused design job with an unchanged-rest assertion."""
+    project = project.resolve()
+    if not route.startswith("/") or not section_id.strip():
+        raise ValueError("section mode requires a route starting with / and a section id")
+    contract = require_design_contract(project)
+    digest = hashlib.sha256((str(project) + "\n" + route + "\n" + section_id).encode()).hexdigest()[:12]
+    job_id = f"section-{digest}"
+    path = design_job_path(project, job_id)
+    if path.exists() and not force:
+        print(path.read_text(encoding="utf-8"), end="")
+        return 0
+    required = ["inspect-section", "capture-before", "implement-section", "capture-after", "assert-unchanged-rest", "route-validation"]
+    job = {
+        "id": job_id, "workflow": "maggie-design", "mode": "section-scoped", "phase": "ready",
+        "project": str(project), "route": route, "sectionId": section_id,
+        "design_contract": contract, "clone_run_required": False,
+        "scope": {"targetSection": section_id, "unchangedRestAssertion": "all non-target section content and structure hashes remain unchanged"},
+        "required_steps": required, "steps": _step_records(required),
         "history": [{"phase": "ready", "at": datetime.now(timezone.utc).isoformat()}],
     }
     save_design_job(project, job)
@@ -566,6 +624,25 @@ def in_place_job(project: Path, routes: list[str], force: bool = False) -> int:
     return 0
 
 
+def validate_section_evidence(before_path: Path, after_path: Path, section_id: str) -> dict[str, object]:
+    """Compare section-scoped evidence and prove the rest stayed unchanged."""
+    before = json.loads(before_path.resolve().read_text(encoding="utf-8"))
+    after = json.loads(after_path.resolve().read_text(encoding="utf-8"))
+    before_sections = {str(item.get("id")): item for item in before.get("sections", []) if isinstance(item, dict) and item.get("id")}
+    after_sections = {str(item.get("id")): item for item in after.get("sections", []) if isinstance(item, dict) and item.get("id")}
+    errors = []
+    if section_id not in before_sections or section_id not in after_sections:
+        errors.append("target section is missing from before or after evidence")
+    unchanged = sorted(section for section in before_sections.keys() & after_sections.keys() if section != section_id and before_sections[section] != after_sections[section])
+    if unchanged:
+        errors.append("non-target sections changed: " + ", ".join(unchanged))
+    missing_rest = sorted((before_sections.keys() ^ after_sections.keys()) - {section_id})
+    if missing_rest:
+        errors.append("non-target section set changed: " + ", ".join(missing_rest))
+    target_changed = section_id in before_sections and section_id in after_sections and before_sections[section_id] != after_sections[section_id]
+    return {"schemaVersion": "maggie-section-evidence.v1", "passed": not errors and target_changed, "targetSection": section_id, "targetChanged": target_changed, "unchangedRest": not unchanged and not missing_rest, "changedNonTargetSections": unchanged, "errors": errors + ([] if target_changed else ["target section did not change"]), "before": str(before_path.resolve()), "after": str(after_path.resolve())}
+
+
 def author_job(project: Path, route: str, purpose: str, audience: str, brief_file: Path | None, confirm: bool) -> int:
     """Create an original page brief without requiring an external source URL."""
     project = project.resolve()
@@ -592,6 +669,20 @@ def author_job(project: Path, route: str, purpose: str, audience: str, brief_fil
 
 
 def main() -> int:
+    if len(sys.argv) > 1 and sys.argv[1] in {"-h", "--help"}:
+        print("""usage: maggie_design.py <command> [options]
+
+commands:
+  run          run the complete clone-backed design workflow
+  in-place     create a resumable redesign contract for existing routes
+  section      create a section-scoped redesign contract
+  step         record completion evidence for one design step
+  status       show a design job and its per-step progress
+  resume       restart a failed design workflow
+  author       plan an original first-party page
+  reference-ui, init, validate-ui, rebrand, review
+""")
+        return 0
     if len(sys.argv) > 1 and sys.argv[1] == "reference-ui":
         command = argparse.ArgumentParser(description="Record sanitized blog/service UI evidence from a read-only reference project.")
         command.add_argument("--project", type=Path, default=Path.cwd())
@@ -653,13 +744,51 @@ def main() -> int:
         in_place = argparse.ArgumentParser(description="Create an in-place redesign contract for existing first-party routes.")
         in_place.add_argument("--project", type=Path, default=Path.cwd())
         in_place.add_argument("--route", action="append", required=True, help="existing route, for example /pricing")
+        in_place.add_argument("--content-source", default="", help="declared DB/content resolver or source manifest for catch-all routes")
         in_place.add_argument("--force", action="store_true")
         args = in_place.parse_args(sys.argv[2:])
         try:
-            return in_place_job(args.project, args.route, args.force)
+            return in_place_job(args.project, args.route, args.force, args.content_source)
         except (OSError, ValueError, json.JSONDecodeError) as error:
             print(f"BLOCKED: maggie-design in-place: {error}", file=sys.stderr)
             return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "section":
+        section = argparse.ArgumentParser(description="Create a section-scoped redesign contract with an unchanged-rest assertion.")
+        section.add_argument("--project", type=Path, default=Path.cwd())
+        section.add_argument("--route", required=True)
+        section.add_argument("--section-id", required=True)
+        section.add_argument("--force", action="store_true")
+        args = section.parse_args(sys.argv[2:])
+        try:
+            return section_job(args.project, args.route, args.section_id, args.force)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design section: {error}", file=sys.stderr)
+            return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "step":
+        step = argparse.ArgumentParser(description="Record evidence for one design workflow step.")
+        step.add_argument("job_id")
+        step.add_argument("--project", type=Path, default=Path.cwd())
+        step.add_argument("--step", required=True)
+        step.add_argument("--evidence", type=Path, required=True)
+        args = step.parse_args(sys.argv[2:])
+        try:
+            return design_step(args.project, args.job_id, args.step, str(args.evidence))
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design step: {error}", file=sys.stderr)
+            return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "section-validate":
+        section_validate = argparse.ArgumentParser(description="Validate before/after evidence for one section and assert the rest is unchanged.")
+        section_validate.add_argument("--before", type=Path, required=True)
+        section_validate.add_argument("--after", type=Path, required=True)
+        section_validate.add_argument("--section-id", required=True)
+        args = section_validate.parse_args(sys.argv[2:])
+        try:
+            result = validate_section_evidence(args.before, args.after, args.section_id)
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+            return 0 if result["passed"] else 1
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design section-validate: {error}", file=sys.stderr)
+            return 1
     if len(sys.argv) > 1 and sys.argv[1] == "author":
         author = argparse.ArgumentParser(description="Create an original first-party page brief and route plan.")
         author.add_argument("--project", type=Path, default=Path.cwd())

package/bundled-tools/clis/maggie_feedback.py

@@ -204,6 +204,9 @@ def main() -> int:
     parser.add_argument("--project", default=".")
     sub = parser.add_subparsers(dest="command", required=True)
     collect_parser = sub.add_parser("collect")
+    # Accept the project flag after the subcommand as shown in the public
+    # examples. argparse otherwise only accepts the global flag before it.
+    collect_parser.add_argument("--project", default=argparse.SUPPRESS)
     collect_parser.add_argument("--skill", default="")
     collect_parser.add_argument("--run-id", default="")
     collect_parser.add_argument("--run-report")

package/bundled-tools/clis/maggie_icon_inventory.py

@@ -10,11 +10,19 @@ from pathlib import Path
 
 SOURCE_EXTENSIONS = {".astro", ".css", ".html", ".jsx", ".js", ".json", ".svelte", ".tsx", ".ts", ".vue"}
 IGNORE_NAMES = {"icon", "icons", "true", "false", "null", "undefined"}
+NOISE_NAME = re.compile(r"^(?:inline-)?svg[-_]\d+$|^(?:solid|regular|brands|light|thin|duotone)[-_]\d+$|^\d+$", re.I)
+
+
+def normalize_name(name: str) -> str:
+    """Return the family-neutral name used for source/runtime comparison."""
+    value = name.strip().lower().replace("/", ":")
+    value = re.sub(r"^(?:phosphor|ph|font-awesome|fa|lucide):", "", value)
+    return value
 
 
 def _add(found: dict[str, set[str]], name: str, file: Path, evidence: str) -> None:
-    name = name.strip().lower()
-    if not name or name in IGNORE_NAMES or len(name) > 80 or not re.fullmatch(r"[a-z0-9][a-z0-9._:/-]*", name):
+    name = normalize_name(name)
+    if not name or name in IGNORE_NAMES or NOISE_NAME.fullmatch(name) or len(name) > 80 or not re.fullmatch(r"[a-z0-9][a-z0-9._:-]*", name):
         return
     found.setdefault(name, set()).add(f"{file.as_posix()}:{evidence}")
 
@@ -31,7 +39,7 @@ def source_icons(root: Path, source_dir: Path) -> dict[str, set[str]]:
             _add(found, match.group(1), relative, "named-property")
         for match in re.finditer(r"data-(?:icon|glyph)\s*=\s*[\"']([^\"']+)", text, re.I):
             _add(found, match.group(1), relative, "data-attribute")
-        for match in re.finditer(r"(?:ph|fa|lucide|icon)-([a-z0-9][a-z0-9-]*)", text, re.I):
+        for match in re.finditer(r"(?:ph|fa|lucide)-([a-z0-9][a-z0-9-]*)", text, re.I):
             _add(found, match.group(1), relative, "icon-class")
         for match in re.finditer(r"(?:phosphor|lucide|icon)[:/]([a-z0-9][a-z0-9-]*)", text, re.I):
             _add(found, match.group(1), relative, "icon-token")
@@ -49,10 +57,14 @@ def runtime_icons(root: Path, runtime_paths: list[Path]) -> tuple[set[str], dict
             continue
         text = path.read_text(encoding="utf-8", errors="replace")
         relative = path.relative_to(root.resolve()) if path.is_relative_to(root.resolve()) else path
-        for match in re.finditer(r"\.(?:ph|fa|lucide|icon)-([a-z0-9][a-z0-9-]*)\b", text, re.I):
-            name = match.group(1).lower(); names.add(name); evidence.setdefault(name, set()).add(f"{relative}:css-class")
+        for match in re.finditer(r"\.(?:ph|fa|lucide)-([a-z0-9][a-z0-9-]*)\b", text, re.I):
+            name = normalize_name(match.group(1))
+            if not NOISE_NAME.fullmatch(name):
+                names.add(name); evidence.setdefault(name, set()).add(f"{relative}:css-class")
         for match in re.finditer(r"(?:data-(?:icon|glyph)|icon)\s*=\s*[\"']([^\"']+)", text, re.I):
-            name = match.group(1).lower(); names.add(name); evidence.setdefault(name, set()).add(f"{relative}:runtime-map")
+            name = normalize_name(match.group(1))
+            if name not in IGNORE_NAMES and not NOISE_NAME.fullmatch(name):
+                names.add(name); evidence.setdefault(name, set()).add(f"{relative}:runtime-map")
     return names, evidence, font_files
 
 

package/bundled-tools/clis/maggie_release.py

@@ -127,6 +127,60 @@ def evidence_gate(project: Path, environment: str) -> dict:
     return {"name": "durable-site-evidence", "passed": not errors, "exitCode": 0 if not errors else 1, "result": {"passed": not errors, "errors": errors, "evidence": summaries}, "stderr": ""}
 
 
+def changed_surface_gate(project: Path) -> dict:
+    """Require visual/runtime evidence when a visitor-facing surface changed."""
+    try:
+        changed = subprocess.run(
+            ["git", "-C", str(project), "diff", "--name-only"],
+            capture_output=True, text=True, check=True,
+        ).stdout.splitlines()
+    except (OSError, subprocess.CalledProcessError):
+        return {"name": "changed-surface-evidence", "passed": True, "exitCode": 0,
+                "result": {"passed": True, "changed": False, "reason": "project is not a git worktree"}, "stderr": ""}
+    visitor_suffixes = {".astro", ".css", ".scss", ".html", ".jsx", ".tsx", ".js", ".ts", ".svg", ".png", ".jpg", ".jpeg", ".webp"}
+    surfaces = sorted(path for path in changed if Path(path).suffix.lower() in visitor_suffixes)
+    if not surfaces:
+        return {"name": "changed-surface-evidence", "passed": True, "exitCode": 0,
+                "result": {"passed": True, "changed": False, "surfaces": []}, "stderr": ""}
+
+    candidates = {
+        "iconInventory": (project / "docs/icon-inventory.json", project / ".maggie/icon-inventory.json"),
+        "renderEvidence": (project / "docs/deployment-canary.json", project / ".maggie/deployment-canary.json", project / "docs/rendered-canary.json", project / ".maggie/rendered-canary.json"),
+    }
+    errors: list[str] = []
+    evidence: dict[str, dict[str, object]] = {}
+    for name, paths in candidates.items():
+        path = next((candidate for candidate in paths if candidate.exists()), None)
+        if path is None:
+            errors.append(f"missing {name} evidence")
+            continue
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            errors.append(f"{name}: {exc}")
+            continue
+        passed = payload.get("passed") is True or payload.get("status") in {"pass", "passed"}
+        evidence[name] = {"path": str(path.relative_to(project)), "passed": passed}
+        if not passed:
+            errors.append(f"{name} is not passed")
+        if name == "renderEvidence":
+            render = payload.get("render", payload)
+            screenshots = render.get("screenshots", render.get("screenshotEvidence", [])) if isinstance(render, dict) else []
+            console_errors = render.get("consoleErrors", []) if isinstance(render, dict) else []
+            network_errors = render.get("networkErrors", []) if isinstance(render, dict) else []
+            placeholders = render.get("placeholderMatches", render.get("placeholders", [])) if isinstance(render, dict) else []
+            if not screenshots:
+                errors.append("renderEvidence has no screenshot evidence")
+            if console_errors:
+                errors.append("renderEvidence contains console errors")
+            if network_errors:
+                errors.append("renderEvidence contains network errors")
+            if placeholders:
+                errors.append("renderEvidence contains placeholder matches")
+    return {"name": "changed-surface-evidence", "passed": not errors, "exitCode": 0 if not errors else 1,
+            "result": {"passed": not errors, "changed": True, "surfaces": surfaces, "evidence": evidence, "errors": errors}, "stderr": ""}
+
+
 def editorial_gate(project: Path) -> dict:
     """Require explicit editorial approval for every launch category.
 
@@ -224,6 +278,7 @@ def main() -> int:
         parser.error(f"project directory does not exist: {project}")
 
     gates = []
+    gates.append(changed_surface_gate(project))
     gates.append(build_gate(project))
     for name, command in build_gates(project, args.environment, args.target, not args.skip_compatibility):
         gates.append(run_gate(name, command, project))

package/bundled-tools/clis/site_audit.py

@@ -9,9 +9,8 @@ import json
 import re
 import sys
 from pathlib import Path
-from urllib.parse import urljoin
-from html.parser import HTMLParser
 from urllib.parse import urljoin, urlparse
+from html.parser import HTMLParser
 from urllib.request import Request, urlopen
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
@@ -39,6 +38,10 @@ class PageParser(HTMLParser):
         self.visible_text = []
         self.hidden_depth = 0
         self.templates = set()
+        self._content_capture = []
+        self.headings = []
+        self.paragraphs = []
+        self.links = []
 
     def handle_starttag(self, tag, attrs):
         data = dict(attrs)
@@ -49,6 +52,8 @@ class PageParser(HTMLParser):
         if not self.hidden_depth:
             self.structure.append(["start", tag, {key: data[key] for key in
                 ("class", "id", "role", "href", "src", "data-template", "data-section", "data-i18n") if key in data}])
+            if tag in {"h1", "h2", "h3", "h4", "h5", "h6", "p", "a"}:
+                self._content_capture.append({"tag": tag, "parts": [], "href": data.get("href", "")})
         if tag == "html":
             self.lang = data.get("lang", "")
         if tag == "meta" and data.get("name"):
@@ -74,6 +79,15 @@ class PageParser(HTMLParser):
             self.images.append({"src": data.get("src", ""), "alt": data.get("alt")})
 
     def handle_endtag(self, tag):
+        if not self.hidden_depth and self._content_capture and self._content_capture[-1]["tag"] == tag:
+            capture = self._content_capture.pop()
+            text = " ".join("".join(capture["parts"]).split())
+            if text and tag.startswith("h"):
+                self.headings.append(text)
+            elif text and tag == "p":
+                self.paragraphs.append(text)
+            elif tag == "a" and capture.get("href"):
+                self.links.append({"href": capture["href"], "text": text})
         if tag in {"script", "style", "noscript"}:
             self.hidden_depth = max(0, self.hidden_depth - 1)
         elif not self.hidden_depth:
@@ -91,6 +105,8 @@ class PageParser(HTMLParser):
     def handle_data(self, data):
         if not self.hidden_depth and data.strip():
             self.visible_text.append(" ".join(data.split()))
+            for capture in self._content_capture:
+                capture["parts"].append(data)
         if self.in_title:
             self.title += data.strip()
         if self._jsonld is not None:
@@ -148,6 +164,22 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
             "structureHash": hashlib.sha256(json.dumps(page.structure, sort_keys=True).encode()).hexdigest(),
             "textHash": hashlib.sha256(" ".join(page.visible_text).encode()).hexdigest(),
         },
+        "contentContract": {
+            "headings": page.headings,
+            "paragraphs": page.paragraphs,
+            "links": [{"href": urljoin(url, link["href"]), "text": link["text"]} for link in page.links],
+            # Images and their alt text are readable content too. Keeping them
+            # in this contract prevents a prose-only migration from silently
+            # dropping the visual content of a page.
+            "images": [{"src": urljoin(url, image["src"]), "alt": image.get("alt")} for image in page.images],
+            "imageAlts": [image.get("alt") for image in page.images],
+            "contentHash": hashlib.sha256(json.dumps({
+                "headings": page.headings,
+                "paragraphs": page.paragraphs,
+                "links": [{"href": urljoin(url, link["href"]), "text": link["text"]} for link in page.links],
+                "images": [{"src": urljoin(url, image["src"]), "alt": image.get("alt")} for image in page.images],
+            }, sort_keys=True, ensure_ascii=False).encode()).hexdigest(),
+        },
         "robots": not robots or not any(token in {"noindex", "none", "nofollow"} for token in robots_tokens),
         "robots_directives": robots,
         "robots_conflict": len({token for token in robots_tokens if token in {"index", "noindex", "follow", "nofollow", "none"}} & {"index", "noindex"}) > 1 or len({token for token in robots_tokens if token in {"follow", "nofollow", "none"}} & {"follow", "nofollow"}) > 1,

package/bundled-tools/runtime/maggie_sections.py

@@ -12,6 +12,10 @@ from typing import Any, Iterable
 
 SCHEMA = "maggiedash-section-registry.v1"
 IDENTITY_SCHEMA = "maggiedash-section-identity.v1"
+TRANSLATION_REMAP_SCHEMA = "maggiedash-translation-remap.v1"
+FANOUT_SCHEMA = "maggiedash-section-fanout.v1"
+RECONCILE_SCHEMA = "maggiedash-reconcile.v1"
+LOCALE_SCHEMA = "maggiedash-locale-coverage.v1"
 
 
 def _validate_field(field: object, at: str, errors: list[str], *, nested: bool = False) -> None:
@@ -153,6 +157,72 @@ def copy_notes(registry: dict[str, Any], sections: object) -> dict[str, Any]:
     return {"passed": not errors, "errors": errors, "notes": notes}
 
 
+def validate_values(registry: dict[str, Any], sections: object) -> dict[str, Any]:
+    """Validate required scalar and repeated values, including pairs rows."""
+    if not isinstance(sections, list):
+        return {"passed": False, "errors": ["sections must be a list"]}
+    specs = {str(item.get("type")): item for item in registry.get("sections", []) if isinstance(item, dict)}
+    errors: list[str] = []
+
+    def check_fields(value: object, fields: list[dict[str, Any]], path: str) -> None:
+        for field in fields:
+            name = str(field.get("name"))
+            child = value.get(name) if isinstance(value, dict) else None
+            at = f"{path}.{name}"
+            if field.get("required") and (child is None or (isinstance(child, str) and not child.strip())):
+                errors.append(f"{at} is required and cannot be blank")
+            repeats = field.get("repeats")
+            if not isinstance(repeats, dict) or not isinstance(child, list):
+                continue
+            if not repeats["min"] <= len(child) <= repeats["max"]:
+                errors.append(f"{at} must contain {repeats['min']}-{repeats['max']} entries")
+            child_fields = [item for item in repeats.get("of", []) if isinstance(item, dict)]
+            for index, item in enumerate(child):
+                if isinstance(item, dict):
+                    check_fields(item, child_fields, f"{at}[{index}]")
+                elif len(child_fields) == 1 and child_fields[0].get("required") and not str(item).strip():
+                    errors.append(f"{at}[{index}] is required and cannot be blank")
+
+    for index, section in enumerate(sections):
+        if not isinstance(section, dict):
+            errors.append(f"sections[{index}] must be an object")
+            continue
+        spec = specs.get(str(section.get("type")))
+        if spec:
+            check_fields(section, [field for field in spec.get("fields", []) if isinstance(field, dict)], f"sections[{index}]")
+    return {"passed": not errors, "errors": errors}
+
+
+def translation_key_paths(page_id: str, sections: object, field_names: tuple[str, ...] = ("imageAlt",)) -> list[str]:
+    """Find stored section fields that need a locale sidecar value."""
+    if not isinstance(sections, list):
+        return []
+    paths: list[str] = []
+
+    def walk(value: object, path: str) -> None:
+        if isinstance(value, dict):
+            for key, child in value.items():
+                child_path = f"{path}.{key}"
+                if key in field_names and isinstance(child, str) and child.strip():
+                    paths.append(child_path)
+                walk(child, child_path)
+        elif isinstance(value, list):
+            for index, child in enumerate(value):
+                walk(child, f"{path}.{index}")
+
+    for index, section in enumerate(sections):
+        walk(section, f"page.{page_id}.sections.{section_key(section, index)}")
+    return paths
+
+
+def validate_locale_coverage(page_id: str, sections: object, translations: object, locales: Iterable[str]) -> dict[str, Any]:
+    """Require non-default locale rows for every declared translatable field."""
+    paths = translation_key_paths(page_id, sections)
+    values = translations if isinstance(translations, dict) else {}
+    missing = [{"locale": locale, "key": key} for locale in locales for key in paths if not isinstance(values.get(locale), dict) or not str(values[locale].get(key) or "").strip()]
+    return {"schemaVersion": LOCALE_SCHEMA, "passed": not missing, "pageId": page_id, "requiredKeys": paths, "missing": missing, "writePolicy": "section row and locale rows must be committed in one transaction"}
+
+
 def new_section_id(existing: Iterable[str] = ()) -> str:
     taken = set(existing)
     while True:
@@ -191,3 +261,73 @@ def section_id_migration(page_id: str, sections: list[dict[str, Any]]) -> dict[s
     identified = ensure_section_ids(sections)
     mappings = [{"from": f"page.{page_id}.sections.{index}.", "to": f"page.{page_id}.sections.{section['id']}."} for index, section in enumerate(identified)]
     return {"schemaVersion": IDENTITY_SCHEMA, "pageId": page_id, "sections": identified, "renameOrder": sorted(mappings, key=lambda item: len(item["from"]), reverse=True), "sourceChecksum": hashlib.sha256(json.dumps(sections, sort_keys=True, ensure_ascii=False, separators=(",", ":")).encode()).hexdigest()}
+
+
+def remap_translations(translations: object, mappings: object) -> dict[str, Any]:
+    """Move an existing translation keyspace without dropping unmapped keys."""
+    if not isinstance(translations, dict):
+        return {"schemaVersion": TRANSLATION_REMAP_SCHEMA, "passed": False, "errors": ["translations must be an object"]}
+    if isinstance(mappings, dict):
+        mappings = mappings.get("renameOrder") or mappings.get("mappings")
+    if not isinstance(mappings, list) or not mappings:
+        return {"schemaVersion": TRANSLATION_REMAP_SCHEMA, "passed": False, "errors": ["mappings must be a non-empty list"]}
+    valid = [item for item in mappings if isinstance(item, dict) and isinstance(item.get("from"), str) and isinstance(item.get("to"), str) and item["from"] and item["to"]]
+    if len(valid) != len(mappings):
+        return {"schemaVersion": TRANSLATION_REMAP_SCHEMA, "passed": False, "errors": ["every mapping needs non-empty from and to prefixes"]}
+    ordered = sorted(valid, key=lambda item: len(item["from"]), reverse=True)
+    result: dict[str, Any] = {}
+    applied: list[dict[str, str]] = []
+    unmapped: list[str] = []
+    collisions: list[str] = []
+    for key, value in translations.items():
+        source = str(key)
+        destination = next((item["to"] + source[len(item["from"]):] for item in ordered if source.startswith(item["from"])), None)
+        if destination is None:
+            destination = source
+            unmapped.append(source)
+        elif destination != source:
+            applied.append({"from": source, "to": destination})
+        if destination in result and result[destination] != value:
+            collisions.append(destination)
+            continue
+        result[destination] = value
+    errors = [f"translation key collision: {key}" for key in sorted(set(collisions))]
+    return {"schemaVersion": TRANSLATION_REMAP_SCHEMA, "passed": not errors, "errors": errors,
+            "translations": result, "applied": applied, "unmapped": sorted(unmapped),
+            "mappingCount": len(valid)}
+
+
+def validate_fanout(registry: dict[str, Any], fanout: object) -> dict[str, Any]:
+    """Ensure every registry type is wired through each host implementation surface.
+
+    A registry is declarative, but hosts still need a type union/schema,
+    blank-state logic, validation, text extraction, renderer, and editor
+    affordance. This contract makes a missing fan-out edit fail loudly.
+    """
+    if not isinstance(fanout, dict) or fanout.get("schemaVersion") != FANOUT_SCHEMA:
+        return {"schemaVersion": FANOUT_SCHEMA, "passed": False, "errors": [f"fanout schemaVersion must be {FANOUT_SCHEMA}"]}
+    types = {str(item.get("type")) for item in registry.get("sections", []) if isinstance(item, dict)}
+    surfaces = ("typeUnion", "sectionSchema", "blank", "validation", "textExtraction", "renderer", "editor")
+    missing: list[dict[str, str]] = []
+    for surface in surfaces:
+        values = fanout.get(surface)
+        declared = set(values) if isinstance(values, list) else set(values.keys()) if isinstance(values, dict) else set()
+        for section_type in sorted(types - declared):
+            missing.append({"type": section_type, "surface": surface})
+    return {"schemaVersion": FANOUT_SCHEMA, "passed": not missing, "errors": [f"{item['type']} missing {item['surface']} fan-out" for item in missing], "sectionTypes": sorted(types), "missing": missing}
+
+
+def reconcile_fields(current: object, desired: object) -> dict[str, Any]:
+    """Return an idempotent compare-and-set result for repair scripts."""
+    if not isinstance(current, dict) or not isinstance(desired, dict):
+        return {"schemaVersion": RECONCILE_SCHEMA, "passed": False, "errors": ["current and desired must be objects"]}
+    result = copy.deepcopy(current)
+    changed: list[str] = []
+    already_correct: list[str] = []
+    for key, value in desired.items():
+        if current.get(key) == value:
+            already_correct.append(str(key))
+        else:
+            result[key] = copy.deepcopy(value)
+            changed.append(str(key))
+    return {"schemaVersion": RECONCILE_SCHEMA, "passed": True, "changed": changed, "alreadyCorrect": already_correct, "result": result, "convergent": True}

package/bundled-tools/runtime/route_imports.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import hashlib
 import re
 from pathlib import Path
+from typing import Any
 
 
 IMPORT_RE = re.compile(r"(?:import\s+(?:[^;\n]*?\s+from\s+)?|export\s+[^;\n]*?\s+from\s+)[\"']([^\"']+)[\"']")
@@ -49,3 +50,25 @@ def imported_components(route: Path) -> list[dict[str, str | None]]:
             "fingerprint": hashlib.sha256(resolved.read_bytes()).hexdigest() if resolved else None,
         })
     return result
+
+
+def classify_bindings(bindings: list[dict[str, Any]], section_paths: set[str], page_paths: set[str]) -> dict[str, Any]:
+    """Classify component bindings against section and page route inventories.
+
+    Hosts supply the inventories from their renderer/database. This keeps the
+    report honest: a binding is not called "missing" merely because a legacy
+    component file still exists on disk.
+    """
+    records = []
+    for binding in bindings:
+        route = str(binding.get("route") or binding.get("path") or "")
+        component = str(binding.get("component") or "")
+        if route in section_paths or component in section_paths or binding.get("superseded") is True:
+            state = "superseded"
+        elif route in page_paths or binding.get("pageId"):
+            state = "migratable"
+        else:
+            state = "no-page-row"
+        records.append({**binding, "state": state})
+    counts = {state: sum(item["state"] == state for item in records) for state in ("superseded", "migratable", "no-page-row")}
+    return {"schemaVersion": "maggie-component-binding-audit.v1", "passed": not any(item["state"] == "no-page-row" for item in records), "counts": counts, "bindings": records}