@mriekki/project-forge 4.18.0 → 4.19.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.18.0",
+  "version": "4.19.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -21,7 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "31985f3e24a3832391cfe873fbb3eab27d0fa9d4",
+      "revision": "09b2ace0b75fcd51ca7175d480bd5671e8be9520",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/generated/ASSEMBLY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.18.0",
+  "version": "4.19.0",
   "components": {
     "core": {
       "revision": "4c74c1801b82d3aa438447d392024d32ca5697b0",
@@ -361,7 +361,7 @@
       ]
     },
     "deployment": {
-      "revision": "31985f3e24a3832391cfe873fbb3eab27d0fa9d4",
+      "revision": "09b2ace0b75fcd51ca7175d480bd5671e8be9520",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -597,12 +597,12 @@
         {
           "source": "src/project_forge_deployment/sqlite_adapter.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_adapter.py",
-          "sha256": "781219312cb81ffb901dff8b8d04d0cf0511b5d37e86f9ad9024a73cba04d3b9"
+          "sha256": "a5fe59886946ef90b664959f7030831c60f8157d30825887bb1d2eac8f891e8b"
         },
         {
           "source": "src/project_forge_deployment/sqlite_adapter_remote.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_adapter_remote.py",
-          "sha256": "d60239f9b75cf688531319284f0123488f4f0ae812ac9982ce611320d8754793"
+          "sha256": "e327a079cb2fb1bec744c77684811ee3a6f382523484b70b430c9cdd73f730f1"
         },
         {
           "source": "src/project_forge_deployment/sqlite_cli.py",

package/assets/generated/deployment/src/project_forge_deployment/sqlite_adapter.py

@@ -36,6 +36,8 @@ _RUN_AS_RE = re.compile(r"^[0-9]+(?::[0-9]+)?$")
 _DB_FILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
 _ENV_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
 _SOURCE_RE = re.compile(r"^/srv/[A-Za-z0-9._/+-]+$")
+_IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+_PUBLIC_LABEL_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
 
 
 def _slug(value: str, field: str) -> str:
@@ -141,8 +143,30 @@ def _b64(value: str) -> str:
     return base64.b64encode(value.encode()).decode("ascii")
 
 
+def _public_label_keys(keys: list[str] | tuple[str, ...]) -> tuple[str, ...]:
+    if not isinstance(keys, (list, tuple)) or not 1 <= len(keys) <= 16:
+        raise DeploymentKitError("Image preparation requires 1-16 explicitly public label keys.")
+    if any(not isinstance(key, str) or _PUBLIC_LABEL_RE.fullmatch(key) is None for key in keys):
+        raise DeploymentKitError("Image preparation label keys must be safe public metadata names.")
+    if len(set(keys)) != len(keys):
+        raise DeploymentKitError("Image preparation label keys must be unique.")
+    return tuple(keys)
+
+
+def _prepared_image_id(value: str) -> str:
+    if not isinstance(value, str) or _IMAGE_ID_RE.fullmatch(value) is None:
+        raise DeploymentKitError("Bound SQLite maintenance requires an exact sha256 Docker image ID.")
+    return value
+
+
 def build_remote_script(spec: dict[str, Any] | None = None) -> str:
     spec = spec or {}
+    prepared_id = spec.get("preparedImageId")
+    if prepared_id is not None:
+        _prepared_image_id(prepared_id)
+    keys = spec.get("publicLabelKeys", ())
+    if keys:
+        keys = _public_label_keys(keys)
     env = spec.get("maintenanceEnvironment", {})
     recovery_payload = json.dumps(spec.get("recoveryEvidence", {}), sort_keys=True, separators=(",", ":"))
     replacements = {
@@ -152,6 +176,8 @@ def build_remote_script(spec: dict[str, Any] | None = None) -> str:
         "__ENV_B64__": _b64(spec.get("environment", "")),
         "__APP_B64__": _b64(spec.get("appSlug", "")),
         "__IMAGE_B64__": _b64(spec.get("image", "")),
+        "__PREPARED_IMAGE_ID__": prepared_id or "",
+        "__PUBLIC_LABEL_KEYS_B64__": _b64("\n".join(keys) + "\n") if keys else "",
         "__RUN_AS_B64__": _b64(spec.get("runAs") or ""),
         "__DB_FILE_B64__": _b64(spec.get("databaseFile") or ""),
         "__SOURCE_DB_B64__": _b64(spec.get("sourceDatabase") or ""),
@@ -380,28 +406,28 @@ def assert_app_spec_matches_persistence(name: str, app_spec: dict[str, Any]) ->
         raise DeploymentKitError("Prepared SQLite persistence requires directory application persistence.")
 
 
-def render_locked_sqlite_operation_stage(
+def _render_locked_sqlite_stage(
     plan: dict[str, Any], *, inherited_lock_fd: int, authorization: str,
+    action: str, prepared_image_id: str | None = None,
+    public_label_keys: tuple[str, ...] = (),
 ) -> dict[str, str]:
-    """Render a Kit-validated SQLite stage for an existing privileged remote lock scope.
-
-    This returns a Bash *stage*, not an SSH command and not an authorization to
-    run it. The caller must have obtained an exclusive non-blocking flock on
-    this exact app/environment lock in the SAME remote root shell; the Kit
-    verifies that inherited open file description before touching storage.
-
-    The caller retains the descriptor across its full-backup/current-storage
-    comparison, Kit migration, optional Kit rollback-check, and its durable
-    application-specific receipt write. Do not execute this stage via a fresh
-    SSH/sudo connection: the inherited descriptor cannot cross that boundary.
-    """
     _validate_sqlite_plan(plan)
     if plan["action"] not in {"migrate", "rollback-check"} or plan["firstInstall"]:
         raise DeploymentKitError("Lock handoff is limited to existing-database migration and rollback-check.")
+    if action not in {"migrate", "rollback-check", "prepare-image"} or (
+        action != "prepare-image" and action != plan["action"]
+    ):
+        raise DeploymentKitError("Image preparation or SQLite operation action differs from the reviewed plan.")
     if type(inherited_lock_fd) is not int or not 3 <= inherited_lock_fd <= 256:
         raise DeploymentKitError("Inherited remote lock descriptor must be an integer between 3 and 256.")
     if authorization != authorization_phrase(plan):
         raise DeploymentKitError("Exact reviewed SQLite operation authorization phrase is required.")
+    if action == "prepare-image" and (prepared_image_id is not None or not public_label_keys):
+        raise DeploymentKitError("Image preparation requires explicitly selected public labels and no prior binding.")
+    if action != "prepare-image" and public_label_keys:
+        raise DeploymentKitError("Public label enumeration belongs only to image preparation.")
+    if prepared_image_id is not None:
+        _prepared_image_id(prepared_image_id)
 
     _require_ready_platform(plan["targetName"])
     current = sqlite_inventory(plan["targetName"])
@@ -409,15 +435,92 @@ def render_locked_sqlite_operation_stage(
         raise DeploymentKitError("SQLite state changed after the plan was reviewed; create and authorize a fresh plan.")
     profile = load_profile(plan["targetName"])
     evidence = verify_access(profile)
-    script = build_remote_script(plan["spec"])
+    spec = dict(plan["spec"])
+    if prepared_image_id is not None:
+        spec["preparedImageId"] = _prepared_image_id(prepared_image_id)
+    if public_label_keys:
+        spec["publicLabelKeys"] = public_label_keys
+    script = build_remote_script(spec)
     delimiter = "PROJECT_FORGE_SQLITE_STAGE_" + hashlib.sha256(script.encode()).hexdigest()[:24]
     if delimiter in script:
         raise DeploymentKitError("Unsafe SQLite script delimiter collision.")
-    args = [plan["action"], plan["expectedReservationSha256"] or "NONE", profile["user"], str(inherited_lock_fd)]
+    args = [action, plan["expectedReservationSha256"] or "NONE", profile["user"], str(inherited_lock_fd)]
     command = "bash -s -- " + " ".join(shlex.quote(arg) for arg in args)
     return {
         "targetName": plan["targetName"],
         "verifiedAddress": evidence["address"],
-        "action": plan["action"],
+        "action": action,
         "script": f"{command} <<'{delimiter}'\n{script.rstrip()}\n{delimiter}\n",
     }
+
+
+def render_locked_sqlite_operation_stage(
+    plan: dict[str, Any], *, inherited_lock_fd: int, authorization: str,
+    prepared_image_id: str | None = None,
+) -> dict[str, str]:
+    """Render a migration/check stage inside the same privileged lock-owning shell.
+
+    Opt-in prepared_image_id rechecks the remote digest-to-image-ID mapping and
+    runs all maintenance commands by that exact ID, without pulling again.
+    Without a binding, legacy pull-by-digest operation behavior remains.
+    The consumer must validate preparation label evidence before this stage.
+    """
+    return _render_locked_sqlite_stage(
+        plan, inherited_lock_fd=inherited_lock_fd, authorization=authorization,
+        action=plan.get("action"), prepared_image_id=prepared_image_id,
+    )
+
+
+def render_locked_sqlite_image_preparation_stage(
+    plan: dict[str, Any], *, inherited_lock_fd: int, authorization: str,
+    public_label_keys: list[str] | tuple[str, ...],
+) -> dict[str, str]:
+    """Render a lock-held remote pull/inspection stage, not a database operation.
+
+    Pulls through the protected deployment-account registry config and emits
+    selected public labels, the requested immutable digest and remote Docker ID.
+    This DOES mutate Docker cache, but does not stop the runtime/change SQLite.
+    """
+    return _render_locked_sqlite_stage(
+        plan, inherited_lock_fd=inherited_lock_fd, authorization=authorization,
+        action="prepare-image", public_label_keys=_public_label_keys(public_label_keys),
+    )
+
+
+def parse_locked_sqlite_image_evidence(
+    output: str, *, image: str, public_label_keys: list[str] | tuple[str, ...],
+) -> dict[str, Any]:
+    """Fail closed on incomplete, reordered, extra, or malformed image evidence."""
+    exact_image = _image(image)
+    keys = _public_label_keys(public_label_keys)
+    if not isinstance(output, str):
+        raise DeploymentKitError("Malformed image preparation evidence.")
+    rows = output.splitlines()
+    if len(rows) != len(keys) + 2 or rows[-1] != "IMAGE_PREPARED_END":
+        raise DeploymentKitError("Incomplete or malformed image preparation evidence.")
+    header = rows[0].split("\t")
+    if (len(header) != 3 or header[0] != "IMAGE_PREPARED" or header[1] != exact_image
+            or _IMAGE_ID_RE.fullmatch(header[2]) is None):
+        raise DeploymentKitError("Image preparation digest or Docker image ID differs from the reviewed image.")
+    labels: dict[str, str] = {}
+    for key, row in zip(keys, rows[1:-1]):
+        parts = row.split("\t")
+        if len(parts) != 3 or parts[0] != "LABEL" or parts[1] != key:
+            raise DeploymentKitError("Image preparation label evidence is malformed or reordered.")
+        try:
+            raw = base64.b64decode(parts[2], validate=True)
+            value = json.loads(raw.decode("utf-8"))
+        except (ValueError, UnicodeError) as error:
+            raise DeploymentKitError("Image preparation label evidence is not valid base64 UTF-8.") from error
+        if (not isinstance(value, str) or not value or len(value.encode("utf-8")) > 1024
+                or any(ord(ch) < 32 or ord(ch) == 127 for ch in value)):
+            raise DeploymentKitError("Image preparation label evidence contains missing/unsafe metadata.")
+        labels[key] = value
+    return {
+        "schemaVersion": 1,
+        "registryDigest": exact_image,
+        "remoteImageId": header[2],
+        "labels": labels,
+        "capabilityProved": "remote-pulled-digest-bound-image-id",
+        "remoteImageCacheWritten": True,
+    }

package/assets/generated/deployment/src/project_forge_deployment/sqlite_adapter_remote.py

@@ -15,6 +15,9 @@ OWNER_B64="__OWNER_B64__"
 ENV_B64="__ENV_B64__"
 APP_B64="__APP_B64__"
 IMAGE_B64="__IMAGE_B64__"
+PREPARED_IMAGE_ID="__PREPARED_IMAGE_ID__"
+PUBLIC_LABEL_KEYS_B64="__PUBLIC_LABEL_KEYS_B64__"
+EXECUTION_IMAGE=""
 RUN_AS_B64="__RUN_AS_B64__"
 DB_FILE_B64="__DB_FILE_B64__"
 SOURCE_DB_B64="__SOURCE_DB_B64__"
@@ -33,6 +36,8 @@ meta_value() {
 valid_slug() { [[ "$1" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]]; }
 valid_repo() { [[ "$1" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; }
 valid_image() { [[ "$1" =~ ^[A-Za-z0-9][A-Za-z0-9._/:+-]*@sha256:[0-9a-f]{64}$ ]]; }
+valid_image_id() { [[ "$1" =~ ^sha256:[0-9a-f]{64}$ ]]; }
+valid_label_key() { [[ "$1" =~ ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$ ]]; }
 valid_run_as() { [[ "$1" =~ ^[0-9]+(:[0-9]+)?$ ]]; }
 valid_db_file() { [[ "$1" =~ ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$ && "$1" != "." && "$1" != ".." ]]; }
 valid_env_key() { [[ "$1" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; }
@@ -130,6 +135,9 @@ decode_spec() {
     valid_slug "$ENVIRONMENT" || { echo "Invalid SQLite environment." >&2; exit 45; }
     valid_slug "$APP_SLUG" || { echo "Invalid SQLite app slug." >&2; exit 45; }
     valid_image "$IMAGE" || { echo "SQLite maintenance image is not an immutable digest reference." >&2; exit 45; }
+    [[ -z "$PREPARED_IMAGE_ID" ]] || valid_image_id "$PREPARED_IMAGE_ID" || {
+        echo "Bound SQLite Docker image ID is malformed." >&2; exit 45;
+    }
     valid_run_as "$RUN_AS" || { echo "Invalid SQLite runAs." >&2; exit 45; }
     valid_db_file "$DATABASE_FILE" || { echo "Invalid SQLite database file name." >&2; exit 45; }
     [[ "$RESERVATION_SHA" =~ ^[0-9a-f]{64}$ ]] || { echo "Invalid SQLite reservation fingerprint." >&2; exit 45; }
@@ -192,7 +200,7 @@ run_backup() {
     local source_dir="$1" backup_dir="$2" backup_name="$3"
     local -a args
     maintenance_args args
-    args+=(--mount "type=bind,src=$source_dir,dst=/data" --mount "type=bind,src=$backup_dir,dst=/backup" "$IMAGE" --backup --backup-path "/backup/$backup_name")
+    args+=(--mount "type=bind,src=$source_dir,dst=/data" --mount "type=bind,src=$backup_dir,dst=/backup" "$EXECUTION_IMAGE" --backup --backup-path "/backup/$backup_name")
     "${args[@]}"
 }
 
@@ -200,7 +208,7 @@ run_check() {
     local data_dir="$1"
     local -a args
     maintenance_args args
-    args+=(--mount "type=bind,src=$data_dir,dst=/data" "$IMAGE" --check-rollback-compatibility)
+    args+=(--mount "type=bind,src=$data_dir,dst=/data" "$EXECUTION_IMAGE" --check-rollback-compatibility)
     "${args[@]}"
 }
 
@@ -208,7 +216,7 @@ run_migrate() {
     local data_dir="$1"
     local -a args
     maintenance_args args
-    args+=(--mount "type=bind,src=$data_dir,dst=/data" "$IMAGE" --migrate)
+    args+=(--mount "type=bind,src=$data_dir,dst=/data" "$EXECUTION_IMAGE" --migrate)
     [[ "$FIRST_INSTALL" == true ]] && args+=(--first-install)
     "${args[@]}"
 }
@@ -266,7 +274,7 @@ acquire_operation_lock() {
     # Never convert an untrusted flag into permission to skip the lock.
     # Inherited lock sharing is limited to existing-reservation migration and
     # compatibility verification; other mutations retain their own lock.
-    [[ "$ACTION" == migrate || "$ACTION" == rollback-check ]] && [[ "$FIRST_INSTALL" == false ]] || {
+    [[ "$ACTION" == migrate || "$ACTION" == rollback-check || "$ACTION" == prepare-image ]] && [[ "$FIRST_INSTALL" == false ]] || {
         echo "An inherited lock is not supported for this SQLite action." >&2; exit 75;
     }
     [[ "$HELD_LOCK_FD" =~ ^[0-9]+$ ]] && (( 10#$HELD_LOCK_FD >= 3 && 10#$HELD_LOCK_FD <= 256 )) || {
@@ -287,6 +295,70 @@ acquire_operation_lock() {
     }
 }
 
+prepare_image() {
+    [[ "$ACTION" == prepare-image && -z "$PREPARED_IMAGE_ID" && -n "$PUBLIC_LABEL_KEYS_B64" ]] || {
+        echo "Image preparation requires a held lock and public label selection." >&2; exit 49;
+    }
+    # The deployment account's protected registry config was verified.
+    # Suppress Docker stderr, which may contain sensitive registry details.
+    docker pull "$IMAGE" >/dev/null 2>&1 || {
+        echo "Exact immutable SQLite image pull failed." >&2; exit 49;
+    }
+    local image_id label_key label_value encoded count=0 label_length
+    image_id="$(docker image inspect --format '{{.Id}}' "$IMAGE" 2>/dev/null)" || {
+        echo "Pulled SQLite image is not inspectable." >&2; exit 49;
+    }
+    valid_image_id "$image_id" || {
+        echo "Remote SQLite Docker image ID is malformed." >&2; exit 49;
+    }
+    printf 'IMAGE_PREPARED\t%s\t%s\n' "$IMAGE" "$image_id"
+    while IFS= read -r label_key; do
+        valid_label_key "$label_key" || {
+            echo "Requested public image label name is invalid." >&2; exit 49;
+        }
+        label_value="$(docker image inspect --format "{{json (index .Config.Labels \"$label_key\")}}" "$image_id" 2>/dev/null)" || {
+            echo "Requested public image label could not be read." >&2; exit 49;
+        }
+        [[ -n "$label_value" && "$label_value" != "null" && "$label_value" != '""' &&
+           "$label_value" != *$'\n'* && "$label_value" != *$'\r'* &&
+           "$label_value" != *$'\t'* ]] || {
+            echo "Requested public image label is missing or unsafe." >&2; exit 49;
+        }
+        label_length="$(printf '%s' "$label_value" | wc -c)"
+        (( label_length <= 4096 )) || {
+            echo "Requested public image label exceeds the evidence limit." >&2; exit 49;
+        }
+        encoded="$(printf '%s' "$label_value" | base64 -w0)"
+        printf 'LABEL\t%s\t%s\n' "$label_key" "$encoded"
+        count=$((count + 1))
+    done < <(printf '%s' "$PUBLIC_LABEL_KEYS_B64" | base64 --decode)
+    [[ "$count" -ge 1 && "$count" -le 16 ]] || {
+        echo "Public image label selection is invalid." >&2; exit 49;
+    }
+    printf 'IMAGE_PREPARED_END\n'
+}
+
+select_execution_image() {
+    if [[ -z "$PREPARED_IMAGE_ID" ]]; then
+        docker pull "$IMAGE" >/dev/null
+        EXECUTION_IMAGE="$IMAGE"
+        return 0
+    fi
+    [[ -n "$HELD_LOCK_FD" && "$FIRST_INSTALL" == false ]] &&
+        [[ "$ACTION" == migrate || "$ACTION" == rollback-check ]] || {
+        echo "Bound SQLite execution requires a supported inherited lock." >&2; exit 49;
+    }
+    local resolved
+    resolved="$(docker image inspect --format '{{.Id}}' "$IMAGE" 2>/dev/null)" || {
+        echo "Prepared digest reference is no longer inspectable." >&2; exit 49;
+    }
+    [[ "$resolved" == "$PREPARED_IMAGE_ID" ]] &&
+        [[ "$(docker image inspect --format '{{.Id}}' "$PREPARED_IMAGE_ID" 2>/dev/null)" == "$PREPARED_IMAGE_ID" ]] || {
+        echo "Prepared digest-to-image-ID binding changed; SQLite execution is blocked." >&2; exit 49;
+    }
+    EXECUTION_IMAGE="$PREPARED_IMAGE_ID"
+}
+
 operate() {
     decode_spec
     configure_registry_auth
@@ -296,6 +368,16 @@ operate() {
     local db="$DATA/$DATABASE_FILE" stamp backup_name source_real source_parent
     managed_runtime_info "$ROOT"
 
+    if [[ "$ACTION" == prepare-image ]]; then
+        assert_marker "$MARKER" "$EXPECTED_RESERVATION_SHA"
+        verify_reserved_dirs
+        [[ -f "$db" && ! -L "$db" ]] || {
+            echo "Image preparation requires reserved SQLite storage." >&2; exit 49;
+        }
+        prepare_image
+        return 0
+    fi
+
     case "$ACTION" in
         import)
             [[ "$EXPECTED_RESERVATION_SHA" == "NONE" && ! -e "$MARKER" ]] || { echo "SQLite import destination was reserved after planning." >&2; exit 47; }
@@ -306,7 +388,7 @@ operate() {
             [[ "$source_real" == "$SOURCE_DATABASE" && -f "$SOURCE_DATABASE" && ! -L "$SOURCE_DATABASE" ]] || { echo "SQLite import source must be an existing non-symlink regular file with no symlinked path components." >&2; exit 49; }
             [[ "$(basename "$SOURCE_DATABASE")" == "$DATABASE_FILE" ]] || { echo "SQLite import source file name mismatch." >&2; exit 49; }
             create_reserved_dirs
-            docker pull "$IMAGE" >/dev/null
+            select_execution_image
             source_parent="$(dirname "$SOURCE_DATABASE")"
             run_backup "$source_parent" "$DATA" "$DATABASE_FILE"
             run_check "$DATA"
@@ -318,7 +400,7 @@ operate() {
             assert_marker "$MARKER" "$EXPECTED_RESERVATION_SHA"
             verify_reserved_dirs
             [[ -f "$db" && ! -L "$db" ]] || { echo "SQLite backup requires the reserved database file." >&2; exit 49; }
-            docker pull "$IMAGE" >/dev/null
+            select_execution_image
             stamp="$(date -u +'%Y%m%dT%H%M%SZ')"
             backup_name="backup-$stamp-$DATABASE_FILE"
             run_backup "$DATA" "$BACKUPS" "$backup_name"
@@ -330,7 +412,7 @@ operate() {
                 [[ "$EXPECTED_RESERVATION_SHA" == "NONE" && ! -e "$MARKER" ]] || { echo "First-install SQLite destination was reserved after planning." >&2; exit 47; }
                 [[ ! -e "$ROOT/deployment.env" && ! -e "$db" ]] || { echo "First-install SQLite migration requires no runtime state or database." >&2; exit 49; }
                 create_reserved_dirs
-                docker pull "$IMAGE" >/dev/null
+                select_execution_image
                 run_migrate "$DATA"
                 run_check "$DATA"
                 write_marker "$MARKER"
@@ -340,7 +422,7 @@ operate() {
                 assert_marker "$MARKER" "$EXPECTED_RESERVATION_SHA"
                 verify_reserved_dirs
                 [[ -f "$db" && ! -L "$db" ]] || { echo "SQLite migration requires the reserved database file." >&2; exit 49; }
-                docker pull "$IMAGE" >/dev/null
+                select_execution_image
                 stamp="$(date -u +'%Y%m%dT%H%M%SZ')"
                 backup_name="pre-migrate-$stamp-$DATABASE_FILE"
                 run_backup "$DATA" "$BACKUPS" "$backup_name"
@@ -359,7 +441,7 @@ operate() {
             assert_marker "$MARKER" "$EXPECTED_RESERVATION_SHA"
             verify_reserved_dirs
             [[ -f "$db" && ! -L "$db" ]] || { echo "SQLite rollback check requires the reserved database file." >&2; exit 49; }
-            docker pull "$IMAGE" >/dev/null
+            select_execution_image
             run_check "$DATA"
             record_evidence "$ROOT" rollback-check compatible ""
             printf 'SQLite rollback compatibility check passed for image %s.\n' "$IMAGE"
@@ -370,7 +452,7 @@ operate() {
 
 case "$ACTION" in
     inventory) inventory ;;
-    import|backup|migrate|rollback-check) operate ;;
+    import|backup|migrate|rollback-check|prepare-image) operate ;;
     *) echo "Unsupported SQLite adapter action: $ACTION" >&2; exit 2 ;;
 esac
 '''

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "4.18.0",
+  "version": "4.19.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {