@topy-ai/maggie 0.7.16 → 0.7.18

package/bundled-tools/clis/maggie_qa_workflow.py

@@ -224,6 +224,8 @@ def record(args: argparse.Namespace) -> int:
         raise ValueError("a failed scenario must have a recorded fix before retest")
     if phase == "test" and args.status == "fail" and not (args.expected and args.actual and args.error_fingerprint):
         raise ValueError("a failed test requires --expected, --actual and --error-fingerprint")
+    if phase in {"test", "retest"} and args.status == "pass" and not args.evidence:
+        raise ValueError("a passing test requires --evidence from the browser adapter")
     event = {
         "at": now(),
         "phase": phase,

package/bundled-tools/clis/maggie_release.py

@@ -16,7 +16,7 @@ from urllib.error import HTTPError, URLError
 from urllib.request import Request, urlopen
 from datetime import datetime, timezone
 from pathlib import Path
-from urllib.parse import urljoin
+from urllib.parse import urljoin, urlsplit
 
 
 ROOT = Path(__file__).resolve().parent
@@ -130,14 +130,23 @@ def evidence_gate(project: Path, environment: str) -> dict:
 def changed_surface_gate(project: Path) -> dict:
     """Require visual/runtime evidence when a visitor-facing surface changed."""
     try:
-        changed = subprocess.run(
+        changed_output = subprocess.run(
             ["git", "-C", str(project), "diff", "--name-only"],
             capture_output=True, text=True, check=True,
         ).stdout.splitlines()
+        staged_output = subprocess.run(
+            ["git", "-C", str(project), "diff", "--cached", "--name-only"],
+            capture_output=True, text=True, check=True,
+        ).stdout.splitlines()
+        untracked_output = subprocess.run(
+            ["git", "-C", str(project), "ls-files", "--others", "--exclude-standard", "-z"],
+            capture_output=True, text=True, check=True,
+        ).stdout.split("\0")
     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"}
+    changed = set(changed_output) | set(staged_output) | {path for path in untracked_output if path}
     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,
@@ -181,6 +190,82 @@ def changed_surface_gate(project: Path) -> dict:
             "result": {"passed": not errors, "changed": True, "surfaces": surfaces, "evidence": evidence, "errors": errors}, "stderr": ""}
 
 
+def _origin(value: object) -> str:
+    try:
+        parsed = urlsplit(str(value or ""))
+        if parsed.scheme and parsed.netloc:
+            return f"{parsed.scheme.lower()}://{parsed.netloc.lower()}"
+    except ValueError:
+        pass
+    return ""
+
+
+def _qa_run_matches(run: dict, manifest_label: str | None, environment: str, base_url: str | None) -> bool:
+    if run.get("schemaVersion") != "maggie.qa-run.v1":
+        return False
+    if run.get("environment") != environment:
+        return False
+    if manifest_label and run.get("scenarioManifest") != manifest_label:
+        return False
+    if base_url and _origin(run.get("baseUrl")) != _origin(base_url):
+        return False
+    return isinstance(run.get("scenarios"), dict) and bool(run.get("scenarios"))
+
+
+def qa_gate(project: Path, environment: str, base_url: str | None = None) -> dict:
+    """Consume the latest matching project QA run without running a browser."""
+    manifest = project / ".maggie" / "scenario-manifest.json"
+    run_dir = project / ".maggie" / "qa-runs"
+    run_paths = sorted(run_dir.glob("*.json")) if run_dir.is_dir() else []
+    configured = manifest.is_file() or bool(run_paths)
+    if not configured:
+        return {"name": "scenario-qa", "passed": True, "exitCode": 0,
+                "result": {"passed": True, "state": "not-configured", "configured": False,
+                            "reason": "no scenario manifest or QA run directory"}, "stderr": ""}
+
+    try:
+        manifest_label = str(manifest.relative_to(project)) if manifest.is_file() else None
+    except ValueError:
+        manifest_label = manifest.name if manifest.is_file() else None
+    candidates: list[tuple[Path, dict]] = []
+    invalid_count = 0
+    for path in run_paths:
+        try:
+            value = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(value, dict) and _qa_run_matches(value, manifest_label, environment, base_url):
+                candidates.append((path, value))
+        except (OSError, json.JSONDecodeError):
+            invalid_count += 1
+    if not candidates:
+        return {"name": "scenario-qa", "passed": False, "exitCode": 1,
+                "result": {"passed": False, "state": "inconclusive", "configured": True,
+                            "errors": ["no matching scenario QA run", f"invalidRuns={invalid_count}"]}, "stderr": ""}
+
+    path, run = max(candidates, key=lambda item: str(item[1].get("updatedAt") or item[1].get("createdAt") or ""))
+    errors: list[str] = []
+    summary = run.get("summary") if isinstance(run.get("summary"), dict) else {}
+    if summary.get("gate") != "pass":
+        errors.append("latest matching QA run is not passed")
+    for scenario in run.get("scenarios", {}).values():
+        if not isinstance(scenario, dict) or scenario.get("status") != "pass":
+            errors.append("latest matching QA run contains a non-passing scenario")
+            continue
+        history = scenario.get("history") if isinstance(scenario.get("history"), list) else []
+        last = history[-1] if history else {}
+        if last.get("phase") not in {"test", "retest"} or last.get("status") != "pass":
+            errors.append("latest matching QA run has a scenario without a passing final test")
+        if not isinstance(last.get("evidence"), list) or not last.get("evidence"):
+            errors.append("latest matching QA run has a scenario without browser evidence")
+    passed = not errors
+    try:
+        report_path = str(path.relative_to(project))
+    except ValueError:
+        report_path = path.name
+    return {"name": "scenario-qa", "passed": passed, "exitCode": 0 if passed else 1,
+            "result": {"passed": passed, "state": "passed" if passed else "failed", "configured": True,
+                        "run": report_path, "updatedAt": run.get("updatedAt"), "errors": errors}, "stderr": ""}
+
+
 def editorial_gate(project: Path) -> dict:
     """Require explicit editorial approval for every launch category.
 
@@ -279,6 +364,7 @@ def main() -> int:
 
     gates = []
     gates.append(changed_surface_gate(project))
+    gates.append(qa_gate(project, args.environment, args.base_url))
     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/maggie_service_booking.py

@@ -12,6 +12,7 @@ from urllib.request import Request, urlopen
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from route_imports import imported_components  # noqa: E402
+from booking_capabilities import audit_matrix  # noqa: E402
 
 NOW = lambda: datetime.now(timezone.utc).isoformat()
 MONEY = re.compile(r"(?:£|GBP\s*)\s*([0-9]+(?:[.,][0-9]{1,2})?)", re.I)
@@ -76,7 +77,8 @@ def parse(source, provider):
                 currency=(offer.get("priceCurrency") or ("GBP" if price and ("£" in text or provider=="fresha") else None))
                 if price is None and dm is None: continue
                 amount=int(round(float(str(price).replace(",",""))*100)) if price is not None else None
-                variants.append({"id":f"{slug(name)}:{dm.group(1) if dm else 'default'}","title":offer.get("name") or (f"{dm.group(1)} minutes" if dm else "Standard"),"durationMinutes":int(dm.group(1)) if dm else None,"price":{"amountMinor":amount,"currency":currency,"display":f"£{amount/100:.2f}" if amount is not None and currency=="GBP" else None}})
+                provider_variant_id = offer.get("sku") or offer.get("@id") or offer.get("id")
+                variants.append({"id":str(provider_variant_id or f"{slug(name)}:{dm.group(1) if dm else 'default'}"),"idSource":"provider" if provider_variant_id else "derived","variantSource":"native" if provider_variant_id else "derived-offers","title":offer.get("name") or (f"{dm.group(1)} minutes" if dm else "Standard"),"durationMinutes":int(dm.group(1)) if dm else None,"price":{"amountMinor":amount,"currency":currency,"display":f"£{amount/100:.2f}" if amount is not None and currency=="GBP" else None}})
             url=item.get("url") or item.get("sameAs")
             if not variants and not url: continue
             pid=str(item.get("providerServiceId") or item.get("productID") or item.get("sku") or slug(name))
@@ -113,7 +115,8 @@ def parse_fresha_embedded(raw, source):
                     parsed_amount, parsed_currency=money_value(display or "")
                     caption=variant.get("caption") or ""
                     duration=duration_minutes(caption) or round(float(variant.get("maxInSeconds") or variant.get("minInSeconds") or item.get("maxInSeconds") or item.get("minInSeconds") or 0)/60) or None
-                    variants.append({"id":str(variant.get("id") or f'{item["serviceId"]}:default'),"title":variant.get("name") or caption or "Standard","durationMinutes":duration,"price":{"amountMinor":parsed_amount if parsed_amount is not None else amount,"currency":parsed_currency or currency,"display":display}})
+                    provider_variant_id = variant.get("id")
+                    variants.append({"id":str(provider_variant_id or f'{item["serviceId"]}:default'),"idSource":"provider" if provider_variant_id else "derived","variantSource":"native" if provider_variant_id else "single-fallback","title":variant.get("name") or caption or "Standard","durationMinutes":duration,"price":{"amountMinor":parsed_amount if parsed_amount is not None else amount,"currency":parsed_currency or currency,"display":display}})
                 if not variants: continue
                 booking=item.get("bookingUrl") or f'{source.split("?")[0]}/booking?offerItemId={quote(str(item.get("id") or ""))}'
                 record=make_record("fresha",source,str(item["serviceId"]),str(item["name"]),str(item.get("description") or ""),variants,booking,[])
@@ -157,7 +160,7 @@ def parse_fresha_embedded(raw, source):
         for caption, display, vid, vname in variant_pattern.findall(match.group("variants")):
             duration=duration_minutes(caption)
             amount, currency=money_value(display)
-            variants.append({"id":vid,"title":vname or caption,"durationMinutes":duration,"price":{"amountMinor":amount,"currency":currency,"display":display}})
+            variants.append({"id":vid,"idSource":"provider","variantSource":"native","title":vname or caption,"durationMinutes":duration,"price":{"amountMinor":amount,"currency":currency,"display":display}})
         if not variants: continue
         name=variants[0]["title"]
         records.append(make_record("fresha",source,match.group("pid"),name,description,variants,None,[]))
@@ -436,6 +439,40 @@ def cmd_category_hash(args):
     print(json.dumps(report, indent=2, ensure_ascii=False))
     return 0 if not errors else 1
 
+
+def cmd_capability_audit(args):
+    """Validate provider declarations and emit a fixture-backed capability matrix."""
+    project = root(args)
+    def read(path_value):
+        path_value = Path(path_value)
+        path_value = path_value if path_value.is_absolute() else project / path_value
+        return path_value.resolve(), json.loads(path_value.resolve().read_text(encoding="utf-8"))
+    try:
+        catalogue_path, catalogue = read(args.catalogue)
+        declaration_path, declarations = read(args.capabilities_file)
+        fixture = None
+        fixture_path = None
+        fixture_digest = None
+        if args.fixture:
+            fixture_path, fixture = read(args.fixture)
+            fixture_digest = hashlib.sha256(fixture_path.read_bytes()).hexdigest()
+        result = audit_matrix(declarations, catalogue, provider=args.provider, fixture=fixture,
+                              fixture_name=fixture_path.name if fixture_path else None,
+                              fixture_sha256=fixture_digest)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(json.dumps({"schemaVersion": "maggie-provider-variant-capabilities.v1", "passed": False, "errors": [str(error)]}, indent=2))
+        return 1
+    output = Path(args.output) if args.output else project / "docs" / "provider-variant-capabilities.json"
+    if not output.is_absolute():
+        output = project / output
+    output = output.resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    result["catalogue"] = catalogue_path.name
+    result["declarations"] = declaration_path.name
+    output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": "passed" if result["passed"] else "failed", "report": str(output), "providers": len(result["providers"]), "errors": result["errors"]}, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
 def category_audit_report(project, pages_dir, copy_data, rendered_dir=None, environment="staging"):
     errors = []
     copy_path = (project / copy_data).resolve()
@@ -976,6 +1013,7 @@ def main():
     q=sub.add_parser("category-editorial-review"); q.add_argument("--project",default="."); q.add_argument("--copy-data",default="docs/category-page-copy.json"); q.add_argument("--category",action="append",help="category to review; defaults to all seven launch categories"); q.add_argument("--reviewer"); q.add_argument("--evidence",action="append",default=[],help="review evidence path or URL; repeatable"); q.add_argument("--apply",action="store_true",help="write explicit editorial approval metadata"); q.add_argument("--confirm",action="store_true",help="confirm that the selected records were actually reviewed by a human")
     q=sub.add_parser("category-hash"); q.add_argument("--project",default="."); q.add_argument("--copy-data",required=True); q.add_argument("--apply",action="store_true",help="backfill deterministic provenance hashes in this generated artifact")
     q=sub.add_parser("fact-audit"); q.add_argument("--project",default="."); q.add_argument("--backfill-source",action="store_true",help="copy the catalogue sourceUrl into records that have no sourceUrl"); q.add_argument("--overrides",help="JSON of human-approved, evidenced descriptions for provider gaps"); q.add_argument("--apply-overrides",action="store_true",help="apply only approved fact overrides to the draft catalogue")
+    q=sub.add_parser("capability-audit", help="validate provider variant declarations and fixture evidence"); q.add_argument("--project",default="."); q.add_argument("--provider"); q.add_argument("--catalogue",default=".maggie/booking/services.json"); q.add_argument("--capabilities-file",default=".maggie/booking/provider-capabilities.json"); q.add_argument("--fixture",help="sanitized provider fixture JSON"); q.add_argument("--output")
     q=sub.add_parser("category-context"); q.add_argument("--project",default="."); q.add_argument("--output")
     q=sub.add_parser("validate-copy"); q.add_argument("--project",default="."); q.add_argument("--service-id",required=True); q.add_argument("--copy-data",required=True,help="AI-authored service copy JSON")
     q=sub.add_parser("sitemap-audit"); q.add_argument("--project",default="."); q.add_argument("--index",required=True,help="rendered sitemap index XML"); q.add_argument("--sitemap-dir",required=True,help="directory containing rendered child sitemap XML files"); q.add_argument("--base-url",help="reserved for URL evidence and report context"); q.add_argument("--environment",choices=("development","staging","production"),default="staging")
@@ -997,6 +1035,7 @@ def main():
     if a.command=="category-editorial-review": return cmd_category_editorial_review(a)
     if a.command=="category-hash": return cmd_category_hash(a)
     if a.command=="fact-audit": return cmd_fact_audit(a)
+    if a.command=="capability-audit": return cmd_capability_audit(a)
     if a.command=="category-context": return cmd_category_context(a)
     if a.command=="validate-copy": return cmd_validate_copy(a)
     if a.command=="sitemap-audit": return cmd_sitemap_audit(a)

package/bundled-tools/clis/maggie_social_cards.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Audit per-page Open Graph social-card assets."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from maggie_social_cards import audit_cards, pages_from_urls, read_pages  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="maggie seo social-cards")
+    sub = parser.add_subparsers(dest="command", required=True)
+    audit = sub.add_parser("audit", help="resolve each page og:image and inspect its image contract")
+    sources = audit.add_mutually_exclusive_group(required=True)
+    sources.add_argument("--urls-file", type=Path, help="JSON array or {\"urls\": []} of HTML URLs")
+    sources.add_argument("--pages-file", type=Path, help="JSON page manifest with url and ogImage fields")
+    audit.add_argument("--timeout", type=int, default=15)
+    audit.add_argument("--output")
+    args = parser.parse_args()
+    try:
+        pages = read_pages(args.pages_file) if args.pages_file else None
+        if args.urls_file:
+            value = json.loads(args.urls_file.read_text(encoding="utf-8"))
+            urls = value.get("urls") if isinstance(value, dict) else value
+            if not isinstance(urls, list) or any(not isinstance(url, str) or not url.strip() for url in urls):
+                raise ValueError("urls file must be a JSON array or {\"urls\": []} of nonempty strings")
+            pages = pages_from_urls(urls, args.timeout)
+        result = audit_cards(pages or [], timeout=args.timeout)
+        if args.output:
+            output = Path(args.output).resolve(); output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        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"maggie-social-cards: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/site_audit.py

@@ -144,7 +144,7 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
         "canonical": bool(canonical) and urlparse(canonical).fragment == "",
         "description": bool(page.meta.get("description")),
         "locale": valid_locale(page.lang) and (not expected_languages or parse_locale(page.lang)[0] in expected_languages or page.lang in expected_languages),
-        "open_graph": all(page.meta.get(key) for key in ("og:title", "og:description", "og:url")),
+        "open_graph": all(page.meta.get(key) for key in ("og:title", "og:description", "og:url", "og:image")),
         "twitter_card": page.meta.get("twitter:card") in {"summary", "summary_large_image"},
         "jsonld": page.jsonld > 0 and all(item is not None for item in page.jsonld_values),
         "entity_jsonld": any(isinstance(item, dict) and item.get("@type") and (item.get("url") or item.get("@id")) for item in page.jsonld_values),
@@ -312,7 +312,7 @@ def main() -> int:
         checks["canonical"] = {"ok": bool(canonical) and urlparse(canonical).fragment == "", "value": canonical}
         checks["description"] = {"ok": bool(page.meta.get("description")), "value": page.meta.get("description", "")}
         checks["locale"] = {"ok": valid_locale(page.lang) and (not expected_languages or parse_locale(page.lang)[0] in expected_languages or page.lang in expected_languages), "value": page.lang, "language": parse_locale(page.lang)[0], "markets": sorted(markets)}
-        checks["open_graph"] = {"ok": all(page.meta.get(key) for key in ("og:title", "og:description", "og:url")), "fields": {key: bool(page.meta.get(key)) for key in ("og:title", "og:description", "og:url")}}
+        checks["open_graph"] = {"ok": all(page.meta.get(key) for key in ("og:title", "og:description", "og:url", "og:image")), "fields": {key: bool(page.meta.get(key)) for key in ("og:title", "og:description", "og:url", "og:image")}}
         checks["twitter_card"] = {"ok": page.meta.get("twitter:card") in {"summary", "summary_large_image"}, "value": page.meta.get("twitter:card", "")}
         checks["jsonld"] = {"ok": page.jsonld > 0 and all(item is not None for item in page.jsonld_values), "count": page.jsonld}
         checks["entity_jsonld"] = {"ok": any(isinstance(item, dict) and item.get("@type") and (item.get("url") or item.get("@id")) for item in page.jsonld_values), "count": page.jsonld}

package/bundled-tools/runtime/booking_capabilities.py

@@ -0,0 +1,137 @@
+"""Provider-neutral service variant capability matrix validation."""
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any
+
+SCHEMA_VERSION = "maggie-provider-variant-capabilities.v1"
+VARIANT_MODES = {"native", "derived-offers", "single-fallback", "blocked"}
+PRICE_SEMANTICS = {"minor-unit", "minor-unit-and-display", "display-only", "unavailable", "unknown"}
+STABLE_ID_CONFIDENCE = {"high", "medium", "low", "unknown", "blocked"}
+
+
+def _services(value: object) -> list[dict[str, Any]]:
+    if isinstance(value, dict) and isinstance(value.get("services"), list):
+        return [item for item in value["services"] if isinstance(item, dict)]
+    if isinstance(value, list):
+        return [item for item in value if isinstance(item, dict)]
+    return []
+
+
+def _fixture_evidence(fixture: object | None, name: str | None, digest: str | None) -> dict[str, Any]:
+    services = _services(fixture)
+    variants = [variant for service in services for variant in _services({"services": service.get("variants", [])})]
+    return {
+        "provided": fixture is not None,
+        "name": name or None,
+        "sha256": digest or None,
+        "serviceCount": len(services),
+        "variantCounts": [len(service.get("variants") or []) for service in services],
+        "allVariantIdsPresent": bool(variants) and all(str(item.get("id") or "").strip() for item in variants),
+        "allVariantSourcesPresent": bool(variants) and all(str(item.get("variantSource") or "").strip() for item in variants),
+    }
+
+
+def audit_provider(declaration: object, catalogue: object, *, fixture: object | None = None,
+                   fixture_name: str | None = None, fixture_sha256: str | None = None) -> dict[str, Any]:
+    """Validate one provider declaration against catalogue and fixture evidence."""
+    item = declaration if isinstance(declaration, dict) else {}
+    provider = str(item.get("provider") or "").strip()
+    mode = str(item.get("variantMode") or "").strip()
+    price_semantics = str(item.get("priceSemantics") or "").strip()
+    stable_id_confidence = str(item.get("stableIdConfidence") or "").strip()
+    errors: list[str] = []
+    if not provider:
+        errors.append("provider is required")
+    if mode not in VARIANT_MODES:
+        errors.append("variantMode must be native, derived-offers, single-fallback, or blocked")
+    if price_semantics not in PRICE_SEMANTICS:
+        errors.append("priceSemantics is unsupported")
+    if stable_id_confidence not in STABLE_ID_CONFIDENCE:
+        errors.append("stableIdConfidence is unsupported")
+
+    services = _services(catalogue)
+    active_services = [service for service in services if service.get("status", "active") != "archived"]
+    variants = [variant for service in active_services for variant in (service.get("variants") or []) if isinstance(variant, dict)]
+    observed_modes = Counter(str(variant.get("variantSource") or "unknown") for variant in variants)
+    all_ids = bool(variants) and all(str(variant.get("id") or "").strip() for variant in variants)
+    native_id_sources = all(str(variant.get("idSource") or "") in {"provider", "native"} for variant in variants) if variants else False
+    structured_prices = bool(variants) and all(
+        isinstance(variant.get("price"), dict)
+        and isinstance(variant["price"].get("amountMinor"), int)
+        and str(variant["price"].get("currency") or "").isalpha()
+        for variant in variants
+    )
+    if not services:
+        errors.append("catalogue has no services")
+    if mode != "blocked" and not variants:
+        errors.append("declared non-blocked provider has no active variants")
+    if mode == "native" and variants and not native_id_sources:
+        errors.append("native variants require provider/native idSource evidence")
+    if mode == "single-fallback" and any(len(service.get("variants") or []) > 1 for service in active_services):
+        errors.append("single-fallback provider has a service with multiple variants")
+    expected_source = {"native": "native", "derived-offers": "derived-offers", "single-fallback": "single-fallback"}.get(mode)
+    if expected_source and variants and any(source != expected_source for source in observed_modes):
+        errors.append(f"catalogue variantSource does not match declared {mode} mode")
+    if stable_id_confidence == "high" and not native_id_sources:
+        errors.append("high stable-ID confidence requires provider/native idSource evidence")
+    if fixture is None:
+        errors.append("fixture evidence is required")
+
+    evidence = _fixture_evidence(fixture, fixture_name, fixture_sha256)
+    if fixture is not None and evidence["serviceCount"] == 0:
+        errors.append("fixture evidence has no services")
+    if mode != "blocked" and fixture is not None and not evidence["allVariantIdsPresent"]:
+        errors.append("fixture evidence is missing variant IDs")
+    if mode != "blocked" and fixture is not None and not evidence["allVariantSourcesPresent"]:
+        errors.append("fixture evidence is missing variant sources")
+    if price_semantics in {"minor-unit", "minor-unit-and-display"} and variants and not structured_prices:
+        errors.append("declared minor-unit price semantics require amountMinor and currency")
+    if price_semantics == "display-only" and variants and any(
+        isinstance(variant.get("price"), dict) and variant["price"].get("amountMinor") is not None
+        for variant in variants
+    ):
+        errors.append("display-only price semantics cannot contain amountMinor")
+    if price_semantics == "unavailable" and variants and any(variant.get("price") for variant in variants):
+        errors.append("unavailable price semantics cannot contain price data")
+    if provider and isinstance(catalogue, dict) and catalogue.get("provider") and catalogue.get("provider") != provider:
+        errors.append("catalogue provider does not match declaration")
+
+    passed = not errors
+    return {
+        "provider": provider or None,
+        "variantMode": mode or None,
+        "priceSemantics": price_semantics or None,
+        "stableIdConfidence": stable_id_confidence or None,
+        "observed": {
+            "serviceCount": len(services),
+            "activeServiceCount": len(active_services),
+            "variantCount": len(variants),
+            "variantSources": dict(sorted(observed_modes.items())),
+            "allVariantIdsPresent": all_ids,
+            "allStructuredPrices": structured_prices,
+        },
+        "fixtureEvidence": evidence,
+        "passed": passed,
+        "errors": errors,
+    }
+
+
+def audit_matrix(declarations: object, catalogue: object, *, provider: str | None = None,
+                 fixture: object | None = None, fixture_name: str | None = None,
+                 fixture_sha256: str | None = None) -> dict[str, Any]:
+    """Validate a machine-readable provider declaration file."""
+    if isinstance(declarations, dict) and declarations.get("providers"):
+        entries = declarations["providers"]
+    elif isinstance(declarations, list):
+        entries = declarations
+    else:
+        entries = []
+    if not isinstance(entries, list):
+        entries = []
+    selected = [entry for entry in entries if isinstance(entry, dict) and (not provider or entry.get("provider") == provider)]
+    if not selected:
+        return {"schemaVersion": SCHEMA_VERSION, "passed": False, "providers": [], "errors": ["no provider declaration selected"]}
+    results = [audit_provider(entry, catalogue, fixture=fixture, fixture_name=fixture_name, fixture_sha256=fixture_sha256) for entry in selected]
+    return {"schemaVersion": SCHEMA_VERSION, "passed": all(result["passed"] for result in results), "providers": results,
+            "errors": [f"{result.get('provider') or 'unknown'}: {error}" for result in results for error in result["errors"]]}

package/bundled-tools/runtime/maggie_blog.py

@@ -6,6 +6,7 @@ import hashlib
 import json
 import re
 import shutil
+import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
 from localization_runner import checkpoint, generate
@@ -44,6 +45,90 @@ def checksum(value: object) -> str:
     return "sha256:" + hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
 
 
+def normalise_review_settings(value: object) -> dict:
+    """Map a host settings record to the small review-gate contract.
+
+    Hosts may store settings in PostgreSQL or another provider. The adapter
+    boundary deliberately accepts only these policy fields; credentials and
+    unrelated provider data never enter the report.
+    """
+    if not isinstance(value, dict):
+        raise ValueError("blog settings adapter must return a JSON object")
+    source = value.get("settings") if isinstance(value.get("settings"), dict) else value
+
+    def first(*keys: str, default: object = None) -> object:
+        for key in keys:
+            if key in source:
+                return source[key]
+        return default
+
+    def as_bool(value: object, default: bool) -> bool:
+        if value is None:
+            return default
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            lowered = value.strip().lower()
+            if lowered in {"true", "1", "yes", "on"}:
+                return True
+            if lowered in {"false", "0", "no", "off", ""}:
+                return False
+        return bool(value)
+
+    default_status = str(first("defaultPostStatus", "default_post_status", default="draft") or "draft")
+    return {
+        "schemaVersion": "maggie-blog-settings.v1",
+        "defaultPostStatus": default_status,
+        "requireReview": as_bool(first("requireReview", "require_review", default=True), True),
+        "autoPublishEnabled": as_bool(first("autoPublishEnabled", "auto_publish", "autoPublish", default=False), False),
+    }
+
+
+def review_settings_from_adapter(project: Path, settings_file: Path | None = None,
+                                 adapter_command: list[str] | None = None,
+                                 timeout: int = 120) -> tuple[dict, str]:
+    """Read sanitized settings from a file or trusted argv adapter.
+
+    ``adapter_command`` is executed without a shell and receives a small
+    request on stdin. Its stdout must be the normalized settings object. Error
+    output is intentionally suppressed so provider details cannot leak into a
+    Maggie report.
+    """
+    if settings_file and adapter_command:
+        raise ValueError("use either --settings-file or --adapter-command")
+    if timeout < 1:
+        raise ValueError("adapter timeout must be positive")
+    if settings_file:
+        try:
+            value = json.loads(settings_file.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            raise ValueError("settings file must contain a JSON object") from None
+        return normalise_review_settings(value), "settings-file"
+    if adapter_command is not None:
+        if not adapter_command or any(not isinstance(part, str) or not part for part in adapter_command):
+            raise ValueError("adapter-command must be a nonempty JSON argv array")
+        try:
+            result = subprocess.run(
+                adapter_command,
+                input=json.dumps({"schemaVersion": "maggie-blog-settings-request.v1"}),
+                text=True,
+                capture_output=True,
+                timeout=timeout,
+                check=False,
+                cwd=project.resolve(),
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            raise OSError("blog settings adapter could not execute or timed out") from None
+        if result.returncode:
+            raise OSError("blog settings adapter failed; provider output suppressed")
+        try:
+            value = json.loads(result.stdout)
+        except json.JSONDecodeError:
+            raise ValueError("blog settings adapter must return a JSON object") from None
+        return normalise_review_settings(value), "adapter-command"
+    raise ValueError("blog is not initialized; use --settings-file or --adapter-command for a provider-backed blog")
+
+
 class BlogStore:
     def __init__(self, project: Path) -> None:
         self.root = project / ".maggie" / "blog"

package/bundled-tools/runtime/maggie_favicon.py

@@ -0,0 +1,86 @@
+"""Behavioural favicon verification for a deployed origin."""
+
+from __future__ import annotations
+
+from html.parser import HTMLParser
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urljoin, urlparse
+from urllib.request import Request, urlopen
+
+from maggie_social_cards import SUPPORTED_FORMATS, _dimensions
+
+
+SCHEMA = "maggie-favicon.v1"
+
+
+class IconLinkParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.href = ""
+        self.type = ""
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag != "link":
+            return
+        data = dict(attrs)
+        rel = set(str(data.get("rel") or "").lower().split())
+        if rel & {"icon", "shortcut"} and data.get("href") and not self.href:
+            self.href = str(data["href"])
+            self.type = str(data.get("type") or "")
+
+
+def _fetch(url: str, timeout: int) -> tuple[int | None, str, bytes, str | None]:
+    try:
+        request = Request(url, headers={"User-Agent": "Maggie-Favicon-Check/1"})
+        with urlopen(request, timeout=timeout) as response:
+            raw = response.read(8_000_001)
+            if len(raw) > 8_000_000:
+                return int(response.status), response.headers.get_content_type(), b"", "response exceeds size limit"
+            return int(response.status), response.headers.get_content_type(), raw, None
+    except HTTPError as error:
+        return int(error.code), "", b"", "HTTP error"
+    except (URLError, TimeoutError, OSError):
+        return None, "", b"", "request failed"
+
+
+def _resource(url: str, timeout: int) -> dict[str, Any]:
+    status, header_type, raw, fetch_error = _fetch(url, timeout)
+    image_type, width, height = _dimensions(raw, header_type)
+    errors: list[str] = []
+    if fetch_error or status != 200:
+        errors.append(fetch_error or "icon request did not return HTTP 200")
+    if image_type not in SUPPORTED_FORMATS:
+        errors.append("unsupported favicon format")
+    if width is None or height is None:
+        errors.append("favicon dimensions could not be read")
+    elif width != height:
+        errors.append("favicon must be square")
+    return {"url": url, "statusCode": status, "format": image_type, "width": width, "height": height, "errors": errors, "passed": not errors}
+
+
+def check_favicon(origin: str, declared_url: str | None = None, timeout: int = 15) -> dict[str, Any]:
+    parsed = urlparse(origin.rstrip("/"))
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc or parsed.fragment:
+        raise ValueError("origin must be an absolute HTTP(S) URL without a fragment")
+    if timeout < 1:
+        raise ValueError("timeout must be positive")
+    base = origin.rstrip("/") + "/"
+    favicon_url = urljoin(base, "favicon.ico")
+    detected: str | None = None
+    if not declared_url:
+        status, content_type, raw, _ = _fetch(base, timeout)
+        if status == 200 and content_type == "text/html":
+            parser = IconLinkParser(); parser.feed(raw.decode("utf-8", "replace"))
+            if parser.href:
+                detected = urljoin(base, parser.href)
+    declared = declared_url or detected
+    if declared:
+        declared = urljoin(base, declared)
+        declared_parsed = urlparse(declared)
+        if declared_parsed.scheme not in {"http", "https"} or declared_parsed.fragment:
+            raise ValueError("declared-url must resolve to an absolute HTTP(S) URL without a fragment")
+    ico = _resource(favicon_url, timeout)
+    declared_check = _resource(declared, timeout) if declared and declared != favicon_url else None
+    passed = ico["passed"] and (declared_check is None or declared_check["passed"])
+    return {"schemaVersion": SCHEMA, "origin": origin.rstrip("/"), "favicon": ico, "declaredUrl": declared, "declared": declared_check, "passed": passed, "mutation": False}