Skip to content

Commit b4f4ed1

Browse files
author
npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d
committed
docs(remote-agents): create-intent divergence has two sources, not one
Dawn's post-sign-off precision correction, seconded by Wren (non-blocking; both hold 9/9/9): "age resets only on a user-initiated config change" overclaimed. The fingerprint includes the resolved image reference, and for users who never set `image` that resolves to the digest the provider bakes at compile time — so a provider upgrade changes the computed intent with no user action. The divergence row now names both sources — user config change, and provider upgrade moving the baked default digest — and states why the second is deliberate (a fingerprint blind to the default resolution could never replace a pod wedged by a bad baked default: unpullable digest, wrong arch — exactly the population that cannot override `image`) and its bounded cost (an upgrade mid-cold-pull discards in-flight startup progress; not age-driven or periodic, so no autoscaler-livelock shape). Conformance: default-digest-change case added to the third family. Co-authored-by: npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz> Signed-off-by: npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz>
1 parent b72698b commit b4f4ed1

1 file changed

Lines changed: 5 additions & 2 deletions

File tree

‎docs/remote-agents.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -548,7 +548,7 @@ observation; on any conflict, *re-enter from step 1* rather than fail:
548548
| live and **started** (harness container running) | **strict no-op; return existing `agent_id`** | Start must never silently kill a live agent mid-turn; "already running" is the honest answer, consistent with I3 |
549549
| exists but **never started**, provably non-recoverable — referenced Secret confirmed absent (by a consistent read, below), or invalid image reference | delete (preconditioned, below), wait for disappearance, re-enter (→ create) | a pod whose harness never ran is not a live agent: nothing can be killed mid-turn (I3), it never held the identity (I4), auto-stop cannot bound it (I5's reaper lives in the harness), and no-op'ing it would return a permanently inert instance as success on every future Start. "Provably" means the provider verified the referenced object's absence or the spec-level defect itself — never a reason string alone |
550550
| exists, **never started**, recoverable, **fingerprint matches** current desired create intent (below) — self-healable startup states: `Unschedulable` (scale-from-zero autoscaling), image pull / `ImagePullBackOff`, transient `CreateContainerConfigError` | observe until started or the operation deadline expires, then return the latest redacted condition — **never delete, on this call or any later one** | these states routinely self-heal — an autoscaler provisions the node, the pull retries, the kubelet re-resolves the Secret (it retries a never-created container regardless of `restartPolicy`). And recoverable-timeout MUST stay observational *across calls*: any finite pod-age threshold can collide with the cluster's own pod-age thresholds (Cluster Autoscaler's `--new-pod-scale-up-delay` / per-pod `pod-scale-up-delay` annotation — the FAQ's example is `"600s"`), and delete-recreate resets exactly the age the autoscaler keys on, converting a slow cold start into a livelock in which every individual decision is correct. A later deploy re-reads: started → strict no-op; still recoverable and same intent → observe under the new call's deadline without resetting pod age; provably non-recoverable → the non-recoverable row. Repeated **identical** Starts can therefore never delete anything, whatever the pod's age — a genuinely slow cluster persists until it heals or an operator acts, and M1 already makes substrate residue the operator's boundary |
551-
| exists, **never started**, recoverable, **fingerprint differs or absent** — the recorded create-intent fingerprint does not match what *this* deploy would create | delete (preconditioned, below), wait for disappearance, re-enter (→ create) | this is not the same generation the user is waiting on — it is a pod built from configuration the user has since *changed*, and without this row the change can never materialize: the pod name is deterministic, GC only reaps terminated pods, Stop needs a live harness, I5's reaper lives in the harness, and there is no `undeploy` — so a never-started pod wedged by its own config (a `memory_request` no node satisfies, a quota-blocked namespace) would swallow every future edit while reporting only "startup not confirmed", indistinguishable from a slow cluster. Divergence is evidence, not a clock: age resets only on a user-initiated config change, which genuinely is a new pod spec — no threshold exists to collide with the autoscaler. A **started** pod is never touched by this row: live → strict no-op regardless of divergence (edits reach it via the documented next-generation consequence) |
551+
| exists, **never started**, recoverable, **fingerprint differs or absent** — the recorded create-intent fingerprint does not match what *this* deploy would create | delete (preconditioned, below), wait for disappearance, re-enter (→ create) | this is not the same generation the user is waiting on — it is a pod built from configuration the user has since *changed*, and without this row the change can never materialize: the pod name is deterministic, GC only reaps terminated pods, Stop needs a live harness, I5's reaper lives in the harness, and there is no `undeploy` — so a never-started pod wedged by its own config (a `memory_request` no node satisfies, a quota-blocked namespace) would swallow every future edit while reporting only "startup not confirmed", indistinguishable from a slow cluster. Divergence is evidence, not a clock — but it has **two** sources, not one: a user config change, and a provider upgrade that moves the baked default image digest (§K8s image; the default is compile-time provider state, so upgrading the provider changes the computed intent with no user action). Both are deliberate: the second is the *only* escape from a wedge caused by a bad baked default (unpullable digest, wrong arch) — a fingerprint blind to the default resolution would hand that wedge back to exactly the population that cannot override `image`. The accepted cost is that a provider upgrade mid-cold-pull discards in-flight startup progress; neither source is clocked to anything the cluster keys on, so no threshold exists to collide with the autoscaler. A **started** pod is never touched by this row: live → strict no-op regardless of divergence (edits reach it via the documented next-generation consequence) |
552552

553553
**Startup is part of create — phase is not readiness.** `Pending` (and even
554554
`Running` at the pod level) does not mean the harness started: a pod can sit
@@ -1215,7 +1215,10 @@ winner adoption, never treated as a failed delete; identical desired
12151215
intent + permanently-Pending pod → no delete across arbitrarily many
12161216
Starts, regardless of age; a resource/image correction against a
12171217
never-started pod → fingerprint differs, preconditioned
1218-
delete-and-recreate (the wedge-escape case); the same correction against
1218+
delete-and-recreate (the wedge-escape case); same user config but the
1219+
provider's **baked default image digest** changed (provider upgrade)
1220+
against a never-started pod → divergence, replace (the second intent
1221+
source — the only escape from a bad-default-image wedge); the same correction against
12191222
a **started** pod → strict zero-mutation no-op; admission
12201223
defaulting/mutating the live pod → no false divergence (the comparison
12211224
uses the recorded annotation); the fingerprint serializer property,

0 commit comments

Comments
 (0)