@mriekki/project-forge 4.20.0 → 4.21.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.20.0",
+  "version": "4.21.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -21,7 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "977ada7310f649adea34059381339012a0c0daaf",
+      "revision": "f2d20ec7aac61494ef9fdb7f3702060b8d8d8865",
       "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.20.0",
+  "version": "4.21.0",
   "components": {
     "core": {
       "revision": "4c74c1801b82d3aa438447d392024d32ca5697b0",
@@ -361,7 +361,7 @@
       ]
     },
     "deployment": {
-      "revision": "977ada7310f649adea34059381339012a0c0daaf",
+      "revision": "f2d20ec7aac61494ef9fdb7f3702060b8d8d8865",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -392,7 +392,7 @@
         {
           "source": "src/project_forge_deployment/app_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_cli.py",
-          "sha256": "f27704c80b1eff45888bf56745bcf8755f2fad88851147600af7056953757825"
+          "sha256": "b44ec913fd1080ff66bff6643d2d9fad17262725c0f35557c56f52c86090c060"
         },
         {
           "source": "src/project_forge_deployment/app_deployment.py",
@@ -402,12 +402,12 @@
         {
           "source": "src/project_forge_deployment/app_runtime.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_runtime.py",
-          "sha256": "73736aada7c3db0e2a7c74a3e88990316b89e6c34a71b4997cdc4c79c7e31708"
+          "sha256": "6f4ae7f663dc7a4e51225c1420f7aa6be5d2b77445b792f9e4495ba3eeb059ad"
         },
         {
           "source": "src/project_forge_deployment/app_runtime_remote.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_runtime_remote.py",
-          "sha256": "791cc7592cff93555f7b6facdd31fbe58de5e711732d9dfcb9321500a0d79cdf"
+          "sha256": "5b6ddffcc1105d3a401ae17456cdfdb279c3005bfcb6c81bbd1eabc27479de05"
         },
         {
           "source": "src/project_forge_deployment/app_runtime_workstation.py",

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

@@ -49,6 +49,16 @@ def _parse_env(items: list[str]) -> list[tuple[str, str]]:
     return result
 
 
+def _parse_materials(items: list[str]) -> list[tuple[str, str]]:
+    values: list[tuple[str, str]] = []
+    for item in items:
+        if "=" not in item:
+            raise DeploymentKitError("--read-only-material requires NAME=/absolute/container/directory.")
+        name, target = item.split("=", 1)
+        values.append((name, target))
+    return values
+
+
 def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
     if args.yes:
         return
@@ -91,6 +101,13 @@ def _add_runtime_contract(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--health-path", required=True)
     parser.add_argument("--run-as", required=True)
     parser.add_argument("--data-container-path")
+    parser.add_argument(
+        "--read-only-material",
+        action="append",
+        default=[],
+        metavar="NAME=/container/directory",
+        help="Opt-in root-owned remote material directory; source derived from Project/environment/name",
+    )
     parser.add_argument(
         "--env",
         action="append",
@@ -185,6 +202,7 @@ def main(argv: list[str] | None = None) -> int:
             persistence_mode=args.persistence_mode,
             data_container_path=args.data_container_path,
             environment_variables=_parse_env(args.env),
+            read_only_materials=_parse_materials(args.read_only_material),
         )
         assert_app_spec_matches_persistence(args.name, spec)
 

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

@@ -19,6 +19,8 @@ from .app_runtime_remote import REMOTE_SCRIPT
 
 APP_ROOT = "/srv/project-forge-apps"
 APP_SCHEMA_VERSION = 1
+# Operator-provisioned remote sources: never workstation paths or auto-created directories.
+REMOTE_MATERIAL_ROOT = "/srv/project-forge-material"
 APP_DEPLOY_WRITE_PHRASE = "[APP DEPLOY WRITE]"
 PRODUCTION_APP_DEPLOY_WRITE_PHRASE = "[PRODUCTION APP DEPLOY]"
 
@@ -84,6 +86,67 @@ def _container_path(value: str | None) -> str | None:
     return value.rstrip("/") or "/"
 
 
+
+def _normalize_read_only_materials(
+    materials: Iterable[tuple[str, str]] | None,
+    *,
+    data_path: str | None,
+) -> list[dict[str, str]]:
+    if materials is None:
+        return []
+    result: list[dict[str, str]] = []
+    names: set[str] = set()
+    paths: list[str] = []
+    for name, target in materials:
+        if len(result) >= 8:
+            raise DeploymentKitError("Remote read-only material mount count must not exceed eight.")
+        name = _slug(name, "read-only material name")
+        if name in names:
+            raise DeploymentKitError(f"Duplicate read-only material name: {name}")
+        if not isinstance(target, str) or _CONTAINER_PATH_RE.fullmatch(target) is None:
+            raise DeploymentKitError("Read-only material target must be a safe absolute container directory.")
+        parts = target.split("/")[1:]
+        if not parts or any(part in {"", ".", ".."} for part in parts):
+            raise DeploymentKitError("Read-only material target must be normalized and cannot be root.")
+        if parts[0] in {"proc", "sys", "dev", "run"} or parts[:2] == ["var", "run"]:
+            raise DeploymentKitError("Read-only material cannot mask a container system runtime directory.")
+        for other in paths + ([data_path] if data_path else []):
+            if target == other or target.startswith(other.rstrip("/") + "/") or other.startswith(target + "/"):
+                raise DeploymentKitError("Read-only material target overlaps another mount.")
+        names.add(name)
+        paths.append(target)
+        result.append({"name": name, "containerPath": target})
+    return sorted(result, key=lambda item: item["name"])
+
+
+def _material_evidence_for_spec(name: str, spec: dict[str, Any]) -> dict[str, str] | None:
+    materials = spec.get("readOnlyMaterials")
+    if not materials:
+        return None
+    profile = load_profile(name)
+    evidence = verify_access(profile)
+    output = _run_remote(profile, evidence["address"], "material-inspect", spec=spec)
+    observed: dict[str, str] = {}
+    for line in output.splitlines():
+        parts = line.split("\t")
+        if len(parts) != 3 or parts[0] != "MATERIAL":
+            raise DeploymentKitError("Malformed remote material source evidence.")
+        _, material_name, identity = parts
+        if not re.fullmatch(r"[a-z0-9](?:[a-z0-9-]*[a-z0-9])?", material_name) or not re.fullmatch(r"[0-9]+:[0-9]+", identity):
+            raise DeploymentKitError("Malformed remote material source identity.")
+        if material_name in observed:
+            raise DeploymentKitError("Duplicate remote material source evidence.")
+        observed[material_name] = identity
+    if set(observed) != {item["name"] for item in materials}:
+        raise DeploymentKitError("Remote material inspection omitted or added a source.")
+    return dict(sorted(observed.items()))
+
+
+def _verify_material_evidence(name: str, plan: dict[str, Any]) -> None:
+    if plan["spec"].get("readOnlyMaterials"):
+        if _material_evidence_for_spec(name, plan["spec"]) != plan["readOnlyMaterialEvidence"]:
+            raise DeploymentKitError("Remote material directory identity changed after planning; review a new plan.")
+
 def _normalize_environment_variables(items: dict[str, str] | Iterable[tuple[str, str]]) -> dict[str, str]:
     pairs = items.items() if isinstance(items, dict) else items
     result: dict[str, str] = {}
@@ -111,6 +174,7 @@ def normalize_app_spec(
     persistence_mode: str,
     data_container_path: str | None,
     environment_variables: dict[str, str] | Iterable[tuple[str, str]],
+    read_only_materials: Iterable[tuple[str, str]] | None = None,
 ) -> dict[str, Any]:
     if persistence_mode not in {"none", "directory"}:
         raise DeploymentKitError("persistenceMode must be 'none' or 'directory'.")
@@ -135,6 +199,9 @@ def normalize_app_spec(
         },
         "environmentVariables": _normalize_environment_variables(environment_variables),
     }
+    materials = _normalize_read_only_materials(read_only_materials, data_path=data_path)
+    if materials:
+        spec["readOnlyMaterials"] = materials
     spec["specSha256"] = _spec_sha(spec)
     return spec
 
@@ -150,8 +217,13 @@ def _b64(value: str) -> str:
     return base64.b64encode(value.encode("utf-8")).decode("ascii")
 
 
-def build_remote_script(spec: dict[str, Any] | None = None) -> str:
+def build_remote_script(
+    spec: dict[str, Any] | None = None, *, expected_materials: dict[str, str] | None = None,
+) -> str:
     env_keys: list[str] = []
+    material_names: list[str] = []
+    material_targets: list[str] = []
+    material_expected: list[str] = []
     env_values: list[str] = []
     desired = {
         "ownerRepo": "",
@@ -183,9 +255,14 @@ def build_remote_script(spec: dict[str, Any] | None = None) -> str:
         for key, value in spec["environmentVariables"].items():
             env_keys.append(_b64(key))
             env_values.append(_b64(value))
+        for item in spec.get("readOnlyMaterials", []):
+            material_names.append(_b64(item["name"]))
+            material_targets.append(_b64(item["containerPath"]))
+            material_expected.append((expected_materials or {}).get(item["name"], ""))
 
     replacements = {
         "__APP_ROOT__": APP_ROOT,
+        "__MATERIAL_ROOT__": REMOTE_MATERIAL_ROOT,
         "__APP_SCHEMA_VERSION__": str(APP_SCHEMA_VERSION),
         "__NETWORK_NAME__": NETWORK_NAME,
         "__CADDY_CONTAINER__": CADDY_CONTAINER,
@@ -203,6 +280,9 @@ def build_remote_script(spec: dict[str, Any] | None = None) -> str:
         "__D_SPEC_SHA__": desired["specSha256"],
         "__D_ENV_KEYS__": " ".join(f"'{item}'" for item in env_keys),
         "__D_ENV_VALUES__": " ".join(f"'{item}'" for item in env_values),
+        "__D_MATERIAL_NAMES__": " ".join(shlex.quote(x) for x in material_names),
+        "__D_MATERIAL_TARGETS__": " ".join(shlex.quote(x) for x in material_targets),
+        "__D_MATERIAL_EXPECTED__": " ".join(shlex.quote(x) for x in material_expected),
     }
     script = REMOTE_SCRIPT
     for placeholder, value in replacements.items():
@@ -224,7 +304,7 @@ def _parse_inventory(output: str) -> dict[str, Any]:
                 raise DeploymentKitError("Malformed or duplicate application inventory summary.")
             summary[parts[1]] = parts[2]
             continue
-        if parts[0] != "APP" or len(parts) != 15:
+        if parts[0] != "APP" or len(parts) not in (15, 17):
             raise DeploymentKitError("Malformed application inventory record.")
         try:
             port = int(parts[7])
@@ -258,6 +338,29 @@ def _parse_inventory(output: str) -> dict[str, Any]:
             "connectedToSharedNetwork": parts[13] == "true",
             "httpHealthy": parts[14] == "true",
         }
+        if len(parts) == 17:
+            if parts[15] not in {"true", "false"} or not parts[16]:
+                raise DeploymentKitError("Malformed remote material mount readiness.")
+            materials: list[dict[str, str]] = []
+            for encoded in parts[16].split(";"):
+                pieces = encoded.split("@")
+                if len(pieces) != 3 or re.fullmatch(r"[0-9]+:[0-9]+", pieces[2]) is None:
+                    raise DeploymentKitError("Malformed remote material inventory identity.")
+                materials.append({
+                    "name": pieces[0],
+                    "containerPath": pieces[1],
+                    "sourceIdentity": pieces[2],
+                })
+            normalized = _normalize_read_only_materials(
+                [(item["name"], item["containerPath"]) for item in materials],
+                data_path=None,
+            )
+            if [(item["name"], item["containerPath"]) for item in normalized] != [
+                (item["name"], item["containerPath"]) for item in materials
+            ]:
+                raise DeploymentKitError("Remote material inventory is unordered or conflicting.")
+            app["readOnlyMaterials"] = materials
+            app["materialMountsVerified"] = parts[15] == "true"
         apps.append(app)
     if set(summary) != {"appCount"}:
         raise DeploymentKitError("Application inventory omitted appCount.")
@@ -280,8 +383,9 @@ def _run_remote(
     *,
     spec: dict[str, Any] | None = None,
     expected_spec_sha: str = "",
+    expected_materials: dict[str, str] | None = None,
 ) -> str:
-    if action not in {"inventory", "deploy"}:
+    if action not in {"inventory", "deploy", "material-inspect"}:
         raise DeploymentKitError(f"Unsupported application-runtime action: {action}")
     args = [action]
     if action == "deploy":
@@ -293,7 +397,7 @@ def _run_remote(
     )
     completed = subprocess.run(
         command,
-        input=build_remote_script(spec).encode("utf-8"),
+        input=build_remote_script(spec, expected_materials=expected_materials).encode("utf-8"),
         check=False,
         capture_output=True,
     )
@@ -360,9 +464,10 @@ def plan_app_deploy(name: str, spec: dict[str, Any]) -> dict[str, Any]:
         and existing["containerRunning"]
         and existing["connectedToSharedNetwork"]
         and existing["httpHealthy"]
+        and existing.get("materialMountsVerified", True)
     ):
         raise DeploymentKitError("The exact application runtime spec is already deployed and healthy.")
-    return {
+    plan = {
         "targetName": name,
         "action": "deploy",
         "environment": spec["environment"],
@@ -385,6 +490,9 @@ def plan_app_deploy(name: str, spec: dict[str, Any]) -> dict[str, Any]:
         "expectedSpecSha256": existing["specSha256"] if existing is not None else None,
         "spec": spec,
     }
+    if spec.get("readOnlyMaterials"):
+        plan["readOnlyMaterialEvidence"] = _material_evidence_for_spec(name, spec)
+    return plan
 
 
 def deploy_write_phrase(plan: dict[str, Any]) -> str:
@@ -428,7 +536,7 @@ def render_locked_app_deploy_stage(
         "expectedSpecSha256",
         "spec",
     }
-    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "deploy":
+    if not isinstance(plan, dict) or set(plan) != required | ({"readOnlyMaterialEvidence"} if plan.get("spec", {}).get("readOnlyMaterials") else set()) 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)
@@ -456,7 +564,8 @@ def render_locked_app_deploy_stage(
         )
     profile = load_profile(plan["targetName"])
     evidence = verify_access(profile)
-    script = build_remote_script(plan["spec"])
+    _verify_material_evidence(plan["targetName"], plan)
+    script = build_remote_script(plan["spec"], expected_materials=plan.get("readOnlyMaterialEvidence"))
     delimiter = "PROJECT_FORGE_APP_DEPLOY_STAGE_" + hashlib.sha256(script.encode()).hexdigest()[:24]
     if delimiter in script:
         raise DeploymentKitError("Unsafe application deployment script delimiter collision.")
@@ -495,7 +604,7 @@ def apply_app_deploy(plan: dict[str, Any]) -> dict[str, Any]:
         "expectedSpecSha256",
         "spec",
     }
-    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "deploy":
+    if not isinstance(plan, dict) or set(plan) != required | ({"readOnlyMaterialEvidence"} if plan.get("spec", {}).get("readOnlyMaterials") else set()) or plan["action"] != "deploy":
         raise DeploymentKitError("Malformed application deployment plan.")
 
     current = app_inventory(plan["targetName"])
@@ -507,6 +616,7 @@ def apply_app_deploy(plan: dict[str, Any]) -> dict[str, Any]:
     if platform["state"] != "ready":
         raise DeploymentKitError("Shared host platform is no longer ready; application deployment is blocked.")
 
+    _verify_material_evidence(plan["targetName"], plan)
     profile = load_profile(plan["targetName"])
     evidence = verify_access(profile)
     _run_remote(
@@ -515,6 +625,7 @@ def apply_app_deploy(plan: dict[str, Any]) -> dict[str, Any]:
         "deploy",
         spec=plan["spec"],
         expected_spec_sha=plan["expectedSpecSha256"] or "",
+        expected_materials=plan.get("readOnlyMaterialEvidence"),
     )
     final = app_inventory(plan["targetName"])
     deployed = _find_app(final, plan["appSlug"], plan["environment"])
@@ -526,6 +637,7 @@ def apply_app_deploy(plan: dict[str, Any]) -> dict[str, Any]:
         deployed["containerRunning"]
         and deployed["connectedToSharedNetwork"]
         and deployed["httpHealthy"]
+        and deployed.get("materialMountsVerified", True)
     ):
         raise DeploymentKitError("Application deployment completed but runtime readiness is not healthy.")
     final["mutated"] = True

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

@@ -8,6 +8,7 @@ EXPECTED_SPEC_SHA="${2:-}"
 DEPLOY_USER="${3:-}"
 HELD_LOCK_FD="${4:-}"
 APP_ROOT="__APP_ROOT__"
+MATERIAL_ROOT="__MATERIAL_ROOT__"
 APP_SCHEMA_VERSION="__APP_SCHEMA_VERSION__"
 NETWORK_NAME="__NETWORK_NAME__"
 CADDY_CONTAINER="__CADDY_CONTAINER__"
@@ -26,6 +27,9 @@ D_DATA_TARGET_B64="__D_DATA_TARGET_B64__"
 D_SPEC_SHA="__D_SPEC_SHA__"
 D_ENV_KEYS=(__D_ENV_KEYS__)
 D_ENV_VALUES=(__D_ENV_VALUES__)
+D_MATERIAL_NAMES=(__D_MATERIAL_NAMES__)
+D_MATERIAL_TARGETS=(__D_MATERIAL_TARGETS__)
+D_MATERIAL_EXPECTED=(__D_MATERIAL_EXPECTED__)
 
 b64d() { printf '%s' "$1" | base64 --decode; }
 meta_value() {
@@ -53,6 +57,92 @@ network_has_container() {
         grep -Fxq "$container"
 }
 
+
+material_source() {
+    printf '%s/%s/%s/%s' "$MATERIAL_ROOT" "$D_APP" "$D_ENV" "$1"
+}
+material_identity() {
+    local source="$1" run_as="$2" uid gid dir owner mode hazards
+    uid="${run_as%%:*}"
+    gid="$uid"
+    [[ "$run_as" != *:* ]] || gid="${run_as#*:}"
+    command -v setpriv >/dev/null 2>&1 || {
+        echo "setpriv is required to verify read-only material access for runAs." >&2; return 1;
+    }
+    for dir in /srv "$MATERIAL_ROOT" "$MATERIAL_ROOT/$D_APP" "$MATERIAL_ROOT/$D_APP/$D_ENV" "$source"; do
+        [[ -d "$dir" && ! -L "$dir" ]] || {
+            echo "Read-only material directory missing or linked: $dir" >&2; return 1;
+        }
+        owner="$(stat -c '%u' "$dir")"
+        mode="$(stat -c '%a' "$dir")"
+        [[ "$owner" == 0 ]] && (( (8#$mode & 022) == 0 )) || {
+            echo "Read-only material directory ownership or mode is unsafe: $dir" >&2; return 1;
+        }
+    done
+    hazards="$(find -P "$source" -mindepth 1 \( -type l -o ! -uid 0 -o -perm /022 -o \( ! -type f -a ! -type d \) \) -print -quit)" || return 1
+    [[ -z "$hazards" ]] || {
+        echo "Read-only material tree has linked, writable, unowned or special entries." >&2; return 1;
+    }
+    setpriv --reuid "$uid" --regid "$gid" --clear-groups -- bash -c '
+        path="$1"
+        [[ -r "$path" && -x "$path" ]] || exit 1
+        invalid="$(find -P "$path" \( -type d \( ! -readable -o ! -executable \) -o -type f ! -readable \) -print -quit)" || exit 1
+        [[ -z "$invalid" ]]
+    ' -- "$source" || {
+        echo "Read-only material tree is not readable/traversable by runAs." >&2; return 1;
+    }
+    stat -c '%d:%i' "$source"
+}
+validate_material_entries() {
+    [[ "${#D_MATERIAL_NAMES[@]}" -eq "${#D_MATERIAL_TARGETS[@]}" &&
+       "${#D_MATERIAL_NAMES[@]}" -eq "${#D_MATERIAL_EXPECTED[@]}" ]] || {
+        echo "Read-only material argument count mismatch." >&2; exit 33;
+    }
+    local index name target part prior data
+    local -a segments targets=()
+    data="$D_DATA_TARGET"
+    for index in "${!D_MATERIAL_NAMES[@]}"; do
+        name="$(b64d "${D_MATERIAL_NAMES[$index]}")"
+        target="$(b64d "${D_MATERIAL_TARGETS[$index]}")"
+        valid_slug "$name" || { echo "Invalid read-only material name." >&2; exit 33; }
+        [[ "$target" == /* && "$target" != / && "$target" =~ ^/[A-Za-z0-9._~+:/-]+$ ]] || {
+            echo "Invalid read-only material target." >&2; exit 33;
+        }
+        IFS='/' read -r -a segments <<< "${target#/}"
+        for part in "${segments[@]}"; do
+            [[ -n "$part" && "$part" != . && "$part" != .. ]] || {
+                echo "Read-only material target is not normalized." >&2; exit 33;
+            }
+        done
+        case "$target/" in
+            /proc/*|/sys/*|/dev/*|/run/*|/var/run/*)
+                echo "Read-only material target overlaps a system path." >&2; exit 33;;
+        esac
+        for prior in "${targets[@]}" "$data"; do
+            [[ -z "$prior" ]] && continue
+            if [[ "$target" == "$prior" || "$target" == "$prior/"* || "$prior" == "$target/"* ]]; then
+                echo "Read-only material target overlaps another mount." >&2; exit 33
+            fi
+        done
+        targets+=("$target")
+    done
+}
+material_probe() {
+    local check_expected="$1" index name source identity expected
+    for index in "${!D_MATERIAL_NAMES[@]}"; do
+        name="$(b64d "${D_MATERIAL_NAMES[$index]}")"
+        source="$(material_source "$name")"
+        identity="$(material_identity "$source" "$D_RUN_AS")" || return 1
+        expected="${D_MATERIAL_EXPECTED[$index]}"
+        if [[ "$check_expected" == true && "$identity" != "$expected" ]]; then
+            echo "Read-only material directory changed after planning: $name" >&2; return 1
+        fi
+        if [[ "$check_expected" != true ]]; then
+            printf 'MATERIAL\t%s\t%s\n' "$name" "$identity"
+        fi
+    done
+}
+
 probe_http() {
     local container="$1" port="$2" path="$3"
     docker exec "$CADDY_CONTAINER" \
@@ -75,6 +165,47 @@ wait_ready() {
     return 1
 }
 
+
+material_inventory_state() {
+    local file="$1" app="$2" env="$3" container="$4" persistence="$5"
+    local number index name target source recorded current raw mounts run_as data_target line
+    number="$(meta_value "$file" MATERIAL_COUNT || true)"
+    MATERIAL_OK=true
+    MATERIAL_ENTRIES=""
+    [[ -n "$number" ]] || return 0
+    [[ "$number" =~ ^[1-8]$ ]] || { echo "Invalid saved material count." >&2; return 1; }
+    D_APP="$app"
+    D_ENV="$env"
+    run_as="$(meta_value "$file" RUN_AS || true)"
+    valid_run_as "$run_as" || { echo "Invalid saved material runAs." >&2; return 1; }
+    mounts="$(docker inspect --format '{{range .Mounts}}{{printf "%s@%s@%t@%s\n" .Source .Destination .RW .Type}}{{end}}' "$container" 2>/dev/null)" || {
+        MATERIAL_OK=false
+        mounts=""
+    }
+    local expected_count="$number"
+    if [[ "$persistence" == directory ]]; then
+        data_target="$(b64d "$(meta_value "$file" DATA_TARGET_B64 || true)")"
+        line="$APP_ROOT/$app/$env/data@$data_target@true@bind"
+        grep -Fxq -- "$line" <<< "$mounts" || MATERIAL_OK=false
+        expected_count="$((number + 1))"
+    fi
+    [[ "$(grep -c '.' <<< "$mounts" || true)" == "$expected_count" ]] || MATERIAL_OK=false
+    for ((index=0; index < number; index++)); do
+        name="$(b64d "$(meta_value "$file" MATERIAL_NAME_B64_"$index" || true)")"
+        target="$(b64d "$(meta_value "$file" MATERIAL_TARGET_B64_"$index" || true)")"
+        recorded="$(meta_value "$file" MATERIAL_ID_"$index" || true)"
+        valid_slug "$name" && [[ "$target" =~ ^/[A-Za-z0-9._~+:/-]+$ && "$recorded" =~ ^[0-9]+:[0-9]+$ ]] || {
+            echo "Invalid saved material mount metadata." >&2; return 1;
+        }
+        source="$(material_source "$name")"
+        current="$(material_identity "$source" "$run_as" 2>/dev/null)" || { MATERIAL_OK=false; current=""; }
+        [[ "$current" == "$recorded" ]] || MATERIAL_OK=false
+        grep -Fxq -- "$source@$target@false@bind" <<< "$mounts" || MATERIAL_OK=false
+        [[ -z "$MATERIAL_ENTRIES" ]] || MATERIAL_ENTRIES+=";"
+        MATERIAL_ENTRIES+="$name@$target@$recorded"
+    done
+}
+
 inventory() {
     local count=0 state current previous release_file
     local owner env app container image spec_sha port health persistence
@@ -114,9 +245,16 @@ inventory() {
             if [[ "$running" == true && "$connected" == true ]]; then
                 probe_http "$container" "$port" "$health" && healthy=true || true
             fi
-            printf 'APP\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
-                "$owner" "$env" "$app" "$container" "$image" "$spec_sha" "$port" "$health" "$persistence" \
-                "$current" "$previous" "$running" "$connected" "$healthy"
+            material_inventory_state "$release_file" "$app" "$env" "$container" "$persistence" || exit 31
+            if [[ -n "$MATERIAL_ENTRIES" ]]; then
+                printf 'APP\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+                    "$owner" "$env" "$app" "$container" "$image" "$spec_sha" "$port" "$health" "$persistence" \
+                    "$current" "$previous" "$running" "$connected" "$healthy" "$MATERIAL_OK" "$MATERIAL_ENTRIES"
+            else
+                printf 'APP\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+                    "$owner" "$env" "$app" "$container" "$image" "$spec_sha" "$port" "$health" "$persistence" \
+                    "$current" "$previous" "$running" "$connected" "$healthy"
+            fi
             count=$((count + 1))
         done < <(find "$APP_ROOT" -mindepth 3 -maxdepth 3 -type f -name deployment.env -print 2>/dev/null | sort)
     fi
@@ -173,6 +311,7 @@ decode_desired() {
         exit 33
     }
     valid_run_as "$D_RUN_AS" || { echo "Invalid numeric runAs value." >&2; exit 33; }
+    validate_material_entries
     [[ "$D_PERSISTENCE" == "none" || "$D_PERSISTENCE" == "directory" ]] || {
         echo "Invalid persistence mode." >&2
         exit 33
@@ -216,6 +355,14 @@ write_release_metadata() {
         printf 'PERSISTENCE_MODE=%s\n' "$D_PERSISTENCE"
         printf 'DATA_TARGET_B64=%s\n' "$D_DATA_TARGET_B64"
         printf 'SPEC_SHA256=%s\n' "$D_SPEC_SHA"
+        if (( ${#D_MATERIAL_NAMES[@]} > 0 )); then
+            printf 'MATERIAL_COUNT=%s\n' "${#D_MATERIAL_NAMES[@]}"
+            for index in "${!D_MATERIAL_NAMES[@]}"; do
+                printf 'MATERIAL_NAME_B64_%s=%s\n' "$index" "${D_MATERIAL_NAMES[$index]}"
+                printf 'MATERIAL_TARGET_B64_%s=%s\n' "$index" "${D_MATERIAL_TARGETS[$index]}"
+                printf 'MATERIAL_ID_%s=%s\n' "$index" "${D_MATERIAL_EXPECTED[$index]}"
+            done
+        fi
         printf 'ENV_COUNT=%s\n' "${#D_ENV_KEYS[@]}"
         for index in "${!D_ENV_KEYS[@]}"; do
             key_b64="${D_ENV_KEYS[$index]}"
@@ -271,6 +418,13 @@ start_desired_container() {
         value="$(b64d "${D_ENV_VALUES[$index]}")"
         docker_args+=(--env "$key=$value")
     done
+    for index in "${!D_MATERIAL_NAMES[@]}"; do
+        local source target name
+        name="$(b64d "${D_MATERIAL_NAMES[$index]}")"
+        target="$(b64d "${D_MATERIAL_TARGETS[$index]}")"
+        source="$(material_source "$name")"
+        docker_args+=(--mount "type=bind,src=$source,dst=$target,readonly")
+    done
     docker_args+=("$D_IMAGE")
     "${docker_args[@]}" >/dev/null
 }
@@ -339,6 +493,7 @@ deploy() {
     release_file="$release_dir/release.env"
 
     acquire_deployment_lock "$lock_file"
+    material_probe true || { echo "Read-only material preflight failed." >&2; exit 40; }
 
     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; }
@@ -397,11 +552,22 @@ deploy() {
             echo "Release directory collision with different runtime metadata." >&2
             exit 35
         }
+        if (( ${#D_MATERIAL_NAMES[@]} > 0 )); then
+            [[ "$(release_value "$release_file" MATERIAL_COUNT || true)" == "${#D_MATERIAL_NAMES[@]}" ]] || {
+                echo "Existing release material metadata mismatch." >&2; exit 35;
+            }
+            for index in "${!D_MATERIAL_NAMES[@]}"; do
+                [[ "$(release_value "$release_file" MATERIAL_ID_"$index" || true)" == "${D_MATERIAL_EXPECTED[$index]}" ]] || {
+                    echo "Existing release material directory identity changed." >&2; exit 35;
+                }
+            done
+        fi
     else
         write_release_metadata "$release_file"
     fi
 
     docker pull "$D_IMAGE" >/dev/null
+    material_probe true || { echo "Read-only material source changed before runtime replacement." >&2; exit 40; }
 
     if [[ -n "$current_container" ]]; then
         docker rm -f "$current_container" >/dev/null
@@ -442,6 +608,10 @@ case "$ACTION" in
     deploy)
         deploy
         ;;
+    material-inspect)
+        decode_desired
+        material_probe false || exit 40
+        ;;
     *)
         echo "Unsupported application-runtime action: $ACTION" >&2
         exit 2

package/package.json

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