@calltelemetry/ct-lab-mcp 0.8.149 → 0.8.151

package/dist/src/tools/appliance-claim-tools.js

@@ -10,13 +10,18 @@
 import { z } from "zod";
 import { fetch, Agent } from "undici";
 import * as fs from "node:fs";
+import { createHash } from "node:crypto";
+import { isIP } from "node:net";
 import { ProxmoxErrorCode, createToolErrorResult } from "../types/mcp.js";
 import { logger } from "../utils/logger.js";
 import { validateStigDescriptor } from "../stig/model.js";
-import { createClaimWithCustody, deleteClaimWithCustody, NoClaimCustodyError } from "./claim-custody.js";
+import { CUSTODY_ANNOTATION, claimCustody, createClaimWithCustody, deleteClaimWithCustody, NoClaimCustodyError, verifyCustodyClaim } from "./claim-custody.js";
+import { buildProvenance } from "../provenance.js";
+import { buildLabInspectionEnvelope, InspectionConflictError, projectAccessObserved, projectCurrentNetworkReadiness, projectLifecycleDiagnostic, projectNetworkRevalidation, projectOperatorWorkflow, NETWORK_REVALIDATION_REQUEST_TTL_MS, unknown as unknownEvidence, verified as verifiedEvidence, } from "../inspection/lab-inspection.js";
+import { readInstalledRuntimeArtifact } from "../inspection/runtime-artifact.js";
 import { LAB_CLAIM_BACKEND_REMEDIATION, LabClaimBackendConfigError, diagnoseLabKubernetesBackend, resolveLabKubernetesBackend, runLabKubectl, } from "./kubernetes-backend.js";
 import { AUTO_NODE, PLACEMENT_ANNOTATION, fleetFromManager, isAutoNode, pinnedPlacementAnnotation, placeOnFleet, placementAnnotation, } from "./placement.js";
-import { proxmoxClaimNode, PROXMOX_HOST_CLAIM_NODES, } from "./proxmox-host-policy.js";
+import { proxmoxClaimNode, CLAIM_NODE_TO_PROXMOX_HOST, PROXMOX_HOST_CLAIM_NODES, } from "./proxmox-host-policy.js";
 export const RECOGNIZED_CHANNELS = ["stable", "beta", "rc", "candidate", "dev", "edge"];
 export function resolveAndValidateChannel(version, trainOrChannel) {
     const isPrerelease = version.includes("-rc") || version.includes("-dev") || version.includes("-beta") || version.includes("-candidate");
@@ -59,9 +64,22 @@ export const ListApplianceClaimsInputShape = {
 export const ListApplianceClaimsInputSchema = z.object(ListApplianceClaimsInputShape);
 export const GetApplianceClaimInputShape = {
     name: z.string().min(1).describe("Name of the ApplianceClaim resource (metadata.name)."),
-    namespace: z.string().optional().default("ct-lab").describe("Kubernetes namespace (default: 'ct-lab').")
+    namespace: z.string().optional().default("ct-lab").describe("Kubernetes namespace (default: 'ct-lab')."),
+    expectedUid: z.string().uuid().optional().describe("Optional expected current claim UID. A mismatch is rejected; this value is never treated as observed evidence."),
+    expectedGeneration: z.number().int().nonnegative().optional().describe("Optional expected current claim generation. A mismatch is rejected; this value is never treated as observed evidence."),
+    expectedRequestId: z.string().uuid().optional().describe("Optional exact read-only network-revalidation request ID whose persisted result should be projected."),
 };
 export const GetApplianceClaimInputSchema = z.object(GetApplianceClaimInputShape);
+export const RevalidateApplianceClaimNetworkInputShape = {
+    name: z.string().min(1).describe("Current ApplianceClaim name."),
+    namespace: z.string().optional().default("ct-lab").describe("Kubernetes namespace (default: 'ct-lab')."),
+    expectedUid: z.string().uuid().describe("Exact live claim UID to bind the read-only revalidation request."),
+    expectedGeneration: z.number().int().positive().describe("Exact live claim generation to bind the read-only revalidation request."),
+    operationId: z.string().min(1).max(128).regex(/^[A-Za-z0-9._:-]+$/).describe("Current durable W2 CUBE workflow operationId."),
+    intentDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/).describe("Current durable W2 secret-free immutable intent digest."),
+    requestId: z.string().uuid().describe("Unique idempotency identity for this read-only probe attempt."),
+};
+export const RevalidateApplianceClaimNetworkInputSchema = z.object(RevalidateApplianceClaimNetworkInputShape).strict();
 export const CreateApplianceClaimInputShape = {
     name: z.string().optional().describe("Name of the ApplianceClaim resource (metadata.name). Auto-generated if omitted."),
     namespace: z.string().optional().default("ct-lab").describe("Kubernetes namespace (default: 'ct-lab')."),
@@ -134,7 +152,7 @@ export function normalizeClaimNode(node) {
         return "esxi";
     return proxmoxClaimNode(raw);
 }
-export async function queryKubernetesApi(path, options = {}) {
+export async function queryKubernetesApiWithObservation(path, options = {}) {
     const backend = resolveLabKubernetesBackend();
     if (backend.mode === "in-cluster") {
         const token = fs.readFileSync(backend.tokenPath, "utf-8").trim();
@@ -162,7 +180,13 @@ export async function queryKubernetesApi(path, options = {}) {
             });
             if (!res.ok)
                 throw new Error(`Kubernetes API request failed (${res.status})`);
-            return res.json();
+            const body = await res.json();
+            const dateHeader = res.headers?.get?.("date");
+            const dateMs = typeof dateHeader === "string" ? Date.parse(dateHeader) : NaN;
+            return {
+                data: body,
+                ...(Number.isFinite(dateMs) ? { observedAt: new Date(dateMs).toISOString() } : {}),
+            };
         }
         finally {
             await agent.close();
@@ -171,12 +195,100 @@ export async function queryKubernetesApi(path, options = {}) {
     // The caller must use runLabKubectl, which validates the same explicit binding.
     return null;
 }
+export async function queryKubernetesApi(path, options = {}) {
+    const observation = await queryKubernetesApiWithObservation(path, options);
+    return observation?.data ?? null;
+}
+function claimHasFinalRevalidation(claim, requestId, uid, generation) {
+    if (claim?.metadata?.uid !== uid || claim?.metadata?.generation !== generation)
+        return false;
+    const workflow = claim?.status?.cubeWorkflow;
+    const receipt = workflow?.networkRevalidation ?? workflow?.summary?.networkRevalidation;
+    return receipt?.requestId === requestId && ["verified", "unknown"].includes(receipt?.state);
+}
+function parseWatchClaimEvents(stdout, requestId, uid, generation) {
+    for (const line of stdout.split(/\r?\n/u)) {
+        if (!line.trim())
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const object = event?.object ?? event;
+        if (event?.type === "DELETED" && object?.metadata?.uid === uid && object?.metadata?.generation === generation) {
+            return { claim: object, deleted: true };
+        }
+        if (!["ADDED", "MODIFIED"].includes(event?.type)
+            || !claimHasFinalRevalidation(object, requestId, uid, generation))
+            continue;
+        return { claim: object, deleted: false };
+    }
+    return undefined;
+}
+/** One Kubernetes watch for the exact request; no GET polling and no guest effect. */
+async function watchClaimRevalidation(namespace, name, resourceVersion, requestId, uid, generation, timeoutMs = 20_000) {
+    const backend = resolveLabKubernetesBackend();
+    const apiPath = `/apis/calltelemetry.com/v1alpha1/namespaces/${encodeURIComponent(namespace)}/applianceclaims?watch=true&allowWatchBookmarks=true&fieldSelector=${encodeURIComponent(`metadata.name=${name}`)}&resourceVersion=${encodeURIComponent(resourceVersion)}&timeoutSeconds=${Math.ceil(timeoutMs / 1000)}`;
+    if (backend.mode === "kubeconfig") {
+        try {
+            const { stdout } = await runLabKubectl([
+                "get", "applianceclaim", name, "-n", namespace,
+                "--watch-only", "--output-watch-events", "-o", "json", `--request-timeout=${Math.ceil(timeoutMs / 1000)}s`,
+            ], { timeoutMs: timeoutMs + 1_000, maxBufferBytes: 1_048_576 });
+            return parseWatchClaimEvents(stdout, requestId, uid, generation);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const token = fs.readFileSync(backend.tokenPath, "utf-8").trim();
+    if (!token)
+        return undefined;
+    const ca = fs.readFileSync(backend.caPath);
+    const agent = new Agent({ connect: { ca, rejectUnauthorized: true } });
+    try {
+        const response = await fetch(`${backend.server}${apiPath}`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+            dispatcher: agent,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok || !response.body)
+            return undefined;
+        const dateHeader = response.headers?.get?.("date");
+        const dateMs = typeof dateHeader === "string" ? Date.parse(dateHeader) : NaN;
+        const observedAt = Number.isFinite(dateMs) ? new Date(dateMs).toISOString() : undefined;
+        const decoder = new TextDecoder();
+        let pending = "";
+        for await (const chunk of response.body) {
+            pending += decoder.decode(chunk, { stream: true });
+            const lines = pending.split(/\r?\n/u);
+            pending = lines.pop() ?? "";
+            const found = parseWatchClaimEvents(`${lines.join("\n")}\n`, requestId, uid, generation);
+            if (found)
+                return { ...found, ...(observedAt ? { observedAt } : {}) };
+        }
+        const final = parseWatchClaimEvents(pending, requestId, uid, generation);
+        return final ? { ...final, ...(observedAt ? { observedAt } : {}) } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await agent.close();
+    }
+}
 export function independentClaimVerb(operation, args) {
     const input = args;
     if (operation === "list_appliance_claims")
         return "list";
     if (operation === "get_appliance_claim")
         return "get";
+    if (operation === "revalidate_appliance_claim_network")
+        return "patch";
     if (operation === "create_appliance_claim")
         return input?.dryRun === true ? null : "create";
     if (operation === "delete_appliance_claim")
@@ -249,6 +361,7 @@ export function claimBackendPreflightError(operation) {
 const FORWARD_METHOD = {
     list_appliance_claims: "claimsList",
     get_appliance_claim: "claimsGet",
+    revalidate_appliance_claim_network: "claimsNetworkRevalidate",
     list_held_claims: "claimsHeld",
     lab_capacity: "claimsCapacity",
     create_appliance_claim: "claimsCreate",
@@ -258,8 +371,8 @@ const FORWARD_METHOD = {
 };
 /**
  * REL-1961/REL-1964: a Worker has no k3s API route but holds a RemoteLabExecutor whose
- * in-cluster claim plane serves claim list/get and, behind the executor's kill switch,
- * create/renew/delete/pause. Forward only when the local backend is unconfigured, so
+ * in-cluster claim plane serves claim list/get and request-bound CUBE revalidation and,
+ * behind the executor's kill switch, claim mutations. Forward only when the local backend is unconfigured, so
  * gateways and the executor itself keep running locally.
  */
 export async function forwardClaim(operation, input, context) {
@@ -344,6 +457,473 @@ export async function handleListApplianceClaims(args, context) {
         return createToolErrorResult(ProxmoxErrorCode.UPSTREAM_API_ERROR, `Failed to list appliance claims in namespace '${namespace}': ${err.message}`);
     }
 }
+const CUBE_REVALIDATION_REQUEST_ANNOTATION = "calltelemetry.com/cube-revalidation-request";
+const CUBE_REVALIDATION_REQUEST_SCHEMA = "ct.appliance.cube-revalidation-request/v1";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const MAC_PATTERN = /^(?:[0-9a-f]{2}:){5}[0-9a-f]{2}$/i;
+function inspectionDigest(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function safeRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function validDate(value) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value)))
+        return undefined;
+    try {
+        return new Date(Date.parse(value)).toISOString();
+    }
+    catch {
+        return undefined;
+    }
+}
+function observedFact(value, observedAt) {
+    return observedAt
+        ? verifiedEvidence({ value, observedAt }, "operator_status_readback")
+        : unknownEvidence("source_observation_time_missing");
+}
+function desiredHostTuple(claim, custodyGuest) {
+    const node = normalizeClaimNode(claim.spec.node);
+    const vmid = claim.spec.vmid;
+    if (!node || node === "esxi" || !Number.isSafeInteger(vmid) || vmid < 100)
+        return undefined;
+    const hostAssetId = CLAIM_NODE_TO_PROXMOX_HOST[node];
+    const tuple = { hostAssetId, node, vmid: vmid };
+    if (custodyGuest && JSON.stringify(tuple) !== JSON.stringify(custodyGuest)) {
+        throw new InspectionConflictError("INSPECTION_CONFLICT");
+    }
+    return tuple;
+}
+function claimExpiry(claim) {
+    const status = safeRecord(claim.status);
+    const explicit = validDate(status?.expiresAt);
+    if (explicit)
+        return verifiedEvidence(explicit, "operator_claim_expiry");
+    const ttlHours = claim.spec.ttlHours ?? 24;
+    if (ttlHours === 0)
+        return verifiedEvidence(null, "claim_spec_no_expiry");
+    if (!Number.isSafeInteger(ttlHours) || ttlHours < 0 || ttlHours > 8760)
+        return unknownEvidence("claim_expiry_invalid");
+    const startsAt = validDate(status?.completionTime) ?? validDate(claim.metadata.creationTimestamp);
+    if (!startsAt)
+        return unknownEvidence("claim_expiry_source_missing");
+    return verifiedEvidence(new Date(Date.parse(startsAt) + ttlHours * 3_600_000).toISOString(), "claim_ttl_contract");
+}
+function claimCustodyProjection(claim) {
+    try {
+        const record = claimCustody(claim);
+        if (!record)
+            return { evidence: verifiedEvidence({ present: false, phase: "missing" }, "claim_metadata_annotations") };
+        verifyCustodyClaim(claim, record, claim.metadata.uid);
+        const guest = record.guest;
+        return {
+            evidence: verifiedEvidence({ present: true, phase: record.phase, guest }, "claim_custody_annotation"),
+            record,
+        };
+    }
+    catch {
+        throw new InspectionConflictError("INSPECTION_CONFLICT");
+    }
+}
+function deriveCubeOperationId(uid, generation, intentDigest) {
+    if (!UUID_PATTERN.test(uid) || !Number.isSafeInteger(generation) || generation < 1
+        || !/^sha256:[a-f0-9]{64}$/.test(intentDigest))
+        return undefined;
+    const input = `${uid.toLowerCase()}\0${generation}\0${intentDigest}`;
+    return `cube-${createHash("sha256").update(input, "utf8").digest("hex").slice(0, 32)}`;
+}
+function workflowBindsClaimGeneration(rawWorkflow, uid, generation) {
+    if (!uid || generation === undefined)
+        return false;
+    const summary = safeRecord(safeRecord(rawWorkflow)?.summary);
+    if (typeof summary?.intentDigest !== "string" || typeof summary.operationId !== "string")
+        return false;
+    return summary.operationId === deriveCubeOperationId(uid, generation, summary.intentDigest);
+}
+function activeCubeClaimRefusal(claim, input, now = Date.now()) {
+    const metadata = safeRecord(claim.metadata) ?? {};
+    const status = safeRecord(claim.status) ?? {};
+    const spec = safeRecord(claim.spec) ?? {};
+    const workflow = safeRecord(status.cubeWorkflow);
+    const summary = safeRecord(workflow?.summary);
+    if (metadata.uid !== input.expectedUid || metadata.generation !== input.expectedGeneration)
+        return "claim_identity_conflict";
+    if (metadata.deletionTimestamp)
+        return "claim_deleting";
+    if (spec.state === "Closed" || spec.closed === true || spec.paused === true)
+        return "claim_inactive";
+    if (status.phase !== "Ready" || status.observedGeneration !== input.expectedGeneration
+        || summary?.phase !== "ready" || summary?.operationId !== input.operationId || summary?.intentDigest !== input.intentDigest
+        || !workflowBindsClaimGeneration(workflow, input.expectedUid, input.expectedGeneration)) {
+        return "claim_not_ready_or_workflow_changed";
+    }
+    if (spec.profile !== "cube" || !safeRecord(spec.cube))
+        return "cube_claim_required";
+    const expiry = claimExpiry(claim);
+    if (expiry.state !== "verified" || !expiry.value || Date.parse(expiry.value) <= now)
+        return "claim_inactive";
+    try {
+        const custody = claimCustody(claim);
+        if (!custody || custody.phase !== "provider-bound")
+            return "active_provider_custody_required";
+        verifyCustodyClaim(claim, custody, input.expectedUid);
+    }
+    catch {
+        return "claim_custody_conflict";
+    }
+    return undefined;
+}
+function phaseTime(workflow, phase) {
+    if (workflow.state !== "verified")
+        return undefined;
+    const result = workflow.value.phases[phase]?.result;
+    return validDate(result?.observedAt);
+}
+function phaseReadiness(workflow, phase) {
+    if (workflow.state !== "verified")
+        return unknownEvidence("workflow_status_unavailable");
+    const result = workflow.value.phases[phase]?.result;
+    const observedAt = validDate(result?.observedAt);
+    if (!result || !observedAt)
+        return unknownEvidence("phase_result_unavailable");
+    if (result.effectCertainty === "confirmed")
+        return verifiedEvidence({ value: { state: "ready" }, observedAt }, "operator_workflow_status");
+    if (result.effectCertainty === "none")
+        return verifiedEvidence({ value: { state: "not_ready" }, observedAt }, "operator_workflow_status");
+    return verifiedEvidence({ value: { state: "pending" }, observedAt }, "operator_workflow_status");
+}
+function readinessDimension(observed, desired = "ready") {
+    return { desired: verifiedEvidence(desired, "claim_profile"), observed };
+}
+function projectBootstrapAddress(statusValue) {
+    const status = safeRecord(statusValue);
+    const bootstrap = safeRecord(status?.networkBootstrap);
+    const observedAt = validDate(bootstrap?.leaseObservedAt);
+    if (!bootstrap || !observedAt || bootstrap.leaseSource !== "ios-dhcp-interface") {
+        return {
+            address: unknownEvidence("historical_network_observation_unavailable"),
+            uuid: unknownEvidence("provider_identity_not_recorded"),
+            mac: unknownEvidence("provider_identity_not_recorded"),
+        };
+    }
+    const address = typeof bootstrap.address === "string" && isIP(bootstrap.address) === 4
+        ? verifiedEvidence({ value: bootstrap.address, source: "ios_dhcp_interface", observedAt }, "operator_network_bootstrap")
+        : unknownEvidence("historical_address_invalid");
+    const uuid = typeof bootstrap.guestUuid === "string" && UUID_PATTERN.test(bootstrap.guestUuid)
+        ? verifiedEvidence({ value: bootstrap.guestUuid.toLowerCase(), observedAt }, "ios_dhcp_interface")
+        : unknownEvidence("provider_identity_not_recorded");
+    const mac = typeof bootstrap.macAddress === "string" && MAC_PATTERN.test(bootstrap.macAddress)
+        ? verifiedEvidence({ value: bootstrap.macAddress.toLowerCase(), observedAt }, "ios_dhcp_interface")
+        : unknownEvidence("provider_identity_not_recorded");
+    return { address, uuid, mac };
+}
+function projectRequestAnnotation(value) {
+    if (typeof value !== "string" || value.length > 2048)
+        return undefined;
+    try {
+        const request = JSON.parse(value);
+        if (!request || request.schema !== CUBE_REVALIDATION_REQUEST_SCHEMA
+            || typeof request.requestId !== "string" || !UUID_PATTERN.test(request.requestId)
+            || typeof request.claimUid !== "string" || !UUID_PATTERN.test(request.claimUid)
+            || !Number.isSafeInteger(request.generation) || request.generation < 1
+            || typeof request.operationId !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(request.operationId)
+            || typeof request.intentDigest !== "string" || !/^sha256:[a-f0-9]{64}$/.test(request.intentDigest)
+            || typeof request.requestedAt !== "string" || !z.string().datetime({ offset: false }).safeParse(request.requestedAt).success
+            || typeof request.requestExpiresAt !== "string" || !z.string().datetime({ offset: false }).safeParse(request.requestExpiresAt).success
+            || Object.keys(request).some((key) => !["schema", "requestId", "claimUid", "generation", "operationId", "intentDigest", "requestedAt", "requestExpiresAt"].includes(key))) {
+            return undefined;
+        }
+        return request;
+    }
+    catch {
+        return undefined;
+    }
+}
+function projectInspectionNetworkResult(claim, workflow, custody, expiry, historical, expectedRequestId, trustedNow) {
+    const status = safeRecord(claim.status);
+    const rawWorkflow = safeRecord(status?.cubeWorkflow);
+    const rawStatus = safeRecord(rawWorkflow?.networkRevalidation)
+        ?? safeRecord(safeRecord(rawWorkflow?.summary)?.networkRevalidation);
+    const workflowValue = workflow.state === "verified" ? workflow.value : undefined;
+    const operationId = workflowValue?.operationId;
+    const intentDigest = workflowValue?.intentDigest;
+    const uid = claim.metadata.uid;
+    const generation = claim.metadata.generation;
+    if (!expectedRequestId && !rawStatus)
+        return undefined;
+    if (!uid || !UUID_PATTERN.test(uid) || !Number.isSafeInteger(generation) || !operationId || !intentDigest) {
+        if (rawStatus)
+            throw new InspectionConflictError("INSPECTION_CONFLICT");
+        return undefined;
+    }
+    const requestId = expectedRequestId ?? (typeof rawStatus?.requestId === "string" ? rawStatus.requestId : undefined);
+    if (!requestId)
+        return undefined;
+    const requestBase = {
+        schema: "ct.appliance.cube-network-revalidation/v1",
+        requestId,
+        claimUid: uid,
+        generation,
+        operationId,
+        intentDigest,
+    };
+    if (rawStatus && rawStatus.requestId === requestId) {
+        const annotations = claim.metadata.annotations ?? {};
+        const requestAnnotation = projectRequestAnnotation(annotations[CUBE_REVALIDATION_REQUEST_ANNOTATION]);
+        if (requestAnnotation?.requestId === requestId
+            && (requestAnnotation.requestedAt !== rawStatus.requestedAt
+                || requestAnnotation.requestExpiresAt !== rawStatus.requestExpiresAt)) {
+            throw new InspectionConflictError("INSPECTION_CONFLICT");
+        }
+        const host = custody.evidence.state === "verified" ? custody.evidence.value.guest : undefined;
+        const expectedGuestUuid = custody.record?.provider?.uuid
+            ?? (historical.uuid.state === "verified" ? historical.uuid.value.value : undefined);
+        const expectedMac = historical.mac.state === "verified" ? historical.mac.value.value : undefined;
+        const expectedExpiry = expiry.state === "verified" && expiry.value ? expiry.value : undefined;
+        const receipt = projectNetworkRevalidation(rawStatus, {
+            ...requestBase,
+            ...(expectedExpiry ? { claimExpiresAt: expectedExpiry } : {}),
+            ...(host ? { host } : {}),
+            ...(expectedGuestUuid ? { guestUuid: expectedGuestUuid } : {}),
+            ...(expectedMac ? { mac: expectedMac } : {}),
+        }, trustedNow);
+        if (receipt.status === "verified" && expiry.state !== "verified") {
+            return { ...requestBase, status: "unknown", reasonCode: "claim_expiry_unavailable" };
+        }
+        return receipt;
+    }
+    const annotations = claim.metadata.annotations ?? {};
+    const requestAnnotation = projectRequestAnnotation(annotations[CUBE_REVALIDATION_REQUEST_ANNOTATION]);
+    if (requestAnnotation?.requestId === requestId
+        && requestAnnotation.claimUid === uid
+        && requestAnnotation.generation === generation
+        && requestAnnotation.operationId === operationId
+        && requestAnnotation.intentDigest === intentDigest) {
+        const expectedExpiry = expiry.state === "verified" && expiry.value ? expiry.value : undefined;
+        if (!expectedExpiry) {
+            return {
+                ...requestBase,
+                status: "unknown",
+                requestedAt: requestAnnotation.requestedAt,
+                requestExpiresAt: requestAnnotation.requestExpiresAt,
+                reasonCode: "claim_expiry_unavailable",
+            };
+        }
+        return projectNetworkRevalidation({
+            ...requestAnnotation,
+            schema: "ct.appliance.cube-network-revalidation/v1",
+            state: "pending",
+        }, {
+            ...requestBase,
+            claimExpiresAt: expectedExpiry,
+        }, trustedNow);
+    }
+    return { ...requestBase, status: "unknown", reasonCode: "revalidation_result_not_available" };
+}
+function buildClaimInspection(claim, input, retrievedAt, backendObservedAt, context, operation = "get_appliance_claim") {
+    const metadata = safeRecord(claim.metadata) ?? {};
+    const spec = safeRecord(claim.spec) ?? {};
+    const status = safeRecord(claim.status) ?? {};
+    const uid = typeof metadata.uid === "string" && UUID_PATTERN.test(metadata.uid) ? metadata.uid : undefined;
+    const generation = Number.isSafeInteger(metadata.generation) && metadata.generation >= 0 ? metadata.generation : undefined;
+    if (input.expectedUid && uid !== input.expectedUid)
+        throw new InspectionConflictError("INSPECTION_CONFLICT");
+    if (input.expectedGeneration !== undefined && generation !== input.expectedGeneration)
+        throw new InspectionConflictError("INSPECTION_CONFLICT");
+    if (metadata.name !== input.name || metadata.namespace !== input.namespace)
+        throw new InspectionConflictError("INSPECTION_CONFLICT");
+    const custody = claimCustodyProjection(claim);
+    const desiredHost = desiredHostTuple(claim, custody.record?.guest);
+    const expiry = claimExpiry(claim);
+    const rawWorkflow = status.cubeWorkflow;
+    const statusGenerationCurrent = generation !== undefined
+        && Number.isSafeInteger(status.observedGeneration)
+        && status.observedGeneration === generation;
+    const workflow = workflowBindsClaimGeneration(rawWorkflow, uid, generation)
+        ? projectOperatorWorkflow(rawWorkflow, statusGenerationCurrent)
+        : unknownEvidence("workflow_generation_unverified");
+    const statusFactsCurrent = statusGenerationCurrent && workflow.state === "verified";
+    const staleStatusReason = statusGenerationCurrent ? "workflow_generation_unverified" : "claim_status_generation_stale";
+    const diagnostic = statusGenerationCurrent
+        ? projectLifecycleDiagnostic(status.diagnostic, {
+            uid: uid ?? "00000000-0000-4000-8000-000000000000",
+            generation: generation ?? -1,
+        })
+        : unknownEvidence("claim_status_generation_stale");
+    if (workflow.state === "verified" && diagnostic.state === "verified") {
+        const current = workflow.value;
+        const report = diagnostic.value;
+        if (current.phase !== report.phase || current.retryClass !== report.retryClass
+            || current.effectCertainty !== report.effectCertainty || current.nextAction !== report.nextAction
+            || current.resumable !== report.resumable || current.retryAt !== report.retryAt) {
+            throw new InspectionConflictError("INSPECTION_CONFLICT");
+        }
+    }
+    const historical = projectBootstrapAddress(statusGenerationCurrent ? status : undefined);
+    const rawRevalidation = safeRecord(safeRecord(rawWorkflow)?.networkRevalidation)
+        ?? safeRecord(safeRecord(safeRecord(rawWorkflow)?.summary)?.networkRevalidation);
+    const selectedRequestId = input.expectedRequestId
+        ?? (typeof rawRevalidation?.requestId === "string" ? rawRevalidation.requestId : undefined);
+    const validationAt = new Date().toISOString();
+    const networkRevalidation = statusFactsCurrent
+        ? projectInspectionNetworkResult(claim, workflow, custody, expiry, historical, selectedRequestId, validationAt)
+        : selectedRequestId && workflow.state === "verified" && uid && generation !== undefined
+            ? {
+                schema: "ct.appliance.cube-network-revalidation/v1",
+                status: "unknown",
+                requestId: selectedRequestId,
+                claimUid: uid,
+                generation,
+                operationId: workflow.value.operationId,
+                intentDigest: workflow.value.intentDigest,
+                reasonCode: staleStatusReason,
+            }
+            : undefined;
+    const networkReadiness = !statusGenerationCurrent
+        ? unknownEvidence("claim_status_generation_stale")
+        : workflow.state !== "verified" && safeRecord(rawWorkflow)
+            ? unknownEvidence("workflow_generation_unverified")
+            : projectCurrentNetworkReadiness(networkRevalidation, validationAt);
+    const currentAddress = networkRevalidation?.status === "verified"
+        ? verifiedEvidence({ value: networkRevalidation.address, source: networkRevalidation.source, observedAt: networkRevalidation.observedAt, validUntil: networkRevalidation.validUntil }, "operator_cube_revalidation")
+        : historical.address;
+    const currentUuid = networkRevalidation?.status === "verified"
+        ? verifiedEvidence({ value: networkRevalidation.guestUuid, observedAt: networkRevalidation.observedAt, validUntil: networkRevalidation.validUntil }, "operator_cube_revalidation")
+        : historical.uuid;
+    const currentMac = networkRevalidation?.status === "verified"
+        ? verifiedEvidence({ value: networkRevalidation.mac.toLowerCase(), observedAt: networkRevalidation.observedAt, validUntil: networkRevalidation.validUntil }, "operator_cube_revalidation")
+        : historical.mac;
+    const accessPhaseTime = phaseTime(workflow, "ios_access");
+    const accessRaw = statusFactsCurrent
+        ? safeRecord(rawWorkflow)?.summary?.accessObserved ?? safeRecord(rawWorkflow)?.accessObserved
+        : undefined;
+    const accessObserved = projectAccessObserved(accessRaw, accessPhaseTime);
+    const cube = safeRecord(spec.cube);
+    const desiredAccess = cube
+        ? verifiedEvidence({
+            credentialSchema: "ct-appliance-cube-credentials/v1",
+            ...(cube.role === "admin" || cube.role === "full_admin" ? { role: cube.role } : {}),
+            capabilities: ["resolved", "authenticated", "privileged"],
+        }, "claim_spec")
+        : unknownEvidence("access_requirement_not_projected");
+    const claimStatusPhase = typeof status.phase === "string" ? status.phase : undefined;
+    const readyResultTime = phaseTime(workflow, "ready");
+    const claimReadiness = statusFactsCurrent && readyResultTime && claimStatusPhase === "Ready"
+        ? verifiedEvidence({ value: { state: "ready" }, observedAt: readyResultTime }, "operator_workflow_status")
+        : unknownEvidence(statusFactsCurrent ? "claim_readiness_source_unavailable" : staleStatusReason);
+    const providerReadiness = statusFactsCurrent
+        ? phaseReadiness(workflow, "clone_bind")
+        : unknownEvidence(staleStatusReason);
+    const guestReadiness = statusFactsCurrent && currentUuid.state === "verified" && currentMac.state === "verified"
+        ? verifiedEvidence({ value: { state: "ready" }, observedAt: currentUuid.value.observedAt, ...(currentUuid.value.validUntil ? { validUntil: currentUuid.value.validUntil } : {}) }, currentUuid.source)
+        : unknownEvidence(statusFactsCurrent ? "guest_identity_unverified" : staleStatusReason);
+    const sshReadiness = statusFactsCurrent && networkRevalidation?.status === "verified" && networkRevalidation.ssh.state === "verified"
+        ? verifiedEvidence({ value: { state: "ready" }, observedAt: networkRevalidation.ssh.observedAt, validUntil: networkRevalidation.ssh.validUntil }, "same_guest_ssh")
+        : unknownEvidence(statusFactsCurrent ? "read_only_revalidation_required" : staleStatusReason);
+    const configTimes = [phaseTime(workflow, "running_config"), phaseTime(workflow, "startup_config")].filter((value) => Boolean(value));
+    const configurationReadiness = statusFactsCurrent && configTimes.length === 2
+        ? verifiedEvidence({ value: { state: "ready" }, observedAt: configTimes.sort().at(-1) }, "operator_workflow_status")
+        : unknownEvidence(statusFactsCurrent ? "configuration_readback_unavailable" : staleStatusReason);
+    const applicationNotRequired = spec.profile === "cube";
+    const applicationReadiness = applicationNotRequired
+        ? verifiedEvidence({ value: { state: "not_required" }, observedAt: readyResultTime ?? validDate(status.diagnostic?.observedAt) ?? retrievedAt }, "claim_profile")
+        : unknownEvidence("application_readiness_not_projected");
+    const backend = (() => {
+        try {
+            const selected = resolveLabKubernetesBackend();
+            const provenance = buildProvenance({
+                plane: context?.plane,
+                credentials: context?.credentials,
+                mockPermitted: context?.mockPermitted,
+            });
+            return verifiedEvidence({
+                kind: "kubernetes_claims",
+                mode: selected.mode,
+                contextFingerprint: inspectionDigest(selected.context),
+                serverFingerprint: inspectionDigest(selected.server),
+                plane: provenance.plane,
+                runtimeVersion: provenance.runtimeVersion,
+                mock: provenance.mock,
+            }, "configured_claim_backend");
+        }
+        catch {
+            return unknownEvidence("backend_identity_unavailable");
+        }
+    })();
+    const diagnosticEvidence = diagnostic;
+    const reason = diagnostic.state === "verified"
+        ? verifiedEvidence({ code: diagnostic.value.code, classification: diagnostic.value.classification, evidenceRefs: diagnostic.value.evidenceRefs }, "operator_lifecycle_diagnostic")
+        : unknownEvidence("diagnostic_not_recorded");
+    const phaseValue = workflow.state === "verified" ? workflow.value : undefined;
+    const effectCertainty = phaseValue
+        ? verifiedEvidence(phaseValue.effectCertainty, "operator_workflow_status")
+        : diagnostic.state === "verified" ? verifiedEvidence(diagnostic.value.effectCertainty, "operator_lifecycle_diagnostic") : verifiedEvidence("none", "read_only_inspection");
+    const retryClass = phaseValue
+        ? verifiedEvidence(phaseValue.retryClass, "operator_workflow_status")
+        : diagnostic.state === "verified" ? verifiedEvidence(diagnostic.value.retryClass, "operator_lifecycle_diagnostic") : verifiedEvidence("never", "read_only_inspection");
+    const nextAction = phaseValue
+        ? verifiedEvidence(phaseValue.nextAction, "operator_workflow_status")
+        : diagnostic.state === "verified" ? verifiedEvidence(diagnostic.value.nextAction, "operator_lifecycle_diagnostic") : verifiedEvidence("none", "read_only_inspection");
+    const hostObserved = networkRevalidation?.status === "verified"
+        ? verifiedEvidence({ value: networkRevalidation.host, observedAt: networkRevalidation.observedAt, validUntil: networkRevalidation.validUntil }, "operator_cube_revalidation")
+        : unknownEvidence("provider_host_readback_unavailable");
+    const guestUuidDesired = custody.record?.provider?.uuid && UUID_PATTERN.test(custody.record.provider.uuid)
+        ? verifiedEvidence(custody.record.provider.uuid, "claim_custody_provider_binding")
+        : unknownEvidence("provider_identity_not_recorded");
+    return buildLabInspectionEnvelope({
+        schema: "ct-lab-inspection/v1",
+        operation: { name: operation, intent: operation === "get_appliance_claim" ? "inspect_claim" : "revalidate_network" },
+        backend: {
+            identity: backend,
+            observedAt: backendObservedAt ? verifiedEvidence(backendObservedAt, "kubernetes_http_date") : unknownEvidence("source_observation_time_unavailable"),
+            retrievedAt: verifiedEvidence(retrievedAt, "adapter_read_boundary"),
+        },
+        claim: {
+            name: typeof metadata.name === "string" ? verifiedEvidence(metadata.name, "claim_metadata") : unknownEvidence("claim_name_unavailable"),
+            assetId: typeof spec.vmName === "string" && spec.vmName.length > 0 ? verifiedEvidence(spec.vmName, "claim_spec") : unknownEvidence("claim_asset_id_unavailable"),
+            uid: uid ? verifiedEvidence(uid, "claim_metadata") : unknownEvidence("claim_uid_unavailable"),
+            generation: generation !== undefined ? verifiedEvidence(generation, "claim_metadata") : unknownEvidence("claim_generation_unavailable"),
+            observedGeneration: Number.isSafeInteger(status.observedGeneration) ? verifiedEvidence(status.observedGeneration, "operator_claim_status") : unknownEvidence("claim_observed_generation_unavailable"),
+            resourceVersion: typeof metadata.resourceVersion === "string" && metadata.resourceVersion.length > 0 ? verifiedEvidence(metadata.resourceVersion, "claim_metadata") : unknownEvidence("claim_resource_version_unavailable"),
+            expiresAt: expiry,
+            custody: custody.evidence,
+        },
+        host: { canonical: {
+                desired: desiredHost ? verifiedEvidence(desiredHost, "claim_spec_and_custody") : unknownEvidence("canonical_host_not_bound"),
+                observed: hostObserved,
+            } },
+        guest: {
+            uuid: { desired: guestUuidDesired, observed: currentUuid },
+            mac: { desired: unknownEvidence("guest_mac_not_in_claim_spec"), observed: currentMac },
+        },
+        address: {
+            desired: typeof spec.targetIp === "string" && isIP(spec.targetIp) === 4
+                ? verifiedEvidence({ value: spec.targetIp, source: "claim_spec" }, "claim_spec")
+                : unknownEvidence("dynamic_address_not_known_before_boot"),
+            observed: currentAddress,
+        },
+        access: { desired: desiredAccess, observed: accessObserved },
+        readiness: {
+            claim: readinessDimension(claimReadiness),
+            provider: readinessDimension(providerReadiness),
+            guestIdentity: readinessDimension(guestReadiness),
+            network: readinessDimension(networkReadiness),
+            ssh: readinessDimension(sshReadiness),
+            configuration: readinessDimension(configurationReadiness),
+            application: readinessDimension(applicationReadiness, applicationNotRequired ? "not_required" : "ready"),
+        },
+        ...(networkRevalidation ? { networkRevalidation } : {}),
+        runtimeArtifact: readInstalledRuntimeArtifact(),
+        workflow,
+        diagnostic: diagnosticEvidence,
+        reason,
+        effectCertainty,
+        retryClass,
+        nextAction,
+    });
+}
 export async function handleGetApplianceClaim(args, context) {
     const parsed = GetApplianceClaimInputSchema.safeParse(args);
     if (!parsed.success) {
@@ -351,25 +931,52 @@ export async function handleGetApplianceClaim(args, context) {
         return createToolErrorResult(ProxmoxErrorCode.VALIDATION_ERROR, issues);
     }
     const forwarded = await forwardClaim("get_appliance_claim", parsed.data, context);
-    if (forwarded)
-        return forwarded;
+    if (forwarded) {
+        if (forwarded.isError)
+            return forwarded;
+        const structured = safeRecord(forwarded.structuredContent);
+        const claim = safeRecord(structured?.claim);
+        if (!claim?.metadata)
+            return forwarded;
+        try {
+            const inspection = buildClaimInspection(claim, parsed.data, new Date().toISOString(), undefined, context);
+            const body = { ...(structured ?? {}), inspection };
+            return { ...forwarded, content: [{ type: "text", text: JSON.stringify(body, null, 2) }], structuredContent: body };
+        }
+        catch (error) {
+            if (error instanceof InspectionConflictError) {
+                return createToolErrorResult("INSPECTION_CONFLICT", "Forwarded live claim identity or lifecycle sources disagree; inspect the current claim before continuing.", {
+                    operation: "get_appliance_claim",
+                    name: parsed.data.name,
+                });
+            }
+            return createToolErrorResult("INSPECTION_CONTRACT_INVALID", "The forwarded claim did not meet the redacted inspection contract.", {
+                operation: "get_appliance_claim",
+                name: parsed.data.name,
+            });
+        }
+    }
     const { name, namespace } = parsed.data;
     try {
         const apiPath = `/apis/calltelemetry.com/v1alpha1/namespaces/${namespace}/applianceclaims/${name}`;
-        const apiRes = await queryKubernetesApi(apiPath);
+        const apiObservation = await queryKubernetesApiWithObservation(apiPath);
+        const apiRes = apiObservation?.data;
         const claim = apiRes?.metadata
             ? apiRes
             : JSON.parse((await runLabKubectl(["get", "applianceclaim", name, "-n", namespace, "-o", "json"])).stdout);
+        const retrievedAt = new Date().toISOString();
+        if (!claim?.metadata)
+            throw new Error("claim read did not return the requested resource");
+        const inspection = buildClaimInspection(claim, parsed.data, retrievedAt, apiObservation?.observedAt, context);
+        const body = { success: true, claim, inspection };
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify({
-                        success: true,
-                        claim
-                    }, null, 2)
+                    text: JSON.stringify(body, null, 2)
                 }
-            ]
+            ],
+            structuredContent: body,
         };
     }
     catch (err) {
@@ -378,7 +985,194 @@ export async function handleGetApplianceClaim(args, context) {
             if (cfg)
                 return cfg;
         }
-        return createToolErrorResult(ProxmoxErrorCode.VALIDATION_ERROR, `ApplianceClaim '${name}' not found in namespace '${namespace}': ${err.message}`);
+        if (err instanceof InspectionConflictError) {
+            return createToolErrorResult("INSPECTION_CONFLICT", "Live claim identity or lifecycle sources disagree; inspect the current claim before continuing.", {
+                operation: "get_appliance_claim",
+                name,
+            });
+        }
+        return createToolErrorResult(ProxmoxErrorCode.VALIDATION_ERROR, `ApplianceClaim '${name}' not found in namespace '${namespace}'.`);
+    }
+}
+function rejectedRevalidationResult(input, live, reasonCode) {
+    const workflow = safeRecord(live?.status?.cubeWorkflow);
+    const summary = safeRecord(workflow?.summary);
+    const actualOperationId = typeof summary?.operationId === "string" && /^[A-Za-z0-9._:-]{1,128}$/.test(summary.operationId)
+        ? summary.operationId : input.operationId;
+    const actualIntentDigest = typeof summary?.intentDigest === "string" && /^sha256:[a-f0-9]{64}$/.test(summary.intentDigest)
+        ? summary.intentDigest : input.intentDigest;
+    const identity = {
+        schema: "ct.appliance.cube-network-revalidation/v1",
+        status: "rejected",
+        requestId: input.requestId,
+        claimUid: typeof live?.metadata?.uid === "string" && UUID_PATTERN.test(live.metadata.uid)
+            ? live.metadata.uid : input.expectedUid,
+        generation: Number.isSafeInteger(live?.metadata?.generation) && live.metadata.generation > 0
+            ? live.metadata.generation : input.expectedGeneration,
+        operationId: actualOperationId,
+        intentDigest: actualIntentDigest,
+        reasonCode,
+    };
+    const result = createToolErrorResult("INSPECTION_CONFLICT", "The read-only network revalidation request was refused by the live claim preconditions.", {
+        operation: "revalidate_appliance_claim_network",
+        reasonCode,
+    });
+    const structured = result.structuredContent;
+    return {
+        ...result,
+        structuredContent: { ...(structured ?? {}), networkRevalidation: identity },
+    };
+}
+async function readLiveClaim(name, namespace) {
+    const path = `/apis/calltelemetry.com/v1alpha1/namespaces/${encodeURIComponent(namespace)}/applianceclaims/${encodeURIComponent(name)}`;
+    const apiObservation = await queryKubernetesApiWithObservation(path);
+    if (safeRecord(apiObservation?.data)?.metadata)
+        return { claim: apiObservation.data, observedAt: apiObservation?.observedAt };
+    const { stdout } = await runLabKubectl(["get", "applianceclaim", name, "-n", namespace, "-o", "json"]);
+    const claim = JSON.parse(stdout);
+    if (!safeRecord(claim)?.metadata)
+        throw new Error("claim read did not return the requested resource");
+    return { claim };
+}
+export async function handleRevalidateApplianceClaimNetwork(args, context) {
+    const parsed = RevalidateApplianceClaimNetworkInputSchema.safeParse(args);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ");
+        return createToolErrorResult(ProxmoxErrorCode.VALIDATION_ERROR, issues);
+    }
+    const input = parsed.data;
+    const forwarded = await forwardClaim("revalidate_appliance_claim_network", input, context);
+    if (forwarded)
+        return forwarded;
+    let lastLiveClaim;
+    try {
+        let { claim, observedAt } = await readLiveClaim(input.name, input.namespace);
+        lastLiveClaim = claim;
+        const meta = safeRecord(claim.metadata) ?? {};
+        const status = safeRecord(claim.status) ?? {};
+        const workflow = safeRecord(status.cubeWorkflow);
+        const summary = safeRecord(workflow?.summary);
+        const initialRefusal = activeCubeClaimRefusal(claim, input);
+        if (initialRefusal)
+            return rejectedRevalidationResult(input, claim, initialRefusal);
+        const expiry = claimExpiry(claim);
+        if (expiry.state !== "verified" || !expiry.value)
+            return rejectedRevalidationResult(input, claim, "claim_inactive");
+        const annotations = safeRecord(meta.annotations) ?? {};
+        const existingStatus = safeRecord(workflow?.networkRevalidation)
+            ?? safeRecord(summary?.networkRevalidation);
+        const existingRequest = projectRequestAnnotation(annotations[CUBE_REVALIDATION_REQUEST_ANNOTATION]);
+        const existingRequestExpired = existingRequest !== undefined
+            && Date.parse(String(existingRequest.requestExpiresAt)) <= Date.now();
+        const identityMatches = (record) => record
+            && record.requestId === input.requestId
+            && record.claimUid === input.expectedUid
+            && record.generation === input.expectedGeneration
+            && record.operationId === input.operationId
+            && record.intentDigest === input.intentDigest;
+        if (existingStatus?.requestId === input.requestId && !identityMatches(existingStatus)) {
+            return rejectedRevalidationResult(input, claim, "request_id_identity_conflict");
+        }
+        if (existingRequest && existingRequest.requestId !== input.requestId && !existingRequestExpired) {
+            return rejectedRevalidationResult(input, claim, "another_revalidation_request_is_active");
+        }
+        if (existingRequest?.requestId === input.requestId && !identityMatches(existingRequest)) {
+            return rejectedRevalidationResult(input, claim, "request_id_identity_conflict");
+        }
+        let selectedClaim = claim;
+        if ((!existingStatus || existingStatus.requestId !== input.requestId)
+            && (!existingRequest || (existingRequest.requestId !== input.requestId && existingRequestExpired))) {
+            const requestedAtMs = Date.now();
+            const requestExpiresAtMs = Math.min(requestedAtMs + NETWORK_REVALIDATION_REQUEST_TTL_MS, Date.parse(expiry.value));
+            if (requestExpiresAtMs <= requestedAtMs)
+                return rejectedRevalidationResult(input, claim, "claim_inactive");
+            const requestValue = {
+                schema: CUBE_REVALIDATION_REQUEST_SCHEMA,
+                requestId: input.requestId,
+                claimUid: input.expectedUid,
+                generation: input.expectedGeneration,
+                operationId: input.operationId,
+                intentDigest: input.intentDigest,
+                requestedAt: new Date(requestedAtMs).toISOString(),
+                requestExpiresAt: new Date(requestExpiresAtMs).toISOString(),
+            };
+            const annotationPath = `/metadata/annotations/${CUBE_REVALIDATION_REQUEST_ANNOTATION.replace(/~/g, "~0").replace(/\//g, "~1")}`;
+            const patch = [
+                { op: "test", path: "/metadata/uid", value: input.expectedUid },
+                { op: "test", path: "/metadata/generation", value: input.expectedGeneration },
+                { op: "test", path: "/metadata/resourceVersion", value: meta.resourceVersion },
+                { op: "test", path: `/metadata/annotations/${CUSTODY_ANNOTATION.replace(/~/g, "~0").replace(/\//g, "~1")}`, value: annotations[CUSTODY_ANNOTATION] },
+                { op: "add", path: annotationPath, value: JSON.stringify(requestValue) },
+            ];
+            const apiPath = `/apis/calltelemetry.com/v1alpha1/namespaces/${encodeURIComponent(input.namespace)}/applianceclaims/${encodeURIComponent(input.name)}`;
+            const patchObservation = await queryKubernetesApiWithObservation(apiPath, {
+                method: "PATCH",
+                body: patch,
+                contentType: "application/json-patch+json",
+                timeoutMs: 10_000,
+            });
+            if (safeRecord(patchObservation?.data)?.metadata) {
+                selectedClaim = patchObservation.data;
+                lastLiveClaim = selectedClaim;
+                observedAt = patchObservation?.observedAt ?? observedAt;
+            }
+            else {
+                const { stdout } = await runLabKubectl([
+                    "patch", "applianceclaim", input.name, "-n", input.namespace,
+                    "--type=json", "--patch", JSON.stringify(patch), "-o", "json",
+                ], { timeoutMs: 10_000 });
+                selectedClaim = JSON.parse(stdout);
+                lastLiveClaim = selectedClaim;
+            }
+        }
+        const selectedMeta = safeRecord(selectedClaim.metadata) ?? {};
+        if (selectedMeta.uid !== input.expectedUid || selectedMeta.generation !== input.expectedGeneration) {
+            return rejectedRevalidationResult(input, selectedClaim, "claim_identity_conflict");
+        }
+        const selectedReceipt = safeRecord(selectedClaim.status?.cubeWorkflow?.networkRevalidation)
+            ?? safeRecord(selectedClaim.status?.cubeWorkflow?.summary?.networkRevalidation);
+        const selectedRequest = projectRequestAnnotation(safeRecord(selectedMeta.annotations)?.[CUBE_REVALIDATION_REQUEST_ANNOTATION]);
+        if (!identityMatches(selectedReceipt) && !identityMatches(selectedRequest)) {
+            return rejectedRevalidationResult(input, selectedClaim, "request_annotation_not_persisted");
+        }
+        if (!claimHasFinalRevalidation(selectedClaim, input.requestId, input.expectedUid, input.expectedGeneration)) {
+            const watched = await watchClaimRevalidation(input.namespace, input.name, typeof selectedMeta.resourceVersion === "string" ? selectedMeta.resourceVersion : String(meta.resourceVersion ?? ""), input.requestId, input.expectedUid, input.expectedGeneration);
+            if (watched) {
+                if (watched.deleted)
+                    return rejectedRevalidationResult(input, watched.claim, "claim_deleted");
+                selectedClaim = watched.claim;
+                lastLiveClaim = selectedClaim;
+                observedAt = watched.observedAt ?? observedAt;
+            }
+        }
+        else if (selectedReceipt?.requestId !== input.requestId) {
+            return rejectedRevalidationResult(input, selectedClaim, "request_id_identity_conflict");
+        }
+        const finalRefusal = activeCubeClaimRefusal(selectedClaim, input);
+        if (finalRefusal)
+            return rejectedRevalidationResult(input, selectedClaim, finalRefusal);
+        const retrievedAt = new Date().toISOString();
+        const inspection = buildClaimInspection(selectedClaim, { name: input.name, namespace: input.namespace, expectedUid: input.expectedUid, expectedGeneration: input.expectedGeneration, expectedRequestId: input.requestId }, retrievedAt, observedAt, context, "revalidate_appliance_claim_network");
+        const body = { success: true, claim: selectedClaim, inspection };
+        return {
+            content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+            structuredContent: body,
+        };
+    }
+    catch (error) {
+        const config = claimBackendConfigErrorResult(error, "revalidate_appliance_claim_network");
+        if (config)
+            return config;
+        if (error instanceof InspectionConflictError) {
+            return rejectedRevalidationResult(input, lastLiveClaim, "inspection_conflict");
+        }
+        if (error instanceof Error && /Kubernetes API request failed \(409\)/u.test(error.message)) {
+            return rejectedRevalidationResult(input, lastLiveClaim, "claim_resource_version_conflict");
+        }
+        return createToolErrorResult("NETWORK_REVALIDATION_REQUEST_FAILED", "The read-only network revalidation request could not be recorded.", {
+            operation: "revalidate_appliance_claim_network",
+            requestId: input.requestId,
+        });
     }
 }
 /**