@mriekki/project-forge 4.17.0 → 4.19.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.17.0",
+  "version": "4.19.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -21,7 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "f5f82c531da03f113209a795930db8444338c69e",
+      "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.17.0",
+  "version": "4.19.0",
   "components": {
     "core": {
       "revision": "4c74c1801b82d3aa438447d392024d32ca5697b0",
@@ -361,7 +361,7 @@
       ]
     },
     "deployment": {
-      "revision": "f5f82c531da03f113209a795930db8444338c69e",
+      "revision": "09b2ace0b75fcd51ca7175d480bd5671e8be9520",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -397,17 +397,17 @@
         {
           "source": "src/project_forge_deployment/app_deployment.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_deployment.py",
-          "sha256": "606d6a4793ac8c8a95da4cd4c61792c69f02ad86900be1944d2ed570dd71e73e"
+          "sha256": "aeecda05bd2f71276dd49f09fd599cf529ea9fe9b0aae7c1e26ab92bd57e7f22"
         },
         {
           "source": "src/project_forge_deployment/app_runtime.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_runtime.py",
-          "sha256": "5f7c6fdd2e84d1f239ceae605018b3c7b8a911aac442241b000333ffadf1fdeb"
+          "sha256": "73736aada7c3db0e2a7c74a3e88990316b89e6c34a71b4997cdc4c79c7e31708"
         },
         {
           "source": "src/project_forge_deployment/app_runtime_remote.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_runtime_remote.py",
-          "sha256": "f86defc9a0841deee40198c7acc3b25a093e514000f0bd08030cbb253f3fa6ee"
+          "sha256": "791cc7592cff93555f7b6facdd31fbe58de5e711732d9dfcb9321500a0d79cdf"
         },
         {
           "source": "src/project_forge_deployment/app_runtime_workstation.py",
@@ -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": "32c319453add977de4e051ca9cadbffaa411adb26713c4a8731553d0d2d4adaf"
+          "sha256": "e327a079cb2fb1bec744c77684811ee3a6f382523484b70b430c9cdd73f730f1"
         },
         {
           "source": "src/project_forge_deployment/sqlite_cli.py",

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

@@ -14,6 +14,7 @@ from .app_runtime import PRODUCTION_APP_DEPLOY_WRITE_PHRASE
 from .app_runtime import apply_app_deploy as _apply_runtime_deploy
 from .app_runtime import deploy_write_phrase
 from .app_runtime import plan_app_deploy as _plan_runtime_deploy
+from .app_runtime import render_locked_app_deploy_stage as _render_locked_runtime_deploy_stage
 from .app_runtime_workstation import apply_app_deploy_with_preloaded_image
 from .environment_isolation import environment_isolation_preflight
 from .errors import DeploymentKitError
@@ -272,6 +273,30 @@ def apply_app_deploy(plan: dict[str, Any]) -> dict[str, Any]:
     return _apply_runtime_deploy(_runtime_plan(plan))
 
 
+def render_locked_app_deploy_stage(
+    plan: dict[str, Any], *, inherited_lock_fd: int, authorization: str,
+) -> dict[str, str]:
+    """Render a registry-backed deploy stage after isolation revalidation."""
+
+    runtime_plan = _runtime_plan(plan)
+    review = plan[ISOLATION_REVIEW_KEY]
+    if not isinstance(review, dict) or type(review.get("production")) is not bool:
+        raise DeploymentKitError("Application deployment plan has malformed Production classification.")
+    production = review["production"] or runtime_plan["environment"] == "production"
+    expected_authorization = (
+        PRODUCTION_APP_DEPLOY_WRITE_PHRASE if production else deploy_write_phrase(runtime_plan)
+    )
+    if authorization != expected_authorization:
+        raise DeploymentKitError("Exact reviewed application deployment authorization phrase is required.")
+    revalidate_app_isolation(plan)
+    return _render_locked_runtime_deploy_stage(
+        runtime_plan,
+        inherited_lock_fd=inherited_lock_fd,
+        authorization=authorization,
+        production=production,
+    )
+
+
 def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
     """Transfer an exact image, then recheck isolation again before runtime mutation."""
 
@@ -291,4 +316,5 @@ __all__ = [
     "plan_app_deploy",
     "plan_app_rollout",
     "revalidate_app_isolation",
+    "render_locked_app_deploy_stage",
 ]

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

@@ -6,6 +6,7 @@ import base64
 import hashlib
 import json
 import re
+import shlex
 import subprocess
 from typing import Any, Iterable
 
@@ -394,6 +395,82 @@ def deploy_write_phrase(plan: dict[str, Any]) -> str:
     )
 
 
+def render_locked_app_deploy_stage(
+    plan: dict[str, Any], *, inherited_lock_fd: int, authorization: str, production: bool = False,
+) -> dict[str, str]:
+    """Render a Kit-validated deployment stage for an existing remote lock scope.
+
+    The returned Bash stage is not an SSH command or authorization to run it.
+    The caller must hold the exact app/environment lock in the same privileged
+    remote shell and keep it through its application-specific checks and this
+    stage. The remote script verifies the inherited descriptor before deploy.
+    """
+    required = {
+        "targetName",
+        "action",
+        "environment",
+        "appSlug",
+        "ownerRepo",
+        "containerName",
+        "image",
+        "runtimePort",
+        "healthPath",
+        "persistenceMode",
+        "changeType",
+        "previousImage",
+        "previousRelease",
+        "retainsPreviousRelease",
+        "publishesHostPort",
+        "attachesSharedNetwork",
+        "modifiesRoutes",
+        "persistentDataDeletion",
+        "inventorySnapshot",
+        "expectedSpecSha256",
+        "spec",
+    }
+    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "deploy":
+        raise DeploymentKitError("Malformed application deployment plan.")
+    if (plan["changeType"] != "update" or plan["retainsPreviousRelease"] is not True
+            or not isinstance(plan["expectedSpecSha256"], str)
+            or re.fullmatch(r"[0-9a-f]{64}", plan["expectedSpecSha256"]) is None):
+        raise DeploymentKitError("Lock handoff is limited to an existing application deployment update.")
+    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 type(production) is not bool:
+        raise DeploymentKitError("Production classification must be a boolean.")
+    expected_authorization = (
+        PRODUCTION_APP_DEPLOY_WRITE_PHRASE
+        if production or plan["environment"] == "production"
+        else APP_DEPLOY_WRITE_PHRASE
+    )
+    if authorization != expected_authorization:
+        raise DeploymentKitError("Exact reviewed application deployment authorization phrase is required.")
+
+    platform = platform_status(plan["targetName"])
+    if platform["state"] != "ready":
+        raise DeploymentKitError("Shared host platform is no longer ready; application deployment is blocked.")
+    current = app_inventory(plan["targetName"])
+    if _inventory_snapshot(current) != plan["inventorySnapshot"]:
+        raise DeploymentKitError(
+            "Application inventory 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"])
+    delimiter = "PROJECT_FORGE_APP_DEPLOY_STAGE_" + hashlib.sha256(script.encode()).hexdigest()[:24]
+    if delimiter in script:
+        raise DeploymentKitError("Unsafe application deployment script delimiter collision.")
+    command = "bash -s -- " + shlex.join([
+        "deploy", plan["expectedSpecSha256"], profile["user"], str(inherited_lock_fd),
+    ])
+    return {
+        "targetName": plan["targetName"],
+        "verifiedAddress": evidence["address"],
+        "action": "deploy",
+        "script": f"{command} <<'{delimiter}'\n{script.rstrip()}\n{delimiter}\n",
+    }
+
+
 def apply_app_deploy(plan: dict[str, Any]) -> dict[str, Any]:
     required = {
         "targetName",

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

@@ -6,6 +6,7 @@ set -Eeuo pipefail
 ACTION="$1"
 EXPECTED_SPEC_SHA="${2:-}"
 DEPLOY_USER="${3:-}"
+HELD_LOCK_FD="${4:-}"
 APP_ROOT="__APP_ROOT__"
 APP_SCHEMA_VERSION="__APP_SCHEMA_VERSION__"
 NETWORK_NAME="__NETWORK_NAME__"
@@ -284,6 +285,43 @@ record_evidence() {
     chmod 0600 "$root/deployment-evidence.jsonl"
 }
 
+acquire_deployment_lock() {
+    local lock_file="$1"
+    if [[ -z "$HELD_LOCK_FD" ]]; then
+        exec 9>>"$lock_file"
+        flock -n 9 || {
+            echo "Another application deployment holds the lock for $D_APP--$D_ENV." >&2
+            exit 75
+        }
+        return 0
+    fi
+
+    [[ "$ACTION" == "deploy" && "$EXPECTED_SPEC_SHA" =~ ^[0-9a-f]{64}$ ]] || {
+        echo "An inherited lock is supported only for existing application deployments." >&2
+        exit 75
+    }
+    [[ "$HELD_LOCK_FD" =~ ^[0-9]+$ ]] && (( 10#$HELD_LOCK_FD >= 3 && 10#$HELD_LOCK_FD <= 256 )) || {
+        echo "Inherited application lock descriptor is invalid." >&2
+        exit 75
+    }
+    [[ -f "$lock_file" && ! -L "$lock_file" ]] || {
+        echo "Inherited application lock path is invalid." >&2
+        exit 75
+    }
+    local inherited_inode expected_inode
+    inherited_inode="$(stat -Lc '%d:%i' "/proc/self/fd/$HELD_LOCK_FD" 2>/dev/null || true)"
+    expected_inode="$(stat -Lc '%d:%i' "$lock_file" 2>/dev/null || true)"
+    [[ -n "$inherited_inode" && "$inherited_inode" == "$expected_inode" ]] || {
+        echo "Inherited application lock descriptor does not match this app/environment." >&2
+        exit 75
+    }
+    grep -Eq '^lock:[[:space:]]+[0-9]+:[[:space:]]+FLOCK[[:space:]]+ADVISORY[[:space:]]+WRITE([[:space:]]|$)' \
+        "/proc/self/fdinfo/$HELD_LOCK_FD" || {
+        echo "Inherited application lock was not held by this descriptor." >&2
+        exit 75
+    }
+}
+
 deploy() {
     platform_ready || { echo "Kit shared platform is not ready." >&2; exit 34; }
     decode_desired
@@ -300,11 +338,7 @@ deploy() {
     release_dir="$releases/$release_id"
     release_file="$release_dir/release.env"
 
-    exec 9>>"$lock_file"
-    if ! flock -n 9; then
-        echo "Another application deployment holds the lock for $D_APP--$D_ENV." >&2
-        exit 75
-    fi
+    acquire_deployment_lock "$lock_file"
 
     for path in "$root" "$releases" "$state" "$root/data" "$root/deployment-evidence.jsonl"; do
         [[ ! -L "$path" ]] || { echo "Managed application path must not be a symbolic link: $path" >&2; exit 35; }

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 )) || {
@@ -275,26 +283,80 @@ acquire_operation_lock() {
     [[ -f "$LOCK_FILE" && ! -L "$LOCK_FILE" ]] || {
         echo "Inherited SQLite lock path is invalid." >&2; exit 75;
     }
-    local inherited_inode expected_inode probe_fd
+    local inherited_inode expected_inode
     inherited_inode="$(stat -Lc '%d:%i' "/proc/self/fd/$HELD_LOCK_FD" 2>/dev/null || true)"
     expected_inode="$(stat -Lc '%d:%i' "$LOCK_FILE" 2>/dev/null || true)"
     [[ -n "$inherited_inode" && "$inherited_inode" == "$expected_inode" ]] || {
         echo "Inherited SQLite lock descriptor does not match this app/environment." >&2; exit 75;
     }
-    # Independent open descriptions must contend: prove the caller ALREADY
-    # holds the lock, not merely that it passed an unlocked file descriptor.
-    exec {probe_fd}>>"$LOCK_FILE"
-    if flock -n "$probe_fd"; then
-        flock -u "$probe_fd"
-        exec {probe_fd}>&-
-        echo "Inherited SQLite lock was not held before this operation." >&2; exit 75
+    grep -Eq '^lock:[[:space:]]+[0-9]+:[[:space:]]+FLOCK[[:space:]]+ADVISORY[[:space:]]+WRITE([[:space:]]|$)' \
+        "/proc/self/fdinfo/$HELD_LOCK_FD" || {
+        echo "Inherited SQLite lock was not held by this descriptor." >&2; exit 75;
+    }
+}
+
+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
-    exec {probe_fd}>&-
-    # A successful flock on this inherited open description proves ownership,
-    # rather than unrelated contention on a different descriptor.
-    flock -n "$HELD_LOCK_FD" || {
-        echo "Inherited SQLite lock is owned by another operation." >&2; exit 75;
+    [[ -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() {
@@ -306,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; }
@@ -316,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"
@@ -328,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"
@@ -340,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"
@@ -350,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"
@@ -369,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"
@@ -380,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.17.0",
+  "version": "4.19.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {