Add reviewed opt-in private bucket save and restore

BUCKET_BUNDLE.md

@@ -0,0 +1,16 @@
+# Portable bucket bundle v1
+
+The browser supports explicit local-file export/import and optional direct save/restore to an existing private bucket. Local export downloads one JSON bundle. Restore validates the complete bundle before staging the network and any optional track or recipe in the current page. A restored receipt is kept in page memory and offered as a separate download. Restore never starts a run or writes browser storage.
+
+Bucket storage starts disconnected and never uploads automatically. The user enters a separate fine-grained token and explicitly connects, saves, refreshes, or restores. An expired/denied server response clears the page connection; the UI does not claim to know token expiry before a request. During those actions, the token and selected bundle pass through this app server to the user-owned private bucket; the app does not keep copies after the operation and exposes no bucket deletion, overwrite, creation, or visibility controls. Provider-side logs and retention are outside the app's deletion guarantee. The token is not included in the portable bundle. Existing run-retention controls remain independent. A separate local CLI guide is distributed with the candidate tooling for users who prefer local bucket transfer.
+
+## Envelope
+
+The only top-level fields are `schema`, `version`, and `artifacts`. The schema is `ald.portable-bundle`, version `1`. The required artifact slot is `selected_network`; optional fixed slots are `selected_track`, `selected_recipe`, and `run_receipt`. Unknown slots or fields are rejected.
+
+- A network stores its original `.evolution` bytes as base64 with byte length, SHA-256, format `evolution`, and kind `input` or `result`. The page validates decoded network content with its existing game-network validator and keeps the original bytes when staging it.
+- A track stores original `.track` bytes with length and SHA-256. A built-in track also records its catalog ID and display label; an uploaded track has no extra identifying metadata.
+- A recipe stores only version, A–J slot, name, and the existing validated training settings. Restore stages it into the form; saving it to the browser recipe library remains a separate user action.
+- A run receipt is an allowlisted summary only: build ID, backend, output hash, and whitelisted report fields for vehicle, counts, metrics, file hashes, and settings. It excludes history, paths, filenames, usernames, account data, job IDs/keys, and raw errors. Receipts that do not match the bundled network or included track are omitted on export or rejected on import.
+
+Caps are 4 MiB for network bytes, 1 MiB for track bytes, 32 KiB for recipe JSON, 128 KiB for receipt JSON, and 8 MiB for the complete bundle. Payload bytes and hashes must match exactly.

DATA_POLICY.md

@@ -3,7 +3,7 @@
 Operator: TiGa (seeker-cyber-maker). Candidate version: 2026-10-13. This package is not a receipt that a hosted deployment or publication has occurred.
 
 Files are processed only for the requested job, not collected for our own
-training, analytics or public examples. Inputs remain in the browser until Run.
+training, analytics or public examples. Inputs remain in the browser until Run or an explicit bucket save.
 The interface supports native CPU and, on a ZeroGPU deployment, an explicitly
 selected GPU job. CPU requests do not acquire a GPU lease.
 
@@ -61,8 +61,7 @@ acceptance limit; they are removed on return, error, or a fresh app load. Closin
 the tab loses them. HF handles password entry and authorization. The callback
 briefly carries a one-use authorization code and state in its URL; the app clears
 that URL before loading the OAuth helper. HF/proxy infrastructure handling is outside this
-application's deletion guarantee. The app does not request email, billing,
-repository access, or persistent bucket access.
+application's deletion guarantee. The OAuth flow does not request email, billing, repository access or bucket scopes. Optional bucket operations use the separate user-supplied credential described below.
 
 A non-GPU queue check forwards the visitor bearer credential to HF's fixed
 userinfo endpoint and returns only the username, PRO flag, and authentication
@@ -77,7 +76,7 @@ Results received by the browser and files saved locally are the user's to manage
 The browser retains its received result in page memory so Save received result
 again can retry a local save without another server retrieval. Discard browser
 result clears the app's reference; closing or refreshing the page loses it.
-No bucket support, network sandbox or provider-wide ZDR guarantee is offered.
+Optional bucket access is separate from HF sign-in. The user enters a fine-grained token for an existing private bucket; it remains in page memory and is sent with the requested bundle through this app server only for explicit Connect, Save, Refresh or Restore actions. Training and result deletion do not require a bucket connection.
 The service uses one result-owning process. HF framework and proxy behavior may have retention outside this app, so this is
 an application-level near-zero-retention design, not a provider-wide ZDR claim.
 
@@ -105,9 +104,7 @@ exported; they are not added to recipe storage.
 Network inspection, creation and editing take place in browser memory. Applying
 an edited network selects it as the next run's input; this alone sends nothing
 to the server. Exporting saves a new file, not the original source. No training
-history is attributed to freshly created or edited weights. A future bucket
-adapter is not implemented; it must be explicitly selected and must not silently
-turn public ephemeral storage into persistent storage.
+history is attributed to freshly created or edited weights. 
 
 
 ## Optional public Steam leaderboard check
@@ -117,3 +114,12 @@ The “After a completed lap” checkbox is off by default. With it off, or when
 The app reads the public Steam Community track index and matching board XML without a Steam login or publisher key. It resolves exact catalog reference labels against that live index; an absent or ambiguous mapping is unavailable. The app retains only a short-lived in-process cache of public board rank/time rows (up to 60 seconds) and the public index mapping (up to five minutes). Player names, Steam IDs and raw XML are discarded after parsing. The comparison request and result are not stored in the job result store or recipe library.
 
 The displayed value is an insertion-position estimate against the fetched raw global board, at millisecond precision. The board may contain entries for different vehicle types; the estimate is not vehicle-filtered, an official rank, a submitted score, or proof that replica timing matches the Steam game. The check runs in the background with an eight-second browser deadline. It cannot delay result availability or download; a timeout leaves the completed result intact. Steam's community page may change or become unavailable, in which case the app reports the check as unavailable.
+
+
+## Optional private bucket storage
+
+Bucket storage starts disconnected and never saves automatically. The user enters an existing private bucket ID and a separate fine-grained HF token, then explicitly selects Connect, Save, Refresh saved bundles or Restore. The token is held in this page's memory, sent in the Authorization header only to the app's fixed bucket routes, and cleared on disconnect, after the app receives an expired/denied response, or on page close. It is not the HF OAuth identity token and is not stored in localStorage, recipes, portable bundles, run receipts, URLs or application logs.
+
+For an explicit operation, the selected bundle and the bucket token pass through this app server to the user's private bucket. The storage bridge uses a short-lived worker and temporary cache, removes temporary files on completion or failure, and does not keep application copies after the operation. The saved object remains in the user's bucket under the app-owned prefix until the user manages it through another authorized tool; this app does not expose bucket deletion, overwriting, creation, or visibility changes. A failed save or restore leaves the page's received result and ordinary training controls available.
+
+These are application-level handling rules, not a guarantee about HF, network, proxy or hosting-provider logs and retention. They do not establish provider-wide zero data retention or secure physical erasure.

FRONTEND_SOURCE.json

@@ -1,10 +1,10 @@
 {
   "source": "Runner r14 single-engine browser UI; selected .track tile renderer added from simulator atlas",
   "source_sha256": "65d1e5f2c4e19b4951b828e82510005ab99a5270cf3dcb9f4eaa0fa1af8c40f8",
-  "output_sha256": "ef759a06305e94edb5ed0e49a587db8c39e3833ec2e02a1bec441c0287c385fd",
+  "output_sha256": "f6834f72d072bbfea28af7f1a686c5439be06c5c0848873ab6723745ea330051",
   "scope": "Frontend only; no engine, private data, track assets, API calls or storage copied",
-  "status": "Four vehicle UI and Type plumbing; native vehicle support pending runtime qualification; optional Steam comparison",
+  "status": "Local v1.1 hosted bucket candidate: explicit private bucket connect/save/list/restore plus local portable bundles; not deployed",
   "track_atlas_sha256": "d97c8900e3e5fb17734b5bd61d1f4f4b196d9be30af9848e2e273ae7e4079ae4",
-  "client_sha256": "f227469481a6a393f78636fde214473f54219c8af016050b35c6ef1af86eff34",
+  "client_sha256": "b47fc63b34fc68a7d3eb43317f574a16ebded99d296d7aea3d2f6f47a86ebc6b",
   "track_map_sha256": "ab5374aa49c7ccec90a787ee8c56cd71beb56b903bf2bbc322783e6f43c009f0"
 }

RELEASE_MANIFEST.json

@@ -4,15 +4,16 @@
     ".gitattributes": "c2ad16718fc51c888d32efc88c8f6e23ebe5fcf6f48e2954f896ba9770f24d72",
     "BETA_TESTING.md": "27e2492f9fe87cc04f52de2974b685b44041f7de9fa1155926b66c436f0bc613",
     "BINARY_PROVENANCE.json": "825d98f9ae91d88ee08143b11d1af9dd6f889c37f68dbea24163f718759dda3e",
+    "BUCKET_BUNDLE.md": "34dfebb783ca61b5b362ca9b2d936e19c87ea440f87558a8a5cfcb11ce1fdd30",
     "CUDA_REFERENCE.md": "f7453c3254d244f8b0de41fde5851cb025159f5cea4a4d1a5d8208a955550c6c",
-    "DATA_POLICY.md": "d5a4066759c823a34ad68a04cf7d9bfa2e39441b24b9466984d06fdb38eb566c",
+    "DATA_POLICY.md": "015ba656568b956f058359d141bd6adb9e8b7fd07bcad50c10c132455c7a4a19",
     "FEEDBACK.md": "f95b8f6afbf4a360976c0edca5d52f5b3a0b668c9a944d4947b840a7c53a122a",
-    "FRONTEND_SOURCE.json": "165fc6a32b0c132e73679ad7e69a1b30376ea0ac6a789283b22206e98d7212c9",
+    "FRONTEND_SOURCE.json": "1adfdbd649fb75b9ce80d58134c182b19e4b1877b40130efac0767a80947b6cd",
     "GODOT_LICENSE": "fb2b3bb82c60f1e76841ba2122eb902f8e39c151476fe21ce10c9a05d1045304",
     "IMPORTER_BUILD_RECEIPT.json": "4ba5c533cc617105478e4d85c83f456a7dfa68b1388049624619871ba9e42e9d",
     "LICENSE": "53d5851b6440feeae36f72a5f57fcab37858c48b7084765ece4b0c54b9a28ed8",
     "README.md": "b2e1d4a21c1ffd0d652a6e2448284b358f4e42dbfa8a0af6b1842d55c2f7c954",
-    "STORAGE_BOUNDARY.md": "9a1ffb5854230690dba3f0895f9a8e570716de47be2c553de13a6892dd740015",
+    "STORAGE_BOUNDARY.md": "e0df12d422a3e9bcc85468fcb6af202fd65551cba6f84d2c8f70f03e8e8cc55e",
     "TRACK_LIBRARY.md": "66b3656ed84f137d5b6116a0075731cd467818f555cca0969084aff67875319f",
     "UPSTREAM.json": "003235bbdf5e966561797fbe3d8bfc65c7c43d4a887fa54c3e6a96fb7c0c6938",
     "app.py": "162486abd6ac7c9281c8e75c15e33373e0fddba2baf6a799dfd54d333fd575d2",
@@ -25,6 +26,7 @@
     "bin/altd-sim": "0135ecc3d435a9d327be7a92e048cfb5c5291a02ef1e0dddd6ead1cc19b31166",
     "bin/extract_saved_track": "3a7733c45b4301a786fcbfe92660a1c484749272da5f608d62f34878bd4ff31a",
     "bin/libaltd_gpu.so": "3b1b88bccc06a21acc33ac4400af016d55a7e3d8727136a0c43b541f3c7887ca",
+    "bucket_storage.py": "6dedcdc6391be574805208e36c4f553e1c3e6faf41c68783c4c825e093dc9d94",
     "build_info.py": "93d331c0405cd10076a544f87761bb4a00f6556bbbdab8abc12e070c4661bd78",
     "builtin_tracks.py": "2ecc2b1d00fe15701b0271d71e1e68d2e7e59c596330879494055f9b2a99c242",
     "builtin_tracks/catalog.json": "65006e70a87a5a53e3738166b0895bc4db9f99767dd891d917b68029abb4e80a",
@@ -56,14 +58,15 @@
     "builtin_tracks/tracks/Replica R08 Demolition Derby.track": "6f11a9ffbcb477c9d19964566b1b612d2a94675605246e93e21f27bbbdb357ef",
     "builtin_tracks/tracks/Replica R09 Eau Noir.track": "3ec0a78478cca1a4f0d2d98ac81f40783928adf271b70f0c32d295a6da2cdaa9",
     "builtin_tracks/tracks/Replica The Champions Trial.track": "a3bfb76422affc774b44c739b0636d08acb901fa7615b9adcb52c069f79834e1",
-    "client.js": "f227469481a6a393f78636fde214473f54219c8af016050b35c6ef1af86eff34",
+    "client.js": "b47fc63b34fc68a7d3eb43317f574a16ebded99d296d7aea3d2f6f47a86ebc6b",
     "delivery.py": "07453999c3831a16e8b1fcc2b4ae5fb28beb7d3952a3fae8de65d16eb6f11e5b",
     "gpu_tickets.py": "b81aadb5ed42cec9212d44da7e7bbb7b413c5bd517383cac0b49ec9b4d659c92",
     "hf-auth.js": "d5cf17b961d1f2efa9d4648d33ba86a148eff0d542c74a121710c4df35c92936",
     "hf_identity.py": "6993d0238ada835606dbdc3275c17a3fe5a5cac5ad2156ab78230acf2d051eba",
-    "index.html": "ef759a06305e94edb5ed0e49a587db8c39e3833ec2e02a1bec441c0287c385fd",
-    "requirements.txt": "9b532747e51bd052e82090ece860d6dafe027407f4512dc74272c148ea104c22",
-    "server.py": "e00369e6840f0cab5350824e95fc0577ae59524d87ad0a34c32795708be17662",
+    "index.html": "f6834f72d072bbfea28af7f1a686c5439be06c5c0848873ab6723745ea330051",
+    "portable_bundle.py": "933915422905883e74081fa073a8024024d3d92662bf653f2174c212fa6cb5da",
+    "requirements.txt": "fc7e0703ad2289fd3926a36efbdce8c61f0edc00f7575a87e2b565e46588c5a4",
+    "server.py": "209936a7f21c290514b1dda68f3c9121366df907c9f7b9ffb08a17c9941ec29f",
     "steam_leaderboard.py": "d76397c39cae58f636ddf9a9be1a46ae3d77fefd6b7269feac73d34d97165481",
     "track-library.js": "351ec4c026b49420ce963f4310cb000d9e987fd28e6dac5ecd0176509340f6e6",
     "track-map.js": "ab5374aa49c7ccec90a787ee8c56cd71beb56b903bf2bbc322783e6f43c009f0",

STORAGE_BOUNDARY.md

@@ -16,7 +16,7 @@ same settings contract is used independently of the selected storage policy.
 | Received candidate / receipt | Browser page memory | Explicit discard, replacement, page reload/close; explicit export to disk |
 | Optional HF identity / token | Browser page memory, separate from job/recipe storage | Sign out, expiry, or page reload/close; no app auth cookie or server session database |
 | One-use HF PKCE verifier/nonce | Tab-local sessionStorage for the sign-in redirect only | Five-minute acceptance limit; removed on return/error/fresh app load or tab close; never stores access tokens or files |
-| User bucket | Not implemented | Must require an explicit opt-in adapter and separate retention policy |
+| User private bucket | Separate optional connection with explicit Save, Refresh and Restore | Only user-selected bundles are sent through the app server; the object remains in the user bucket until managed elsewhere; this app exposes no delete/overwrite/create/visibility operation |
 
 `recipes.cjs` has no host/network dependency. Its `createStore(storage)` receives
 only getItem/setItem/removeItem capabilities. A future bucket adapter must keep
@@ -25,8 +25,7 @@ bytes to recipe JSON. A public profile must not inherit private persistent
 artifact storage implicitly. Server cleanup must never clear the recipe library;
 clearing recipes must never delete a server job, bucket, or downloaded file.
 
-The current app has no bucket credentials, persistent HF identity storage, telemetry, or
-automatic recipe upload. Browser-local storage is site-specific and may be
+The app has no persistent HF identity or bucket credential storage, telemetry, or automatic recipe/bundle upload. Bucket operations are explicit and application-level cleanup does not make provider-wide retention claims. Browser-local storage is site-specific and may be
 blocked by browser privacy settings. A local runner and an HF iframe do not
 automatically share their library; explicit JSON export/import is the bridge.
 

bucket_storage.py

@@ -0,0 +1,279 @@
+"""Isolated, user-token-only Hugging Face Bucket operations for the API."""
+from __future__ import annotations
+
+import base64
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tempfile
+import uuid
+
+from portable_bundle import BundleError, MAX_BUNDLE, load_bundle
+
+HF_ENDPOINT = "https://huggingface.co"
+MAX_REQUEST = 2 * MAX_BUNDLE + 64 * 1024
+MAX_CHILD_INPUT = 4 * ((MAX_BUNDLE + 2) // 3) + 64 * 1024
+MAX_CHILD_OUTPUT = 128 * 1024
+CHILD_TIMEOUT_SECONDS = 55
+MAX_LIST_SCAN = 50
+APP_KEY = re.compile(r"^ald-exports/([0-9a-f]{32}|[0-9a-f]{64})/bundle\.json$")
+BUCKET_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}/[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$")
+
+
+class BucketStorageError(Exception):
+    """Safe error category; never carries upstream text or credentials."""
+
+    def __init__(self, category: str):
+        self.category = category
+        super().__init__(category)
+
+
+def valid_bucket_id(value: object) -> bool:
+    return isinstance(value, str) and bool(BUCKET_ID.fullmatch(value))
+
+
+def valid_bundle_key(value: object) -> bool:
+    return isinstance(value, str) and bool(APP_KEY.fullmatch(value))
+
+
+def _child_environment(cache_root: Path) -> dict[str, str]:
+    # Do not inherit host HF tokens, endpoints, cache locations, or login state.
+    env = {
+        "PATH": os.environ.get("PATH", "/usr/local/bin:/usr/bin:/bin"),
+        "LANG": "C.UTF-8",
+        "LC_ALL": "C.UTF-8",
+        "TMPDIR": str(cache_root),
+        "HF_HOME": str(cache_root / "hf"),
+        "HF_HUB_CACHE": str(cache_root / "hub-cache"),
+        "HF_XET_CACHE": str(cache_root / "xet-cache"),
+        "HF_XET_LOG_DEST": str(cache_root / "xet.log"),
+        "HF_HUB_DISABLE_TELEMETRY": "1",
+        "HF_HUB_DISABLE_IMPLICIT_TOKEN": "1",
+        "HF_HUB_DISABLE_PROGRESS_BARS": "1",
+        "PYTHONNOUSERSITE": "1",
+        "ALD_BUCKET_CHILD": "1",
+        "ALD_BUCKET_TEMP": str(cache_root),
+    }
+    return env
+
+
+def run_bucket_operation(operation: str, token: str, bucket_id: str, **args):
+    """Run one HF operation in an isolated process with a temporary Xet cache."""
+    if operation not in {"connect", "list", "save", "restore"}:
+        raise BucketStorageError("invalid_request")
+    if not isinstance(token, str) or not token or len(token) > 4096 or any(ch.isspace() or ord(ch) < 33 for ch in token):
+        raise BucketStorageError("unauthorized")
+    if not valid_bucket_id(bucket_id):
+        raise BucketStorageError("invalid_request")
+
+    try:
+        with tempfile.TemporaryDirectory(prefix="ald-bucket-") as temp_name:
+            temp = Path(temp_name)
+            payload = {"operation": operation, "token": token, "bucket_id": bucket_id, **args}
+            raw = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+            if len(raw) > MAX_CHILD_INPUT:
+                raise BucketStorageError("invalid_request")
+            proc = subprocess.run(
+                [sys.executable, str(Path(__file__).resolve()), "--child"],
+                input=raw,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                timeout=CHILD_TIMEOUT_SECONDS,
+                check=False,
+                shell=False,
+                env=_child_environment(temp),
+            )
+            if len(proc.stdout) > MAX_CHILD_OUTPUT:
+                raise BucketStorageError("storage_unavailable")
+            try:
+                result = json.loads(proc.stdout.decode("utf-8"))
+            except (UnicodeDecodeError, json.JSONDecodeError):
+                raise BucketStorageError("storage_unavailable") from None
+            if proc.returncode != 0 or not isinstance(result, dict):
+                category = result.get("error") if isinstance(result, dict) else None
+                if category in {"unauthorized", "forbidden", "not_found", "invalid_request", "storage_unavailable"}:
+                    raise BucketStorageError(category)
+                raise BucketStorageError("storage_unavailable")
+            if operation in {"save", "restore"}:
+                expected_name = "readback.json" if operation == "save" else "restore.json"
+                file_path = temp / expected_name
+                if not file_path.is_file() or file_path.is_symlink():
+                    raise BucketStorageError("storage_unavailable")
+                if file_path.stat().st_size > MAX_BUNDLE:
+                    raise BucketStorageError("invalid_request")
+                content = file_path.read_bytes()
+                if operation == "save":
+                    if hashlib.sha256(content).hexdigest() != result.get("sha256"):
+                        raise BucketStorageError("storage_unavailable")
+                    result["verified_bytes"] = content
+                else:
+                    try:
+                        load_bundle(content)
+                    except BundleError:
+                        raise BucketStorageError("invalid_bundle") from None
+                    result["bundle_bytes"] = content
+            return result
+    except subprocess.TimeoutExpired:
+        raise BucketStorageError("timeout") from None
+    except BucketStorageError:
+        raise
+    except Exception:
+        raise BucketStorageError("storage_unavailable") from None
+
+
+def _verify_bucket(api, token: str, bucket_id: str):
+    try:
+        user = api.whoami(token=token, cache=False)
+    except Exception:
+        raise BucketStorageError("unauthorized") from None
+    username = user.get("name") if isinstance(user, dict) else None
+    if not isinstance(username, str) or not username or bucket_id.split("/", 1)[0] != username:
+        raise BucketStorageError("forbidden")
+    try:
+        info = api.bucket_info(bucket_id, token=token)
+    except Exception:
+        # Inaccessible and nonexistent buckets deliberately share one response.
+        raise BucketStorageError("forbidden") from None
+    if getattr(info, "id", None) != bucket_id or getattr(info, "private", None) is not True:
+        raise BucketStorageError("forbidden")
+    return username
+
+
+def _download_descriptor(api, token: str, bucket_id: str, key: str, destination: Path):
+    from huggingface_hub._buckets import BucketFile
+
+    metadata = api.get_bucket_file_metadata(bucket_id, key, token=token)
+    size = getattr(metadata, "size", None)
+    xet_data = getattr(metadata, "xet_file_data", None)
+    xet_hash = getattr(xet_data, "file_hash", None)
+    if type(size) is not int or size < 0 or size > MAX_BUNDLE or not isinstance(xet_hash, str) or not xet_hash:
+        raise BucketStorageError("invalid_request")
+    descriptor = BucketFile(
+        type="file",
+        path=key,
+        size=size,
+        xetHash=xet_hash,
+        mtime=None,
+        uploadedAt=None,
+    )
+    try:
+        api.download_bucket_files(
+            bucket_id,
+            [(descriptor, destination)],
+            raise_on_missing_files=True,
+            token=token,
+        )
+    except Exception:
+        raise BucketStorageError("storage_unavailable") from None
+    if not destination.is_file() or destination.is_symlink() or destination.stat().st_size != size:
+        raise BucketStorageError("storage_unavailable")
+    return size, xet_hash
+
+
+def _perform_operation(request: dict, api, temp: Path) -> dict:
+    operation = request["operation"]
+    token = request["token"]
+    bucket_id = request["bucket_id"]
+    username = _verify_bucket(api, token, bucket_id)
+    if operation == "connect":
+        return {"status": "connected", "bucket_id": bucket_id, "username": username, "private": True}
+    if operation == "list":
+        items = []
+        truncated = False
+        for index, item in enumerate(api.list_bucket_tree(bucket_id, prefix="ald-exports", recursive=True, token=token)):
+            if index >= MAX_LIST_SCAN:
+                truncated = True
+                break
+            key = getattr(item, "path", None)
+            size = getattr(item, "size", None)
+            match = APP_KEY.fullmatch(key) if isinstance(key, str) else None
+            if match and type(size) is int and 0 <= size <= MAX_BUNDLE:
+                uploaded = getattr(item, "uploaded_at", None) or getattr(item, "mtime", None)
+                if isinstance(uploaded, datetime):
+                    if uploaded.tzinfo is None:
+                        uploaded = uploaded.replace(tzinfo=timezone.utc)
+                    date_label = uploaded.astimezone(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+                else:
+                    date_label = "Saved bundle"
+                items.append({"key": key, "bytes": size, "label": f"{date_label} · {match.group(1)[:8]}"})
+        return {"items": items, "truncated": truncated}
+    if operation == "save":
+        encoded = request.get("bundle_base64")
+        if not isinstance(encoded, str) or len(encoded) > 4 * ((MAX_BUNDLE + 2) // 3):
+            raise BucketStorageError("invalid_request")
+        try:
+            bundle = base64.b64decode(encoded, validate=True)
+            load_bundle(bundle)
+        except Exception:
+            raise BucketStorageError("invalid_bundle") from None
+        digest = hashlib.sha256(bundle).hexdigest()
+        prefix = f"ald-exports/{uuid.uuid4().hex}"
+        key = f"{prefix}/bundle.json"
+        source = temp / "upload"
+        source.mkdir(mode=0o700)
+        (source / "bundle.json").write_bytes(bundle)
+        try:
+            api.sync_bucket(
+                str(source), f"hf://buckets/{bucket_id}/{prefix}",
+                delete=False, ignore_existing=True, quiet=True, token=token,
+            )
+        except Exception:
+            raise BucketStorageError("storage_unavailable") from None
+        readback = temp / "readback.json"
+        size, _ = _download_descriptor(api, token, bucket_id, key, readback)
+        if size != len(bundle) or hashlib.sha256(readback.read_bytes()).hexdigest() != digest:
+            raise BucketStorageError("storage_unavailable")
+        return {"status": "saved_verified", "bucket_id": bucket_id, "key": key, "bytes": size, "sha256": digest}
+    key = request.get("key")
+    if not valid_bundle_key(key):
+        raise BucketStorageError("invalid_request")
+    restore = temp / "restore.json"
+    size, _ = _download_descriptor(api, token, bucket_id, key, restore)
+    try:
+        bundle = restore.read_bytes()
+        load_bundle(bundle)
+    except Exception:
+        raise BucketStorageError("invalid_bundle") from None
+    return {"status": "restored", "key": key, "bytes": size}
+
+
+def _child_main() -> int:
+    if os.environ.get("ALD_BUCKET_CHILD") != "1":
+        return 2
+    raw = sys.stdin.buffer.read(MAX_CHILD_INPUT + 1)
+    if len(raw) > MAX_CHILD_INPUT:
+        print(json.dumps({"error": "invalid_request"}))
+        return 2
+    try:
+        request = json.loads(raw.decode("utf-8"))
+        if not isinstance(request, dict) or request.get("operation") not in {"connect", "list", "save", "restore"}:
+            raise BucketStorageError("invalid_request")
+        operation = request["operation"]
+        token = request.get("token")
+        bucket_id = request.get("bucket_id")
+        if not isinstance(token, str) or not token or len(token) > 4096 or any(c.isspace() or ord(c) < 33 for c in token):
+            raise BucketStorageError("unauthorized")
+        if not valid_bucket_id(bucket_id):
+            raise BucketStorageError("invalid_request")
+        from huggingface_hub import HfApi
+
+        api = HfApi(endpoint=HF_ENDPOINT, token=False)
+        temp = Path(os.environ["ALD_BUCKET_TEMP"])
+        result = _perform_operation(request, api, temp)
+        print(json.dumps(result, separators=(",", ":")))
+        return 0
+    except BucketStorageError as exc:
+        print(json.dumps({"error": exc.category}, separators=(",", ":")))
+        return 1
+    except Exception:
+        print(json.dumps({"error": "storage_unavailable"}, separators=(",", ":")))
+        return 1
+
+
+if __name__ == "__main__" and len(sys.argv) == 2 and sys.argv[1] == "--child":
+    raise SystemExit(_child_main())

client.js

@@ -15,6 +15,16 @@ let runReceipt = null;
 let appBuild = null;
 let leaderboardRequest = null;
 let leaderboardGeneration = 0;
+let portableReceipt = null;
+let bundleRestoring = false;
+let bucketToken = null;
+let bucketId = null;
+let bucketUsername = null;
+let bucketItems = [];
+let bucketOperation = false;
+let bucketOperationId = 0;
+let bucketEpoch = 0;
+let bundleRestoreId = 0;
 // Display context affects quota guidance, never whether GPU can be selected.
 const hostedStandalone = location.hostname.endsWith('.hf.space') && window.self === window.top;
 const say = text => { $('status').textContent = text; };
@@ -28,24 +38,143 @@ const trackLibrary=window.TrackLibrary?.mount({document,fetch,digest:sha});
 window.TrackMap?.mount({document,fetch,picker:trackLibrary});
 const trackSource=()=>trackLibrary?trackLibrary.file():Promise.resolve($('track').files[0]);
 function buttons() {
-  trackLibrary?.setBusy(busy || !!job);
-  window.HFAuth?.setBusy(busy || !!job);
-  window.setTrainingBusy?.(busy || !!job);
-  window.setEditorBusy?.(busy || !!job);
-  $('run').disabled = busy || !!job || !capabilitiesReady || !networkSource() || ($('backend').value==='gpu'&&!gpuAvailable);
-  $('backend').disabled = busy || !!job || !capabilitiesReady;
+  const unavailable=busy||!!job||bundleRestoring||bucketOperation;
+  trackLibrary?.setBusy(unavailable);
+  window.HFAuth?.setBusy(unavailable);
+  window.setTrainingBusy?.(unavailable);
+  window.setEditorBusy?.(unavailable);
+  $('run').disabled = unavailable || !capabilitiesReady || !networkSource() || ($('backend').value==='gpu'&&!gpuAvailable);
+  $('backend').disabled = unavailable || !capabilitiesReady;
   $('download').disabled = busy || !job;
   $('erase').disabled = busy || !job;
   $('keepServer').disabled = busy || !!job;
   $('saveLocal').disabled = busy || !localResult;
   $('forgetLocal').disabled = busy || !localResult;
-  $('track').disabled=busy || !!job;
-  $('network').disabled=busy || !!job;
-  if($('batch_start'))$('batch_start').disabled=busy || !!job || !capabilitiesReady || ($('backend').value==='gpu'&&!gpuAvailable);
+  $('track').disabled=unavailable;
+  $('network').disabled=unavailable;
+  if($('batch_start'))$('batch_start').disabled=unavailable || !capabilitiesReady || ($('backend').value==='gpu'&&!gpuAvailable);
   if($('batch_stop'))$('batch_stop').disabled=!batchActive || batchStopRequested;
   if($('run_export'))$('run_export').disabled=busy || !runReceipt;
   if($('batch_export'))$('batch_export').disabled=busy || !batchReceipt;
+  if($('bundle_export'))$('bundle_export').disabled=unavailable;
+  if($('bundle_import'))$('bundle_import').disabled=unavailable;
+  if($('bucket_connect'))$('bucket_connect').disabled=unavailable||!!bucketToken;
+  if($('bucket_id'))$('bucket_id').disabled=unavailable||!!bucketToken;
+  if($('bucket_token'))$('bucket_token').disabled=unavailable||!!bucketToken;
+  if($('bucket_disconnect'))$('bucket_disconnect').disabled=unavailable||!bucketToken;
+  if($('bucket_save'))$('bucket_save').disabled=unavailable||!bucketToken||(!networkSource()&&!localResult);
+  if($('bucket_refresh'))$('bucket_refresh').disabled=unavailable||!bucketToken;
+  if($('bucket_restore'))$('bucket_restore').disabled=unavailable||!bucketToken||!$('bucket_items')?.value;
+  if($('bucket_items'))$('bucket_items').disabled=unavailable||!bucketToken;
 }
+function renderBucketConnection(){
+  const connected=!!bucketToken&&!!bucketId;
+  $('bucketConnectForm')?.toggleAttribute('hidden',connected);
+  $('bucketConnected')?.toggleAttribute('hidden',!connected);
+  if($('bucket_account'))$('bucket_account').textContent=connected?'Connected as '+bucketUsername+' · '+bucketId:'';
+  const select=$('bucket_items');
+  if(select){
+    const options=[];
+    if(!bucketItems.length){const option=document.createElement('option');option.value='';option.textContent='Refresh to list saved bundles';options.push(option);}
+    for(const item of bucketItems){const option=document.createElement('option');option.value=item.key;option.textContent=item.label+' · '+item.bytes+' bytes';options.push(option);}
+    select.replaceChildren(...options);
+    if(options.length)select.value='';
+  }
+  buttons();
+}
+const bucketKeyValid=key=>typeof key==='string'&&/^ald-exports\/(?:[0-9a-f]{32}|[0-9a-f]{64})\/bundle\.json$/.test(key);
+function bucketSnapshot(){return {token:bucketToken,id:bucketId,epoch:bucketEpoch};}
+function bucketSnapshotCurrent(snapshot){return !!snapshot?.token&&snapshot.epoch===bucketEpoch&&snapshot.token===bucketToken&&snapshot.id===bucketId;}
+function clearBucketConnection(snapshot=null){
+  if(snapshot&&!bucketSnapshotCurrent(snapshot))return false;
+  bucketEpoch++;
+  bucketOperationId++;bucketOperation=false;
+  bundleRestoreId++;bundleRestoring=false;
+  bucketToken=null;bucketId=null;bucketUsername=null;bucketItems=[];
+  if($('bucket_token'))$('bucket_token').value='';
+  if($('bucket_id'))$('bucket_id').value='';
+  if($('bucket_status'))$('bucket_status').textContent='Bucket connection cleared. Reconnect to continue.';
+  renderBucketConnection();
+  return true;
+}
+async function bucketRequest(endpoint,body,snapshot){
+  if(!['connect','list','save','restore'].includes(endpoint))throw Error('Unsupported bucket action');
+  const current=()=>endpoint==='connect'
+    ? snapshot.epoch===bucketEpoch&&bucketToken===null&&bucketId===null
+    : bucketSnapshotCurrent(snapshot);
+  const response=await fetch('/api/bucket/'+endpoint,{method:'POST',cache:'no-store',credentials:'omit',headers:{'Content-Type':'application/json','Authorization':'Bearer '+snapshot.token},body:JSON.stringify(body)});
+  if(!current())throw Error('Bucket connection changed; the old response was ignored');
+  if(response.status===401||response.status===403){if(endpoint!=='connect')clearBucketConnection(snapshot);throw Error('Bucket access expired or was denied. Reconnect to continue.');}
+  if(!response.ok)throw Error('Bucket action failed. Check the bucket settings and try again.');
+  return response;
+}
+function beginBucketOperation(){bucketOperation=true;const id=++bucketOperationId;buttons();return id;}
+function endBucketOperation(id){if(id!==bucketOperationId)return;bucketOperation=false;buttons();}
+if($('bucket_connect'))$('bucket_connect').onclick=async()=>{
+  const id=$('bucket_id').value.trim(),token=$('bucket_token').value.trim();
+  if(!id||!token){$('bucket_status').textContent='Enter the existing private bucket ID and its fine-grained token.';return;}
+  const epoch=++bucketEpoch,snapshot={token,id,epoch},operationId=beginBucketOperation();$('bucket_status').textContent='Checking private bucket access…';
+  try{
+    const response=await bucketRequest('connect',{bucket_id:id},snapshot),result=await response.json();
+    if(epoch!==bucketEpoch||bucketToken!==null||bucketId!==null)return;
+    if(result?.status!=='connected'||result.bucket_id!==id||result.private!==true||typeof result.username!=='string'||!result.username.trim()||result.username.length>200)throw Error('Private bucket access could not be verified.');
+    bucketToken=token;bucketId=id;bucketUsername=result.username;bucketItems=[];$('bucket_token').value='';
+    $('bucket_status').textContent='Connected. Refresh saved bundles or choose Save; nothing is uploaded automatically.';
+    renderBucketConnection();
+  }catch(error){if(epoch===bucketEpoch){bucketToken=null;bucketId=null;bucketUsername=null;bucketItems=[];$('bucket_token').value='';$('bucket_status').textContent=error.message||'Bucket connection failed.';renderBucketConnection();}}
+  finally{if(epoch===bucketEpoch)endBucketOperation(operationId);}
+};
+if($('bucket_disconnect'))$('bucket_disconnect').onclick=()=>{
+  if(bucketOperation)return;
+  clearBucketConnection();$('bucket_status').textContent='Disconnected. The bucket token was cleared from this page.';
+};
+if($('bucket_refresh'))$('bucket_refresh').onclick=async()=>{
+  if(!bucketToken)return;
+  const snapshot=bucketSnapshot(),operationId=beginBucketOperation();$('bucket_status').textContent='Refreshing this app’s saved bundle list…';
+  try{
+    const response=await bucketRequest('list',{bucket_id:snapshot.id},snapshot),result=await response.json();
+    if(!bucketSnapshotCurrent(snapshot))return;
+    if(!Array.isArray(result?.items)||result.items.length>50||typeof result.truncated!=='boolean')throw Error('The saved bundle list was not valid.');
+    const checked=result.items.map(item=>{
+      if(!bucketKeyValid(item?.key)||!Number.isSafeInteger(item.bytes)||item.bytes<1||item.bytes>window.PortableBundle.LIMITS.bundle||typeof item.label!=='string'||!item.label.trim()||item.label.length>120)throw Error('The saved bundle list was not valid.');
+      return {key:item.key,bytes:item.bytes,label:item.label};
+    });
+    bucketItems=checked;renderBucketConnection();
+    $('bucket_status').textContent=checked.length?checked.length+' saved bundle'+(checked.length===1?'':'s')+' available.'+(result.truncated?' Listing limited; additional bundles may not be shown.':''):'No bundles saved by this app were found.';
+  }catch(error){if(bucketSnapshotCurrent(snapshot))$('bucket_status').textContent=error.message||'Could not refresh saved bundles.';}
+  finally{endBucketOperation(operationId);}
+};
+if($('bucket_items'))$('bucket_items').addEventListener('change',buttons);
+if($('bucket_save'))$('bucket_save').onclick=async()=>{
+  if(!bucketToken)return;
+  const snapshot=bucketSnapshot(),operationId=beginBucketOperation();$('bucket_status').textContent='Building and verifying the selected bundle…';
+  try{
+    const {text}=await buildPortableBundle();
+    if(!bucketSnapshotCurrent(snapshot))throw Error('Bucket connection changed; no save was attempted.');
+    const bytes=new TextEncoder().encode(text),sha256=await window.PortableBundle.sha(bytes);
+    if(bytes.byteLength>window.PortableBundle.LIMITS.bundle)throw Error('Portable bundle exceeds 8 MiB');
+    const response=await bucketRequest('save',{bucket_id:snapshot.id,bundle:text},snapshot),result=await response.json();
+    if(!bucketSnapshotCurrent(snapshot))return;
+    if(result?.status!=='saved_verified'||result.bucket_id!==snapshot.id||!bucketKeyValid(result.key)||result.bytes!==bytes.byteLength||result.sha256!==sha256)throw Error('The app could not verify the saved bundle. Refresh the list before trying again; the remote save may have completed.');
+    $('bucket_status').textContent='Bundle saved and read back successfully. Refresh the list to see it. Your current result remains available for download.';
+  }catch(error){if(bucketSnapshotCurrent(snapshot))$('bucket_status').textContent=error.message||'Bundle save failed. Your current result remains available for download.';}
+  finally{endBucketOperation(operationId);}
+};
+if($('bucket_restore'))$('bucket_restore').onclick=async()=>{
+  if(!bucketToken)return;
+  const snapshot=bucketSnapshot(),key=$('bucket_items').value;
+  if(!bucketKeyValid(key)||!bucketItems.some(item=>item.key===key)){ $('bucket_status').textContent='Choose a listed saved bundle to restore.';return; }
+  const operationId=beginBucketOperation(),restoreId=++bundleRestoreId;bundleRestoring=true;buttons();$('bucket_status').textContent='Downloading and validating the selected bundle…';
+  try{
+    const response=await bucketRequest('restore',{bucket_id:snapshot.id,key},snapshot);
+    const text=await response.text();
+    if(!bucketSnapshotCurrent(snapshot))return;
+    if(new TextEncoder().encode(text).byteLength>window.PortableBundle.LIMITS.bundle)throw Error('Portable bundle exceeds 8 MiB');
+    await restorePortableText(text,{lockHeld:true,isCurrent:()=>bucketSnapshotCurrent(snapshot)});
+    if(bucketSnapshotCurrent(snapshot))$('bucket_status').textContent='Bundle restored in this page only. No run started and the existing result remains available.';
+  }catch(error){if(bucketSnapshotCurrent(snapshot))$('bucket_status').textContent='Bundle not restored: '+(error.message||'validation failed')+'. Existing selections and results were left unchanged.';}
+  finally{if(restoreId===bundleRestoreId)bundleRestoring=false;endBucketOperation(operationId);}
+};
 $('backend').addEventListener('change',buttons);
 $('leaderboard_opt_in')?.addEventListener('change',()=>{
   if(!$('leaderboard_opt_in').checked&&leaderboardRequest){
@@ -87,7 +216,7 @@ const headers = () => ({'X-Job-Key':job.key});
 const networkSource=()=>stagedNetwork || $('network').files[0];
 $('network').onchange=()=>{stagedNetwork=null;if($('networkChoice'))$('networkChoice').textContent='Uploaded file selected.';buttons();};
 window.TrainingClient={
-  isBusy:()=>busy||!!job,
+  isBusy:()=>busy||!!job||bundleRestoring,
   useNetwork(file){
     if(busy||job)throw Error('Finish or delete the current result before changing the network');
     stagedNetwork=file;$('network').value='';
@@ -367,3 +496,155 @@ if($('run_export'))$('run_export').onclick=()=>{
   const url=URL.createObjectURL(new Blob([JSON.stringify(runReceipt,null,2)],{type:'application/json'}));
   const a=document.createElement('a');a.href=url;a.download='ald-run-receipt.json';a.click();setTimeout(()=>URL.revokeObjectURL(url),1000);
 };
+const bundleMessage=text=>{if($('bundle_status'))$('bundle_status').textContent=text;};
+const bundleExact=(value,keys)=>{
+  if(!value||typeof value!=='object'||Array.isArray(value)||Object.keys(value).sort().join()!==[...keys].sort().join())throw Error('Unexpected receipt fields');
+};
+const bundleFinite=value=>typeof value==='number'&&Number.isFinite(value);
+function cleanRunReceipt(source){
+  if(!source||!source.report)return null;
+  const report=source.report,buildId=source.build_id??source.build?.build_id??report.build?.build_id;
+  if(source.version!==1||source.state!=='completed'||typeof buildId!=='string'||buildId.length>128||!['cpu','gpu'].includes(source.backend)||!/^[a-f0-9]{64}$/.test(source.output_sha256))return null;
+  const vehicleNames=['Formula','Rally','Snowmobile','Truck'];
+  if(!Number.isInteger(report.vehicle_type)||report.vehicle_type<0||report.vehicle_type>3||report.vehicle_name!==vehicleNames[report.vehicle_type]||
+     !Number.isInteger(report.generations_completed)||report.generations_completed<0||!Number.isInteger(report.generations_requested)||report.generations_requested<1||
+     !Number.isInteger(report.population)||report.population<1||!bundleFinite(report.elapsed_seconds)||report.elapsed_seconds<0||
+     !bundleFinite(report.best_score)||!bundleFinite(report.mean_score)||
+     !(report.best_lap_seconds===null||(bundleFinite(report.best_lap_seconds)&&report.best_lap_seconds>0))||
+     !(report.lapped_cars===null||(Number.isInteger(report.lapped_cars)&&report.lapped_cars>=0))||
+     !Number.isInteger(report.simulated_ticks)||report.simulated_ticks<0||!Number.isInteger(report.requested_ticks)||report.requested_ticks<1||report.candidate_validated!==true||
+     !['cpu','cuda'].includes(report.execution_backend)||report.execution_backend!==(source.backend==='gpu'?'cuda':'cpu'))return null;
+  try{
+    bundleExact(report.inputs,['track_sha256','network_sha256']);
+    if(!/^[a-f0-9]{64}$/.test(report.inputs.track_sha256)||!/^[a-f0-9]{64}$/.test(report.inputs.network_sha256))return null;
+    bundleExact(report.settings,Object.keys(window.RecipeLibrary.defaults));
+    const settings=window.RecipeLibrary.settings(report.settings);
+    return {version:1,kind:'run',state:'completed',build_id:buildId,backend:source.backend,output_sha256:source.output_sha256,
+      report:{vehicle_type:report.vehicle_type,vehicle_name:report.vehicle_name,generations_completed:report.generations_completed,
+        generations_requested:report.generations_requested,population:report.population,elapsed_seconds:report.elapsed_seconds,
+        best_score:report.best_score,mean_score:report.mean_score,best_lap_seconds:report.best_lap_seconds,lapped_cars:report.lapped_cars,
+        simulated_ticks:report.simulated_ticks,requested_ticks:report.requested_ticks,candidate_validated:true,
+        execution_backend:report.execution_backend,inputs:{track_sha256:report.inputs.track_sha256,network_sha256:report.inputs.network_sha256},settings}};
+  }catch{return null;}
+}
+function validatePortableReceipt(receipt,network,track){
+  bundleExact(receipt,['version','kind','state','build_id','backend','output_sha256','report']);
+  const report=receipt.report,reportKeys=['vehicle_type','vehicle_name','generations_completed','generations_requested','population','elapsed_seconds','best_score','mean_score','best_lap_seconds','lapped_cars','simulated_ticks','requested_ticks','candidate_validated','execution_backend','inputs','settings'];
+  bundleExact(report,reportKeys);
+  const clean=cleanRunReceipt(receipt);
+  if(receipt.version!==1||receipt.kind!=='run'||receipt.state!=='completed'||!clean)throw Error('Run receipt failed its allowlist or value checks');
+  const inputMatches=network.kind==='input'&&report.inputs.network_sha256===network.sha256;
+  const outputMatches=network.kind==='result'&&receipt.output_sha256===network.sha256;
+  if(!inputMatches&&!outputMatches)throw Error('Run receipt does not describe the bundled network');
+  if(track&&report.inputs.track_sha256!==track.sha256)throw Error('Run receipt does not describe the bundled track');
+  return clean;
+}
+async function validateNetworkBytes(bytes){
+  let decoded=bytes;
+  if(bytes[0]===31&&bytes[1]===139){
+    if(typeof DecompressionStream!=='function')throw Error('This browser cannot validate compressed .evolution files');
+    const reader=new Blob([bytes]).stream().pipeThrough(new DecompressionStream('gzip')).getReader(),chunks=[];let length=0;
+    try{while(true){const {value,done}=await reader.read();if(done)break;length+=value.byteLength;if(length>4*1024*1024)throw Error('Expanded network exceeds 4 MiB');chunks.push(value);}}
+    finally{reader.releaseLock();}
+    decoded=new Uint8Array(length);let at=0;for(const chunk of chunks){decoded.set(chunk,at);at+=chunk.byteLength;}
+  }
+  const value=JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(decoded));window.NetworkEditor.compatible(value);return value;
+}
+async function validateBundleTrack(track){
+  if(!track)return null;
+  const file=new File([track.bytes],'portable-track.track',{type:'application/octet-stream'});
+  const saved=await window.TrackMap.decode(file);
+  const response=await fetch('/assets/track-atlas.json',{cache:'no-store',credentials:'same-origin'});
+  if(!response.ok)throw Error('Track preview reference unavailable; bundle was not restored');
+  window.TrackMap.model(saved,await response.json());
+  return file;
+}
+async function buildPortableBundle(){
+  const api=window.PortableBundle;if(!api)throw Error('Portable bundle support is unavailable');
+  const inputNetwork=networkSource(),selected=inputNetwork||localResult;if(!selected)throw Error('Choose or download a network/result first');
+  const kind=inputNetwork?'input':'result',networkBytes=new Uint8Array(await selected.arrayBuffer());
+  await validateNetworkBytes(networkBytes);
+  const network=await api.artifact('evolution',kind,networkBytes),artifacts={selected_network:network};
+  let selectedTrack=null,trackInfo=null;
+  if($('bundle_track').checked){
+    const source=await trackSource();if(!source)throw Error('Choose a track before including it');
+    const bytes=new Uint8Array(await source.arrayBuffer());trackInfo=trackLibrary?.info()??{source:'upload'};
+    selectedTrack=await api.artifact('track','selected',bytes);
+    delete selectedTrack.kind;
+    if(trackInfo.source==='builtin')Object.assign(selectedTrack,{source:'builtin',track_id:trackInfo.id,display_name:trackInfo.display_name});
+    else selectedTrack.source='upload';
+    artifacts.selected_track=selectedTrack;
+  }
+  if($('bundle_recipe').checked){
+    const recipe=window.getPortableRecipe?.();if(recipe)artifacts.selected_recipe={version:1,slot:recipe.slot,name:recipe.name,settings:window.RecipeLibrary.settings(recipe.settings)};
+  }
+  let note='';
+  const receiptSource=runReceipt||portableReceipt;
+  if($('bundle_receipt').checked&&receiptSource){
+    const candidate=cleanRunReceipt(receiptSource);
+    const matches=candidate&&((kind==='result'&&candidate.output_sha256===network.sha256)||(kind==='input'&&candidate.report.inputs.network_sha256===network.sha256));
+    if(matches&&(!trackInfo||trackInfo.source!=='builtin'&&trackInfo.source!=='upload'||!selectedTrack||candidate.report.inputs.track_sha256===selectedTrack.sha256))artifacts.run_receipt=candidate;
+    else note=' The latest run receipt did not match this selected network/track and was omitted.';
+  }
+  const text=await api.pack(artifacts);
+  return {text,note};
+}
+async function exportPortableBundle(){
+  const {text,note}=await buildPortableBundle(),url=URL.createObjectURL(new Blob([text],{type:'application/json'}));
+  const a=document.createElement('a');a.href=url;a.download='ald-portable-bundle.json';a.click();setTimeout(()=>URL.revokeObjectURL(url),1000);
+  bundleMessage('Portable bundle downloaded to this device. It has not been uploaded or saved by the app.'+note);
+}
+if($('bundle_export'))$('bundle_export').onclick=async()=>{
+  try{await exportPortableBundle();}catch(error){bundleMessage('Bundle not exported: '+error.message);}
+};
+async function restorePortableText(text,{lockHeld=false,isCurrent=null}={}){
+  if((bundleRestoring&&!lockHeld)||busy||job)throw Error('Finish the active run before restoring a bundle');
+  if(new TextEncoder().encode(text).byteLength>window.PortableBundle.LIMITS.bundle)throw Error('Portable bundle exceeds 8 MiB');
+  const parsed=await window.PortableBundle.parse(text);
+  await validateNetworkBytes(parsed.network.bytes);
+  if(parsed.track){
+    if(parsed.track.metadata.source==='builtin'){
+      const entry=trackLibrary?.entries().find(e=>e.id===parsed.track.metadata.track_id);
+      if(!entry||entry.display_name!==parsed.track.metadata.display_name||entry.bytes!==parsed.track.bytes.byteLength||entry.sha256!==parsed.track.metadata.sha256)throw Error('Built-in track does not match this app’s catalog');
+    }
+    parsed.track.file=await validateBundleTrack(parsed.track);
+  }
+  if(parsed.recipe){bundleExact(parsed.recipe.settings,Object.keys(window.RecipeLibrary.defaults));parsed.recipe.settings=window.RecipeLibrary.settings(parsed.recipe.settings);}
+  if(parsed.receipt)parsed.receipt=validatePortableReceipt(parsed.receipt,parsed.network,parsed.track?.metadata);
+  let trackTransfer=null;
+  if(parsed.track?.metadata.source==='upload'){
+    if(typeof DataTransfer!=='function')throw Error('This browser cannot stage an uploaded track; no bundle data was applied');
+    trackTransfer=new DataTransfer();trackTransfer.items.add(parsed.track.file);
+  }
+  const networkFile=new File([parsed.network.bytes],'portable-network.evolution',{type:'application/octet-stream'});
+  // Recheck immediately before applying; a run or connection change during validation must not partially restore state.
+  if(busy||job)throw Error('A run started while the bundle was being validated; no bundle data was applied');
+  if(isCurrent&&!isCurrent())throw Error('Bucket connection changed while the bundle was being validated; no bundle data was applied');
+  if(parsed.track){
+    if(parsed.track.metadata.source==='builtin'){
+      const picker=$('trackPresetDrive');picker.value=parsed.track.metadata.track_id;picker.dispatchEvent(new Event('change',{bubbles:true}));
+    }else{
+      $('track').files=trackTransfer.files;$('track').dispatchEvent(new Event('change',{bubbles:true}));
+    }
+  }
+  window.TrainingClient.useNetwork(networkFile);
+  if(parsed.recipe)window.stagePortableRecipe(parsed.recipe);
+  portableReceipt=parsed.receipt||null;
+  $('bundle_receipt_download').disabled=!portableReceipt;
+  bundleMessage('Bundle restored in this page only. Network and optional track/recipe are staged; no run started and no browser storage or server was changed.'+(portableReceipt?' Sanitized receipt is available for separate download.':''));
+}
+if($('bundle_import'))$('bundle_import').onchange=async()=>{
+  const input=$('bundle_import'),file=input.files?.[0];if(!file)return;let restoreId=null;
+  try{
+    if(bundleRestoring||busy||job)throw Error('Finish the active run before restoring a bundle');
+    restoreId=++bundleRestoreId;bundleRestoring=true;buttons();
+    if(file.size>window.PortableBundle.LIMITS.bundle)throw Error('Portable bundle exceeds 8 MiB');
+    await restorePortableText(await file.text(),{lockHeld:true});
+  }catch(error){bundleMessage('Bundle not restored: '+error.message+'. The existing selections were left unchanged.');}
+  finally{if(restoreId===bundleRestoreId)bundleRestoring=false;buttons();input.value='';}
+};
+if($('bundle_receipt_download'))$('bundle_receipt_download').onclick=()=>{
+  if(!portableReceipt)return;
+  const url=URL.createObjectURL(new Blob([JSON.stringify(portableReceipt,null,2)],{type:'application/json'}));
+  const a=document.createElement('a');a.href=url;a.download='ald-run-receipt.json';a.click();setTimeout(()=>URL.revokeObjectURL(url),1000);
+};

index.html

@@ -46,6 +46,8 @@
 <h3 id="runState" role="status" aria-live="polite">READY — no run started</h3>
 <pre id="runSummary" style="white-space:pre-wrap;line-height:1.7" aria-live="polite"></pre><label class="keep-result"><input id="leaderboard_opt_in" type="checkbox"> After a completed lap, check its position against the public Steam leaderboard</label><p class="privacy-note">Optional, read-only check for supported built-in tracks. It sends the track ID and best lap to this app server; Steam receives only a public leaderboard read. No score is submitted. The result is an estimate, not an official rank.</p><p id="leaderboard_status" role="status" aria-live="polite"></p>
 <p><button id="run_export" disabled>Export run receipt</button></p><p class="hint">Receipts include build identity, settings, metrics and file hashes. Review them before sharing; they contain no network weights or job access keys.</p>
+<details id="portableBundle"><summary>Portable bucket bundle</summary><p>Build, export, or restore one validated bundle. Saving to an existing private bucket is optional and happens only when you explicitly connect, save, or restore. No automatic uploads occur.</p><label><input id="bundle_track" type="checkbox"> Include the selected track</label><label><input id="bundle_recipe" type="checkbox"> Include the recipe in the selected slot, if saved</label><label><input id="bundle_receipt" type="checkbox"> Include a sanitized receipt for the selected completed result</label><div class="toolbar"><button id="bundle_export" type="button">Export portable bundle</button><label for="bundle_import">Restore portable bundle (.json)<input id="bundle_import" type="file" accept=".json,application/json"></label><button id="bundle_receipt_download" type="button" disabled>Download staged receipt</button></div><p id="bundle_status" role="status" aria-live="polite">No bucket action has been requested.</p>
+<details id="bucketStorage"><summary>Connect to an existing private bucket</summary><p>Use a fine-grained Hugging Face token that can access your private bucket. The token is sent to this app only for explicit bucket actions, stays in page memory, and is cleared when you disconnect, the app receives an expired or denied response, or this page closes. The app cannot create buckets or change visibility. Normal runs do not require a bucket connection.</p><div id="bucketConnectForm"><label for="bucket_id">Private bucket ID</label><input id="bucket_id" type="text" autocomplete="off" placeholder="username/bucket-name"><label for="bucket_token">Fine-grained bucket token</label><input id="bucket_token" type="password" autocomplete="new-password" spellcheck="false"><button id="bucket_connect" type="button">Connect bucket</button></div><div id="bucketConnected" hidden><p id="bucket_account"></p><button id="bucket_disconnect" type="button">Disconnect bucket</button><div class="toolbar"><button id="bucket_save" type="button" disabled>Save selected bundle</button><button id="bucket_refresh" type="button">Refresh saved bundles</button></div><label for="bucket_items">Saved bundles from this app</label><select id="bucket_items" size="4"><option value="">Refresh to list saved bundles</option></select><button id="bucket_restore" type="button" disabled>Restore selected bundle</button></div><p id="bucket_status" role="status" aria-live="polite">Not connected. Bucket storage is optional.</p></details></details>
 <p id="deadline"></p><p id="status" role="status">Ready. Inputs remain on this device until you run the test.</p>
 <details><summary>Effective training settings</summary><pre id="effectiveSettings"></pre></details><details><summary>Generation results</summary><pre id="generationHistory"></pre></details><details><summary>Star challenges — not evaluated</summary><p>The current runner has star-challenge reporting. Its evaluator and required statistics have not been ported to HF; no star result is inferred from a completed test.</p></details></section></div>
 </div><section id="training" class="pane" hidden><div class="card"><h2>Training settings</h2><p class="hint">Choose the track on Drive & view. Choose the training settings and reward mix here, then start the run on Drive & view. Recipes and batch sequences are saved in this browser.</p><p><label for="trackPresetTraining">Training track</label><select id="trackPresetTraining" data-track-library disabled><option value="">Upload a custom track</option></select></p><p data-track-status role="status" class="hint">Loading built-in replica tracks…</p><div id="training_controls"><label for="training_ticks">Simulated ticks per generation</label><input id="training_ticks" type="number" min="1" max="18000" value="60"><small>60 ticks = one simulated second. Current preview limit: population × generations × ticks ≤ 4,000,000; execution timeout 25 seconds.</small>
@@ -294,6 +296,18 @@
   q('end_rate_group').hidden=false;
   applySettings(api.defaults);
   window.getTrainingSettings=executableSettings;
+  let stagedPortableRecipe=false;
+  window.getPortableRecipe=()=>{
+    if(stagedPortableRecipe)return {slot:q('recipe_slot').value,name:q('recipe_name').value,settings:currentSettings()};
+    const slot=q('recipe_slot').value;return read().recipes.find(r=>r.slot===slot)||null;
+  };
+  window.stagePortableRecipe=recipe=>{
+    if(!recipe||! /^[A-J]$/.test(recipe.slot)||typeof recipe.name!=='string'||!recipe.name.trim()||recipe.name.length>80)throw Error('Invalid selected recipe');
+    const settings=api.settings(recipe.settings);q('recipe_slot').value=recipe.slot;q('recipe_name').value=recipe.name.trim();
+    applySettings(settings);q('preset').value='custom';q('reward_preset').value='custom';stagedPortableRecipe=true;
+    message('Imported recipe staged in the training form. Save it explicitly to add it to this browser’s recipe library. No run started.');
+  };
+  q('recipe_slot').addEventListener('change',()=>{stagedPortableRecipe=false;});
   window.setTrainingBusy=busy=>{
     for(const id of editable)q(id).disabled=busy;
     for(const node of q('rewards').querySelectorAll('input,select,button'))node.disabled=busy;
@@ -449,7 +463,73 @@
   }
   return {create,mount};
 });
-</script><script src="/track-map.js"></script><script src="/client.js"></script><script src="/hf-auth.js"></script><script>'use strict';
+</script><script src="/track-map.js"></script><script>/* Explicit local portable-bundle format. This module never stores or sends data. */
+(function(root,factory){
+  if(typeof module==='object'&&module.exports)module.exports=factory();
+  else root.PortableBundle=factory();
+})(typeof window==='undefined'?globalThis:window,function(){
+  const SCHEMA='ald.portable-bundle',LIMITS={network:4*1024*1024,track:1024*1024,recipe:32768,receipt:131072,bundle:8*1024*1024};
+  const exact=(value,keys)=>{
+    if(!value||typeof value!=='object'||Array.isArray(value)||Object.keys(value).sort().join()!==[...keys].sort().join())throw Error('Unexpected portable bundle fields');
+  };
+  const utf8=value=>new TextEncoder().encode(value);
+  const sha=async bytes=>Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256',bytes)),b=>b.toString(16).padStart(2,'0')).join('');
+  function b64(bytes){let text='';for(let i=0;i<bytes.length;i+=8192)text+=String.fromCharCode(...bytes.subarray(i,i+8192));return btoa(text);}
+  function unb64(text){
+    if(typeof text!=='string'||text.length>Math.ceil(LIMITS.network/3)*4+8)throw Error('Invalid portable artifact encoding');
+    let binary;try{binary=atob(text);}catch{throw Error('Invalid portable artifact encoding');}
+    const bytes=Uint8Array.from(binary,c=>c.charCodeAt(0));if(b64(bytes)!==text)throw Error('Non-canonical portable artifact encoding');return bytes;
+  }
+  async function artifact(format,kind,bytes){
+    const data=bytes instanceof Uint8Array?bytes:new Uint8Array(bytes);
+    const limit=format==='evolution'?LIMITS.network:LIMITS.track;
+    if(!data.length||data.byteLength>limit)throw Error(format==='evolution'?'Network exceeds 4 MiB bundle limit':'Track exceeds 1 MiB bundle limit');
+    return {format,kind,bytes:data.byteLength,sha256:await sha(data),data_base64:b64(data)};
+  }
+  async function pack(artifacts){
+    if(!artifacts||!artifacts.selected_network)throw Error('A selected network is required');
+    const clean={schema:SCHEMA,version:1,artifacts};
+    const text=JSON.stringify(clean,null,2);if(utf8(text).byteLength>LIMITS.bundle)throw Error('Portable bundle exceeds 8 MiB');
+    return text;
+  }
+  async function parse(text){
+    if(typeof text!=='string'||utf8(text).byteLength>LIMITS.bundle)throw Error('Portable bundle exceeds 8 MiB');
+    let bundle;try{bundle=JSON.parse(text);}catch{throw Error('Portable bundle is not valid JSON');}
+    exact(bundle,['schema','version','artifacts']);if(bundle.schema!==SCHEMA||bundle.version!==1)throw Error('Unsupported portable bundle version');
+    const allowed=['selected_network','selected_track','selected_recipe','run_receipt'];
+    if(!bundle.artifacts||typeof bundle.artifacts!=='object'||Array.isArray(bundle.artifacts)||Object.keys(bundle.artifacts).some(k=>!allowed.includes(k))||!bundle.artifacts.selected_network)throw Error('Portable bundle needs a selected network and fixed artifact slots');
+    const a=bundle.artifacts,networkMeta=a.selected_network,networkBytes=await checkArtifact(networkMeta,'evolution',['format','kind','bytes','sha256','data_base64'],LIMITS.network);
+    if(!['input','result'].includes(networkMeta.kind))throw Error('Invalid selected network kind');
+    let track=null,recipe=null,receipt=null;
+    if(Object.hasOwn(a,'selected_track')){
+      const t=a.selected_track;if(!t||typeof t!=='object')throw Error('Invalid selected track');
+      const builtin=t.source==='builtin';
+      exact(t,builtin?['format','source','track_id','display_name','bytes','sha256','data_base64']:['format','source','bytes','sha256','data_base64']);
+      if(!['builtin','upload'].includes(t.source)||t.format!=='track')throw Error('Invalid selected track metadata');
+      if(builtin&&(!/^[a-z0-9-]{1,80}$/.test(t.track_id)||typeof t.display_name!=='string'||!t.display_name.length||t.display_name.length>100))throw Error('Invalid built-in track identity');
+      track={metadata:t,bytes:await checkArtifact(t,'track',Object.keys(t),LIMITS.track)};
+    }
+    if(Object.hasOwn(a,'selected_recipe')){
+      const r=a.selected_recipe;exact(r,['version','slot','name','settings']);
+      if(r.version!==1||! /^[A-J]$/.test(r.slot)||typeof r.name!=='string'||!r.name.trim()||r.name.length>80)throw Error('Invalid selected recipe');
+      const text=JSON.stringify(r);if(utf8(text).byteLength>LIMITS.recipe)throw Error('Recipe exceeds 32 KiB bundle limit');
+      recipe=r;
+    }
+    if(Object.hasOwn(a,'run_receipt')){
+      const r=a.run_receipt;exact(r,['version','kind','state','build_id','backend','output_sha256','report']);
+      if(r.version!==1||r.kind!=='run'||r.state!=='completed'||typeof r.build_id!=='string'||r.build_id.length>128||!['cpu','gpu'].includes(r.backend)||! /^[a-f0-9]{64}$/.test(r.output_sha256)||!r.report||typeof r.report!=='object'||Array.isArray(r.report))throw Error('Invalid sanitized run receipt');
+      const text=JSON.stringify(r);if(utf8(text).byteLength>LIMITS.receipt)throw Error('Run receipt exceeds 128 KiB bundle limit');
+      receipt=r;
+    }
+    return {bundle,network:{...networkMeta,bytes:networkBytes},track,recipe,receipt};
+  }
+  async function checkArtifact(value,format,keys,limit){
+    exact(value,keys);if(value.format!==format||!Number.isInteger(value.bytes)||value.bytes<1||value.bytes>limit||! /^[a-f0-9]{64}$/.test(value.sha256))throw Error('Invalid '+format+' artifact metadata');
+    const bytes=unb64(value.data_base64);if(bytes.byteLength!==value.bytes||await sha(bytes)!==value.sha256)throw Error(format+' bytes or SHA-256 do not match');
+    return bytes;
+  }
+  return {SCHEMA,LIMITS,sha,artifact,pack,parse};
+});</script><script src="/client.js"></script><script src="/hf-auth.js"></script><script>'use strict';
 // Navigation only. Editor and training/storage adapters are separate layers.
 document.querySelectorAll('[data-tab]').forEach(button=>button.addEventListener('click',()=>{
   document.querySelectorAll('.pane').forEach(pane=>pane.hidden=pane.id!==button.dataset.tab);

portable_bundle.py

@@ -0,0 +1,347 @@
+"""Strict versioned portable bundle validator shared by CLI and hosted API."""
+from __future__ import annotations
+import base64, binascii, gzip, hashlib, io, json, math, os, re, sys
+from pathlib import Path
+from typing import Any
+PACKAGE_ROOT = Path(__file__).resolve().parent
+sys.path.insert(0, str(PACKAGE_ROOT))
+from worker import network_input as _game_network_input, track_input as _game_track_input
+
+SCHEMA = "ald.portable-bundle"
+VERSION = 1
+MAX_NETWORK = 4 * 1024 * 1024
+MAX_TRACK = 1 * 1024 * 1024
+MAX_RECIPE = 32 * 1024
+MAX_RECEIPT = 128 * 1024
+MAX_BUNDLE = 8 * 1024 * 1024
+MAX_EXPANDED_JSON = 4 * 1024 * 1024
+HEX64 = re.compile(r"^[0-9a-f]{64}$")
+BUCKET_PATH = re.compile(r"^hf://buckets/([A-Za-z0-9][A-Za-z0-9_.-]{0,63})/([A-Za-z0-9][A-Za-z0-9_.-]{0,127})(?:/([A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)*))?$")
+SAFE_SEGMENT = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+
+RECIPE_KEYS = {
+    "population", "generations", "ticks", "mutation", "seed", "mutation_end",
+    "schedule", "selection", "parents", "elite", "crossover", "decay",
+    "adaptive_mutation", "control_hz", "workers", "collision", "idle", "rewards",
+}
+METRICS = {
+    "total_score", "total_speed", "total_abs_steering", "total_actual_distance",
+    "total_drifting_amount", "total_momentum_change_frequency", "total_throttle_change_frequency",
+    "total_braking_frequency", "total_distance_from_wall", "total_distance_from_center",
+    "network_novelty", "collision_count", "best_lap_performance", "total_racing_line_efficiency",
+}
+RECEIPT_KEYS = {"version", "kind", "state", "build_id", "backend", "output_sha256", "report"}
+REPORT_KEYS = {
+    "vehicle_type", "vehicle_name", "generations_completed", "generations_requested", "population",
+    "elapsed_seconds", "best_score", "mean_score", "best_lap_seconds", "lapped_cars",
+    "simulated_ticks", "requested_ticks", "candidate_validated", "execution_backend", "inputs", "settings",
+}
+INPUT_HASH_KEYS = {"track_sha256", "network_sha256"}
+
+
+class BundleError(ValueError):
+    pass
+
+
+def _no_constant(value: str) -> None:
+    raise BundleError(f"Non-finite JSON number is not allowed: {value}")
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in out:
+            raise BundleError(f"Duplicate JSON key: {key}")
+        out[key] = value
+    return out
+
+
+def _json_bytes(value: Any) -> bytes:
+    try:
+        return json.dumps(value, ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode("utf-8")
+    except (TypeError, ValueError, UnicodeEncodeError) as exc:
+        raise BundleError("Value is not valid portable JSON") from exc
+
+
+def _parse_json(raw: bytes, *, limit: int, label: str) -> Any:
+    if len(raw) > limit:
+        raise BundleError(f"{label} exceeds its byte limit")
+    try:
+        return json.loads(raw.decode("utf-8"), object_pairs_hook=_unique_object, parse_constant=_no_constant)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise BundleError(f"{label} must be valid UTF-8 JSON") from exc
+
+
+def _strict_keys(value: Any, allowed: set[str], required: set[str], label: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise BundleError(f"{label} must be an object")
+    keys = set(value)
+    if not required <= keys or keys - allowed:
+        raise BundleError(f"{label} has missing or unsupported fields")
+    return value
+
+
+def _is_int(value: Any, low: int, high: int) -> bool:
+    return type(value) is int and low <= value <= high
+
+
+def _is_number(value: Any, low: float, high: float) -> bool:
+    return type(value) in (int, float) and math.isfinite(value) and low <= value <= high
+
+
+def validate_settings(value: Any) -> dict[str, Any]:
+    settings = _strict_keys(value, RECIPE_KEYS, RECIPE_KEYS, "recipe settings")
+    bounds = {
+        "population": (1, 128), "generations": (1, 1000), "ticks": (1, 18000),
+        "seed": (0, 2147483647), "parents": (1, 128), "elite": (0, 128), "workers": (1, 4),
+    }
+    if any(not _is_int(settings[k], *bounds[k]) for k in bounds):
+        raise BundleError("recipe settings contain an out-of-range integer")
+    for key in ("mutation", "mutation_end"):
+        if not _is_number(settings[key], 0, 4.2):
+            raise BundleError("recipe mutation rates must be finite and between 0 and 4.2")
+    if settings["mutation"] <= 0 or (settings["schedule"] != "fixed" and settings["mutation_end"] <= 0):
+        raise BundleError("recipe mutation rates must be positive for the selected schedule")
+    if not _is_number(settings["decay"], 0, 1):
+        raise BundleError("recipe decay must be between 0 and 1")
+    choices = {
+        "schedule": {"fixed", "linear", "geometric"},
+        "selection": {"best", "tournament", "roulette"},
+        "crossover": {"none", "single_point", "uniform"},
+        "control_hz": {15, 30, 60},
+    }
+    if any(type(settings[k]) is not str for k in ("schedule", "selection", "crossover")):
+        raise BundleError("recipe contains an unsupported option")
+    if any(settings[k] not in values for k, values in choices.items()):
+        raise BundleError("recipe contains an unsupported option")
+    if type(settings["control_hz"]) is not int:
+        raise BundleError("recipe control_hz must be an integer")
+    if any(type(settings[k]) is not bool for k in ("adaptive_mutation", "collision", "idle")):
+        raise BundleError("recipe boolean setting is invalid")
+    if settings["parents"] > settings["population"] or settings["elite"] > settings["population"]:
+        raise BundleError("recipe parents or elite exceeds population")
+    rewards = settings["rewards"]
+    if not isinstance(rewards, list) or not 1 <= len(rewards) <= 5:
+        raise BundleError("recipe must have between one and five rewards")
+    seen: set[str] = set()
+    for reward in rewards:
+        _strict_keys(reward, {"metric", "type", "weight"}, {"metric", "type", "weight"}, "reward")
+        if (not isinstance(reward["metric"], str) or not isinstance(reward["type"], str)
+                or reward["metric"] not in METRICS or reward["type"] not in {"default", "average"}
+                or reward["metric"] in seen or not _is_int(reward["weight"], -100, 100)):
+            raise BundleError("recipe reward is invalid or duplicated")
+        seen.add(reward["metric"])
+    if all(reward["weight"] == 0 for reward in rewards):
+        raise BundleError("recipe rewards must include a nonzero weight")
+    return settings
+
+
+def validate_recipe(value: Any) -> dict[str, Any]:
+    recipe = _strict_keys(value, {"version", "slot", "name", "settings"}, {"version", "slot", "name", "settings"}, "selected recipe")
+    if recipe["version"] != 1 or type(recipe["version"]) is not int:
+        raise BundleError("selected recipe version is unsupported")
+    if not isinstance(recipe["slot"], str) or not re.fullmatch(r"[A-J]", recipe["slot"]):
+        raise BundleError("selected recipe slot must be A through J")
+    if not isinstance(recipe["name"], str) or not recipe["name"].strip() or len(recipe["name"]) > 80:
+        raise BundleError("selected recipe name must contain 1 to 80 characters")
+    validate_settings(recipe["settings"])
+    return recipe
+
+
+def validate_receipt(value: Any) -> dict[str, Any]:
+    receipt = _strict_keys(value, RECEIPT_KEYS, RECEIPT_KEYS, "run receipt")
+    if type(receipt["version"]) is not int or receipt["version"] != 1 or receipt["kind"] != "run":
+        raise BundleError("run receipt version or kind is unsupported")
+    if (not isinstance(receipt["state"], str) or receipt["state"] != "completed"
+            or not isinstance(receipt["backend"], str) or receipt["backend"] not in {"cpu", "gpu"}):
+        raise BundleError("run receipt state or backend is unsupported")
+    if not isinstance(receipt["build_id"], str) or len(receipt["build_id"]) > 128 or not re.fullmatch(r"[A-Za-z0-9._:+-]+", receipt["build_id"]):
+        raise BundleError("run receipt build id is invalid")
+    if not isinstance(receipt["output_sha256"], str) or not HEX64.fullmatch(receipt["output_sha256"]):
+        raise BundleError("run receipt output hash is invalid")
+    report = _strict_keys(receipt["report"], REPORT_KEYS, REPORT_KEYS, "run receipt report")
+    if not _is_int(report["vehicle_type"], 0, 3) or report["vehicle_name"] != ("Formula", "Rally", "Snowmobile", "Truck")[report["vehicle_type"]]:
+        raise BundleError("run receipt vehicle is invalid")
+    for key in ("generations_completed", "generations_requested", "population", "simulated_ticks", "requested_ticks"):
+        if not _is_int(report[key], 0, 4_000_000):
+            raise BundleError("run receipt count is invalid")
+    if report["generations_requested"] < 1 or report["population"] < 1 or report["requested_ticks"] < 1:
+        raise BundleError("run receipt requested counts and population must be positive")
+    for key in ("best_score", "mean_score"):
+        if not _is_number(report[key], -1e12, 1e12):
+            raise BundleError("run receipt metric is non-finite or out of range")
+    if not _is_number(report["elapsed_seconds"], 0, 1e12):
+        raise BundleError("run receipt elapsed time is invalid")
+    if report["best_lap_seconds"] is not None and not _is_number(report["best_lap_seconds"], 0, 1e12):
+        raise BundleError("run receipt best lap is invalid")
+    if report["best_lap_seconds"] == 0:
+        raise BundleError("run receipt best lap must be positive")
+    if report["lapped_cars"] is not None and not _is_int(report["lapped_cars"], 0, 128):
+        raise BundleError("run receipt lapped car count is invalid")
+    if (report["candidate_validated"] is not True or not isinstance(report["execution_backend"], str)
+            or report["execution_backend"] not in {"cpu", "cuda"}):
+        raise BundleError("run receipt execution status is invalid")
+    hashes = _strict_keys(report["inputs"], INPUT_HASH_KEYS, INPUT_HASH_KEYS, "run receipt inputs")
+    if any(not isinstance(hashes[k], str) or not HEX64.fullmatch(hashes[k]) for k in INPUT_HASH_KEYS):
+        raise BundleError("run receipt input hash is invalid")
+    validate_settings(report["settings"])
+    return receipt
+
+
+def _bounded_json_payload(raw: bytes, label: str) -> Any:
+    """Validate payload JSON with bounded gzip expansion, preserving bytes elsewhere."""
+    expanded = raw
+    if raw.startswith(b"\x1f\x8b"):
+        try:
+            with gzip.GzipFile(fileobj=io.BytesIO(raw)) as stream:
+                expanded = stream.read(MAX_EXPANDED_JSON + 1)
+        except (OSError, EOFError) as exc:
+            raise BundleError(f"{label} is not a valid gzip JSON payload") from exc
+        if len(expanded) > MAX_EXPANDED_JSON:
+            raise BundleError(f"{label} expands beyond 4 MiB")
+    value = _parse_json(expanded, limit=MAX_EXPANDED_JSON, label=label)
+    if not isinstance(value, dict):
+        raise BundleError(f"{label} must contain a JSON object")
+    return value
+
+
+def _validate_game_payload(raw: bytes, label: str, validator: Any) -> None:
+    try:
+        validator(raw)
+    except (ValueError, KeyError, TypeError, OSError, EOFError) as exc:
+        raise BundleError(f"{label} does not pass the current game input validator") from exc
+
+
+def _read_regular_file(path_value: str | Path, *, limit: int, label: str) -> bytes:
+    path = Path(path_value).expanduser()
+    if not path.is_absolute():
+        path = Path.cwd() / path
+    # Reject every symlinked component, not only a final symlink.
+    absolute = Path(os.path.abspath(path))
+    cursor = Path(absolute.anchor)
+    for part in absolute.parts[1:]:
+        cursor = cursor / part
+        if cursor.is_symlink():
+            raise BundleError(f"{label} path includes a symlink")
+    try:
+        st = absolute.stat()
+    except OSError as exc:
+        raise BundleError(f"{label} file cannot be read") from exc
+    if not absolute.is_file() or st.st_size > limit:
+        raise BundleError(f"{label} must be a regular file no larger than its limit")
+    try:
+        raw = absolute.read_bytes()
+    except OSError as exc:
+        raise BundleError(f"{label} file cannot be read") from exc
+    if len(raw) > limit:
+        raise BundleError(f"{label} exceeds its byte limit")
+    return raw
+
+
+def _slot(role: str, raw: bytes, *, fmt: str) -> dict[str, Any]:
+    return {
+        "format": fmt,
+        "bytes": len(raw),
+        "sha256": hashlib.sha256(raw).hexdigest(),
+        "data_base64": base64.b64encode(raw).decode("ascii"),
+    }
+
+
+def _decode_slot(value: Any, *, role: str, limit: int, fmt: str, allowed_extra: set[str], required_extra: set[str]) -> bytes:
+    allowed = {"format", "bytes", "sha256", "data_base64"} | allowed_extra
+    required = {"format", "bytes", "sha256", "data_base64"} | required_extra
+    item = _strict_keys(value, allowed, required, role)
+    if item["format"] != fmt:
+        raise BundleError(f"{role} format is unsupported")
+    if type(item["bytes"]) is not int or item["bytes"] < 0 or item["bytes"] > limit:
+        raise BundleError(f"{role} byte count exceeds its limit")
+    if not isinstance(item["sha256"], str) or not HEX64.fullmatch(item["sha256"]):
+        raise BundleError(f"{role} SHA-256 is invalid")
+    encoded = item["data_base64"]
+    if not isinstance(encoded, str) or len(encoded) > 4 * ((limit + 2) // 3):
+        raise BundleError(f"{role} base64 content exceeds its limit")
+    try:
+        raw = base64.b64decode(encoded, validate=True)
+    except (ValueError, binascii.Error) as exc:
+        raise BundleError(f"{role} base64 content is invalid") from exc
+    if len(raw) != item["bytes"] or len(raw) > limit:
+        raise BundleError(f"{role} byte count does not match its data")
+    if hashlib.sha256(raw).hexdigest() != item["sha256"]:
+        raise BundleError(f"{role} SHA-256 does not match its data")
+    return raw
+
+
+def load_bundle(raw: bytes, *, catalog_path: Path | None = None) -> tuple[dict[str, Any], dict[str, bytes]]:
+    value = _parse_json(raw, limit=MAX_BUNDLE, label="bundle")
+    bundle = _strict_keys(value, {"schema", "version", "artifacts"}, {"schema", "version", "artifacts"}, "bundle")
+    if bundle["schema"] != SCHEMA or type(bundle["version"]) is not int or bundle["version"] != VERSION:
+        raise BundleError("bundle schema or version is unsupported")
+    artifacts = bundle["artifacts"]
+    if not isinstance(artifacts, dict) or not {"selected_network"} <= set(artifacts) or set(artifacts) - {"selected_network", "selected_track", "selected_recipe", "run_receipt"}:
+        raise BundleError("bundle must contain a selected network and only supported optional artifacts")
+    files: dict[str, bytes] = {}
+    net = _strict_keys(artifacts["selected_network"], {"format", "kind", "bytes", "sha256", "data_base64"}, {"format", "kind", "bytes", "sha256", "data_base64"}, "selected network")
+    if not isinstance(net["kind"], str) or net["kind"] not in {"input", "result"}:
+        raise BundleError("selected network kind is unsupported")
+    files["selected_network.evolution"] = _decode_slot(net, role="selected network", limit=MAX_NETWORK, fmt="evolution", allowed_extra={"kind"}, required_extra={"kind"})
+    _bounded_json_payload(files["selected_network.evolution"], "selected network")
+    _validate_game_payload(files["selected_network.evolution"], "selected network", _game_network_input)
+
+    if "selected_track" in artifacts:
+        track = artifacts["selected_track"]
+        if not isinstance(track, dict):
+            raise BundleError("selected track must be an object")
+        source = track.get("source")
+        base_extra = {"source"}
+        req_extra = {"source"}
+        if source == "builtin":
+            base_extra |= {"track_id", "display_name"}
+            req_extra |= {"track_id", "display_name"}
+            if not isinstance(track.get("track_id"), str) or not isinstance(track.get("display_name"), str):
+                raise BundleError("built-in track metadata is invalid")
+            catalog_path = catalog_path or PACKAGE_ROOT / "builtin_tracks/catalog.json"
+            catalog = _parse_json(catalog_path.read_bytes(), limit=2 * 1024 * 1024, label="built-in track catalog")
+            matched = [x for x in catalog.get("tracks", []) if x.get("id") == track["track_id"] and x.get("display_name") == track["display_name"]]
+            if len(matched) != 1:
+                raise BundleError("built-in track id and label must match the local catalog")
+        elif source == "upload":
+            if "track_id" in track or "display_name" in track:
+                raise BundleError("uploaded track must not include built-in catalog metadata")
+        else:
+            raise BundleError("selected track source is unsupported")
+        files["selected_track.track"] = _decode_slot(track, role="selected track", limit=MAX_TRACK, fmt="track", allowed_extra=base_extra, required_extra=req_extra)
+        if source == "builtin" and (len(files["selected_track.track"]) != matched[0].get("bytes")
+                                    or hashlib.sha256(files["selected_track.track"]).hexdigest() != matched[0].get("sha256")):
+            raise BundleError("built-in track bytes do not match the selected catalog entry")
+        _bounded_json_payload(files["selected_track.track"], "selected track")
+        _validate_game_payload(files["selected_track.track"], "selected track", _game_track_input)
+
+    if "selected_recipe" in artifacts:
+        recipe = validate_recipe(artifacts["selected_recipe"])
+        recipe_bytes = _json_bytes(recipe)
+        if len(recipe_bytes) > MAX_RECIPE:
+            raise BundleError("selected recipe exceeds 32 KiB")
+        files["selected_recipe.json"] = recipe_bytes
+
+    if "run_receipt" in artifacts:
+        receipt = validate_receipt(artifacts["run_receipt"])
+        report = receipt["report"]
+        network_sha = net["sha256"]
+        if net["kind"] == "input":
+            network_matches = report["inputs"]["network_sha256"] == network_sha
+        else:
+            network_matches = receipt["output_sha256"] == network_sha
+        if not network_matches:
+            raise BundleError("run receipt does not describe the bundled network")
+        if "selected_track" in artifacts and report["inputs"]["track_sha256"] != artifacts["selected_track"]["sha256"]:
+            raise BundleError("run receipt does not describe the bundled track")
+        if receipt["backend"] == "cpu" and report["execution_backend"] != "cpu":
+            raise BundleError("run receipt backend does not match its execution backend")
+        if receipt["backend"] == "gpu" and report["execution_backend"] != "cuda":
+            raise BundleError("run receipt backend does not match its execution backend")
+        receipt_bytes = _json_bytes(receipt)
+        if len(receipt_bytes) > MAX_RECEIPT:
+            raise BundleError("run receipt exceeds 128 KiB")
+        files["run_receipt.json"] = receipt_bytes
+    return bundle, files
+

requirements.txt

@@ -1,3 +1,4 @@
 fastapi==0.141.1
 uvicorn==0.52.1
 spaces==0.51.3
+huggingface_hub==1.33.0

server.py

@@ -13,6 +13,8 @@ from training_config import validate_config
 from hf_identity import oauth_config
 from builtin_tracks import TrackLibrary
 from steam_leaderboard import compare_public_best_lap, milliseconds, SteamUnavailable
+from bucket_storage import BucketStorageError, MAX_REQUEST as BUCKET_MAX_REQUEST, run_bucket_operation, valid_bucket_id, valid_bundle_key
+from portable_bundle import BundleError, load_bundle, MAX_BUNDLE
 
 ROOT=Path(__file__).resolve().parent
 
@@ -20,7 +22,106 @@ def create_app(worker=run_reported,store=None,gpu_worker=None,track_library=None
     app=create_api(store)
     admission=threading.BoundedSemaphore(1)
     leaderboard_admission=threading.BoundedSemaphore(1)
+    bucket_admission=threading.BoundedSemaphore(1)
     library=track_library if track_library is not None else TrackLibrary(ROOT/'builtin_tracks')
+
+    @app.middleware('http')
+    async def bucket_no_store(request:Request, call_next):
+        response=await call_next(request)
+        if request.url.path.startswith('/api/bucket/'):
+            response.headers['Cache-Control']='no-store'
+        return response
+
+    def bucket_token(request:Request):
+        authorization=request.headers.get('authorization','')
+        if not authorization.startswith('Bearer '):
+            raise HTTPException(401,'Storage credential required')
+        token=authorization[7:]
+        if not token or len(token)>4096 or any(ch.isspace() or ord(ch)<33 for ch in token):
+            raise HTTPException(401,'Storage credential required')
+        return token
+
+    async def bucket_body(request:Request, token:str, *, limit:int, fields:set[str]):
+        chunks=bytearray()
+        try:
+            async for chunk in request.stream():
+                if len(chunks)+len(chunk)>limit: raise HTTPException(413,'Storage request too large')
+                chunks.extend(chunk)
+            def unique_object(pairs):
+                result={}
+                for key,value in pairs:
+                    if key in result: raise ValueError('duplicate key')
+                    result[key]=value
+                return result
+            value=json.loads(chunks.decode('utf-8'),object_pairs_hook=unique_object)
+            if not isinstance(value,dict) or set(value)!=fields:
+                raise ValueError('invalid body')
+        except HTTPException:
+            raise
+        except Exception:
+            raise HTTPException(400,'Invalid storage request') from None
+        finally:
+            chunks.clear()
+        if not valid_bucket_id(value.get('bucket_id')):
+            raise HTTPException(400,'Invalid storage request')
+        return value
+
+    def bucket_http_error(exc:BucketStorageError):
+        status={'unauthorized':401,'forbidden':403,'not_found':404,'invalid_request':400,
+                'invalid_bundle':400,'storage_unavailable':502,'timeout':504}.get(exc.category,502)
+        detail=('Storage credential is invalid' if status==401 else
+                'Storage access is unavailable' if status==403 else
+                'Invalid portable bundle' if exc.category=='invalid_bundle' else
+                'Storage operation timed out' if status==504 else
+                'Storage operation failed')
+        return HTTPException(status,detail)
+
+    async def bucket_operation(request:Request, operation:str, *, fields:set[str], limit:int=4096):
+        token=bucket_token(request)
+        if not bucket_admission.acquire(blocking=False):
+            raise HTTPException(429,'Storage operation busy')
+        try:
+            body=await bucket_body(request,token,limit=limit,fields=fields)
+            if operation=='save':
+                bundle=body.get('bundle')
+                if not isinstance(bundle,str) or len(bundle.encode('utf-8'))>MAX_BUNDLE:
+                    raise HTTPException(400,'Invalid portable bundle')
+                try: load_bundle(bundle.encode('utf-8'))
+                except BundleError: raise HTTPException(400,'Invalid portable bundle') from None
+                call_args={'bundle_base64':base64.b64encode(bundle.encode('utf-8')).decode('ascii')}
+            elif operation=='restore':
+                if not valid_bundle_key(body.get('key')):
+                    raise HTTPException(400,'Invalid storage request')
+                call_args={'key':body['key']}
+            else:
+                call_args={}
+            try:
+                result=await run_in_threadpool(run_bucket_operation,operation,token,body['bucket_id'],**call_args)
+            except BucketStorageError as exc:
+                raise bucket_http_error(exc) from None
+            return result
+        finally:
+            bucket_admission.release()
+
+    @app.post('/api/bucket/connect')
+    async def bucket_connect(request:Request):
+        result=await bucket_operation(request,'connect',fields={'bucket_id'})
+        return JSONResponse(result,headers={'Cache-Control':'no-store'})
+
+    @app.post('/api/bucket/list')
+    async def bucket_list(request:Request):
+        result=await bucket_operation(request,'list',fields={'bucket_id'})
+        return JSONResponse(result,headers={'Cache-Control':'no-store'})
+
+    @app.post('/api/bucket/save')
+    async def bucket_save(request:Request):
+        result=await bucket_operation(request,'save',fields={'bucket_id','bundle'},limit=BUCKET_MAX_REQUEST)
+        return JSONResponse({key:result[key] for key in ('status','bucket_id','key','bytes','sha256')},headers={'Cache-Control':'no-store'})
+
+    @app.post('/api/bucket/restore')
+    async def bucket_restore(request:Request):
+        result=await bucket_operation(request,'restore',fields={'bucket_id','key'})
+        return Response(result['bundle_bytes'],media_type='application/json',headers={'Cache-Control':'no-store','X-Content-Type-Options':'nosniff'})
     @app.get('/api/tracks')
     def track_catalog():
         return JSONResponse(library.catalog(),headers={'Cache-Control':'no-store'})