@namzu/sandbox 26.0.0 → 27.0.0

package/src/backends/kubernetes/objects.ts

@@ -68,6 +68,19 @@ export interface KubernetesObjectMeta {
 	 * `k8s-client.ts` states still holds. See {@link buildHolderEpochPatch}.
 	 */
 	readonly resourceVersion?: string
+	/**
+	 * `metadata.generation`: bumped by the API server on every change to
+	 * `spec`. Read only by the readiness observation, which compares it with a
+	 * condition's `observedGeneration` so that a `Ready: True` the controller
+	 * wrote for an EARLIER spec is not mistaken for the outcome of the latest
+	 * one.
+	 */
+	readonly generation?: number
+	/** Who owns this object. Read off a PVC, to tell the Sandbox's disk from a stranger's. */
+	readonly ownerReferences?: readonly {
+		readonly uid?: string
+		readonly controller?: boolean
+	}[]
 	/**
 	 * 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 —
@@ -85,6 +98,12 @@ export interface KubernetesCondition {
 	readonly reason?: string
 	readonly message?: string
 	readonly lastTransitionTime?: string
+	/**
+	 * The `metadata.generation` the controller had seen when it wrote this
+	 * condition. A condition whose value is below the object's current
+	 * generation describes an earlier spec.
+	 */
+	readonly observedGeneration?: number
 }
 
 /**
@@ -561,6 +580,70 @@ export function podTemplateHash(podTemplate: SandboxPodTemplate): string {
 	return `sha256:${digest}`
 }
 
+/**
+ * `sha256:<hex>` over any JSON-serialisable value, taken over its CANONICAL
+ * form: object keys sorted by code unit at every depth, `undefined` members
+ * dropped, arrays kept in order, then `JSON.stringify` with no whitespace.
+ *
+ * {@link podTemplateHash} and the execution-profile fingerprint both go
+ * through it, so two hosts on the same release computing it over the same
+ * content get the same string whatever order their objects were built in.
+ */
+export function canonicalFingerprint(value: unknown): string {
+	const digest = createHash('sha256')
+		.update(JSON.stringify(canonicalJson(value)))
+		.digest('hex')
+	return `sha256:${digest}`
+}
+
+/**
+ * Backend-owned annotation carrying the ALLOCATION ID a workspace was created
+ * for by `allocateKubernetesWorkspace`: the host's own immutable identifier
+ * for "this allocation", chosen and persisted by the host BEFORE the create.
+ *
+ * Public contract. Written once, in the create POST, and never patched by
+ * this backend afterwards — a refresh, a resume, a suspend or an epoch write
+ * merges other annotations and leaves it alone. Absent on a workspace made
+ * by `createKubernetesWorkspace`.
+ *
+ * Same prefix as {@link HOLDER_EPOCH_ANNOTATION_KEY}.
+ */
+export const ALLOCATION_ID_ANNOTATION_KEY = 'sandbox.namzu.ai/allocation-id'
+
+/**
+ * Backend-owned annotation carrying the host's SCOPE FINGERPRINT for the
+ * allocation: an opaque string naming what the workspace is for (tenant,
+ * project, session — the host decides). The backend never interprets it; it
+ * only stores it and compares it for equality. Written with, and under the
+ * same rules as, {@link ALLOCATION_ID_ANNOTATION_KEY}.
+ */
+export const ALLOCATION_SCOPE_ANNOTATION_KEY = 'sandbox.namzu.ai/allocation-scope'
+
+/**
+ * Backend-owned annotation carrying the EXECUTION PROFILE FINGERPRINT the
+ * workspace was allocated under: the `sha256:<hex>` that
+ * `resolveKubernetesExecutionProfile` returns. Written with, and under the
+ * same rules as, {@link ALLOCATION_ID_ANNOTATION_KEY}.
+ */
+export const EXECUTION_PROFILE_ANNOTATION_KEY = 'sandbox.namzu.ai/execution-profile'
+
+/** What a Sandbox's allocation annotations say; each `undefined` when absent. */
+export interface AllocationReading {
+	readonly id: string | undefined
+	readonly scopeFingerprint: string | undefined
+	readonly executionProfile: string | undefined
+}
+
+/** Read the three allocation annotations off an object's metadata. */
+export function readAllocation(meta: KubernetesObjectMeta | undefined): AllocationReading {
+	const annotations = meta?.annotations
+	return {
+		id: annotations?.[ALLOCATION_ID_ANNOTATION_KEY],
+		scopeFingerprint: annotations?.[ALLOCATION_SCOPE_ANNOTATION_KEY],
+		executionProfile: annotations?.[EXECUTION_PROFILE_ANNOTATION_KEY],
+	}
+}
+
 /**
  * One RFC 6902 operation, in the only three shapes this backend sends.
  *
@@ -621,6 +704,11 @@ export interface HolderEpochReading {
 	readonly hasAnnotations: boolean
 	/** `metadata.resourceVersion`, for the fallback `test` and a fenced DELETE. */
 	readonly resourceVersion?: string
+	/**
+	 * `metadata.uid` of the object this reading came from, so a write can
+	 * refuse a same-name replacement off the very read it is conditioned on.
+	 */
+	readonly sandboxUid?: string
 }
 
 /** Decimal, no sign, no padding, no exponent — what this backend writes. */
@@ -637,6 +725,7 @@ export function readHolderEpoch(meta: KubernetesObjectMeta | undefined): HolderE
 	const base = {
 		hasAnnotations: annotations !== undefined,
 		...(resourceVersion !== undefined ? { resourceVersion } : {}),
+		...(typeof meta?.uid === 'string' && meta.uid !== '' ? { sandboxUid: meta.uid } : {}),
 	}
 	if (typeof stored !== 'string') return { ...base, epoch: 0 }
 	if (!HOLDER_EPOCH_PATTERN.test(stored)) return { ...base, annotation: stored }
@@ -963,6 +1052,15 @@ export function validatingAdmissionPolicyBindingPath(name: string): string {
 	return `/apis/${ADMISSION_REGISTRATION_API_GROUP}/${ADMISSION_REGISTRATION_API_VERSION}/validatingadmissionpolicybindings/${segment(name)}`
 }
 
+/**
+ * One core `ConfigMap`. Read by exactly one caller: the per-sandbox fence's
+ * operator-pinned host set (`per-sandbox-fence.ts`), which the backend only
+ * ever GETs.
+ */
+export function configMapPath(namespace: string, name: string): string {
+	return `/api/v1/namespaces/${segment(namespace)}/configmaps/${segment(name)}`
+}
+
 /**
  * An `ownerReferences` entry, as this backend writes it.
  *