@topy-ai/maggie 0.7.48 → 0.7.49

package/bundled-skills/maggie-social-share/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-social-share
 description: Turn approved AI CMO articles and content assets into platform-native social drafts, scheduled posts, and measured distribution. Use for Social Share planning, LinkedIn/Facebook copy, CTA mapping, calendars, approvals, publish retries, or social performance readback.
 metadata:
-  version: 1.0.0
+  version: 1.1.0
 ---
 
 # Maggie Social Share
@@ -39,6 +39,22 @@ maggie tool maggie_social_share.py adapters .maggie/social-adapters.json
 maggie tool maggie_social_share.py connections .maggie/social-connections.json
 maggie tool maggie_social_share.py campaigns .maggie/social-campaigns.json
 maggie tool maggie_social_share.py queue .maggie/social-queue.json --slots 14
+maggie tool maggie_social_share.py reconcile .maggie/social-attempts.json
+```
+
+A publishing adapter also declares limits, media rules, pending behaviour,
+retry classes (a timeout is an unknown outcome, never retryable), idempotency,
+and readback. `reconcile` turns the attempt log plus provider readback into
+adopt / await / retry-with-the-same-key / fail decisions, so a
+timeout-after-success never creates a duplicate post.
+
+When social work is part of a wider campaign, record it in a
+[marketing run](references/marketing-run.md) with named schedule layers
+(infrastructure, content calendar, campaign flight, measurement window) and,
+for regulated content, a review that gates only external publication:
+
+```bash
+maggie tool maggie_marketing_run.py validate .maggie/marketing-runs/<runId>.json
 ```
 
 1. Select an approved or explicitly shareable source article/content asset.
@@ -54,7 +70,8 @@ maggie tool maggie_social_share.py queue .maggie/social-queue.json --slots 14
    overdue posts). Campaign ideas stay in the idea stage until written, and a
    campaign starts only through the Start gate.
 6. Publish only after the required approval and entitlement checks. Record the
-   publication attempt and provider ID; retry only with bounded idempotency.
+   publication attempt and provider ID; reconcile unknown outcomes against
+   readback and retry only with the original idempotency key.
 7. Read back clicks, engagement, assisted conversions, and failures separately
    from article SEO/GEO metrics.
 

package/bundled-skills/maggie-social-share/references/marketing-run.md

@@ -0,0 +1,57 @@
+# Marketing runs, schedule layers, and regulated-content review
+
+A marketing run joins content, Social Share, Ads, and measurement under one
+project-scoped `runId`. It is a reference record: it points at source
+revisions, capability evidence, approvals, mutations, and readbacks by ID and
+never stores provider secrets or large payloads.
+
+Schema: `contracts/maggie-ops/marketing-run-v1.schema.json`
+(`schemaVersion: maggie-marketing-run-v1`). Validate with:
+
+```bash
+maggie tool maggie_marketing_run.py validate .maggie/marketing-runs/<runId>.json
+maggie tool maggie_marketing_run.py layers          # print the layer model
+```
+
+## Run fields
+
+| Field | Purpose |
+|---|---|
+| `runId`, `projectRef` | One project-scoped correlation ID across every channel. |
+| `objective`, `conversion` | What the run is for and which event (and source) proves it. |
+| `channels`, `timezone`, `mode` | Channels involved, the run's IANA zone, and `draft`/`scheduled`/`executing`/`completed`/`cancelled`. |
+| `sourceRevisions` | `{sourceId, revision}` of every content source used. |
+| `capabilityEvidence` | IDs/paths of capability reports (for example a Google capability report). |
+| `approval` | `state`, `actor`, `approvalId`; external mutations require `approved`. |
+| `scheduleLayers` | Named layers (below); a run never carries a single `scheduled_at`. |
+| `mutations` | `{mutationId, kind, channel, status, idempotencyKey, approvalRef}`; external publication and Ads changes need an idempotency key. |
+| `readbacks` | `{readbackId, mutationRef}`; a succeeded mutation needs one before the run is `completed`. |
+| `policy`, `stages` | Regulated-content review (below). |
+
+## Schedule layers
+
+| Layer | Meaning | Owner | Notes |
+|---|---|---|---|
+| `infrastructure` | When a worker wakes up (cron, systemd timer, queue). | Operations | Points at a `maggie_schedule.py` job via `scheduleRef`; never a publish time. |
+| `content_calendar` | When reviewed content or social posts may publish. | Editor/marketer | Social Share's slot queue; `start` required. |
+| `campaign_flight` | When paid campaigns may run and spend. | Ads owner | `start` and `end` required. |
+| `measurement_window` | Collection and attribution period. | Analytics | `start`, `end`, and `lagDays` for conversion lag. |
+
+Every layer declares `timezone`, `owner`, `status`, and a `reconciliation`
+rule describing how its real state is read back. `maggie_schedule.py` jobs are
+always the `infrastructure` layer and reject publish-time fields.
+
+## Regulated-content review
+
+`policy.regulatedContent` is off by default, so existing runs are unchanged.
+When it is on, only the **external publication** action waits for
+`policy.reviewState: approved`. Content delivery and pull (including legacy
+plugins), draft creation, SEO/GEO work, and measurement continue; policy
+labels are additive metadata, never a gate in the delivery path.
+
+The validator fails when:
+
+- a stage other than `external_publication` is `blocked` with reason
+  `policy_review`;
+- an `external_publication` mutation is pending or succeeded before the review
+  is approved.

package/bundled-skills/maggie-social-share/references/queue-and-connections.md

@@ -99,3 +99,54 @@ Rules the planner applies, in order:
 
 The plan is advisory output for the host scheduler, which re-plans after every
 publish, approval, or queue edit instead of persisting stale per-post times.
+
+## Publish contract — `adapters` with `"publishes": true`
+
+An adapter that publishes must declare, in addition to its scope set:
+
+| Field | Meaning |
+|---|---|
+| `limits.text_max` | Provider text limit used by `validate`. |
+| `media.types`, `media.max_bytes` | Accepted media and size budget. |
+| `pending.states`, `pending.max_pending_seconds` | Provider "processing" states and how long a post may stay there before it is treated as failed. |
+| `retry_classes.retryable` / `.terminal` / `.unknown_outcome` | Provider error classes. A timeout is always `unknown_outcome`: the post may already exist. |
+| `idempotency.key_source`, `idempotency.provider_supported` | How the stable key is derived (for example `queue_item_id+revision`) and whether the provider honours it. |
+| `readback.lookup` | `by_idempotency_key` (only when the provider supports keys), `by_marker` (key embedded in the post), or `by_recent_posts`. |
+
+Adapters without `publishes` keep the scope-only shape.
+
+## Publish reconciliation — `reconcile`
+
+`reconcile` reads the publish-attempt log and a provider readback and returns
+one safe action per queue item. It never publishes.
+
+```json
+{
+  "attempts": [{"queue_item_id": "q1", "idempotency_key": "q1:r3", "status": "timeout"}],
+  "readback": {"complete": true, "posts": [{"id": "urn:li:share:1", "marker": "#mg-q1:r3"}]}
+}
+```
+
+```bash
+maggie tool maggie_social_share.py reconcile attempts.json
+```
+
+| Situation | Action |
+|---|---|
+| A readback post carries the item's key or marker | `adopt` it as the published post (timeout-after-success). |
+| An attempt reported a post ID that readback does not show | `verify_readback` before anything else. |
+| Last outcome `timeout`/`pending`/`unknown`, readback incomplete | `await_readback`; no retry. |
+| Same, readback complete and no match | `retry_same_key`. |
+| `failed_retryable` | `retry_same_key`. |
+| `failed_terminal` | `fail`. |
+| Two provider posts for one item, or retries that changed the key | invalid; `resolve_duplicate` (keep the first, delete extras). |
+
+Immediate and scheduled publishing share this one path, so a retry can never
+create a second post.
+
+## Marketing runs and schedule layers
+
+Social work that belongs to a wider campaign is recorded in a
+[marketing run](marketing-run.md) (`maggie-marketing-run-v1`). The slot queue
+above is the `content_calendar` layer; it is never the infrastructure timer
+that wakes the publish worker.

package/bundled-tools/clis/maggie_deployment.py

@@ -566,7 +566,7 @@ def preflight(
         rollback_passed = False
         if rollback_evidence.exists():
             try:
-                rollback_passed = validate_rollback_evidence(json.loads(rollback_evidence.read_text(encoding="utf-8"))) ["passed"]
+                rollback_passed = validate_rollback_evidence(json.loads(rollback_evidence.read_text(encoding="utf-8")), plan.get("retention", {}).get("keep"))["passed"]
             except (OSError, json.JSONDecodeError):
                 rollback_passed = False
         migration_manifest = project / ".maggie" / "migration-manifest.json"
@@ -579,7 +579,12 @@ def preflight(
         data_path = project / ".maggie" / "deployment" / "data-release.json"
         data_required = bool(migration.get("dataDependencies"))
         data_checkpoint = validate_data_checkpoint(data_path) if data_path.exists() else {"passed": not data_required, "declared": False, "errors": ["data-release.json is required for a data-dependent release"] if data_required else []}
-        retention_ok = bool(plan.get("retention", {}).get("keep") in (2, 3, 4, 5) and plan.get("retention", {}).get("prune") and plan.get("retention", {}).get("preserve"))
+        retention = plan.get("retention", {}) if isinstance(plan.get("retention"), dict) else {}
+        keep = retention.get("keep")
+        retention_ok = bool(keep in (1, 2, 3, 4, 5) and retention.get("prune") and retention.get("preserve"))
+        rollback_command = (plan.get("commands") or {}).get("rollback")
+        # Never advertise a rollback target that the retention policy deletes.
+        rollback_consistent = retention_ok and (bool(rollback_command) if keep >= 2 else not rollback_command and not any("<previous-release>" in str(item) for item in retention.get("preserve", [])))
         delegation = {"passed": True, "state": "not-required", "errors": []}
         delegation_path = delegation_evidence or project / ".maggie" / "deployment" / "deployer-delegation.json"
         if require_deployer:
@@ -591,14 +596,14 @@ def preflight(
             else:
                 delegation = validate_deployer_delegation(delegation_value, plan.get("release_root"), plan.get("service"))
                 delegation["path"] = str(delegation_path)
-        result["checks"].update({"node_runtime_declared": bool(package.get("engines", {}).get("node") or package.get("dependencies", {}).get("astro")), "start_command_or_runtime": "start" in scripts or "preview" in scripts, "stateless_or_migration_plan": True, "release_layout_declared": True, "rollback_command_declared": True, "release_retention_policy": retention_ok, "data_release_checkpoint": data_checkpoint["passed"], "remote_verification_pending": not delegation["passed"], "deployer_delegation": delegation["passed"], "release_plan_artifact": bool(plan_path and plan.get("release_layout") and plan.get("current_release")), "systemd_artifact": bool(systemd_text and "ExecStart=" in systemd_text and "EnvironmentFile=" in systemd_text and "NoNewPrivileges=true" in systemd_text), "nginx_artifact": bool(nginx_text and "proxy_pass" in nginx_text and "server_name" in nginx_text), "deployment_artifacts_secret_free": secret_free, "rollback_evidence": rollback_passed if environment == "production" else True})
+        result["checks"].update({"node_runtime_declared": bool(package.get("engines", {}).get("node") or package.get("dependencies", {}).get("astro")), "start_command_or_runtime": "start" in scripts or "preview" in scripts, "stateless_or_migration_plan": True, "release_layout_declared": True, "rollback_command_declared": True, "release_retention_policy": retention_ok, "rollback_target_retained": rollback_consistent, "data_release_checkpoint": data_checkpoint["passed"], "remote_verification_pending": not delegation["passed"], "deployer_delegation": delegation["passed"], "release_plan_artifact": bool(plan_path and plan.get("release_layout") and plan.get("current_release")), "systemd_artifact": bool(systemd_text and "ExecStart=" in systemd_text and "EnvironmentFile=" in systemd_text and "NoNewPrivileges=true" in systemd_text), "nginx_artifact": bool(nginx_text and "proxy_pass" in nginx_text and "server_name" in nginx_text), "deployment_artifacts_secret_free": secret_free, "rollback_evidence": rollback_passed if environment == "production" else True})
         result["delegation"] = delegation
         result["vps"] = {"runtime":"Node.js standalone","reverseProxy":"Nginx","processManager":"systemd","releaseLayout":"/var/www/<site>/releases/<release> + current symlink","dns":"Cloudflare DNS or registrar DNS; verify apex and www separately","remoteCommands":["npm ci","npm run build","systemctl restart <service>","systemctl is-active <service>","curl -fsS https://<domain>/robots.txt","curl -fsS https://<domain>/sitemap.xml"],"handoverFields":["host","sshUser","domain","service","release","previousRelease","nginxConfig","migrationVersion","verification","rollback"]}
         result["next_action"] = "review VPS host, SSH user, domain/DNS, systemd service, Nginx config, release path, migrations, and rollback owner before execute"
         runners = sorted(deployment_dir.rglob("release-runner.sh")) if deployment_dir.exists() else []
         result["release_runners"] = [release_runner_status(path) for path in runners[:25]]
         result["warnings"] = isolation_warnings + [f"generated release runner is stale or unmarked: {item['path']}" for item in result["release_runners"] if item["status"] == "stale"]
-        result["blocking_checks"] = ["package_manifest", "build_command", "env_example", "node_runtime_declared", "start_command_or_runtime", "stateless_or_migration_plan", "release_layout_declared", "rollback_command_declared", "release_retention_policy", "data_release_checkpoint", "release_plan_artifact", "systemd_artifact", "nginx_artifact", "deployment_artifacts_secret_free", "rollback_evidence"]
+        result["blocking_checks"] = ["package_manifest", "build_command", "env_example", "node_runtime_declared", "start_command_or_runtime", "stateless_or_migration_plan", "release_layout_declared", "rollback_command_declared", "release_retention_policy", "rollback_target_retained", "data_release_checkpoint", "release_plan_artifact", "systemd_artifact", "nginx_artifact", "deployment_artifacts_secret_free", "rollback_evidence"]
         if require_deployer:
             result["blocking_checks"].append("deployer_delegation")
     else:
@@ -608,7 +613,21 @@ def preflight(
     return result
 
 
-def vps_plan(domain: str, service: str, release_root: str, node_port: int | None, deployer_user: str = "maggie-deploy") -> dict:
+def retention_policy(root: str, current: str, keep: int) -> dict:
+    """One retention policy shared by the plan, runner, preflight, prune, and rollback evidence."""
+    if not isinstance(keep, int) or isinstance(keep, bool) or not 1 <= keep <= 5:
+        raise ValueError("keep must be between 1 and 5")
+    preserve = [current] + ([f"{root}/releases/<previous-release>"] if keep >= 2 else [])
+    return {
+        "keep": keep,
+        "preserve": preserve,
+        "prune": f"find {root}/releases -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -nr | tail -n +{keep + 1} | cut -d' ' -f2- | xargs -r rm -rf --",
+        "rollbackAvailable": keep >= 2,
+        "rollbackUnavailableReason": "" if keep >= 2 else "retention keeps only the active release; recover by redeploying the previous commit as a new release and restoring its data checkpoint",
+    }
+
+
+def vps_plan(domain: str, service: str, release_root: str, node_port: int | None, deployer_user: str = "maggie-deploy", keep_releases: int = 2) -> dict:
     """Create reviewable, secret-free VPS service and reverse-proxy artifacts."""
     if not re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?", domain):
         raise ValueError("domain must be a hostname without a scheme or path")
@@ -622,6 +641,7 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int | None
         raise ValueError("node port must be between 1024 and 65535")
     root = release_root.rstrip("/")
     current = f"{root}/current"
+    retention = retention_policy(root, current, keep_releases)
     privileged_commands = [
         f"/bin/systemctl restart {service}",
         f"/bin/systemctl is-active {service}",
@@ -649,7 +669,7 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int | None
             "allowed_domains_required": True,
         },
         "release_layout": f"{root}/releases/<immutable-release> plus current symlink",
-        "retention": {"keep": 2, "preserve": [current, f"{root}/releases/<previous-release>"], "prune": f"find {root}/releases -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -nr | tail -n +3 | cut -d' ' -f2- | xargs -r rm -rf --"},
+        "retention": retention,
         "staging_first": True,
         "secrets": "external environment file; no secrets in generated artifacts",
         "commands": {
@@ -657,7 +677,11 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int | None
             "switch": f"ln -sfn {root}/releases/<release> {current}",
             "restart": f"sudo -n /bin/systemctl restart {service}",
             "verify": f"sudo -n /bin/systemctl is-active {service} && curl -fsS https://{domain}/robots.txt && curl -fsS https://{domain}/sitemap.xml",
-            "rollback": f"ln -sfn {root}/releases/<previous-release> {current} && sudo -n /bin/systemctl restart {service}",
+            "rollback": f"ln -sfn {root}/releases/<previous-release> {current} && sudo -n /bin/systemctl restart {service}" if retention["rollbackAvailable"] else None,
+            # The database owner (e.g. postgres) often cannot traverse a release
+            # under a deploy user's home; stream the file instead of widening
+            # filesystem permissions.
+            "migrate_as_db_owner": f"sudo cat {root}/releases/<release>/<migration.sql> | sudo -u postgres psql -v ON_ERROR_STOP=1 --single-transaction -d <database> -f -",
             "data_rollback": "restore the matching data checkpoint before restarting the previous code release",
         },
         "files": {
@@ -692,8 +716,12 @@ def validate_data_checkpoint(path: Path) -> dict:
     return {"passed": not errors, "declared": True, "errors": errors}
 
 
-def validate_rollback_evidence(value: object) -> dict:
-    """Validate release rollback evidence, including the explicitly safe first release."""
+def validate_rollback_evidence(value: object, keep: int | None = None) -> dict:
+    """Validate release rollback evidence, including the explicitly safe first release.
+
+    With a one-release retention policy no previous release stays on disk, so
+    upgrade evidence must say the code rollback is unavailable and name the
+    recovery plan instead of advertising a removed target."""
     if not isinstance(value, dict):
         return {"passed": False, "errors": ["rollback evidence must be an object"]}
     errors = []
@@ -713,6 +741,13 @@ def validate_rollback_evidence(value: object) -> dict:
             errors.append("first release evidence must not claim a previous release")
         if not value.get("notApplicableReason"):
             errors.append("first release evidence needs notApplicableReason")
+    elif keep == 1:
+        if value.get("codeRollback") != "unavailable":
+            errors.append("retention keeps one release; rollback evidence must declare codeRollback: unavailable")
+        if not value.get("recoveryPlan"):
+            errors.append("retention keeps one release; rollback evidence needs a recoveryPlan (redeploy previous commit + data checkpoint)")
+    elif value.get("codeRollback") == "unavailable":
+        errors.append("codeRollback unavailable contradicts a retention policy that keeps a previous release")
     elif not value.get("previousRelease"):
         errors.append("upgrade rollback evidence requires previousRelease")
     return {"passed": not errors, "errors": errors}
@@ -740,15 +775,14 @@ def verify_infrastructure(units_dir: Path | None, service: str, timer: str | Non
 
 
 def retention_plan(release_root: str, current_link: str, keep: int) -> dict:
-    if keep < 2 or keep > 5:
-        raise ValueError("keep must be between 2 and 5")
+    policy = retention_policy(release_root.rstrip("/"), current_link, keep)
     root = Path(release_root).resolve()
     releases = sorted((path for path in root.iterdir() if path.is_dir() and not path.is_symlink()), key=lambda path: path.stat().st_mtime, reverse=True) if root.is_dir() else []
     current_target = Path(current_link).resolve() if Path(current_link).exists() else None
     preserved = {str(current_target)} if current_target else set()
     preserved.update(str(path) for path in releases[:keep])
     candidates = [str(path) for path in releases if str(path) not in preserved]
-    return {"schemaVersion": "maggie-retention-plan.v1", "releaseRoot": str(root), "currentLink": str(Path(current_link)), "keep": keep, "preserved": sorted(preserved), "candidates": candidates, "mutation": "not executed", "generatedAt": datetime.now(timezone.utc).isoformat()}
+    return {"schemaVersion": "maggie-retention-plan.v1", "releaseRoot": str(root), "currentLink": str(Path(current_link)), "keep": keep, "preserved": sorted(preserved), "candidates": candidates, "rollbackAvailable": policy["rollbackAvailable"], "rollbackUnavailableReason": policy["rollbackUnavailableReason"], "mutation": "not executed", "generatedAt": datetime.now(timezone.utc).isoformat()}
 
 
 def write_vps_plan(output_dir: Path, plan: dict) -> None:
@@ -836,6 +870,7 @@ def release_runner(plan: dict) -> str:
     service = plan["service"]
     domain = plan["domain"]
     current = plan["current_release"]
+    keep = retention_policy(root, current, plan.get("retention", {}).get("keep", 2))["keep"]
     generator = release_runner_generator()
     return f'''#!/usr/bin/env bash
 set -euo pipefail
@@ -899,13 +934,19 @@ wait_for_active
 wait_for_http "https://{domain}/robots.txt"
 wait_for_http "https://{domain}/sitemap.xml"
 
-# Keep current plus one rollback candidate, and prune only after health checks.
+# Retention policy: keep {keep} release(s), and prune only after health checks.
+KEEP_RELEASES={keep}
 mapfile -t RELEASES < <(find "$RELEASE_ROOT/releases" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -nr | cut -d' ' -f2-)
-for candidate in "${{RELEASES[@]:2}}"; do
-  [ "$candidate" = "$PREVIOUS" ] && continue
+for candidate in "${{RELEASES[@]:$KEEP_RELEASES}}"; do
+  [ "$KEEP_RELEASES" -ge 2 ] && [ "$candidate" = "$PREVIOUS" ] && continue
   [ "$candidate" = "$RELEASE" ] && continue
   rm -rf -- "$candidate"
 done
+if [ "$KEEP_RELEASES" -ge 2 ] && [ -n "$PREVIOUS" ]; then
+  echo "rollback target retained: $PREVIOUS"
+else
+  echo "rollback target: unavailable (retention keeps only the active release; redeploy the previous commit and restore its data checkpoint)"
+fi
 '''
 
 
@@ -946,7 +987,7 @@ def main() -> int:
     parser.add_argument("--check-runner", help="read-only check of a generated runner's Maggie version and template fingerprint")
     parser.add_argument("--retention-plan", action="store_true", help="create a read-only release prune candidate plan")
     parser.add_argument("--current-link", help="current symlink for --retention-plan")
-    parser.add_argument("--keep-releases", type=int, default=2)
+    parser.add_argument("--keep-releases", type=int, default=2, help="releases to keep (1-5); 1 means no on-disk rollback target, used by --vps-plan and --retention-plan")
     parser.add_argument("--verify-infra", action="store_true", help="verify declared or installed systemd service/timer")
     parser.add_argument("--units-dir", help="directory containing generated .service and .timer units")
     parser.add_argument("--timer", help="systemd timer unit name")
@@ -974,7 +1015,7 @@ def main() -> int:
         if args.vps_plan:
             if not args.domain:
                 parser.error("--domain is required with --vps-plan")
-            plan = vps_plan(args.domain, args.service, args.release_root, args.node_port, args.deployer_user)
+            plan = vps_plan(args.domain, args.service, args.release_root, args.node_port, args.deployer_user, args.keep_releases)
             if args.plan_dir:
                 write_vps_plan(Path(args.plan_dir).resolve(), plan)
             if args.runner_output:

package/bundled-tools/clis/maggie_deployment_auth_canary.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""Run declared, role-scoped authenticated API canaries without storing credentials or bodies.
+
+Public route canaries cannot see authenticated failures such as database
+permission errors, schema mismatches, or 403s on account and business APIs.
+This command executes a reviewed probe plan with credentials read only from
+environment variable *names*, and records status codes and contract checks
+only: never cookies, tokens, headers, response bodies, or personal data.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlparse
+
+PLAN_SCHEMA = "maggie-auth-canary-plan.v1"
+EVIDENCE_SCHEMA = "maggie-deployment-auth-canary.v1"
+MUTATING = {"POST", "PUT", "PATCH", "DELETE"}
+ALLOWED_METHODS = {"GET", "HEAD", "OPTIONS"} | MUTATING
+LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+ENV_NAME = re.compile(r"^[A-Z][A-Z0-9_]{1,63}$")
+SECRET_VALUE = re.compile(r"(?:Bearer\s+\S{8,}|eyJ[A-Za-z0-9_-]{10,}\.|sk[-_](?:live|test)[-_]|session=|sid=|[A-Fa-f0-9]{32,})")
+
+
+class PlanError(ValueError):
+    pass
+
+
+def classify(status: int | None) -> str:
+    if status is None:
+        return "network"
+    if status in (401, 403):
+        return "authorization"
+    if status >= 500:
+        return "server"
+    if status == 404:
+        return "route"
+    return "contract"
+
+
+def contains_literal_secret(value: object) -> bool:
+    if isinstance(value, dict):
+        return any(contains_literal_secret(item) for item in value.values())
+    if isinstance(value, list):
+        return any(contains_literal_secret(item) for item in value)
+    return isinstance(value, str) and bool(SECRET_VALUE.search(value))
+
+
+def validate_plan(plan: object) -> dict:
+    """Return the normalized plan or raise PlanError for an unsafe/invalid plan."""
+    if not isinstance(plan, dict) or plan.get("schemaVersion") != PLAN_SCHEMA:
+        raise PlanError(f"plan schemaVersion must be {PLAN_SCHEMA}")
+    if contains_literal_secret(plan):
+        raise PlanError("plan contains a literal credential; reference environment variable names only")
+    base = str(plan.get("baseUrl") or "")
+    parsed = urlparse(base)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname or parsed.query or parsed.fragment:
+        raise PlanError("baseUrl must be an http(s) origin without query or fragment")
+    if parsed.scheme == "http" and parsed.hostname not in LOCAL_HOSTS:
+        raise PlanError("baseUrl must use https outside localhost")
+    roles = plan.get("roles")
+    if not isinstance(roles, dict) or not roles:
+        raise PlanError("roles must declare at least one role")
+    for name, role in roles.items():
+        if not isinstance(role, dict):
+            raise PlanError(f"role {name} must be an object")
+        keys = [key for key in ("tokenEnv", "cookieEnv") if role.get(key)]
+        if len(keys) != 1:
+            raise PlanError(f"role {name} must declare exactly one of tokenEnv or cookieEnv")
+        if not ENV_NAME.fullmatch(str(role[keys[0]])):
+            raise PlanError(f"role {name} {keys[0]} must be an environment variable name")
+        unknown = set(role) - {"tokenEnv", "cookieEnv", "scheme", "description"}
+        if unknown:
+            raise PlanError(f"role {name} has unsupported fields: {', '.join(sorted(unknown))}")
+    probes = plan.get("probes")
+    if not isinstance(probes, list) or not probes:
+        raise PlanError("probes must be a non-empty list")
+    seen = set()
+    for probe in probes:
+        if not isinstance(probe, dict):
+            raise PlanError("each probe must be an object")
+        probe_id = str(probe.get("id") or "")
+        if not re.fullmatch(r"[a-z0-9][a-z0-9._-]{0,63}", probe_id) or probe_id in seen:
+            raise PlanError(f"probe id is missing, invalid, or duplicated: {probe_id or '<empty>'}")
+        seen.add(probe_id)
+        if probe.get("role") not in roles:
+            raise PlanError(f"probe {probe_id} references an undeclared role")
+        method = str(probe.get("method", "GET")).upper()
+        if method not in ALLOWED_METHODS:
+            raise PlanError(f"probe {probe_id} method is unsupported")
+        path = str(probe.get("path") or "")
+        if not path.startswith("/") or "//" in path or "?" in path or "#" in path:
+            raise PlanError(f"probe {probe_id} path must be an absolute path without query or fragment")
+        expect = probe.get("expectStatus", [200])
+        if not isinstance(expect, list) or not expect or not all(isinstance(code, int) and 100 <= code <= 599 for code in expect):
+            raise PlanError(f"probe {probe_id} expectStatus must be a list of HTTP status codes")
+        if method in MUTATING and probe.get("fixture") != "disposable":
+            raise PlanError(f"probe {probe_id} mutates state and must declare fixture: disposable")
+        keys = probe.get("expectJsonKeys", [])
+        if not isinstance(keys, list) or not all(isinstance(key, str) and key for key in keys):
+            raise PlanError(f"probe {probe_id} expectJsonKeys must be a list of key names")
+    return plan
+
+
+def credential_headers(role: dict) -> dict[str, str] | None:
+    if role.get("tokenEnv"):
+        value = os.environ.get(role["tokenEnv"], "")
+        return {"Authorization": f"{role.get('scheme', 'Bearer')} {value}"} if value else None
+    value = os.environ.get(role["cookieEnv"], "")
+    return {"Cookie": value} if value else None
+
+
+def run_probe(base: str, probe: dict, role: dict, timeout: float) -> dict:
+    method = str(probe.get("method", "GET")).upper()
+    record = {"id": probe["id"], "role": probe["role"], "method": method, "path": probe["path"], "expectStatus": probe.get("expectStatus", [200])}
+    if probe.get("fixture"):
+        record["fixture"] = probe["fixture"]
+    headers = credential_headers(role)
+    if headers is None:
+        record.update({"state": "inconclusive", "reason": "credential environment variable is not set"})
+        return record
+    headers["User-Agent"] = "maggie-deployment-auth-canary/1.0"
+    headers["Accept"] = "application/json"
+    data = None
+    if method in MUTATING:
+        headers["Content-Type"] = "application/json"
+        data = json.dumps(probe.get("body", {})).encode("utf-8")
+    request = urllib.request.Request(base.rstrip("/") + probe["path"], data=data, headers=headers, method=method)
+    status: int | None = None
+    body = b""
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            status = response.status
+            body = response.read(1_000_000)
+    except urllib.error.HTTPError as error:
+        status = error.code
+    except (urllib.error.URLError, OSError) as error:
+        record.update({"state": "failed", "status": None, "failureClass": "network", "reason": type(error).__name__})
+        return record
+    record["status"] = status
+    errors = []
+    if status not in record["expectStatus"]:
+        errors.append(f"status {status} not in {record['expectStatus']}")
+    keys = probe.get("expectJsonKeys", [])
+    if keys and not errors:
+        try:
+            payload = json.loads(body.decode("utf-8") or "null")
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            payload = None
+        if not isinstance(payload, dict):
+            errors.append("response is not a JSON object")
+        else:
+            missing = [key for key in keys if key not in payload]
+            record["contractKeys"] = {"expected": len(keys), "present": len(keys) - len(missing)}
+            if missing:
+                errors.append("missing contract keys: " + ", ".join(missing))
+    if errors:
+        record.update({"state": "failed", "failureClass": classify(status) if status not in record["expectStatus"] else "contract", "reason": "; ".join(errors)})
+    else:
+        record["state"] = "passed"
+    return record
+
+
+def auth_canary(plan: dict, allow_mutations: bool, timeout: float = 15.0) -> dict:
+    plan = validate_plan(plan)
+    results = []
+    for probe in plan["probes"]:
+        method = str(probe.get("method", "GET")).upper()
+        if method in MUTATING and not allow_mutations:
+            results.append({"id": probe["id"], "role": probe["role"], "method": method, "path": probe["path"], "fixture": probe.get("fixture"), "state": "blocked", "reason": "mutating probe requires --allow-mutations"})
+            continue
+        results.append(run_probe(plan["baseUrl"], probe, plan["roles"][probe["role"]], timeout))
+    states = {item["state"] for item in results}
+    status = "failed" if "failed" in states else "inconclusive" if states & {"inconclusive", "blocked"} else "passed"
+    return {
+        "schemaVersion": EVIDENCE_SCHEMA,
+        "generatedAt": datetime.now(timezone.utc).isoformat(),
+        "origin": urlparse(plan["baseUrl"]).netloc,
+        "status": status,
+        "passed": status == "passed",
+        "roles": sorted(plan["roles"]),
+        "probes": results,
+        "privacy": "status codes and contract-key counts only; no credentials, headers, bodies, or personal data",
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--plan", type=Path, required=True, help=f"{PLAN_SCHEMA} probe plan")
+    parser.add_argument("--allow-mutations", action="store_true", help="run probes that mutate disposable fixtures")
+    parser.add_argument("--timeout", type=float, default=15.0)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    try:
+        report = auth_canary(json.loads(args.plan.read_text(encoding="utf-8")), args.allow_mutations, args.timeout)
+    except (OSError, json.JSONDecodeError, PlanError) as error:
+        print(f"BLOCKED: maggie deployment auth-canary: {error}", file=sys.stderr)
+        return 2
+    encoded = json.dumps(report, indent=2, ensure_ascii=False) + "\n"
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(encoded, encoding="utf-8")
+    print(encoded, end="")
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())