@namzu/sandbox 14.0.0 → 15.0.0

package/dist/backends/kubernetes/lease.js

@@ -16,36 +16,48 @@
  *
  * One `setTimeout` chained per tick, never `setInterval`: a renewal PATCH
  * that takes longer than the interval must not queue a second one behind
- * it. The interval is HALF the TTL, so a single failed tick still leaves a
- * whole half-TTL of headroom for the next one to succeed, and it is
- * jittered ±10% so a hundred handles acquired in the same second do not
- * PATCH the API server in the same millisecond forever after.
+ * it. On SUCCESS the interval is HALF the TTL, jittered ±10% so a hundred
+ * handles acquired in the same second do not PATCH the API server in the
+ * same millisecond forever after.
  *
  * The timer is `unref`'d: a host process that has finished its work should
  * exit, not linger because a sandbox handle is still counting. A handle
  * nobody destroyed then expires on the cluster's clock exactly as an
  * abandoned one does, which is the behaviour the TTL exists for.
  *
+ * ## A failed tick does not wait for the next half-TTL
+ *
+ * Waiting a full half-TTL before retrying a FAILED renewal means one blip at
+ * exactly the wrong moment is a coin flip against the object's own
+ * `shutdownTime`: the retry and the expiry are both roughly a TTL after the
+ * last success, so a single failure can lose that race. A failed tick
+ * instead retries on capped exponential backoff — starting at one second,
+ * doubling, capped at whichever is smaller of thirty seconds or a
+ * twentieth of the TTL — so an outage around a scheduled renewal gets many
+ * attempts inside the window that actually matters, not one. Every success
+ * resets the backoff and returns the loop to the normal half-TTL cadence.
+ *
  * ## Every tick is bounded
  *
- * A renewal that FAILS is survivable — it is reported and retried with half
- * a TTL of headroom. A renewal that HANGS is not: the next tick is scheduled
+ * A renewal that FAILS is survivable — it is reported and retried on a
+ * short backoff. A renewal that HANGS is not: the next tick is scheduled
  * only after the current one settles, so a PATCH that never answers parks
  * the loop forever, reports nothing, and lets the lease expire in silence —
  * precisely the defect this file exists to close, moved onto the failure
  * path. An API server that accepts a connection and then never responds is
  * an ordinary cluster event, so each PATCH runs under its own deadline: it
  * aborts the request through the signal the client already takes, and an
- * expiry is then just another reported failure that retries on the next
- * tick.
+ * expiry is then just another reported failure that retries on backoff.
  *
  * ## What each outcome means
  *
- *  - Success → the object's expiry moves a full TTL into the future.
+ *  - Success → the object's expiry moves a full TTL into the future, the
+ *    backoff resets, and the next tick is a half-TTL away again.
  *  - Any error, a tick that ran out of time included → reported to
- *    `onRenewalError` and RETRIED on the next tick. A transient API blip
- *    must not tear down a working sandbox, and there is still half a TTL of
- *    headroom.
+ *    `onRenewalError` and RETRIED on a backoff far shorter than the
+ *    half-TTL interval. A transient API blip must not tear down a working
+ *    sandbox, and the loop keeps trying rather than spend the object's
+ *    remaining headroom waiting.
  *  - Already gone (404/410) → the object this handle owns no longer exists.
  *    Nothing will bring it back, so the loop stops and the handle is marked
  *    gone; every later call fails with a named error instead of dialing an
@@ -59,6 +71,21 @@ import { KubernetesAlreadyGoneError } from './k8s-client.js';
  * derived quarter-interval would otherwise be 7.5 minutes of silence.
  */
 const MAX_RENEWAL_TIMEOUT_MS = 30_000;
+/**
+ * The floor of the retry backoff after a failed renewal: one second. Far
+ * short of the half-TTL interval, on purpose — a failure needs another
+ * chance long before the object's `shutdownTime` is at risk, not after
+ * waiting as long as a successful tick would have.
+ */
+const RETRY_BACKOFF_FLOOR_MS = 1_000;
+/**
+ * The ceiling of the retry backoff, whichever is smaller: thirty seconds, or
+ * a twentieth of the TTL. The TTL fraction keeps a short-TTL sandbox (tests,
+ * mainly) from retrying so slowly that the backoff alone could still lose
+ * the race against expiry; thirty seconds keeps an hour-plus TTL from
+ * retrying needlessly often once the ceiling is reached.
+ */
+const MAX_RETRY_BACKOFF_MS = 30_000;
 /** ±10%: enough to spread a synchronised fleet, far too little to matter
  * against a half-TTL of headroom. */
 const JITTER_FRACTION = 0.1;
@@ -78,13 +105,20 @@ export class KubernetesLeaseRenewal {
     started = false;
     baseIntervalMs;
     patchTimeoutMs;
+    retryBackoffCapMs;
     random;
+    /**
+     * Non-gone failures since the last success (or since the loop started).
+     * Reset to 0 by every success; drives how far the next retry backs off.
+     */
+    consecutiveFailures = 0;
     constructor(options) {
         this.options = options;
         this.baseIntervalMs = options.intervalMs ?? Math.max(1, (options.ttlSeconds * 1_000) / 2);
         this.patchTimeoutMs =
             options.patchTimeoutMs ??
                 Math.max(1, Math.min(MAX_RENEWAL_TIMEOUT_MS, Math.round(this.baseIntervalMs / 4)));
+        this.retryBackoffCapMs = Math.max(1, Math.min(MAX_RETRY_BACKOFF_MS, (options.ttlSeconds * 1_000) / 20));
         this.random = options.random ?? Math.random;
     }
     /**
@@ -101,7 +135,7 @@ export class KubernetesLeaseRenewal {
         if (this.stopped || this.timer !== undefined)
             return;
         this.started = true;
-        this.schedule();
+        this.scheduleNext(this.baseIntervalMs);
     }
     stop() {
         this.stopped = true;
@@ -110,16 +144,27 @@ export class KubernetesLeaseRenewal {
             this.timer = undefined;
         }
     }
-    schedule() {
+    scheduleNext(baseMs) {
         if (this.stopped)
             return;
         const timer = setTimeout(() => {
             void this.tick();
-        }, jitteredInterval(this.baseIntervalMs, this.random));
+        }, jitteredInterval(baseMs, this.random));
         // A pending renewal must never be the reason a host process stays up.
         timer.unref?.();
         this.timer = timer;
     }
+    /**
+     * The delay before the NEXT retry after a non-gone failure: capped
+     * exponential backoff from {@link RETRY_BACKOFF_FLOOR_MS}, doubling on
+     * every consecutive failure, ceilinged at {@link retryBackoffCapMs}.
+     * Called only once `consecutiveFailures` has already been incremented for
+     * the failure that just happened, so the first retry uses the floor.
+     */
+    retryDelayMs() {
+        const doubled = RETRY_BACKOFF_FLOOR_MS * 2 ** (this.consecutiveFailures - 1);
+        return Math.min(this.retryBackoffCapMs, doubled);
+    }
     /** Exposed for tests: one renewal attempt plus its scheduling decision. */
     async tick() {
         this.timer = undefined;
@@ -141,11 +186,16 @@ export class KubernetesLeaseRenewal {
                 return;
             }
             // Everything else is transient until proven otherwise: report it
-            // and try again on the next tick, which is still half a TTL
-            // before anything expires.
+            // and retry on a backoff far shorter than the half-TTL interval —
+            // a coin-flip race against the object's own expiry is exactly what
+            // this file exists to avoid.
+            this.consecutiveFailures += 1;
             this.options.onRenewalError?.(error);
+            this.scheduleNext(this.retryDelayMs());
+            return;
         }
-        this.schedule();
+        this.consecutiveFailures = 0;
+        this.scheduleNext(this.baseIntervalMs);
     }
 }
 //# sourceMappingURL=lease.js.map

package/dist/backends/kubernetes/lease.js.map

@@ -1 +1 @@
-{"version":3,"file":"lease.js","sourceRoot":"","sources":["../../../src/backends/kubernetes/lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAA;AAwC5D;;;;GAIG;AACH,MAAM,sBAAsB,GAAG,MAAM,CAAA;AAErC;qCACqC;AACrC,MAAM,eAAe,GAAG,GAAG,CAAA;AAE3B,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,MAAoB;IACpE,MAAM,MAAM,GAAG,CAAC,GAAG,eAAe,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,eAAe,CAAC,CAAA;IACrE,uEAAuE;IACvE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAA;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,sBAAsB;IAQL;IAPrB,KAAK,CAA2C;IAChD,OAAO,GAAG,KAAK,CAAA;IACf,OAAO,GAAG,KAAK,CAAA;IACN,cAAc,CAAQ;IACtB,cAAc,CAAQ;IACtB,MAAM,CAAc;IAErC,YAA6B,OAA4B;QAA5B,YAAO,GAAP,OAAO,CAAqB;QACxD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,UAAU,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;QACzF,IAAI,CAAC,cAAc;YAClB,OAAO,CAAC,cAAc;gBACtB,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,sBAAsB,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QACnF,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAA;IAC5C,CAAC;IAED;;;;;;OAMG;IACH,IAAI,MAAM;QACT,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAA;IACrC,CAAC;IAED,KAAK;QACJ,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,OAAM;QACpD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QACnB,IAAI,CAAC,QAAQ,EAAE,CAAA;IAChB,CAAC;IAED,IAAI;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QACnB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC9B,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACxB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAA;QACvB,CAAC;IACF,CAAC;IAEO,QAAQ;QACf,IAAI,IAAI,CAAC,OAAO;YAAE,OAAM;QACxB,MAAM,KAAK,GAAG,UAAU,CACvB,GAAG,EAAE;YACJ,KAAK,IAAI,CAAC,IAAI,EAAE,CAAA;QACjB,CAAC,EACD,gBAAgB,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,CAClD,CAAA;QACD,sEAAsE;QACtE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAA;QACf,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACnB,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,IAAI;QACT,IAAI,CAAC,KAAK,GAAG,SAAS,CAAA;QACtB,IAAI,IAAI,CAAC,OAAO;YAAE,OAAM;QACxB,MAAM,YAAY,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,GAAG,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;QACzF,IAAI,CAAC;YACJ,kEAAkE;YAClE,mEAAmE;YACnE,mEAAmE;YACnE,mEAAmE;YACnE,mDAAmD;YACnD,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,cAAc,EAAE,0BAA0B,CAAC,CAAC,GAAG,CAC/E,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,MAAM,CAAC,CAChE,CAAA;QACF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,KAAK,YAAY,0BAA0B,EAAE,CAAC;gBACjD,IAAI,CAAC,IAAI,EAAE,CAAA;gBACX,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAA;gBACrB,OAAM;YACP,CAAC;YACD,iEAAiE;YACjE,4DAA4D;YAC5D,2BAA2B;YAC3B,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,KAAK,CAAC,CAAA;QACrC,CAAC;QACD,IAAI,CAAC,QAAQ,EAAE,CAAA;IAChB,CAAC;CACD"}
+{"version":3,"file":"lease.js","sourceRoot":"","sources":["../../../src/backends/kubernetes/lease.ts"],"names":[],"mappings":"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"}

package/dist/backends/kubernetes/objects.d.ts

@@ -33,6 +33,25 @@ export interface KubernetesObjectMeta {
     readonly name?: string;
     readonly namespace?: string;
     readonly uid?: string;
+    /**
+     * RFC 3339, written by the API server on admission and never by a client.
+     * Read only to report how old a workspace is — see
+     * `workspace.ts`'s `listKubernetesWorkspaces`.
+     */
+    readonly creationTimestamp?: string;
+    /**
+     * The object's version as this read saw it, written by the API server on
+     * every write and never by a client.
+     *
+     * It is here for exactly one use and no other: the fallback `test` clause
+     * of a holder-epoch patch aimed at an object that does not carry the
+     * annotation yet, and the `preconditions.resourceVersion` of a fenced
+     * DELETE — both INSIDE the one read-write pair that read it. It is never
+     * stored on a handle, never carried across calls and never streamed, so
+     * the "no watch, no informers, no resourceVersion tracking" invariant
+     * `k8s-client.ts` states still holds. See {@link buildHolderEpochPatch}.
+     */
+    readonly resourceVersion?: string;
     /**
      * Set the moment a DELETE is accepted, long before the object goes away.
      * A pod that carries one is on its way out and must never be bound to —
@@ -86,12 +105,28 @@ export interface SandboxClaimLifecycle {
  * absent from this type: setting either forces the claim to cold-start rather
  * than adopt a warm pool sandbox, which is the one thing the warm path exists
  * to avoid. A field that cannot be named cannot be set by accident.
+ *
+ * `additionalPodMetadata` is the exception, and the reason the rule above is
+ * about COLD STARTS rather than about claim-time metadata in general: labels
+ * are merged into an adopted warm sandbox without one. Measured on
+ * agent-sandbox v1.0.2 — two claims out of one two-replica pool, each
+ * carrying a different label value, both binding a replica that already
+ * existed, and the controller patching the label onto the running pod and
+ * into the Sandbox's own podTemplate. See `egress-policy.ts`'s profile
+ * support.
  */
 export interface SandboxClaimResourceSpec {
     readonly warmPoolRef: {
         readonly name: string;
     };
     readonly lifecycle?: SandboxClaimLifecycle;
+    /**
+     * Labels (and annotations, which this backend never sets) the controller
+     * merges onto the pod it binds. Warm-safe — see the type comment.
+     */
+    readonly additionalPodMetadata?: {
+        readonly labels?: Readonly<Record<string, string>>;
+    };
 }
 /**
  * `SandboxClaim.status`. `sandbox` is the whole reason the claim path reads
@@ -113,6 +148,33 @@ export interface SandboxClaimResource {
     readonly spec?: SandboxClaimResourceSpec;
     readonly status?: SandboxClaimResourceStatus;
 }
+/**
+ * A `GET` of the claims COLLECTION. Read by `readKubernetesTaskCapacity` (a
+ * count) and `releaseKubernetesTaskSandboxes` (the names to `DELETE`) — both
+ * in `index.ts`. Same "no watch, no `continue`" shape as
+ * {@link SandboxListResource}, for the same reason: this backend does no
+ * watch at all.
+ */
+export interface SandboxClaimListResource {
+    readonly items?: readonly SandboxClaimResource[];
+}
+/**
+ * `SandboxWarmPool.spec`/`.status`, read by `readKubernetesTaskCapacity`
+ * alone — the first place in this backend that reads a `SandboxWarmPool`
+ * rather than only naming one in a claim's `warmPoolRef`. Partial in the
+ * same way every other shape here is: `replicas` and `readyReplicas` are the
+ * two fields a capacity read needs, off the exact same object
+ * `k8s/scripts/acquire-p50.mjs` already polls by hand.
+ */
+export interface SandboxWarmPoolResource {
+    readonly metadata?: KubernetesObjectMeta;
+    readonly spec?: {
+        readonly replicas?: number;
+    };
+    readonly status?: {
+        readonly readyReplicas?: number;
+    };
+}
 /**
  * `podTemplate` on a Sandbox or a SandboxTemplate. `spec` is a core `PodSpec`,
  * carried opaquely: this backend copies one from a template into a Sandbox and
@@ -178,6 +240,16 @@ export interface SandboxResource {
     readonly spec?: SandboxResourceSpec;
     readonly status?: SandboxResourceStatus;
 }
+/**
+ * A `GET` of the sandboxes COLLECTION. `items` is the only field anything
+ * here reads: this backend does no watch, so `metadata.resourceVersion` and
+ * `continue` have nothing to feed — the namespace a deployment gives its
+ * sandboxes holds tens of objects, not the thousands that would make a page
+ * boundary a real answer rather than a truncated one.
+ */
+export interface SandboxListResource {
+    readonly items?: readonly SandboxResource[];
+}
 export interface SandboxTemplateResource {
     readonly metadata?: KubernetesObjectMeta;
     readonly spec?: {
@@ -187,16 +259,59 @@ export interface SandboxTemplateResource {
     };
 }
 /**
- * `metadata.uid` is the per-instance agent bind token; the other two fields
- * exist only to answer "is this the pod that uid belongs to, or the one being
- * deleted?" — see {@link isPodLive}.
+ * `metadata.uid` is the per-instance agent bind token; `deletionTimestamp`
+ * and `phase` exist only to answer "is this the pod that uid belongs to, or
+ * the one being deleted?" — see {@link isPodLive}.
+ *
+ * `podIP` is read by the `pod-ip` address mode only, and deliberately from
+ * the SAME object the uid comes from: an address taken from one pod and a
+ * token taken from another is the mismatch that reports as a flat
+ * `unauthorized` with nothing pointing at the pod that was replaced in
+ * between. Both spellings are carried because a dual-stack cluster fills
+ * `podIPs` and single-stack clusters have always filled `podIP`; the API
+ * server sets `podIP` to the first entry of `podIPs` on every cluster that
+ * sets either, so {@link readPodIP} prefers it and falls back.
  */
 export interface PodResource {
     readonly metadata?: KubernetesObjectMeta;
     readonly status?: {
         readonly phase?: string;
+        readonly podIP?: string;
+        readonly podIPs?: readonly {
+            readonly ip?: string;
+        }[];
+        /**
+         * `status.conditions` — read on ONE path only, and never on a healthy
+         * one: after an acquire has already run out of readiness budget,
+         * `PodScheduled=False` with reason `Unschedulable` is what separates
+         * "the cluster has no room" from "the sandbox is just slow". Nothing
+         * waits on a pod condition: `Ready` here is the kubelet's view of the
+         * container, and readiness on this backend is the Sandbox's own
+         * `Ready`, which is what {@link isConditionTrue} is called with
+         * everywhere else. See `index.ts`'s `diagnoseUnreadyPod`.
+         */
+        readonly conditions?: readonly KubernetesCondition[];
+        /**
+         * `status.containerStatuses` — read on the same one path, for the same
+         * one question. A container stuck in `waiting` with an image-pull
+         * reason is a permanent failure wearing the clothes of a slow start,
+         * and it is the only one of those this backend can name from the API.
+         */
+        readonly containerStatuses?: readonly PodContainerStatus[];
     };
 }
+/** The single `status.containerStatuses` field the diagnosis above reads. */
+export interface PodContainerStatus {
+    readonly name?: string;
+    readonly state?: {
+        readonly waiting?: {
+            readonly reason?: string;
+            readonly message?: string;
+        };
+    };
+}
+/** The pod's own address, whichever of the two fields this cluster fills. */
+export declare function readPodIP(pod: PodResource | undefined): string | undefined;
 export interface PodListResource {
     readonly items?: readonly PodResource[];
 }
@@ -258,6 +373,260 @@ export declare function isPodStopped(pod: PodResource | undefined): boolean;
  * `docs/sdk/kubernetes-sandbox.md`'s egress section.
  */
 export declare const SANDBOX_TEMPLATE_LABEL_KEY = "sandbox.namzu.ai/template";
+/**
+ * Backend-owned annotation naming when a Sandbox's `spec.operatingMode` was
+ * last changed BY THIS BACKEND, RFC 3339.
+ *
+ * It exists because nothing already on the object answers the question, and
+ * an inventory that never wakes a workspace is the reason to ask it: a
+ * retention pass deleting the workspaces nobody has resumed for a month reads
+ * this and `metadata.creationTimestamp` and nothing else.
+ *
+ * The obvious candidate is the controller's own `Suspended` condition and its
+ * `lastTransitionTime`, and upstream's `sandbox_types.go` rules it out in the
+ * same breath it documents it: "the controller does not currently remove this
+ * condition when the Sandbox is resumed", so after a resume the condition is
+ * still True and its timestamp still names the suspend that preceded it. The
+ * `Ready` condition's timestamp is no better — it moves for every pod that
+ * comes and goes, a crash-restart included, and a workspace whose pod
+ * restarted has not changed operating mode at all.
+ *
+ * So the two patches that DO change the mode stamp the moment they were sent,
+ * and the value is exactly that: the host's clock at the moment it asked, not
+ * the cluster's at the moment it applied. It is an inventory column, never a
+ * lock or an ordering, and nothing in this backend reads it back to make a
+ * decision. A Sandbox whose mode has never been changed since it was created
+ * carries no annotation at all, and is reported without one rather than with
+ * a guess.
+ *
+ * Same prefix as {@link SANDBOX_TEMPLATE_LABEL_KEY}, for the same reason.
+ */
+export declare const OPERATING_MODE_CHANGED_AT_ANNOTATION_KEY = "sandbox.namzu.ai/operating-mode-changed-at";
+/**
+ * Backend-owned annotation carrying the HOLDER EPOCH: a decimal integer the
+ * host raises whenever authority over this workspace moves to another
+ * process.
+ *
+ * A workspace id is a name, not a lock, and a host that drives one workspace
+ * from more than one process has to decide which of them may suspend, resume
+ * or delete it. Checking its own epoch and then calling `suspend()` does not
+ * close the race, because the write that follows is a separate request and
+ * the API server accepts it. So the epoch is stored HERE, on the object every
+ * lifecycle write targets, and every such write carries it as a condition in
+ * the same request — see {@link buildHolderEpochPatch}.
+ *
+ * The rule: a write carrying epoch `e` applies when the stored epoch is `<=
+ * e`, and sets the stored epoch to `e` in the same request. A stored epoch
+ * greater than `e` refuses it. An object with NO annotation reads as 0, so
+ * every workspace created before this existed accepts its first
+ * epoch-carrying write.
+ *
+ * It is the caller's number, never this backend's: nothing here invents,
+ * increments or persists an epoch of its own, and a call that passes none
+ * sends exactly the requests it always sent.
+ *
+ * Same prefix as {@link SANDBOX_TEMPLATE_LABEL_KEY} and
+ * {@link OPERATING_MODE_CHANGED_AT_ANNOTATION_KEY}, for the same reason.
+ */
+export declare const HOLDER_EPOCH_ANNOTATION_KEY = "sandbox.namzu.ai/holder-epoch";
+/**
+ * Backend-owned annotation carrying a hash of the pod template a Sandbox was
+ * last built with.
+ *
+ * A Sandbox's `spec.podTemplate` is a COPY of the SandboxTemplate's, taken
+ * once, and the controller rebuilds every replacement pod from that copy
+ * rather than from the template — so a workspace kept for weeks runs the pod
+ * spec it was created with, and an edit to the template (a new image tag, a
+ * memory limit, a grace period, an env entry) reaches only workspaces created
+ * after it. Nothing on the object answers "is this copy still the template's
+ * current one": the two are separate objects with separate
+ * `resourceVersion`s, and comparing the templates field by field on every
+ * open would be a second, weaker copy of the overlay rules.
+ *
+ * So the value is a hash of exactly what was written: the template's
+ * `podTemplate` AFTER this backend's own overlays (the template label and the
+ * configured `runtimeClassName`), which is the object the Sandbox carries.
+ * Hashing before the overlays would report drift on every workspace whose
+ * RuntimeClass this backend chose.
+ *
+ * Written by the workspace paths only — the create POST and the refresh patch
+ * — and read back as `templateRevision` on a handle. A task sandbox is
+ * ephemeral and has nothing to drift from, so its create body is unchanged.
+ * A workspace created before this existed carries no annotation and reports
+ * `templateRevision: undefined`, which reads honestly as "unknown", never as
+ * "current".
+ *
+ * Same prefix as {@link SANDBOX_TEMPLATE_LABEL_KEY}, for the same reason.
+ */
+export declare const POD_TEMPLATE_HASH_ANNOTATION_KEY = "sandbox.namzu.ai/pod-template-hash";
+/**
+ * `sha256:<hex>` over the pod template, for
+ * {@link POD_TEMPLATE_HASH_ANNOTATION_KEY}.
+ *
+ * It is an identity, not a checksum of anything security-relevant: two hosts
+ * running the same release against the same template must compute the same
+ * string, and a template edit must change it. Nothing here compares it
+ * against a value an untrusted party chose.
+ */
+export declare function podTemplateHash(podTemplate: SandboxPodTemplate): string;
+/**
+ * One RFC 6902 operation, in the only three shapes this backend sends.
+ *
+ * `test` is the condition, `add` is every mutation. `add` rather than
+ * `replace` throughout: RFC 6902 §4.1 says that on a JSON object member `add`
+ * creates the member when it is missing and replaces its value when it is
+ * present, while §4.3's `replace` fails outright on a missing one — and
+ * `spec.operatingMode` is absent on a Sandbox that has never been suspended,
+ * as is the epoch annotation on every workspace created before this release.
+ * A `replace` would turn both of those ordinary cases into a rejected patch.
+ *
+ * So where a design or an issue says the wire carries `replace /spec/…`, this
+ * is that write: on a member that is already there the two operations are the
+ * same write, and on one that is not, only this one lands.
+ */
+export interface JsonPatchOperation {
+    readonly op: 'test' | 'add';
+    readonly path: string;
+    readonly value: unknown;
+}
+/**
+ * One JSON Pointer reference token (RFC 6901 §3): `~` becomes `~0` and `/`
+ * becomes `~1`, in that order — the reverse order would turn a literal `~1`
+ * into a slash.
+ *
+ * An annotation key always contains a `/` (`sandbox.namzu.ai/holder-epoch`),
+ * so the pointer to one is unusable without this.
+ */
+export declare function escapeJsonPointerSegment(token: string): string;
+/** Pointer to one annotation on an object's own metadata. */
+export declare function annotationPointer(key: string): string;
+/** What one read of an object saw about its holder epoch. */
+export interface HolderEpochReading {
+    /**
+     * The stored epoch: the annotation parsed, or `0` when there is none.
+     *
+     * `undefined` means the annotation is PRESENT and is not a decimal
+     * integer, which no version of this backend writes. It is reported as
+     * unreadable rather than as 0 on purpose: reading a value this code does
+     * not understand as "nobody holds this workspace" would let a write
+     * overwrite a fence somebody else established, which is the one thing the
+     * annotation exists to prevent.
+     */
+    readonly epoch?: number;
+    /**
+     * The annotation exactly as stored, and the value the `test` clause
+     * carries. Absent when the object has no such annotation.
+     */
+    readonly annotation?: string;
+    /** `metadata.annotations` existed at all — decides which `add` is sent. */
+    readonly hasAnnotations: boolean;
+    /** `metadata.resourceVersion`, for the fallback `test` and a fenced DELETE. */
+    readonly resourceVersion?: string;
+}
+/** Read {@link HOLDER_EPOCH_ANNOTATION_KEY} off an object's metadata. */
+export declare function readHolderEpoch(meta: KubernetesObjectMeta | undefined): HolderEpochReading;
+/**
+ * Read {@link POD_TEMPLATE_HASH_ANNOTATION_KEY} off an object's metadata.
+ *
+ * Absent — an object created before this existed, or one an older release
+ * refreshed — is `undefined`, which reads as "unknown" everywhere it is
+ * consumed. It is deliberately never compared as an empty string: a
+ * revision nobody recorded is not a revision that differs.
+ */
+export declare function readPodTemplateHash(meta: KubernetesObjectMeta | undefined): string | undefined;
+/** A stored epoch of `epoch` or lower lets a write carrying `epoch` through. */
+export declare function holderEpochAllows(reading: HolderEpochReading, epoch: number): boolean;
+/** What {@link buildHolderEpochPatch} is asked to write, and under what condition. */
+export interface HolderEpochPatchInput {
+    /** The metadata the GET returned. The condition is built from THIS read. */
+    readonly reading: HolderEpochReading;
+    /**
+     * The epoch the write carries, and the one it stores.
+     *
+     * ABSENT is the unfenced conditional write: no epoch clause is tested and
+     * no epoch annotation is written, and {@link tests} then carries the whole
+     * condition — which is why an epoch-less call with no `tests` is refused
+     * below rather than sent unconditionally. A workspace refresh is the one
+     * caller: its condition is `spec.operatingMode`, and a host that has not
+     * opted into the fence must not acquire one by asking for a new pod
+     * template.
+     */
+    readonly epoch?: number;
+    /**
+     * Further `test` clauses composed into the SAME body.
+     *
+     * This is the seam a second condition uses instead of a second request: a
+     * write that also has to assert, say, `spec.operatingMode` passes its
+     * clause here and the object is still written under one atomic patch. Two
+     * call sites each sending their own conditional patch would be two writes
+     * and two chances to lose a race between them.
+     */
+    readonly tests?: readonly JsonPatchOperation[];
+    /** Written to `spec.operatingMode`; omitted leaves the mode alone. */
+    readonly operatingMode?: 'Running' | 'Suspended';
+    /**
+     * RFC 3339 stamp for {@link OPERATING_MODE_CHANGED_AT_ANNOTATION_KEY}.
+     * Passed only by a write that actually CHANGES the mode — the annotation
+     * says when the mode last changed, and a write that merely restamps the
+     * epoch has not changed it.
+     */
+    readonly operatingModeChangedAt?: string;
+    /**
+     * Further annotations written in the SAME body, merged with the epoch's
+     * and the mode stamp's rather than sent after them.
+     *
+     * {@link POD_TEMPLATE_HASH_ANNOTATION_KEY} is the only caller: the hash
+     * has to land with the pod template it describes, or a patch that applied
+     * half of the pair would leave the object claiming a revision it is not
+     * running.
+     */
+    readonly annotations?: Readonly<Record<string, string>>;
+    /**
+     * Written to `spec.podTemplate`, replacing it WHOLE — which is the reason
+     * this is a JSON Patch at all. A merge patch recurses into maps, so a
+     * `nodeSelector` entry the template dropped would survive in the object
+     * and the pod would keep a constraint nobody can see in the template any
+     * more.
+     */
+    readonly podTemplate?: SandboxPodTemplate;
+}
+/**
+ * The one conditional-write builder this backend has, and the only place a
+ * JSON Patch body is composed.
+ *
+ * Every clause is decided from ONE read, and the whole thing goes up as one
+ * request: the condition and the mutation are in the same body, so there is
+ * no window between checking and writing for another holder to fit into.
+ *
+ * Three shapes, decided by what that read saw:
+ *
+ *  - the object carries the epoch annotation ⇒ `test` it by its exact stored
+ *    string, then `add` the new value over it;
+ *  - the object carries annotations but not this one ⇒ `test`
+ *    `/metadata/resourceVersion` instead, then `add` the member;
+ *  - the object carries no `metadata.annotations` at all ⇒ the same
+ *    `resourceVersion` test, then `add` the map whole, because there is no
+ *    member to add one to.
+ *
+ * The `resourceVersion` fallback is the migration case and nothing more: it
+ * fires once, on a workspace created before this release, and from the first
+ * epoch write onwards the annotation is what is tested. That matters because
+ * a controller status write moves `resourceVersion` without touching the
+ * annotation, and under the annotation test those are simply not conditions
+ * this write is interested in.
+ *
+ * A call carrying NO epoch skips all three: it tests only what
+ * {@link HolderEpochPatchInput.tests} carries and writes no epoch annotation,
+ * which is how a workspace refresh conditions itself on `spec.operatingMode`
+ * without fencing a host that never asked for a fence.
+ *
+ * Every `test` precedes every mutation, which RFC 6902 requires of a
+ * condition: operations apply in order, so a `test` written after an `add`
+ * would be testing this patch's own work. Mutations go up in a fixed order —
+ * annotations, then `spec.podTemplate`, then `spec.operatingMode` — so the
+ * body a given input produces is one body and a test can assert it.
+ */
+export declare function buildHolderEpochPatch(input: HolderEpochPatchInput): readonly JsonPatchOperation[];
 /** `{ [SANDBOX_TEMPLATE_LABEL_KEY]: sandboxTemplateName }`, as a matchLabels-ready object. */
 export declare function sandboxTemplateLabel(sandboxTemplateName: string): Readonly<Record<string, string>>;
 /** Core `NetworkPolicy` — a stock resource, no CRD. */
@@ -272,11 +641,62 @@ export declare const CILIUM_NETWORK_POLICY_API_GROUP = "cilium.io";
 export declare const CILIUM_NETWORK_POLICY_API_VERSION = "v2";
 export declare function claimCollectionPath(namespace: string): string;
 export declare function claimPath(namespace: string, name: string): string;
+/** The claims collection, narrowed to a `labelSelector` — same shape as {@link podListPath}. */
+export declare function claimListPath(namespace: string, labelSelector: string): string;
+export declare function warmPoolPath(namespace: string, name: string): string;
 export declare function sandboxCollectionPath(namespace: string): string;
 export declare function sandboxPath(namespace: string, name: string): string;
 export declare function sandboxTemplatePath(namespace: string, name: string): string;
+/**
+ * The PVC the controller creates for one `volumeClaimTemplates` entry:
+ * `<entry name>-<sandbox name>`, in the Sandbox's own namespace.
+ *
+ * Written out here rather than derived at each call site because it is a
+ * NAME the controller owns, not one this backend chooses — a release that
+ * changes it breaks every read of it at once, and the one place to notice
+ * that is a function whose whole body is the convention.
+ */
+export declare function persistentVolumeClaimPath(namespace: string, sandboxName: string, claimTemplateName: string): string;
 export declare function podPath(namespace: string, name: string): string;
+/** The whole pods collection, unfiltered. Read by `readKubernetesTaskCapacity` alone. */
+export declare function podCollectionPath(namespace: string): string;
 export declare function podListPath(namespace: string, labelSelector: string): string;
+export declare function networkPolicyCollectionPath(namespace: string): string;
 export declare function networkPolicyPath(namespace: string, name: string): string;
+export declare function ciliumNetworkPolicyCollectionPath(namespace: string): string;
 export declare function ciliumNetworkPolicyPath(namespace: string, name: string): string;
+/**
+ * Core Kubernetes' own admission-policy resources — `ValidatingAdmissionPolicy`
+ * and its binding, both CLUSTER-scoped and both stock since v1.30, so a
+ * cluster that serves this group needs nothing installed.
+ *
+ * Read by exactly one caller: the per-sandbox policy fence
+ * (`per-sandbox-policy.ts`), which refuses to write a `CiliumNetworkPolicy`
+ * at all unless an operator has applied the policy that bounds what this
+ * host may write. Never written by this backend — the fence is the operator's
+ * object, reviewed by whoever has cluster-admin, and a host that could create
+ * its own fence would not have one.
+ */
+export declare const ADMISSION_REGISTRATION_API_GROUP = "admissionregistration.k8s.io";
+export declare const ADMISSION_REGISTRATION_API_VERSION = "v1";
+export declare function validatingAdmissionPolicyPath(name: string): string;
+export declare function validatingAdmissionPolicyBindingPath(name: string): string;
+/**
+ * An `ownerReferences` entry, as this backend writes it.
+ *
+ * `controller` and `blockOwnerDeletion` are deliberately ABSENT rather than
+ * written as `false`. `blockOwnerDeletion: true` would make the API server's
+ * `OwnerReferencesPermissionEnforcement` admission plugin demand `update` on
+ * the OWNER's `finalizers` subresource — a verb no Role in this repo grants
+ * and no host needs — so a field whose only legal value here is `false` is
+ * one the body is better off not carrying at all. Garbage collection does not
+ * need either field: a dependent whose owners are all gone is deleted, owning
+ * controller or not.
+ */
+export interface KubernetesOwnerReference {
+    readonly apiVersion: string;
+    readonly kind: string;
+    readonly name: string;
+    readonly uid: string;
+}
 //# sourceMappingURL=objects.d.ts.map