ADFA-4128: 0902 review round on quickbuild:core deploy/reload

Non-blocking items from Akash's 2 September round; the PR itself is approved.

- Two sibling docs still stated a "restart closure" rule the policy does not
  implement. Both now say what DeployPolicy does - a declared restart-sensitive
  component restarts every code-bearing deploy - and the stale-helpers notice
  says which deploys can still reach it.
  #1718 (comment)
- An ask is no longer reported as AWAITS_DEPLOY without checking that a deploy
  is actually still coming. Every path that declines to start a build leaves
  the work queued, so this changes no outcome today; it stops a future early
  return from dropping the tap silently instead.
  #1718 (comment)
- installPriorityHold releases the hold it replaces, which is what its KDoc
  already promised.
  #1718 (comment)
- Dropped an unused import ktlint's substring match cannot see.
  #1718 (comment)
- RetainedPayloadStore's KDoc claims the last deploy's own parts rather than a
  cumulative set, which is what retain writes.
  #1718 (comment)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017o3nPrBbGi2XYkMUGavG2A

Author: fryanpan

quickbuild/core/src/main/java/org/appdevforall/cotg/quickbuild/domain/reload/ComponentInfo.kt

@@ -27,12 +27,12 @@ enum class ComponentKind {
 }
 
 /**
- * The kinds whose live instance a loader swap cannot update, so a recompile inside their
- * restart closure forces a process restart ([DeployPolicy]).
+ * The kinds whose live instance a loader swap cannot update, so an app that DECLARES one
+ * restarts the process on every code-bearing deploy ([DeployPolicy]).
  *
  * One home for the set, because two rules key off it: the restart decision, and the
- * [org.appdevforall.cotg.quickbuild.domain.session.QuickBuildNotice.STALE_COMPONENT_HELPERS] warning that fires when one of these merely
- * EXISTS and the deploy hot-swapped instead. Both read it through [isRestartSensitive], which
+ * [org.appdevforall.cotg.quickbuild.domain.session.QuickBuildNotice.STALE_COMPONENT_HELPERS] warning that fires when one of these
+ * exists and the deploy hot-swapped anyway. Both read it through [isRestartSensitive], which
  * also applies the [COGO_INJECTED_COMPONENTS] exemption.
  */
 val RESTART_SENSITIVE_KINDS: Set<ComponentKind> =

quickbuild/core/src/main/java/org/appdevforall/cotg/quickbuild/domain/reload/LiveReloadOrchestrator.kt

@@ -219,17 +219,17 @@ class LiveReloadOrchestrator(
 					// names why, so only a forced blind rebuild repairs it.
 					markBatchArrivalLocked()
 					pendingForced = true
-					outcome = LiveReloadRequestOutcome.AWAITS_DEPLOY
 					maybeStartBuildLocked(events)
+					outcome = deployAnsweringOutcomeLocked()
 				}
 
 				!pending.isEmpty -> {
 					// Accumulated work: build it now, routed by the classifier as any save
 					// would be; the deploy answers the tap.
 					markBatchArrivalLocked()
 					pendingUserInitiated = true
-					outcome = LiveReloadRequestOutcome.AWAITS_DEPLOY
 					maybeStartBuildLocked(events)
+					outcome = deployAnsweringOutcomeLocked()
 				}
 
 				expectChanges -> {
@@ -254,6 +254,23 @@ class LiveReloadOrchestrator(
 		return outcome
 	}
 
+	/**
+	 * Whether a deploy is still coming for the ask just recorded, read after the build attempt.
+	 *
+	 * [maybeStartBuildLocked] can decline to start one - a build already in flight, a proxy app
+	 * rebuild absorbing the set, a route the live reload path hands off as an invalidation - and
+	 * the outcome was AWAITS_DEPLOY regardless, which promises the caller a deploy that may never
+	 * come. Every one of those declines leaves the work queued for a later build, so the promise
+	 * holds today; asserting it here is what keeps a future early return from silently dropping
+	 * the tap instead.
+	 */
+	private fun deployAnsweringOutcomeLocked(): LiveReloadRequestOutcome =
+		if (inFlight != null || !pending.isEmpty || pendingForced) {
+			LiveReloadRequestOutcome.AWAITS_DEPLOY
+		} else {
+			LiveReloadRequestOutcome.SWITCH_NOW
+		}
+
 	/**
 	 * Disarms a tap still waiting for its save-all's watcher batch and says whether it was
 	 * waiting - the deadline half of the arm-on-batch tap protocol.

quickbuild/core/src/main/java/org/appdevforall/cotg/quickbuild/domain/session/QuickBuildNotice.kt

@@ -27,9 +27,11 @@ enum class QuickBuildNotice {
 	 * `Application`, so an instance of one keeps calling the PREVIOUS copies of the helper
 	 * classes this build recompiled until it restarts.
 	 *
-	 * Not a failure: the deploy worked and the recreated activity runs the new code. The restart
-	 * closure covers a component's own code and its supertypes, and a hit there restarts the
-	 * process; what it cannot see is a helper class the component merely calls.
+	 * Not a failure: the deploy worked and the recreated activity runs the new code. A declared
+	 * restart-sensitive component normally makes every code-bearing deploy a restart, so this
+	 * only fires where one did not - a baseline whose runtime cannot honour the restart request.
+	 * The stale copies are then the helper classes the live component calls, which no restart
+	 * decision inspects.
 	 */
 	STALE_COMPONENT_HELPERS,
 

quickbuild/core/src/main/java/org/appdevforall/cotg/quickbuild/service/deploy/DeployChannel.kt

@@ -8,7 +8,6 @@ import kotlinx.coroutines.async
 import kotlinx.coroutines.coroutineScope
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.withTimeoutOrNull
-import org.appdevforall.cotg.quickbuild.service.telemetry.report
 import org.slf4j.LoggerFactory
 import java.io.File
 

quickbuild/core/src/main/java/org/appdevforall/cotg/quickbuild/service/deploy/ProxyAppConnections.kt

@@ -61,6 +61,9 @@ class ProxyAppConnections {
 	 * @param hold the hold to take on connect and drop on disconnect or session end
 	 */
 	fun installPriorityHold(hold: ProxyAppPriorityHold) {
+		// The KDoc promises replacement, so the one being replaced has to be dropped: keeping it
+		// would hold a gone proxy app out of the freezer for the rest of the process's life.
+		if (priorityHold !== hold) priorityHold?.release()
 		priorityHold = hold
 	}
 

quickbuild/core/src/main/java/org/appdevforall/cotg/quickbuild/service/deploy/RetainedPayloadStore.kt

@@ -10,9 +10,11 @@ import java.io.File
  * below the deployed generation can be answered by re-sending them at their original
  * generation (concurrency.md rules 3-4) instead of by a forced blind rebuild.
  *
- * Payloads are cumulative over their baseline, so the last-deployed set alone brings a
- * same-baseline app fully current. The bytes are copied because the executor's own artifacts
- * (the daemon's dex, the staged assets zip) are overwritten by the next build.
+ * What is kept is the LAST deploy's own parts, not a cumulative union: a re-send therefore
+ * brings a same-baseline app current only where that deploy's parts already covered it, and
+ * whether every consumer needs more than that is the reconnect re-send's question, not this
+ * store's. The bytes are copied because the executor's own artifacts (the daemon's dex, the
+ * staged assets zip) are overwritten by the next build.
  *
  * Everything here is best-effort by contract: a failed [retain] or an unreadable [load] only
  * costs the caller its fallback - the forced catch-up build - never a build result. Call only