@topy-ai/maggie 0.7.0 → 0.7.1

package/bundled-tools/clis/maggie_ops.py

@@ -9,6 +9,10 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from dependency_lock import audit as audit_lockfiles
+from seed_evidence import validate_manifest
+
 
 REQUIRED_ROUTES = (
     "/ops", "/ops/posts", "/ops/sitemap", "/ops/reports",
@@ -132,14 +136,30 @@ def command_verify(args: argparse.Namespace) -> int:
     return 0 if result["checks"]["ready"] and result["stateFile"] else 1
 
 
+def command_lockfiles(args: argparse.Namespace) -> int:
+    result = audit_lockfiles(root(args))
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
+def command_seed_manifest(args: argparse.Namespace) -> int:
+    value = read_json(Path(args.manifest).resolve())
+    result = validate_manifest(value)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--project", default=".")
     sub = parser.add_subparsers(dest="command", required=True)
-    for name, handler in (("audit", command_audit), ("preflight", command_preflight), ("status", command_status), ("verify", command_verify)):
+    for name, handler in (("audit", command_audit), ("preflight", command_preflight), ("status", command_status), ("verify", command_verify), ("lockfiles", command_lockfiles)):
         command = sub.add_parser(name)
         if name == "preflight": command.add_argument("--write", action="store_true")
         command.set_defaults(func=handler)
+    seed = sub.add_parser("seed-manifest", help="validate explicit sanitized development fixtures")
+    seed.add_argument("--manifest", required=True)
+    seed.set_defaults(func=command_seed_manifest)
     record = sub.add_parser("record", help="record an explicitly authorised operation")
     record.add_argument("operation", choices=("sync", "sitemap-match", "rewrite-queue", "rewrite-approve", "publish", "migration"))
     record.add_argument("--dry-run", action="store_true")

package/bundled-tools/clis/maggie_service_booking.py

@@ -10,6 +10,9 @@ from pathlib import Path
 from urllib.parse import quote, urljoin, urlsplit
 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
+
 NOW = lambda: datetime.now(timezone.utc).isoformat()
 MONEY = re.compile(r"(?:£|GBP\s*)\s*([0-9]+(?:[.,][0-9]{1,2})?)", re.I)
 DURATION = re.compile(r"(\d{2,3})\s*(?:min|mins|minutes?)", re.I)
@@ -751,7 +754,7 @@ def inventory_candidates(project, pages_root):
     found={}
     for page in pages_root.rglob("*") if pages_root.exists() else []:
         if page.is_file() and page.suffix.lower() in {".astro",".md",".mdx",".html"} and page.stem not in {"index","404"}:
-            found["/"+str(page.relative_to(project)).replace("\\","/")]={"path":"/"+str(page.relative_to(project)).replace("\\","/"),"text":page_text(page),"canonical":None,"pageType":"filesystem"}
+            found["/"+str(page.relative_to(project)).replace("\\","/")]={"path":"/"+str(page.relative_to(project)).replace("\\","/"),"text":page_text(page),"canonical":None,"pageType":"filesystem","imports":imported_components(page)}
     for name in ("pages.json","page-content.json"):
         source=project/"docs"/name
         if not source.exists(): continue
@@ -762,7 +765,7 @@ def inventory_candidates(project, pages_root):
             if not isinstance(item,dict): continue
             value=item.get("path") or item.get("url") or item.get("route")
             if not value: continue
-            current=found.setdefault(value,{"path":value,"text":"","canonical":None,"pageType":"inventory"}); current["text"]+=" "+str(item.get("content") or item.get("text") or item.get("title") or ""); current["canonical"]=item.get("canonicalUrl") or item.get("canonical") or current["canonical"]; current["pageType"]=item.get("pageType") or current["pageType"]
+            current=found.setdefault(value,{"path":value,"text":"","canonical":None,"pageType":"inventory","imports":[]}); current["text"]+=" "+str(item.get("content") or item.get("text") or item.get("title") or ""); current["canonical"]=item.get("canonicalUrl") or item.get("canonical") or current["canonical"]; current["pageType"]=item.get("pageType") or current["pageType"]
     return list(found.values())
 def cmd_match_pages_review(args):
     project=root(args); data=load(project); candidates=inventory_candidates(project,(project/args.pages_dir).resolve()); aliases={"lymphatic drainage":{"lymphatic","lymph drainage","lymphdrainage","manual lymphatic","ml d"},"deep tissue":{"deep tissue","therapeutic massage"},"thai":{"thai massage","thai"},"postpartum":{"postpartum","new mom"},"facial":{"facial","hydra facial","hydrafacial"},"massage":{"massage"}}
@@ -779,7 +782,7 @@ def cmd_match_pages_review(args):
         matches=[]
         for page in candidates:
             path_slug=slug(page["path"].rsplit("/",1)[-1].rsplit(".",1)[0]); page_words=page_tokens(path_slug+" "+page["text"][:2000]); exact=path_slug==service.get("slug"); overlap=len(expanded & page_words)/max(1,len(expanded)); generic=bool(concepts & {"massage","facial","acupuncture","waxing"}) and overlap<0.75; score=1.0 if exact else min(0.49 if generic else overlap,0.99)
-            if score>=0.45: matches.append({"path":page["path"],"role":"supporting","pageType":page["pageType"],"canonicalUrl":page["canonical"],"matchedConcepts":sorted(expanded & page_words),"method":"slug" if exact else "semantic-concepts","confidence":round(score,3)})
+            if score>=0.45: matches.append({"path":page["path"],"role":"supporting","pageType":page["pageType"],"canonicalUrl":page["canonical"],"matchedConcepts":sorted(expanded & page_words),"imports":page.get("imports",[]),"method":"slug" if exact else "semantic-concepts","confidence":round(score,3)})
         matches.sort(key=lambda x:(-x["confidence"],x["path"])); report.append({"serviceId":service["id"],"title":service["title"],"candidates":matches})
         for path_value in selections.get(service["id"], []):
             if path_value in {m["path"] for m in matches}: selected.append((service,path_value))

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/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/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/maggie_dash_store.py

@@ -4,10 +4,12 @@
 from __future__ import annotations
 
 import hashlib
+import base64
+import hmac
 import json
 import sqlite3
 import uuid
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any
 
@@ -55,6 +57,20 @@ class MaggieDashStore:
               created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
               UNIQUE(project_id, slug)
             );
+            CREATE TABLE IF NOT EXISTS maggiedash_document_revisions (
+              id TEXT PRIMARY KEY, document_id TEXT NOT NULL REFERENCES maggiedash_documents(id),
+              revision INTEGER NOT NULL, title TEXT NOT NULL, slug TEXT NOT NULL,
+              locale TEXT NOT NULL, excerpt TEXT NOT NULL, content_json TEXT NOT NULL,
+              canonical_url TEXT, provenance_json TEXT NOT NULL, checksum TEXT NOT NULL,
+              created_at TEXT NOT NULL, created_by TEXT NOT NULL,
+              UNIQUE(document_id, revision)
+            );
+            CREATE TABLE IF NOT EXISTS maggiedash_redirects (
+              id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES maggiedash_projects(id),
+              from_path TEXT NOT NULL, to_path TEXT NOT NULL, status_code INTEGER NOT NULL DEFAULT 301,
+              reason TEXT NOT NULL, actor_id TEXT NOT NULL, created_at TEXT NOT NULL,
+              UNIQUE(project_id, from_path)
+            );
             CREATE TABLE IF NOT EXISTS maggiedash_approvals (
               id TEXT PRIMARY KEY, document_id TEXT NOT NULL REFERENCES maggiedash_documents(id),
               from_status TEXT NOT NULL, to_status TEXT NOT NULL, actor_id TEXT NOT NULL,
@@ -68,6 +84,15 @@ class MaggieDashStore:
             );
             """
         )
+        self._ensure_column("maggiedash_documents", "trashed_at", "TEXT")
+        self._ensure_column("maggiedash_documents", "trashed_from_status", "TEXT")
+        self._ensure_column("maggiedash_documents", "publish_at", "TEXT")
+        self.connection.commit()
+
+    def _ensure_column(self, table: str, column: str, definition: str) -> None:
+        columns = {row[1] for row in self.connection.execute(f"PRAGMA table_info({table})")}
+        if column not in columns:
+            self.connection.execute(f"ALTER TABLE {table} ADD COLUMN {column} {definition}")
 
     def close(self) -> None:
         self.connection.close()
@@ -97,22 +122,27 @@ class MaggieDashStore:
             raise ValueError(f"invalid document status: {status}")
         stable = {key: value for key, value in document.items() if key not in {"provenance", "checksum"}}
         document_checksum = document.get("provenance", {}).get("checksum") or checksum(stable)
-        existing = self.connection.execute("SELECT status FROM maggiedash_documents WHERE id=?", (document["id"],)).fetchone()
+        existing = self.connection.execute("SELECT * FROM maggiedash_documents WHERE id=?", (document["id"],)).fetchone()
         if existing and existing["status"] != status:
             raise ValueError("status changes must use transition()")
+        if existing and existing["checksum"] != document_checksum:
+            self._store_revision(existing, actor_id)
         self.connection.execute(
             """INSERT INTO maggiedash_documents
-            (id,project_id,kind,title,slug,locale,status,excerpt,content_json,canonical_url,provenance_json,checksum,created_at,updated_at)
-            VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+            (id,project_id,kind,title,slug,locale,status,excerpt,content_json,canonical_url,provenance_json,checksum,created_at,updated_at,publish_at)
+            VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
             ON CONFLICT(id) DO UPDATE SET title=excluded.title, slug=excluded.slug,
               locale=excluded.locale, excerpt=excluded.excerpt, content_json=excluded.content_json,
               canonical_url=excluded.canonical_url, provenance_json=excluded.provenance_json,
-              checksum=excluded.checksum, updated_at=excluded.updated_at""",
+              checksum=excluded.checksum, updated_at=excluded.updated_at,
+              publish_at=excluded.publish_at, trashed_at=NULL, trashed_from_status=NULL""",
             (document["id"], project_id, document["kind"], document["title"], document["slug"], document["locale"],
              status, document.get("excerpt", ""), json.dumps(document["content"], ensure_ascii=False),
              document.get("canonicalUrl"), json.dumps(document["provenance"], ensure_ascii=False), document_checksum,
-             timestamp, timestamp),
+             timestamp, timestamp, document.get("publishAt")),
         )
+        if not existing:
+            self._store_revision(self.connection.execute("SELECT * FROM maggiedash_documents WHERE id=?", (document["id"],)).fetchone(), actor_id)
         self._audit(project_id, "document.upserted", "document", document["id"], actor_id, "draft content stored")
         self.connection.commit()
         return self.get_document(project_id, document["id"]) or {}
@@ -125,8 +155,122 @@ class MaggieDashStore:
         result["content"] = json.loads(result.pop("content_json"))
         result["provenance"] = json.loads(result.pop("provenance_json"))
         result["canonicalUrl"] = result.pop("canonical_url")
+        result["trashedAt"] = result.pop("trashed_at")
+        result["trashedFromStatus"] = result.pop("trashed_from_status")
+        result["publishAt"] = result.pop("publish_at")
         return result
 
+    def _store_revision(self, row: sqlite3.Row, actor_id: str) -> None:
+        revision = self.connection.execute(
+            "SELECT COALESCE(MAX(revision), 0) + 1 FROM maggiedash_document_revisions WHERE document_id=?",
+            (row["id"],),
+        ).fetchone()[0]
+        self.connection.execute(
+            "INSERT INTO maggiedash_document_revisions VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)",
+            (str(uuid.uuid4()), row["id"], revision, row["title"], row["slug"], row["locale"], row["excerpt"],
+             row["content_json"], row["canonical_url"], row["provenance_json"], row["checksum"], row["updated_at"], actor_id),
+        )
+
+    def list_revisions(self, project_id: str, document_id: str) -> list[dict[str, Any]]:
+        if not self.get_document(project_id, document_id):
+            raise ValueError("document not found")
+        rows = self.connection.execute(
+            "SELECT * FROM maggiedash_document_revisions WHERE document_id=? ORDER BY revision DESC", (document_id,)
+        ).fetchall()
+        return [dict(row) for row in rows]
+
+    def trash(self, project_id: str, document_id: str, actor_id: str, reason: str) -> dict[str, Any]:
+        row = self.connection.execute("SELECT status, trashed_at FROM maggiedash_documents WHERE project_id=? AND id=?", (project_id, document_id)).fetchone()
+        if not row:
+            raise ValueError("document not found")
+        if row["trashed_at"]:
+            return self.get_document(project_id, document_id) or {}
+        timestamp = now()
+        self.connection.execute("UPDATE maggiedash_documents SET trashed_at=?, trashed_from_status=?, updated_at=? WHERE id=?", (timestamp, row["status"], timestamp, document_id))
+        self._audit(project_id, "document.trashed", "document", document_id, actor_id, reason)
+        self.connection.commit()
+        return self.get_document(project_id, document_id) or {}
+
+    def restore(self, project_id: str, document_id: str, actor_id: str, reason: str) -> dict[str, Any]:
+        row = self.connection.execute("SELECT trashed_at, trashed_from_status FROM maggiedash_documents WHERE project_id=? AND id=?", (project_id, document_id)).fetchone()
+        if not row:
+            raise ValueError("document not found")
+        if not row["trashed_at"]:
+            return self.get_document(project_id, document_id) or {}
+        status = row["trashed_from_status"] if row["trashed_from_status"] in STATUSES else "draft"
+        timestamp = now()
+        self.connection.execute("UPDATE maggiedash_documents SET status=?, trashed_at=NULL, trashed_from_status=NULL, updated_at=? WHERE id=?", (status, timestamp, document_id))
+        self._audit(project_id, "document.restored", "document", document_id, actor_id, reason)
+        self.connection.commit()
+        return self.get_document(project_id, document_id) or {}
+
+    def schedule_publish(self, project_id: str, document_id: str, publish_at: str, actor_id: str, reason: str) -> dict[str, Any]:
+        try:
+            target = datetime.fromisoformat(publish_at.replace("Z", "+00:00"))
+        except ValueError as exc:
+            raise ValueError("publish_at must be an ISO-8601 timestamp") from exc
+        if target.tzinfo is None:
+            raise ValueError("publish_at must include a timezone")
+        document = self.get_document(project_id, document_id)
+        if not document:
+            raise ValueError("document not found")
+        if document["status"] not in {"approved", "scheduled"}:
+            raise ValueError("only approved documents can be scheduled")
+        if document["status"] == "approved":
+            self.transition(project_id, document_id, "scheduled", actor_id, reason)
+        self.connection.execute("UPDATE maggiedash_documents SET publish_at=?, updated_at=? WHERE id=?", (publish_at, now(), document_id))
+        self._audit(project_id, "document.publish_scheduled", "document", document_id, actor_id, reason)
+        self.connection.commit()
+        return self.get_document(project_id, document_id) or {}
+
+    def duplicate(self, project_id: str, document_id: str, new_id: str, new_slug: str, actor_id: str, reason: str) -> dict[str, Any]:
+        source = self.get_document(project_id, document_id)
+        if not source:
+            raise ValueError("document not found")
+        if self.connection.execute("SELECT 1 FROM maggiedash_documents WHERE project_id=? AND slug=?", (project_id, new_slug)).fetchone():
+            raise ValueError("new slug already exists")
+        copy = dict(source)
+        copy.update({"id": new_id, "slug": new_slug, "status": "draft", "provenance": {**source["provenance"], "duplicatedFrom": document_id}})
+        copy.pop("trashedAt", None); copy.pop("trashedFromStatus", None); copy.pop("publishAt", None)
+        result = self.put_document(project_id, copy, actor_id)
+        self._audit(project_id, "document.duplicated", "document", new_id, actor_id, reason)
+        self.connection.commit()
+        return result
+
+    def add_redirect(self, project_id: str, from_path: str, to_path: str, actor_id: str, reason: str, status_code: int = 301) -> dict[str, Any]:
+        if not from_path.startswith("/") or not to_path.startswith("/") or from_path == to_path:
+            raise ValueError("redirect paths must be distinct absolute paths")
+        if status_code not in {301, 302, 307, 308}:
+            raise ValueError("status_code must be 301, 302, 307 or 308")
+        record = (str(uuid.uuid4()), project_id, from_path, to_path, status_code, reason, actor_id, now())
+        self.connection.execute("INSERT INTO maggiedash_redirects VALUES (?,?,?,?,?,?,?,?) ON CONFLICT(project_id,from_path) DO UPDATE SET to_path=excluded.to_path, status_code=excluded.status_code, reason=excluded.reason, actor_id=excluded.actor_id, created_at=excluded.created_at", record)
+        self._audit(project_id, "redirect.upserted", "redirect", from_path, actor_id, reason)
+        self.connection.commit()
+        row = self.connection.execute("SELECT * FROM maggiedash_redirects WHERE project_id=? AND from_path=?", (project_id, from_path)).fetchone()
+        return dict(row)
+
+    def issue_preview(self, project_id: str, document_id: str, secret: str, ttl_seconds: int = 900) -> dict[str, Any]:
+        if not secret:
+            raise ValueError("preview secret is required")
+        if not self.get_document(project_id, document_id):
+            raise ValueError("document not found")
+        expires = int((datetime.now(timezone.utc) + timedelta(seconds=ttl_seconds)).timestamp())
+        payload = f"{project_id}:{document_id}:{expires}".encode()
+        encoded = base64.urlsafe_b64encode(payload).decode().rstrip("=")
+        signature = hmac.new(secret.encode(), encoded.encode(), hashlib.sha256).hexdigest()
+        return {"token": f"{encoded}.{signature}", "expiresAt": datetime.fromtimestamp(expires, timezone.utc).isoformat().replace("+00:00", "Z")}
+
+    @staticmethod
+    def verify_preview(token: str, secret: str, project_id: str, document_id: str) -> bool:
+        try:
+            encoded, signature = token.split(".", 1)
+            expected = hmac.new(secret.encode(), encoded.encode(), hashlib.sha256).hexdigest()
+            payload = base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4)).decode()
+            token_project, token_document, expires = payload.split(":", 2)
+            return hmac.compare_digest(signature, expected) and token_project == project_id and token_document == document_id and int(expires) >= int(datetime.now(timezone.utc).timestamp())
+        except (ValueError, TypeError, UnicodeDecodeError):
+            return False
+
     def transition(self, project_id: str, document_id: str, target: str, actor_id: str, reason: str) -> dict[str, Any]:
         if target not in STATUSES:
             raise ValueError(f"invalid target status: {target}")

package/bundled-tools/runtime/maggie_dash_ui.py

@@ -0,0 +1,60 @@
+"""Validate the provider-neutral MaggieDash dashboard chrome contract."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Iterable
+
+
+SCHEMA = "maggiedash-dashboard-ui.v1"
+
+
+def _component_source(name: str, source: str) -> str:
+    match = re.search(rf"(?:function\s+{re.escape(name)}\s*\([^)]*\)|const\s+{re.escape(name)}\s*=\s*\([^)]*\))(?P<body>[\s\S]{{0,12000}})", source)
+    return match.group(0) if match else ""
+
+
+def validate(contract: object, sources: Iterable[str] = ()) -> dict:
+    errors: list[str] = []
+    if not isinstance(contract, dict):
+        return {"schemaVersion": SCHEMA, "passed": False, "errors": ["contract must be an object"]}
+    if contract.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    shell = contract.get("shell")
+    if not isinstance(shell, dict):
+        errors.append("shell is required")
+    elif shell.get("reference") != "users-workspace" or shell.get("navigation") != "sidebar-plus-content-tabs":
+        errors.append("shell must declare the users-workspace reference and sidebar-plus-content-tabs navigation")
+    components = contract.get("components")
+    if not isinstance(components, list) or not components:
+        errors.append("components must be a non-empty list")
+        components = []
+    source = "\n".join(str(item) for item in sources)
+    for component in components:
+        if not isinstance(component, dict) or not component.get("name"):
+            errors.append("each component needs a name")
+            continue
+        name = str(component["name"])
+        component_source = _component_source(name, source)
+        if source and not component_source:
+            errors.append(f"component source is missing: {name}")
+            continue
+        props = [str(prop) for prop in component.get("props", [])]
+        forbidden = [str(prop) for prop in component.get("forbiddenProps", [])]
+        if component_source:
+            signature = component_source.split("=>", 1)[0] if "=>" in component_source else component_source[:500]
+            for prop in props:
+                if len(re.findall(rf"\b{re.escape(prop)}\b", component_source)) < 2:
+                    errors.append(f"{name}.{prop} is declared but not evidenced in rendered output")
+            for prop in forbidden:
+                if re.search(rf"\b{re.escape(prop)}\b", signature):
+                    errors.append(f"{name} declares forbidden dead prop: {prop}")
+    return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "components": [item.get("name") for item in components if isinstance(item, dict)]}
+
+
+def load_and_validate(contract_path: Path, source_paths: Iterable[Path] = ()) -> dict:
+    import json
+    contract = json.loads(contract_path.read_text(encoding="utf-8"))
+    sources = [path.read_text(encoding="utf-8", errors="replace") for path in source_paths]
+    return validate(contract, sources)