@mriekki/project-forge 4.1.0 → 4.3.0

package/assets/generated/deployment/docs/PROJECT_TOPOLOGY_BINDING.md

@@ -0,0 +1,44 @@
+# Project topology target binding
+
+Project Forge keeps reusable non-secret target definitions in the developer's personal profile while each Project owns its logical environment-to-target binding in `DEPLOYMENT_TOPOLOGY.json`.
+
+For an existing environment whose durable intent is already `placement: remote-target`, `adapter: remote-ssh`, and `bindingState: deferred`, Deployment Kit can preview and persist one target binding without rewriting Bootstrap provenance or other topology fields.
+
+## Preview
+
+```text
+project-forge-deploy topology plan-binding <environment> \
+  --target-profile <logical-target> \
+  --root . \
+  --json
+```
+
+The preview:
+
+- reads the current project-owned topology;
+- requires the named environment to already be a remote-target/remote-ssh environment;
+- loads the selected user-scoped target profile;
+- checks declared target OS compatibility;
+- shows the exact before/after environment record;
+- changes only `bindingState` and `targetProfile`;
+- records a topology hash so a later write fails if the file changed after preview;
+- never deploys an application, runs a proof, or changes target SSH/profile state.
+
+A configured environment bound to another target is not eligible for this command. Rebinding requires a separate explicit topology-change contract.
+
+## Apply
+
+```text
+project-forge-deploy topology bind <environment> \
+  --target-profile <logical-target> \
+  --root .
+```
+
+The write requires the bounded phrase reported by the plan:
+
+- `[PROJECT TOPOLOGY WRITE]` for non-Production environments;
+- `[PROJECT PRODUCTION TOPOLOGY WRITE]` for Production-class environments.
+
+Production classification comes from the existing topology role. The command never infers a Production target and this authorization is only for project configuration; it does **not** authorize Production proof or application deployment.
+
+After a successful write, callers should re-read `DEPLOYMENT_TOPOLOGY.json` and continue normal environment setup/readiness from the selected logical target.

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

@@ -11,6 +11,7 @@ from .local_cli import main as local_main
 from .registry_cli import main as registry_main
 from .sqlite_cli import main as sqlite_main
 from .teardown_cli import main as teardown_main
+from .topology_cli import main as topology_main
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -27,6 +28,8 @@ def main(argv: list[str] | None = None) -> int:
         return sqlite_main(args[1:])
     if args and args[0] == "tear-down":
         return teardown_main(args[1:])
+    if args and args[0] == "topology":
+        return topology_main(args[1:])
     if not args or args == ["--help"] or args == ["-h"]:
         print("Command group: app  Remote immutable application runtime inventory/deployment")
         print("Command group: environment  Portable profiles, Home Lab onboarding, and image transfer")
@@ -34,4 +37,5 @@ def main(argv: list[str] | None = None) -> int:
         print("Command group: registry  Read-only exact-image registry access verification")
         print("Command group: sqlite  SQLite persistence import/backup/migration/rollback checks")
         print("Command group: tear-down  Scoped destructive Project environment/local cleanup")
+        print("Command group: topology  Project-owned logical environment binding")
     return core_main(args)

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

@@ -56,6 +56,32 @@ def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
         raise DeploymentKitError(f"{action.capitalize()} was not authorized.")
 
 
+def _setup_readiness(result: dict[str, Any], *, require_deployment_path: bool) -> dict[str, Any]:
+    required_phases = ["workspace", "targetDefinition", "targetAccess", "hostPlatform"]
+    expected_states = {
+        "workspace": "ready",
+        "targetDefinition": "ready",
+        "targetAccess": "ready",
+        "hostPlatform": "ready",
+    }
+    if require_deployment_path:
+        required_phases.append("deploymentPath")
+        expected_states["deploymentPath"] = "proven"
+
+    not_ready = [
+        phase
+        for phase in required_phases
+        if result["phases"][phase]["state"] != expected_states[phase]
+    ]
+    return {
+        "ready": not not_ready,
+        "requiredThrough": "deploymentPath" if require_deployment_path else "hostPlatform",
+        "requiredPhases": required_phases,
+        "notReadyPhases": not_ready,
+        "applicationRequired": False,
+    }
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="project-forge-deploy environment")
     groups = parser.add_subparsers(dest="group", required=True)
@@ -68,6 +94,19 @@ def build_parser() -> argparse.ArgumentParser:
     setup_status = setup_sub.add_parser("status", help="Show one terminal readiness model for a remote target")
     setup_status.add_argument("name")
     setup_status.add_argument("--json", action="store_true")
+    setup_check = setup_sub.add_parser(
+        "check",
+        help="Return success only when the requested remote setup readiness contract is satisfied",
+    )
+    setup_check.add_argument("name")
+    setup_check.add_argument("--owner-repo")
+    setup_check.add_argument("--environment")
+    setup_check.add_argument(
+        "--production",
+        action="store_true",
+        help="Require proof evidence classified as Production; requires owner/environment proof context",
+    )
+    setup_check.add_argument("--json", action="store_true")
     setup_plan = setup_sub.add_parser("plan", help="Show the exact next deterministic remote setup action")
     setup_plan.add_argument("name")
     setup_plan.add_argument("--owner-repo")
@@ -201,6 +240,23 @@ def main(argv: list[str] | None = None) -> int:
         if args.group == "setup" and args.command == "status":
             _print(remote_setup_status(args.name), as_json=args.json)
             return 0
+        if args.group == "setup" and args.command == "check":
+            if args.production and (args.owner_repo is None or args.environment is None):
+                raise DeploymentKitError(
+                    "--production requires --owner-repo and --environment for setup readiness checking."
+                )
+            result = remote_setup_plan(
+                args.name,
+                owner_repo=args.owner_repo,
+                environment=args.environment,
+                production=args.production,
+            )
+            readiness = _setup_readiness(
+                result,
+                require_deployment_path=args.owner_repo is not None,
+            )
+            _print({**result, "readinessCheck": readiness}, as_json=args.json)
+            return 0 if readiness["ready"] else 2
         if args.group == "setup" and args.command == "plan":
             _print(
                 remote_setup_plan(

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

@@ -14,6 +14,7 @@ from .app_runtime_workstation import apply_app_deploy_with_preloaded_image
 from .box_platform import platform_status
 from .errors import DeploymentKitError
 from .image_transfer import remote_image_present, transfer_image, verify_local_image
+from .proof_receipt import write_environment_proof_receipt
 from .registry_access import normalize_registry_image
 from .teardown import tear_down_project
 
@@ -152,6 +153,8 @@ def _proof_result(plan: dict[str, Any]) -> dict[str, Any]:
         "finalMutationState": "none",
         "error": None,
         "cleanupError": None,
+        "receipt": None,
+        "receiptError": None,
     }
 
 
@@ -298,4 +301,8 @@ def run_environment_proof(plan: dict[str, Any]) -> dict[str, Any]:
         result["error"] = "Environment proof cleanup did not return terminal runtime cleanup evidence."
 
     result["finalMutationState"] = _final_mutation_state(result)
+    try:
+        result["receipt"] = write_environment_proof_receipt(result)
+    except Exception as error:  # proof result stays truthful even if local evidence persistence fails
+        result["receiptError"] = str(error)
     return result

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

@@ -14,7 +14,8 @@ from .doctor import target_doctor, workstation_doctor
 from .environment_probe import plan_environment_proof
 from .errors import DeploymentKitError
 from .profiles import load_profile
-from .ssh import verify_access
+from .proof_receipt import load_environment_proof_receipt
+from .ssh import diagnose_access
 
 
 READINESS_ORDER = (
@@ -34,6 +35,13 @@ def _phase(label: str, state: str, *, detail: Any = None) -> dict[str, Any]:
     return value
 
 
+def _current_phase(phases: dict[str, dict[str, Any]]) -> str:
+    return next(
+        (key for key in READINESS_ORDER if phases[key]["state"] not in {"ready", "proven", "not-part-of-setup"}),
+        "application",
+    )
+
+
 def remote_setup_status(name: str) -> dict[str, Any]:
     """Return one read-only, terminal status model for remote environment setup."""
 
@@ -57,19 +65,15 @@ def remote_setup_status(name: str) -> dict[str, Any]:
         "application": _phase("APPLICATION DEPLOYED", "not-part-of-setup"),
     }
 
-    target_access: dict[str, Any] | None = None
     host_platform: dict[str, Any] | None = None
 
     if target["state"] == "ready-to-verify":
-        try:
-            target_access = verify_access(load_profile(name))
-            phases["targetAccess"] = _phase("TARGET ACCESS READY", "ready", detail=target_access)
-        except DeploymentKitError as error:
-            phases["targetAccess"] = _phase(
-                "TARGET ACCESS READY",
-                "verification-failed",
-                detail={"reason": str(error)},
-            )
+        target_access = diagnose_access(load_profile(name))
+        phases["targetAccess"] = _phase(
+            "TARGET ACCESS READY",
+            "ready" if target_access["state"] == "verified" else "diagnosis-required",
+            detail=target_access,
+        )
     elif target["state"] == "needs-profile":
         phases["targetAccess"] = _phase("TARGET ACCESS READY", "blocked-by-target-definition")
     else:
@@ -96,19 +100,76 @@ def remote_setup_status(name: str) -> dict[str, Any]:
     else:
         phases["hostPlatform"] = _phase("HOST PLATFORM READY", "blocked-by-target-access")
 
-    current = next(
-        (key for key in READINESS_ORDER if phases[key]["state"] not in {"ready", "not-part-of-setup"}),
-        "application",
-    )
     return {
         "targetName": name,
         "state": "host-platform-ready" if phases["hostPlatform"]["state"] == "ready" else "needs-setup",
-        "currentPhase": current,
+        "currentPhase": _current_phase(phases),
         "phases": phases,
         "mutated": False,
     }
 
 
+def _access_recovery(status: dict[str, Any]) -> dict[str, Any]:
+    detail = status["phases"]["targetAccess"].get("detail") or {}
+    category = detail.get("failureCategory")
+    target = status["targetName"]
+    command = f"project-forge-deploy environment setup status {target} --json"
+
+    if category in {"remote-authentication-rejected", "remote-account-policy-rejected"}:
+        return {
+            "kind": "operator-action-required",
+            "action": "inspect-remote-account-access-policy",
+            "command": command,
+            "reason": detail.get("guidance"),
+            "safety": (
+                "Use a trusted target console or already-authorized administrative session. "
+                "Do not reinstall keys repeatedly, enable password SSH, widen AllowUsers, or weaken host verification implicitly."
+            ),
+        }
+    if category == "local-signing-failed":
+        return {
+            "kind": "local-repair",
+            "action": "repair-local-key-signing",
+            "command": command,
+            "reason": detail.get("guidance"),
+        }
+    if category == "host-identity-rejected":
+        return {
+            "kind": "human-verification",
+            "action": "reverify-host-identity",
+            "command": f"project-forge-deploy target trust-candidates {target}",
+            "reason": detail.get("guidance"),
+        }
+    if category in {"transport-failed", "name-resolution-failed"}:
+        return {
+            "kind": "missing-facts",
+            "action": "repair-target-address-or-network-path",
+            "command": command,
+            "reason": detail.get("guidance") or detail.get("reason"),
+        }
+    if category == "missing-identity":
+        return {
+            "kind": "write-gated",
+            "action": "create-or-select-key",
+            "command": f"project-forge-deploy target key-create {target}",
+            "authorization": "[LOCAL KEY WRITE]",
+            "reason": detail.get("reason"),
+        }
+    if category == "missing-trust":
+        return {
+            "kind": "human-verification",
+            "action": "verify-and-enroll-host-trust",
+            "command": f"project-forge-deploy target trust-candidates {target}",
+            "reason": detail.get("reason"),
+        }
+    return {
+        "kind": "read-only",
+        "action": "diagnose-target-access",
+        "command": command,
+        "reason": detail.get("guidance") or detail.get("reason"),
+    }
+
+
 def _next_action(status: dict[str, Any]) -> dict[str, Any]:
     phases = status["phases"]
     target = phases["targetDefinition"].get("detail") or {}
@@ -151,12 +212,7 @@ def _next_action(status: dict[str, Any]) -> dict[str, Any]:
         }
 
     if phases["targetAccess"]["state"] != "ready":
-        return {
-            "kind": "read-only",
-            "action": "verify-target-access",
-            "command": f"project-forge-deploy target verify {status['targetName']}",
-            "reason": (phases["targetAccess"].get("detail") or {}).get("reason"),
-        }
+        return _access_recovery(status)
 
     platform = phases["hostPlatform"].get("detail") or {}
     platform_state = phases["hostPlatform"]["state"]
@@ -188,6 +244,14 @@ def _next_action(status: dict[str, Any]) -> dict[str, Any]:
             "reason": f"Host platform state is {platform_state}.",
         }
 
+    if phases["deploymentPath"]["state"] == "proven":
+        return {
+            "kind": "complete",
+            "action": "remote-environment-ready",
+            "reason": "Fresh workstation-local proof evidence matches this Project/environment/target context.",
+            "proofReceipt": phases["deploymentPath"].get("detail"),
+        }
+
     return {
         "kind": "proof-context-required",
         "action": "plan-deployment-path-proof",
@@ -204,7 +268,26 @@ def remote_setup_plan(
 ) -> dict[str, Any]:
     """Return the exact next deterministic setup action without mutating state."""
 
+    if (owner_repo is None) != (environment is None):
+        raise DeploymentKitError("ownerRepo and environment must be supplied together for setup proof planning.")
+
     status = remote_setup_status(name)
+    if owner_repo is not None and environment is not None and status["phases"]["hostPlatform"]["state"] == "ready":
+        receipt = load_environment_proof_receipt(
+            name,
+            owner_repo=owner_repo,
+            environment=environment,
+            production=production,
+        )
+        status["phases"]["deploymentPath"] = _phase(
+            "DEPLOYMENT PATH PROVEN",
+            "proven" if receipt["state"] == "proven" else "not-proven",
+            detail=receipt,
+        )
+        status["currentPhase"] = _current_phase(status["phases"])
+        if receipt["state"] == "proven":
+            status["state"] = "environment-ready"
+
     next_action = _next_action(status)
 
     if (
@@ -230,9 +313,8 @@ def remote_setup_plan(
             "command": command,
             "proofPlan": proof,
             "runAuthorization": proof["requiredAuthorization"],
+            "previousProof": status["phases"]["deploymentPath"].get("detail"),
         }
-    elif (owner_repo is None) != (environment is None):
-        raise DeploymentKitError("ownerRepo and environment must be supplied together for setup proof planning.")
 
     return {
         **status,

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

@@ -14,7 +14,7 @@ from .keys import key_fingerprint, public_key_info, required_tool as required_ss
 from .portable_profile import _machine_paths
 from .profiles import load_profile, save_profile, target_profile_path, validate_profile, validate_target_name
 from .security import check_identity_security, prepare_ssh_directory, validate_target_trust_file
-from .ssh import verify_access
+from .ssh import probe_authentication_methods, resolve_addresses, verify_access
 
 
 HOME_LAB_BOOTSTRAP_PHRASE = "[HOME LAB ACCESS BOOTSTRAP]"
@@ -212,6 +212,23 @@ def _password_bootstrap_args(profile: dict[str, Any], *, first_use: bool, comman
     ]
 
 
+def _require_password_bootstrap_capability(profile: dict[str, Any]) -> list[dict[str, Any]]:
+    """Fail before password onboarding when a trusted server advertises key-only auth."""
+
+    evidence = [probe_authentication_methods(profile, address) for address in resolve_addresses(profile)]
+    observed = [item for item in evidence if item["observed"]]
+    if observed and not any(item["passwordSupported"] for item in observed):
+        advertised = sorted({method for item in observed for method in item["methods"]})
+        shown = ", ".join(advertised) if advertised else "none observed"
+        raise DeploymentKitError(
+            "Password-assisted Home Lab bootstrap is unavailable for this trusted target: "
+            f"the SSH server advertises {shown}, not password/keyboard-interactive authentication. "
+            "Use the Strict key-onboarding path and a trusted console or already-authorized session "
+            "for any required server-side key/account-policy change. Do not enable password SSH merely for bootstrap."
+        )
+    return evidence
+
+
 def _install_public_key_with_password(profile: dict[str, Any], *, first_use: bool) -> None:
     info = public_key_info(profile)
     encoded = base64.b64encode(info["publicKey"].encode("utf-8")).decode("ascii")
@@ -316,6 +333,10 @@ def apply_home_lab_bootstrap(
         except DeploymentKitError:
             pass
 
+        # Existing trust lets us discover the server's advertised auth methods safely.
+        # Avoid a guaranteed-to-fail password prompt against public-key-only servers.
+        _require_password_bootstrap_capability(desired)
+
     _install_public_key_with_password(desired, first_use=first_use)
     validate_target_trust_file(desired)
     evidence = verify_access(desired)

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

@@ -0,0 +1,218 @@
+"""Deterministic mutation of project-owned deployment topology bindings."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+from .errors import DeploymentKitError
+from .profiles import load_profile
+
+
+TOPOLOGY_FILE = "DEPLOYMENT_TOPOLOGY.json"
+TOPOLOGY_SCHEMA_VERSION = 1
+PROJECT_TOPOLOGY_WRITE_PHRASE = "[PROJECT TOPOLOGY WRITE]"
+PROJECT_PRODUCTION_TOPOLOGY_WRITE_PHRASE = "[PROJECT PRODUCTION TOPOLOGY WRITE]"
+
+
+def _topology_path(root: str | Path) -> Path:
+    project_root = Path(root).expanduser().resolve()
+    path = project_root / TOPOLOGY_FILE
+    if path.is_symlink() or not path.is_file():
+        raise DeploymentKitError(f"Project deployment topology is missing or unsafe: {path}")
+    return path
+
+
+def _read_topology(root: str | Path) -> tuple[Path, str, dict[str, Any]]:
+    path = _topology_path(root)
+    try:
+        raw = path.read_text(encoding="utf-8")
+        value = json.loads(raw)
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise DeploymentKitError(f"Cannot read project deployment topology {path}: {error}") from error
+    if not isinstance(value, dict) or value.get("schemaVersion") != TOPOLOGY_SCHEMA_VERSION:
+        raise DeploymentKitError("Unsupported or malformed project deployment topology schema.")
+    environments = value.get("environments")
+    if not isinstance(environments, list):
+        raise DeploymentKitError("Project deployment topology environments must be an array.")
+    names: list[str] = []
+    for item in environments:
+        if not isinstance(item, dict):
+            raise DeploymentKitError("Project deployment topology contains a non-object environment.")
+        name = item.get("name")
+        if not isinstance(name, str) or not name:
+            raise DeploymentKitError("Project deployment topology contains an environment without a valid name.")
+        names.append(name)
+    if len(names) != len(set(names)):
+        raise DeploymentKitError("Project deployment topology contains duplicate environment names.")
+    return path, raw, value
+
+
+def _environment(value: dict[str, Any], name: str) -> tuple[int, dict[str, Any]]:
+    for index, item in enumerate(value["environments"]):
+        if item.get("name") == name:
+            return index, item
+    raise DeploymentKitError(f"Project deployment topology does not define environment: {name}")
+
+
+def _topology_sha(raw: str) -> str:
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def plan_environment_binding(
+    root: str | Path,
+    environment: str,
+    target_profile: str,
+) -> dict[str, Any]:
+    """Preview completion of one deferred remote-target binding without writing project state."""
+
+    path, raw, topology = _read_topology(root)
+    _, current = _environment(topology, environment)
+
+    role = current.get("role")
+    if role not in {"non-production", "production"}:
+        raise DeploymentKitError(f"Environment {environment} has an unsupported role: {role}")
+    if current.get("placement") != "remote-target" or current.get("adapter") != "remote-ssh":
+        raise DeploymentKitError(
+            f"Environment {environment} is not an existing remote-target/remote-ssh binding; "
+            "this command will not rewrite placement or adapter intent."
+        )
+
+    profile = load_profile(target_profile)
+    target_os = profile.get("targetOs")
+    required_os = current.get("targetOs")
+    if required_os not in {None, "other"} and target_os != required_os:
+        raise DeploymentKitError(
+            f"Target profile {target_profile} uses targetOs={target_os}; environment {environment} requires {required_os}."
+        )
+
+    state = current.get("bindingState")
+    existing_target = current.get("targetProfile")
+    production = role == "production"
+    authorization = (
+        PROJECT_PRODUCTION_TOPOLOGY_WRITE_PHRASE
+        if production
+        else PROJECT_TOPOLOGY_WRITE_PHRASE
+    )
+
+    before = deepcopy(current)
+    if state == "configured":
+        if existing_target != target_profile:
+            raise DeploymentKitError(
+                f"Environment {environment} is already configured for target {existing_target}; "
+                "rebinding requires a separate explicit topology-change contract."
+            )
+        return {
+            "status": "already-bound",
+            "projectRoot": str(path.parent),
+            "path": str(path),
+            "environment": environment,
+            "production": production,
+            "targetProfile": target_profile,
+            "targetOs": target_os,
+            "before": before,
+            "after": deepcopy(current),
+            "changedFields": [],
+            "requiredAuthorization": None,
+            "expectedTopologySha256": _topology_sha(raw),
+            "mutated": False,
+        }
+    if state != "deferred":
+        raise DeploymentKitError(
+            f"Environment {environment} has unsupported bindingState={state}; expected deferred or configured."
+        )
+    if existing_target is not None:
+        raise DeploymentKitError(
+            f"Deferred environment {environment} unexpectedly already contains targetProfile={existing_target}."
+        )
+
+    after = deepcopy(current)
+    after["bindingState"] = "configured"
+    after["targetProfile"] = target_profile
+
+    return {
+        "status": "bind",
+        "projectRoot": str(path.parent),
+        "path": str(path),
+        "environment": environment,
+        "production": production,
+        "targetProfile": target_profile,
+        "targetOs": target_os,
+        "targetSummary": {
+            "targetName": profile.get("targetName"),
+            "targetOs": target_os,
+            "hostName": profile.get("hostName"),
+            "sshAlias": profile.get("sshAlias"),
+        },
+        "before": before,
+        "after": after,
+        "changedFields": ["bindingState", "targetProfile"],
+        "requiredAuthorization": authorization,
+        "expectedTopologySha256": _topology_sha(raw),
+        "mutated": False,
+    }
+
+
+def apply_environment_binding(plan: dict[str, Any]) -> dict[str, Any]:
+    """Apply exactly one previously previewed deferred binding, refusing stale topology state."""
+
+    if plan.get("status") == "already-bound":
+        return {
+            "status": "already-bound",
+            "environment": plan.get("environment"),
+            "targetProfile": plan.get("targetProfile"),
+            "production": bool(plan.get("production")),
+            "path": plan.get("path"),
+            "mutated": False,
+        }
+    required = {
+        "projectRoot",
+        "environment",
+        "targetProfile",
+        "before",
+        "after",
+        "expectedTopologySha256",
+        "requiredAuthorization",
+    }
+    if plan.get("status") != "bind" or any(key not in plan for key in required):
+        raise DeploymentKitError("Project topology binding plan is malformed.")
+
+    path, raw, topology = _read_topology(plan["projectRoot"])
+    if _topology_sha(raw) != plan["expectedTopologySha256"]:
+        raise DeploymentKitError(
+            "Project deployment topology changed after preview; re-run the binding plan before writing."
+        )
+    index, current = _environment(topology, plan["environment"])
+    if current != plan["before"]:
+        raise DeploymentKitError(
+            "Selected environment changed after preview; re-run the binding plan before writing."
+        )
+
+    updated = deepcopy(topology)
+    updated["environments"][index] = deepcopy(plan["after"])
+    temp = path.with_name(path.name + ".tmp")
+    if temp.is_symlink():
+        raise DeploymentKitError(f"Refusing to write project topology through a symbolic link: {temp}")
+    try:
+        temp.write_text(json.dumps(updated, indent=2) + "\n", encoding="utf-8")
+        temp.replace(path)
+    except (OSError, UnicodeError) as error:
+        raise DeploymentKitError(f"Cannot persist project deployment topology {path}: {error}") from error
+
+    _, _, reread = _read_topology(plan["projectRoot"])
+    _, bound = _environment(reread, plan["environment"])
+    if bound != plan["after"]:
+        raise DeploymentKitError("Project deployment topology write did not persist the reviewed environment binding.")
+
+    return {
+        "status": "bound",
+        "environment": plan["environment"],
+        "targetProfile": plan["targetProfile"],
+        "production": bool(plan.get("production")),
+        "bindingState": "configured",
+        "path": str(path),
+        "mutated": True,
+    }