Publish curated MobilityOps source snapshot

scripts/check-contracts.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""Fail when checked-in API, event, MCP or n8n contracts drift from the code."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+from app.core.config import get_settings
+from app.main import app
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def fail(message: str, failures: list[str]) -> None:
+    failures.append(message)
+
+
+def check_openapi(failures: list[str]) -> None:
+    committed = yaml.safe_load((ROOT / "contracts/openapi.yaml").read_text(encoding="utf-8"))
+    generated = app.openapi()
+    if committed != generated:
+        fail(
+            "contracts/openapi.yaml differs from app.openapi(); regenerate it with "
+            "scripts/generate-openapi.py",
+            failures,
+        )
+
+
+def check_mcp(failures: list[str]) -> None:
+    contract = json.loads((ROOT / "contracts/mcp-tools.json").read_text(encoding="utf-8"))
+    contracted = {
+        (tool["endpoint"]["method"].upper(), tool["endpoint"]["path"])
+        for tool in contract["tools"]
+        if tool.get("read_only") is True and isinstance(tool.get("endpoint"), dict)
+    }
+    generated = app.openapi()
+    implemented = {
+        (method.upper(), path)
+        for path, operations in generated["paths"].items()
+        if path.startswith("/api/v1/integrations/mcp/")
+        for method in operations
+        if method.lower() in {"get", "post", "put", "patch", "delete"}
+    }
+    if len(contracted) != len(contract["tools"]):
+        fail("Every MCP tool must be read-only and declare its provider endpoint", failures)
+    if contracted != implemented:
+        fail(
+            f"MCP endpoint drift: contract={sorted(contracted)!r}, code={sorted(implemented)!r}",
+            failures,
+        )
+    if any(method not in {"GET", "POST"} for method, _path in contracted):
+        fail("MCP contract exposes an unsupported mutation method", failures)
+
+
+def check_event_schema(failures: list[str]) -> None:
+    schema = json.loads((ROOT / "contracts/events.schema.json").read_text(encoding="utf-8"))
+    expected_envelope = {
+        "event_id",
+        "event_type",
+        "occurred_at",
+        "correlation_id",
+        "aggregate",
+        "data",
+    }
+    expected_data = {
+        "vehicle_ref",
+        "inspection_ref",
+        "resulting_vehicle_status",
+        "attention_reasons",
+    }
+    if set(schema.get("required", [])) != expected_envelope:
+        fail("Event envelope required fields drifted", failures)
+    data_schema = schema.get("properties", {}).get("data", {})
+    if set(data_schema.get("required", [])) != expected_data:
+        fail("vehicle.returned.v1 data fields drifted", failures)
+    event_type = schema.get("properties", {}).get("event_type", {}).get("const")
+    if event_type != "vehicle.returned.v1":
+        fail("Unexpected event_type contract", failures)
+
+
+def check_workflows(failures: list[str]) -> None:
+    workflows_dir = ROOT / "n8n/workflows"
+    manifest = (workflows_dir / "MANIFEST.md").read_text(encoding="utf-8")
+    expected = {
+        "fleet-ops-vehicle-return.json": "mobilityops-return-processing",
+        "fleet-ops-data-quality-scan.json": "mobilityops-scheduled-quality-scan",
+        "fleet-ops-ragcore-procedure-sync.json": "6wbkc4d1AouGpmWT",
+        "fleet-ops-error-handler.json": "Xppn2rAEqUuyiCJF",
+        "fleet-ops-alert-receiver.json": "mobilityops-alert-receiver",
+    }
+    declared_hashes = set(re.findall(r"`([0-9a-f]{64})`", manifest))
+    for filename, workflow_id in expected.items():
+        path = workflows_dir / filename
+        raw = path.read_bytes()
+        digest = hashlib.sha256(raw).hexdigest()
+        if digest not in declared_hashes:
+            fail(f"{filename} checksum is missing or stale in MANIFEST.md", failures)
+        definition = json.loads(raw)
+        if definition.get("id") != workflow_id:
+            fail(f"{filename} has unexpected workflow id", failures)
+        serialized = raw.decode("utf-8")
+        if "http://fleetops.example.test" in serialized:
+            fail(f"{filename} contains a cleartext Fleet Ops callback", failures)
+        if filename == "fleet-ops-vehicle-return.json":
+            check_return_workflow_timing(definition, failures)
+        if filename == "fleet-ops-ragcore-procedure-sync.json":
+            check_ragcore_sync_workflow(definition, failures)
+
+
+def check_ragcore_sync_workflow(definition: dict, failures: list[str]) -> None:
+    """Keep the sync identity stable and reject HTTP error bodies as successful syncs."""
+    nodes_by_name = {node.get("name"): node for node in definition.get("nodes", [])}
+    upload = nodes_by_name.get("Upload to RAGcore", {})
+    credential = upload.get("credentials", {}).get("httpHeaderAuth", {})
+    if credential.get("name") != "RAGcore Sync Token":
+        fail("RAGcore upload must use the dedicated sync credential", failures)
+
+    parameters = upload.get("parameters", {}).get("bodyParameters", {}).get("parameters", [])
+    field_names = {
+        item.get("name") for item in parameters if isinstance(item, dict)
+    }
+    required = {"space_id", "source_id", "external_id", "locale", "file"}
+    if not required.issubset(field_names):
+        fail(
+            "RAGcore upload must preserve source_id, external_id and locale provenance",
+            failures,
+        )
+
+    summary_code = (
+        nodes_by_name.get("Summarize sync result", {}).get("parameters", {}).get("jsCode", "")
+    )
+    if not all(token in summary_code for token in ("job_id", "status_url", "failed += 1")):
+        fail("RAGcore sync summary must accept only a real AcceptedJob response", failures)
+
+
+def check_return_workflow_timing(definition: dict, failures: list[str]) -> None:
+    """Keep nested retry budgets inside the dispatcher's recoverable delivery lease."""
+    nodes_by_name = {node.get("name"): node for node in definition.get("nodes", [])}
+    validation_code = (
+        nodes_by_name.get("Validate and derive follow-up", {}).get("parameters", {}).get("jsCode", "")
+    )
+    if not all(field in validation_code for field in ("event_id", "correlation_id")):
+        fail(
+            "Vehicle-return workflow must preserve event_id and correlation_id for its callback",
+            failures,
+        )
+    required_nodes = ("Record follow-up", "Report workflow heartbeat")
+    workflow_budget_ms = 0
+    for name in required_nodes:
+        node = nodes_by_name.get(name)
+        if not isinstance(node, dict):
+            fail(f"Vehicle-return workflow is missing timing-critical node {name!r}", failures)
+            return
+        options = node.get("parameters", {}).get("options", {})
+        timeout_ms = options.get("timeout")
+        if node.get("retryOnFail") is not True:
+            fail(f"{name!r} must retain bounded retries", failures)
+            return
+        max_tries = node.get("maxTries")
+        wait_ms = node.get("waitBetweenTries", 0)
+        if not all(
+            isinstance(value, int) and not isinstance(value, bool) and value > 0
+            for value in (timeout_ms, max_tries)
+        ) or (
+            max_tries < 2
+            or not isinstance(wait_ms, int)
+            or isinstance(wait_ms, bool)
+            or wait_ms < 0
+        ):
+            fail(f"{name!r} has an invalid timeout/retry budget", failures)
+            return
+        workflow_budget_ms += timeout_ms * max_tries + wait_ms * (max_tries - 1)
+
+    settings = get_settings()
+    dispatcher_timeout_ms = settings.n8n_http_timeout_seconds * 1000
+    lease_ms = settings.n8n_delivery_lease_seconds * 1000
+    if not workflow_budget_ms < dispatcher_timeout_ms < lease_ms:
+        fail(
+            "Vehicle-return timing contract violated: complete callback/heartbeat retry "
+            f"budget {workflow_budget_ms}ms must be below dispatcher timeout "
+            f"{dispatcher_timeout_ms:g}ms, which must be below delivery lease {lease_ms:g}ms",
+            failures,
+        )
+
+
+def main() -> int:
+    failures: list[str] = []
+    check_openapi(failures)
+    check_mcp(failures)
+    check_event_schema(failures)
+    check_workflows(failures)
+    if failures:
+        for failure in failures:
+            print(f"ERROR: {failure}", file=sys.stderr)
+        return 1
+    print("OpenAPI, event, MCP and n8n contracts are synchronized.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/check-frontend-budget.mjs

@@ -0,0 +1,18 @@
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+const limits = { ".js": 400 * 1024, ".css": 180 * 1024 };
+const assets = join(import.meta.dirname, "..", "frontend", "dist", "assets");
+const failures = [];
+
+for (const name of await readdir(assets)) {
+  const extension = Object.keys(limits).find((candidate) => name.endsWith(candidate));
+  if (!extension) continue;
+  const bytes = (await stat(join(assets, name))).size;
+  console.log(`${name}: ${(bytes / 1024).toFixed(1)} KiB / ${limits[extension] / 1024} KiB`);
+  if (bytes > limits[extension]) failures.push(name);
+}
+
+if (failures.length) {
+  throw new Error(`Frontend asset budget exceeded: ${failures.join(", ")}`);
+}

scripts/check-source-budgets.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Prevent known large modules from growing while they are incrementally decomposed."""
+
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+LINE_LIMITS = {
+    "backend/app/services/data_quality.py": 900,
+    "backend/app/services/data_quality_duplicate_scan.py": 150,
+    "frontend/src/pages/DataQualityIssueDetail.tsx": 700,
+    "frontend/src/pages/data-quality/DuplicateCustomerPanel.tsx": 250,
+}
+BYTE_LIMITS = {
+    "frontend/src/styles.css": 78_000,
+    "frontend/src/styles-architecture-flow.css": 9_000,
+    "frontend/src/styles-data-quality.css": 8_000,
+}
+
+failures: list[str] = []
+for relative, limit in LINE_LIMITS.items():
+    count = len((ROOT / relative).read_text(encoding="utf-8").splitlines())
+    print(f"{relative}: {count}/{limit} lines")
+    if count > limit:
+        failures.append(relative)
+for relative, limit in BYTE_LIMITS.items():
+    count = (ROOT / relative).stat().st_size
+    print(f"{relative}: {count}/{limit} bytes")
+    if count > limit:
+        failures.append(relative)
+
+if failures:
+    raise SystemExit("Source budget exceeded; extract a focused module: " + ", ".join(failures))

scripts/generate-openapi.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+"""Regenerate the deterministic checked-in FastAPI OpenAPI contract."""
+
+from pathlib import Path
+
+import yaml
+
+from app.main import app
+
+target = Path(__file__).resolve().parents[1] / "contracts/openapi.yaml"
+target.write_text(
+    yaml.safe_dump(app.openapi(), sort_keys=False, allow_unicode=True),
+    encoding="utf-8",
+)
+print(target)

scripts/generate-release-provenance.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Generate inspectable release provenance for the images built by CI."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+from pathlib import Path
+
+IMAGES = {
+    "api": "mobilityops-api-release",
+    "web": "mobilityops-web-release",
+    "backup_tools": "mobilityops-backup-tools-release",
+}
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def main() -> None:
+    revision = os.environ.get("GITHUB_SHA", "")
+    if len(revision) != 40:
+        raise SystemExit("GITHUB_SHA must contain the full release revision")
+    images: dict[str, dict[str, str]] = {}
+    for name, image in IMAGES.items():
+        details = json.loads(
+            subprocess.check_output(["docker", "image", "inspect", image], text=True)
+        )[0]
+        labels = details.get("Config", {}).get("Labels", {}) or {}
+        if labels.get("org.opencontainers.image.revision") != revision:
+            raise SystemExit(f"revision label mismatch for {image}")
+        sbom = Path(f"mobilityops-{name.replace('_', '-')}-sbom.cdx.json")
+        images[name] = {
+            "reference": image,
+            "local_image_id": details["Id"],
+            "revision": labels["org.opencontainers.image.revision"],
+            "sbom": sbom.name,
+            "sbom_sha256": sha256(sbom),
+        }
+    provenance = {
+        "schema": "mobilityops.release-provenance.v1",
+        "revision": revision,
+        "repository": os.environ.get("GITHUB_REPOSITORY", "MobilityOps"),
+        "ref": os.environ.get("GITHUB_REF", ""),
+        "workflow_run": os.environ.get("GITHUB_RUN_ID", ""),
+        "images": images,
+    }
+    Path("release-provenance.json").write_text(
+        json.dumps(provenance, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+
+
+if __name__ == "__main__":
+    main()

scripts/run-isolated-tests.sh

@@ -0,0 +1,13 @@
+#!/bin/sh
+set -eu
+
+project="mobilityops-test"
+compose_files="-f compose.yaml -f compose.test.yaml"
+
+cleanup() {
+  docker compose -p "$project" $compose_files down -v --remove-orphans
+}
+
+trap cleanup EXIT INT TERM
+cleanup
+docker compose -p "$project" $compose_files run --build --rm api pytest "$@"

scripts/run-readonly-load-smoke.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Small dependency-free concurrency gate for the persisted read paths."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import time
+import urllib.error
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+PATHS = (
+    "/api/v1/dashboard",
+    "/api/v1/vehicles?page=1&page_size=25",
+    "/api/v1/bookings?page=1&page_size=25&sort=operational",
+    "/api/v1/data-quality/issues?status=open&page=1&page_size=25",
+    "/api/v1/audit?page=1&page_size=25",
+    "/api/v1/system/status",
+)
+
+
+def request(url: str, cookie: str, timeout: float) -> tuple[float, int]:
+    started = time.perf_counter()
+    try:
+        with urllib.request.urlopen(
+            urllib.request.Request(url, headers={"Cookie": cookie}), timeout=timeout
+        ) as response:
+            response.read()
+            status = response.status
+    except urllib.error.HTTPError as error:
+        status = error.code
+    return (time.perf_counter() - started) * 1000, status
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--base-url", default="http://localhost:1228")
+    parser.add_argument("--requests", type=int, default=240)
+    parser.add_argument("--concurrency", type=int, default=12)
+    parser.add_argument("--timeout", type=float, default=5.0)
+    parser.add_argument("--max-p95-ms", type=float, default=1500.0)
+    args = parser.parse_args()
+    if args.requests < 1 or args.concurrency < 1:
+        raise SystemExit("requests and concurrency must be positive")
+
+    login = urllib.request.Request(
+        f"{args.base_url.rstrip('/')}/api/v1/demo/login",
+        data=json.dumps({"role": "operations_manager"}).encode(),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(login, timeout=args.timeout) as response:
+        cookie = response.headers.get("Set-Cookie", "").split(";", 1)[0]
+    if not cookie:
+        raise SystemExit("demo login returned no session cookie")
+
+    base = args.base_url.rstrip("/")
+    work = [f"{base}{PATHS[index % len(PATHS)]}" for index in range(args.requests)]
+    results: list[tuple[float, int]] = []
+    with ThreadPoolExecutor(max_workers=args.concurrency) as executor:
+        futures = [executor.submit(request, url, cookie, args.timeout) for url in work]
+        results.extend(future.result() for future in as_completed(futures))
+
+    failures = [status for _, status in results if status != 200]
+    durations = sorted(duration for duration, _ in results)
+    p95 = durations[max(0, math.ceil(len(durations) * 0.95) - 1)]
+    print(
+        f"read-only load smoke: requests={len(results)} concurrency={args.concurrency} "
+        f"failures={len(failures)} p95_ms={p95:.1f} max_ms={durations[-1]:.1f}"
+    )
+    if failures:
+        raise SystemExit(f"read-only load smoke returned non-200 statuses: {sorted(set(failures))}")
+    if p95 > args.max_p95_ms:
+        raise SystemExit(f"p95 {p95:.1f} ms exceeds {args.max_p95_ms:.1f} ms")
+
+
+if __name__ == "__main__":
+    main()
+

scripts/scan-ci-image.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TARGET_IMAGE="${1:?usage: scan-ci-image.sh <image>}"
+TRIVY_IMAGE="aquasec/trivy@sha256:be1190afcb28352bfddc4ddeb71470835d16462af68d310f9f4bca710961a41e"
+SAFE_NAME="$(printf '%s' "$TARGET_IMAGE" | tr -cs 'A-Za-z0-9._-' '-')"
+ARCHIVE_RELATIVE="artifacts/.${SAFE_NAME}.tar"
+ARCHIVE="$ROOT/$ARCHIVE_RELATIVE"
+trap 'rm -f "$ARCHIVE"' EXIT
+
+mkdir -p "$ROOT/artifacts"
+docker image inspect "$TARGET_IMAGE" >/dev/null
+docker save --output "$ARCHIVE" "$TARGET_IMAGE"
+
+WORKSPACE_ARGS=(-v "$ROOT:/workspace:ro")
+CONTAINER_ARCHIVE="/workspace/$ARCHIVE_RELATIVE"
+if docker inspect "${HOSTNAME:-}" >/dev/null 2>&1; then
+  WORKSPACE_ARGS=(--volumes-from "$HOSTNAME")
+  CONTAINER_ARCHIVE="$ROOT/$ARCHIVE_RELATIVE"
+fi
+
+docker run --rm "${WORKSPACE_ARGS[@]}" "$TRIVY_IMAGE" image \
+  --input "$CONTAINER_ARCHIVE" \
+  --scanners vuln \
+  --severity HIGH,CRITICAL \
+  --ignore-unfixed \
+  --exit-code 1 \
+  --format table