@namzu/sandbox 26.0.0 → 28.0.0

package/dist/backends/kubernetes/workspace-observe.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Looking at a retained workspace by its exact identity, without creating,
+ * waking or writing anything.
+ *
+ * `createKubernetesWorkspace` is create-or-adopt: handed an id it POSTs, and
+ * on a 409 adopts whatever stands there and resumes it. That is the right
+ * verb for "give me a workspace" and the wrong one for a host that restarted
+ * and wants to know whether the workspace it recorded last week is still the
+ * workspace under that name — the question has to be answered BEFORE a pod is
+ * started for what might be a stranger's disk.
+ *
+ * Three verbs, all GET-only:
+ *
+ *  - {@link inspectKubernetesWorkspace} — what is there, and who holds it.
+ *  - {@link openKubernetesWorkspace} — authenticate a retained identity, and
+ *    optionally wait, under one deadline, for its claims and its guest.
+ *  - {@link reconcileKubernetesWorkspace} — after a restart: live, suspended,
+ *    absent or replaced.
+ *
+ * ## Ownership and readiness are separate questions
+ *
+ * Ownership is decided by uids and by nothing else: the Sandbox's
+ * `metadata.uid`, each volume claim's uid, and who owns each claim. A
+ * `resourceVersion` that moved, a `Ready` condition that flipped and a
+ * condition left over from an earlier generation are the controller working,
+ * and none of them is ever read as a change of owner. Readiness is a bounded
+ * poll on top of an ownership check that runs again on every pass, so a
+ * replacement that lands while waiting is still a refusal.
+ */
+import { type KubernetesObservedAllocation, type KubernetesWorkspaceAllocation } from './allocation.js';
+import { type KubernetesWorkspaceExpectedIdentity, type KubernetesWorkspaceIdentity, type KubernetesWorkspaceIdentityMismatch } from './identity.js';
+import { type KubernetesBackendInternalConfig } from './index.js';
+/** What every verb here takes besides its own fields. */
+export interface KubernetesWorkspaceObservationOptions {
+    readonly signal?: AbortSignal;
+}
+/** {@link inspectKubernetesWorkspace}'s options. */
+export interface KubernetesWorkspaceInspectOptions extends KubernetesWorkspaceObservationOptions {
+    /**
+     * The allocation this host expects. A Sandbox under the id whose
+     * allocation annotations or copied pod template differ is refused with
+     * `KubernetesWorkspaceAllocationMismatchError`; absence still resolves
+     * `undefined`, because there is nothing to compare.
+     */
+    readonly expectedAllocation?: KubernetesWorkspaceAllocation;
+    /**
+     * The holder epoch this reader acts under. A workspace held at a HIGHER
+     * epoch refuses it with `KubernetesWorkspacePreconditionError`: a
+     * superseded host must not conclude anything about a workspace that
+     * belongs to another process now. Nothing is written either way.
+     */
+    readonly epoch: number;
+}
+/** What one read-only look at a workspace found. */
+export interface KubernetesWorkspaceInspection {
+    readonly workspaceId: string;
+    readonly sandboxName: string;
+    readonly operatingMode: 'Running' | 'Suspended';
+    /**
+     * The disk and the guest, as the cluster reports them now.
+     * `volumeClaimUids` holds the claims that exist; `podUid` is the live pod
+     * and is `undefined` for a suspended workspace; `guestBootId` is always
+     * `undefined` — nothing here dials the guest.
+     */
+    readonly identity: KubernetesWorkspaceIdentity;
+    /** The stored holder epoch; `0` for a workspace that never carried one. */
+    readonly holderEpoch: number;
+    /**
+     * The allocation annotations as stored; every field `undefined` for a
+     * workspace not made by `allocateKubernetesWorkspace`.
+     */
+    readonly allocation: KubernetesObservedAllocation;
+    /**
+     * The Sandbox reports `Ready` for its CURRENT generation AND a live pod
+     * stands under it. A `Ready: True` the controller wrote for an earlier
+     * generation does not count.
+     */
+    readonly ready: boolean;
+    /** `volumeClaimTemplates` entries whose PVC does not exist (yet). */
+    readonly missingVolumeClaims: readonly string[];
+}
+/** {@link openKubernetesWorkspace}'s options. */
+export interface KubernetesWorkspaceOpenOptions extends KubernetesWorkspaceObservationOptions {
+    readonly workspaceId: string;
+    /** The identity the host retained. The Sandbox uid is required. */
+    readonly identity: KubernetesWorkspaceExpectedIdentity;
+    /** The holder epoch this host acts under — see {@link KubernetesWorkspaceInspectOptions.epoch}. */
+    readonly epoch: number;
+    /**
+     * The allocation this host expects, checked after the Sandbox uid: a
+     * mismatch is `KubernetesWorkspaceAllocationMismatchError`.
+     */
+    readonly expectedAllocation?: KubernetesWorkspaceAllocation;
+    /**
+     * Poll, under ONE deadline (`readyTimeoutMs`), until every volume claim
+     * exists and the guest is ready. A suspended workspace is returned at
+     * once — opening never wakes anything, so there is nothing to wait for.
+     * Omitted or `false`, one pass is made and the result says what was
+     * missing.
+     */
+    readonly waitForReady?: boolean;
+}
+/** {@link reconcileKubernetesWorkspace}'s options. */
+export interface KubernetesWorkspaceReconcileOptions extends KubernetesWorkspaceObservationOptions {
+    readonly workspaceId: string;
+    readonly identity: KubernetesWorkspaceExpectedIdentity;
+    /** When given, a workspace held at a higher epoch refuses the reconcile. */
+    readonly epoch?: number;
+    /**
+     * The allocation this host expects. Checked after the identity, so a
+     * `replaced` answer still wins; a Sandbox that IS the retained one but
+     * carries a different allocation or template content throws
+     * `KubernetesWorkspaceAllocationMismatchError`.
+     */
+    readonly expectedAllocation?: KubernetesWorkspaceAllocation;
+}
+/**
+ * What stands under a retained identity now.
+ *
+ *  - `live` — the same Sandbox, `Running`.
+ *  - `suspended` — the same Sandbox, `Suspended`; its disk is intact.
+ *  - `absent` — no Sandbox stands under the name at all.
+ *  - `replaced` — a different Sandbox, or a different volume claim, stands
+ *    there; `mismatch` says which. The retained workspace is gone.
+ */
+export type KubernetesWorkspaceClosureState = 'live' | 'suspended' | 'absent' | 'replaced';
+export interface KubernetesWorkspaceClosure {
+    readonly state: KubernetesWorkspaceClosureState;
+    readonly workspaceId: string;
+    readonly sandboxName: string;
+    /** What was observed. Absent for `absent`; the STRANGER's for `replaced`. */
+    readonly identity?: KubernetesWorkspaceIdentity;
+    /** Why the state is `replaced`. */
+    readonly mismatch?: KubernetesWorkspaceIdentityMismatch;
+}
+/** The wait ran out before the workspace was ready. Ownership was never in doubt. */
+export declare class KubernetesWorkspaceReadyTimeoutError extends Error {
+    readonly workspaceId: string;
+    readonly sandboxName: string;
+    readonly timeoutMs: number;
+    /** What the last pass was still waiting for. */
+    readonly waitingFor: readonly ('volume-claims' | 'ready-condition' | 'pod')[];
+    /** The last pass, so a caller can see how far it got. */
+    readonly lastObserved: KubernetesWorkspaceInspection;
+    readonly name = "KubernetesWorkspaceReadyTimeoutError";
+    constructor(workspaceId: string, sandboxName: string, timeoutMs: number, 
+    /** What the last pass was still waiting for. */
+    waitingFor: readonly ('volume-claims' | 'ready-condition' | 'pod')[], 
+    /** The last pass, so a caller can see how far it got. */
+    lastObserved: KubernetesWorkspaceInspection);
+}
+/**
+ * Read what stands under a workspace id: its Sandbox uid, its claim uids, its
+ * pod and its operating mode, and who holds it. GET requests only — nothing
+ * is created, woken, patched or deleted — and `undefined` when no Sandbox
+ * stands there.
+ *
+ * Needs `get` on `sandboxes`, `persistentvolumeclaims` and `pods`. A failed
+ * read rejects as itself: an unanswered request is never reported as a
+ * workspace that is absent.
+ */
+export declare function inspectKubernetesWorkspace(config: KubernetesBackendInternalConfig, workspaceId: string, options: KubernetesWorkspaceInspectOptions): Promise<KubernetesWorkspaceInspection | undefined>;
+/**
+ * Authenticate a retained identity against what stands under the workspace
+ * id, and — with `waitForReady` — wait for it to be usable. Never creates,
+ * wakes or writes.
+ *
+ * Refuses with {@link KubernetesWorkspaceIdentityMismatchError} when the
+ * Sandbox is gone or has another uid, or a claim has another uid or another
+ * owner, and with `KubernetesWorkspacePreconditionError` when the workspace
+ * is held at a higher epoch. The waiting form repeats both checks on every
+ * pass and retains every claim uid it has seen, so a replacement that lands
+ * mid-wait is a refusal rather than a longer wait. Cancelling `signal`
+ * rejects with its reason; running out of `readyTimeoutMs` rejects with
+ * {@link KubernetesWorkspaceReadyTimeoutError}. The three never share a class.
+ */
+export declare function openKubernetesWorkspace(config: KubernetesBackendInternalConfig, options: KubernetesWorkspaceOpenOptions): Promise<KubernetesWorkspaceInspection>;
+/**
+ * After a restart: what became of the workspace a host retained? One
+ * GET-only pass, answered as a closure state rather than thrown.
+ *
+ * A different Sandbox or claim is `replaced`, not an error, because for a
+ * host closing its books that IS the answer. A read that did not answer
+ * rejects as itself — it is never mapped to `absent`.
+ */
+export declare function reconcileKubernetesWorkspace(config: KubernetesBackendInternalConfig, options: KubernetesWorkspaceReconcileOptions): Promise<KubernetesWorkspaceClosure>;
+//# sourceMappingURL=workspace-observe.d.ts.map

package/dist/backends/kubernetes/workspace-observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-observe.d.ts","sourceRoot":"","sources":["../../../src/backends/kubernetes/workspace-observe.ts"],"names":[],"mappings":"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"}

package/dist/backends/kubernetes/workspace-observe.js

@@ -0,0 +1,343 @@
+/**
+ * Looking at a retained workspace by its exact identity, without creating,
+ * waking or writing anything.
+ *
+ * `createKubernetesWorkspace` is create-or-adopt: handed an id it POSTs, and
+ * on a 409 adopts whatever stands there and resumes it. That is the right
+ * verb for "give me a workspace" and the wrong one for a host that restarted
+ * and wants to know whether the workspace it recorded last week is still the
+ * workspace under that name — the question has to be answered BEFORE a pod is
+ * started for what might be a stranger's disk.
+ *
+ * Three verbs, all GET-only:
+ *
+ *  - {@link inspectKubernetesWorkspace} — what is there, and who holds it.
+ *  - {@link openKubernetesWorkspace} — authenticate a retained identity, and
+ *    optionally wait, under one deadline, for its claims and its guest.
+ *  - {@link reconcileKubernetesWorkspace} — after a restart: live, suspended,
+ *    absent or replaced.
+ *
+ * ## Ownership and readiness are separate questions
+ *
+ * Ownership is decided by uids and by nothing else: the Sandbox's
+ * `metadata.uid`, each volume claim's uid, and who owns each claim. A
+ * `resourceVersion` that moved, a `Ready` condition that flipped and a
+ * condition left over from an earlier generation are the controller working,
+ * and none of them is ever read as a change of owner. Readiness is a bounded
+ * poll on top of an ownership check that runs again on every pass, so a
+ * replacement that lands while waiting is still a refusal.
+ */
+import { OperationDeadline, OperationDeadlineExpired } from '../readiness.js';
+import { KubernetesWorkspaceAllocationMismatchError, assertAllocation, firstAllocationMismatch, observedAllocation, } from './allocation.js';
+import { KubernetesWorkspaceIdentityMismatchError, } from './identity.js';
+import { clientAccess, clientOptions, resolveKubernetesReadiness, } from './index.js';
+import { KubernetesAlreadyGoneError, createKubernetesClient, } from './k8s-client.js';
+import { READY_CONDITION, isPodLive, persistentVolumeClaimPath, podPath, readHolderEpoch, sandboxPath, } from './objects.js';
+import { KubernetesWorkspacePreconditionError, assertHolderEpoch, workspaceSandboxName, } from './workspace.js';
+/** The wait ran out before the workspace was ready. Ownership was never in doubt. */
+export class KubernetesWorkspaceReadyTimeoutError extends Error {
+    workspaceId;
+    sandboxName;
+    timeoutMs;
+    waitingFor;
+    lastObserved;
+    name = 'KubernetesWorkspaceReadyTimeoutError';
+    constructor(workspaceId, sandboxName, timeoutMs, 
+    /** What the last pass was still waiting for. */
+    waitingFor, 
+    /** The last pass, so a caller can see how far it got. */
+    lastObserved) {
+        super(`kubernetes: workspace ${workspaceId} (Sandbox ${sandboxName}) was the retained workspace on every pass but was not ready ${timeoutMs}ms later — still waiting for ${waitingFor.join(', ')}. Ownership is not in question: this is the controller not having finished, and nothing was created or woken to hurry it.`);
+        this.workspaceId = workspaceId;
+        this.sandboxName = sandboxName;
+        this.timeoutMs = timeoutMs;
+        this.waitingFor = waitingFor;
+        this.lastObserved = lastObserved;
+    }
+}
+async function readOrGone(client, path, signal) {
+    try {
+        return await client.request('GET', path, undefined, signal);
+    }
+    catch (err) {
+        if (err instanceof KubernetesAlreadyGoneError)
+            return undefined;
+        throw err;
+    }
+}
+/**
+ * One GET pass: the Sandbox, each of its claims, the pod behind the name.
+ * `undefined` is "no Sandbox"; every other failure travels out as itself, so
+ * a read that did not answer is never reported as a workspace that is gone.
+ */
+async function observe(client, namespace, name, signal) {
+    const sandbox = await readOrGone(client, sandboxPath(namespace, name), signal);
+    if (sandbox === undefined)
+        return undefined;
+    const sandboxUid = sandbox.metadata?.uid;
+    const claims = new Map();
+    const claimNames = [];
+    for (const entry of sandbox.spec?.volumeClaimTemplates ?? []) {
+        const claimName = entry?.metadata?.name;
+        if (typeof claimName !== 'string' || claimName === '')
+            continue;
+        claimNames.push(claimName);
+        const claim = await readOrGone(client, persistentVolumeClaimPath(namespace, name, claimName), signal);
+        const uid = claim?.metadata?.uid;
+        if (typeof uid !== 'string' || uid === '')
+            continue;
+        const owners = claim?.metadata?.ownerReferences ?? [];
+        // Only a claim that NAMES owners and names none of them this Sandbox is
+        // foreign; one with no owner list says nothing, and refusing it would
+        // refuse a cluster that simply does not report them.
+        const foreign = sandboxUid !== undefined && owners.length > 0 && !owners.some((o) => o?.uid === sandboxUid);
+        claims.set(claimName, { uid, ownedByOtherSandbox: foreign });
+    }
+    const pod = await readOrGone(client, podPath(namespace, name), signal);
+    return { sandbox, sandboxUid, claims, claimNames, pod };
+}
+function operatingModeOf(sandbox) {
+    return sandbox.spec?.operatingMode === 'Suspended' ? 'Suspended' : 'Running';
+}
+/**
+ * `Ready` is true AND is about the object's current spec. The controller
+ * keeps a `Ready: True` it wrote for an earlier generation visible after a
+ * spec change, and reading that as the new outcome is how a wake gets
+ * reported ready while its pod is still being replaced.
+ */
+function isReadyForCurrentGeneration(sandbox) {
+    const condition = sandbox.status?.conditions?.find((c) => c.type === READY_CONDITION);
+    if (condition?.status !== 'True')
+        return false;
+    const generation = sandbox.metadata?.generation;
+    const observed = condition.observedGeneration;
+    return !(generation !== undefined && observed !== undefined && observed < generation);
+}
+function inspectionOf(workspaceId, name, seen) {
+    const livePod = isPodLive(seen.pod) ? seen.pod : undefined;
+    const podUid = livePod?.metadata?.uid;
+    const uids = {};
+    for (const [claimName, claim] of seen.claims)
+        uids[claimName] = claim.uid;
+    const mode = operatingModeOf(seen.sandbox);
+    return {
+        workspaceId,
+        sandboxName: name,
+        operatingMode: mode,
+        identity: {
+            sandboxUid: seen.sandboxUid,
+            volumeClaimUids: uids,
+            podUid: mode === 'Suspended' ? undefined : podUid,
+            guestBootId: undefined,
+        },
+        holderEpoch: readHolderEpoch(seen.sandbox.metadata).epoch ?? 0,
+        allocation: observedAllocation(seen.sandbox),
+        ready: mode === 'Running' &&
+            isReadyForCurrentGeneration(seen.sandbox) &&
+            typeof podUid === 'string' &&
+            podUid !== '',
+        missingVolumeClaims: seen.claimNames.filter((n) => !seen.claims.has(n)),
+    };
+}
+/**
+ * The first way `seen` is not the retained workspace, or `undefined`.
+ *
+ * `claimUids` is every claim uid trusted so far: the retained ones, and every
+ * one a previous pass of the same wait saw. A claim that is not there yet is
+ * not a mismatch; one that is there with a DIFFERENT uid than one already
+ * trusted is.
+ */
+function firstMismatch(retained, claimUids, seen) {
+    if (seen.sandboxUid !== retained.sandboxUid) {
+        return { kind: 'sandbox-uid', expected: retained.sandboxUid, actual: seen.sandboxUid };
+    }
+    for (const [claimName, claim] of seen.claims) {
+        const trusted = claimUids[claimName];
+        if (trusted !== undefined && trusted !== claim.uid) {
+            return { kind: 'volume-claim-uid', expected: trusted, actual: claim.uid, claim: claimName };
+        }
+        if (claim.ownedByOtherSandbox) {
+            return {
+                kind: 'volume-claim-owner',
+                expected: retained.sandboxUid,
+                actual: claim.uid,
+                claim: claimName,
+            };
+        }
+    }
+    return undefined;
+}
+function assertRetained(identity, where) {
+    if (typeof identity?.sandboxUid !== 'string' || identity.sandboxUid === '') {
+        throw new TypeError(`kubernetes: ${where} needs identity.sandboxUid, a non-empty string — without it there is nothing to authenticate.`);
+    }
+}
+function assertEpochAllows(operation, workspaceId, name, epoch, sandbox) {
+    const reading = readHolderEpoch(sandbox.metadata);
+    if (reading.epoch !== undefined && reading.epoch <= epoch)
+        return;
+    throw new KubernetesWorkspacePreconditionError(operation, workspaceId, name, epoch, reading.epoch, reading.annotation);
+}
+function assertExpectedAllocation(workspaceId, name, sandbox, expected) {
+    if (expected === undefined)
+        return;
+    const mismatch = firstAllocationMismatch(sandbox, expected);
+    if (mismatch === undefined)
+        return;
+    throw new KubernetesWorkspaceAllocationMismatchError(workspaceId, name, mismatch.kind, mismatch.expected, mismatch.actual);
+}
+function clientFor(config) {
+    return createKubernetesClient(clientAccess(config), clientOptions(config));
+}
+/**
+ * Read what stands under a workspace id: its Sandbox uid, its claim uids, its
+ * pod and its operating mode, and who holds it. GET requests only — nothing
+ * is created, woken, patched or deleted — and `undefined` when no Sandbox
+ * stands there.
+ *
+ * Needs `get` on `sandboxes`, `persistentvolumeclaims` and `pods`. A failed
+ * read rejects as itself: an unanswered request is never reported as a
+ * workspace that is absent.
+ */
+export async function inspectKubernetesWorkspace(config, workspaceId, options) {
+    options.signal?.throwIfAborted();
+    const epoch = assertHolderEpoch(options.epoch, 'inspectKubernetesWorkspace');
+    if (epoch === undefined) {
+        throw new TypeError('kubernetes: inspectKubernetesWorkspace needs an epoch.');
+    }
+    if (options.expectedAllocation !== undefined) {
+        assertAllocation(options.expectedAllocation, 'inspectKubernetesWorkspace');
+    }
+    const name = workspaceSandboxName(workspaceId);
+    const seen = await observe(clientFor(config), config.namespace, name, options.signal);
+    if (seen === undefined)
+        return undefined;
+    assertEpochAllows('inspectKubernetesWorkspace', workspaceId, name, epoch, seen.sandbox);
+    assertExpectedAllocation(workspaceId, name, seen.sandbox, options.expectedAllocation);
+    return inspectionOf(workspaceId, name, seen);
+}
+/**
+ * Authenticate a retained identity against what stands under the workspace
+ * id, and — with `waitForReady` — wait for it to be usable. Never creates,
+ * wakes or writes.
+ *
+ * Refuses with {@link KubernetesWorkspaceIdentityMismatchError} when the
+ * Sandbox is gone or has another uid, or a claim has another uid or another
+ * owner, and with `KubernetesWorkspacePreconditionError` when the workspace
+ * is held at a higher epoch. The waiting form repeats both checks on every
+ * pass and retains every claim uid it has seen, so a replacement that lands
+ * mid-wait is a refusal rather than a longer wait. Cancelling `signal`
+ * rejects with its reason; running out of `readyTimeoutMs` rejects with
+ * {@link KubernetesWorkspaceReadyTimeoutError}. The three never share a class.
+ */
+export async function openKubernetesWorkspace(config, options) {
+    options.signal?.throwIfAborted();
+    const { workspaceId } = options;
+    assertRetained(options.identity, 'openKubernetesWorkspace');
+    if (options.expectedAllocation !== undefined) {
+        assertAllocation(options.expectedAllocation, 'openKubernetesWorkspace');
+    }
+    const epoch = assertHolderEpoch(options.epoch, 'openKubernetesWorkspace');
+    if (epoch === undefined)
+        throw new TypeError('kubernetes: openKubernetesWorkspace needs an epoch.');
+    const name = workspaceSandboxName(workspaceId);
+    const client = clientFor(config);
+    const trusted = { ...(options.identity.volumeClaimUids ?? {}) };
+    const wait = options.waitForReady === true;
+    const readiness = resolveKubernetesReadiness(config);
+    const deadline = new OperationDeadline(readiness.timeoutMs, `kubernetes workspace ${name} open`, options.signal);
+    const pass = async (signal) => {
+        const seen = await observe(client, config.namespace, name, signal);
+        if (seen === undefined) {
+            throw new KubernetesWorkspaceIdentityMismatchError(workspaceId, name, 'sandbox-absent', options.identity.sandboxUid, undefined);
+        }
+        const mismatch = firstMismatch(options.identity, trusted, seen);
+        if (mismatch !== undefined) {
+            throw new KubernetesWorkspaceIdentityMismatchError(workspaceId, name, mismatch.kind, mismatch.expected, mismatch.actual, mismatch.claim);
+        }
+        assertEpochAllows('openKubernetesWorkspace', workspaceId, name, epoch, seen.sandbox);
+        assertExpectedAllocation(workspaceId, name, seen.sandbox, options.expectedAllocation);
+        for (const [claimName, claim] of seen.claims)
+            trusted[claimName] = claim.uid;
+        return inspectionOf(workspaceId, name, seen);
+    };
+    if (!wait)
+        return await pass(options.signal);
+    let last;
+    while (deadline.remainingMs() > 0) {
+        try {
+            last = await deadline.run((signal) => pass(signal));
+        }
+        catch (err) {
+            if (err instanceof OperationDeadlineExpired)
+                break;
+            throw err;
+        }
+        if (last.operatingMode === 'Suspended')
+            return last;
+        if (last.missingVolumeClaims.length === 0 && last.ready)
+            return last;
+        try {
+            await deadline.delay(readiness.pollIntervalMs);
+        }
+        catch (err) {
+            if (err instanceof OperationDeadlineExpired)
+                break;
+            throw err;
+        }
+    }
+    options.signal?.throwIfAborted();
+    if (last === undefined) {
+        // The deadline expired before the first pass answered. That is an
+        // unanswered read, not a workspace that is not ready, and it is said so.
+        throw new OperationDeadlineExpired(`kubernetes workspace ${name} open`);
+    }
+    throw new KubernetesWorkspaceReadyTimeoutError(workspaceId, name, readiness.timeoutMs, [
+        ...(last.missingVolumeClaims.length > 0 ? ['volume-claims'] : []),
+        ...(last.identity.podUid === undefined ? ['pod'] : []),
+        ...(last.ready ? [] : ['ready-condition']),
+    ], last);
+}
+/**
+ * After a restart: what became of the workspace a host retained? One
+ * GET-only pass, answered as a closure state rather than thrown.
+ *
+ * A different Sandbox or claim is `replaced`, not an error, because for a
+ * host closing its books that IS the answer. A read that did not answer
+ * rejects as itself — it is never mapped to `absent`.
+ */
+export async function reconcileKubernetesWorkspace(config, options) {
+    options.signal?.throwIfAborted();
+    const { workspaceId } = options;
+    assertRetained(options.identity, 'reconcileKubernetesWorkspace');
+    if (options.expectedAllocation !== undefined) {
+        assertAllocation(options.expectedAllocation, 'reconcileKubernetesWorkspace');
+    }
+    const epoch = assertHolderEpoch(options.epoch, 'reconcileKubernetesWorkspace');
+    const name = workspaceSandboxName(workspaceId);
+    const seen = await observe(clientFor(config), config.namespace, name, options.signal);
+    if (seen === undefined)
+        return { state: 'absent', workspaceId, sandboxName: name };
+    const inspection = inspectionOf(workspaceId, name, seen);
+    const mismatch = firstMismatch(options.identity, { ...(options.identity.volumeClaimUids ?? {}) }, seen);
+    if (mismatch !== undefined) {
+        return {
+            state: 'replaced',
+            workspaceId,
+            sandboxName: name,
+            identity: inspection.identity,
+            mismatch: mismatch.kind,
+        };
+    }
+    if (epoch !== undefined) {
+        assertEpochAllows('reconcileKubernetesWorkspace', workspaceId, name, epoch, seen.sandbox);
+    }
+    assertExpectedAllocation(workspaceId, name, seen.sandbox, options.expectedAllocation);
+    return {
+        state: inspection.operatingMode === 'Suspended' ? 'suspended' : 'live',
+        workspaceId,
+        sandboxName: name,
+        identity: inspection.identity,
+    };
+}
+//# sourceMappingURL=workspace-observe.js.map

package/dist/backends/kubernetes/workspace-observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-observe.js","sourceRoot":"","sources":["../../../src/backends/kubernetes/workspace-observe.ts"],"names":[],"mappings":"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"}

package/dist/backends/kubernetes/workspace-per-sandbox.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Per-sandbox egress on a workspace: the pieces `createKubernetesWorkspace`,
+ * `allocateKubernetesWorkspace` and a workspace handle share.
+ *
+ * ## The shape, and where it differs from a task sandbox
+ *
+ *  - **Label.** The per-sandbox selector label rides on the workspace's
+ *    directly created `Sandbox` pod template, composed by
+ *    `composeAdditionalPodLabels` beside the egress profile. Its VALUE is the
+ *    Sandbox's own name, `namzu-ws-<workspaceId>`: deterministic, known before
+ *    the POST, and stable across a suspend and a resume, because a resume
+ *    patches `operatingMode` and the pod template (labels included) is carried
+ *    by the object, not by the pod.
+ *  - **Owner.** The `Sandbox` itself. A policy names it in `ownerReferences`
+ *    with its `metadata.uid`, so deleting the workspace (`destroy({ deleteDisk:
+ *    true })`, `deleteKubernetesWorkspace`) lets the cluster's garbage
+ *    collector remove every policy it owns. The default `destroy()` only
+ *    suspends, keeps the object, and so keeps the policy.
+ *  - **Name.** `namzu-sbx-<sandbox uid>`, the same rule as a task sandbox. The
+ *    workspace NAME is deterministic and its uid is not, so a workspace deleted
+ *    and created again under the same name selects by the same label value
+ *    and owns a policy of a different name.
+ *
+ * ## Suspend and resume
+ *
+ * The behaviour is one rule, applied on every path that is about to run the
+ * workspace's pod: a resume, and an open of an existing workspace.
+ *
+ *  1. The admission fence is re-verified from scratch (never from a memo). A
+ *     fence that is missing or would not enforce REFUSES the resume, before
+ *     the patch: the workspace stays suspended, which is the only state that
+ *     is safe without the fence, and nothing is written.
+ *  2. Every per-sandbox policy in the namespace that selects this workspace
+ *     (name prefix `namzu-sbx-`, selector label value equal to the Sandbox's
+ *     name) and that this Sandbox does not own (no `ownerReferences` entry of
+ *     kind `Sandbox` with this name and the uid the cluster reports NOW) is
+ *     deleted. Such a policy belongs to a workspace that was deleted and
+ *     created again under the same name and has not been garbage-collected
+ *     yet; left alone it would grant the new workspace what the old one's
+ *     consent covered.
+ *  3. A policy this Sandbox owns is KEPT, unchanged. A suspend is not a
+ *     revocation: the grant was admitted by the fence when it was written and
+ *     the resumed pod carries the same label, so the policy applies to it
+ *     again. A host that wants the grant gone calls `setNetworkPolicy({
+ *     allowedHosts: [] })` (which deletes it) before it suspends.
+ *
+ * A freshly created workspace gets step 2 after the create reply, with the uid
+ * the reply carried.
+ *
+ * ## What is NOT proven here
+ *
+ * That any of it is enforced. Enforcement is the CNI's data plane: it needs a
+ * cluster running Cilium, the same as the task path.
+ */
+import type { KubernetesEgressConfig, KubernetesPerSandboxEgressConfig } from './egress-policy.js';
+import { type KubernetesClient } from './k8s-client.js';
+import { type PerSandboxPolicyFence } from './per-sandbox-policy.js';
+/** The profile variant a workspace with per-sandbox egress configured carries. */
+export declare const KUBERNETES_PER_SANDBOX_PROFILE_VARIANT = "core/no-network+per-sandbox";
+/**
+ * The extra pod-label map a workspace named `sandboxName` contributes to
+ * `composeAdditionalPodLabels`, or `undefined` when `perSandbox` is not
+ * configured, which is what keeps that workspace's request log unchanged.
+ */
+export declare function perSandboxWorkspaceLabels(egress: KubernetesEgressConfig | undefined, sandboxName: string): Readonly<Record<string, string>> | undefined;
+/** `labels` without the per-sandbox key `extra` carries; `labels` itself when there is none. */
+export declare function withoutPerSandboxLabel(labels: Readonly<Record<string, string>>, extra: Readonly<Record<string, string>> | undefined): Readonly<Record<string, string>>;
+/**
+ * The names of the per-sandbox policies this workspace's label selects and
+ * its Sandbox does not own. Read only.
+ */
+export declare function findForeignPerSandboxPolicies(client: KubernetesClient, namespace: string, labelKey: string, sandboxName: string, ownerUid: string, signal?: AbortSignal): Promise<readonly string[]>;
+/** What {@link reverifyPerSandboxEgress} needs. */
+export interface PerSandboxReverification {
+    readonly client: KubernetesClient;
+    readonly namespace: string;
+    readonly sandboxName: string;
+    /** The uid the cluster reports for the Sandbox NOW. */
+    readonly ownerUid: string;
+    readonly egress: KubernetesEgressConfig & {
+        readonly perSandbox: KubernetesPerSandboxEgressConfig;
+    };
+    /** A fence whose memo has not been used yet. */
+    readonly fence: PerSandboxPolicyFence;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Steps 1 and 2 of the resume rule above: prove the fence, then delete the
+ * policies that select this workspace and that its Sandbox does not own.
+ * Returns the names it deleted. Throws the fence's own refusal, having
+ * written nothing, when the fence does not verify.
+ */
+export declare function reverifyPerSandboxEgress(options: PerSandboxReverification): Promise<readonly string[]>;
+//# sourceMappingURL=workspace-per-sandbox.d.ts.map

package/dist/backends/kubernetes/workspace-per-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-per-sandbox.d.ts","sourceRoot":"","sources":["../../../src/backends/kubernetes/workspace-per-sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,gCAAgC,EAAE,MAAM,oBAAoB,CAAA;AAElG,OAAO,EAA8B,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAEnF,OAAO,EAAkC,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAA;AAEpG,kFAAkF;AAClF,eAAO,MAAM,sCAAsC,gCAAgC,CAAA;AAEnF;;;;GAIG;AACH,wBAAgB,yBAAyB,CACxC,MAAM,EAAE,sBAAsB,GAAG,SAAS,EAC1C,WAAW,EAAE,MAAM,GACjB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAG9C;AAED,gGAAgG;AAChG,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACxC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GACjD,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAGlC;AAmBD;;;GAGG;AACH,wBAAsB,6BAA6B,CAClD,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAkB5B;AAED,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,GAAG;QACzC,QAAQ,CAAC,UAAU,EAAE,gCAAgC,CAAA;KACrD,CAAA;IACD,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAA;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC7B;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC7C,OAAO,EAAE,wBAAwB,GAC/B,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAqB5B"}