@topy-ai/maggie 0.7.17 → 0.7.19

package/bundled-tools/runtime/maggie_dash_runtime.py

@@ -0,0 +1,58 @@
+"""Validate runtime evidence that a dashboard screen actually mounted and ran."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import urlparse
+
+
+SCHEMA = "maggiedash-dashboard-runtime.v1"
+
+
+def validate_runtime_evidence(evidence: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(evidence, Mapping):
+        return {"schemaVersion": SCHEMA, "passed": False, "errors": ["evidence must be an object"]}
+    if evidence.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    for field in ("screen", "route"):
+        if not isinstance(evidence.get(field), str) or not evidence[field].strip():
+            errors.append(f"{field} is required")
+    if evidence.get("mounted") is not True:
+        errors.append("mounted must be true")
+    checks = evidence.get("checks")
+    if not isinstance(checks, list) or not checks:
+        errors.append("checks must contain at least one executed check")
+        checks = []
+    check_results: list[dict[str, Any]] = []
+    for index, check in enumerate(checks):
+        if not isinstance(check, Mapping) or not isinstance(check.get("name"), str) or not check["name"].strip():
+            errors.append(f"checks[{index}] needs a name")
+            continue
+        if not isinstance(check.get("passed"), bool):
+            errors.append(f"checks[{index}].passed must be boolean")
+        elif check["passed"] is False:
+            errors.append(f"runtime check failed: {check['name']}")
+        check_results.append({"name": check["name"], "passed": check.get("passed")})
+    calls = evidence.get("dataCalls", [])
+    if not isinstance(calls, list):
+        errors.append("dataCalls must be a list")
+        calls = []
+    call_results: list[dict[str, Any]] = []
+    for index, call in enumerate(calls):
+        if not isinstance(call, Mapping):
+            errors.append(f"dataCalls[{index}] must be an object")
+            continue
+        url = str(call.get("url") or "")
+        parsed = urlparse(url)
+        if not url or parsed.username or parsed.password or parsed.scheme not in {"", "http", "https"}:
+            errors.append(f"dataCalls[{index}].url must be a relative or credential-free HTTP URL")
+        if not isinstance(call.get("method", "GET"), str):
+            errors.append(f"dataCalls[{index}].method must be a string")
+        if not isinstance(call.get("ok"), bool):
+            errors.append(f"dataCalls[{index}].ok must be boolean")
+        elif call["ok"] is False:
+            errors.append(f"data call failed: {url or 'unknown'}")
+        call_results.append({"url": url, "method": call.get("method", "GET"), "status": call.get("status"), "ok": call.get("ok")})
+    return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "screen": evidence.get("screen"), "route": evidence.get("route"), "mounted": evidence.get("mounted"), "checks": check_results, "dataCalls": call_results}

package/bundled-tools/runtime/maggie_schema_audit.py

@@ -0,0 +1,72 @@
+"""Validate host-supplied table/reader evidence without connecting to a database."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+SCHEMA = "maggie-schema-inventory.v1"
+
+
+def audit_schema_inventory(inventory: object, *, fail_on_unread: bool = False) -> dict[str, Any]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if not isinstance(inventory, Mapping):
+        return {"schemaVersion": SCHEMA, "passed": False, "errors": ["inventory must be an object"], "tables": []}
+    if inventory.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    tables = inventory.get("tables")
+    if not isinstance(tables, list):
+        errors.append("tables must be a list")
+        tables = []
+    seen: set[str] = set()
+    normalized: list[dict[str, Any]] = []
+    unread: list[dict[str, Any]] = []
+    unknown: list[str] = []
+    for index, table in enumerate(tables):
+        prefix = f"tables[{index}]"
+        if not isinstance(table, Mapping):
+            errors.append(f"{prefix} must be an object")
+            continue
+        name = str(table.get("name") or "").strip()
+        if not name:
+            errors.append(f"{prefix}.name is required")
+            continue
+        if name in seen:
+            errors.append(f"duplicate table: {name}")
+        seen.add(name)
+        row_count = table.get("rowCount")
+        if not isinstance(row_count, int) or isinstance(row_count, bool) or row_count < 0:
+            errors.append(f"{prefix}.rowCount must be a non-negative integer")
+            row_count = None
+        readers = table.get("readers")
+        if readers is None:
+            unknown.append(name)
+            warnings.append(f"{name} has no reader evidence")
+            reader_list: list[str] = []
+            reader_status = "unknown"
+        elif not isinstance(readers, list) or any(not isinstance(reader, str) or not reader.strip() for reader in readers):
+            errors.append(f"{prefix}.readers must be a list of non-empty strings")
+            reader_list = []
+            reader_status = "invalid"
+        else:
+            reader_list = sorted({reader.strip() for reader in readers})
+            reader_status = "read" if reader_list else "unread"
+        record = {"name": name, "rowCount": row_count, "readers": reader_list, "readerStatus": reader_status}
+        normalized.append(record)
+        if reader_status == "unread":
+            unread.append(record)
+    if fail_on_unread and unread:
+        errors.append(f"{len(unread)} declared table(s) have no reader evidence")
+    return {
+        "schemaVersion": SCHEMA,
+        "passed": not errors,
+        "errors": errors,
+        "warnings": warnings,
+        "tables": normalized,
+        "unreadTables": unread,
+        "unknownReaderEvidence": unknown,
+        "tableCount": len(normalized),
+        "unreadCount": len(unread),
+    }

package/bundled-tools/runtime/service_variants.py

@@ -35,6 +35,16 @@ def variant_slug(kind: str, *, location: str = "", event: str = "", holiday: str
     return f"{kind}/{slug_part(value)}"
 
 
+def locale_segment(value: str) -> str:
+    """Return the stable lowercase URL segment for a BCP 47-like locale."""
+    return slug_part(value.replace("_", "-"))
+
+
+def variant_canonical_url(slug: str, locale: str, market: str) -> str:
+    """Build a collision-safe, market/language-aware service URL."""
+    return f"/services/{slug_part(market)}/{locale_segment(locale)}/{slug.strip('/')}/"
+
+
 def similarity(source: str, variant: str) -> float:
     left, right = set(re.findall(r"[a-z0-9]+", source.lower())), set(re.findall(r"[a-z0-9]+", variant.lower()))
     return 1.0 if not left and not right else len(left & right) / max(1, len(left | right))
@@ -62,6 +72,20 @@ class ServiceVariantStore:
             raise ValueError("service variant not found")
         return found
 
+    def _cluster(self, canonical_variant_id: str) -> list[dict]:
+        return [
+            item for item in self.data["variants"]
+            if item.get("id") == canonical_variant_id or item.get("canonicalVariantId") == canonical_variant_id
+        ]
+
+    def _refresh_hreflang(self, canonical_variant_id: str) -> None:
+        """Keep published locale links reciprocal and limited to published peers."""
+        cluster = self._cluster(canonical_variant_id)
+        published = [item for item in cluster if item.get("status") == "published"]
+        published_links = {item["locale"]: item["canonicalUrl"] for item in published}
+        for item in cluster:
+            item["hreflang"] = published_links if item in published else {item["locale"]: item["canonicalUrl"]}
+
     def create(self, *, service_id: str, variant_id: str, variant_type: str, locale: str, market: str,
                slug: str, title: str, facts: list[dict], source_revision: str, canonical_variant_id: str | None = None,
                cluster_links: list[str] | None = None, layout_family: str = "service-default", actor: str = "cli") -> dict:
@@ -73,15 +97,19 @@ class ServiceVariantStore:
             raise ValueError("variant requires meaningful keyed facts")
         if any(item["id"] == variant_id for item in self.data["variants"]):
             raise ValueError("variant ID already exists")
-        if any(item["slug"] == slug and item["locale"] == locale for item in self.data["variants"]):
-            raise ValueError("variant slug and locale collision")
         if canonical_variant_id and not any(item["id"] == canonical_variant_id for item in self.data["variants"]):
             raise ValueError("canonical variant does not exist")
+        canonical_url = variant_canonical_url(slug, locale, market)
+        if any(item.get("canonicalUrl") == canonical_url for item in self.data["variants"]):
+            raise ValueError("variant market, locale and slug route collision")
+        family = canonical_variant_id or variant_id
+        if any(item.get("canonicalVariantId") == family and item.get("locale") == locale for item in self.data["variants"]):
+            raise ValueError("variant locale collision in translation cluster")
         item = {"id": variant_id, "serviceId": service_id, "variantType": variant_type, "locale": locale,
                 "market": market, "slug": slug, "title": title, "facts": facts,
                 "clusterLinks": sorted(set(cluster_links or [])), "layoutFamily": layout_family,
-                "canonicalVariantId": canonical_variant_id or variant_id, "canonicalUrl": "/services/" + slug + "/",
-                "hreflang": {locale: "/services/" + slug + "/"}, "sourceRevision": source_revision,
+                "canonicalVariantId": family, "canonicalUrl": canonical_url,
+                "hreflang": {locale: canonical_url}, "sourceRevision": source_revision,
                 "provenance": {"operation": "create", "actor": actor, "sourceRevision": source_revision},
                 "status": "draft", "createdAt": now(), "updatedAt": now()}
         self.data["variants"].append(item); self._event("variant.created", variant_id, actor, "draft created"); self._save()
@@ -120,6 +148,7 @@ class ServiceVariantStore:
                 raise ValueError("canonical source must be published before a translated variant")
         old = item["status"]; item["status"] = target; item["updatedAt"] = now()
         item.setdefault("approval", []).append({"from": old, "to": target, "actor": actor, "reason": reason, "at": now()})
+        self._refresh_hreflang(item["canonicalVariantId"])
         self._event("variant." + target, variant_id, actor, reason); self._save(); return item
 
     def plan_slug_change(self, variant_id: str, new_slug: str, actor: str) -> dict:
@@ -128,17 +157,29 @@ class ServiceVariantStore:
             raise ValueError("published URL changes require owner approval")
         if not new_slug.startswith(item["variantType"] + "/") or not SLUG_WORD.fullmatch(new_slug.split("/", 1)[-1]):
             raise ValueError("new slug violates variant grammar")
-        if any(v["slug"] == new_slug and v["locale"] == item["locale"] for v in self.data["variants"] if v["id"] != variant_id):
-            raise ValueError("new slug collides with another variant")
-        redirect = {"from": item["canonicalUrl"], "to": "/services/" + new_slug + "/", "ownerApproval": actor, "status": "planned"}
+        new_url = variant_canonical_url(new_slug, item["locale"], item["market"])
+        if any(v.get("canonicalUrl") == new_url for v in self.data["variants"] if v["id"] != variant_id):
+            raise ValueError("new market, locale and slug route collides with another variant")
+        redirect = {"from": item["canonicalUrl"], "to": new_url, "ownerApproval": actor, "status": "planned"}
         self.data["redirects"].append(redirect); self._save(); return redirect
 
     def validate(self, variant_id: str, source_text: str | None = None, render_report: dict | None = None) -> dict:
         item = self._find(variant_id); errors = []
+        expected_url = variant_canonical_url(item["slug"], item["locale"], item["market"])
+        if item.get("canonicalUrl") != expected_url:
+            errors.append("canonical URL must include market, locale and variant slug")
         if not item["clusterLinks"] and item["variantType"] != "location": errors.append("cluster links required")
         if source_text is not None and similarity(source_text, item["title"] + " " + " ".join(str(f["value"]) for f in item["facts"])) < 0.1:
             errors.append("variant content has no meaningful similarity to source")
         if item["canonicalVariantId"] != item["id"] and item["canonicalVariantId"] not in {v["id"] for v in self.data["variants"]}: errors.append("canonical relation missing")
+        if item.get("status") == "published":
+            expected_hreflang = {
+                peer["locale"]: peer["canonicalUrl"]
+                for peer in self._cluster(item["canonicalVariantId"])
+                if peer.get("status") == "published"
+            }
+            if item.get("hreflang") != expected_hreflang:
+                errors.append("published hreflang links must be reciprocal published counterparts")
         if render_report is not None:
             if render_report.get("schemaVersion") != "maggie-service-variant-render.v1" or render_report.get("passed") is not True:
                 errors.append("render report is not passed")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.17",
+  "version": "0.7.19",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/universal-booking-adapter.md

@@ -25,8 +25,10 @@ when a title changes.
     "title": "Signature Scalp Ritual",
     "description": "Provider-supplied factual description.",
     "category": {"level1": "Head Spa", "level2": "Scalp Treatments"},
-    "variants": [{
+  "variants": [{
       "id": "service-123:60",
+      "idSource": "provider",
+      "variantSource": "native",
       "title": "60 minutes",
       "durationMinutes": 60,
       "price": {"amountMinor": 9500, "currency": "GBP", "display": "£95.00"}
@@ -147,3 +149,36 @@ Provider adapters may add `raw` evidence in a private local snapshot, but
 public page generation consumes only the canonical fields above. A sync must
 preserve removed records as `archived` with `removedAt` and must output a
 change report.
+
+## Provider variant capability matrix
+
+Before service pages are published, each provider declares its variant
+behavior in a project-owned JSON file. The declaration is validated against a
+sanitized fixture and emits `maggie-provider-variant-capabilities.v1`:
+
+```json
+{
+  "schemaVersion": "maggie-provider-capabilities.v1",
+  "providers": [{
+    "provider": "fresha",
+    "variantMode": "native",
+    "priceSemantics": "minor-unit-and-display",
+    "stableIdConfidence": "high"
+  }]
+}
+```
+
+`variantMode` is one of `native`, `derived-offers`, `single-fallback`, or
+`blocked`. `priceSemantics` records whether structured minor units and display
+prices are available. `stableIdConfidence` must be justified by provider or
+derived ID evidence. The audit records service/variant counts, observed source
+types, fixture name and hash, and validation errors without copying fixture
+rows or provider credentials. Run it with:
+
+```bash
+maggie service capability-audit \
+  --project . \
+  --catalogue .maggie/booking/services.json \
+  --capabilities-file .maggie/booking/provider-capabilities.json \
+  --fixture .maggie/booking/fixtures/provider.json
+```