@topy-ai/maggie 0.6.9 → 0.7.1

package/bundled-tools/clis/maggie_sitemap.py

@@ -10,7 +10,7 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
-from maggie_sitemap import build_plan, parse_routes, validate_plan_data  # noqa: E402
+from maggie_sitemap import agent_files, build_plan, parse_routes, validate_plan_data  # noqa: E402
 
 
 def write_json(path: str, value: dict) -> None:
@@ -31,6 +31,12 @@ def main() -> int:
     plan.add_argument("--output", required=True)
     validate = sub.add_parser("validate")
     validate.add_argument("--plan", required=True)
+    validate.add_argument("--strict-semantic", action="store_true")
+    agent = sub.add_parser("agent-files")
+    agent.add_argument("--origin", required=True)
+    agent.add_argument("--routes-file", required=True)
+    agent.add_argument("--output-dir", required=True)
+    agent.add_argument("--locale", default="en")
     apply = sub.add_parser("apply")
     apply.add_argument("--plan", required=True)
     apply.add_argument("--public-dir", required=True)
@@ -65,9 +71,17 @@ def main() -> int:
                     restored += 1
             print(json.dumps({"status": "rolled-back", "restored": restored}, indent=2))
             return 0
+        if args.command == "agent-files":
+            output = Path(args.output_dir)
+            output.mkdir(parents=True, exist_ok=True)
+            files = agent_files(parse_routes(Path(args.routes_file).read_text(encoding="utf-8")), args.origin, args.locale)
+            for name, content in files.items():
+                (output / name).write_text(content, encoding="utf-8")
+            print(json.dumps({"status": "generated", "locale": args.locale, "files": [str(output / name) for name in files]}, indent=2))
+            return 0
         plan_value = json.loads(Path(args.plan).read_text(encoding="utf-8"))
         if args.command == "validate":
-            result = validate_plan_data(plan_value)
+            result = validate_plan_data(plan_value, args.strict_semantic)
             print(json.dumps(result, indent=2))
             return 0 if result["status"] == "pass" else 1
         if not args.confirm:

package/bundled-tools/clis/site_audit.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import re
 import sys
@@ -15,6 +16,7 @@ from urllib.request import Request, urlopen
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from content_localization import MARKETS, parse_locale, valid_locale  # noqa: E402
+import site_baseline
 
 
 class PageParser(HTMLParser):
@@ -33,9 +35,20 @@ class PageParser(HTMLParser):
         self.images = []
         self.hreflang = []
         self.robots_directives = []
+        self.structure = []
+        self.visible_text = []
+        self.hidden_depth = 0
+        self.templates = set()
 
     def handle_starttag(self, tag, attrs):
         data = dict(attrs)
+        if data.get("data-template"):
+            self.templates.add(data["data-template"])
+        if tag in {"script", "style", "noscript"}:
+            self.hidden_depth += 1
+        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 == "html":
             self.lang = data.get("lang", "")
         if tag == "meta" and data.get("name"):
@@ -61,6 +74,10 @@ class PageParser(HTMLParser):
             self.images.append({"src": data.get("src", ""), "alt": data.get("alt")})
 
     def handle_endtag(self, tag):
+        if tag in {"script", "style", "noscript"}:
+            self.hidden_depth = max(0, self.hidden_depth - 1)
+        elif not self.hidden_depth:
+            self.structure.append(["end", tag])
         if tag == "title":
             self.in_title = False
         if tag == "script" and self._jsonld is not None:
@@ -72,25 +89,35 @@ class PageParser(HTMLParser):
             self._jsonld = None
 
     def handle_data(self, data):
+        if not self.hidden_depth and data.strip():
+            self.visible_text.append(" ".join(data.split()))
         if self.in_title:
             self.title += data.strip()
         if self._jsonld is not None:
             self._jsonld.append(data)
 
 
-def fetch(url: str) -> tuple[int, str, str]:
+def fetch(url: str, evidence: dict | None = None) -> tuple[int, str, str]:
     request = Request(url, headers={"User-Agent": "AI-CMO-Skills-Audit/0.1"})
     with urlopen(request, timeout=15) as response:
-        body = response.read(2_000_000).decode("utf-8", "replace")
+        raw = response.read(2_000_001)
+        if len(raw) > 2_000_000:
+            raise ValueError("response exceeds audit size limit")
+        body = raw.decode(response.headers.get_content_charset() or "utf-8", "replace")
+        if evidence is not None:
+            evidence.update({"finalUrl": response.geturl(),
+                             "xRobotsTag": response.headers.get_all("X-Robots-Tag", [])})
         return response.status, response.headers.get_content_type(), body
 
 
-def audit_page(url: str, html: str, status: int, content_type: str, expected_languages: set[str] | None = None) -> dict:
+def audit_page(url: str, html: str, status: int, content_type: str, expected_languages: set[str] | None = None, response_evidence: dict | None = None) -> dict:
     page = PageParser()
     page.feed(html)
     canonical = urljoin(url, page.canonical) if page.canonical else ""
-    robots = page.robots_directives
+    response_evidence = response_evidence or {"finalUrl": url, "xRobotsTag": []}
+    robots = page.robots_directives + [value.lower() for value in response_evidence["xRobotsTag"]]
     robots_tokens = [token.strip() for directive in robots for token in directive.split(",")]
+    robots_tokens = [token.rsplit(":", 1)[-1].strip() for token in robots_tokens]
     return {
         "url": url,
         "status": status,
@@ -109,13 +136,45 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
         "canonical_value": canonical,
         "image_count": len(page.images),
         "language": parse_locale(page.lang)[0],
+        "declaredLocale": page.lang,
+        "template": next(iter(page.templates)) if len(page.templates) == 1 else "unknown",
+        "evidence": {"structural": "captured", "rendered": "not_run", "behavioral": "not_run"},
         "hreflang": page.hreflang,
+        "contract": {
+            "response": response_evidence,
+            "title": page.title, "meta": page.meta, "canonical": canonical,
+            "lang": page.lang, "hreflang": page.hreflang, "robots": robots,
+            "jsonld": page.jsonld_values, "images": page.images,
+            "structureHash": hashlib.sha256(json.dumps(page.structure, sort_keys=True).encode()).hexdigest(),
+            "textHash": hashlib.sha256(" ".join(page.visible_text).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,
     }
 
 
+def summarize_crawl(pages: list[dict]) -> dict:
+    """Count captured evidence, preserving regional/script locale distinctions."""
+    groups = {}
+    for page in pages:
+        locale = page.get("declaredLocale") or "unknown"
+        template = page.get("template") or "unknown"
+        key = (locale, template)
+        group = groups.setdefault(key, {"locale": locale, "template": template,
+            "total": 0, "passed": 0, "failed": 0, "failedUrls": [],
+            "evidence": {"structural": "captured", "rendered": "not_run", "behavioral": "not_run"}})
+        group["total"] += 1
+        if page.get("passed") is True:
+            group["passed"] += 1
+        else:
+            group["failed"] += 1
+            group["failedUrls"].append(page["url"])
+    for group in groups.values():
+        group["failedUrls"].sort()
+    return {"byLocaleTemplate": [groups[key] for key in sorted(groups)]}
+
+
 def language_set(value: str | None) -> set[str]:
     if not value:
         return set()
@@ -178,7 +237,17 @@ def main() -> int:
     parser.add_argument("--markets", help="comma-separated markets: global,uk,us")
     parser.add_argument("--check-hreflang", action="store_true")
     parser.add_argument("--check-translation-completeness", action="store_true")
+    baseline_args = parser.add_mutually_exclusive_group()
+    baseline_args.add_argument("--save-baseline", type=Path, help="create a new reviewed contract from a passing complete crawl")
+    baseline_args.add_argument("--baseline", type=Path, help="fail on differences from a reviewed contract")
+    parser.add_argument("--reviewer", help="required for --save-baseline")
     args = parser.parse_args()
+    if args.max_pages < 1:
+        parser.error("max-pages must be positive")
+    if (args.save_baseline or args.baseline) and not args.crawl:
+        parser.error("baseline operations require --crawl")
+    if args.save_baseline and not (args.reviewer or "").strip():
+        parser.error("save-baseline requires --reviewer")
     try:
         expected_languages = language_set(args.languages)
         markets = {item.strip() for item in (args.markets or "").split(",") if item.strip()}
@@ -232,11 +301,14 @@ def main() -> int:
     if args.crawl:
         try:
             urls, sitemap_violations = sitemap_urls(base)
+            crawl["discovered_url_count"] = len(urls)
+            crawl["complete"] = len(urls) <= args.max_pages and not sitemap_violations
             urls = urls[: args.max_pages]
             for page_url in urls:
                 try:
-                    status, content_type, body = fetch(page_url)
-                    page_checks = audit_page(page_url, body, status, content_type, expected_languages)
+                    response_evidence = {}
+                    status, content_type, body = fetch(page_url, response_evidence)
+                    page_checks = audit_page(page_url, body, status, content_type, expected_languages, response_evidence)
                     if args.check_hreflang or args.check_translation_completeness:
                         parsed = PageParser(); parsed.feed(body)
                         page_checks["hreflang_check"] = hreflang_check(page_url, parsed, expected_languages) if args.check_hreflang else {"ok": True, "links": parsed.hreflang}
@@ -244,18 +316,30 @@ def main() -> int:
                             page_checks["translation_completeness"] = {"ok": all(lang in {item["lang"] for item in parsed.hreflang} for lang in expected_languages), "expected": sorted(expected_languages)}
                     page_checks["passed"] = all(
                         page_checks[key]
-                        for key in ("ok", "title", "h1", "canonical", "description", "locale", "open_graph", "twitter_card", "jsonld", "entity_jsonld", "images", "robots", "robots_conflict")
-                    ) and (not args.check_hreflang or page_checks["hreflang_check"]["ok"]) and (not args.check_translation_completeness or page_checks.get("translation_completeness", {}).get("ok", False))
+                        for key in ("ok", "title", "h1", "canonical", "description", "locale", "open_graph", "twitter_card", "jsonld", "entity_jsonld", "images", "robots")
+                    ) and not page_checks["robots_conflict"] and (not args.check_hreflang or page_checks["hreflang_check"]["ok"]) and (not args.check_translation_completeness or page_checks.get("translation_completeness", {}).get("ok", False))
                 except Exception as exc:
                     page_checks = {"url": page_url, "passed": False, "error": type(exc).__name__}
                 crawl["pages"].append(page_checks)
             crawl["sitemap_loc_violations"] = sitemap_violations
-            crawl["passed"] = not sitemap_violations and bool(urls) and len(crawl["pages"]) == len(urls) and all(item["passed"] for item in crawl["pages"])
+            crawl["passed"] = crawl["complete"] and bool(urls) and len(crawl["pages"]) == len(urls) and all(item["passed"] for item in crawl["pages"])
             crawl["url_count"] = len(urls)
         except Exception as exc:
             crawl = {"enabled": True, "passed": False, "error": type(exc).__name__, "pages": []}
 
     result = {"url": base, "environment": args.environment, "checks": checks, "crawl": crawl, "passed": all(v.get("ok", False) for v in checks.values()) and crawl["passed"]}
+    result["evidence"] = {"structural": "captured", "rendered": "not_run", "behavioral": "not_run"}
+    crawl["summary"] = summarize_crawl(crawl["pages"])
+    try:
+        if args.baseline:
+            result["baseline"] = site_baseline.compare(json.loads(args.baseline.read_text()), result)
+            result["passed"] = result["passed"] and result["baseline"]["passed"]
+        if args.save_baseline:
+            site_baseline.save(args.save_baseline, site_baseline.snapshot(result, args.reviewer))
+            result["baseline"] = {"passed": True, "saved": str(args.save_baseline)}
+    except (OSError, ValueError, TypeError) as exc:
+        result["baseline"] = {"passed": False, "error": str(exc)}
+        result["passed"] = False
     if args.output:
         output = Path(args.output).resolve()
         output.parent.mkdir(parents=True, exist_ok=True)

package/bundled-tools/runtime/analytics_traffic.py

@@ -0,0 +1,30 @@
+"""Safe classification of known first-party/toolchain traffic."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from typing import Iterable
+
+TOOL_USER_AGENT = re.compile(r"(?:maggie|playwright|puppeteer|selenium|lighthouse|headlesschrome|synthetic|test[-_ ]?sweep)", re.I)
+
+
+def is_tool_traffic(event: dict) -> bool:
+    if str(event.get("maggieTest") or "").lower() == "true":
+        return True
+    if str(event.get("xMaggieTest") or "").lower() == "true":
+        return True
+    return bool(TOOL_USER_AGENT.search(str(event.get("userAgent") or "")))
+
+
+def audit_events(events: Iterable[dict]) -> dict:
+    totals = Counter()
+    excluded = Counter()
+    included = 0
+    for event in events:
+        totals[str(event.get("event") or "unknown")] += 1
+        if is_tool_traffic(event):
+            excluded[str(event.get("event") or "unknown")] += 1
+        else:
+            included += 1
+    return {"schemaVersion": "maggie-analytics-traffic.v1", "total": sum(totals.values()), "included": included, "excluded": sum(excluded.values()), "byEvent": dict(sorted(totals.items())), "excludedByEvent": dict(sorted(excluded.items())), "policy": "exclude only explicit Maggie/toolchain markers; no IP or identity inference"}

package/bundled-tools/runtime/browser_behavior.py

@@ -0,0 +1,35 @@
+"""Compare actual browser samples against explicit route expectations."""
+
+
+def validate_samples(samples: list[dict], selectors: list[str], sticky: list[str]) -> dict:
+    errors = []
+    if len(samples) < 2:
+        return {"passed": False, "errors": ["at least two scroll samples required"]}
+    first = samples[0]
+    for sample in samples:
+        if sample.get("viewport") != first.get("viewport") or sample.get("url") != first.get("url"):
+            errors.append("samples must share URL and viewport")
+        if sample.get("horizontalOverflow"):
+            errors.append("horizontal overflow")
+        elements = {element["selector"]: element for element in sample.get("elements", [])}
+        for selector in selectors:
+            element = elements.get(selector, {})
+            if not element.get("found") or not element.get("visible"):
+                errors.append(f"required element missing or hidden: {selector}")
+    if samples[-1].get("scroll", {}).get("y", 0) <= first.get("scroll", {}).get("y", 0):
+        errors.append("scroll did not advance; behavior unverified")
+    for selector in sticky:
+        for sample in samples[1:]:
+            element = next((item for item in sample.get("elements", []) if item.get("selector") == selector), {})
+            if element.get("position") not in {"sticky", "fixed"}:
+                errors.append(f"expected sticky/fixed positioning: {selector}")
+                continue
+            top = element.get("rect", {}).get("top")
+            try:
+                inset = float(element.get("insetTop", "auto").removesuffix("px"))
+            except (ValueError, AttributeError):
+                errors.append(f"sticky top inset unmeasurable: {selector}")
+                continue
+            if not isinstance(top, (int, float)) or abs(top - inset) > 2:
+                errors.append(f"sticky element left expected top inset: {selector}")
+    return {"passed": not errors, "errors": sorted(set(errors))}

package/bundled-tools/runtime/browser_geometry.js

@@ -0,0 +1,31 @@
+// Read-only browser measurements. The caller supplies selectors and scrolls
+// between samples; never infer scrolling behavior from position:sticky alone.
+((selectors = window.__maggieAuditSelectors || []) => {
+  const visible = element => {
+    const rect = element.getBoundingClientRect();
+    if (!rect.width || !rect.height) return false;
+    for (let node = element; node; node = node.parentElement) {
+      const style = getComputedStyle(node);
+      if (style.display === 'none' || style.visibility === 'hidden' || Number(style.opacity) === 0) return false;
+    }
+    return true;
+  };
+  return {
+    url: location.href,
+    viewport: {width: innerWidth, height: innerHeight},
+    scroll: {x: scrollX, y: scrollY, maxY: Math.max(0, document.documentElement.scrollHeight - innerHeight)},
+    horizontalOverflow: document.documentElement.scrollWidth > innerWidth + 1,
+    elements: selectors.map(selector => {
+      const element = document.querySelector(selector);
+      if (!element) return {selector, found: false, visible: false};
+      const rect = element.getBoundingClientRect();
+      const style = getComputedStyle(element);
+      const parent = element.parentElement?.getBoundingClientRect();
+      return {selector, found: true, visible: visible(element),
+        rect: {top: rect.top, bottom: rect.bottom, left: rect.left, right: rect.right, width: rect.width, height: rect.height},
+        position: style.position, insetTop: style.top,
+        parentRect: parent ? {top: parent.top, bottom: parent.bottom, height: parent.height} : null,
+        hiddenDescendants: [...element.querySelectorAll('a,button,input,select')].filter(child => !visible(child)).length};
+    })
+  };
+})()

package/bundled-tools/runtime/content_localization.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import re
-from typing import Any
+from typing import Any, Iterable
 
 # Deliberately broad, dependency-free registry of the major web/content
 # languages. Script variants remain distinct where they affect copy, search,
@@ -19,6 +19,68 @@ OPERATIONS = {"translate", "polish", "rewrite", "localise", "rebrand", "manual_e
 PROTECTED_FIELDS = {"price", "currency", "rating", "provider", "providerId", "bookingUrl", "paymentUrl", "legalClaims", "healthClaims", "contentId", "slug", "canonicalUrl", "translationGroupId"}
 
 
+class TranslationIndex:
+    """One canonical index for translated records and their public wording.
+
+    Hosts may persist this structure wherever they keep content, but they must
+    build it once and reject conflicting duplicate `(contentId, locale)` rows.
+    This prevents a registry and a second dictionary from silently disagreeing.
+    """
+
+    def __init__(self, records: Iterable[dict[str, Any]] = ()):
+        self._records: dict[tuple[str, str], dict[str, Any]] = {}
+        self.conflicts: list[dict[str, Any]] = []
+        for record in records:
+            self.add(record)
+
+    def add(self, record: dict[str, Any]) -> None:
+        content_id = str(record.get("contentId") or "").strip()
+        locale = str(record.get("locale") or "").strip()
+        if not content_id or not locale:
+            raise ValueError("translation index records require contentId and locale")
+        key = (content_id, locale)
+        previous = self._records.get(key)
+        if previous and previous != record:
+            self.conflicts.append({"key": key, "existing": previous, "incoming": record})
+            raise ValueError(f"conflicting translation record for {content_id}/{locale}")
+        self._records[key] = dict(record)
+
+    def get(self, content_id: str, locale: str) -> dict[str, Any] | None:
+        record = self._records.get((content_id, locale))
+        return dict(record) if record else None
+
+    def records(self) -> list[dict[str, Any]]:
+        return [dict(self._records[key]) for key in sorted(self._records)]
+
+    def as_dict(self) -> dict[str, dict[str, Any]]:
+        return {f"{content_id}:{locale}": dict(record) for (content_id, locale), record in sorted(self._records.items())}
+
+
+def is_translated_path(path: str, exact_paths: Iterable[str] = (), prefixes: Iterable[str] = ()) -> bool:
+    """Use exact routes and normalized prefix routes with identical semantics."""
+    normalized = "/" + str(path or "").lstrip("/")
+    normalized = normalized.rstrip("/") or "/"
+    exact = {("/" + str(item).lstrip("/")).rstrip("/") or "/" for item in exact_paths}
+    normalized_prefixes = {("/" + str(item).lstrip("/")).rstrip("/") or "/" for item in prefixes}
+    return normalized in exact or any(normalized == prefix or normalized.startswith(prefix + "/") for prefix in normalized_prefixes)
+
+
+def should_localize_path(path: str, locale_prefixes: Iterable[str], static_extensions: Iterable[str] = (".txt", ".md", ".xml", ".json")) -> bool:
+    """Locale middleware only handles localized routes, never root static files."""
+    normalized = "/" + str(path or "").lstrip("/")
+    if any(normalized.lower().endswith(extension.lower()) for extension in static_extensions):
+        return False
+    return is_translated_path(normalized, prefixes=locale_prefixes)
+
+
+def rewrite_once(request_key: str, seen: set[str]) -> bool:
+    """Return true only for the first rewrite observation of a request."""
+    if request_key in seen:
+        return False
+    seen.add(request_key)
+    return True
+
+
 def parse_locale(value: Any) -> tuple[str | None, str | None, str | None]:
     if not isinstance(value, str):
         return None, None, None

package/bundled-tools/runtime/dependency_lock.py

@@ -0,0 +1,43 @@
+"""Detect package-manager drift before an npm-ci deployment."""
+from __future__ import annotations
+import json
+import re
+from pathlib import Path
+
+
+def package_dependencies(project: Path) -> set[str]:
+    data = json.loads((project / "package.json").read_text(encoding="utf-8"))
+    return set(data.get("dependencies", {})) | set(data.get("devDependencies", {})) | set(data.get("optionalDependencies", {}))
+
+
+def npm_lock_dependencies(path: Path) -> set[str]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    packages = data.get("packages", {})
+    names = {key.removeprefix("node_modules/") for key in packages
+             if key.startswith("node_modules/") and "/node_modules/" not in key}
+    if not packages and isinstance(data.get("dependencies"), dict):
+        names = set(data["dependencies"])
+    return names
+
+
+def pnpm_lock_dependencies(path: Path) -> set[str]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    return {match.group(1) for match in re.finditer(r"^\s{4,}/?(@[^/\s]+/[^/\s]+|[A-Za-z0-9_.-]+)@[^:]+:", text, re.M)}
+
+
+def audit(project: Path) -> dict:
+    errors = []
+    try:
+        declared = package_dependencies(project)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        return {"passed": False, "errors": [f"package.json: {error}"]}
+    npm = project / "package-lock.json"
+    pnpm = project / "pnpm-lock.yaml"
+    npm_names = npm_lock_dependencies(npm) if npm.exists() else set()
+    pnpm_names = pnpm_lock_dependencies(pnpm) if pnpm.exists() else set()
+    if not npm.exists(): errors.append("package-lock.json is required by npm ci")
+    missing = sorted(declared - npm_names) if npm.exists() else sorted(declared)
+    if missing: errors.append("package-lock missing declared dependencies: " + ", ".join(missing))
+    return {"schemaVersion": "maggie-dependency-lock-audit.v1", "passed": not errors,
+            "errors": errors, "declared": sorted(declared), "npmLock": sorted(npm_names),
+            "pnpmLock": sorted(pnpm_names), "lockfiles": {"npm": npm.exists(), "pnpm": pnpm.exists()}}

package/bundled-tools/runtime/integration_state.py

@@ -0,0 +1,17 @@
+"""Explicit state model for optional Search/AI visibility integrations."""
+
+from __future__ import annotations
+
+
+def integration_state(*, configured: bool, consent_required: bool = False, consent: bool = False, authorized: bool = False, error: str | None = None) -> dict:
+    if error:
+        status = "error"
+    elif not configured:
+        status = "not-configured"
+    elif consent_required and not consent:
+        status = "awaiting-consent"
+    elif not authorized:
+        status = "awaiting-authorization"
+    else:
+        status = "ready"
+    return {"status": status, "configured": configured, "consentRequired": consent_required, "consent": consent, "authorized": authorized, "reason": error or status}

package/bundled-tools/runtime/localization_runner.py

@@ -0,0 +1,113 @@
+"""Resumable translation batches; provider calls are supplied by the adapter."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+def process_adapter(command: list[str], project: Path, timeout: int = 120):
+    if not isinstance(command, list) or not command or any(not isinstance(part, str) or not part for part in command):
+        raise ValueError("adapter-command must be a nonempty JSON argv array")
+    if timeout < 1:
+        raise ValueError("timeout must be positive")
+    def adapter(batch, contract):
+        try:
+            result = subprocess.run(command, input=json.dumps({
+                "schemaVersion": "maggie-provider-request.v1", "strings": batch,
+                "contract": contract}, ensure_ascii=False), text=True, capture_output=True,
+                timeout=timeout, check=False, cwd=project.resolve())
+        except (OSError, subprocess.TimeoutExpired):
+            raise OSError("provider adapter could not execute or timed out; retry to resume") from None
+        if result.returncode:
+            raise OSError("provider adapter failed; retry to resume (provider logs suppressed)")
+        return result.stdout
+    return adapter
+
+
+def checkpoint(path: Path, state: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, name = tempfile.mkstemp(prefix=".translation-", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            json.dump(state, stream, ensure_ascii=False, indent=2)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(name, path)
+    finally:
+        if os.path.exists(name):
+            os.unlink(name)
+
+
+def generate(strings: list[dict], contract: dict, output: Path, adapter,
+             character_budget: int = 8000) -> dict:
+    """Adapter accepts (batch, contract) and returns an exact ID-to-text map.
+
+    Invalid/truncated output splits a batch. Provider exceptions propagate;
+    successfully checkpointed batches are reusable on the next invocation.
+    """
+    if type(character_budget) is not int or character_budget < 1:
+        raise ValueError("character_budget must be positive")
+    if not strings or any(not isinstance(item, dict) or not isinstance(item.get("id"), str)
+                          or not item["id"] or not isinstance(item.get("text"), str)
+                          or not item["text"].strip() for item in strings):
+        raise ValueError("source strings require nonempty IDs and text")
+    if len({item["id"] for item in strings}) != len(strings):
+        raise ValueError("duplicate source IDs")
+    identity = hashlib.sha256(json.dumps({"strings": strings, "contract": contract},
+                                        sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+    state = {"schemaVersion": "maggie-generation.v1", "identity": identity,
+             "translations": {}, "status": "pending", "publish": False}
+    if output.exists():
+        state = json.loads(output.read_text(encoding="utf-8"))
+        if not isinstance(state, dict) or state.get("schemaVersion") != "maggie-generation.v1" or state.get("publish") is not False:
+            raise ValueError("invalid generation checkpoint")
+        if state.get("identity") != identity:
+            raise ValueError("source or generation contract changed; choose a new output")
+        translations = state.get("translations")
+        if not isinstance(translations, dict) or any(key not in {s["id"] for s in strings}
+                or not isinstance(value, str) or not value.strip() for key, value in translations.items()):
+            raise ValueError("invalid generation checkpoint")
+
+    def run(batch):
+        try:
+            result = adapter(batch, contract)
+            if isinstance(result, str):
+                result = json.loads(result)
+            if not isinstance(result, dict) or set(result) != {item["id"] for item in batch}:
+                raise ValueError("provider returned missing or unexpected IDs")
+            if any(not isinstance(value, str) or not value.strip() for value in result.values()):
+                raise ValueError("provider returned empty translations")
+        except (ValueError, json.JSONDecodeError):
+            if len(batch) == 1:
+                raise ValueError("provider output invalid for single source string") from None
+            midpoint = len(batch) // 2
+            run(batch[:midpoint])
+            run(batch[midpoint:])
+            return
+        state["translations"].update(result)
+        checkpoint(output, state)
+
+    pending = [item for item in strings if item["id"] not in state["translations"]]
+    state["status"] = "running"
+    checkpoint(output, state)
+    try:
+        batch, size = [], 0
+        for item in pending:
+            if batch and size + len(item["text"]) > character_budget:
+                run(batch)
+                batch, size = [], 0
+            batch.append(item)
+            size += len(item["text"])
+        if batch:
+            run(batch)
+    except Exception:
+        state["status"] = "failed"
+        checkpoint(output, state)
+        raise
+    state["status"] = "generated"
+    checkpoint(output, state)
+    return state