@mriekki/project-forge 4.15.1 → 4.16.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.15.1",
+  "version": "4.16.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -13,7 +13,7 @@
   },
   "components": {
     "core": {
-      "revision": "6e31941ac4b6c2490b0470b1b4d25b7289b97c98",
+      "revision": "4c74c1801b82d3aa438447d392024d32ca5697b0",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -21,7 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "1119331414ec53e0c48b864403fabfef7998df60",
+      "revision": "f5325556e1ee1e256e3dfb426d91feb42cbdc2c3",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/generated/ASSEMBLY.json

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.15.1",
+  "version": "4.16.0",
   "components": {
     "core": {
-      "revision": "6e31941ac4b6c2490b0470b1b4d25b7289b97c98",
+      "revision": "4c74c1801b82d3aa438447d392024d32ca5697b0",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -56,7 +56,7 @@
         {
           "source": "core/skills/setup/SKILL.md",
           "destination": ".github/skills/setup/SKILL.md",
-          "sha256": "d1c6e7a0a04a1fb358b136ed8f83495c27bf8959ebd8941a3d42397fa4dcbaf1"
+          "sha256": "0e08797b2f7d7e3e3f825cbb22bdad509255a4a0b875878d4ec1d9eecd23cad2"
         },
         {
           "source": "core/skills/build/SKILL.md",
@@ -361,7 +361,7 @@
       ]
     },
     "deployment": {
-      "revision": "1119331414ec53e0c48b864403fabfef7998df60",
+      "revision": "f5325556e1ee1e256e3dfb426d91feb42cbdc2c3",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -512,17 +512,17 @@
         {
           "source": "src/project_forge_deployment/local_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/local_cli.py",
-          "sha256": "f44d4900852354ee38703d35025a3efefd32686f2158659dcb62a7c2142400e0"
+          "sha256": "b0b99dc66a95a5f9cb386a15d7a32f3f935bf37be2cf06175ceb9cc2c9a479cd"
         },
         {
           "source": "src/project_forge_deployment/local_runtime.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/local_runtime.py",
-          "sha256": "b83c9eeef0e53088bf9617a237f5ff864903b4f9e83797d34e9f2b8763b36e8e"
+          "sha256": "1d84ab88baac81a7a9ead001156d86b4969d834e34e4f766b33cfcff2fc1d1ce"
         },
         {
           "source": "src/project_forge_deployment/local_spec.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/local_spec.py",
-          "sha256": "372b8c041edd9d3a1005861d85bb3a6bad38064b0be081a470460ad2dc62be4d"
+          "sha256": "bddaafcb5785e74103cb82d73f01d4e577c97476bd6a6549b3e332cca5eb50f8"
         },
         {
           "source": "src/project_forge_deployment/local_sqlite.py",

package/assets/generated/core/core/skills/setup/SKILL.md

@@ -46,7 +46,7 @@ From the repository root inspect only what is needed:
 - `PROJECT_BOOTSTRAP.json` as generation/provenance and initial topology fallback;
 - `SCAFFOLD_PLAN.json` when present;
 - `.github/project-forge-workspace.json` and Project Forge/component baselines when present;
-- `scripts/setup.ps1` on Windows or `scripts/setup.sh` on macOS;
+- `scripts/setup.ps1` on Windows or `scripts/setup.sh` on macOS/Linux; WSL2 is the supported generated Linux setup path;
 - `tools/project-forge-vscode/work-item-status/install.py` and `docs/work-items` when present;
 - current Git branch/status/upstream evidence so setup does not overwrite unrelated work;
 - workstation-local setup/readiness evidence when present;
@@ -104,8 +104,9 @@ Do not silently repair state during `status`.
 Select the launcher for the actual workstation OS:
 
 ```text
-Windows  -> .\scripts\setup.ps1
-macOS    -> ./scripts/setup.sh
+Windows     -> .\scripts\setup.ps1
+macOS       -> ./scripts/setup.sh
+Linux/WSL2  -> ./scripts/setup.sh
 ```
 
 For normal setup, run the launcher with repository restore enabled when supported:
@@ -147,7 +148,6 @@ python tools/project-forge-vscode/work-item-status/install.py install --json
 ```
 
 This installation is already authorized by `/setup` as routine workstation preparation; do not require a second `/work-item-status enable` confirmation. The installer may replace older versions of this same Project Forge extension only and must not install unrelated extensions, alter Project files, or change Git/GitHub state.
-
 If the result has `reloadRequired: true`, tell the developer to reload VS Code once after setup. Do not repeatedly reinstall an already-ready version merely because the editor has not yet been reloaded.
 
 If a Project has local `docs/work-items` but the package-managed installer is absent, report:
@@ -447,7 +447,6 @@ Never silently edit `sshd`, widen account/source policy, disable host verificati
 A verified workstation-to-target access relationship may be reused by multiple Projects/environments that bind to the same logical target. Environment proof remains specific to the Project + named environment + target + adapter/isolation contract.
 
 When Staging and Production share one physical target, explicitly surface the shared failure domain and verify that their Project/environment-owned runtime identity, compose project, route/port allocation, persistence paths, and locking cannot collide. Staging evidence does not become Production evidence merely because the host is shared.
-
 ## 8. Prove supported remote mechanics with a disposable Project Forge probe
 
 When the installed Deployment Kit exposes environment proof operations, a selected remote environment should normally be taken through an end-to-end **environment proof deployment** during setup.

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

@@ -42,6 +42,24 @@ def _parse_env(items: list[str]) -> list[tuple[str, str]]:
     return result
 
 
+def _parse_mapping(value: str) -> dict[str, int]:
+    try:
+        left, right = value.split(":")
+        return {"hostPort": int(left), "runtimePort": int(right)}
+    except (ValueError, TypeError) as error:
+        raise DeploymentKitError("--additional-port requires HOST_PORT:RUNTIME_PORT.") from error
+
+
+def _parse_mount(value: str) -> dict[str, str]:
+    try:
+        left, right = value.split("::", 1)
+        if not left or not right:
+            raise ValueError("empty path")
+        return {"source": left, "target": right}
+    except ValueError as error:
+        raise DeploymentKitError("--read-only-mount requires SOURCE::TARGET.") from error
+
+
 def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
     if args.yes:
         return
@@ -102,6 +120,8 @@ def build_parser() -> argparse.ArgumentParser:
     deploy.add_argument("--persistence-mode", choices=("none", "directory"), required=True)
     deploy.add_argument("--data-container-path")
     deploy.add_argument("--env", action="append", default=[])
+    deploy.add_argument("--additional-port", action="append", default=[], metavar="HOST_PORT:RUNTIME_PORT")
+    deploy.add_argument("--read-only-mount", action="append", default=[], metavar="SOURCE::TARGET")
     deploy.add_argument("--json", action="store_true")
     deploy.add_argument("--yes", action="store_true")
     return parser
@@ -170,6 +190,8 @@ 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),
+            additional_port_bindings=[_parse_mapping(value) for value in args.additional_port],
+            read_only_mounts=[_parse_mount(value) for value in args.read_only_mount],
         )
         plan = plan_local_deploy(spec)
         production_classified = args.production or plan["environment"] == "production"

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

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import hashlib
 import json
+import socket
 import shutil
 import subprocess
 import time
@@ -14,6 +15,7 @@ from typing import Any, Iterable
 
 from .app_runtime import PRODUCTION_APP_DEPLOY_WRITE_PHRASE, normalize_app_spec
 from .errors import DeploymentKitError
+from .local_extensions import bindings, normalize_bindings, normalize_mounts, snapshot_material
 from .profiles import config_root
 
 LOCAL_RUNTIME_SCHEMA_VERSION = 1
@@ -107,7 +109,7 @@ def _load_state(app_slug: str, environment: str) -> dict[str, Any] | None:
         value = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, UnicodeError, json.JSONDecodeError) as error:
         raise DeploymentKitError(f"Cannot read local deployment state {path}: {error}") from error
-    if not isinstance(value, dict) or value.get("schemaVersion") != LOCAL_RUNTIME_SCHEMA_VERSION:
+    if not isinstance(value, dict) or value.get("schemaVersion") not in (1, 2):
         raise DeploymentKitError(f"Unsupported local deployment state: {path}")
     return value
 
@@ -126,6 +128,8 @@ def normalize_local_spec(
     persistence_mode: str,
     data_container_path: str | None,
     environment_variables: dict[str, str] | Iterable[tuple[str, str]],
+    additional_port_bindings: list[dict[str, int]] | None = None,
+    read_only_mounts: list[dict[str, str]] | None = None,
 ) -> dict[str, Any]:
     base = normalize_app_spec(
         owner_repo=owner_repo,
@@ -151,6 +155,12 @@ def normalize_local_spec(
             "hostPort": _host_port(host_port),
         }
     )
+    extra_bindings = normalize_bindings(base["hostPort"], base["runtimePort"], additional_port_bindings or [])
+    extra_mounts = normalize_mounts(base["appSlug"], base["environment"], read_only_mounts or [], base["persistence"]["dataContainerPath"])
+    if extra_bindings:
+        base["additionalPortBindings"] = extra_bindings
+    if extra_mounts:
+        base["readOnlyMounts"] = extra_mounts
     base["specSha256"] = hashlib.sha256(
         json.dumps(base, sort_keys=True, separators=(",", ":")).encode("utf-8")
     ).hexdigest()
@@ -163,7 +173,7 @@ def _inspect_owned_container(docker: str, container_name: str) -> dict[str, Any]
         [
             "inspect",
             "--format",
-            "{{json .Config.Labels}}\t{{json .NetworkSettings.Ports}}\t{{.State.Running}}",
+            "{{json .Config.Labels}}\t{{json .NetworkSettings.Ports}}\t{{.State.Running}}\t{{json .Mounts}}\t{{json .HostConfig.PortBindings}}",
             container_name,
         ],
         check=False,
@@ -176,11 +186,13 @@ def _inspect_owned_container(docker: str, container_name: str) -> dict[str, Any]
             f"Unable to inspect local container {container_name}: {(inspected.stderr or inspected.stdout).strip()}"
         )
     parts = inspected.stdout.strip().split("\t")
-    if len(parts) != 3:
+    if len(parts) != 5:
         raise DeploymentKitError("Local Docker inspect returned malformed container evidence.")
     try:
         labels = json.loads(parts[0]) if parts[0] else {}
         ports = json.loads(parts[1]) if parts[1] else {}
+        mounts = json.loads(parts[3]) if parts[3] else []
+        host_bindings = json.loads(parts[4]) if parts[4] else {}
     except json.JSONDecodeError as error:
         raise DeploymentKitError("Local Docker inspect returned malformed JSON evidence.") from error
     if not isinstance(labels, dict):
@@ -188,6 +200,8 @@ def _inspect_owned_container(docker: str, container_name: str) -> dict[str, Any]
     return {
         "labels": labels,
         "ports": ports if isinstance(ports, dict) else {},
+        "mounts": mounts if isinstance(mounts, list) else [],
+        "hostBindings": host_bindings if isinstance(host_bindings, dict) else {},
         "running": parts[2].strip().lower() == "true",
     }
 
@@ -235,6 +249,9 @@ def _managed_containers(docker: str) -> list[dict[str, Any]]:
                 "environment": labels[_LABEL_ENV],
                 "specSha256": labels[_LABEL_SPEC],
                 "running": info["running"],
+                "actualPorts": info["ports"],
+                "actualMounts": info["mounts"],
+                "actualHostBindings": info["hostBindings"],
             }
         )
     return result
@@ -249,6 +266,98 @@ def _http_healthy(spec: dict[str, Any], *, timeout: float = 2.0) -> bool:
         return False
 
 
+
+def _actual_bindings(raw: dict[str, Any]) -> list[dict[str, int | str]]:
+    result: list[dict[str, int | str]] = []
+    if not isinstance(raw, dict):
+        raise DeploymentKitError("Invalid Docker port-binding evidence.")
+    for container, hosts in raw.items():
+        if hosts is None:
+            continue  # Exposed internally, not published on the host.
+        if not isinstance(hosts, list) or not container.endswith("/tcp"):
+            raise DeploymentKitError("Unexpected Docker port protocol or malformed binding evidence.")
+        try:
+            runtime = int(container.removesuffix("/tcp"))
+            for host in hosts:
+                result.append({"hostAddress": host["HostIp"], "hostPort": int(host["HostPort"]), "runtimePort": runtime})
+        except (KeyError, ValueError, TypeError) as error:
+            raise DeploymentKitError("Invalid Docker port-binding evidence.") from error
+    return sorted(result, key=lambda item: (item["hostPort"], item["runtimePort"]))
+
+
+def _expected_bindings(state: dict[str, Any]) -> list[dict[str, int | str]]:
+    return sorted(({"hostAddress": LOOPBACK_ADDRESS, **item} for item in bindings(state)),
+                  key=lambda item: (item["hostPort"], item["runtimePort"]))
+
+
+def _actual_mounts(raw: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    if not isinstance(raw, list):
+        raise DeploymentKitError("Invalid Docker mount evidence.")
+    try:
+        return sorted(({"source": item["Source"], "target": item["Destination"],
+                        "readOnly": not item["RW"], "type": item["Type"]} for item in raw),
+                      key=lambda item: (item["target"], item["source"]))
+    except (KeyError, TypeError) as error:
+        raise DeploymentKitError("Invalid Docker mount evidence.") from error
+
+
+def _expected_mounts(state: dict[str, Any]) -> list[dict[str, Any]]:
+    expected = [{"source": item["source"], "target": item["target"], "readOnly": True, "type": "bind"}
+                for item in state.get("readOnlyMounts", [])]
+    if state["persistence"]["mode"] == "directory":
+        expected.append({"source": str(_data_dir(state["appSlug"], state["environment"]).resolve()),
+                         "target": state["persistence"]["dataContainerPath"], "readOnly": False, "type": "bind"})
+    return sorted(expected, key=lambda item: (item["target"], item["source"]))
+
+
+def _config_drift(container: dict[str, Any], state: dict[str, Any] | None) -> bool:
+    if not state or container["specSha256"] != state.get("specSha256"):
+        return True
+    try:
+        actual = _actual_bindings(container["actualPorts"])
+        host_config = _actual_bindings(container["actualHostBindings"])
+        return (actual != _expected_bindings(state)
+                or host_config != _expected_bindings(state)
+                or _actual_mounts(container["actualMounts"]) != _expected_mounts(state))
+    except (DeploymentKitError, KeyError, TypeError, ValueError):
+        return True
+
+
+def _assert_bindable(ports: list[int], owned_ports: set[int]) -> None:
+    for port in ports:
+        if port in owned_ports:
+            continue
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+                probe.bind((LOOPBACK_ADDRESS, port))
+        except OSError as error:
+            raise DeploymentKitError(f"Loopback host port {port} is occupied or unavailable.") from error
+
+
+def _preflight_material(docker: str, spec: dict[str, Any]) -> None:
+    if not spec.get("readOnlyMounts"):
+        return
+    for mount in spec["readOnlyMounts"]:
+        source = Path(mount["source"])
+        checks: list[str] = []
+        for path in [source, *sorted(source.rglob("*"))]:
+            suffix = path.relative_to(source).as_posix()
+            inside = mount["target"] if suffix == "." else mount["target"] + "/" + suffix
+            checks.extend(["d:" + inside if path.is_dir() else "f:" + inside])
+        args = ["run", "--rm", "--network", "none", "--read-only", "--pull", "never",
+                "--user", spec["runAs"], "--mount",
+                f"type=bind,source={mount['source']},target={mount['target']},readonly",
+                "--entrypoint", "/bin/sh", spec["image"], "-c",
+                'for item do path=${item#??}; case "$item" in d:*) [ -d "$path" ] && [ -r "$path" ] && [ -x "$path" ] ;; f:*) [ -f "$path" ] && [ -r "$path" ] ;; esac || exit 1; done',
+                "--", *checks]
+        result = _run(docker, args, check=False)
+        if result.returncode != 0:
+            raise DeploymentKitError(
+                "Material preflight failed: configured container UID/GID cannot read approved material "
+                "or the immutable image lacks /bin/sh. Existing runtime was not replaced."
+            )
+
+
 def local_inventory() -> dict[str, Any]:
     docker = _docker()
     applications: list[dict[str, Any]] = []
@@ -266,6 +375,9 @@ def local_inventory() -> dict[str, Any]:
                 "runtimePort": state.get("runtimePort") if state else None,
                 "healthPath": state.get("healthPath") if state else None,
                 "httpHealthy": bool(state and container["running"] and _http_healthy(state)),
+                "additionalPortBindings": state.get("additionalPortBindings", []) if state else [],
+                "readOnlyMounts": state.get("readOnlyMounts", []) if state else [],
+                "configurationDrift": _config_drift(container, state),
             }
         )
         applications.append(item)
@@ -292,6 +404,9 @@ def _inventory_snapshot(inventory: dict[str, Any]) -> str:
                     "specSha256",
                     "running",
                     "hostPort",
+                    "additionalPortBindings",
+                    "readOnlyMounts",
+                    "configurationDrift",
                 )
             }
             for item in inventory["applications"]
@@ -306,10 +421,8 @@ def _assert_port_available(
     inventory: dict[str, Any], *, host_port: int, app_slug: str, environment: str
 ) -> None:
     for item in inventory["applications"]:
-        if item.get("hostPort") == host_port and (item["appSlug"], item["environment"]) != (
-            app_slug,
-            environment,
-        ):
+        owned = {item.get("hostPort")} | {mapping["hostPort"] for mapping in item.get("additionalPortBindings", [])}
+        if host_port in owned and (item["appSlug"], item["environment"]) != (app_slug, environment):
             raise DeploymentKitError(
                 f"Loopback host port {host_port} is already owned by "
                 f"{item['appSlug']} / {item['environment']}."
@@ -326,12 +439,11 @@ def plan_local_deploy(spec: dict[str, Any]) -> dict[str, Any]:
         environment=spec["environment"],
     )
     inventory = local_inventory()
-    _assert_port_available(
-        inventory,
-        host_port=spec["hostPort"],
-        app_slug=spec["appSlug"],
-        environment=spec["environment"],
-    )
+    for mapping in bindings(spec):
+        _assert_port_available(
+            inventory, host_port=mapping["hostPort"],
+            app_slug=spec["appSlug"], environment=spec["environment"],
+        )
     existing = next(
         (
             item
@@ -340,7 +452,7 @@ def plan_local_deploy(spec: dict[str, Any]) -> dict[str, Any]:
         ),
         None,
     )
-    if existing and existing["specSha256"] == spec["specSha256"] and existing["running"] and existing["httpHealthy"]:
+    if existing and existing["specSha256"] == spec["specSha256"] and existing["running"] and existing["httpHealthy"] and not existing.get("configurationDrift", True):
         raise DeploymentKitError("The exact local application runtime is already deployed and healthy.")
     return {
         "action": "deploy",
@@ -361,6 +473,9 @@ def plan_local_deploy(spec: dict[str, Any]) -> dict[str, Any]:
         "changeType": "update" if existing else "create",
         "previousImage": existing.get("image") if existing else None,
         "inventorySnapshot": _inventory_snapshot(inventory),
+        **({"materialSnapshot": snapshot_material(spec)} if spec.get("readOnlyMounts") else {}),
+        **({"additionalPortBindings": spec["additionalPortBindings"]} if spec.get("additionalPortBindings") else {}),
+        **({"readOnlyMounts": spec["readOnlyMounts"]} if spec.get("readOnlyMounts") else {}),
         "spec": spec,
     }
 
@@ -392,6 +507,10 @@ def _container_args(spec: dict[str, Any]) -> list[str]:
         "--label",
         f"{_LABEL_PLACEMENT}=workstation",
     ]
+    for mapping in spec.get("additionalPortBindings", []):
+        args.extend(["-p", f"{LOOPBACK_ADDRESS}:{mapping['hostPort']}:{mapping['runtimePort']}"])
+    for mount in spec.get("readOnlyMounts", []):
+        args.extend(["--mount", f"type=bind,source={mount['source']},target={mount['target']},readonly"])
     if spec["persistence"]["mode"] == "directory":
         data_dir = _data_dir(spec["appSlug"], spec["environment"]).resolve()
         data_dir.mkdir(parents=True, exist_ok=True)
@@ -416,7 +535,9 @@ def _wait_for_health(spec: dict[str, Any], *, timeout_seconds: float = 120.0) ->
 
 def _persist_state(spec: dict[str, Any]) -> None:
     value = {
-        "schemaVersion": LOCAL_RUNTIME_SCHEMA_VERSION,
+        "schemaVersion": 2 if spec.get("additionalPortBindings") or spec.get("readOnlyMounts") else LOCAL_RUNTIME_SCHEMA_VERSION,
+        **({"additionalPortBindings": spec["additionalPortBindings"]} if spec.get("additionalPortBindings") else {}),
+        **({"readOnlyMounts": spec["readOnlyMounts"]} if spec.get("readOnlyMounts") else {}),
         "ownerRepo": spec["ownerRepo"],
         "appSlug": spec["appSlug"],
         "environment": spec["environment"],
@@ -459,7 +580,13 @@ def apply_local_deploy(plan: dict[str, Any]) -> dict[str, Any]:
         "inventorySnapshot",
         "spec",
     }
-    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "deploy":
+    if not isinstance(plan, dict):
+        raise DeploymentKitError("Malformed local application deployment plan.")
+    if plan.get("additionalPortBindings"):
+        required.add("additionalPortBindings")
+    if plan.get("readOnlyMounts"):
+        required.update(("readOnlyMounts", "materialSnapshot"))
+    if set(plan) != required or plan["action"] != "deploy":
         raise DeploymentKitError("Malformed local application deployment plan.")
     current = local_inventory()
     if _inventory_snapshot(current) != plan["inventorySnapshot"]:
@@ -467,6 +594,18 @@ def apply_local_deploy(plan: dict[str, Any]) -> dict[str, Any]:
             "Local application inventory changed after plan review; create and authorize a fresh plan."
         )
     spec = plan["spec"]
+    if plan.get("additionalPortBindings", []) != spec.get("additionalPortBindings", []) or plan.get("readOnlyMounts", []) != spec.get("readOnlyMounts", []):
+        raise DeploymentKitError("Deployment plan options differ from the approved specification.")
+    if plan.get("materialSnapshot") != snapshot_material(spec):
+        raise DeploymentKitError("External material changed after review; approve a fresh deployment plan.")
+    current_app = next((item for item in current["applications"]
+                        if item["appSlug"] == spec["appSlug"] and item["environment"] == spec["environment"]), None)
+    if current_app and current_app.get("configurationDrift", False):
+        raise DeploymentKitError("Existing managed Docker runtime has configuration drift; do not replace it automatically.")
+    for mapping in bindings(spec):
+        _assert_port_available(current, host_port=mapping["hostPort"], app_slug=spec["appSlug"], environment=spec["environment"])
+    owned_ports = ({item["hostPort"] for item in bindings(current_app)} if current_app else set())
+    _assert_bindable([item["hostPort"] for item in bindings(spec)], owned_ports)
     docker = _docker()
     existing = _assert_owned_or_absent(
         docker,
@@ -487,30 +626,54 @@ def apply_local_deploy(plan: dict[str, Any]) -> dict[str, Any]:
         "exposure": "loopback",
     }
     try:
-        if existing is not None:
-            _run(docker, ["rm", "-f", spec["containerName"]])
         if spec.get("imageSource") == "local-image-id":
             _run(docker, ["image", "inspect", spec["image"]])
         else:
             _run(docker, ["pull", spec["image"]])
+        # All detectable preflight checks precede removal of the existing container.
+        if plan.get("materialSnapshot") != snapshot_material(spec):
+            raise DeploymentKitError("External material changed before replacement.")
+        _preflight_material(docker, spec)
+        if existing is not None:
+            _run(docker, ["rm", "-f", spec["containerName"]])
         _run(docker, _container_args(spec))
         _wait_for_health(spec)
     except DeploymentKitError:
         _append_evidence(spec["appSlug"], spec["environment"], {**evidence_base, "outcome": "failed"})
         raise
-    _persist_state(spec)
+    # Verify the new container against the approved spec, not persisted state:
+    # a late failure must not overwrite the last accepted deployment record.
+    try:
+        actual = _inspect_owned_container(docker, spec["containerName"])
+        if actual is None or not actual["running"]:
+            raise DeploymentKitError("Local deployment is not running after health verification.")
+        observed = {
+            "specSha256": actual["labels"].get(_LABEL_SPEC),
+            "actualPorts": actual["ports"],
+            "actualHostBindings": actual["hostBindings"],
+            "actualMounts": actual["mounts"],
+        }
+        if actual["labels"].get(_LABEL_OWNER) != spec["ownerRepo"] or (
+            actual["labels"].get(_LABEL_APP), actual["labels"].get(_LABEL_ENV)
+        ) != (spec["appSlug"], spec["environment"]) or _config_drift(observed, spec):
+            raise DeploymentKitError("Local Docker configuration does not match the approved spec.")
+        _persist_state(spec)
+        final = local_inventory()
+        deployed = next(
+            (
+                item
+                for item in final["applications"]
+                if item["appSlug"] == spec["appSlug"] and item["environment"] == spec["environment"]
+            ),
+            None,
+        )
+        if not deployed or deployed["specSha256"] != spec["specSha256"] or not deployed["httpHealthy"] or deployed.get("configurationDrift", False):
+            raise DeploymentKitError("Local deployment completed but readiness evidence is not healthy.")
+    except DeploymentKitError:
+        _append_evidence(spec["appSlug"], spec["environment"],
+                         {**evidence_base, "outcome": "failed", "reason": "post-deploy-verification"})
+        raise
     _append_evidence(spec["appSlug"], spec["environment"], {**evidence_base, "outcome": "ready"})
-    final = local_inventory()
-    deployed = next(
-        (
-            item
-            for item in final["applications"]
-            if item["appSlug"] == spec["appSlug"] and item["environment"] == spec["environment"]
-        ),
-        None,
-    )
-    if not deployed or deployed["specSha256"] != spec["specSha256"] or not deployed["httpHealthy"]:
-        raise DeploymentKitError("Local deployment completed but readiness evidence is not healthy.")
     final["mutated"] = True
     return final
 

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

@@ -9,6 +9,7 @@ from typing import Any, Iterable
 
 from .app_runtime import normalize_app_spec
 from .errors import DeploymentKitError
+from .local_extensions import normalize_bindings, normalize_mounts
 
 
 _LOCAL_IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
@@ -40,6 +41,8 @@ def normalize_workstation_spec(
     persistence_mode: str,
     data_container_path: str | None,
     environment_variables: dict[str, str] | Iterable[tuple[str, str]],
+    additional_port_bindings: list[dict[str, int]] | None = None,
+    read_only_mounts: list[dict[str, str]] | None = None,
 ) -> dict[str, Any]:
     """Normalize a loopback-only workstation spec.
 
@@ -76,6 +79,12 @@ def normalize_workstation_spec(
             "imageSource": "local-image-id" if local_image_id else "registry-digest",
         }
     )
+    extra_bindings = normalize_bindings(base["hostPort"], base["runtimePort"], additional_port_bindings or [])
+    extra_mounts = normalize_mounts(base["appSlug"], base["environment"], read_only_mounts or [], base["persistence"]["dataContainerPath"])
+    if extra_bindings:
+        base["additionalPortBindings"] = extra_bindings
+    if extra_mounts:
+        base["readOnlyMounts"] = extra_mounts
     base["specSha256"] = hashlib.sha256(
         json.dumps(base, sort_keys=True, separators=(",", ":")).encode("utf-8")
     ).hexdigest()

package/package.json

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