docs(deployment): reconcile delete-from-NotDeployed — spec matrix now matches deliberate code (#31, M2.17)

git blame shows commit 1d5465f3 deliberately added NotDeployed to CanDelete so an
undeployed instance can have its orphan record fully removed. Code + tests already
permit it; the spec matrix said 'No'. Per M2.17, reconcile doc→code (not the reverse):
matrix now reads 'Delete from Not deployed = Yes (removes the orphan record)' with a
note, and CanDelete carries a remark citing the rationale + origin commit.
This commit is contained in:
Joseph Doherty
2026-06-16 07:24:57 -04:00
parent c9244d8bda
commit c1043569f6
2 changed files with 16 additions and 1 deletions
@@ -84,7 +84,14 @@ All mutating operations on a single instance (deploy, disable, enable, delete) s
|---------------|--------|---------|--------|--------|
| Enabled | Yes | Yes | No (already enabled) | Yes |
| Disabled | Yes (enables on apply) | No (already disabled) | Yes | Yes |
| Not deployed | Yes (initial deploy) | No | No | No |
| Not deployed | Yes (initial deploy) | No | No | Yes (removes the orphan record) |
> **Delete from Not deployed:** permitted so an instance that was previously
> undeployed (state `NotDeployed`) can have its record fully removed —
> deployment history, snapshot, attribute/alarm overrides, and connection
> bindings — rather than lingering as an unremovable orphan. There is no live
> site configuration to tear down in this state, so the delete is a
> central-side record cleanup (no site round-trip required).
## System-Wide Artifact Deployment Failure Handling
@@ -37,6 +37,14 @@ public static class StateTransitionValidator
/// <summary>Returns true when a delete operation is allowed from the given state.</summary>
/// <param name="currentState">The current instance state.</param>
/// <returns><see langword="true"/> if delete is permitted; otherwise <see langword="false"/>.</returns>
/// <remarks>
/// Delete is allowed from <see cref="InstanceState.NotDeployed"/> by design: an
/// undeployed instance would otherwise linger as an unremovable orphan record.
/// Delete from <c>NotDeployed</c> is a central-side record cleanup (no live site
/// config to tear down). This matches the state-transition matrix in
/// Component-DeploymentManager.md ("Delete from Not deployed = Yes") — reconciled
/// in M2.17 (#31); the deliberate behaviour was introduced in commit 1d5465f3.
/// </remarks>
public static bool CanDelete(InstanceState currentState) =>
currentState is InstanceState.NotDeployed or InstanceState.Enabled or InstanceState.Disabled;