@topy-ai/maggie 0.7.48 → 0.7.49

package/bundled-tools/clis/maggie_social_queue.py

@@ -98,6 +98,8 @@ def validate_adapters(manifest: dict) -> dict:
         if shared:
             warnings.append(f"{label} OAuth client is shared with {len(shared)} other product(s); their sign-ins can "
                             "revoke this product's tokens unless they request the identical scope set — prefer a dedicated client")
+        if adapter.get("publishes"):
+            errors.extend(f"{label} {problem}" for problem in publish_contract_errors(adapter))
         hosts = sorted({urlsplit(uri).hostname or "" for uri in adapter.get("redirect_uris") or [] if isinstance(uri, str)} - {""})
         if len(hosts) > 1 and not shared:
             warnings.append(f"{label} redirect URIs span {len(hosts)} hosts ({', '.join(hosts)}); confirm they belong to "
@@ -105,6 +107,108 @@ def validate_adapters(manifest: dict) -> dict:
     return {"valid": not errors, "errors": errors, "warnings": warnings}
 
 
+# --- D33: publish contract and reconciliation ----------------------------------------------------
+
+
+RETRY_CLASSES = ("retryable", "terminal", "unknown_outcome")
+READBACK_LOOKUPS = {"by_idempotency_key", "by_marker", "by_recent_posts"}
+
+
+def publish_contract_errors(adapter: dict) -> list[str]:
+    """A publishing adapter declares limits, media rules, pending behaviour, retry classes, idempotency, and readback."""
+    problems: list[str] = []
+    limits = adapter.get("limits")
+    if not isinstance(limits, dict) or not isinstance(limits.get("text_max"), int) or limits["text_max"] <= 0:
+        problems.append("publish contract needs limits.text_max")
+    media = adapter.get("media")
+    if not isinstance(media, dict) or not isinstance(media.get("types"), list) or not isinstance(media.get("max_bytes"), int):
+        problems.append("publish contract needs media.types and media.max_bytes")
+    pending = adapter.get("pending")
+    if not isinstance(pending, dict) or not isinstance(pending.get("max_pending_seconds"), int) or not pending.get("states"):
+        problems.append("publish contract needs pending.states and pending.max_pending_seconds")
+    retry = adapter.get("retry_classes")
+    if not isinstance(retry, dict) or any(not isinstance(retry.get(name), list) for name in RETRY_CLASSES):
+        problems.append("publish contract needs retry_classes.retryable, .terminal and .unknown_outcome lists")
+    else:
+        overlap = (set(retry["retryable"]) & set(retry["terminal"])) | (set(retry["retryable"]) & set(retry["unknown_outcome"]))
+        if overlap:
+            problems.append(f"retry classes overlap: {', '.join(sorted(overlap))}")
+        if "timeout" in retry["retryable"]:
+            problems.append("timeout must be classed unknown_outcome, not retryable: the post may already exist")
+    idem = adapter.get("idempotency")
+    if not isinstance(idem, dict) or not idem.get("key_source"):
+        problems.append("publish contract needs idempotency.key_source")
+        idem = {}
+    readback = adapter.get("readback")
+    if not isinstance(readback, dict) or readback.get("lookup") not in READBACK_LOOKUPS:
+        problems.append(f"publish contract needs readback.lookup ({', '.join(sorted(READBACK_LOOKUPS))})")
+    elif not idem.get("provider_supported") and readback["lookup"] == "by_idempotency_key":
+        problems.append("provider has no idempotency support; readback must look up by_marker or by_recent_posts")
+    return problems
+
+
+def _matches(post: dict, key: str) -> bool:
+    return post.get("idempotency_key") == key or (isinstance(post.get("marker"), str) and key in post["marker"])
+
+
+def reconcile(document: dict) -> dict:
+    """Decide the next safe action per queue item from the attempt log and provider readback.
+
+    Timeout-after-success never produces a duplicate: an unknown outcome waits
+    for readback, a readback post carrying the idempotency key is adopted, and
+    a retry always reuses the original key.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    attempts = document.get("attempts")
+    readback = document.get("readback") or {}
+    posts = readback.get("posts") if isinstance(readback, dict) else None
+    if not isinstance(attempts, list) or not isinstance(posts, list):
+        return {"valid": False, "errors": ["attempts and readback.posts must be lists"], "warnings": [], "items": []}
+    complete = bool(readback.get("complete"))
+    by_item: dict[str, list[dict]] = {}
+    for attempt in attempts:
+        if not isinstance(attempt, dict) or not attempt.get("queue_item_id") or not attempt.get("idempotency_key"):
+            errors.append("each attempt needs queue_item_id and idempotency_key")
+            continue
+        by_item.setdefault(attempt["queue_item_id"], []).append(attempt)
+    items = []
+    for item_id, history in by_item.items():
+        keys = {attempt["idempotency_key"] for attempt in history}
+        if len(keys) > 1:
+            errors.append(f"queue item {item_id} used {len(keys)} idempotency keys; retries must reuse the original key")
+        key = history[0]["idempotency_key"]
+        matched = [post for post in posts if isinstance(post, dict) and _matches(post, key)]
+        claimed = sorted({attempt["provider_post_id"] for attempt in history if attempt.get("provider_post_id")})
+        ids = sorted({post.get("id") for post in matched} | set(claimed))
+        if len(matched) > 1 or len(ids) > 1:
+            errors.append(f"queue item {item_id} has duplicate provider posts ({', '.join(map(str, ids))}); delete extras and keep the first")
+            items.append({"queue_item_id": item_id, "action": "resolve_duplicate", "provider_post_ids": ids, "retry_allowed": False})
+            continue
+        last = history[-1].get("status")
+        if matched:
+            action, status = "adopt", "published"
+        elif claimed:
+            action, status = "verify_readback", "published"
+            warnings.append(f"queue item {item_id} reports {claimed[0]} but readback did not find it")
+        elif last in {"timeout", "pending", "unknown"}:
+            if complete:
+                action, status = "retry_same_key", "retrying"
+            else:
+                action, status = "await_readback", "pending"
+        elif last == "failed_retryable":
+            action, status = "retry_same_key", "retrying"
+        elif last == "failed_terminal":
+            action, status = "fail", "failed"
+        else:
+            action, status = "await_readback", "pending"
+            warnings.append(f"queue item {item_id} has unclassified last status {last!r}")
+        items.append({"queue_item_id": item_id, "idempotency_key": key, "action": action, "status": status,
+                      "provider_post_id": (matched[0].get("id") if matched else (claimed[0] if claimed else None)),
+                      "retry_allowed": action == "retry_same_key"})
+    return {"valid": not errors, "errors": errors, "warnings": warnings, "readback_complete": complete, "items": items}
+
+
 # --- T02: connection health --------------------------------------------------------------------
 
 

package/bundled-tools/clis/maggie_social_share.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Create and validate deterministic Maggie Social Share drafts, adapters, connections, campaigns, and the slot queue."""
+"""Create and validate deterministic Maggie Social Share drafts, adapters, connections, campaigns, the slot queue, and publish reconciliation."""
 from __future__ import annotations
 
 import argparse
@@ -10,7 +10,7 @@ from pathlib import Path
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from maggie_social_queue import check_campaigns, connection_health, parse_instant, plan_queue, validate_adapters  # noqa: E402
+from maggie_social_queue import check_campaigns, connection_health, parse_instant, plan_queue, reconcile, validate_adapters  # noqa: E402
 
 
 LIMITS = {"linkedin": 3000, "facebook": 63206, "x": 280}
@@ -82,6 +82,8 @@ def main() -> int:
     health.add_argument("--now", help="ISO 8601 instant used for expiry checks (default: current time)")
     campaigns = sub.add_parser("campaigns", help="check the campaign idea stage and Start gate")
     campaigns.add_argument("input")
+    rec = sub.add_parser("reconcile", help="decide adopt/await/retry per queue item from attempts and provider readback")
+    rec.add_argument("input")
     queue = sub.add_parser("queue", help="assign queued and campaign posts to the next posting slots")
     queue.add_argument("input")
     queue.add_argument("--from", dest="start", help="ISO 8601 instant to plan from (default: current time)")
@@ -95,6 +97,8 @@ def main() -> int:
             result = validate_adapters(value)
         elif args.command == "connections":
             result = connection_health(value, parse_instant(args.now, "--now") if args.now else now)
+        elif args.command == "reconcile":
+            result = reconcile(value)
         elif args.command == "campaigns":
             result = check_campaigns(value)
         elif args.command == "queue":

package/bundled-tools/runtime/google_ads.py

@@ -0,0 +1,306 @@
+"""Read-only Google Ads preflight and Keyword Planner adapter.
+
+Every request goes through an injectable transport so tests run offline. The
+default transport uses urllib and is only exercised when an operator runs the
+CLI with credentials. The adapter refuses any request that is not one of the
+three read-only calls below, so it cannot mutate Ads state.
+
+Credential values are read from environment variables named by the caller and
+are never returned, logged, or written to a report.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable
+
+from google_remediation import classify
+
+
+ADS_SCOPE = "https://www.googleapis.com/auth/adwords"
+ADS_HOST = "googleads.googleapis.com"
+TOKENINFO_URL = "https://oauth2.googleapis.com/tokeninfo"
+DEFAULT_API_VERSION = os.environ.get("MAGGIE_GOOGLE_ADS_API_VERSION", "v21")
+COMPETITION = {"UNSPECIFIED": "unknown", "UNKNOWN": "unknown", "LOW": "low", "MEDIUM": "medium", "HIGH": "high"}
+
+# (method, path regex relative to https://googleads.googleapis.com/<version>/)
+READ_ONLY_ROUTES = (
+    ("GET", r"customers:listAccessibleCustomers"),
+    ("POST", r"customers/\d{10}/googleAds:search"),
+    ("POST", r"customers/\d{10}:generateKeywordIdeas"),
+)
+
+Transport = Callable[[str, str, dict[str, str], Any], tuple[int, Any]]
+
+
+class AdsRequestRefused(ValueError):
+    """Raised when a request is not on the read-only allowlist."""
+
+
+def normalize_customer_id(value: Any) -> str | None:
+    """Return a 10-digit customer ID without hyphens, or None when invalid."""
+    if not isinstance(value, str):
+        return None
+    digits = value.replace("-", "").strip()
+    return digits if re.fullmatch(r"\d{10}", digits) else None
+
+
+def urllib_transport(method: str, url: str, headers: dict[str, str], body: Any) -> tuple[int, Any]:
+    data = None
+    if body is not None:
+        if headers.get("content-type") == "application/x-www-form-urlencoded":
+            data = urllib.parse.urlencode(body).encode()
+        else:
+            data = json.dumps(body).encode()
+            headers = {**headers, "content-type": "application/json"}
+    request = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return response.status, json.loads(response.read() or b"{}")
+    except urllib.error.HTTPError as error:
+        try:
+            payload = json.loads(error.read() or b"{}")
+        except json.JSONDecodeError:
+            payload = {}
+        return error.code, payload
+
+
+def _error_signal(payload: Any) -> dict[str, Any]:
+    """Extract only error codes/reasons from a provider payload for classification."""
+    signal: list[str] = []
+    if isinstance(payload, dict):
+        error = payload.get("error")
+        if isinstance(error, str):
+            signal.append(error)
+        if isinstance(error, dict):
+            signal.append(str(error.get("status") or ""))
+            signal.append(str(error.get("message") or "")[:300])
+            for detail in error.get("details") or []:
+                if not isinstance(detail, dict):
+                    continue
+                signal.append(str(detail.get("reason") or ""))
+                for item in detail.get("errors") or []:
+                    if isinstance(item, dict) and isinstance(item.get("errorCode"), dict):
+                        signal.extend(f"{value}" for value in item["errorCode"].values())
+        if isinstance(payload.get("error_description"), str):
+            signal.append(payload["error_description"][:300])
+    return {"reason": " ".join(part for part in signal if part)[:300]}
+
+
+class AdsClient:
+    def __init__(self, *, access_token: str, developer_token: str | None, login_customer_id: str | None = None,
+                 api_version: str = DEFAULT_API_VERSION, transport: Transport | None = None) -> None:
+        self._access_token = access_token
+        self._developer_token = developer_token
+        self._login_customer_id = login_customer_id
+        self.api_version = api_version
+        self._transport = transport or urllib_transport
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"authorization": f"Bearer {self._access_token}"}
+        if self._developer_token:
+            headers["developer-token"] = self._developer_token
+        if self._login_customer_id:
+            headers["login-customer-id"] = self._login_customer_id
+        return headers
+
+    def request(self, method: str, path: str, body: Any = None) -> tuple[int, Any]:
+        if not any(method == allowed and re.fullmatch(pattern, path) for allowed, pattern in READ_ONLY_ROUTES):
+            raise AdsRequestRefused(f"refused non-allowlisted Google Ads request: {method} {path.split('/')[-1].split(':')[-1]}")
+        return self._transport(method, f"https://{ADS_HOST}/{self.api_version}/{path}", self._headers(), body)
+
+    def token_scopes(self) -> tuple[int, list[str]]:
+        # POST body keeps the token out of URLs and access logs.
+        status, payload = self._transport("POST", TOKENINFO_URL, {"content-type": "application/x-www-form-urlencoded"}, {"access_token": self._access_token})
+        scopes = str(payload.get("scope") or "").split() if isinstance(payload, dict) else []
+        return status, scopes
+
+
+def _check(checks: list[dict[str, Any]], name: str, status: str, detail: str, remediation: dict[str, Any] | None = None) -> None:
+    item = {"check": name, "status": status, "detail": detail}
+    if remediation:
+        item["remediation"] = {key: remediation[key] for key in ("code", "prerequisite", "nextAction", "httpStatus")}
+    checks.append(item)
+
+
+def _failure(status: int, payload: Any) -> dict[str, Any]:
+    return classify(_error_signal(payload), status=status, provider="google-ads")
+
+
+def preflight(*, customer_id: str | None, login_customer_id: str | None, access_token: str | None,
+              developer_token: str | None, api_version: str = DEFAULT_API_VERSION,
+              transport: Transport | None = None, probe_keyword_planner: bool = False) -> dict[str, Any]:
+    """Run ordered, independent read-only checks and return a redacted report."""
+    checks: list[dict[str, Any]] = []
+    customer = normalize_customer_id(customer_id)
+    login = normalize_customer_id(login_customer_id) if login_customer_id else None
+    if customer:
+        _check(checks, "customer_id_format", "passed", "customer ID is 10 digits")
+    else:
+        _check(checks, "customer_id_format", "failed", "customer ID must be 10 digits (hyphens allowed in input)",
+               {"code": "customer_id_format", "prerequisite": "ads-customer-id", "nextAction": "Pass the target Ads customer ID as 10 digits, e.g. 123-456-7890.", "httpStatus": None})
+    if login_customer_id is None:
+        _check(checks, "login_customer_id_format", "skipped", "no manager login-customer-id supplied")
+    elif login:
+        _check(checks, "login_customer_id_format", "passed", "login-customer-id is 10 digits")
+    else:
+        _check(checks, "login_customer_id_format", "failed", "login-customer-id must be 10 digits",
+               {"code": "login_customer_mismatch", "prerequisite": "ads-login-customer-id", "nextAction": "Pass the manager account ID as 10 digits, or omit it for direct access.", "httpStatus": None})
+    if developer_token:
+        _check(checks, "developer_token_present", "passed", "developer token is present (value not recorded)")
+    else:
+        _check(checks, "developer_token_present", "failed", "developer token environment variable is empty", classify("DEVELOPER_TOKEN_PARAMETER_MISSING", provider="google-ads"))
+    if not access_token:
+        _check(checks, "oauth_scope", "failed", "access token environment variable is empty", classify("invalid_grant", provider="google-ads"))
+        return _report(checks, customer, login, api_version)
+
+    client = AdsClient(access_token=access_token, developer_token=developer_token, login_customer_id=login, api_version=api_version, transport=transport)
+    status, scopes = client.token_scopes()
+    if status != 200:
+        _check(checks, "oauth_scope", "failed", "token introspection failed", classify("invalid_grant", status=status, provider="google-ads"))
+        return _report(checks, customer, login, api_version)
+    if ADS_SCOPE in scopes:
+        _check(checks, "oauth_scope", "passed", "token carries the adwords scope")
+    else:
+        _check(checks, "oauth_scope", "failed", "token lacks the adwords scope", classify("ACCESS_TOKEN_SCOPE_INSUFFICIENT", provider="google-ads"))
+        return _report(checks, customer, login, api_version)
+    if not developer_token or not customer:
+        return _report(checks, customer, login, api_version)
+
+    status, payload = client.request("GET", "customers:listAccessibleCustomers")
+    accessible = sorted(name.split("/")[-1] for name in (payload.get("resourceNames") or [])) if status == 200 and isinstance(payload, dict) else []
+    if status != 200:
+        _check(checks, "accessible_customers", "failed", "listAccessibleCustomers was rejected", _failure(status, payload))
+        return _report(checks, customer, login, api_version)
+    direct = customer in accessible
+    via_manager = bool(login and login in accessible)
+    if direct or via_manager:
+        _check(checks, "accessible_customers", "passed", f"{len(accessible)} accessible customer(s); target reachable {'directly' if direct else 'via manager'}")
+    else:
+        _check(checks, "accessible_customers", "failed", f"{len(accessible)} accessible customer(s); target not among them",
+               classify("USER_PERMISSION_DENIED" if not login else "USER_PERMISSION_DENIED manager", provider="google-ads"))
+        return _report(checks, customer, login, api_version)
+
+    currency = None
+    if via_manager and not direct:
+        query = f"SELECT customer_client.id, customer_client.manager, customer_client.status FROM customer_client WHERE customer_client.id = {customer}"
+        status, payload = client.request("POST", f"customers/{login}/googleAds:search", {"query": query})
+        rows = (payload.get("results") or []) if status == 200 and isinstance(payload, dict) else []
+        if status == 200 and rows:
+            _check(checks, "account_hierarchy", "passed", "target is linked under the manager account")
+        else:
+            _check(checks, "account_hierarchy", "failed", "target is not linked under the manager account",
+                   _failure(status, payload) if status != 200 else classify("login-customer-id", provider="google-ads"))
+            return _report(checks, customer, login, api_version)
+    else:
+        _check(checks, "account_hierarchy", "skipped", "direct access; no manager hierarchy needed")
+    status, payload = client.request("POST", f"customers/{customer}/googleAds:search",
+                                     {"query": "SELECT customer.id, customer.currency_code, customer.manager, customer.test_account FROM customer LIMIT 1"})
+    if status == 200 and isinstance(payload, dict) and payload.get("results"):
+        info = payload["results"][0].get("customer") or {}
+        currency = info.get("currencyCode")
+        if info.get("manager"):
+            _check(checks, "customer_readable", "failed", "target is a manager account; Keyword Planner needs a client account",
+                   {"code": "manager_account_target", "prerequisite": "ads-client-account", "nextAction": "Select a client (non-manager) customer ID as the Keyword Planner target.", "httpStatus": None})
+            return _report(checks, customer, login, api_version, currency)
+        _check(checks, "customer_readable", "passed", "customer row readable" + (" (test account)" if info.get("testAccount") else ""))
+    else:
+        _check(checks, "customer_readable", "failed", "customer query was rejected", _failure(status, payload))
+        return _report(checks, customer, login, api_version)
+
+    if probe_keyword_planner:
+        status, payload = client.request("POST", f"customers/{customer}:generateKeywordIdeas",
+                                         {"keywordSeed": {"keywords": ["test"]}, "pageSize": 1, "includeAdultKeywords": False})
+        if status == 200:
+            _check(checks, "keyword_planner", "passed", "one-result KeywordPlanIdeaService probe succeeded")
+        else:
+            _check(checks, "keyword_planner", "failed", "KeywordPlanIdeaService probe was rejected", _failure(status, payload))
+    else:
+        _check(checks, "keyword_planner", "ready", "all prerequisites passed; pass --probe-keyword-planner to spend one read-only request")
+    return _report(checks, customer, login, api_version, currency)
+
+
+def _report(checks: list[dict[str, Any]], customer: str | None, login: str | None, api_version: str, currency: str | None = None) -> dict[str, Any]:
+    failed = [item for item in checks if item["status"] == "failed"]
+    return {
+        "schemaVersion": "maggie-google-ads-preflight.v1",
+        "passed": not failed,
+        "apiVersion": api_version,
+        "customerId": customer,
+        "loginCustomerId": login,
+        "currency": currency,
+        "checks": checks,
+        "firstFailure": failed[0]["check"] if failed else None,
+        "nextAction": failed[0]["remediation"]["nextAction"] if failed and failed[0].get("remediation") else None,
+        "mutationsAllowed": False,
+    }
+
+
+def _micros(value: Any) -> float | None:
+    try:
+        return round(int(value) / 1_000_000, 2)
+    except (TypeError, ValueError):
+        return None
+
+
+def normalize_ideas(results: list[Any], currency: str | None) -> list[dict[str, Any]]:
+    ideas = []
+    for item in results:
+        if not isinstance(item, dict) or not isinstance(item.get("text"), str):
+            continue
+        metrics = item.get("keywordIdeaMetrics") or {}
+        searches = metrics.get("avgMonthlySearches")
+        ideas.append({
+            "text": item["text"],
+            "avgMonthlySearches": int(searches) if str(searches or "").isdigit() else None,
+            "competition": COMPETITION.get(str(metrics.get("competition") or "UNKNOWN"), "unknown"),
+            "competitionIndex": int(metrics["competitionIndex"]) if str(metrics.get("competitionIndex") or "").isdigit() else None,
+            "lowTopOfPageBid": _micros(metrics.get("lowTopOfPageBidMicros")),
+            "highTopOfPageBid": _micros(metrics.get("highTopOfPageBidMicros")),
+            "currency": currency,
+        })
+    return ideas
+
+
+def keyword_ideas(*, customer_id: str, login_customer_id: str | None, access_token: str, developer_token: str,
+                  keywords: list[str], url: str | None = None, language: str | None = None, geo_targets: list[str] | None = None,
+                  currency: str | None = None, max_pages: int = 1, page_size: int = 100,
+                  api_version: str = DEFAULT_API_VERSION, transport: Transport | None = None) -> dict[str, Any]:
+    customer = normalize_customer_id(customer_id)
+    if not customer:
+        raise ValueError("customer ID must be 10 digits")
+    if not keywords and not url:
+        raise ValueError("provide at least one seed keyword or a seed URL")
+    login = normalize_customer_id(login_customer_id) if login_customer_id else None
+    client = AdsClient(access_token=access_token, developer_token=developer_token, login_customer_id=login, api_version=api_version, transport=transport)
+    body: dict[str, Any] = {"pageSize": max(1, min(page_size, 1000)), "includeAdultKeywords": False, "keywordPlanNetwork": "GOOGLE_SEARCH"}
+    if keywords and url:
+        body["keywordAndUrlSeed"] = {"keywords": keywords, "url": url}
+    elif keywords:
+        body["keywordSeed"] = {"keywords": keywords}
+    else:
+        body["urlSeed"] = {"url": url}
+    if language:
+        body["language"] = language if language.startswith("languageConstants/") else f"languageConstants/{language}"
+    if geo_targets:
+        body["geoTargetConstants"] = [item if item.startswith("geoTargetConstants/") else f"geoTargetConstants/{item}" for item in geo_targets]
+    results: list[Any] = []
+    pages = 0
+    while pages < max(1, max_pages):
+        status, payload = client.request("POST", f"customers/{customer}:generateKeywordIdeas", body)
+        pages += 1
+        if status != 200:
+            return {"schemaVersion": "maggie-google-ads-keyword-ideas.v1", "passed": False, "customerId": customer, "ideas": normalize_ideas(results, currency),
+                    "pages": pages, "remediation": {key: value for key, value in _failure(status, payload).items() if key != "provider"}, "mutationsAllowed": False}
+        results.extend(payload.get("results") or [])
+        token = payload.get("nextPageToken")
+        if not token:
+            break
+        body = {**body, "pageToken": token}
+    return {"schemaVersion": "maggie-google-ads-keyword-ideas.v1", "passed": True, "customerId": customer, "pages": pages,
+            "ideas": normalize_ideas(results, currency), "mutationsAllowed": False}

package/bundled-tools/runtime/google_capabilities.py

@@ -6,6 +6,8 @@ import re
 from typing import Any
 from urllib.parse import urlsplit
 
+from google_remediation import classify as classify_failure
+
 
 SCHEMA_VERSION = "maggie-google-capability-report.v2"
 CAPABILITY_NAMES = ("read", "report", "edit", "publish")
@@ -172,7 +174,7 @@ def validate_report(report: Any) -> dict[str, Any]:
             errors.append(f"{prefix} must be an object")
             continue
         required = {"provider", "resource", "activeAccount", "target", "authMode", "scopes", "productRole", "evidence", "capabilities", "nextAction"}
-        unknown = sorted(set(row) - required)
+        unknown = sorted(set(row) - required - {"failure"})
         if unknown:
             errors.append(f"{prefix} contains unsupported fields")
         provider = row.get("provider")
@@ -253,6 +255,15 @@ def validate_report(report: Any) -> dict[str, Any]:
                 errors.append(f"{prefix}.evidence.adsPrerequisites requires developer token and customer ID presence")
         elif prerequisites is not None:
             errors.append(f"{prefix}.evidence.adsPrerequisites is only valid for google-ads")
+        remediation = None
+        failure = row.get("failure")
+        if failure is not None:
+            if not isinstance(failure, dict) or set(failure) - {"code", "reason", "httpStatus"} or not any(failure.get(key) for key in ("code", "reason", "httpStatus")):
+                errors.append(f"{prefix}.failure must contain only code, reason, and httpStatus")
+            elif any(not isinstance(failure.get(key), str) or len(failure[key]) > 300 for key in ("code", "reason") if key in failure):
+                errors.append(f"{prefix}.failure.code and reason must be bounded strings")
+            else:
+                remediation = classify_failure(failure, provider=provider)
         normalized.append({
             "provider": provider,
             "resource": resource,
@@ -269,7 +280,8 @@ def validate_report(report: Any) -> dict[str, Any]:
                 "writeTested": isinstance(evidence.get("writeTest"), dict),
             },
             "capabilities": safe_capabilities,
-            "nextAction": row.get("nextAction"),
+            "nextAction": remediation["nextAction"] if remediation else row.get("nextAction"),
+            **({"remediation": remediation} if remediation else {}),
         })
 
     return {
@@ -277,5 +289,9 @@ def validate_report(report: Any) -> dict[str, Any]:
         "passed": not errors,
         "errors": sorted(set(errors)),
         "providerResults": normalized,
+        "remediation": [
+            {"provider": item["provider"], "resource": item["resource"], **{key: item["remediation"][key] for key in ("code", "prerequisite", "nextAction", "httpStatus")}}
+            for item in normalized if item.get("remediation")
+        ],
         "mutationsAllowed": False,
     }